From fc7242b3ca76af0b6468160af7b3d14b6432ccf6 Mon Sep 17 00:00:00 2001 From: Phil Ngo Date: Fri, 18 Oct 2024 21:30:12 -0400 Subject: [PATCH 01/12] docs update oct 2024 init --- docs/docusaurus.config.ts | 32 +- docs/pages/google0c42298b7ec08b7e.html | 1 - docs/pages/index.md | 20 +- docs/pages/introduction.md | 24 +- .../run/beacon-management/starting-a-node.md | 126 ++-- .../pages/run/getting-started/installation.md | 6 +- .../quick-start-custom-guide.md | 713 ++++++++++++++++++ docs/pages/run/getting-started/quick-start.md | 26 +- .../logging-and-metrics/client-monitoring.md | 2 +- .../run/logging-and-metrics/dashboards.md | 0 .../run/logging-and-metrics/log-management.md | 3 - .../logging-and-metrics/metrics-management.md | 0 .../logging-and-metrics/prometheus-grafana.md | 10 +- .../validator-management/proposer-config.md | 36 + .../validator-management/vc-configuration.md | 4 + docs/pages/trouble-shooting.md | 1 - docs/sidebars.ts | 21 +- packages/light-client/README.md | 2 +- packages/prover/README.md | 2 +- 19 files changed, 897 insertions(+), 132 deletions(-) delete mode 100644 docs/pages/google0c42298b7ec08b7e.html create mode 100644 docs/pages/run/getting-started/quick-start-custom-guide.md delete mode 100644 docs/pages/run/logging-and-metrics/dashboards.md delete mode 100644 docs/pages/run/logging-and-metrics/log-management.md delete mode 100644 docs/pages/run/logging-and-metrics/metrics-management.md create mode 100644 docs/pages/run/validator-management/proposer-config.md delete mode 100644 docs/pages/trouble-shooting.md diff --git a/docs/docusaurus.config.ts b/docs/docusaurus.config.ts index e37cee619e81..3e57867009f8 100644 --- a/docs/docusaurus.config.ts +++ b/docs/docusaurus.config.ts @@ -97,29 +97,23 @@ const config: Config = { style: "dark", links: [ { - title: "Docs", - items: [ - { - label: "Introduction", - to: "/introduction", - }, - ], + label: 'Lodestar Website', + href: 'https://lodestar.chainsafe.io', }, { - title: "Community", - items: [ - { - label: "Discord", - href: "https://discord.com/invite/yjyvFRP", - }, - { - label: "Twitter", - href: "https://twitter.com/lodestar_eth", - }, - ], + label: 'Discord', + href: 'https://discord.com/invite/yjyvFRP', + }, + { + label: 'Twitter/X', + href: 'https://x.com/lodestar_eth', + }, + { + label: 'Github', + href: 'https://github.com/ChainSafe/lodestar', }, ], - copyright: `Copyright © ${new Date().getFullYear()} ChainSafe, Inc.`, + copyright: `Copyright © ${new Date().getFullYear()} ChainSafe. Built with Docusaurus.` , }, colorMode: { respectPrefersColorScheme: false, diff --git a/docs/pages/google0c42298b7ec08b7e.html b/docs/pages/google0c42298b7ec08b7e.html deleted file mode 100644 index 7edebde149af..000000000000 --- a/docs/pages/google0c42298b7ec08b7e.html +++ /dev/null @@ -1 +0,0 @@ -google-site-verification: google0c42298b7ec08b7e.html \ No newline at end of file diff --git a/docs/pages/index.md b/docs/pages/index.md index c74ad6470d7d..2a23047282eb 100644 --- a/docs/pages/index.md +++ b/docs/pages/index.md @@ -4,11 +4,11 @@ title: Home ![lodestar logo](../../assets/lodestar_icon_text_black_stroke.png) -## Welcome to the Lodestar documentation +## Welcome to the Lodestar Documentation > **Lodestar is an open-source Ethereum Consensus client and Typescript ecosystem, maintained by ChainSafe Systems** -### Getting started +### Getting Started - Follow the instructions for [build from source](./run/getting-started/installation#build-from-source), [binaries](./run/getting-started/installation#binaries), or [Docker](./run/getting-started/installation#docker-installation) to install Lodestar. Or use our [Lodestar Quickstart scripts](https://github.com/ChainSafe/lodestar-quickstart). - Use [Lodestar libraries](./supporting-libraries/index.md) in your next Ethereum Typescript project. @@ -26,14 +26,18 @@ Hardware specifications minimum / recommended, to run the Lodestar client. | | Minimum | Recommended | | --------- | -------------------------------------- | -------------------------------------- | | Processor | Intel Core i3–9100 or AMD Ryzen 5 3450 | Intel Core i7–9700 or AMD Ryzen 7 4700 | -| Memory | 16GB RAM | 32GB RAM | -| Storage | 100GB available space SSD | 1TB available space SSD | -| Internet | Broadband connection | Broadband connection | +| Memory | 8 GB RAM | 16 GB RAM | +| Storage | 130 GB available space SSD | 200 GB available space SSD | +| Internet | Reliable broadband with 10mbps upload | Reliable broadband with >10mbps upload | -## About these docs +### Execution Client -This documentation is open source, contribute at [Github Lodestar repository /docs](https://github.com/ChainSafe/lodestar/tree/unstable/docs). +If you run the [execution client](https://ethereum.org/en/developers/docs/nodes-and-clients/#execution-clients) on the same host, you will need to check their requirements and add them to the above requirements. -## Need assistance? +## About These Docs + +This documentation is open source, contribute on our [Github Lodestar repository /docs](https://github.com/ChainSafe/lodestar/tree/unstable/docs). + +## Need Assistance? If you have questions about this documentation, feel free to talk to us on our [ChainSafe Discord](https://discord.gg/yjyvFRP) or [open an issue](https://github.com/ChainSafe/lodestar/issues/new/choose) and a member of the team or our community will be happy to assist you. diff --git a/docs/pages/introduction.md b/docs/pages/introduction.md index ab864b8a9df8..0a11a0acb594 100644 --- a/docs/pages/introduction.md +++ b/docs/pages/introduction.md @@ -1,29 +1,29 @@ # Introduction -Ethereum is one of the most profoundly important inventions in recent history. It is a decentralized, open-source blockchain featuring smart contract functionality. It is the second-largest cryptocurrency by market capitalization, after Bitcoin, and is the most actively used blockchain. Ethereum was proposed in 2013 by programmer Vitalik Buterin. Development was crowdfunded in 2014, and the network went live on 30 July 2015, with 72 million coins premined. ChainSafe was founded not too long afterwards and has been actively working in the Ethereum space ever since. We are proud to develop Lodestar and to present this documentation as a resource for the Ethereum community. +Ethereum is one of the most profoundly important inventions in recent history. It is a decentralized, open-source blockchain featuring smart contract functionality. It is the second-largest cryptocurrency by market capitalization, after Bitcoin, and is the second largest blockchain by market capitalization. Ethereum was proposed in 2013 by programmer Vitalik Buterin. Development was crowdfunded in 2014, and the network went live on 30 July 2015, with 72 million coins premined. ChainSafe was founded not too long afterwards in 2017 and has been actively working in the Ethereum ecosystem ever since. We are proud to develop Lodestar, the only Typescript based consensus client, and to present this documentation as a resource for the Ethereum community. ## Proof of Stake -In Ethereum's Proof of Stake (PoS) model, validators replace miners from the Proof of Work (PoW) system. Validators are Ethereum stakeholders who lock up a portion of their Ether as a stake. The protocol randomly selects these validators to propose new blocks. The chance of being chosen is tied to the size of their stake: the more Ether staked, the higher the probability of being selected to propose the block. Proposers receive transaction fees and block rewards as incentives. Validators are also responsible for voting on the validity of blocks proposed by other validators. However, they face penalties, known as slashing, for actions like double-signing, votes on a block that is not in the majority or going offline, ensuring network integrity and reliability. The PoS mechanism significantly reduces energy consumption compared to PoW, because it does not require extensive computational power. Moreover, PoS tends to facilitate faster transaction validations and block creations, enhancing the overall performance and scalability of the network. +In Ethereum's Proof of Stake (PoS) model, validators replace miners from the Proof of Work (PoW) system. Validators are Ethereum stakeholders who lock up a portion of their Ether as a stake. The protocol randomly selects these validators to propose new blocks. The chance of being chosen is tied to the size of their stake: the more Ether staked, the higher the probability of being selected to propose the block. Proposers receive transaction fees and block rewards as incentives. Validators are also responsible for voting on the validity of blocks proposed by other validators. However, they also face penalties, known as slashing, for actions like signing two different block proposals in the same slot or voting on two different attestations for the same target epoch, which creates conflicting states. The PoS mechanism significantly reduces energy consumption compared to PoW, because it does not require extensive computational power. Moreover, PoS tends to facilitate faster transaction validations and block creations, enhancing the overall performance and scalability of the network. ## Consensus Clients -In an effort to promote client diversity there are several beacon-nodes being developed. Each is programmed in a different language and by a different team. The following is a list of the current beacon-node clients: +In an effort to promote client diversity there are several consensus beacon nodes being developed. Each is programmed in a different language and by a different team. The following is a list of the current open source consensus clients in alphabetical order: -- [Lodestar](https://lodestar.chainsafe.io/) -- [Prysm](https://prysmaticlabs.com/) -- [Lighthouse](https://lighthouse.sigmaprime.io/) -- [Teku](https://consensys.net/knowledge-base/ethereum-2/teku/) -- [Nimbus](https://nimbus.team/) -- [Grandine](https://grandine.io) +- [Grandine (Rust)](https://grandine.io) +- [Lighthouse (Rust)](https://lighthouse.sigmaprime.io/) +- [Lodestar (Typescript)](https://lodestar.chainsafe.io/) +- [Nimbus (Nim)](https://nimbus.team/) +- [Prysm (Golang)](https://prysmaticlabs.com/) +- [Teku (Java)](https://consensys.net/knowledge-base/ethereum-2/teku/) ## Why Client Diversity? -The Ethereum network's robustness is significantly enhanced by its client diversity, whereby multiple, independently-developed clients conforming to a common specification facilitate seamless interaction and function equivalently across nodes. This client variety not only fosters a rich ecosystem but also provides a buffer against network-wide issues stemming from bugs or malicious attacks targeted at particular clients. For instance, during the Shanghai denial-of-service attack in 2016, the diversified client structure enabled the network to withstand the assault, underscoring the resilience afforded by multiple client configurations. +The Ethereum network's robustness is significantly enhanced by its client diversity, whereby multiple, independently-developed clients conforming to a common specification, facilitating seamless interaction and function equivalently across different nodes. This client variety not only fosters a rich ecosystem but also provides a buffer against network-wide issues stemming from bugs or malicious attacks targeted at particular clients. For instance, during the Shanghai denial-of-service attack in 2016, the diversified client structure enabled the network to withstand the assault, underscoring the resilience afforded by multiple client configurations. -On the consensus layer, client distribution is crucial for maintaining network integrity and finality, ensuring transactions are irreversible once validated. A balanced spread of nodes across various clients helps mitigate risks associated with potential bugs or attacks that could, in extreme cases, derail the consensus process or lead to incorrect chain splits, thereby jeopardizing the network's stability and trust. While the data suggests a dominance of Prysm client on the consensus layer, efforts are ongoing to promote a more even distribution among others like Lighthouse, Teku, Nimbus and Grandine. Encouraging the adoption of minority clients, bolstering their documentation, and leveraging real-time client diversity dashboards are among the strategies being employed to enhance client diversity, which in turn fortifies the Ethereum consensus layer against adversities and fosters a healthier decentralized network ecosystem. +On the consensus layer, client distribution is crucial for maintaining network integrity and finality, ensuring transactions are irreversible once validated. A balanced spread of nodes across various clients help to mitigate risks associated with potential bugs or attacks that could, in extreme cases, derail the consensus process (liveness failure) or lead to incorrect chain splits (forking), thereby jeopardizing the network's stability and trust. While the data suggests a [dominance of the Prysm client](https://clientdiversity.org) on the consensus layer, efforts are ongoing to promote a more even distribution among others clients. Encouraging the adoption of minority clients, bolstering their documentation, and leveraging real-time client diversity dashboards are among the strategies being employed to enhance client diversity, which in turn fortifies the Ethereum consensus layer against adversities and fosters a healthier decentralized network. -The non-finality event in May 2023 on the Ethereum network posed a significant challenge. The issue arose from attestations for a fork, which necessitated state replays to validate the attestations, causing a notable strain on system resources. As a result, nodes fell out of sync, which deterred the accurate tracking of the actual head of the chain. This situation was exacerbated by a decline in attestations during specific epochs, further hampering the consensus mechanism. The Lodestar team noticed late attestations several weeks prior to the event and implemented a feature that attempted to address such challenges by not processing untimely attestations, and thus not requiring expensive state replays​. While it was done for slightly different reasons, the result was the same. Lodestar was able to follow the chain correctly and helped to stabilize the network. This example underscored the importance of client diversity and network resilience against potential forks and replay attacks. These are considered realistic threats, especially in the context of system complexity like in Ethereum's consensus mechanism. +The [non-finality event of May 2023](https://medium.com/offchainlabs/post-mortem-report-ethereum-mainnet-finality-05-11-2023-95e271dfd8b2) on the Ethereum network posed a significant challenge. The issue arose from attestations for a fork, which necessitated state replays to validate the attestations, causing a notable strain on system resources. As a result, nodes fell out of sync, which deterred the accurate tracking of the actual head of the chain. This situation was exacerbated by a decline in attestations during specific epochs, further hampering the consensus mechanism from reaching finality. The Lodestar team noticed late attestations several weeks prior to the event and implemented a feature that attempted to address such challenges by not processing untimely attestations, and thus not requiring expensive state replays​. While it was done for slightly different reasons, the result was the same. Lodestar was able to follow the chain correctly and helped to stabilize the network. This example underscored the importance of client diversity and network resilience against potential forks and replay attacks. These are considered realistic threats, especially in the context of system complexity like in Ethereum's consensus mechanism. ## Ethereum Reading List diff --git a/docs/pages/run/beacon-management/starting-a-node.md b/docs/pages/run/beacon-management/starting-a-node.md index 6838e14304d6..28baaeb8fda7 100644 --- a/docs/pages/run/beacon-management/starting-a-node.md +++ b/docs/pages/run/beacon-management/starting-a-node.md @@ -2,15 +2,13 @@ title: Starting a Node --- -# Beacon management +# Beacon Management -The following instructions are required to setup and run a Lodestar beacon node. +Running a Lodestar node on mainnet or a testnet only requires basic familiarity with the terminal. The following instructions are required to configure and run the Lodestar beacon node. This page assumes you have already setup an Ethereum execution client. -## Connect to mainnet or a public testnet +## Connect to Mainnet or a Public Testnet -Running a Lodestar node on mainnet or a testnet only requires basic familiarity with the terminal. - -Make sure Lodestar is installed in your local environment, following the chosen install method. The following command should return a non error message. +Make sure Lodestar is installed in your local environment, following the chosen [Installation](../getting-started/installation.md) method. The following command should return a non-error message. ```bash ./lodestar --help @@ -18,25 +16,21 @@ Make sure Lodestar is installed in your local environment, following the chosen For a complete list of beacon node CLI commands and options, see the [`beacon` CLI Command](../beacon-management/beacon-cli.md) section. -To select a known testnet or mainnet, use the `--network` flag. `mainnet` is selected by default, and a list of available networks is listed with the `--help` flag. Setting the `--network` flag will conveniently configure the beacon node or validator client for the selected network. For power users, any configuration option should be able to be overridden. +To select a known testnet or mainnet, use the `--network` flag. The option `mainnet` is selected by default, and a list of available networks is listed with the `--help` flag. Setting the `--network` flag will conveniently configure the beacon node for the selected network. For power users, any configuration option should be able to be overridden. -## Configure the Lodestar JWT authentication token +## Configure the Lodestar JWT Authentication Token -Post-Merge Ethereum will require [secure authentication with the Engine API](https://github.com/ethereum/execution-apis/blob/main/src/engine/authentication.md) connection on your chosen Execution node. +Ethereum requires a [secure authentication with the Engine API](https://github.com/ethereum/execution-apis/blob/main/src/engine/authentication.md) for connecting to your chosen execution client on port 8551. -:::info -Post-Merge Ethereum **requires** a secure, authenticated connection to the Execution client on port 8551. We recommend setting this up now to ensure a proper configuration before the Merge. -::: - -### Generate a secret key +### Generate a Secret Key You must generate a secret 32-byte (64 characters) hexadecimal string that will be used to authenticate with an execution node. You can use the following command in most terminals to generate a random secret: `openssl rand -hex 32`. Or you can use an [online generator](https://codebeautify.org/generate-random-hexadecimal-numbers). Save this secret key into a text file and note where you store this file. -### Configure Lodestar to locate the JWT secret +### Configure Lodestar to Locate the JWT Secret When starting up a Lodestar beacon node in any configuration, ensure you add the `--jwtSecret $JWT_SECRET_PATH` flag to point to the saved secret key file. -### Ensure JWT is configured with your execution node +### Configure the Execution Client with the JWT Secret **For Go Ethereum:** Use the `--authrpc.jwtsecret /path/to/jwtsecret.hex` flag to configure the secret. Use their documentation [here](https://geth.ethereum.org/docs/getting-started#start-geth). @@ -53,59 +47,68 @@ Use the `--authrpc.jwtsecret /path/to/jwtsecret.hex` flag to configure the secre **For Reth:** Use the `--authrpc.jwtsecret /path/to/jwtsecret.hex` flag to configure the secret. Use their documentation [here](https://reth.rs/run/mainnet.html?highlight=jwt#running-the-reth-node). -## Run a beacon node +## Run the Beacon Node -To start a Lodestar beacon run the command: +To start the Lodestar beacon, run the command: ```bash ./lodestar beacon --network $NETWORK_NAME --jwtSecret $JWT_SECRET_PATH ``` -This will assume an execution-layer client is available at the default -location of `https://localhost:8545`. +This will assume an execution client is available at the default location of `https://localhost:8545`. -In case execution-layer clients are available at different locations, use `--execution.urls` to specify these locations in the command: +If the execution clients are available at different locations, use the flag `--execution.urls` to specify these locations in the command: ```bash ./lodestar beacon --network $NETWORK_NAME --jwtSecret $JWT_SECRET_PATH --execution.urls $EL_URL1 $EL_URL2 ``` -Immediately you should see confirmation that the node has started +Your initial logs should confirm that the node has started. ```txt -Apr-20 15:12:45.274[] info: Lodestar network=mainnet, version=v1.7.2, commit= -Apr-20 15:12:45.327[] info: Connected to LevelDB database path=/data/mt1/chain-db -Apr-20 15:12:57.747[] info: Initializing beacon from a valid db state slot=6264480, epoch=195765, stateRoot=0x8133cd4d0be59c3e94405f902fe0ad68ffaa5013b525dddb6285b91ad79716f6, isWithinWeakSubjectivityPeriod=true -Apr-20 15:13:18.077[network] info: PeerId 16Uiu2HAmDsGet67va6VCnaW2Tu1Ae2yujiDMnmURMMWNvssER7ZQ, Multiaddrs /ip4/127.0.0.1/tcp/9000/p2p/16Uiu2HAmDsGet67va6VCnaW2Tu1Ae2yujiDMnmURMMWNvssER7ZQ,/ip4/10.244.0.199/tcp/9000/p2p/16Uiu2HAmDsGet67va6VCnaW2Tu1Ae2yujiDMnmURMMWNvssER7ZQ -Apr-20 15:13:18.270[rest] info: Started REST API server address=http://127.0.0.1:9596 -Apr-20 15:13:18.271[] warn: Low peer count peers=0 -Apr-20 15:13:18.280[] info: Searching peers - peers: 0 - slot: 6264964 - head: (slot - 484) 0x7ee6…2a15 - exec-block: syncing(17088043 0x9442…) - finalized: 0xe359…4d7e:195763 -Apr-20 15:13:23.009[chain] info: Validated transition configuration with execution client terminalTotalDifficulty=0xc70d808a128d7380000, terminalBlockHash=0x0000000000000000000000000000000000000000000000000000000000000000, terminalBlockNumber=0x0 -Apr-20 15:13:29.287[] info: Syncing - ? left - 0.00 slots/s - slot: 6264965 - head: (slot - 485) 0x7ee6…2a15 - exec-block: syncing(17088043 0x9442…) - finalized: 0xe359…4d7e:195763 - peers: 1 -Apr-20 15:14:41.003[] info: Syncing - 22 seconds left - 4.92 slots/s - slot: 6264971 - head: (slot - 108) 0xd15f…b605 - exec-block: valid(17088414 0x3dba…) - finalized: 0x70fd…5157:195775 - peers: 4 -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 +Jul-31 13:35:27.967[] info: Lodestar network=mainnet, version=v1.21.0/ff35faa, commit=ff35faae4ad1697b86d708a0367a95a71648ab6e +Jul-31 13:35:28.344[] info: Connected to LevelDB database path=/data/lodestar/chain-db +Jul-31 13:35:49.828[] info: Initializing beacon from a valid db state slot=9633504, epoch=301047, stateRoot=0xfa2845a6877b98555906a1654941c97d9c05bdd41e61cc0870a967dc9030b156, isWithinWeakSubjectivityPeriod=true +Jul-31 13:35:51.955[chain] info: Historical state worker started +Jul-31 13:35:51.969[eth1] info: Eth1 provider urls=http://localhost:8551 +Jul-31 13:35:51.975[execution] info: Execution client urls=http://localhost:8551 +Jul-31 13:35:51.977[] info: External builder url=http://localhost:8661 +Jul-31 13:36:21.128[network] info: running libp2p instance in worker thread +Jul-31 13:36:21.727[network] info: libp2p worker started peer=15Uiu2HAmACcmCEXcgt3zCtJL2rqJZ2Mvdjh6U6fe26HgD2FoNRwW +Jul-31 13:36:27.677[network] info: discv5 worker started peerId=16Uiu2HAmACcmCEXcgt3zCtJL2rqJZ2Mvdjh6U6fe26HgD2FoNRwW, initialENR=enr:-IO4QHGTUd1Zg8LAhUAioOz_ySTKoJLIOa6zltSP_AvvhTFVYw6M6YB35IxsiKxQG7nUgCpUB5SIsNxMntCNlTK9sMEBgmlkgnY0iXNlY3AyNTZrMaEC24cdmzuGnWqSwF-8Hw2gbkAZDzMWW3LsHJfp_kDhy-GDdGNwgiMog3VkcIIeWH, bindAddr4=/ip4/0.0.0.0/udp/9000 +Jul-31 13:36:28.134[network] info: PeerId 16Uiu2HAmACcmCEXcgt3zCtJL2rqJZ2Mvdjh6U6fe26HgD2FoNRwW, Multiaddrs /ip4/0.0.0.0/tcp/9000 +Jul-31 13:36:28.137[metrics] info: Started metrics HTTP server address=http://127.0.0.1:8008 +Jul-31 13:36:28.256[rest] info: Started REST API server address=http://0.0.0.0:9596 +Jul-31 13:36:28.257[] info: Searching peers - peers: 0 - slot: 9634080 - head: (slot -576) 0x9d88…d02a - exec-block: syncing(20426302 0xcec4…) - finalized: 0x7feb…c130:301045 +Jul-31 13:36:36.461[execution] info: Execution client is synced oldState=ONLINE, newState=SYNCED +Jul-31 13:36:53.019[] info: Syncing - 3.7 minutes left - 2.32 slots/s - slot: 9634082 - head: (slot -515) 0x792f…f8aa - exec-block: valid(20426365 0x58b1…) - finalized: 0x9d88…d02a:301047 - peers: 11 +Jul-31 13:38:53.168[] info: Syncing - 11 seconds left - 4.01 slots/s - slot: 9634092 - head: (slot -44) 0x7491…f63e - exec-block: valid(20426841 0xd4b2…) - finalized: 0x1e00…6e6b:301062 - peers: 59 +Jul-31 13:38:58.051[network] info: Subscribed gossip core topics +Jul-31 13:38:58.132[sync] info: Subscribed gossip core topics +Jul-31 13:39:05.001[] info: Synced - slot: 9634093 - head: 0x35de…1f0e - exec-block: valid(20426886 0x10ff…) - finalized: 0x88f8…5375:301063 - peers: 70 +Jul-31 13:39:17.000[] info: Synced - slot: 9634094 - head: 0x7844…3b3e - exec-block: valid(20426887 0x67d1…) - finalized: 0x88f8…5375:301063 - peers: 69 +Jul-31 13:39:29.000[] info: Synced - slot: 9634095 - head: 0x5516…ba12 - exec-block: valid(20426888 0x4ceb…) - finalized: 0x88f8…5375:301063 - peers: 74 ``` :::info -If your node is stuck with `Searching for peers` review your network configuration to make sure your ports are open. +If your node is stuck with `Searching peers`, review your network configuration to make sure your ports are open and forwarded to your host machine. ::: By default, Lodestar stores all configuration and chain data at the path `$XDG_DATA_HOME/lodestar/$NETWORK_NAME`. -A young testnet should take a few hours to sync. If you see multiple or consistent errors in the logs, please open a [Github issue](https://github.com/ChainSafe/lodestar/issues/new/choose) or reach out to us in [Discord](https://discord.gg/yjyvFRP). Just by reporting anomalies you are helping accelerate the progress of Ethereum Consensus, thanks for contributing! +A young testnet should take a few hours to sync. If you see multiple or consistent errors in the logs, please open a [Github issue](https://github.com/ChainSafe/lodestar/issues/new/choose) or reach out to us in [Discord](https://discord.gg/yjyvFRP). By reporting anomalies, you are helping to accelerate the progress of Ethereum consensus and we thank you for contributing! :::warning -It is dangerous to expose your Beacon APIs publicly as there is no default authentication mechanism provided. Ensure your beacon node host is not exposing ports 8545 or 9596 outside of your internal network. +It is dangerous to expose your Beacon or Execution APIs publicly as there is no default authentication mechanism provided. Ensure your beacon node host is not exposing ports 8545 or 9596 outside of your internal network. ::: ### Checkpoint Sync -If you are starting your node from a blank db, like starting from genesis, or from the last saved state in db and the network is now far ahead, your node will be susceptible to "long range attacks." Ethereum's solution to this is via something called weak subjectivity. [Read Vitalik's illuminating post explaining weak subjectivity.](https://blog.ethereum.org/2014/11/25/proof-stake-learned-love-weak-subjectivity/). +If you are starting your node from a blank database, or from a last saved database state that is too old (outside of the weak subjectivity period), your node will be susceptible to "long range attacks." Ethereum's solution to this attack is via something called weak subjectivity. [Read Vitalik's illuminating post explaining weak subjectivity.](https://blog.ethereum.org/2014/11/25/proof-stake-learned-love-weak-subjectivity/). -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! +If you have a synced beacon node available (e.g., your friend's node or a trusted infrastructure provider) to serve a trusted checkpoint you can rely on, you can start syncing your beacon node from that available checkpoint with the flag `--checkpointSyncUrl` and passing in the URL of the checkpoint provider. This will allow your beacon node to sync within minutes rather than several days. + +The Ethereum community has maintained a set of [public beacon chain checkpoints](https://eth-clients.github.io/checkpoint-sync-endpoints/) that serve these sync endpoints to the larger community. You can correlate the state root and the block root with more than one provider to verify the checkpoints being served follow the same canonical chain. Just supply these **extra arguments** to your beacon node command: @@ -113,28 +116,27 @@ Just supply these **extra arguments** to your beacon node command: --checkpointSyncUrl [--wssCheckpoint ] ``` -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 the `--checkpointSyncUrl` provider, 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. :::warning -Please use this option very carefully (and at your own risk), a malicious server URL can put you on the wrong chain with a danger of you losing your funds by social engineering. -If possible, validate your `wssCheckpoint` from multiple places (e.g. different client distributions) or from other trusted sources. This will highly reduce the risk of starting off on a malicious chain. -This list of [public endpoints](https://eth-clients.github.io/checkpoint-sync-endpoints/) maintained by the Ethereum community may be used for reference. +Please be aware that a malicious checkpoint sync server URL can put you on the wrong chain with a danger of you losing your funds by social engineering. +If possible, validate your `wssCheckpoint` state from multiple places (e.g. different client distributions) or from other trusted sources. This will highly reduce the risk of starting off on a malicious chain. This list of [public endpoints](https://eth-clients.github.io/checkpoint-sync-endpoints/) maintained by the Ethereum community may be used for reference. ::: -**Taking too long to sync?** +#### Still Taking Long to Sync? -After your node has been offline for a while, it might be the case that it takes a long time to sync even though a `checkpointSyncUrl` is specified. -This is due to the fact that the last db state is still within the weak subjectivity period (~15 days on mainnet) which causes the node -to sync from the db state instead of the checkpoint state. +After your node has been offline for a while, it might be the case that it takes a long time to sync even though a `--checkpointSyncUrl` is specified. +This is due to the fact that the last databse state is still within the weak subjectivity period (~15 days on mainnet) which causes the node +to sync from the database state instead of the checkpoint state. -It is possible to force syncing from checkpoint state by supplying the `--forceCheckpointSync` flag. This option is only recommended if it is absolutely +It is possible to force syncing from a checkpoint state by supplying the `--forceCheckpointSync` flag. This option is only recommended if it is absolutely necessary for the node to be synced right away to fulfill its duties as there is an inherent risk each time the state is obtained from an external source. -### Guide to the sync logs +### Sync Log Guide -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: +The Lodestar beacon syncronization log aims to provide information of utmost importance about the state of your node and 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]` +`[Sync status] - [ Slot info ] - [Head info] - [Execution block info] - [Finalized info] - [Peers info]` See the following example of different kinds of sync log: @@ -171,16 +173,20 @@ Apr-20 15:16:05.000[] info: Synced - slot: 6264978 - head: 0xc9f 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. +1. Sync status: This status takes three values: + +- `Synced`: The node is currently synced +- `Syncing` The node is currently in the syncing process +- `Searching`: The 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 +2. Slot (clock) info: 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 independently shows the head slot else it show how far behind from the Slot it is if difference < 1000. +3. Head info: Specifies where the local beacon chain head hash is. In case it's far behind the Slot (clock), then it independently shows the head slot. Else, it will show how far behind the node is from the Slot (if the difference is < 1000) -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. +4. Execution block info: Provides the information about the execution block head, whether its confirmed `valid` or still `syncing` to it. In parenthesis, it shows the current execution block number and a short hash for 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` +5. Finalized info: Shows the current local `finalized` checkpoint in the format of `[checkpoint root]:[checkpoint epoch]`. For example: `0xd7ba…8386:189636` shows a checkpoint root of `0xd7ba…8386` in epoch `189636` -6. Peer info: Current total number of outbound or inbound peers, for e.g.: `peers: 27` +6. Peer info: Current total number of outbound and inbound peers -For more insight into how a Lodestar beacon node is functioning, you may setup lodestar metrics and use the prepared Grafana dashboards that are found in the repository. Check out our section on [Prometheus and Grafana](../logging-and-metrics/prometheus-grafana.md) for more details. +For more insight into how a Lodestar beacon node is functioning, you may setup Lodestar metrics with the `--metrics` flag and use the prepared Grafana dashboards that are found in the repository. Check out our section on [Prometheus and Grafana](../logging-and-metrics/prometheus-grafana.md) for more details. diff --git a/docs/pages/run/getting-started/installation.md b/docs/pages/run/getting-started/installation.md index 52cb2770725b..40c4865f7726 100644 --- a/docs/pages/run/getting-started/installation.md +++ b/docs/pages/run/getting-started/installation.md @@ -1,8 +1,8 @@ -# Installation +# Install Options ## Binaries -Binaries can be downloaded from [the release page](https://github.com/ChainSafe/lodestar/releases/latest) under the `Assets` section. +Binaries can be downloaded from the Lodestar [release page](https://github.com/ChainSafe/lodestar/releases/latest) under the `Assets` section. ## Docker Installation @@ -100,5 +100,5 @@ pip3 install setuptools --force-reinstall --user ## Install from NPM [not recommended] :::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. +For mainnet (production) usage, we only recommend installing with Docker, using binaries or building from source 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. ::: diff --git a/docs/pages/run/getting-started/quick-start-custom-guide.md b/docs/pages/run/getting-started/quick-start-custom-guide.md new file mode 100644 index 000000000000..54cecdf18a16 --- /dev/null +++ b/docs/pages/run/getting-started/quick-start-custom-guide.md @@ -0,0 +1,713 @@ +# Quickstart Custom Setup Guide + +This is a step-by-step guide to utilize [@ChainSafe/lodestar-quickstart](https://github.com/ChainSafe/lodestar-quickstart) to setup a Ubuntu-based full Ethereum node using a local execution client and ChainSafe's Lodestar consensus client via Docker (the recommended method to use Lodestar for production environments). This is an adaptation of [Somer Esat's guides](https://someresat.medium.com/) for the Ethereum staking community. + +This guide will provide instructions which include running a local execution node. This guide uses Lodestar's `stable` release branch and supports **Holesky** testnet setups and **Mainnet**. + +:::info +This guide specifically focuses on using Lodestar's Quickstart scripts which allows for near instantanious setup with the following technologies: + +- [Ubuntu v22.04 (LTS) x64 server](https://releases.ubuntu.com/22.04/) +- Ethereum Execution (eth1) clients: + - [Erigon](https://github.com/ledgerwatch/erigon/releases) | [Github](https://github.com/ledgerwatch/erigon) + - [Go-Ethereum (Geth)](https://geth.ethereum.org/) | [Github](https://github.com/ethereum/go-ethereum/releases/) + - [Hyperledger Besu](https://www.hyperledger.org/) | [Github](https://github.com/hyperledger/besu) + - [Nethermind](https://nethermind.io/) | [Github](https://github.com/NethermindEth/nethermind) + - [Rust](https://reth.rs) | [Github](https://github.com/paradigmxyz/reth) +- [ChainSafe's Lodestar Ethereum Consensus Client](https://lodestar.chainsafe.io/) | [Github](https://github.com/ChainSafe/lodestar) +- [Docker Engine](https://docs.docker.com/engine/) + ::: + +:::danger +This guide **_does not_** assist with securing your server such as secure SSH logins or enabling firewalls. Ensure you have limited access to your server and blocked unused ports with guides such as [CoinCashew's Security Best Practices for your ETH staking validator node](https://www.coincashew.com/coins/overview-eth/guide-or-how-to-setup-a-validator-on-eth2-mainnet/part-i-installation/guide-or-security-best-practices-for-a-eth2-validator-beaconchain-node) before continuing with this guide. +::: + +:::warning +This guide is for informational purposes only and does not constitute professional advice. The author does not guarantee accuracy of the information in this article and the author is not responsible for any damages or losses incurred by following this article. A full disclaimer can be found at the bottom of this page — please read before continuing. +::: + +## Support + +For technical support please reach out to: + +- The Lodestar team actively develops and collaborates on the [ChainSafe Discord Server](https://discord.gg/642wB3XC3Q) under **_#:star2:-lodestar-general_** channel. +- Please subscribe to our Discord server announcements on the [ChainSafe Discord Server](https://discord.gg/642wB3XC3Q) under **_#lodestar-announcements_** channel. + +## Prerequisites + +This guide assumes knowledge of Ethereum (ETH), Docker, staking and Linux. + +You require the following before getting started: + +- [Ubuntu Server v22.04 (LTS) amd64](https://releases.ubuntu.com/22.04/) or newer, installed and running on a local machine or in the cloud. _A locally running machine is encouraged for greater decentralization — if the cloud provider goes down then all nodes hosted with that provider go down._ + +- 32 ETH to run a solo validator with Lodestar. If running on testnet, contact us in our [ChainSafe Discord Server](https://discord.gg/642wB3XC3Q) for testnet Ether. + +## Testnet to Mainnet + +If moving from a testnet setup to a mainnet setup it is strongly recommended that you start on a fresh (newly installed) server instance. This guide has not been tested for migration scenarios and does not guarantee success if you are using an existing instance with previously installed testnet software. + +## Hardware Requirements + +| | Minimum | Recommended | +| --------- | -------------------------------------- | -------------------------------------- | +| Processor | Intel Core i3–9100 or AMD Ryzen 5 3450 | Intel Core i7–9700 or AMD Ryzen 7 4700 | +| Memory | 8 GB RAM | 16 GB RAM | +| Storage | 130 GB available space SSD | 200 GB available space SSD | +| Internet | Reliable broadband with 10mbps upload | Reliable broadband with >10mbps upload | + +:::info +Check your available disk space. Even you have a large SSD there are cases where Ubuntu is reporting only 100GB free. If this applies to you then take a look at [**_Appendix A — Expanding the Logical Volume._**](#appendix-a---expanding-the-logical-volume) +::: + +--- + +## Setup Machine & Repository + +### Install Docker Engine & Docker Compose + +We must install Docker Engine to run the images on your local machine. + +#### Add Docker's GPG Keyrings + +Run each line one at a time. + +```bash= +sudo apt-get update +sudo apt-get install ca-certificates curl gnupg +sudo install -m 0755 -d /etc/apt/keyrings +curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg +sudo chmod a+r /etc/apt/keyrings/docker.gpg +``` + +#### Add the repository to Apt sources + +Copy and paste the entire command below. + +```bash +echo \ + "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \ + $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \ + sudo tee /etc/apt/sources.list.d/docker.list > /dev/null +``` + +#### Update Ubuntu + +Ensure all updates to your Ubuntu Server are complete. + +```bash= +sudo apt-get update +sudo apt-get upgrade -y +``` + +Hit `Enter` if required to restart services. + +#### Install Docker Engine + +```bash +sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin +``` + +#### Test Docker + +```bash +sudo docker run hello-world +``` + +If you see the message `Hello from Docker! +This message shows that your installation appears to be working correctly.`, you can move on to the next step. + +#### Clone lodestar-quickstart repository + +Clone the [lodestar-quickstart](https://github.com/ChainSafe/lodestar-quickstart) from Github into your local server. + +```bash +cd ~ && git clone https://github.com/ChainSafe/lodestar-quickstart.git +``` + +## Configure Lodestar Quick Scripts + +### Navigate to the root directory + +The script and required files are located within the `lodestar-quickstart` folder. + +``` +cd lodestar-quickstart +``` + +### Create your own JWT Secret + +We will generate a JWT secret that is shared by the Execution client and Lodestar in order to have a required secure connection for the `Engine API` on port `8551`. + +``` +openssl rand -hex 32 | tr -d "\n" > "jwtsecret" +``` + +Confirm that your JWT token created. + +``` +cat jwtsecret ; echo +``` + +Your terminal should display the secret. Copy the token for the next step. Be careful to only copy the 64 characters corresponding to the secret and nothing else. + +:::danger +:rotating_light: **WARNING:** Do not share this secret as it protects your authenticated port 8551. +::: + +### Input your JWT Secret into the `import-args.sh` script + +Edit the `import-args.sh` file. + +```sh +nano import-args.sh +``` + +Replace the 64 characters after `0x` with your token. + +If you are not running validators, press `CTRL` + `x` then `y` then `Enter` to save and exit. Proceed to Configuring your Network. + +### Configure feeRecipient + +Optional: If you are running validators, you **must** set this to receive rewards. If you are not running validators, you can skip this section. + +If you are running validators, Ethereum requires validators to set a **Fee Recipient** which allows you to receive priority fees and MEV rewards when proposing blocks. If you do not set this address, your rewards will be sent to the [burn address by default](https://etherscan.io/address/0x0000000000000000000000000000000000000000). + +Configure your validator client's feeRecipient address by changing the `FEE_RECIPIENT` line. Ensure you specify an Ethereum address you control. + +An example of a fee recipient set with the address `0xB7576e9d314Df41EC5506494293Afb1bd5D3f65d`, you would change the configuration to: + +``` +FEE_RECIPIENT="0xB7576e9d314Df41EC5506494293Afb1bd5D3f65d" +``` + +If you would like to run [MEV-Boost](https://boost.flashbots.net) with your validators, proceed to the next section. + +If you do not want to run MEV-Boost, press `CTRL` + `x` then `y` then `Enter` to save and exit. Proceed to Configuring your Network. + +### Set minimum bid for MEV-Boost validators + +:::info +(Optional): If you are running validators and would like to use MEV-Boost, follow this section. Otherwise, skip this section. +::: + +Validators running MEV-Boost maximize their staking reward by selling blockspace to an open market of builders. MEV-Boost v1.4+ allows you to set a minimum bid threshold to only use an externally built block if it meets or exceeds this parameter. For more information, see + +The `min-bid` parameter is denominated in ETH. For example, if you want to set your threshold to 0.03 ETH, set your configuration to `MIN_BUILDERBID=0.03` + +When complete, press `CTRL` + `x` then `y` then `Enter` to save and exit. + +### Configuring your Network + +When using the quick scripts, each supported network has a `.vars` file to define the parameters required for configuring the clients to the specified network. + +To view the available files, use the command: + +``` +ls *.vars +``` + +### Select your Network + +Each network has specifics variables that you may want to setup for use. We will use `Holesky` to demonstrate connecting to a public testnet. + +Open the `holesky.vars` file. + +```bash +nano holesky.vars +``` + +### Configure MEV-boost relays + +:::info +(Optional): If you have validators you intend to use for MEV-boost, you can input the relays you want to connect here. Otherwise, skip this section. +::: + +You can list multiple relays simply by pasting the relay URL as a variable in this file. + +```shell= +RELAY_A=https://0xRelayPubKey@relay.com +RELAY_B=https://0xRelayPubKey@relay2.com +``` + +Make sure to identify the ones you want to use by editing the line: + +```shell= +RELAYS="$RELAY_A,$RELAY_B" +``` + +### Configure Lodestar version + +The lodestar-quickstart scripts currently defaults to using our `stable` release branch. To use our nightly `unstable` release instead, replace `LODESTAR_IMAGE=chainsafe/lodestar:latest` with `LODESTAR_IMAGE=chainsafe/lodestar:next` in the `import-images.sh` file. + +You may also choose to use a specific version release of Lodestar. To select a specific version, replace the image with `LODESTAR_IMAGE=chainsafe/lodestar:v1.x.x` + +:::warning +:warning: We do not recommend using the `unstable` branch or `@chainsafe/lodestar:next` docker versions of Lodestar for production related tasks. +::: + +### Modify your weak subjectivity (checkpoint sync) provider + +:::info +(Optional): We use ChainSafe's Lodestar checkpoints by default. You may choose to point your trusted checkpoint at another source or verify the checkpoints with other providers. If you would rather sync from genesis, you can skip this step. +::: + +Weak subjectivity (checkpoint sync) allows your beacon node to sync within minutes by utilizing a trusted checkpoint from a trusted provider. + +**We highly recommend using this feature** so you do not need to wait days to sync from genesis and will mitigate your susceptibility to [long-range attacks](https://blog.ethereum.org/2014/11/25/proof-stake-learned-love-weak-subjectivity/). + +Minimize your risk of syncing a malicious chain from a malicious checkpoint by verifying the trusted checkpoint from multiple sources. + +1. View the community maintained list of [Beacon Chain checkpoint sync endpoints](https://eth-clients.github.io/checkpoint-sync-endpoints/) +2. Verify multiple endpoint links and ensure the latest finalized and latest justified block roots are the same +3. Choose one of those endpoint URLs +4. Replace the `--checkpointSyncUrl` address with your chosen provider. + +:::info +**NOTE**: Ensure you use checkpoint URLs from the list above corresponding to the network you are trying to sync or you **will** receive errors. +::: + +When complete, press `CTRL` + `x` then `y` then `Enter` to save and exit. + +## Modify other client parameters (For advanced users) + +:::info +(Optional): We have already set fixed parameters for a seamless setup. If you are looking to customize the default parameters of the clients you are using, follow this section. Otherwise, skip this section. +::: + +Fixed parameters for clients can be modified under the `fixed.vars` configuration file. + +Under the selected client, modify or add the custom arguments on their corresponding line. + +:::note +The following are links to client documentation for CLI commands: + +- [**Lodestar CLI Commands**](https://chainsafe.github.io/lodestar/reference/cli/) +- [**Nethermind CLI Commands**](https://docs.nethermind.io/fundamentals/configuration#command-line-options) +- [**Besu CLI Commands**](https://besu.hyperledger.org/en/stable/Reference/CLI/CLI-Syntax/) +- [**Go Ethereum CLI commands**](https://geth.ethereum.org/docs/interface/command-line-options) +- [**Erigon CLI commands**](https://github.com/ledgerwatch/erigon#beacon-chain) +- [**Reth CLI commands**](https://reth.rs/cli/reth.html) + ::: + +Once complete, press `CTRL` + `x` then `y` then `Enter` to save and exit. + +--- + +## Setup Validators + +:::info +Optional: Skip this entire section if you do not intend to run validators. +::: + +### Create validator keystore password + +Make sure you are in your main quickstart directory. Create the `pass.txt` file containing your validator's decryption password for use. + +``` +cd ~/lodestar-quickstart +``` + +``` +nano pass.txt +``` + +Enter the password for your validators. + +:::info +Once the validator container is running, you can delete this file from your server. Note that every time you restart this container, you will need this password to decrypt your keystore.json files. +::: + +Once complete, press `CTRL` + `x` then `y` then `Enter` to save and exit. + +### Option 1: Setup validators with keystores + +If you want to setup validators with your `keystores.json` files follow this section. Otherwise, skip this step. + +#### Copy/Move keystores to `lodestar-quickstart/keystores` directory + +Your `keystore.json` file(s) generated from the [`staking-deposit-cli`](https://github.com/ethereum/staking-deposit-cli) or similar generator for validator keys will be placed in the `lodestar-quickstart/keystores` directory using the `cp` command to copy or `mv` command to move the files. + +``` +mkdir keystores +``` + +:::info +You may choose to use your own method (e.g. SFTP) for copying/uploading keys to your server. This is only a guide. +::: + +The format of the command to use is below: + +``` +cp +``` + +An example usage of this command is: + +``` +cp /home/user/validator_keys/keystore-x.json ~/lodestar-quickstart/keystores +``` + +Ensure your `keystore.json` files are in the `lodestar-quickstart/keystores` directory using `ls` command. + +``` +ls -lsah ~/lodestar-quickstart/keystores/ +``` + +You should see the keystore files within the directory. + +:::info +Ensure the `/keystores` directory only has the `keystore-m_xxxxx.json` files and nothing else. If you copied in the `deposit_data-xxxxx.json` files, you can remove them by using the `sudo rm ` command. + +Example: + +``` +sudo rm deposit_data-1552658472.json +``` + +::: + +Continue to the [**Startup Quickstart Script**](#Startup-Quickstart-Script) section. + +### Option 2: Setup multiple validator sets with keystores encrypted under different passwords + +Optional: If you want to setup validators with your `keystores.json` files but they are not encrypted with the same password, follow this section. Otherwise, skip this step. + +This option will allow you to run multiple validator clients corresponding to each validator keystore set encrypted with the same password. Therefore, we will setup `validatorset1` with one decryption password and `validatorset2` with another decryption password. You can repeat these steps to create subsequent validator sets with different keystore decryption passwords. + +#### Create validator keystore set directory + +Ensure you are in the `lodestar-quickstart` directory and create a folder for your first validator keystore set. + +``` +cd ~/lodestar-quickstart +``` + +Make the new directory for set one. + +``` +mkdir validatorset1 +``` + +Navigate into the directory. + +``` +cd validatorset1 +``` + +### Create validator keystore password + +Create the `pass.txt` file containing your validator's decryption password for use. + +``` +nano pass.txt +``` + +Enter the password for your validators. + +:::info +Once the validator container is running, you can delete this file from your server. Note that every time you restart this container, you will need this password to decrypt your keystore.json files. +::: + +Once complete, press `CTRL` + `x` then `y` then `Enter` to save and exit. + +### Copy/Move keystores to `lodestar-quickstart/validatorset1/keystores` directory + +Your `keystore.json` file(s) generated from the [`staking-deposit-cli`](https://github.com/ethereum/staking-deposit-cli) or similar generator for validator keys will be placed in the `lodestar-quickstart/validatorset1/keystores` directory using the `sudo cp` command to copy or `sudo mv` command to move the files. + +``` +mkdir keystores +``` + +The format of the command to use is below: + +``` +cp +``` + +An example usage of this command is: + +``` +cp /home/user/validator_keys/keystore-x.json ~/lodestar-quickstart/validatorset1/keystores +``` + +Ensure your `keystore.json` files are in the `lodestar-quickstart/validatorset1/keystores` directory using `ls` command. + +``` +ls -lsah ~/lodestar-quickstart/validatorset1/keystores/ +``` + +You should see the keystore files within the directory. + +:::info +Ensure the `/keystores` directory only has the `keystore-m_xxxxx.json` files and nothing else. If you copied in the `deposit_data-xxxxx.json` files, you can remove them by using the `sudo rm ` command. + +Example: + +``` +sudo rm deposit_data-1552658472.json +``` + +::: + +Repeat the same steps above for `validatorset2` and any subsequent sets of validators you require. When complete you should have a similar looking directory tree such as the one below: + +Then, continue to the [**Startup Quickstart Script**](#Startup-Quickstart-Script) section. Pay particular attention to startup script example five (5) and (6). + +### Option 3: Setup validators with mnemonic + +:::warning +:warning: **TESTNET USE ONLY:** Do not use this method unless you're validating on a testnet. Your mnemonic will be stored in plaintext on your server. +::: + +Optional: If you want to setup validators with your mnemonic. Otherwise, skip this step. + +#### Setup Mnemonic + +Select the `.vars` file corresponding to the network you want to run. For Holesky, select `holesky.vars`. Open the file with the `nano` text editor and edit the configuration: + +``` +nano holesky.vars +``` + +We will modify the `LODESTAR_VALIDATOR_MNEMONIC_ARGS=`. Specifically, the mnemonic located after the `--fromMnemonic` flag. + +- Replace the default mnemonic with your mnemonic. Ensure it is between the quotations + +- Indicate which indexes of the mnemonic you wish Lodestar to run. Specify a specific index number `--mnemonicIndexes 0` or a range of numbers `--mnemonicIndexes 0..5` + +:::info +If you created your mnemonic with one key, it is likely located in index 0. If you've added to it, the generated keys are likely the subsequent indexes. + +Therefore, if you generated one key, it is likely in index 0, so you would use `--mnemonicIndexes 0`. If you generated five keys, it is likely in index 0 to 4, so you would use `--mnemonicIndexes 0..4` +::: + +Once complete, press `CTRL` + `x` then `y` then `Enter` to save and exit. + +Continue to the [**Startup Quickstart Script**](#Startup-Quickstart-Script) section. + +--- + +## Startup Quickstart Script + +Ensure you are in the `~/lodestar-quickstart folder. + +``` +cd ~/lodestar-quickstart +``` + +The following are **_example commands_** as a template for initiating the quickstart script: + +1. Startup a Sepolia beacon node with no validators and Go Ethereum (Geth) execution client with terminals attached: + +``` +./setup.sh --dataDir sepolia-data --elClient geth --network sepolia --dockerWithSudo --withTerminal "gnome-terminal --disable-factory --" +``` + +2. Startup Mainnet beacon node with no validators and Nethermind execution client detached from containers (Recommended only when you've verified the setup has initiated properly with terminals attached): + +``` +./setup.sh --dataDir mainnet-data --elClient nethermind --network mainnet --dockerWithSudo --detached +``` + +3. Startup Holesky beacon node with validator client (using mnemonic in /keystores) and Erigon execution client detached from containers: + +``` +./setup.sh --dataDir holesky-data --elClient erigon --network holesky --dockerWithSudo --detached --withValidatorMnemonic ~/lodestar-quickstart/ +``` + +4. Startup Mainnet beacon node with validator client (using keystores) with MEV-Boost and Hyperledger Besu execution client detached from containers: + +``` +./setup.sh --dataDir mainnet-data --elClient besu --network mainnet --dockerWithSudo --detached --withValidatorKeystore ~/lodestar-quickstart/ --withMevBoost +``` + +5. Startup Holesky beacon node with validator client set one (using keystores) and execution client Geth detached from containers: + +``` +./setup.sh --dataDir holesky-data --elClient geth --network holesky --dockerWithSudo --detached --withValidatorKeystore ~/lodestar-quickstart/validatorset1 +``` + +:::warning +**NOTE:** You can only start up one set of validator keystores per validator client on the same command. Use the below command (#6) to startup another validator client for another set of validator keys. +::: + +6. Startup validator client only with validator client set two (using keystores) and execution client Geth detached from containers: + +``` +./setup.sh --dataDir holesky-data --elClient geth --network holesky --dockerWithSudo --detached --withValidatorKeystore ~/lodestar-quickstart/validatorset2 --justVC +``` + +:::info +**NOTE:** You may wish to start only the execution node first for syncing to reduce Lodestar's execution client (eth1) requests for data that doesn't exist yet and reduce warnings/errors. Be sure to use our flags below such as `--justEL` to start the execution client standalone. + +**NOTE:** The script will standardize naming your containers so running the `setup.sh` twice, will not create two instances of the same containers. The script will standardize naming your containers so running the `./setup.sh ` a second time, will not create two instances of the same containers. +::: + +Configure the above commands with what you intend to run using the Quickstart Script Help table below. + +# Quickstart Script Help + +| Command | Required/Optional | Description | +| ------------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `dataDir` | Required | File location (volume) of the configuration & data for setup. This directory should be non-existent for the first run. If the directory exists, it will skip fetching the configuration, assuming it has been done previously. You can also clean individual directors of CL/EL between the re-runs. | +| `elClient` | Required | The selected EL client you want to run with Lodestar. Options are `nethermind`, `besu`, `erigon` or `geth`. | +| `network` | Required | The network/chain you want to load, reads the corresponding `.vars` (for e.g. `holesky.vars`) network configuration , like images, or urls for EL/CL to interact. Example: Default for Holesky is `--network holesky` using `holesky.vars`. | +| `dockerWithSudo` | Optional | Provide this argument if your Docker needs a `sudo` prefix. | +| `--withTerminal` | Optional\* | Provide the terminal command prefix for CL and EL processes to run in your favourite terminal. You may use an alias or a terminal launching script as long as it waits for the command it runs till ends and then closes. If not provided, it will launch the docker processes in in-terminal mode. | +| `--detached` | Optional\* | By default the script will wait for processes and use user input (ctrl +c) to end the processes, however you can pass this option to skip this behavior and just return, for e.g. in case you just want to leave it running. | +| `--withValidatorKeystore` | Optional\*\* | Launch a validator client using `LODESTAR_VALIDATOR_MNEMONIC_ARGS` (`--withValidatorMnemonic`) or using a folder (`--withValidatorKeystore --justVC` connecting to same beacon node. | +| `--withValidatorMnemonic` | Optional\*\* | Launch a validator client using mnemonic method.(`LODESTAR_VALIDATOR_MNEMONIC_ARGS`) as set in the network vars file. | +| `--withMevBoost` | Optional | Launch a MEV-Boost container to interface with multiple relays picked for the corresponding network vars file. When paired with `--justCL` or `--justVC` this only activates the builder args in the beacon/validator and use the builder url set in MEVBOOST_URL variable in fixed.vars | +| `--justEL` | Optional | Launch only the Execution Layer client. | +| `--justCL` | Optional | Launch only the Lodestar beacon node. | +| `--justVC` | Optional | Launch only the Lodestar validator. | +| `--skipImagePull` | Optional | Launch with only the local Docker images. Do not update them on this run. | + +:::info +**NOTE:** +`*` : Only one of the two options should be provided. +`**` : Only one of the two options should be provided. +::: + +## Check Containers + +You can check the status and get the name of your containers by using the `docker ps` command: + +``` +sudo docker ps +``` + +The containers should not constantly restart. If they restart, likely a misconfiguration occurred. + +## Check Container Logs + +You can check the status of what your container is logging to diagnose a problem or follow along the status of your container output. + +Check the logs by using the `docker logs` command: + +``` +sudo docker logs +``` + +Follow along the logs by adding the `-f` flag: + +``` +sudo docker logs -f +``` + +Limit the fetched logs by indicating the latest container out puts by number of lines using the `-n ` flag. For the last 10 lines: + +``` +sudo docker logs -n 10 +``` + +### Check beacon node is progressing + +Your beacon node should initialize and you should see something similar to: + +``` +Jul-12 00:13:35.912[] info: Lodestar network=goerli, version=v0.40.0-dev.2b16141fc6, commit=2b16141fc6d73e570d338da5d3448c67373405cb +Jul-12 00:13:35.935[] info: Connected to LevelDB database name=/data/lodestar/peerstore +Jul-12 00:13:35.948[DB] info: Connected to LevelDB database name=/data/lodestar/chain-db +Jul-12 00:13:40.076[] info: Initializing beacon state from anchor state slot=0, epoch=0, stateRoot=0x75b3f63942f47f1b17a1ca4a61bf5ca37ffb5e2a9ef9129f9c80cc13d6c67f03 +Jul-12 00:13:40.382[ETH1] info: Starting search for terminal POW block TERMINAL_TOTAL_DIFFICULTY=50000000000000000 +Jul-12 00:13:43.499[METRICS] info: Starting metrics HTTP server port=8008, address=127.0.0.1 +Jul-12 00:13:43.588[API] info: Started REST api server address=http://0.0.0.0:9596 +Jul-12 00:14:18.001[] info: Syncing - 4.3 days left - 0.822 slots/s - slot: 305171 (skipped 305140) - head: 31 0x00f3…8e6b - finalized: 0x0000…0000:0 - peers: 1 +Jul-12 00:14:30.000[] info: Syncing - 14 hours left - 5.91 slots/s - slot: 305172 (skipped 304847) - head: 325 0x3ae7…8752 - finalized: 0x1044…8852:8 - peers: 1 +``` + +### Check validators are detected and decrypted + +> OPTIONAL: If you are running validators, you can check the validator client logs to ensure the validator keys exist, has been detected and decrypted. + +Here is an example command if you are running validators on Goerli with the lodestar-quickstart script: + +``` +sudo docker logs goerli-validator +``` + +You should see something similar to: + +``` +Jul-06 21:28:00.571[] info: Lodestar network=goerli, version=v0.40.0-dev.e5dabac124, commit=e5dabac124933bcadc650d19d6b128dcbfcb6c43 +Jul-06 21:28:10.308[] info: 3 local keystores +Jul-06 21:28:10.309[] info: 0xa30147006edd615ffc5a5d9351e0fbdcc6318cc2c432e22b7134d7ace9cb90a4b276468560afdcc0be07810190f3eaed +Jul-06 21:28:10.309[] info: 0xa27db12f5645a61dc9c17300c2b8c53750f3a6940d944122e0da18a4ddedd42d590938340e9a011873168db4f028cf6e +Jul-06 21:28:10.309[] info: 0x9135a6e4b67beff56ae89ddd1168ebf3f1287f23350f77815020aa5f87857d6b2957aa9703a57417922268715ba4367d +Jul-06 21:28:10.332[] info: Genesis available +Jul-06 21:28:10.345[] info: Verified node and validator have same config +Jul-06 21:28:10.347[] info: Persisted genesisValidatorRoot 0x44f1e56283ca88b35c789f7f449e52339bc1fefe3a45913a43a6d16edcd33cf1 +Jul-06 21:28:10.347[] info: Persisted genesisTime 1653922800 +Jul-06 21:28:10.347[] info: Verified node and validator have same genesisValidatorRoot +Jul-06 21:28:10.358[] info: Discovered new validators count=0 +``` + +:::info +**NOTE:** It is normal to see `Error on getProposerDuties` in your validator logs as your beacon node and execution node sync up. Give it time. +::: + +## Stop Containers + +You can stop the running containers by using the `docker stop` command and apply it to more than one container if necessary. + +``` +sudo docker stop +``` + +Ensure to remove the container if you don't plan to restart it with the same parameters. + +``` +sudo docker rm +``` + +--- + +# Appendix + +## Appendix A - Expanding the Logical Volume + +There are cases where Ubuntu is provisioning only 200GB of a larger SSD causing users to run out of disk space when syncing their Eth1 node. The error message is similar to: + +`Fatal: Failed to register the Ethereum service: write /var/lib/goethereum/geth/chaindata/383234.ldb: no space left on device` + +To address this issue, assuming you have a SSD that is larger than 200GB, expand the space allocation for the LVM by following these steps: + +``` +sudo lvdisplay <-- Check your logical volume size +sudo lvm +lvextend -l +100%FREE /dev/ubuntu-vg/ubuntu-lv +lvextend -l +100%FREE -r /dev/ubuntu-vg/ubuntu-lv +exit +sudo resize2fs /dev/ubuntu-vg/ubuntu-lv +df -h <-- Check results +``` + +That should resize your disk to the maximum available space. + +If you need support, please check with the [ChainSafe Discord](https://discord.gg/642wB3XC3Q) under the #:star2:-lodestar-general channel. + +## Appendix B - Update client images + +To update client images, you just need to stop all the containers, remove them and restart the lodestar-quickstart script to automatically check for new images. + +You can stop the running containers by using the `docker stop` command with the container names. + +``` +sudo docker stop +``` + +Remove the containers by using the `docker rm` command. + +``` +sudo docker rm +``` + +Restart your containers using your [Startup Quickstart Script](#Startup-Quickstart-Script) command. + +--- + +## Full Disclaimer + +This article (the guide) is for informational purposes only and does not constitute professional advice. The author does not warrant or guarantee the accuracy, integrity, quality, completeness, currency, or validity of any information in this article. All information herein is provided “as is” without warranty of any kind and is subject to change at any time without notice. The author disclaims all express, implied, and statutory warranties of any kind, including warranties as to accuracy, timeliness, completeness, or fitness of the information in this article for any particular purpose. The author is not responsible for any direct, indirect, incidental, consequential or any other damages arising out of or in connection with the use of this article or in reliance on the information available on this article. This includes any personal injury, business interruption, loss of use, lost data, lost profits, or any other pecuniary loss, whether in an action of contract, negligence, or other misuse, even if the author has been informed of the possibility. diff --git a/docs/pages/run/getting-started/quick-start.md b/docs/pages/run/getting-started/quick-start.md index a28de8014b6a..3a07f6dd1017 100644 --- a/docs/pages/run/getting-started/quick-start.md +++ b/docs/pages/run/getting-started/quick-start.md @@ -2,25 +2,21 @@ title: Quick Start --- -## Lodestar Quickstart +## 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! +In order to make things easier and quicker for all types of users to bootstrap the Lodestar consensus client with a variety of execution clients, we have come up with [Lodestar Quickstart](https://github.com/ChainSafe/lodestar-quickstart) Docker scripts! -✅ Zero Configuration -✅ All testnets supported along with `mainnet` -✅ All mainstream Execution Clients integrated +- ✅ Zero configuration +- ✅ Single command startup +- ✅ All testnets supported along with mainnet +- ✅ All mainstream execution clients integrated -With just single command you can run lodestar with various execution engines, switch them up to see the Optimistic sync work its magic and eventually brings lodestar and the execution engine in sync - -### Customizations - -You can adapt them to your production setups with ease! Here is a simple guide for you to follow along: +### Support -👉 [Lodestar Quick Setup Guide](https://hackmd.io/@philknows/rJegZyH9q) +We actively maintain and update the configurations of running Lodestar with the most commonly used execution clients for various test/production networks so there is minimal configuration required for a standard setup. -### Support +If you have questions about these scripts, documentation or repository, feel free to talk to us on our [ChainSafe Discord](https://discord.gg/yjyvFRP) or [open an issue](https://github.com/ChainSafe/lodestar-quickstart/issues/new) and a member of the team or our community will be happy to assist you. -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. +### Customizations (Optional) -In case you are facing any issues with the quick start guide, do reach us out on lodestar discord! -Happy to help! 🙏🙏🙏 +You can further adapt our Quickstart Docker scripts to your node setups with ease! Use our [Quickstart Custom Setup Guide](./quick-start-custom-guide.md)! diff --git a/docs/pages/run/logging-and-metrics/client-monitoring.md b/docs/pages/run/logging-and-metrics/client-monitoring.md index dc707f2b31d0..3d9ede1d8464 100644 --- a/docs/pages/run/logging-and-metrics/client-monitoring.md +++ b/docs/pages/run/logging-and-metrics/client-monitoring.md @@ -1,4 +1,4 @@ -# Client monitoring +# Client Monitoring 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/). diff --git a/docs/pages/run/logging-and-metrics/dashboards.md b/docs/pages/run/logging-and-metrics/dashboards.md deleted file mode 100644 index e69de29bb2d1..000000000000 diff --git a/docs/pages/run/logging-and-metrics/log-management.md b/docs/pages/run/logging-and-metrics/log-management.md deleted file mode 100644 index a0ee1d5fec07..000000000000 --- a/docs/pages/run/logging-and-metrics/log-management.md +++ /dev/null @@ -1,3 +0,0 @@ -# Log Management - -Check back soon for more information!! diff --git a/docs/pages/run/logging-and-metrics/metrics-management.md b/docs/pages/run/logging-and-metrics/metrics-management.md deleted file mode 100644 index e69de29bb2d1..000000000000 diff --git a/docs/pages/run/logging-and-metrics/prometheus-grafana.md b/docs/pages/run/logging-and-metrics/prometheus-grafana.md index f49a44f37209..1214db7a0ade 100644 --- a/docs/pages/run/logging-and-metrics/prometheus-grafana.md +++ b/docs/pages/run/logging-and-metrics/prometheus-grafana.md @@ -1,8 +1,12 @@ -# Prometheus and Grafana +# Prometheus and Grafana Setup Prometheus is an open-source monitoring system with efficient time series database and a modern alerting approach. Together with Grafana it's the recommended way to make sure that your node and validator(s) are performing correctly. -## Prometheus +## Localized Docker Metrics Script + +The Lodestar team has setup a script which will copy the latest dashboards compiled by our team for development purposes. By utilizing the script localed in `/docker/docker-compose.local_dev.sh`, you can instantly setup the latest dockerized metrics alongside your local beacon node. + +## Prometheus Setup 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 configuration file @@ -23,7 +27,7 @@ lodestar --metrics=true --metrics.port=8008 Navigate to http://localhost:9090/ in your browser to verify that Prometheus is monitoring Lodestar -## Grafana +## Grafana Setup Download and install Grafana from its official repository https://grafana.com/docs/grafana/latest/installation/debian/ diff --git a/docs/pages/run/validator-management/proposer-config.md b/docs/pages/run/validator-management/proposer-config.md new file mode 100644 index 000000000000..0bd136a31f15 --- /dev/null +++ b/docs/pages/run/validator-management/proposer-config.md @@ -0,0 +1,36 @@ +# Proposer Configuration + +:::warning +This is an alpha feature. The feature and its format are subject to change. +::: + +With Lodestar's validator client, you can assign specific metadata for each proposer/public key using a proposer configuration file written in YAML file. This will allow you to set specific graffiti, fee recipients and builder settings per validator key. + +### Example proposer_config.yaml + +```yaml +proposer_config: + "0xa99a76ed7796f7be22d5b7e85deeb7c5677e88e511e0b337618f8c4eb61349b4bf2d153f649f7b53359fe8b94a38e44c": + graffiti: "graffiti" + strict_fee_recipient_check: false + fee_recipient: "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" + builder: + enabled: true + gas_limit: "30000000" + "0xa4855c83d868f772a579133d9f23818008417b743e8447e235d8eb78b1d8f8a9f63f98c551beb7de254400f89592314d": + fee_recipient: "0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb" + builder: + enabled: "true" + gas_limit: "35000000" +default_config: + graffiti: "default graffiti" + strict_fee_recipient_check: true + fee_recipient: "0xcccccccccccccccccccccccccccccccccccccccc" + builder: + enabled: true + gas_limit: "30000000" +``` + +### Enable Proposer Configuration + +After you have configured your proposer configuration YAML file, you can start Lodestar with an additional CLI flag option pointing to the file: `--proposerSettingsFile /path/to/proposer_config.yaml`. diff --git a/docs/pages/run/validator-management/vc-configuration.md b/docs/pages/run/validator-management/vc-configuration.md index ce6db52b3a66..f1df43afe86e 100644 --- a/docs/pages/run/validator-management/vc-configuration.md +++ b/docs/pages/run/validator-management/vc-configuration.md @@ -74,6 +74,10 @@ Configure your validator client's fee recipient address by using the [`--suggest You may choose to use the [`--strictFeeRecipientCheck`](./validator-cli.md#--strictfeerecipientcheck) flag to enable a strict check of the fee recipient address with the one returned by the beacon node for added reassurance. +:::note +If you would like to set unique proposer metadata (e.g. fee recipient address) for each validator you are running, see the [Proposer Configuration](./proposer-config.md) feature. +::: + ### Configure your builder selection and/or builder boost factor If you are running a beacon node with connected builder relays, you may use these validator configurations to signal which block (builder vs. local execution) the beacon node should produce. diff --git a/docs/pages/trouble-shooting.md b/docs/pages/trouble-shooting.md deleted file mode 100644 index 144aeb90ce20..000000000000 --- a/docs/pages/trouble-shooting.md +++ /dev/null @@ -1 +0,0 @@ -# Trouble Shooting diff --git a/docs/sidebars.ts b/docs/sidebars.ts index d9a4839a90c4..5efcedd37724 100644 --- a/docs/sidebars.ts +++ b/docs/sidebars.ts @@ -11,10 +11,17 @@ const sidebars: SidebarsConfig = { collapsed: false, items: [ "run/getting-started/quick-start", - "run/getting-started/installation", { type: "category", - label: "Beacon node", + label: "Installation", + items: [ + "run/getting-started/installation", + "run/getting-started/quick-start-custom-guide", + ], + }, + { + type: "category", + label: "Beacon Node", items: [ "run/beacon-management/starting-a-node", "run/beacon-management/beacon-cli", @@ -31,17 +38,23 @@ const sidebars: SidebarsConfig = { "run/validator-management/vc-configuration", "run/validator-management/validator-cli", "run/validator-management/external-signer", + "run/validator-management/proposer-config", ], }, { type: "category", label: "Logging and Metrics", - items: ["run/logging-and-metrics/prometheus-grafana", "run/logging-and-metrics/client-monitoring"], + items: [ + "run/logging-and-metrics/prometheus-grafana", + "run/logging-and-metrics/client-monitoring", + ], }, { type: "category", label: "Discv5 Bootnode", - items: ["run/bootnode/bootnode-cli"], + items: [ + "run/bootnode/bootnode-cli", + ], }, ], }, diff --git a/packages/light-client/README.md b/packages/light-client/README.md index 0323e8fc4326..3cab0c12f13b 100644 --- a/packages/light-client/README.md +++ b/packages/light-client/README.md @@ -31,7 +31,7 @@ You can find more information about the light-client protocol in the [specificat ## Getting started -- Follow the [installation guide](https://chainsafe.github.io/lodestar/getting-started/installation) or [Docker install](https://chainsafe.github.io/lodestar/getting-started/installation/#docker-installation) to install Lodestar. +- Follow the [installation guide](https://chainsafe.github.io/lodestar/run/getting-started/installation) to install Lodestar. - Quickly try out the whole stack by [starting a local testnet](https://chainsafe.github.io/lodestar/advanced-topics/setting-up-a-testnet). ## Light-Client CLI Example diff --git a/packages/prover/README.md b/packages/prover/README.md index ce1f33dd8efb..477da5140c4b 100644 --- a/packages/prover/README.md +++ b/packages/prover/README.md @@ -152,7 +152,7 @@ You will need to go over the [specification](https://github.com/ethereum/beacon- ## Getting started -- Follow the [installation guide](https://chainsafe.github.io/lodestar/getting-started/installation) to install Lodestar. +- Follow the [installation guide](https://chainsafe.github.io/lodestar/run/getting-started/installation) to install Lodestar. - Quickly try out the whole stack by [starting a local testnet](https://chainsafe.github.io/lodestar/advanced-topics/setting-up-a-testnet). ## Contributors From dae0c966a31d8f234c9ed0ae6f812d7208bfc8f5 Mon Sep 17 00:00:00 2001 From: Phil Ngo Date: Sat, 19 Oct 2024 01:55:49 -0400 Subject: [PATCH 02/12] Reconfig quickstart nav and minor fixes --- .../quick-start-custom-guide.md | 104 ++++++++++-------- docs/pages/run/getting-started/quick-start.md | 4 +- docs/sidebars.ts | 6 +- 3 files changed, 63 insertions(+), 51 deletions(-) diff --git a/docs/pages/run/getting-started/quick-start-custom-guide.md b/docs/pages/run/getting-started/quick-start-custom-guide.md index 54cecdf18a16..7b7007445d7c 100644 --- a/docs/pages/run/getting-started/quick-start-custom-guide.md +++ b/docs/pages/run/getting-started/quick-start-custom-guide.md @@ -1,4 +1,4 @@ -# Quickstart Custom Setup Guide +# Quick Start Custom Setup Guide This is a step-by-step guide to utilize [@ChainSafe/lodestar-quickstart](https://github.com/ChainSafe/lodestar-quickstart) to setup a Ubuntu-based full Ethereum node using a local execution client and ChainSafe's Lodestar consensus client via Docker (the recommended method to use Lodestar for production environments). This is an adaptation of [Somer Esat's guides](https://someresat.medium.com/) for the Ethereum staking community. @@ -168,10 +168,9 @@ Replace the 64 characters after `0x` with your token. If you are not running validators, press `CTRL` + `x` then `y` then `Enter` to save and exit. Proceed to Configuring your Network. ### Configure feeRecipient - -Optional: If you are running validators, you **must** set this to receive rewards. If you are not running validators, you can skip this section. - +:::warning If you are running validators, Ethereum requires validators to set a **Fee Recipient** which allows you to receive priority fees and MEV rewards when proposing blocks. If you do not set this address, your rewards will be sent to the [burn address by default](https://etherscan.io/address/0x0000000000000000000000000000000000000000). +::: Configure your validator client's feeRecipient address by changing the `FEE_RECIPIENT` line. Ensure you specify an Ethereum address you control. @@ -183,7 +182,7 @@ FEE_RECIPIENT="0xB7576e9d314Df41EC5506494293Afb1bd5D3f65d" If you would like to run [MEV-Boost](https://boost.flashbots.net) with your validators, proceed to the next section. -If you do not want to run MEV-Boost, press `CTRL` + `x` then `y` then `Enter` to save and exit. Proceed to Configuring your Network. +If you do not want to run MEV-Boost, press `CTRL` + `x` then `y` then `Enter` to save and exit. Proceed to [Configuring your Network](#configuring-your-network). ### Set minimum bid for MEV-Boost validators @@ -191,7 +190,7 @@ If you do not want to run MEV-Boost, press `CTRL` + `x` then `y` then `Enter` to (Optional): If you are running validators and would like to use MEV-Boost, follow this section. Otherwise, skip this section. ::: -Validators running MEV-Boost maximize their staking reward by selling blockspace to an open market of builders. MEV-Boost v1.4+ allows you to set a minimum bid threshold to only use an externally built block if it meets or exceeds this parameter. For more information, see +Validators running MEV-Boost maximize their staking reward by selling blockspace to an open market of builders. MEV-Boost v1.4+ allows you to set a minimum bid threshold to only use an externally built block if it meets or exceeds this parameter. The `min-bid` parameter is denominated in ETH. For example, if you want to set your threshold to 0.03 ETH, set your configuration to `MIN_BUILDERBID=0.03` @@ -248,8 +247,8 @@ You may also choose to use a specific version release of Lodestar. To select a s ### Modify your weak subjectivity (checkpoint sync) provider -:::info -(Optional): We use ChainSafe's Lodestar checkpoints by default. You may choose to point your trusted checkpoint at another source or verify the checkpoints with other providers. If you would rather sync from genesis, you can skip this step. +:::note +(Optional): We use ChainSafe's Lodestar checkpoints by default. You may choose to point your trusted checkpoint at another source or verify the checkpoints with other providers. If you would rather sync from genesis (not recommended), you can skip this step. ::: Weak subjectivity (checkpoint sync) allows your beacon node to sync within minutes by utilizing a trusted checkpoint from a trusted provider. @@ -367,7 +366,7 @@ sudo rm deposit_data-1552658472.json ::: -Continue to the [**Startup Quickstart Script**](#Startup-Quickstart-Script) section. +Continue to the [**Startup Quickstart Script**](#startup-quickstart-script) section. ### Option 2: Setup multiple validator sets with keystores encrypted under different passwords @@ -395,7 +394,7 @@ Navigate into the directory. cd validatorset1 ``` -### Create validator keystore password +#### Create validator keystore password Create the `pass.txt` file containing your validator's decryption password for use. @@ -411,7 +410,7 @@ Once the validator container is running, you can delete this file from your serv Once complete, press `CTRL` + `x` then `y` then `Enter` to save and exit. -### Copy/Move keystores to `lodestar-quickstart/validatorset1/keystores` directory +#### Copy/Move keystores to `lodestar-quickstart/validatorset1/keystores` directory Your `keystore.json` file(s) generated from the [`staking-deposit-cli`](https://github.com/ethereum/staking-deposit-cli) or similar generator for validator keys will be placed in the `lodestar-quickstart/validatorset1/keystores` directory using the `sudo cp` command to copy or `sudo mv` command to move the files. @@ -452,12 +451,12 @@ sudo rm deposit_data-1552658472.json Repeat the same steps above for `validatorset2` and any subsequent sets of validators you require. When complete you should have a similar looking directory tree such as the one below: -Then, continue to the [**Startup Quickstart Script**](#Startup-Quickstart-Script) section. Pay particular attention to startup script example five (5) and (6). +Then, continue to the [**Startup Quickstart Script**](#startup-quickstart-script) section. Pay particular attention to startup script example five (5) and (6). ### Option 3: Setup validators with mnemonic :::warning -:warning: **TESTNET USE ONLY:** Do not use this method unless you're validating on a testnet. Your mnemonic will be stored in plaintext on your server. +**TESTNET USE ONLY:** Do not use this method unless you're validating on a testnet. Your mnemonic will be stored in plaintext on your server, which is unsafe. ::: Optional: If you want to setup validators with your mnemonic. Otherwise, skip this step. @@ -484,7 +483,7 @@ Therefore, if you generated one key, it is likely in index 0, so you would use ` Once complete, press `CTRL` + `x` then `y` then `Enter` to save and exit. -Continue to the [**Startup Quickstart Script**](#Startup-Quickstart-Script) section. +Continue to the [**Startup Quickstart Script**](#startup-quickstart-script) section. --- @@ -529,7 +528,7 @@ The following are **_example commands_** as a template for initiating the quicks ``` :::warning -**NOTE:** You can only start up one set of validator keystores per validator client on the same command. Use the below command (#6) to startup another validator client for another set of validator keys. +You can only start up one set of validator keystores per validator client on the same command. Use the below command (#6) to startup another validator client for another set of validator keys. ::: 6. Startup validator client only with validator client set two (using keystores) and execution client Geth detached from containers: @@ -539,14 +538,12 @@ The following are **_example commands_** as a template for initiating the quicks ``` :::info -**NOTE:** You may wish to start only the execution node first for syncing to reduce Lodestar's execution client (eth1) requests for data that doesn't exist yet and reduce warnings/errors. Be sure to use our flags below such as `--justEL` to start the execution client standalone. - -**NOTE:** The script will standardize naming your containers so running the `setup.sh` twice, will not create two instances of the same containers. The script will standardize naming your containers so running the `./setup.sh ` a second time, will not create two instances of the same containers. +The script will standardize naming your containers so running the `setup.sh` twice, will not create two instances of the same containers. The script will standardize naming your containers so running the `./setup.sh ` a second time, will not create two instances of the same containers. ::: Configure the above commands with what you intend to run using the Quickstart Script Help table below. -# Quickstart Script Help +## Quickstart Script Help | Command | Required/Optional | Description | | ------------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -564,13 +561,12 @@ Configure the above commands with what you intend to run using the Quickstart Sc | `--justVC` | Optional | Launch only the Lodestar validator. | | `--skipImagePull` | Optional | Launch with only the local Docker images. Do not update them on this run. | -:::info -**NOTE:** +:::note `*` : Only one of the two options should be provided. `**` : Only one of the two options should be provided. ::: -## Check Containers +### Check Containers You can check the status and get the name of your containers by using the `docker ps` command: @@ -580,7 +576,7 @@ sudo docker ps The containers should not constantly restart. If they restart, likely a misconfiguration occurred. -## Check Container Logs +### Check Container Logs You can check the status of what your container is logging to diagnose a problem or follow along the status of your container output. @@ -607,15 +603,28 @@ sudo docker logs -n 10 Your beacon node should initialize and you should see something similar to: ``` -Jul-12 00:13:35.912[] info: Lodestar network=goerli, version=v0.40.0-dev.2b16141fc6, commit=2b16141fc6d73e570d338da5d3448c67373405cb -Jul-12 00:13:35.935[] info: Connected to LevelDB database name=/data/lodestar/peerstore -Jul-12 00:13:35.948[DB] info: Connected to LevelDB database name=/data/lodestar/chain-db -Jul-12 00:13:40.076[] info: Initializing beacon state from anchor state slot=0, epoch=0, stateRoot=0x75b3f63942f47f1b17a1ca4a61bf5ca37ffb5e2a9ef9129f9c80cc13d6c67f03 -Jul-12 00:13:40.382[ETH1] info: Starting search for terminal POW block TERMINAL_TOTAL_DIFFICULTY=50000000000000000 -Jul-12 00:13:43.499[METRICS] info: Starting metrics HTTP server port=8008, address=127.0.0.1 -Jul-12 00:13:43.588[API] info: Started REST api server address=http://0.0.0.0:9596 -Jul-12 00:14:18.001[] info: Syncing - 4.3 days left - 0.822 slots/s - slot: 305171 (skipped 305140) - head: 31 0x00f3…8e6b - finalized: 0x0000…0000:0 - peers: 1 -Jul-12 00:14:30.000[] info: Syncing - 14 hours left - 5.91 slots/s - slot: 305172 (skipped 304847) - head: 325 0x3ae7…8752 - finalized: 0x1044…8852:8 - peers: 1 +Jul-31 13:35:27.967[] info: Lodestar network=mainnet, version=v1.21.0/ff35faa, commit=ff35faae4ad1697b86d708a0367a95a71648ab6e +Jul-31 13:35:28.344[] info: Connected to LevelDB database path=/data/lodestar/chain-db +Jul-31 13:35:49.828[] info: Initializing beacon from a valid db state slot=9633504, epoch=301047, stateRoot=0xfa2845a6877b98555906a1654941c97d9c05bdd41e61cc0870a967dc9030b156, isWithinWeakSubjectivityPeriod=true +Jul-31 13:35:51.955[chain] info: Historical state worker started +Jul-31 13:35:51.969[eth1] info: Eth1 provider urls=http://localhost:8551 +Jul-31 13:35:51.975[execution] info: Execution client urls=http://localhost:8551 +Jul-31 13:35:51.977[] info: External builder url=http://localhost:8661 +Jul-31 13:36:21.128[network] info: running libp2p instance in worker thread +Jul-31 13:36:21.727[network] info: libp2p worker started peer=15Uiu2HAmACcmCEXcgt3zCtJL2rqJZ2Mvdjh6U6fe26HgD2FoNRwW +Jul-31 13:36:27.677[network] info: discv5 worker started peerId=16Uiu2HAmACcmCEXcgt3zCtJL2rqJZ2Mvdjh6U6fe26HgD2FoNRwW, initialENR=enr:-IO4QHGTUd1Zg8LAhUAioOz_ySTKoJLIOa6zltSP_AvvhTFVYw6M6YB35IxsiKxQG7nUgCpUB5SIsNxMntCNlTK9sMEBgmlkgnY0iXNlY3AyNTZrMaEC24cdmzuGnWqSwF-8Hw2gbkAZDzMWW3LsHJfp_kDhy-GDdGNwgiMog3VkcIIeWH, bindAddr4=/ip4/0.0.0.0/udp/9000 +Jul-31 13:36:28.134[network] info: PeerId 16Uiu2HAmACcmCEXcgt3zCtJL2rqJZ2Mvdjh6U6fe26HgD2FoNRwW, Multiaddrs /ip4/0.0.0.0/tcp/9000 +Jul-31 13:36:28.137[metrics] info: Started metrics HTTP server address=http://127.0.0.1:8008 +Jul-31 13:36:28.256[rest] info: Started REST API server address=http://0.0.0.0:9596 +Jul-31 13:36:28.257[] info: Searching peers - peers: 0 - slot: 9634080 - head: (slot -576) 0x9d88…d02a - exec-block: syncing(20426302 0xcec4…) - finalized: 0x7feb…c130:301045 +Jul-31 13:36:36.461[execution] info: Execution client is synced oldState=ONLINE, newState=SYNCED +Jul-31 13:36:53.019[] info: Syncing - 3.7 minutes left - 2.32 slots/s - slot: 9634082 - head: (slot -515) 0x792f…f8aa - exec-block: valid(20426365 0x58b1…) - finalized: 0x9d88…d02a:301047 - peers: 11 +Jul-31 13:38:53.168[] info: Syncing - 11 seconds left - 4.01 slots/s - slot: 9634092 - head: (slot -44) 0x7491…f63e - exec-block: valid(20426841 0xd4b2…) - finalized: 0x1e00…6e6b:301062 - peers: 59 +Jul-31 13:38:58.051[network] info: Subscribed gossip core topics +Jul-31 13:38:58.132[sync] info: Subscribed gossip core topics +Jul-31 13:39:05.001[] info: Synced - slot: 9634093 - head: 0x35de…1f0e - exec-block: valid(20426886 0x10ff…) - finalized: 0x88f8…5375:301063 - peers: 70 +Jul-31 13:39:17.000[] info: Synced - slot: 9634094 - head: 0x7844…3b3e - exec-block: valid(20426887 0x67d1…) - finalized: 0x88f8…5375:301063 - peers: 69 +Jul-31 13:39:29.000[] info: Synced - slot: 9634095 - head: 0x5516…ba12 - exec-block: valid(20426888 0x4ceb…) - finalized: 0x88f8…5375:301063 - peers: 74 ``` ### Check validators are detected and decrypted @@ -631,21 +640,26 @@ sudo docker logs goerli-validator You should see something similar to: ``` -Jul-06 21:28:00.571[] info: Lodestar network=goerli, version=v0.40.0-dev.e5dabac124, commit=e5dabac124933bcadc650d19d6b128dcbfcb6c43 -Jul-06 21:28:10.308[] info: 3 local keystores -Jul-06 21:28:10.309[] info: 0xa30147006edd615ffc5a5d9351e0fbdcc6318cc2c432e22b7134d7ace9cb90a4b276468560afdcc0be07810190f3eaed -Jul-06 21:28:10.309[] info: 0xa27db12f5645a61dc9c17300c2b8c53750f3a6940d944122e0da18a4ddedd42d590938340e9a011873168db4f028cf6e -Jul-06 21:28:10.309[] info: 0x9135a6e4b67beff56ae89ddd1168ebf3f1287f23350f77815020aa5f87857d6b2957aa9703a57417922268715ba4367d -Jul-06 21:28:10.332[] info: Genesis available -Jul-06 21:28:10.345[] info: Verified node and validator have same config -Jul-06 21:28:10.347[] info: Persisted genesisValidatorRoot 0x44f1e56283ca88b35c789f7f449e52339bc1fefe3a45913a43a6d16edcd33cf1 -Jul-06 21:28:10.347[] info: Persisted genesisTime 1653922800 -Jul-06 21:28:10.347[] info: Verified node and validator have same genesisValidatorRoot -Jul-06 21:28:10.358[] info: Discovered new validators count=0 +Mar-01 03:06:35.048[] info: Lodestar network=holesky, version=v1.16.0/6ad9740, commit=6ad9740a085574306cf46c7642e749d6ec9a4264 +Mar-01 03:06:35.050[] info: Connecting to LevelDB database path=/keystoresDir/validator-db-holesky +Mar-01 03:06:35.697[] info: 100% of keystores imported. current=2 total=2 rate=1318.68keys/m +Mar-01 03:06:35.698[] info: 2 local keystores +Mar-01 03:06:35.698[] info: 0xa6fcfca12e1db6c7341d82327010cd57224dc239d1c5e4fb18286cc32edb877d813c5af1c870d474aef7b3ff7ab927ea +Mar-01 03:06:35.698[] info: 0x8f868e53bbe1451bcf6d42c9ab6d292cbd7fbfa09c59b6b99c1dd6a4977e2e7b4b752c328784ca2788dd6f63ffcbdb7e +Mar-01 03:06:35.732[] info: Beacon node urls=http://127.0.0.1:9596 +Mar-01 03:09:23.813[] info: Genesis fetched from the beacon node +Mar-01 03:09:23.816[] info: Verified connected beacon node and validator have same the config +Mar-01 03:09:23.818[] info: Verified connected beacon node and validator have the same genesisValidatorRoot +Mar-01 03:09:23.818[] info: Initializing validator useProduceBlockV3=deneb+, broadcastValidation=gossip, defaultBuilderSelection=executiononly, suggestedFeeRecipient=0xeeef273281fB83F56182eE960aA4bAfe7fE075DE, strictFeeRecipientCheck=false +Mar-01 03:09:23.830[] info: Validator seen on beacon chain validatorIndex=1234567, pubKey=0xa6fcfca12e1db6c7341d82327010cd57224dc239d1c5e4fb18286cc32edb877d813c5af1c870d474aef7b3ff7ab927ea +Mar-01 03:09:23.830[] info: Validator seen on beacon chain validatorIndex=1234568, pubKey=0x8f868e53bbe1451bcf6d42c9ab6d292cbd7fbfa09c59b6b99c1dd6a4977e2e7b4b752c328784ca2788dd6f63ffcbdb7e +Mar-01 03:09:23.830[] info: Validator statuses active=2, total=2 +Mar-01 03:15:50.191[] info: Published attestations slot=1113379, count=1 +Mar-01 03:16:02.728[] info: Published attestations slot=1113380, count=1 ``` :::info -**NOTE:** It is normal to see `Error on getProposerDuties` in your validator logs as your beacon node and execution node sync up. Give it time. +It is normal to see `Error on getProposerDuties` in your validator logs as your beacon node and execution node sync up. Give it time. ::: ## Stop Containers @@ -704,7 +718,7 @@ Remove the containers by using the `docker rm` command. sudo docker rm ``` -Restart your containers using your [Startup Quickstart Script](#Startup-Quickstart-Script) command. +Restart your containers using your [Startup Quickstart Script](#startup-quickstart-script) command. --- diff --git a/docs/pages/run/getting-started/quick-start.md b/docs/pages/run/getting-started/quick-start.md index 3a07f6dd1017..e1a77face695 100644 --- a/docs/pages/run/getting-started/quick-start.md +++ b/docs/pages/run/getting-started/quick-start.md @@ -1,9 +1,7 @@ --- -title: Quick Start +title: Lodestar Quick Start Scripts --- -## Lodestar Quickstart Scripts - In order to make things easier and quicker for all types of users to bootstrap the Lodestar consensus client with a variety of execution clients, we have come up with [Lodestar Quickstart](https://github.com/ChainSafe/lodestar-quickstart) Docker scripts! - ✅ Zero configuration diff --git a/docs/sidebars.ts b/docs/sidebars.ts index 5efcedd37724..1b6eb1ac055d 100644 --- a/docs/sidebars.ts +++ b/docs/sidebars.ts @@ -10,12 +10,12 @@ const sidebars: SidebarsConfig = { label: "Run A Node", collapsed: false, items: [ - "run/getting-started/quick-start", + "run/getting-started/installation", { type: "category", - label: "Installation", + label: "Quick Start", items: [ - "run/getting-started/installation", + "run/getting-started/quick-start", "run/getting-started/quick-start-custom-guide", ], }, From 42460a3fcdba44456180b7a5816bc48204d40654 Mon Sep 17 00:00:00 2001 From: Phil Ngo Date: Sat, 19 Oct 2024 02:11:39 -0400 Subject: [PATCH 03/12] fix lint --- docs/pages/run/getting-started/quick-start-custom-guide.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/pages/run/getting-started/quick-start-custom-guide.md b/docs/pages/run/getting-started/quick-start-custom-guide.md index 7b7007445d7c..63040cfc79db 100644 --- a/docs/pages/run/getting-started/quick-start-custom-guide.md +++ b/docs/pages/run/getting-started/quick-start-custom-guide.md @@ -168,6 +168,7 @@ Replace the 64 characters after `0x` with your token. If you are not running validators, press `CTRL` + `x` then `y` then `Enter` to save and exit. Proceed to Configuring your Network. ### Configure feeRecipient + :::warning If you are running validators, Ethereum requires validators to set a **Fee Recipient** which allows you to receive priority fees and MEV rewards when proposing blocks. If you do not set this address, your rewards will be sent to the [burn address by default](https://etherscan.io/address/0x0000000000000000000000000000000000000000). ::: From a5b3fe91fa77c2ab06e326611a9dcb9bb098d825 Mon Sep 17 00:00:00 2001 From: Phil Ngo Date: Sun, 20 Oct 2024 12:47:05 -0400 Subject: [PATCH 04/12] spelling fixes --- docs/pages/run/beacon-management/starting-a-node.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/pages/run/beacon-management/starting-a-node.md b/docs/pages/run/beacon-management/starting-a-node.md index 28baaeb8fda7..7aa0799b6e83 100644 --- a/docs/pages/run/beacon-management/starting-a-node.md +++ b/docs/pages/run/beacon-management/starting-a-node.md @@ -126,7 +126,7 @@ If possible, validate your `wssCheckpoint` state from multiple places (e.g. diff #### Still Taking Long to Sync? After your node has been offline for a while, it might be the case that it takes a long time to sync even though a `--checkpointSyncUrl` is specified. -This is due to the fact that the last databse state is still within the weak subjectivity period (~15 days on mainnet) which causes the node +This is due to the fact that the last database state is still within the weak subjectivity period (~15 days on mainnet) which causes the node to sync from the database state instead of the checkpoint state. It is possible to force syncing from a checkpoint state by supplying the `--forceCheckpointSync` flag. This option is only recommended if it is absolutely @@ -134,7 +134,7 @@ necessary for the node to be synced right away to fulfill its duties as there is ### Sync Log Guide -The Lodestar beacon syncronization log aims to provide information of utmost importance about the state of your node and be succinct at the same time. You may see the sync logs in the following format: +The Lodestar beacon sync log aims to provide information of utmost importance about the state of your node and be succinct at the same time. You may see the sync logs in the following format: `[Sync status] - [ Slot info ] - [Head info] - [Execution block info] - [Finalized info] - [Peers info]` From e59a6eca149d52c43334dc7cd1fb34e196c217c9 Mon Sep 17 00:00:00 2001 From: Phil Ngo Date: Sun, 20 Oct 2024 23:44:24 -0400 Subject: [PATCH 05/12] minor fixes and add to wordlist --- .wordlist.txt | 19 +++++++++++++++++++ .../quick-start-custom-guide.md | 6 +++--- .../logging-and-metrics/prometheus-grafana.md | 2 +- 3 files changed, 23 insertions(+), 4 deletions(-) diff --git a/.wordlist.txt b/.wordlist.txt index a2e642a926a0..45d3bd6bc3d7 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -13,6 +13,7 @@ Casper Chai ChainSafe Codespaces +CoinCashew Corepack Customizations DPoS @@ -29,6 +30,7 @@ ENRs ETH Edgington Erigon +Esat EthStaker EtherScan Ethereum @@ -37,8 +39,10 @@ FINDNODE FX Flamegraph Flamegraphs +GPG Geth Github +Goerli Gossipsub Grafana Grandine @@ -46,6 +50,7 @@ HTTPS HackMD Hashicorp Homebrew +Hyperledger IPFS IPv Infura @@ -60,6 +65,7 @@ LGPLv LMD LPoS LTS +LVM Lerna MEV MacOS @@ -81,9 +87,11 @@ Quickstart RPC Reth Ryzen +SFTP SHA SSD SSZ +Somer Stakehouse TOC TTD @@ -103,6 +111,7 @@ backfill beaconcha blockRoot blockchain +blockspace blst bootnode bootnodes @@ -110,6 +119,7 @@ bundlers chainConfig chainsafe chiado +chmod cli cmd codebase @@ -125,6 +135,7 @@ dApp dApps ddos decrypt +derypted deserialization dev devcontainer @@ -139,17 +150,21 @@ env envs ephemery ethers +feeRecipient flamegraph flamegraphs floodsub +fsSL getNetworkIdentity gnosis +gpg heapdump heaptrack holesky interop js keypair +keyrings keystore keystores libp @@ -160,9 +175,11 @@ llnode lockfile mainnet malloc +mbps mdns merkle merkleization +misconfiguration mmeshsub monorepo multiaddr @@ -199,6 +216,7 @@ ssz stakers subnet subnets +sudo tcp testnet testnets @@ -215,6 +233,7 @@ vite vitest webpack wip +xRelayPubKey xcode yaml yamux diff --git a/docs/pages/run/getting-started/quick-start-custom-guide.md b/docs/pages/run/getting-started/quick-start-custom-guide.md index 63040cfc79db..4aefc78151fe 100644 --- a/docs/pages/run/getting-started/quick-start-custom-guide.md +++ b/docs/pages/run/getting-started/quick-start-custom-guide.md @@ -5,7 +5,7 @@ This is a step-by-step guide to utilize [@ChainSafe/lodestar-quickstart](https:/ This guide will provide instructions which include running a local execution node. This guide uses Lodestar's `stable` release branch and supports **Holesky** testnet setups and **Mainnet**. :::info -This guide specifically focuses on using Lodestar's Quickstart scripts which allows for near instantanious setup with the following technologies: +This guide specifically focuses on using Lodestar's Quickstart scripts which allows for near instant setup with the following technologies: - [Ubuntu v22.04 (LTS) x64 server](https://releases.ubuntu.com/22.04/) - Ethereum Execution (eth1) clients: @@ -68,7 +68,7 @@ Check your available disk space. Even you have a large SSD there are cases where We must install Docker Engine to run the images on your local machine. -#### Add Docker's GPG Keyrings +#### Add Docker's GPG keyrings Run each line one at a time. @@ -556,7 +556,7 @@ Configure the above commands with what you intend to run using the Quickstart Sc | `--detached` | Optional\* | By default the script will wait for processes and use user input (ctrl +c) to end the processes, however you can pass this option to skip this behavior and just return, for e.g. in case you just want to leave it running. | | `--withValidatorKeystore` | Optional\*\* | Launch a validator client using `LODESTAR_VALIDATOR_MNEMONIC_ARGS` (`--withValidatorMnemonic`) or using a folder (`--withValidatorKeystore --justVC` connecting to same beacon node. | | `--withValidatorMnemonic` | Optional\*\* | Launch a validator client using mnemonic method.(`LODESTAR_VALIDATOR_MNEMONIC_ARGS`) as set in the network vars file. | -| `--withMevBoost` | Optional | Launch a MEV-Boost container to interface with multiple relays picked for the corresponding network vars file. When paired with `--justCL` or `--justVC` this only activates the builder args in the beacon/validator and use the builder url set in MEVBOOST_URL variable in fixed.vars | +| `--withMevBoost` | Optional | Launch a MEV-Boost container to interface with multiple relays picked for the corresponding network vars file. When paired with `--justCL` or `--justVC` this only activates the builder arguments in the beacon/validator and use the builder url set in MEVBOOST_URL variable in fixed.vars | | `--justEL` | Optional | Launch only the Execution Layer client. | | `--justCL` | Optional | Launch only the Lodestar beacon node. | | `--justVC` | Optional | Launch only the Lodestar validator. | diff --git a/docs/pages/run/logging-and-metrics/prometheus-grafana.md b/docs/pages/run/logging-and-metrics/prometheus-grafana.md index 1214db7a0ade..c36c52a72a0c 100644 --- a/docs/pages/run/logging-and-metrics/prometheus-grafana.md +++ b/docs/pages/run/logging-and-metrics/prometheus-grafana.md @@ -4,7 +4,7 @@ Prometheus is an open-source monitoring system with efficient time series databa ## Localized Docker Metrics Script -The Lodestar team has setup a script which will copy the latest dashboards compiled by our team for development purposes. By utilizing the script localed in `/docker/docker-compose.local_dev.sh`, you can instantly setup the latest dockerized metrics alongside your local beacon node. +The Lodestar team has setup a script which will copy the latest dashboards compiled by our team for development purposes. By utilizing the script located in `/docker/docker-compose.local_dev.sh`, you can instantly setup the latest dockerized metrics alongside your local beacon node. ## Prometheus Setup From affc183114d5e02088c1301741d3349f415298a6 Mon Sep 17 00:00:00 2001 From: Phil Ngo Date: Mon, 21 Oct 2024 00:21:12 -0400 Subject: [PATCH 06/12] prettier fix --- docs/pages/run/getting-started/quick-start-custom-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/pages/run/getting-started/quick-start-custom-guide.md b/docs/pages/run/getting-started/quick-start-custom-guide.md index 4aefc78151fe..8afc11c00ebf 100644 --- a/docs/pages/run/getting-started/quick-start-custom-guide.md +++ b/docs/pages/run/getting-started/quick-start-custom-guide.md @@ -556,7 +556,7 @@ Configure the above commands with what you intend to run using the Quickstart Sc | `--detached` | Optional\* | By default the script will wait for processes and use user input (ctrl +c) to end the processes, however you can pass this option to skip this behavior and just return, for e.g. in case you just want to leave it running. | | `--withValidatorKeystore` | Optional\*\* | Launch a validator client using `LODESTAR_VALIDATOR_MNEMONIC_ARGS` (`--withValidatorMnemonic`) or using a folder (`--withValidatorKeystore --justVC` connecting to same beacon node. | | `--withValidatorMnemonic` | Optional\*\* | Launch a validator client using mnemonic method.(`LODESTAR_VALIDATOR_MNEMONIC_ARGS`) as set in the network vars file. | -| `--withMevBoost` | Optional | Launch a MEV-Boost container to interface with multiple relays picked for the corresponding network vars file. When paired with `--justCL` or `--justVC` this only activates the builder arguments in the beacon/validator and use the builder url set in MEVBOOST_URL variable in fixed.vars | +| `--withMevBoost` | Optional | Launch a MEV-Boost container to interface with multiple relays picked for the corresponding network vars file. When paired with `--justCL` or `--justVC` this only activates the builder arguments in the beacon/validator and use the builder url set in MEVBOOST_URL variable in fixed.vars | | `--justEL` | Optional | Launch only the Execution Layer client. | | `--justCL` | Optional | Launch only the Lodestar beacon node. | | `--justVC` | Optional | Launch only the Lodestar validator. | From 4ad21272b6ac04a822a33487530b9eeb84cd94bf Mon Sep 17 00:00:00 2001 From: Phil Ngo Date: Mon, 21 Oct 2024 10:39:35 -0400 Subject: [PATCH 07/12] add to wordlist --- .wordlist.txt | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/.wordlist.txt b/.wordlist.txt index 45d3bd6bc3d7..46759b5bf455 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -135,6 +135,7 @@ dApp dApps ddos decrypt +decrypted derypted deserialization dev @@ -156,6 +157,7 @@ flamegraphs floodsub fsSL getNetworkIdentity +Golang gnosis gpg heapdump @@ -170,6 +172,7 @@ keystores libp lightclient linter +liveness lldb llnode lockfile @@ -179,6 +182,7 @@ mbps mdns merkle merkleization +MevBoost misconfiguration mmeshsub monorepo @@ -187,6 +191,7 @@ multifork namespace namespaced namespaces +Nim nodemodule orchestrator osx From 48dbab95702782ea4e941b635e2ad3700a420696 Mon Sep 17 00:00:00 2001 From: Phil Ngo Date: Mon, 21 Oct 2024 11:03:49 -0400 Subject: [PATCH 08/12] sort wordlist --- .wordlist.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/.wordlist.txt b/.wordlist.txt index 46759b5bf455..0146f60e78c4 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -43,6 +43,7 @@ GPG Geth Github Goerli +Golang Gossipsub Grafana Grandine @@ -70,11 +71,13 @@ Lerna MEV MacOS Metamask +MevBoost ModuleNotFoundError Monorepo NPM NVM Nethermind +Nim NodeJS NodeSource OSI @@ -157,7 +160,6 @@ flamegraphs floodsub fsSL getNetworkIdentity -Golang gnosis gpg heapdump @@ -182,7 +184,6 @@ mbps mdns merkle merkleization -MevBoost misconfiguration mmeshsub monorepo @@ -191,7 +192,6 @@ multifork namespace namespaced namespaces -Nim nodemodule orchestrator osx From 1a92441910afc91cf65f9f91e054f47616509ed4 Mon Sep 17 00:00:00 2001 From: Phil Ngo Date: Tue, 22 Oct 2024 02:00:23 -0400 Subject: [PATCH 09/12] modify dominance to include lighthouse --- docs/pages/introduction.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/pages/introduction.md b/docs/pages/introduction.md index 0a11a0acb594..f1481999b1eb 100644 --- a/docs/pages/introduction.md +++ b/docs/pages/introduction.md @@ -21,7 +21,7 @@ In an effort to promote client diversity there are several consensus beacon node The Ethereum network's robustness is significantly enhanced by its client diversity, whereby multiple, independently-developed clients conforming to a common specification, facilitating seamless interaction and function equivalently across different nodes. This client variety not only fosters a rich ecosystem but also provides a buffer against network-wide issues stemming from bugs or malicious attacks targeted at particular clients. For instance, during the Shanghai denial-of-service attack in 2016, the diversified client structure enabled the network to withstand the assault, underscoring the resilience afforded by multiple client configurations. -On the consensus layer, client distribution is crucial for maintaining network integrity and finality, ensuring transactions are irreversible once validated. A balanced spread of nodes across various clients help to mitigate risks associated with potential bugs or attacks that could, in extreme cases, derail the consensus process (liveness failure) or lead to incorrect chain splits (forking), thereby jeopardizing the network's stability and trust. While the data suggests a [dominance of the Prysm client](https://clientdiversity.org) on the consensus layer, efforts are ongoing to promote a more even distribution among others clients. Encouraging the adoption of minority clients, bolstering their documentation, and leveraging real-time client diversity dashboards are among the strategies being employed to enhance client diversity, which in turn fortifies the Ethereum consensus layer against adversities and fosters a healthier decentralized network. +On the consensus layer, client distribution is crucial for maintaining network integrity and finality, ensuring transactions are irreversible once validated. A balanced spread of nodes across various clients help to mitigate risks associated with potential bugs or attacks that could, in extreme cases, derail the consensus process (liveness failure) or lead to incorrect chain splits (forking), thereby jeopardizing the network's stability and trust. While the data suggests a [dominance of the Prysm and Lighthouse clients](https://clientdiversity.org) on the consensus layer, efforts are ongoing to promote a more even distribution among others clients. Encouraging the adoption of minority clients, bolstering their documentation, and leveraging real-time client diversity dashboards are among the strategies being employed to enhance client diversity, which in turn fortifies the Ethereum consensus layer against adversities and fosters a healthier decentralized network. The [non-finality event of May 2023](https://medium.com/offchainlabs/post-mortem-report-ethereum-mainnet-finality-05-11-2023-95e271dfd8b2) on the Ethereum network posed a significant challenge. The issue arose from attestations for a fork, which necessitated state replays to validate the attestations, causing a notable strain on system resources. As a result, nodes fell out of sync, which deterred the accurate tracking of the actual head of the chain. This situation was exacerbated by a decline in attestations during specific epochs, further hampering the consensus mechanism from reaching finality. The Lodestar team noticed late attestations several weeks prior to the event and implemented a feature that attempted to address such challenges by not processing untimely attestations, and thus not requiring expensive state replays​. While it was done for slightly different reasons, the result was the same. Lodestar was able to follow the chain correctly and helped to stabilize the network. This example underscored the importance of client diversity and network resilience against potential forks and replay attacks. These are considered realistic threats, especially in the context of system complexity like in Ethereum's consensus mechanism. From ec1de12b5e22674c9aeadff9f71daa6e7c8ad791 Mon Sep 17 00:00:00 2001 From: Phil Ngo Date: Wed, 23 Oct 2024 01:50:12 -0400 Subject: [PATCH 10/12] fix typescript casing and add recommendation --- docs/pages/index.md | 6 +++--- docs/pages/introduction.md | 4 ++-- docs/pages/supporting-libraries/libraries.md | 4 ++-- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/pages/index.md b/docs/pages/index.md index 2a23047282eb..2bca344b84cb 100644 --- a/docs/pages/index.md +++ b/docs/pages/index.md @@ -6,12 +6,12 @@ title: Home ## Welcome to the Lodestar Documentation -> **Lodestar is an open-source Ethereum Consensus client and Typescript ecosystem, maintained by ChainSafe Systems** +> **Lodestar is an open-source Ethereum Consensus client and TypeScript ecosystem, maintained by ChainSafe Systems** ### Getting Started - Follow the instructions for [build from source](./run/getting-started/installation#build-from-source), [binaries](./run/getting-started/installation#binaries), or [Docker](./run/getting-started/installation#docker-installation) to install Lodestar. Or use our [Lodestar Quickstart scripts](https://github.com/ChainSafe/lodestar-quickstart). -- Use [Lodestar libraries](./supporting-libraries/index.md) in your next Ethereum Typescript project. +- Use [Lodestar libraries](./supporting-libraries/index.md) in your next Ethereum TypeScript project. - Run a beacon node on [mainnet or a public testnet](./run/beacon-management/starting-a-node.md). - Utilize the whole stack by [starting a local testnet](./contribution/advanced-topics/setting-up-a-testnet.md). - View the Lodestar Beacon [CLI commands and options](./run/beacon-management/beacon-cli.md) @@ -32,7 +32,7 @@ Hardware specifications minimum / recommended, to run the Lodestar client. ### Execution Client -If you run the [execution client](https://ethereum.org/en/developers/docs/nodes-and-clients/#execution-clients) on the same host, you will need to check their requirements and add them to the above requirements. +If you run the [execution client](https://ethereum.org/en/developers/docs/nodes-and-clients/#execution-clients) on the same host, you will need to check their requirements and add them to the above requirements. Broadly, to run both an execution and a consensus client on the same machine, we recommend a 4 TB SSD and 32 GB RAM. ## About These Docs diff --git a/docs/pages/introduction.md b/docs/pages/introduction.md index f1481999b1eb..f74d0b70768d 100644 --- a/docs/pages/introduction.md +++ b/docs/pages/introduction.md @@ -1,6 +1,6 @@ # Introduction -Ethereum is one of the most profoundly important inventions in recent history. It is a decentralized, open-source blockchain featuring smart contract functionality. It is the second-largest cryptocurrency by market capitalization, after Bitcoin, and is the second largest blockchain by market capitalization. Ethereum was proposed in 2013 by programmer Vitalik Buterin. Development was crowdfunded in 2014, and the network went live on 30 July 2015, with 72 million coins premined. ChainSafe was founded not too long afterwards in 2017 and has been actively working in the Ethereum ecosystem ever since. We are proud to develop Lodestar, the only Typescript based consensus client, and to present this documentation as a resource for the Ethereum community. +Ethereum is one of the most profoundly important inventions in recent history. It is a decentralized, open-source blockchain featuring smart contract functionality. It is the second-largest cryptocurrency by market capitalization, after Bitcoin, and is the second largest blockchain by market capitalization. Ethereum was proposed in 2013 by programmer Vitalik Buterin. Development was crowdfunded in 2014, and the network went live on 30 July 2015, with 72 million coins premined. ChainSafe was founded not too long afterwards in 2017 and has been actively working in the Ethereum ecosystem ever since. We are proud to develop Lodestar, the only TypeScript based consensus client, and to present this documentation as a resource for the Ethereum community. ## Proof of Stake @@ -12,7 +12,7 @@ In an effort to promote client diversity there are several consensus beacon node - [Grandine (Rust)](https://grandine.io) - [Lighthouse (Rust)](https://lighthouse.sigmaprime.io/) -- [Lodestar (Typescript)](https://lodestar.chainsafe.io/) +- [Lodestar (TypeScript)](https://lodestar.chainsafe.io/) - [Nimbus (Nim)](https://nimbus.team/) - [Prysm (Golang)](https://prysmaticlabs.com/) - [Teku (Java)](https://consensys.net/knowledge-base/ethereum-2/teku/) diff --git a/docs/pages/supporting-libraries/libraries.md b/docs/pages/supporting-libraries/libraries.md index e76ccc2f9ec7..58796e56cd15 100644 --- a/docs/pages/supporting-libraries/libraries.md +++ b/docs/pages/supporting-libraries/libraries.md @@ -1,13 +1,13 @@ # Lodestar libraries -The Lodestar project is divided into Typescript packages that can be used independently of the CLI. These packages span the breadth of the Ethereum Consensus layer, and are perfect for Typescript developers looking to build around Ethereum. +The Lodestar project is divided into TypeScript packages that can be used independently of the CLI. These packages span the breadth of the Ethereum Consensus layer, and are perfect for TypeScript developers looking to build around Ethereum. ## Monorepo libraries 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 types, Typescript interfaces and SSZ type objects +- [`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 From dcbe8ba09f64994be5c26c38fbbc4a68f3bac94d Mon Sep 17 00:00:00 2001 From: Phil Ngo Date: Wed, 23 Oct 2024 02:00:36 -0400 Subject: [PATCH 11/12] add selection and boost_factor with keymanager notice --- docs/pages/run/validator-management/proposer-config.md | 8 +++++++- docs/pages/run/validator-management/vc-configuration.md | 2 +- 2 files changed, 8 insertions(+), 2 deletions(-) diff --git a/docs/pages/run/validator-management/proposer-config.md b/docs/pages/run/validator-management/proposer-config.md index 0bd136a31f15..2d5264151e3d 100644 --- a/docs/pages/run/validator-management/proposer-config.md +++ b/docs/pages/run/validator-management/proposer-config.md @@ -17,11 +17,15 @@ proposer_config: builder: enabled: true gas_limit: "30000000" + selection: "executionalways" + boost_factor: "0" "0xa4855c83d868f772a579133d9f23818008417b743e8447e235d8eb78b1d8f8a9f63f98c551beb7de254400f89592314d": fee_recipient: "0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb" builder: enabled: "true" - gas_limit: "35000000" + gas_limit: "3000000" + selection: "maxprofit" + boost_factor: "100" default_config: graffiti: "default graffiti" strict_fee_recipient_check: true @@ -29,6 +33,8 @@ default_config: builder: enabled: true gas_limit: "30000000" + selection: "default" + boost_factor: "90" ``` ### Enable Proposer Configuration diff --git a/docs/pages/run/validator-management/vc-configuration.md b/docs/pages/run/validator-management/vc-configuration.md index f1df43afe86e..a51791eff494 100644 --- a/docs/pages/run/validator-management/vc-configuration.md +++ b/docs/pages/run/validator-management/vc-configuration.md @@ -75,7 +75,7 @@ Configure your validator client's fee recipient address by using the [`--suggest You may choose to use the [`--strictFeeRecipientCheck`](./validator-cli.md#--strictfeerecipientcheck) flag to enable a strict check of the fee recipient address with the one returned by the beacon node for added reassurance. :::note -If you would like to set unique proposer metadata (e.g. fee recipient address) for each validator you are running, see the [Proposer Configuration](./proposer-config.md) feature. +If you would like to set unique proposer metadata (e.g. fee recipient address) for each validator you are running, see the [Proposer Configuration](./proposer-config.md) feature. This feature is also available via the keymanager API. ::: ### Configure your builder selection and/or builder boost factor From 72b5e9a94ae04341ec66a3a1f13be542542cbf08 Mon Sep 17 00:00:00 2001 From: Phil Ngo Date: Wed, 23 Oct 2024 02:07:03 -0400 Subject: [PATCH 12/12] update wordlist --- .wordlist.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/.wordlist.txt b/.wordlist.txt index 0146f60e78c4..ccada1b2a863 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -167,6 +167,7 @@ heaptrack holesky interop js +keymanager keypair keyrings keystore