github/lodestar
1
1
Fork 0
mirror of https://github.com/ChainSafe/lodestar.git synced 2026-01-08 23:28:10 -05:00
Code Issues Packages Projects Releases Wiki Activity

ci: check docs spelling (#5527)

Browse Source 
* Check docs spelling

* Add config

* Fix docs spelling

* Lint docs format

* docs(flamegraph): remove note about script that was removed

* sort wordlist

* Set sort algo

* Fix CI pipeline

* hope to fix CI ordering

* Disable wordlist sort check

* docs(CONTRIBUTING): remove merge conflict marker and add codeblock types

* refactor: change to pyspelling.yml for local runs

* docs: make spell-checking wordlist case insensitive

* fix: sort .wordlist.txt

* refactor: alphabetize script order

* fix: add docs/reference to gitignore

* docs: add codeblocks to pyspelling ignore and clear all errors

* docs: ignore possessive endings in spellcheck

* docs: clear spelling errors in package readmes

* docs: pyspelling fix generated cli.md

* feat(workflows): lint generated docs

* feat(workflows): add word sort to docs-check

* test: unsort wordlist

* fix: sort wordlist

* refactor(workflow): remove unused comments

---------

Co-authored-by: matthewkeil <me@matthewkeil.com>
Co-authored-by: Cayman <caymannava@gmail.com>
This commit is contained in:
Lion - dapplion
2023-06-21 20:24:27 +02:00
committed by GitHub
parent 2a2c517456
commit 9e57b7d320
47 changed files with 508 additions and 220 deletions
Download Patch File Download Diff File Expand all files Collapse all files

50
.github/workflows/docs-check.yml vendored Normal file
View File

@@ -0,0 +1,50 @@
name: Check docs
on:
push:
# We intentionally don't run push on feature branches. See PR for rational.
branches: [unstable, stable]
pull_request:
jobs:
build:
name: Docs spellcheck
runs-on: ubuntu-latest
steps:
# <common-build> - Uses YAML anchors in the future
- uses: actions/checkout@v3
- uses: actions/setup-node@v3
with:
node-version: 18
- name: Node.js version
id: node
run: echo "v8CppApiVersion=$(node --print "process.versions.modules")" >> $GITHUB_OUTPUT
- name: Restore dependencies
uses: actions/cache@master
id: cache-deps
with:
path: |
node_modules
packages/*/node_modules
key: ${{ runner.os }}-${{ steps.node.outputs.v8CppApiVersion }}-${{ hashFiles('**/yarn.lock', '**/package.json') }}
- name: Install & build
if: steps.cache-deps.outputs.cache-hit != 'true'
run: yarn install --frozen-lockfile && yarn build
- name: Build
run: yarn build
if: steps.cache-deps.outputs.cache-hit == 'true'
- name: Check wordlist is sorted
run: scripts/wordlist_sort_check.sh
- name: Build and collect docs
run: yarn build:docs
# Run prettier check with fix after generating the docs. The CLI reference is formatted with prettier for
# deployed version so this will fail if not "fixable"
- name: Check docs format
run: yarn lint-docs:fix
# Run spellcheck AFTER building docs, in case the CLI reference has issues
- name: Spellcheck
uses: rojopolis/spellcheck-github-actions@0.32.0

5
.github/workflows/docs.yml vendored
View File

@@ -36,12 +36,17 @@ jobs:
- name: Build and collect docs
run: yarn build:docs
- name: Lint built docs
run: yarn lint-docs:fix
- name: Set up Python
uses: actions/setup-python@v1
- name: Install dependencies
run: |
python -m pip install --upgrade pip
pip install -r docs/requirements.txt
- name: Build docs
run: mkdocs build --site-dir site -v --clean

7
.github/workflows/test.yml vendored
View File

@@ -67,13 +67,10 @@ jobs:
run: scripts/assert_eslintrc_sorted.mjs
- name: Check Types
run: yarn run check-types
# Test docs generation, even if not published
- name: Build docs
run: yarn build:docs
run: yarn check-types
- name: README check
run: yarn run check-readme
run: yarn check-readme
- name: Lint
run: yarn lint

7
.gitignore vendored
View File

@@ -40,10 +40,10 @@ packages/api/oapi-schemas
# Autogenerated docs
packages/**/docs
packages/**/typedocs
docs/packages
docs/contributing.md
docs/assets
docs/reference/cli.md
docs/packages
docs/reference
docs/contributing.md
/site
# Testnet artifacts
@@ -70,5 +70,6 @@ packages/cli/.git-data.json
# Build artifacts
.last_build_unixsec
dictionary.dic
temp/

4
.prettierignore
View File

@@ -1,3 +1,5 @@
**/lib
**/.nyc_output
/packages/*/spec-tests
/packages/*/spec-tests
node_modules
**/node_modules

42
.pyspelling.yml Normal file
View File

@@ -0,0 +1,42 @@
matrix:
- name: markdown
aspell:
lang: en
ignore-case: true
dictionary:
wordlists:
- .wordlist.txt
pipeline:
- pyspelling.filters.url:
- pyspelling.filters.markdown:
markdown_extensions:
- pymdownx.superfences:
- pymdownx.highlight:
- pymdownx.striphtml:
- pymdownx.magiclink:
- pyspelling.filters.url:
- pyspelling.filters.html:
comments: false
ignores:
- code
- pre
- pyspelling.filters.context:
context_visible_first: true
delimiters:
# Ignore possessive endings
- open: '(?<=\w)''s(?!\w)'
close: '\b'
# Ignore eth methods (e.g. eth_estimateGas)
- open: '(?:\s)eth_(?:\w*)'
close: '\s'
# Ignore flags in cli.md
- open: '--(?:\w*)'
close: '[^\w]'
# Ignore hex strings
- open: '0x[a-fA-F0-9]'
close: '[^a-fA-F0-9]'
sources:
- "docs/**/*.md"
- "CONTRIBUTING.md"
- "README.md"
- "packages/*/README.md"

130
.wordlist.txt Normal file
View File

@@ -0,0 +1,130 @@
APIs
AssemblyScript
BLS
BeaconNode
Besu
CLA
CLI
CTRL
Chai
ChainSafe
Customizations
Discv
DockerHub
Dockerized
EIP
EIPs
EL
ENR
ENRs
ESLint
ETH
Erigon
EthStaker
Ethereum
FX
Flamegraph
Flamegraphs
Github
Gossipsub
Grafana
HackMD
IPv
Infura
JSON
JWT
LGPL
LGPLv
LTS
Lerna
MEV
MacOS
Monorepo
NPM
NVM
Nethermind
NodeJS
NodeSource
PR
PRs
Plaintext
PoS
Quickstart
RPC
SHA
SSD
SSZ
Stakehouse
TOC
TTD
TypeScript
UI
UTF
VM
Vitalik
Wagyu
api
async
beaconcha
bootnode
bootnodes
chainConfig
chainsafe
cli
cmd
config
configs
const
constantish
cors
cryptographic
dApp
dApps
decrypt
deserialization
devnet
devnets
enum
envs
flamegraph
flamegraphs
goerli
interop
keypair
keystore
keystores
lightclient
linter
lockfile
mainnet
mdns
merkle
merkleization
monorepo
namespace
namespaced
namespaces
nodemodule
overriden
params
plaintext
prover
req
reqresp
runtime
sharding
ssz
stakers
subnets
tcp
testnet
testnets
todo
typesafe
udp
util
utils
validator
validators
wip
yaml

74
CONTRIBUTING.md
View File

@@ -25,6 +25,13 @@ To run tests:
- :test_tube: Run `yarn check-types` to check TypeScript types.
- :test_tube: Run `yarn lint` to run the linter (ESLint).
Contributing to tests:
- Test must not depend on external live resources, such that running tests for a commit must be deterministic:
- Do not pull data from external APIs like execution JSON RPC (instead run a local node).
- Do not pull unpinned versions from DockerHub (use deterministic tag) or Github (checkout commit not branch).
- Carefully design tests that depend on timing sensitive events like p2p network e2e tests. Consider that Github runners are significantly less powerful than your development environment.
### Debugging Spec Tests
- To fix errors always focus on passing all minimal tests first without running mainnet tests.
@@ -32,7 +39,7 @@ To run tests:
- A single logical error can cause many spec tests to fail. To focus on a single test at a time you can use mocha's option `--bail` to stop at the first failed test
- To then run only that failed test you can run against a specific file as use mocha's option `--grep` to run only one case
```
```sh
LODESTAR_PRESET=minimal ../../node_modules/.bin/mocha --config .mocharc.spec.yml test/spec/phase0/sanity.test.ts --inline-diffs --bail --grep "attestation"
```
@@ -40,29 +47,29 @@ LODESTAR_PRESET=minimal ../../node_modules/.bin/mocha --config .mocharc.spec.yml
The docker-compose file requires that a `.env` file be present in this directory. The `default.env` file provides a template and can be copied `.env`:
```
```sh
cp default.env .env
```
###### Beacon node only:
###### Beacon node only
```
```sh
docker-compose up -d
```
###### Beacon node and validator:
###### Beacon node and validator
First, you must have keystores and their secrets available locally at `./keystores` and your password.txt in `./secrets`
First, you must have keystores and their secrets available locally at `./keystores` and your `password.txt` in `./secrets`
```
```sh
docker-compose -f docker-compose.yml -f docker-compose.validator.yml up -d
```
###### Dockerized metrics + local beacon node:
###### Dockerized metrics + local beacon node
Run a local beacon with `--metrics` enabled. Then start Prometheus + Grafana with all dashboards in `./dashboards` automatically loaded running:
```
```sh
./docker/docker-compose.local_dev.sh
```
@@ -92,7 +99,7 @@ Unsure where to begin contributing to Lodestar? Here are some ideas!
**Branch Naming**
If you are contributing from this repo prefix the branch name with your Github username (i.e. `myusername/short-description`)
If you are contributing from this repository prefix the branch name with your Github username (i.e. `myusername/short-description`)
**Pull Request Naming**
@@ -118,7 +125,7 @@ For example:
## Lodestar Monorepo
We're currently experimenting with hosting the majority of lodestar packages and support packages in this repository as a [monorepo](https://en.wikipedia.org/wiki/Monorepo). We're using [Lerna](https://lerna.js.org/) to manage the packages. See [packages/](https://github.com/ChainSafe/lodestar/tree/unstable/packages) for a list of packages hosted in this repo.
We're currently experimenting with hosting the majority of lodestar packages and support packages in this repository as a [monorepo](https://en.wikipedia.org/wiki/Monorepo). We're using [Lerna](https://lerna.js.org/) to manage the packages. See [packages/](https://github.com/ChainSafe/lodestar/tree/unstable/packages) for a list of packages hosted in this repository.
## Style Guide
@@ -134,7 +141,7 @@ We're currently experimenting with hosting the majority of lodestar packages and
- Functions and variables should be [`camelCase`](https://en.wikipedia.org/wiki/Camel_case), classes should be [`PascalCase`](http://wiki.c2.com/?PascalCase), constants should be `UPPERCASE_WITH_UNDERSCORES`.
- Use `"` instead of `'`
- All functions should have types declared for all parameters and return value
- You shouldn't be using TypeScript's `any`
- You shouldn't be using TypeScript type `any`
- Private class properties should not be prefixed with a `_`
- e.g.: `private dirty;`, not `private _dirty;`
- Make sure that your code is properly type checked:
@@ -145,7 +152,7 @@ We're currently experimenting with hosting the majority of lodestar packages and
- Commenting: If your code does something that is not obvious or deviates from standards, leave a comment for other developers to explain your logic and reasoning.
- Use `//` commenting format unless it's a comment you want people to see in their IDE.
- Use `/** **/` commenting format for documenting a function/variable.
- Code whitespace can be helpful for reading complex code, please add some.
- Code white space can be helpful for reading complex code, please add some.
- For unit tests, we forbid import stubbing when other approaches are feasible.
## Tests style guide
@@ -187,7 +194,7 @@ Contributors must choose the log level carefully to ensure a consistent experien
To edit or extend an existing Grafana dashboard with minimal diff:
1. Grab the .json dashboard file from current unstable
1. Grab the `.json` dashboard file from current unstable
2. Import file to Grafana via the web UI at `/dashboard/import`. Give it some temporal name relevant to your work (i.e. the branch name)
3. Visually edit the dashboard
4. Once done make sure to leave the exact same visual aspect as before: same refresh interval, collapsed rows, etc.
@@ -215,7 +222,7 @@ node scripts/download_dashboards.mjs
Issues and pull requests are subject to the following labeling guidelines.
- PRs may have a status label to indicate deviation from the normal process such as `status-blocked` or `status-do-not-merge`
- Issues and PRs will be tagged with a `scope` and `prio` to indicate type and priority for triaging.
- Issues and PRs will be tagged with a `scope` and `prio` to indicate type and priority for triage.
- All other labels allow for further evaluation and organization.
Label descriptions can be found below.
@@ -224,55 +231,18 @@ Label descriptions can be found below.
Status labels apply to issues and pull requests which deviate from normal processes.
- `status-blocked`: This is blocked by another issue that requires resolving first.
- `status-do-not-merge`: Merging this issue will break the build. Do not merge!
###### `scope.*` Scope Indicator
Scope is comparable to Module labels but less strict with the definition of components. It applies to both, issues and pull requests.
- `scope-cpu-performance`: Performance issue and ideas to improve performance.
- `scope-documentation`: All issues related to the Lodestar documentation.
- `scope-interop`: Issues that fix interop issues between Lodestar and CL, EL or tooling.
- `scope-light-clients`: All issues regarding light client development.
- `scope-logging`: Issue about logs: hygiene, format issues, improvements.
- `scope-memory`: Issues to reduce and improve memory usage.
- `scope-metrics`: All issues with regards to the exposed metrics.
- `scope-networking`: All issues related to networking, gossip, and libp2p.
- `scope-profitability`: Issues to directly improve validator performance and its profitability.
- `scope-security`: Issues that fix security issues: DOS, key leak, CVEs.
- `scope-testing`: Issues for adding test coverage, fixing existing tests or testing strategies
- `scope-testnet-debugging`: Issues uncovered through running a node on a public testnet.
- `scope-ux`: Issues for CLI UX or general consumer UX.
###### `prio.*` Prioritization Indicator
A simple indicator of issue prioritization. It mainly applies to issues.
- `prio0-critical`: Drop everything to resolve this immediately.
- `prio1-high`: Resolve issues as soon as possible.
- `prio2-medium`: Resolve this some time soon (tm).
- `prio3-low`: This is nice to have.
###### `spec.*` Ethereum Consensus Spec Version Target
Issues that target a specific version of the Ethereum consensus spec, shall be tagged accordingly.
- `spec-phase0`: Issues targeting the initial Ethereum consensus spec version.
- `spec-altair`: Issues targeting the Altair Ethereum consensus spec version.
- `spec-bellatrix`: Issues targeting the Bellatrix Ethereum consensus spec version.
###### `meta.*` Meta Labels to organize Miscellaneous Issues
- `meta-breaking-change`: Introduces breaking changes to DB, Validator, Beacon Node, or CLI interfaces. Handle with care!
- `meta-dependencies`: Pull requests that update a dependency.
- `meta-discussion`: Indicates a topic that requires input from various developers.
- `meta-good-first-issue`: Good first issues for newcomers and first-time contributors.
- `meta-help-wanted`: The author indicates that additional help is wanted.
- `meta-pm`: Issues relating to Project Management tasks.
- `meta-stale`: Label for stale issues applied by the stale bot.
- `meta-technicaldebt`: Issues introducing or resolving technical debts.
## Community
Come chat with us on [Discord](https://discord.gg/aMxzVcr) and join our public weekly planning meetings!

32
README.md
View File

@@ -5,7 +5,7 @@
[![GitHub release (latest by date)](https://img.shields.io/github/v/release/chainsafe/lodestar?label=Github)](https://github.com/ChainSafe/lodestar/releases/latest)
[![npm](https://img.shields.io/npm/v/@chainsafe/lodestar)](https://www.npmjs.com/package/@chainsafe/lodestar)
[![Docker Image Version (latest by date)](https://img.shields.io/docker/v/chainsafe/lodestar?color=blue&label=Docker&sort=semver)](https://hub.docker.com/r/chainsafe/lodestar)
[![Eth Consensus Spec v1.1.10](https://img.shields.io/badge/ETH%20consensus--spec-1.1.10-blue)](https://github.com/ethereum/consensus-specs/releases/tag/v1.1.10)
[![Ethereum Consensus Spec v1.1.10](https://img.shields.io/badge/ETH%20consensus--spec-1.1.10-blue)](https://github.com/ethereum/consensus-specs/releases/tag/v1.1.10)
[![codecov](https://codecov.io/gh/ChainSafe/lodestar/branch/unstable/graph/badge.svg)](https://codecov.io/gh/ChainSafe/lodestar)
![ES Version](https://img.shields.io/badge/ES-2020-yellow)
![Node Version](https://img.shields.io/badge/node-18.x-green)
@@ -45,21 +45,21 @@ yarn build
- :package: This mono-repository contains a suite of Ethereum Consensus packages.
- :balance_scale: The mono-repository is released under [LGPLv3 license](./LICENSE). Note, that the packages contain their own licenses.
| Package | Version | License | Docs | Description |
| --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| [@lodestar/beacon-node](./packages/beacon-node) | [![npm](https://img.shields.io/npm/v/@chainsafe/lodestar)](https://www.npmjs.com/package/@chainsafe/lodestar) | [![License: LGPL v3](https://img.shields.io/badge/License-LGPL%20v3-blue.svg)](https://www.gnu.org/licenses/lgpl-3.0) | [![documentation](https://img.shields.io/badge/readme-blue)](./packages/beacon-node) | :rotating_light: Beacon-chain client |
| [@lodestar/validator](./packages/validator) | [![npm](https://img.shields.io/npm/v/@lodestar/validator)](https://www.npmjs.com/package/@lodestar/validator) | [![License: LGPL v3](https://img.shields.io/badge/License-LGPL%20v3-blue.svg)](https://www.gnu.org/licenses/lgpl-3.0) | [![documentation](https://img.shields.io/badge/readme-blue)](./packages/validator) | :bank: Validator client |
| [@lodestar/light-client](./packages/light-client) | [![npm](https://img.shields.io/npm/v/@lodestar/light-client)](https://www.npmjs.com/package/@lodestar/light-client) | [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) | [![documentation](https://img.shields.io/badge/readme-blue)](./packages/light-client) | :bird: Ethereum Light client |
| [@lodestar/api](./packages/api) | [![npm](https://img.shields.io/npm/v/@lodestar/api)](https://www.npmjs.com/package/@lodestar/api) | [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) | [![documentation](https://img.shields.io/badge/readme-blue)](./packages/api) | :clipboard: REST Client for the Eth Beacon API |
| [@chainsafe/lodestar](./packages/cli) | [![npm](https://img.shields.io/npm/v/@chainsafe/lodestar)](https://www.npmjs.com/package/@chainsafe/lodestar) | [![License: LGPL v3](https://img.shields.io/badge/License-LGPL%20v3-blue.svg)](https://www.gnu.org/licenses/lgpl-3.0) | [![documentation](https://img.shields.io/badge/readme-blue)](./packages/cli/) | :computer: Command-line tool for Lodestar |
| [@lodestar/state-transition](./packages/state-transition) | [![npm](https://img.shields.io/npm/v/@lodestar/state-transition)](https://www.npmjs.com/package/@lodestar/state-transition) | [![License: LGPL v3](https://img.shields.io/badge/License-LGPL%20v3-blue.svg)](https://www.gnu.org/licenses/lgpl-3.0) | [![documentation](https://img.shields.io/badge/readme-blue)](./packages/state-transition) | :mag_right: Eth Consensus beacon-state transition |
| [@lodestar/types](./packages/types) | [![npm](https://img.shields.io/npm/v/@lodestar/types)](https://www.npmjs.com/package/@lodestar/types) | [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) | [![documentation](https://img.shields.io/badge/readme-blue)](./packages/types) | :spiral_notepad: Eth Consensus TypeScript and SSZ types |
| [@lodestar/params](./packages/params) | [![npm](https://img.shields.io/npm/v/@lodestar/params)](https://www.npmjs.com/package/@lodestar/params) | [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) | [![documentation](https://img.shields.io/badge/readme-blue)](./packages/params) | :spider_web: Eth Consensus network parameters |
| [@lodestar/utils](./packages/utils) | [![npm](https://img.shields.io/npm/v/@lodestar/utils)](https://www.npmjs.com/package/@lodestar/utils) | [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) | [![documentation](https://img.shields.io/badge/readme-blue)](./packages/utils) | :toolbox: Miscellaneous utility functions used across Lodestar |
| [@lodestar/config](./packages/config) | [![npm](https://img.shields.io/npm/v/@lodestar/config)](https://www.npmjs.com/package/@lodestar/config) | [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) | [![documentation](https://img.shields.io/badge/readme-blue)](./packages/config) | :spiral_notepad: Eth Consensus types and params bundled together |
| [@lodestar/spec-test-util](./packages/spec-test-util) | [![npm](https://img.shields.io/npm/v/@lodestar/spec-test-util)](https://www.npmjs.com/package/@lodestar/spec-test-util) | [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) | [![documentation](https://img.shields.io/badge/readme-blue)](./packages/spec-test-util) | :test_tube: Test harness for Eth Consensus spec tests |
| [@lodestar/db](./packages/db) | [![npm](https://img.shields.io/npm/v/@lodestar/db)](https://www.npmjs.com/package/@lodestar/db) | [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) | [![documentation](https://img.shields.io/badge/readme-blue)](./packages/db) | :floppy_disk: Read/write persistent Eth Consensus data |
| [@lodestar/fork-choice](./packages/fork-choice) | [![npm](https://img.shields.io/npm/v/@lodestar/fork-choice)](https://www.npmjs.com/package/@lodestar/fork-choice) | [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) | [![documentation](https://img.shields.io/badge/readme-blue)](./packages/fork-choice) | :fork_and_knife: Beacon-chain fork choice |
| Package | Version | License | Docs | Description |
| ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| [`@lodestar/beacon-node`](./packages/beacon-node) | [![npm](https://img.shields.io/npm/v/@chainsafe/lodestar)](https://www.npmjs.com/package/@chainsafe/lodestar) | [![License: LGPL v3](https://img.shields.io/badge/License-LGPL%20v3-blue.svg)](https://www.gnu.org/licenses/lgpl-3.0) | [![documentation](https://img.shields.io/badge/readme-blue)](./packages/beacon-node) | :rotating_light: Beacon-chain client |
| [`@lodestar/validator`](./packages/validator) | [![npm](https://img.shields.io/npm/v/@lodestar/validator)](https://www.npmjs.com/package/@lodestar/validator) | [![License: LGPL v3](https://img.shields.io/badge/License-LGPL%20v3-blue.svg)](https://www.gnu.org/licenses/lgpl-3.0) | [![documentation](https://img.shields.io/badge/readme-blue)](./packages/validator) | :bank: Validator client |
| [`@lodestar/light-client`](./packages/light-client) | [![npm](https://img.shields.io/npm/v/@lodestar/light-client)](https://www.npmjs.com/package/@lodestar/light-client) | [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) | [![documentation](https://img.shields.io/badge/readme-blue)](./packages/light-client) | :bird: Ethereum Light client |
| [`@lodestar/api`](./packages/api) | [![npm](https://img.shields.io/npm/v/@lodestar/api)](https://www.npmjs.com/package/@lodestar/api) | [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) | [![documentation](https://img.shields.io/badge/readme-blue)](./packages/api) | :clipboard: REST Client for the Ethereum Beacon API |
| [@chainsafe/lodestar`](./packages/cli) | [![npm](https://img.shields.io/npm/v/@chainsafe/lodestar)](https://www.npmjs.com/package/@chainsafe/lodestar) | [![License: LGPL v3](https://img.shields.io/badge/License-LGPL%20v3-blue.svg)](https://www.gnu.org/licenses/lgpl-3.0) | [![documentation](https://img.shields.io/badge/readme-blue)](./packages/cli/) | :computer: Command-line tool for Lodestar |
| [`@lodestar/state-transition`](./packages/state-transition) | [![npm](https://img.shields.io/npm/v/@lodestar/state-transition)](https://www.npmjs.com/package/@lodestar/state-transition) | [![License: LGPL v3](https://img.shields.io/badge/License-LGPL%20v3-blue.svg)](https://www.gnu.org/licenses/lgpl-3.0) | [![documentation](https://img.shields.io/badge/readme-blue)](./packages/state-transition) | :mag_right: Eth Consensus beacon-state transition |
| [`@lodestar/types`](./packages/types) | [![npm](https://img.shields.io/npm/v/@lodestar/types)](https://www.npmjs.com/package/@lodestar/types) | [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) | [![documentation](https://img.shields.io/badge/readme-blue)](./packages/types) | :spiral_notepad: Eth Consensus TypeScript and SSZ types |
| [`@lodestar/params`](./packages/params) | [![npm](https://img.shields.io/npm/v/@lodestar/params)](https://www.npmjs.com/package/@lodestar/params) | [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) | [![documentation](https://img.shields.io/badge/readme-blue)](./packages/params) | :spider_web: Eth Consensus network parameters |
| [`@lodestar/utils`](./packages/utils) | [![npm](https://img.shields.io/npm/v/@lodestar/utils)](https://www.npmjs.com/package/@lodestar/utils) | [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) | [![documentation](https://img.shields.io/badge/readme-blue)](./packages/utils) | :toolbox: Miscellaneous utility functions used across Lodestar |
| [`@lodestar/config`](./packages/config) | [![npm](https://img.shields.io/npm/v/@lodestar/config)](https://www.npmjs.com/package/@lodestar/config) | [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) | [![documentation](https://img.shields.io/badge/readme-blue)](./packages/config) | :spiral_notepad: Eth Consensus types and params bundled together |
| [`@lodestar/spec-test-util`](./packages/spec-test-util) | [![npm](https://img.shields.io/npm/v/@lodestar/spec-test-util)](https://www.npmjs.com/package/@lodestar/spec-test-util) | [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) | [![documentation](https://img.shields.io/badge/readme-blue)](./packages/spec-test-util) | :test_tube: Test harness for Eth Consensus spec tests |
| [`@lodestar/db`](./packages/db) | [![npm](https://img.shields.io/npm/v/@lodestar/db)](https://www.npmjs.com/package/@lodestar/db) | [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) | [![documentation](https://img.shields.io/badge/readme-blue)](./packages/db) | :floppy_disk: Read/write persistent Eth Consensus data |
| [`@lodestar/fork-choice`](./packages/fork-choice) | [![npm](https://img.shields.io/npm/v/@lodestar/fork-choice)](https://www.npmjs.com/package/@lodestar/fork-choice) | [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) | [![documentation](https://img.shields.io/badge/readme-blue)](./packages/fork-choice) | :fork_and_knife: Beacon-chain fork choice |
## Contributors

6
RELEASE.md
View File

@@ -94,6 +94,7 @@ Tagging a stable release will trigger CI to publish to NPM, dockerhub, and Githu
- `git checkout stable`
- `yarn release:tag-stable 1.1.0`
- Must be run locally from a write-access account capable of triggering CI.
#### Manual steps (for example version `v1.1.0`):
- Check out the new stable
@@ -112,6 +113,7 @@ Tagging a stable release will trigger CI to publish to NPM, dockerhub, and Githu
If a stable version requires an immediate hot-fix before the next release, a hot-fix release is started.
A similar process for a stable release is used, with the three differences.
- The candidate commit must be chosen from the `stable` branch instead of the `unstable` branch.
- Depending on the severity of the bug being fixed, the testing window may be decreased.
- All hotfixes are committed with an `unstable` first strategy rather than directly on the RC branch itself. Hotfixes are always merged to `unstable` first, then cherry-picked into hotfix release candidates.
@@ -142,7 +144,7 @@ A similar process for a stable release is used, with the three differences.
- Commit changes
- `git commit -am "v1.1.1"`
- `git push origin rc/v1.1.1`
Open draft PR from `rc/v1.1.1` to `stable` with the title `v1.1.1 release`.
Open draft PR from `rc/v1.1.1` to `stable` with the title `v1.1.1 release`.
### 2. Tag release candidate
@@ -239,7 +241,9 @@ The release should be announced on the following social channels:
- Blog post (if necessary): To outline specific changes that require additional context for users
# Release Manager Checklist
This section is to guide the Release Manager tasked with the next version release to ensure all items have been completed.
- Start thread on communication channels for new release
- Confirm consensus on `unstable` release candidate commit
- Complete Step 1: Create release candidate

32
docs/design/depgraph.md
View File

@@ -72,43 +72,43 @@ For a list of all the packages in the monorepo and a description for each, click
Let's talk about how each package fits together in finer detail, from top to bottom, following the chart.
## @lodestar/params
## `@lodestar/params`
[@lodestar/params](https://github.com/ChainSafe/lodestar/tree/unstable/packages/params) contains the parameters for configuring an Ethereum Consensus network. For example, the [mainnet params](https://github.com/ethereum/consensus-specs/blob/v1.1.10/specs/phase0/beacon-chain.md#configuration)
## @lodestar/types
## `@lodestar/types`
[@lodestar/types](https://github.com/ChainSafe/lodestar/tree/unstable/packages/types) contains Eth Consensus ssz types and data structures.
[@lodestar/types](https://github.com/ChainSafe/lodestar/tree/unstable/packages/types) contains Ethereum Consensus ssz types and data structures.
## @lodestar/config
## `@lodestar/config`
[@lodestar/config](https://github.com/ChainSafe/lodestar/tree/unstable/packages/config) combines [`lodestar-params`](#chainsafelodestar-params) and [`lodestar-types`](#chainsafelodestar-types) together to be used as a single config object across the other Lodestar packages.
[@lodestar/config](https://github.com/ChainSafe/lodestar/tree/unstable/packages/config) combines `@lodestar/params` and `@lodestar/types` together to be used as a single config object across the other Lodestar packages.
## @lodestar/utils
## `@lodestar/utils`
[@lodestar/utils](https://github.com/ChainSafe/lodestar/tree/unstable/packages/utils) contains various utilities that are common among the various Lodestar monorepo packages.
## @lodestar/state-transition
## `@lodestar/state-transition`
[@lodestar/state-transition](https://github.com/ChainSafe/lodestar/tree/unstable/packages/state-transition) contains the Lodestar implementation of the [beacon state transition function](https://github.com/ethereum/consensus-specs/blob/v1.1.10/specs/phase0/beacon-chain.md#beacon-chain-state-transition-function), which is used by [`@lodestar/beacon-node`](#chainsafelodestar) to perform the actual beacon state transition. This package also contains various functions used to calculate info about the beacon chain (such as `computeEpochAtSlot`) which are used by [@lodestar/fork-choice](#chainsafelodestar-fork-choice) and [@lodestar/validator](#chainsafelodestar-validator)
[@lodestar/state-transition](https://github.com/ChainSafe/lodestar/tree/unstable/packages/state-transition) contains the Lodestar implementation of the [beacon state transition function](https://github.com/ethereum/consensus-specs/blob/v1.1.10/specs/phase0/beacon-chain.md#beacon-chain-state-transition-function), which is used by `@lodestar/beacon-node` to perform the actual beacon state transition. This package also contains various functions used to calculate info about the beacon chain (such as `computeEpochAtSlot`) which are used by `@lodestar/fork-choice` and `@lodestar/validator`
## @lodestar/db
## `@lodestar/db`
[@lodestar/db](https://github.com/ChainSafe/lodestar/tree/unstable/packages/db) is where all persistent data about the beacon node is stored. Any package that needs to read or write persistent beacon node data depends on `lodestar-db`.
## @lodestar/fork-choice
## `@lodestar/fork-choice`
[@lodestar/fork-choice](https://github.com/ChainSafe/lodestar/tree/unstable/packages/fork-choice) holds the methods for reading/writing the fork choice DAG. The [`@lodestar/beacon-node`](#chainsafelodestar) package is the sole consumer of this package because the beacon node itself is what controls when the fork choice DAG is updated.
For a good explainer on how the fork choice itself works, see the [annotated fork choice spec](https://github.com/ethereum/annotated-spec/blob/v1.1.10/phase0/fork-choice.md). This is an annotated version of the [Eth Consensus fork choice spec](https://github.com/ethereum/consensus-specs/blob/v1.1.10/specs/phase0/fork-choice.md) which `lodestar-fork-choice` is based on.
[@lodestar/fork-choice](https://github.com/ChainSafe/lodestar/tree/unstable/packages/fork-choice) holds the methods for reading/writing the fork choice DAG. The `@lodestar/beacon-node` package is the sole consumer of this package because the beacon node itself is what controls when the fork choice DAG is updated.
For a good explanation on how the fork choice itself works, see the [annotated fork choice spec](https://github.com/ethereum/annotated-spec/blob/v1.1.10/phase0/fork-choice.md). This is an annotated version of the [Ethereum Consensus fork choice spec](https://github.com/ethereum/consensus-specs/blob/v1.1.10/specs/phase0/fork-choice.md) which `lodestar-fork-choice` is based on.
## @lodestar/validator
## `@lodestar/validator`
[@lodestar/validator](https://github.com/ChainSafe/lodestar/tree/unstable/packages/validator) contains the validator client. The sole consumer of this package is [@chainsafe/lodestar](#chainsafelodestar-cli), which provides CLI access to run and configure the validator client. However, the validator client communicates to a REST API that is contained in [@lodestar/beacon-node](#chainsafelodestar) (specifically in the `api` module) to perform the validator duties.
[@lodestar/validator](https://github.com/ChainSafe/lodestar/tree/unstable/packages/validator) contains the validator client. The sole consumer of this package is `@chainsafe/lodestar`, which provides CLI access to run and configure the validator client. However, the validator client communicates to a REST API that is contained in `@lodestar/beacon-node` (specifically in the `api` module) to perform the validator duties.
## @lodestar/beacon-node
## `@lodestar/beacon-node`
[@lodestar/beacon-node](https://github.com/ChainSafe/lodestar/tree/unstable/packages/beacon-node) contains the actual beacon node process itself, which is the aggregate of all the above packages and the "brain" of the Lodestar beacon chain implementation. All of the node modules live in this package as well.
## @chainsafe/lodestar
## `@chainsafe/lodestar`
[@chainsafe/lodestar](https://github.com/ChainSafe/lodestar/tree/unstable/packages/cli) combines everything together for CLI usage and configuration of the beacon node and validator.

2
docs/index.md
View File

@@ -29,7 +29,7 @@ Hardware specifications minimum / recommended, to run the Lodestar client.
## About these docs
This documentation is open source, contribute at [github.com/chainsafe/lodestar/docs](https://github.com/ChainSafe/lodestar/tree/unstable/docs).
This documentation is open source, contribute at [Github Lodestar repository /docs](https://github.com/ChainSafe/lodestar/tree/unstable/docs).
## Need assistance?

7
docs/install/docker.md
View File

@@ -1,10 +1,10 @@
# Install with Docker
The [`chainsafe/lodestar`](https://hub.docker.com/r/chainsafe/lodestar) Docker Hub repository is mantained actively. It contains the `lodestar` CLI preinstalled.
The [`chainsafe/lodestar`](https://hub.docker.com/r/chainsafe/lodestar) Docker Hub repository is maintained actively. It contains the `lodestar` CLI preinstalled.
<!-- prettier-ignore-start -->
!!! info
The Docker Hub image tagged as `chainsafe/lodestar:next` is run on CI every dev commit on our `unstable` branch.
The Docker Hub image tagged as `chainsafe/lodestar:next` is run on CI every commit on our `unstable` branch.
For `stable` releases, the image is tagged as `chainsafe/lodestar:latest`.
<!-- prettier-ignore-end -->
@@ -22,7 +22,8 @@ Pull, run the image and Lodestar should now be ready to use
docker pull chainsafe/lodestar
docker run chainsafe/lodestar --help
```
<!-- prettier-ignore-start -->
!!! info
Docker is the recommended setup for Lodestar. Use our [Lodestar Quickstart scripts](https://github.com/ChainSafe/lodestar-quickstart) with Docker for detailed instructions.
<!-- prettier-ignore-end -->
<!-- prettier-ignore-end -->

2
docs/install/npm.md
View File

@@ -3,4 +3,4 @@
<!-- prettier-ignore-start -->
!!! danger
For mainnet (production) usage, we only recommend installing with docker due to [NPM supply chain attacks](https://hackaday.com/2021/10/22/supply-chain-attack-npm-library-used-by-facebook-and-others-was-compromised/). Until a [safer installation method has been found](https://github.com/ChainSafe/lodestar/issues/3596), do not use this install method except for experimental purposes only.
<!-- prettier-ignore-end -->
<!-- prettier-ignore-end -->

4
docs/install/source.md
View File

@@ -10,12 +10,12 @@ Make sure to have [Yarn installed](https://classic.yarnpkg.com/en/docs/install).
It is important to make sure the NodeJS version is not changed after reboot by setting a default `nvm alias default <version> && nvm use default`.
!!! note
Node Version Manager (NVM) will only install NodeJS for use with the active user. If you intend on setting up Lodestar to run under another user, we recommend using [Nodesource's source for NodeJS](https://github.com/nodesource/distributions/blob/master/README.md#installation-instructions) so you can install NodeJS globally.
Node Version Manager (NVM) will only install NodeJS for use with the active user. If you intend on setting up Lodestar to run under another user, we recommend using [NodeSource's source for NodeJS](https://github.com/nodesource/distributions/blob/master/README.md#installation-instructions) so you can install NodeJS globally.
<!-- prettier-ignore-end -->
## Clone repository
Clone the repo locally and build from the stable release branch.
Clone the repository locally and build from the stable release branch.
```bash
git clone -b stable https://github.com/chainsafe/lodestar.git

30
docs/libraries/index.md
View File

@@ -6,29 +6,29 @@ The Lodestar project is divided into Typescript packages that can be used indepe
Several useful Ethereum consensus libraries are developed as part of the [Lodestar monorepo](https://github.com/ChainSafe/lodestar) and may be useful when used individually.
- [params](https://github.com/ChainSafe/lodestar/tree/unstable/packages/params) - Ethereum consensus constants and fork names
- [types](https://github.com/ChainSafe/lodestar/tree/unstable/packages/types) - Ethereum consensus datatypes, Typescript interfaces and SSZ type objects
- [config](https://github.com/ChainSafe/lodestar/tree/unstable/packages/config) - Ethereum consensus run-time network configuration
- [api](https://github.com/ChainSafe/lodestar/tree/unstable/packages/api) - Ethereum consensus REST API client
- [flare](https://github.com/ChainSafe/lodestar/tree/unstable/packages/flare) - Beacon chain multi-purpose and debugging tool
- [`params`](https://github.com/ChainSafe/lodestar/tree/unstable/packages/params) - Ethereum consensus constants and fork names
- [`types`](https://github.com/ChainSafe/lodestar/tree/unstable/packages/types) - Ethereum consensus types, Typescript interfaces and SSZ type objects
- [`config`](https://github.com/ChainSafe/lodestar/tree/unstable/packages/config) - Ethereum consensus run-time network configuration
- [`api`](https://github.com/ChainSafe/lodestar/tree/unstable/packages/api) - Ethereum consensus REST API client
- [`flare`](https://github.com/ChainSafe/lodestar/tree/unstable/packages/flare) - Beacon chain multi-purpose and debugging tool
## Other libraries
### BLS Utilities
- [bls](https://github.com/ChainSafe/bls) - Eth Consensus BLS sign / verify / aggregate
- [bls-keystore](https://github.com/ChainSafe/bls-keystore) - store / retrieve a BLS secret key from an [EIP-2335](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-2335.md) JSON keystore
- [bls-keygen](https://github.com/ChainSafe/bls-keygen) - utility functions to generate BLS secret keys, following [EIP-2333](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-2333.md) and [EIP-2334](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-2334.md)
- [bls-hd-key](https://github.com/ChainSafe/bls-hd-key) - low level [EIP-2333](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-2333.md) and [EIP-2334](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-2334.md) functionality
- [`bls`](https://github.com/ChainSafe/bls) - Ethereum Consensus BLS sign / verify / aggregate
- [`bls-keystore`](https://github.com/ChainSafe/bls-keystore) - store / retrieve a BLS secret key from an [EIP-2335](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-2335.md) JSON keystore
- [`bls-keygen`](https://github.com/ChainSafe/bls-keygen) - utility functions to generate BLS secret keys, following [EIP-2333](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-2333.md) and [EIP-2334](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-2334.md)
- [`bls-hd-key`](https://github.com/ChainSafe/bls-hd-key) - low level [EIP-2333](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-2333.md) and [EIP-2334](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-2334.md) functionality
### Hashing
- [ssz](https://github.com/ChainSafe/ssz) - Simple Serialize (SSZ)
- [persistent-merkle-tree](https://github.com/ChainSafe/persistent-merkle-tree) - binary merkle tree implemented as a [persistent data structure](https://en.wikipedia.org/wiki/Persistent_data_structure)
- [as-sha256](https://github.com/ChainSafe/as-sha256) - Small AssemblyScript implementation of SHA256
- [`ssz`](https://github.com/ChainSafe/ssz) - Simple Serialize (SSZ)
- [`persistent-merkle-tree`](https://github.com/ChainSafe/persistent-merkle-tree) - binary merkle tree implemented as a [persistent data structure](https://en.wikipedia.org/wiki/Persistent_data_structure)
- [`as-sha256`](https://github.com/ChainSafe/as-sha256) - Small AssemblyScript implementation of SHA256
### Networking
- [discv5](https://github.com/ChainSafe/discv5) - [Discv5](https://github.com/ethereum/devp2p/blob/master/discv5/discv5.md) protocol
- [js-libp2p-gossipsub](https://github.com/ChainSafe/js-libp2p-gossipsub) - [Gossipsub](https://github.com/libp2p/specs/tree/master/pubsub/gossipsub) protocol for js-libp2p
- [js-libp2p-noise](https://github.com/NodeFactoryIo/js-libp2p-noise) - [Noise](https://noiseprotocol.org/noise.html) handshake for js-libp2p
- [`discv5`](https://github.com/ChainSafe/discv5) - [Discv5](https://github.com/ethereum/devp2p/blob/master/discv5/discv5.md) protocol
- [`js-libp2p-gossipsub`](https://github.com/ChainSafe/js-libp2p-gossipsub) - [Gossipsub](https://github.com/libp2p/specs/tree/master/pubsub/gossipsub) protocol for `js-libp2p`
- [`js-libp2p-noise`](https://github.com/NodeFactoryIo/js-libp2p-noise) - [Noise](https://noiseprotocol.org/noise.html) handshake for `js-libp2p`

14
docs/quickstart.md
View File

@@ -1,6 +1,6 @@
## Lodestar Quickstart
In order to make things easy for users to onboard and try the ethereum **Proof of Stake** we have come up with [Lodestar quickstart](https://github.com/ChainSafe/lodestar-quickstart) scripts!
In order to make things easy for users to onboard and try the Ethereum **Proof of Stake** we have come up with [Lodestar quick start](https://github.com/ChainSafe/lodestar-quickstart) scripts!
✅ Zero Configuration
✅ All testnets supported along with `mainnet`
@@ -12,17 +12,11 @@ With just single command you can run lodestar with various execution engines, sw
You can adapt them to your production setups with ease! Here is a simple guide for you to follow along:
👉 https://hackmd.io/@philknows/rJegZyH9q
👉 [Lodestar Quick Setup Guide](https://hackmd.io/@philknows/rJegZyH9q)
### Support
### Support
We actively maintain and update the configurations of running lodestar with the top of the line execution engines for various PoS networks so you have the minimum possible figuring out to do.
In case you are facing any issues with the quickstart, do reach us out on lodestar discord!
In case you are facing any issues with the quick start guide, do reach us out on lodestar discord!
Happy to help! 🙏🙏🙏

28
docs/tools/flamegraphs.md
View File

@@ -1,34 +1,30 @@
# Generating Flamegraphs for a Running Node Service on Linux
This guide assumes a running instance of Lodestar and will walk through how to generate a flamegraph for the process while running on Linux. While it is possible to run Lodestar in a number of ways, for performance profiling it is recommended to not use Dockerized implementations. It is best to run Lodestar as a service on a Linux machine. Follow the Lodestar docs to get the service installed and running. Then come back here when you are ready to generate the flamegraph.
This guide assumes a running instance of Lodestar and will walk through how to generate a flamegraph for the process while running on Linux. While it is possible to run Lodestar in a number of ways, for performance profiling it is recommended to not use Dockerized implementations. It is best to run Lodestar as a service on a Linux machine. Follow the Lodestar docs to get the service installed and running. Then come back here when you are ready to generate the flamegraph.
## Modifying Linux and Lodestar
Use the following two commands to install `perf` for generating the stack traces. You may get a warning about needing to restart the VM due to kernel updates. This is nothing to be concerned with and if so, cancel out of the restart dialog.
Use the following two commands to install `perf` for generating the stack traces. You may get a warning about needing to restart the VM due to kernel updates. This is nothing to be concerned with and if so, cancel out of the restart dialog.
```bash
sudo apt-get install linux-tools-common linux-tools-generic
sudo apt-get install linux-tools-`uname -r` # empirically this throws if run on the same line above
```
Next we need to update the Lodestar service by modifying the start script. We need to add a necessary flag `--perf-basic-prof` to allow the stack traces to be useful. Node is a virtual machine and `perf` is designed to capture host stack traces. In order to allow the JS functions to be captured meaningfully, `v8` can provide some help. Generally Lodestar is started with a script like the following:
Next we need to update the Lodestar service by modifying the start script. We need to add a necessary flag `--perf-basic-prof` to allow the stack traces to be useful. Node is a virtual machine and `perf` is designed to capture host stack traces. In order to allow the JavaScript functions to be captured meaningfully, `v8` can provide some help. Generally Lodestar is started with a script like the following:
### Example start_lodestar.sh
```sh
#!/bin/bash
# Add the --perf-basic-prof flag to the node process
node \
--perf-basic-prof \
--perf-basic-prof \
--max-old-space-size=4096 \
/usr/src/lodestar/packages/cli/bin/lodestar \
beacon \
--rcConfig /home/devops/beacon/rcconfig.yml
```
After updating the start script, restart the node process running the beacon service. Note in the command below, that the `beacon` service may have a different name or restart command, depending on your setup.
After updating the start script, restart the node process running the beacon service. Note in the command below, that the `beacon` service may have a different name or restart command, depending on your setup.
```sh
admin@12.34.56.78: sudo systemctl restart beacon
@@ -64,7 +60,7 @@ The `isolate-*-v8.log` files are the maps that `v8` outputs for the `perf` comma
The first command below will run `perf` for 60 seconds, and then save the output to a file named `perf.out`. The second one will merge the exported, unknown, tokens with the isolate maps and output full stack traces for the render. Running both `perf` commands in the folder with the `isolate` maps will allow the data to be seamlessly spliced. Once the output is saved, update the permissions so the file can be copied to your local machine via `scp`.
You can modify the frequency of capture by changing `-F 99` to a different number. Try to stay away from whole numbers as they are more likely to cause interference with periodically scheduled tasks. As an example use `99Hz` or `997Hz` instead of `100Hz` or `1000Hz`. In testing neither seemed to have an appreciable affect on cpu usage when run for a short period of time.
You can modify the frequency of capture by changing `-F 99` to a different number. Try to stay away from whole numbers as they are more likely to cause interference with periodically scheduled tasks. As an example use `99Hz` or `997Hz` instead of `100Hz` or `1000Hz`. In testing neither seemed to have an appreciable affect on CPU usage when run for a short period of time.
To change the period of capture adjust the sleep duration (which is in seconds).
@@ -76,7 +72,7 @@ admin@12.34.56.78: sudo perf script -f > perf.out
admin@12.34.56.78: sudo chmod 777 ~/beacon/perf.out
```
And then copy the `perf.out` file to your local machine to render the flamegraph. Running at `99Hz` for 180 seconds results in a file size of about 3.5mb and `997Hz` for 60 seconds is roughly 4.4mb.
And then copy the `perf.out` file to your local machine to render the flamegraph. Running at `99Hz` for 180 seconds results in a file size of about 3.5MB and `997Hz` for 60 seconds is roughly 4.4MB.
```sh
scp admin@12.34.56.78:/home/devops/beacon/out.perf /some_temp_dir/perf.out
@@ -84,15 +80,15 @@ scp admin@12.34.56.78:/home/devops/beacon/out.perf /some_temp_dir/perf.out
## Rendering a Flamegraph
By far the best tool to render flamegraphs is [`flamescope`](https://github.com/Netflix/flamescope) from Netflix. It allows for easy analysis and zooming into specific time periods. It also give a holistic view of how the process is performing over time.
By far the best tool to render flamegraphs is [`flamescope`](https://github.com/Netflix/flamescope) from Netflix. It allows for easy analysis and zooming into specific time periods. It also give a holistic view of how the process is performing over time.
## Installation
Python3 is required. Clone the repository and install the dependencies:
_The original is no longer maintained and had a configuration bug. This is a fork that fixes the issue._
```sh
# The original is no longer maintained and had a configuration bug
# This is a fork that fixes the issue.
git clone https://github.com/matthewkeil/flamescope
cd flamescope
pip3 install -r requirements.txt
@@ -116,7 +112,7 @@ Then navigate in a browser to `http://localhost:8080` and begin analyzing the da
## Filtering Results
There can be a lot of "noise" in the stack traces with `libc`, `v8` and `libuv` calls. It is possible to filter the results to make it more useful, but note this will skew the results. Looking at the graph both filtered and unfiltered can be beneficial. The following `sed` command will remove the noise from the stack traces. You can also use the bottom script programmatically to add/remove filters.
There can be a lot of "noise" in the stack traces with `libc`, `v8` and `libuv` calls. It is possible to filter the results to make it more useful, but note this will skew the results. Looking at the graph both filtered and unfiltered can be beneficial. The following `sed` command will remove the noise from the stack traces.
```sh
sed -r -e "/( __libc_start| uv_| LazyCompile | v8::internal::| node::| Builtins_| Builtin:| Stub:| LoadIC:| \\[unknown\\]| LoadPolymorphicIC:)/d" -e 's/ LazyCompile:[*~]?/ /'
@@ -137,7 +133,7 @@ sed -r -e "/( __libc_start| uv_| LazyCompile | v8::internal::| node::| Builtins_
- <https://www.brendangregg.com/flamegraphs.html>
- <https://nodejs.org/en/docs/guides/diagnostics-flamegraph>
- <https://netflixtechblog.com/netflix-flamescope-a57ca19d47bb>
- <https://jaanhio.me/blog/nodejs-flamegraph-analysis/> (this was a great one about filtering methodology)
- <https://jaanhio.me/blog/nodejs-flamegraph-analysis/> (this was a great one about filtering methodology)
- <https://medium.com/voodoo-engineering/node-js-and-cpu-profiling-on-production-in-real-time-without-downtime-d6e62af173e2>
### Visualization Tools

24
docs/usage/beacon-management.md
View File

@@ -106,13 +106,13 @@ If you are starting your node from a blank db/genesis (or from last saved state
If you have a synced beacon node available (e.g., your friend's node or an infrastructure provider) and a trusted checkpoint you can rely on, you can start off your beacon node in under a minute! And at the same time kicking the "long range attack" in its butt!
Just supply these **extra args** to your beacon node command:
Just supply these **extra arguments** to your beacon node command:
```bash
--checkpointSyncUrl <synced node url> [--wssCheckpoint <trusted checkpoint in root:epoch format>]
```
In case you really trust `checkpointSyncUrl` then you may skip providing `wssCheckpoint`, which will then result into your beacon node syncing and starting off the recently finalized state from the trusted url.
In case you really trust `checkpointSyncUrl` then you may skip providing `wssCheckpoint`, which will then result into your beacon node syncing and starting off the recently finalized state from the trusted URL.
<!-- prettier-ignore-start -->
!!! warning
@@ -131,45 +131,55 @@ necessary for the node to be synced right away to fulfill its duties as there is
### Guide to the sync logs
Lodestar beacon sync log aims to provide information of utmost importance about your node and yet be suucint at the same time. You may see the sync logs in the following format:
Lodestar beacon sync log aims to provide information of utmost importance about your node and yet be succinct at the same time. You may see the sync logs in the following format:
`[Sync status] - [ Slot info ] - [Head info] - [Exec block info] - [Finalized info] - [Peers info]`
See the following example of different kinds of sync log:
```
Apr-20 15:24:08.034[] info: Searching peers - peers: 0 - slot: 6265018 - head: 6264018 0xed93…7b0a - exec-block: syncing(17088476 0x9649…) - finalized: 0xbf30…7e7c:195777
Apr-20 15:24:17.000[] info: Searching peers - peers: 0 - slot: 6265019 - head: 6264018 0xed93…7b0a - exec-block: syncing(17088476 0x9649…) - finalized: 0xbf30…7e7c:195777
```
```
Apr-20 15:13:41.298[] info: Syncing - 2.5 minutes left - 2.78 slots/s - slot: 6264966 - head: 6262966 0x5cec…f5b8 - exec-block: valid(17088105 0x6f74…) - finalized: 0x5cc0…3874:195764 - peers: 1
Apr-20 15:13:41.298[] info: Syncing - 2 minutes left - 2.78 slots/s - slot: 6264967 - head: 6263965 0x5cec…f5b8 - exec-block: valid(17088105 0x6f74…) - finalized: 0x5cc0…3874:195764 - peers: 1
```
```
Apr-20 15:13:53.151[] info: Syncing - 1.6 minutes left - 3.82 slots/s - slot: 6264967 - head: (slot -360) 0xe0cf…9f3c - exec-block: valid(17088167 0x2d6a…) - finalized: 0x8f3f…2f81:195766 - peers: 5
Apr-20 15:14:05.425[] info: Syncing - 1.1 minutes left - 4.33 slots/s - slot: 6264968 - head: (slot -297) 0x3655…1658 - exec-block: valid(17088231 0xdafd…) - finalized: 0x9475…425a:195769 - peers: 2
Apr-20 15:14:53.001[] info: Syncing - 9 seconds left - 5.00 slots/s - slot: 6264972 - head: (slot -45) 0x44e4…20a4 - exec-block: valid(17088475 0xca61…) - finalized: 0x9cbd…ba83:195776 - peers: 8
```
```
Apr-20 15:15:01.443[network] info: Subscribed gossip core topics
Apr-20 15:15:01.446[sync] info: Subscribed gossip core topics
Apr-20 15:15:05.000[] info: Synced - slot: 6264973 - head: 0x90ea…c655 - exec-block: valid(17088521 0xca9b…) - finalized: 0x6981…682f:195778 - peers: 6
Apr-20 15:15:17.003[] info: Synced - slot: 6264974 - head: 0x4f7e…0e3a - exec-block: valid(17088522 0x08b1…) - finalized: 0x6981…682f:195778 - peers: 6
```
```
Apr-20 15:15:41.001[] info: Synced - slot: 6264976 - head: (slot -1) 0x17c6…71a7 - exec-block: valid(17088524 0x5bc1…) - finalized: 0x6981…682f:195778 - peers: 8
Apr-20 15:15:53.001[] info: Synced - slot: 6264977 - head: (slot -2) 0x17c6…71a7 - exec-block: valid(17088524 0x5bc1…) - finalized: 0x6981…682f:195778 - peers: 8
```
```
Apr-20 15:16:05.000[] info: Synced - slot: 6264978 - head: 0xc9fd…28c5 - exec-block: valid(17088526 0xb5bf…) - finalized: 0x6981…682f:195778 - peers: 8
Apr-20 15:16:17.017[] info: Synced - slot: 6264979 - head: 0xde91…d4cb - exec-block: valid(17088527 0xa488…) - finalized: 0x6981…682f:195778 - peers: 7
```
1. Sync status: Takes three values : `Synced` or `Syncing` (along with sync speed info) or `Searching` if node is is still looking for viable peers from where it can download blocks.
2. Slot (clock) info: What is the current ongoing slot as per the chain genesis
3. Head info: It specifies where the local chain head hash is. In case its far behind the Slot (clock) then it independntly shows the head slot else it show how far behind from the Slot it is if difference < 1000.
3. Head info: It specifies where the local chain head hash is. In case its far behind the Slot (clock) then it independently shows the head slot else it show how far behind from the Slot it is if difference < 1000.
4. Exec block info: It provides the execution information about the head whether its confirmed `valid` or EL is still `syncing` to it, as well as its number and a short hash to easy identification.
4. Execution block info: It provides the execution information about the head whether its confirmed `valid` or execution layer is still `syncing` to it, as well as its number and a short hash to easy identification.
5. Finalized info: What is the current local `finalized` checkpoint in the format of `[checkpoint root]:[checkpoint epoch]`, for e.g.: `0xd7ba…8386:189636`
6. Peer info: Current total number of outbound or inbound peers, for e.g.: `peers: 27`
For more insight into lodestar beacon functioning, you may setup lodestar metrics and use prepared grafana dashboards that you may find in the repo.
For more insight into lodestar beacon functioning, you may setup lodestar metrics and use prepared Grafana dashboards that you may find in the repository.

4
docs/usage/client-monitoring.md
View File

@@ -3,7 +3,7 @@
Lodestar has the ability to send client stats to a remote service for collection.
At the moment, the main service offering remote monitoring is [beaconcha.in](https://beaconcha.in/).
Instructions for setting up client monitoring with *beaconcha.in* can be found in their docs about
Instructions for setting up client monitoring with _beaconcha.in_ can be found in their docs about
[Mobile App <> Node Monitoring](https://kb.beaconcha.in/beaconcha.in-explorer/mobile-app-less-than-greater-than-beacon-node)
and in your [account settings](https://beaconcha.in/user/settings#app).
@@ -19,7 +19,7 @@ Client monitoring can be enabled by setting the `--monitoring.endpoint` flag to
lodestar beacon --monitoring.endpoint "https://beaconcha.in/api/v1/client/metrics?apikey={apikey}&machine={machineName}"
```
In case of *beaconcha.in*, the API key can be found in your [account settings](https://beaconcha.in/user/settings#api).
In case of _beaconcha.in_, the API key can be found in your [account settings](https://beaconcha.in/user/settings#api).
Setting the machine is optional but it is especially useful if you are monitoring multiple nodes.
<!-- prettier-ignore-start -->

11
docs/usage/local.md
View File

@@ -19,15 +19,15 @@ Run a beacon node as a **bootnode**, with 8 validators with the following comman
`--genesisValidators` and `--genesisTime` define the genesis state of the beacon chain. `--dataDir` defines a path where
lodestar should store the beacon state.
`--enr.ip` sets the enr ip entry for the node (essential for second node to connect via `enr`) and `--enr.udp` exposes the `discv5` discovery service (if you want to connect more than 1 node and enable discovery amongst them via *bootnode*).
`--enr.ip` sets the ENR IP entry for the node (essential for second node to connect via `enr`) and `--enr.udp` exposes the `discv5` discovery service (if you want to connect more than 1 node and enable discovery amongst them via _bootnode_).
Lastly the `--reset` flag ensures the state is cleared on each restart - which is useful when testing locally.
Once the node has started, make a request to `curl http://localhost:9596/eth/v1/node/identity` and copy the `enr` value.
This would be used to connect from the second node.
> ENR stands for ethereum node records, which is a format for conveying p2p connectivity information for ethereum nodes.
> For more info see [eip-778](https://eips.ethereum.org/EIPS/eip-778).
> ENR stands for Ethereum node records, which is a format for conveying p2p connectivity information for Ethereum nodes.
> For more info see [EIP-778](https://eips.ethereum.org/EIPS/eip-778).
**Terminal 2**
@@ -53,8 +53,8 @@ to have the same beacon chain.
Also `--port` and `--rest.port` are supplied since the default values will already be in use by the first node.
The `--network.connectToDiscv5Bootnodes` flags needs to be set to true as this is needed to allow connection to boot enrs on local devnet.
The exact enr of node to connect to is then supplied via the `--network.discv5.bootEnrs` flag.
The `--network.connectToDiscv5Bootnodes` flags needs to be set to true as this is needed to allow connection to boot ENRs on local devnet.
The exact ENR of node to connect to is then supplied via the `--network.discv5.bootEnrs` flag.
Once the second node starts, you should see an output similar to the following in either of the terminals:
@@ -71,7 +71,6 @@ For example, making the request on the first node via the following command:
will give a result similar to the following:
```
{
"data": [
{

22
docs/usage/mev-integration.md
View File

@@ -1,8 +1,8 @@
# MEV & Merge
MEV is a term refered to bundling the transactions in one particular order to extract (mostly) arbitrage opportunities on the DAPPs and DEXes.
MEV is a term that refers to the bundling of transactions in one particular order to extract (mostly) arbitrage opportunities on the dApps and decentralized exchanges.
And the ones who gets to include these execution payloads (miners in pre-merge world, validators in post-merge) in the canonical chain get paid a per-block reward which essentially _should be_ higher than the normal payload inclusion reward (including transactions tips).
And the ones who gets to include these execution payloads (miners before the merge, validators after the merge) in the canonical chain get paid a per-block reward which essentially _should be_ higher than the normal payload inclusion reward (including transactions tips).
Currently these happen with miners running forked versions of their favorite execution client, integrating with these "builders" but in the post-merge world they get a more native and standard integration with the CL.
@@ -10,7 +10,7 @@ This is what we in CL land refer to as **Builder Api**.
## Lodestar and Builder API
Lodestar offers builder integrations through the _spec-ed_ [builder API](https://ethereum.github.io/builder-specs/#/Builder).
Lodestar offers builder integration through the _spec-ed_ [builder API](https://ethereum.github.io/builder-specs/#/Builder).
This sits in parallel with the execution engine so when enabled, lodestar validator run both flows in parallel when its time to propose for a validator key and currently (naively) picks the builder block in preference to execution if a builder block is fetched (else just proceeds with the execution block).
@@ -18,14 +18,14 @@ This sits in parallel with the execution engine so when enabled, lodestar valida
All you have to do is:
1. Provide lodestar BN with a Builder endpoint (which corresponds to the network you are running) via these additional flags:
```shell
--builder --builder.urls <builder/relay/boost url>
```
2. Run lodestar VC with these additional flags
```shell
--builder --suggestedFeeRecipient <your ethereum address>
```
1. Provide lodestar beacon node with a Builder endpoint (which corresponds to the network you are running) via these additional flags:
```shell
--builder --builder.urls <builder/relay/boost url>
```
2. Run lodestar validator client with these additional flags
```shell
--builder --suggestedFeeRecipient <your ethereum address>
```
There are some more builder flags available in lodestar cli (for both beacon and validator) which you may inspect and use.

4
docs/usage/prometheus-grafana.md
View File

@@ -5,7 +5,7 @@ Prometheus is an open-source monitoring system with efficient time series databa
## Prometheus
To start, download Prometheus from https://prometheus.io/download/.
Unzip the downloaded .zip file and run Prometheus from its installed location with the lodestar prometheus.yml passed in as the config file
Unzip the downloaded .zip file and run Prometheus from its installed location with the lodestar `prometheus.yml` passed in as the configuration file
```
./prometheus --config.file=$dataDir/prometheus.yml
@@ -13,7 +13,7 @@ Unzip the downloaded .zip file and run Prometheus from its installed location wi
<!-- prettier-ignore-start -->
!!! info
8008 is also the default port specified in the prometheus.yml in the lodestar repo
8008 is also the default port specified in the `prometheus.yml` in the lodestar repository
<!-- prettier-ignore-end -->
Then run the Lodestar beacon node with

22
docs/usage/validator-management.md
View File

@@ -19,7 +19,7 @@ The mnemonic is randomly generated during wallet creation and printed out to the
Lodestar is deprecating its functionality to create wallets.
To create a wallet, we recommend using the official [staking-deposit-cli](https://github.com/ethereum/staking-deposit-cli/releases) from the Ethereum Foundation for users comfortable with command line interfaces.
To create a wallet, we recommend using the official [`staking-deposit-cli`](https://github.com/ethereum/staking-deposit-cli/releases) from the Ethereum Foundation for users comfortable with command line interfaces.
Alternatively, for a graphical user interface, you can use the [Stakehouse Wagyu Key Generator](https://wagyu.gg/) developed by members of the EthStaker community.
@@ -34,20 +34,25 @@ Validators are represented by a BLS keypair. Use your generated mnemonic from on
### Import a validator keystore from your wallet to Lodestar
To import a validator keystore that was created via one of the methods described above, you must locate the validator keystore JSONs exported by those tools (ex. `keystore-m_12381_3600_0_0_0-1654128694.json`).
To import a validator keystore that was created via one of the methods described above, you must locate the validator JSON keystores exported by those tools (ex. `keystore-m_12381_3600_0_0_0-1654128694.json`).
Inside the keystore JSON file, you should have an [EIP-2335 conformant keystore file](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-2335.md#json-schema).
Inside the keystore JSON file, you should have an [EIP-2335 keystore file](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-2335.md#json-schema).
You will also need the passphrase used the encrypt the keystore. This can be specified interactively, or provided in a plaintext file.
#### Option 1: Import Keys To Lodestar's Keystores Folder
You can load the keys into the keystore folder using the `validator import` command. There are two methods for importing keystores:
```bash
# Interactive passphrase import
./lodestar validator import --importKeystores ./validator_keys
# Plaintext passphrase file import
_Interactive passphrase import_
```bash
./lodestar validator import --importKeystores ./validator_keys
```
_Plaintext passphrase file import_
```bash
./lodestar validator import --importKeystores ./validator_keys --importKeystoresPassword ./password.txt
```
@@ -61,6 +66,7 @@ You can load the keys into the keystore folder using the `validator import` comm
Once imported with either method, these keystores will be automatically loaded when you start the validator. To list the imported keystores, use the `validator list` command.
---
#### Option 2: Import Keys When Starting the Validator
To import keys when you start the validator specify the `--importKeystores` and `--importKeystoresPassword` flags with the `validator` command:
@@ -74,7 +80,6 @@ To import keys when you start the validator specify the `--importKeystores` and
If you import keys using `--importKeystores` at runtime (Option 2) any keys loaded to the keystores folder from Option 1 will be ignored.
<!-- prettier-ignore-end -->
### Configuring the fee recipient address
Post-Merge Ethereum requires validators to set a **Fee Recipient** which allows you to receive priority fees when proposing blocks. If you do not set this address, your priority fees will be sent to the [burn address](https://etherscan.io/address/0x0000000000000000000000000000000000000000).
@@ -86,6 +91,7 @@ You may choose to use the `--strictFeeRecipientCheck` flag to enable a strict ch
### Submit a validator deposit
Please use the official tools to perform your deposits
- `staking-deposit-cli`: <https://github.com/ethereum/staking-deposit-cli>
- Ethereum Foundation launchpad: <https://launchpad.ethereum.org>

6
package.json
View File

@@ -16,7 +16,10 @@
"build:ifchanged": "lerna exec -- ../../scripts/build_if_changed.sh",
"lint": "eslint --color --ext .ts packages/*/src packages/*/test",
"lint:fix": "yarn lint --fix",
"lint-docs": "prettier '**/*.md' --check",
"lint-docs:fix": "prettier '**/*.md' --write",
"check-build": "lerna run check-build",
"check-readme": "lerna run check-readme",
"check-types": "lerna run check-types --no-bail",
"coverage": "lerna run coverage --no-bail",
"test": "lerna run test --no-bail --concurrency 1",
@@ -30,8 +33,7 @@
"release:create-rc": "node scripts/release/create_rc.mjs",
"release:tag-rc": "node scripts/release/tag_rc.mjs",
"release:tag-stable": "node scripts/release/tag_stable.mjs",
"release:publish": "lerna publish from-package --yes --no-verify-access",
"check-readme": "lerna run check-readme"
"release:publish": "lerna publish from-package --yes --no-verify-access"
},
"devDependencies": {
"@chainsafe/eslint-plugin-node": "^11.2.3",

2
packages/api/README.md
View File

@@ -25,7 +25,7 @@ api.beacon
"0x933ad9491b62059dd065b560d256d8957a8c402cc6e8d8ee7290ae11e8f7329267a8811c397529dac52ae1342ba58c95"
)
.then((res) => {
if(res.ok) {
if (res.ok) {
console.log("Your balance is:", res.response.data.balance, res.ok, res.status);
} else {
console.error(res.status, res.error.code, res.error.message);

1
packages/beacon-node/test/scripts/el-interop/gethdocker/README.md
View File

@@ -1,6 +1,7 @@
# Geth Docker setup for running the sim merge tests on local machine
###### Geth docker image
Pull the latest `geth` image from the dockerhub
```bash

2
packages/cli/README.md
View File

@@ -23,7 +23,7 @@ Here's a quick list of the available CLI commands:
| - | - |
| `./bin/lodestar init` | Write a configuration and network identity to disk, by default `./.lodestar`|
|`./bin/lodestar beacon` | Run a beacon node using a configuration from disk, by default `./.lodestar`|
|`./bin/lodestar account` | Run various subcommands for creating/managing Ethereum Consensus accounts|
|`./bin/lodestar account` | Run various sub-commands for creating/managing Ethereum Consensus accounts|
|`./bin/lodestar validator` | Run one or more validator clients|
|`./bin/lodestar dev` | Quickly bootstrap a beacon node and multiple validators. Use for development and testing|
Append `--help` to any of these commands to print out all options for each command.

2
packages/cli/docsgen/index.ts
View File

@@ -58,7 +58,7 @@ function cmdToMarkdownSection(cmd: CliCommand<any>, parentCommand?: string): Mar
body.push("**Options**");
if (cmd.subcommands) {
body.push("The options below apply to all subcommands.");
body.push("The options below apply to all sub-commands.");
}
// De-duplicate beaconOptions. If all beaconOptions exists in this command, skip them

2
packages/cli/src/cmds/beacon/options.ts
View File

@@ -63,7 +63,7 @@ export const beaconExtraOptions: CliCommandOptions<BeaconExtraArgs> = {
wssCheckpoint: {
description:
"Start beacon node off a state at the provided weak subjectivity checkpoint, to be supplied in <blockRoot>:<epoch> format. For example, 0x1234:100 will sync and start off from the weakSubjectivity state at checkpoint of epoch 100 with block root 0x1234.",
"Start beacon node off a state at the provided weak subjectivity checkpoint, to be supplied in <blockRoot>:<epoch> format. For example, 0x1234:100 will sync and start off from the weak subjectivity state at checkpoint of epoch 100 with block root 0x1234.",
type: "string",
group: "weak subjectivity",
},

2
packages/cli/src/cmds/validator/blsToExecutionChange.ts
View File

@@ -37,7 +37,7 @@ like to choose for BLS To Execution Change.",
options: {
publicKey: {
description: "Validator pubkey for which to set withdrawal address hence enabling withdrawals",
description: "Validator public key for which to set withdrawal address hence enabling withdrawals",
type: "string",
string: true,
},

2
packages/cli/src/cmds/validator/list.ts
View File

@@ -15,7 +15,7 @@ export const list: CliCommand<IValidatorCliArgs, GlobalArgs, ReturnType> = {
examples: [
{
command: "validator list",
description: "List all validator pubkeys previously imported",
description: "List all validator public keys previously imported",
},
],

30
packages/cli/src/cmds/validator/options.ts
View File

@@ -83,31 +83,31 @@ export type KeymanagerArgs = {
export const keymanagerOptions: CliCommandOptions<KeymanagerArgs> = {
keymanager: {
type: "boolean",
description: "Enable keymanager API server",
description: "Enable key manager API server",
default: false,
group: "keymanager",
},
"keymanager.authEnabled": {
type: "boolean",
description: "Enable token bearer authentication for keymanager API server",
description: "Enable token bearer authentication for key manager API server",
default: true,
group: "keymanager",
},
"keymanager.port": {
type: "number",
description: "Set port for keymanager API",
description: "Set port for key manager API",
defaultDescription: String(keymanagerRestApiServerOptsDefault.port),
group: "keymanager",
},
"keymanager.address": {
type: "string",
description: "Set host for keymanager API",
description: "Set host for key manager API",
defaultDescription: keymanagerRestApiServerOptsDefault.address,
group: "keymanager",
},
"keymanager.cors": {
type: "string",
description: "Configures the Access-Control-Allow-Origin CORS header for keymanager API",
description: "Configures the Access-Control-Allow-Origin CORS header for key manager API",
defaultDescription: keymanagerRestApiServerOptsDefault.cors,
group: "keymanager",
},
@@ -207,24 +207,24 @@ export const validatorOptions: CliCommandOptions<IValidatorCliArgs> = {
proposerSettingsFile: {
description:
"A yaml file to specify detailed default and per validator pubkey customized proposer configs. PS: This feature and its format is in alpha and subject to change",
"A yaml file to specify detailed default and per validator public key customized proposer configs. PS: This feature and its format is in alpha and subject to change",
type: "string",
},
suggestedFeeRecipient: {
description:
"Specify fee recipient default for collecting the EL block fees and rewards (a hex string representing 20 bytes address: ^0x[a-fA-F0-9]{40}$). It would be possible (WIP) to override this per validator key using config or keymanager API. Only used post merge.",
"Specify fee recipient default for collecting the EL block fees and rewards (a hex string representing 20 bytes address: ^0x[a-fA-F0-9]{40}$). It would be possible (WIP) to override this per validator key using config or key manager API. Only used post merge.",
defaultDescription: defaultOptions.suggestedFeeRecipient,
type: "string",
},
strictFeeRecipientCheck: {
description: "Enable strict checking of the validator's feeRecipient with the one returned by engine",
description: "Enable strict checking of the validator's `feeRecipient` with the one returned by engine",
type: "boolean",
},
defaultGasLimit: {
description: "Suggested gasLimit to the engine/builder for building execution payloads. Only used post merge.",
description: "Suggested gas limit to the engine/builder for building execution payloads. Only used post merge.",
defaultDescription: `${defaultOptions.defaultGasLimit}`,
type: "number",
},
@@ -237,22 +237,22 @@ export const validatorOptions: CliCommandOptions<IValidatorCliArgs> = {
"builder.selection": {
type: "string",
description: "Default builder block selection strategy: maxprofit, builderalways, or builderonly",
defaultDescription: `${defaultOptions.builderSelection}`,
description: "Default builder block selection strategy: `maxprofit`, `builderalways`, or `builderonly`",
defaultDescription: `\`${defaultOptions.builderSelection}\``,
group: "builder",
},
importKeystores: {
alias: ["keystore"], // Backwards compatibility with old `validator import` cmdx
description: "Path(s) to a directory or single filepath to validator keystores, i.e. Launchpad validators",
description: "Path(s) to a directory or single file path to validator keystores, i.e. Launchpad validators",
defaultDescription: "./keystores/*.json",
type: "array",
},
importKeystoresPassword: {
alias: ["passphraseFile"], // Backwards compatibility with old `validator import` cmd
description: "Path to a file with password to decrypt all keystores from importKeystores option",
defaultDescription: "./password.txt",
description: "Path to a file with password to decrypt all keystores from `importKeystores` option",
defaultDescription: "`./password.txt`",
type: "string",
},
@@ -289,7 +289,7 @@ export const validatorOptions: CliCommandOptions<IValidatorCliArgs> = {
"externalSigner.fetch": {
conflicts: ["externalSigner.pubkeys"],
description: "Fetch then list of pubkeys to validate from an external signer",
description: "Fetch then list of public keys to validate from an external signer",
type: "boolean",
group: "externalSignerUrl",
},

2
packages/cli/src/cmds/validator/slashingProtection/export.ts
View File

@@ -37,7 +37,7 @@ export const exportCmd: CliCommand<ExportArgs, ISlashingProtectionArgs & Account
type: "string",
},
pubkeys: {
description: "Export slashing protection data only for a given subset of pubkeys",
description: "Export slashing protection data only for a given subset of public keys",
type: "array",
string: true, // Ensures the pubkey string is not automatically converted to numbers
coerce: (pubkeys: string[]): string[] =>

2
packages/cli/src/cmds/validator/slashingProtection/options.ts
View File

@@ -9,7 +9,7 @@ export const slashingProtectionOptions: CliCommandOptions<ISlashingProtectionArg
beaconNodes: validatorOptions.beaconNodes,
force: {
description: "If genesisValidatorsRoot can't be fetched from the Beacon node, use a zero hash",
description: "If `genesisValidatorsRoot` can't be fetched from the Beacon node, use a zero hash",
type: "boolean",
},
};

4
packages/cli/src/cmds/validator/voluntaryExit.ts
View File

@@ -42,12 +42,12 @@ If no `pubkeys` are provided, it will exit all validators that have been importe
options: {
exitEpoch: {
description:
"The epoch upon which to submit the voluntary exit. If no value is provided, then we default to the currentEpoch.",
"The epoch upon which to submit the voluntary exit. If no value is provided, then we default to the current epoch.",
type: "number",
},
pubkeys: {
description: "Pubkeys to exit, must be available as local signers",
description: "Public keys to exit, must be available as local signers",
type: "array",
string: true, // Ensures the pubkey string is not automatically converted to numbers
coerce: (pubkeys: string[]): string[] =>

2
packages/cli/src/options/beaconNodeOptions/builder.ts
View File

@@ -53,7 +53,7 @@ export const options: CliCommandOptions<ExecutionBuilderArgs> = {
"builder.allowedFaults": {
type: "number",
description: "Number of missed slots allowed in the faultInspectionWindow for builder circuit",
description: "Number of missed slots allowed in the `faultInspectionWindow` for builder circuit",
group: "builder",
},
};

4
packages/cli/src/options/beaconNodeOptions/chain.ts
View File

@@ -51,7 +51,7 @@ export const options: CliCommandOptions<ChainArgs> = {
suggestedFeeRecipient: {
type: "string",
description:
"Specify fee recipient default for collecting the EL block fees and rewards (a hex string representing 20 bytes address: ^0x[a-fA-F0-9]{40}$) in case validator fails to update for a validator index before calling produceBlock.",
"Specify fee recipient default for collecting the EL block fees and rewards (a hex string representing 20 bytes address: ^0x[a-fA-F0-9]{40}$) in case validator fails to update for a validator index before calling `produceBlock`.",
default: defaultOptions.chain.suggestedFeeRecipient,
group: "chain",
},
@@ -59,7 +59,7 @@ export const options: CliCommandOptions<ChainArgs> = {
emitPayloadAttributes: {
type: "boolean",
defaultDescription: String(defaultOptions.chain.emitPayloadAttributes),
description: "Flag to SSE emit execution payloadAttributes before every slot",
description: "Flag to SSE emit execution `payloadAttributes` before every slot",
group: "chain",
},

2
packages/cli/src/options/beaconNodeOptions/eth1.ts
View File

@@ -48,7 +48,7 @@ export const options: CliCommandOptions<Eth1Args> = {
"eth1.providerUrls": {
description:
"Urls to Eth1 node with enabled rpc. If not explicity provided and execution endpoint provided via execution.urls, it will use execution.urls. Otherwise will try connecting on the specified default(s)",
"Urls to Eth1 node with enabled rpc. If not explicitly provided and execution endpoint provided via execution.urls, it will use execution.urls. Otherwise will try connecting on the specified default(s)",
defaultDescription: defaultOptions.eth1.providerUrls?.join(","),
type: "array",
string: true,

4
packages/cli/src/options/logOptions.ts
View File

@@ -17,7 +17,7 @@ export type LogArgs = {
export const logOptions: CliCommandOptions<LogArgs> = {
logLevel: {
choices: LogLevels,
description: "Logging verbosity level for emittings logs to terminal",
description: "Logging verbosity level for emitting logs to terminal",
default: LogLevel.info,
type: "string",
},
@@ -29,7 +29,7 @@ export const logOptions: CliCommandOptions<LogArgs> = {
logFileLevel: {
choices: LogLevels,
description: "Logging verbosity level for emittings logs to file",
description: "Logging verbosity level for emitting logs to file",
default: LogLevel.debug,
type: "string",
},

5
packages/params/README.md
View File

@@ -8,7 +8,6 @@
> This package is part of [ChainSafe's Lodestar](https://lodestar.chainsafe.io) project
Lodestar defines all constants and presets defined in the [Ethereum Consensus spec](https://github.com/ethereum/consensus-specs). This can be used in conjunction with other Lodestar libraries to interact with the Ethereum consensus.
## Installation
@@ -53,7 +52,7 @@ import {GENESIS_SLOT} from "@lodestar/params";
### Presets
Presets are "constants"-ish defined in the spec that can only be configured at build-time. These are meant to be treated as constants, and indeed are treated as constants by all downstream Lodestar libraries. The default preset is `mainnet`. The only other preset defined is `minimal`, used only in testing environments.
Presets are defined in the spec as "constantish" and can only be configured at build-time. These are meant to be treated as constants, and indeed are treated as constants by all downstream Lodestar libraries. The default preset is `mainnet`. The only other preset defined is `minimal`, used only in testing environments.
The active preset is exported under the `ACTIVE_PRESET` named export.
@@ -68,7 +67,7 @@ The preset may be set in one of two ways:
Important Notes:
- Interacting with and understanding the active preset is only necessary in very limited testing environments, eg: for ephemeral testnets
- Interacting with and understanding the active preset is only necessary in very limited testing environments, like for ephemeral testnets
- The `minimal` preset is NOT compatible with the `mainnet` preset.
- using `setActivePreset` may be dangerous, and only should be run once before loading any other libraries. All downstream Lodestar libraries expect the active preset to never change.
- Preset values can be overriden by executing `setActivePreset(presetName: PresetName, overrides?: Partial<BeaconPreset>)` and supplying values to override.

2
packages/prover/README.md
View File

@@ -110,7 +110,7 @@ lodestar-prover start \
## Warnings
- To use this prover the ehtereum provider must support the `eth_getProof` method. Unfortunately, Infura does not currently support this endpoint. As an alternative, we suggest using Alchemy.
- To use this prover the ethereum provider must support the `eth_getProof` method. Unfortunately, Infura does not currently support this endpoint. As an alternative, we suggest using Alchemy.
## Prerequisites

2
packages/spec-test-util/README.md
View File

@@ -2,7 +2,7 @@
> This package is part of [ChainSafe's Lodestar](https://lodestar.chainsafe.io) project
Mocha / Chai utility for interacting with eth2.0 spec tests.
Mocha / Chai utility for interacting with eth2.0 spec tests.
For usage see [spec tests]("https://github.com/ChainSafe/lodestar/tree/unstable/packages/beacon-node/test/spec")

8
packages/types/README.md
View File

@@ -8,7 +8,7 @@
> This package is part of [ChainSafe's Lodestar](https://lodestar.chainsafe.io) project
Lodestar defines all datatypes defined in the [Ethereum Consensus spec](https://github.com/ethereum/consensus-specs). This tooling can be used for any Typescript project looking to operate on these types. Both Typescript interfaces _and_ Simple Serialize (SSZ) methods are exported for consumers.
Lodestar defines all data types defined in the [Ethereum Consensus spec](https://github.com/ethereum/consensus-specs). This tooling can be used for any Typescript project looking to operate on these types. Both Typescript interfaces _and_ Simple Serialize (SSZ) methods are exported for consumers.
## Installation
@@ -18,14 +18,14 @@ npm install @lodestar/types
## Usage
The lodestar types library organizes datatypes on several dimensions:
The lodestar types library organizes data types on several dimensions:
- Typescript interfaces vs SSZ objects
- By fork
### Typescript interfaces
Lodestar types are all defined as typescript interfaces. These interfaces can be used independently, and are used throughout downstream Lodestar packages (eg: in the beacon node).
Lodestar types are all defined as typescript interfaces. These interfaces can be used independently, and are used throughout downstream Lodestar packages (in the beacon node).
These interfaces are accessible via named exports.
@@ -67,7 +67,7 @@ import {Epoch, ssz} from "@lodestar/types";
const epoch: Epoch = ssz.Epoch.defaultValue();
```
In some cases, we need interfaces that accept types across all forks, eg: when the fork is not known ahead of time. Typescript interfaces for this purpose are exported under the `allForks` namespace. SSZ Types typed to these interfaces are also provided under an `allForks` namespace, but keyed by `ForkName`.
In some cases, we need interfaces that accept types across all forks, like when the fork is not known ahead of time. Typescript interfaces for this purpose are exported under the `allForks` namespace. SSZ Types typed to these interfaces are also provided under an `allForks` namespace, but keyed by `ForkName`.
```typescript
import {ForkName} from "@lodestar/params";

7
scripts/wordlist_sort.sh Executable file
View File

@@ -0,0 +1,7 @@
#!/bin/bash
# Define wordlist file
wordlist=".wordlist.txt"
# Sort the wordlist in place
sort --human-numeric-sort -o "$wordlist" "$wordlist"

23
scripts/wordlist_sort_check.sh Executable file
View File

@@ -0,0 +1,23 @@
#!/bin/bash
# You can sort the wordlist by running:
# ```
# $ scripts/wordlist_sort.sh
# ```
# Define wordlist file
wordlist=".wordlist.txt"
# Check if wordlist is sorted
if ! sort --ignore-case --human-numeric-sort --check "$wordlist"; then
echo "Error: The wordlist is not sorted."
exit 1
fi
# Check for repeated words
if uniq -d "$wordlist" | grep -q .; then
echo "Error: The wordlist contains repeated words."
exit 1
fi
echo "The wordlist is sorted and contains no repeated words."

49
yarn.lock
View File

@@ -3757,6 +3757,11 @@
resolved "https://registry.yarnpkg.com/@types/node/-/node-18.15.11.tgz#b3b790f09cb1696cffcec605de025b088fa4225f"
integrity sha512-E5Kwq2n4SbMzQOn6wnmBjuK9ouqlURrcZDVfbo9ftDDTFt3nk7ZKK4GMOzoYgnpQJKcxwQw+lGaBvvlMo0qN/Q==
"@types/node@^18.16.2":
version "18.16.18"
resolved "https://registry.yarnpkg.com/@types/node/-/node-18.16.18.tgz#85da09bafb66d4bc14f7c899185336d0c1736390"
integrity sha512-/aNaQZD0+iSBAGnvvN2Cx92HqE5sZCPZtx2TsK+4nvV23fFe09jVDvpArXr2j9DnYlzuU9WuoykDDc6wqvpNcw==
"@types/normalize-package-data@^2.4.0":
version "2.4.1"
resolved "https://registry.yarnpkg.com/@types/normalize-package-data/-/normalize-package-data-2.4.1.tgz#d3357479a0fdfdd5907fe67e17e0a85c906e1301"
@@ -6264,6 +6269,11 @@ dashdash@^1.12.0:
dependencies:
assert-plus "^1.0.0"
data-uri-to-buffer@^4.0.0:
version "4.0.1"
resolved "https://registry.yarnpkg.com/data-uri-to-buffer/-/data-uri-to-buffer-4.0.1.tgz#d8feb2b2881e6a4f58c2e08acfd0e2834e26222e"
integrity sha512-0R9ikRb668HB7QDxT1vkpuUBtqc53YyAwMwGeUFKRojY/NWKvdZ+9UYtRfGmhqNbRkTSVpMbmyhXipFFv2cb/A==
datastore-core@^8.0.1:
version "8.0.3"
resolved "https://registry.yarnpkg.com/datastore-core/-/datastore-core-8.0.3.tgz#d14bda75184b03d319c80d94f49ff36b27a619d4"
@@ -7749,6 +7759,14 @@ fecha@^4.2.0:
resolved "https://registry.npmjs.org/fecha/-/fecha-4.2.1.tgz"
integrity sha512-MMMQ0ludy/nBs1/o0zVOiKTpG7qMbonKUzjJgQFEuvq6INZ1OraKPRAWkBq5vlKLOUMpmNYG1JoN3oDPUQ9m3Q==
fetch-blob@^3.1.2, fetch-blob@^3.1.4:
version "3.2.0"
resolved "https://registry.yarnpkg.com/fetch-blob/-/fetch-blob-3.2.0.tgz#f09b8d4bbd45adc6f0c20b7e787e793e309dcce9"
integrity sha512-7yAQpD2UMJzLi1Dqv7qFYnPbaPx7ZfFK6PiIxQ4PfkGPyNyl2Ugx+a/umUonmKqjhM4DnfbMvdX6otXq83soQQ==
dependencies:
node-domexception "^1.0.0"
web-streams-polyfill "^3.0.3"
figures@3.2.0, figures@^3.0.0:
version "3.2.0"
resolved "https://registry.yarnpkg.com/figures/-/figures-3.2.0.tgz#625c18bd293c604dc4a8ddb2febf0c88341746af"
@@ -7986,6 +8004,13 @@ form-data@~2.3.2:
combined-stream "^1.0.6"
mime-types "^2.1.12"
formdata-polyfill@^4.0.10:
version "4.0.10"
resolved "https://registry.yarnpkg.com/formdata-polyfill/-/formdata-polyfill-4.0.10.tgz#24807c31c9d402e002ab3d8c720144ceb8848423"
integrity sha512-buewHzMvYL29jdeQTVILecSaZKnt/RJWjoZCF5OW60Z67/GmSLBkOFM7qh1PI3zFNtJbaZL5eQu1vLfazOwj4g==
dependencies:
fetch-blob "^3.1.2"
formidable@^2.1.2:
version "2.1.2"
resolved "https://registry.yarnpkg.com/formidable/-/formidable-2.1.2.tgz#fa973a2bec150e4ce7cac15589d7a25fc30ebd89"
@@ -11354,6 +11379,11 @@ node-addon-api@^5.0.0:
resolved "https://registry.yarnpkg.com/node-addon-api/-/node-addon-api-5.1.0.tgz#49da1ca055e109a23d537e9de43c09cca21eb762"
integrity sha512-eh0GgfEkpnoWDq+VY8OyvYhFEzBk6jIYbRKdIlyTiAXIVJ8PyBaKb0rp7oDtoddbdoHWhq8wwr+XZ81F1rpNdA==
node-domexception@^1.0.0:
version "1.0.0"
resolved "https://registry.yarnpkg.com/node-domexception/-/node-domexception-1.0.0.tgz#6888db46a1f71c0b76b3f7555016b63fe64766e5"
integrity sha512-/jKZoMpw0F8GRwl4/eLROPA3cfcXtLApP0QzLmUT/HuPCZWyB7IY9ZrMeKw2O/nFIqPQB3PVM9aYm0F312AXDQ==
node-fetch@2.6.7, node-fetch@^2.6.0, node-fetch@^2.6.1, node-fetch@^2.6.7:
version "2.6.7"
resolved "https://registry.npmjs.org/@achingbrain/node-fetch/-/node-fetch-2.6.7.tgz"
@@ -11366,6 +11396,15 @@ node-fetch@^2.6.9:
dependencies:
whatwg-url "^5.0.0"
node-fetch@^3.3.1:
version "3.3.1"
resolved "https://registry.yarnpkg.com/node-fetch/-/node-fetch-3.3.1.tgz#b3eea7b54b3a48020e46f4f88b9c5a7430d20b2e"
integrity sha512-cRVc/kyto/7E5shrWca1Wsea4y6tL9iYJE5FBCius3JQfb/4P4I295PfhgbJQBLTx6lATE4z+wK0rPM4VS2uow==
dependencies:
data-uri-to-buffer "^4.0.0"
fetch-blob "^3.1.4"
formdata-polyfill "^4.0.10"
node-forge@^1.1.0, node-forge@^1.3.1:
version "1.3.1"
resolved "https://registry.yarnpkg.com/node-forge/-/node-forge-1.3.1.tgz#be8da2af243b2417d5f646a770663a92b7e9ded3"
@@ -14984,6 +15023,11 @@ typescript@^5.0.3:
resolved "https://registry.yarnpkg.com/typescript/-/typescript-5.0.3.tgz#fe976f0c826a88d0a382007681cbb2da44afdedf"
integrity sha512-xv8mOEDnigb/tN9PSMTwSEqAnUvkoXMQlicOb0IUVDBSQCgBSaAAROUZYy2IcUy5qU6XajK5jjjO7TMWqBTKZA==
typescript@^5.0.4:
version "5.1.3"
resolved "https://registry.yarnpkg.com/typescript/-/typescript-5.1.3.tgz#8d84219244a6b40b6fb2b33cc1c062f715b9e826"
integrity sha512-XH627E9vkeqhlZFQuL+UsyAXEnibT0kWR2FWONlr4sTjvxyJYnyefgrkyECLzM5NenmKzRAy2rR/OlYLA1HkZw==
ua-parser-js@^0.7.30:
version "0.7.33"
resolved "https://registry.yarnpkg.com/ua-parser-js/-/ua-parser-js-0.7.33.tgz#1d04acb4ccef9293df6f70f2c3d22f3030d8b532"
@@ -15358,6 +15402,11 @@ wcwidth@^1.0.0, wcwidth@^1.0.1:
dependencies:
defaults "^1.0.3"
web-streams-polyfill@^3.0.3:
version "3.2.1"
resolved "https://registry.yarnpkg.com/web-streams-polyfill/-/web-streams-polyfill-3.2.1.tgz#71c2718c52b45fd49dbeee88634b3a60ceab42a6"
integrity sha512-e0MO3wdXWKrLbL0DgGnUV7WHVuw9OUvL4hjgnPkIeEvESk74gAITi5G606JtZPp39cd8HA9VQzCIvA49LpPN5Q==
web3-bzz@1.10.0:
version "1.10.0"
resolved "https://registry.yarnpkg.com/web3-bzz/-/web3-bzz-1.10.0.tgz#ac74bc71cdf294c7080a79091079192f05c5baed"