Add Run a Node guide (#3681)
## Issue Addressed Related to #3672 ## Proposed Changes - Added a guide to run a node. Mainly, copy and paste from 'Merge Migration' and 'Checkpoint Sync'. - Ranked it high in ToC: - Introduction - Installation - Run a Node - Become a Validator ... - Hid 'Merge Migration' in ToC. ## Additional Info - Should I add/rephrase/delete something? - Now there is some redundancy: - 'Run a node' and 'Checkpoint Sync' contain similar information. - Same for 'Run a node' and 'Become a Validator'. Co-authored-by: kevinbogner <114221396+kevinbogner@users.noreply.github.com> Co-authored-by: Michael Sproul <micsproul@gmail.com>
This commit is contained in:
kevinbogner
parent
2779017076
commit
99ec9d9baf
@ -1,9 +1,6 @@
|
||||
# Summary
|
||||
|
||||
* [Introduction](./intro.md)
|
||||
* [Become a Validator](./mainnet-validator.md)
|
||||
* [Become a Testnet Validator](./testnet-validator.md)
|
||||
* [Merge Migration](./merge-migration.md)
|
||||
* [Installation](./installation.md)
|
||||
* [System Requirements](./system-requirements.md)
|
||||
* [Pre-Built Binaries](./installation-binaries.md)
|
||||
@ -13,6 +10,9 @@
|
||||
* [Cross-Compiling](./cross-compiling.md)
|
||||
* [Homebrew](./homebrew.md)
|
||||
* [Update Priorities](./installation-priorities.md)
|
||||
* [Run a Node](./run_a_node.md)
|
||||
* [Become a Validator](./mainnet-validator.md)
|
||||
* [Become a Testnet Validator](./testnet-validator.md)
|
||||
* [Key Management](./key-management.md)
|
||||
* [Create a wallet](./wallet-create.md)
|
||||
* [Create a validator](./validator-create.md)
|
||||
@ -46,6 +46,7 @@
|
||||
* [Pre-Releases](./advanced-pre-releases.md)
|
||||
* [Release Candidates](./advanced-release-candidates.md)
|
||||
* [MEV and Lighthouse](./builders.md)
|
||||
* [Merge Migration](./merge-migration.md)
|
||||
* [Contributing](./contributing.md)
|
||||
* [Development Environment](./setup.md)
|
||||
* [FAQs](./faq.md)
|
||||
|
||||
@ -18,6 +18,7 @@ We implement the specification as defined in the
|
||||
You may read this book from start to finish, or jump to some of these topics:
|
||||
|
||||
- Follow the [Installation Guide](./installation.md) to install Lighthouse.
|
||||
- Run your very [own beacon node](./run_a_node.md).
|
||||
- Learn about [becoming a mainnet validator](./mainnet-validator.md).
|
||||
- Get hacking with the [Development Environment Guide](./setup.md).
|
||||
- Utilize the whole stack by starting a [local testnet](./setup.md#local-testnets).
|
||||
|
||||
@ -61,6 +61,7 @@ the relevant page for your execution engine for the required flags:
|
||||
- [Geth: Connecting to Consensus Clients](https://geth.ethereum.org/docs/interface/consensus-clients)
|
||||
- [Nethermind: Running Nethermind Post Merge](https://docs.nethermind.io/nethermind/first-steps-with-nethermind/running-nethermind-post-merge)
|
||||
- [Besu: Prepare For The Merge](https://besu.hyperledger.org/en/stable/HowTo/Upgrade/Prepare-for-The-Merge/)
|
||||
- [Erigon: Beacon Chain (Consensus Layer)](https://github.com/ledgerwatch/erigon#beacon-chain-consensus-layer)
|
||||
|
||||
Once you have configured your execution engine to open up the engine API (usually on port 8551) you
|
||||
should add the URL to your `lighthouse bn` flags with `--execution-endpoint <URL>`, as well as
|
||||
|
||||
171
book/src/run_a_node.md
Normal file
171
book/src/run_a_node.md
Normal file
@ -0,0 +1,171 @@
|
||||
# Run a Node
|
||||
|
||||
This document provides detail for users who want to run a Lighthouse beacon node.
|
||||
You should be finished with one [Installation](./installation.md) method of your choice to continue with the following steps:
|
||||
|
||||
1. Set up an [execution node](#step-1-set-up-an-execution-node);
|
||||
1. Enable [checkpoint sync](#step-2-choose-a-checkpoint-sync-provider);
|
||||
1. Run [Lighthouse](#step-3-run-lighthouse);
|
||||
1. [Check logs](#step-4-check-logs); and
|
||||
1. [Further readings](#step-5-further-readings).
|
||||
|
||||
Checkpoint sync is *optional*; however, we recommend it since it is substantially faster
|
||||
than syncing from genesis while still providing the same functionality.
|
||||
|
||||
## Step 1: Set up an execution node
|
||||
|
||||
The Lighthouse beacon node *must* connect to an execution engine in order to validate the transactions
|
||||
present in blocks. Two flags are used to configure this connection:
|
||||
|
||||
- `--execution-endpoint`: the *URL* of the execution engine API. Often this will be
|
||||
`http://localhost:8551`.
|
||||
- `--execution-jwt`: the *path* to the file containing the JWT secret shared by Lighthouse and the
|
||||
execution engine. This is a mandatory form of authentication that ensures that Lighthouse
|
||||
has authority to control the execution engine.
|
||||
|
||||
Each execution engine has its own flags for configuring the engine API and JWT.
|
||||
Please consult the relevant page of your execution engine for the required flags:
|
||||
|
||||
- [Geth: Connecting to Consensus Clients](https://geth.ethereum.org/docs/interface/consensus-clients)
|
||||
- [Nethermind: Running Nethermind & CL](https://docs.nethermind.io/nethermind/first-steps-with-nethermind/running-nethermind-post-merge)
|
||||
- [Besu: Connect to Mainnet](https://besu.hyperledger.org/en/stable/public-networks/get-started/connect/mainnet/)
|
||||
- [Erigon: Beacon Chain (Consensus Layer)](https://github.com/ledgerwatch/erigon#beacon-chain-consensus-layer)
|
||||
|
||||
The execution engine connection must be *exclusive*, i.e. you must have one execution node
|
||||
per beacon node. The reason for this is that the beacon node _controls_ the execution node.
|
||||
|
||||
## Step 2: Choose a checkpoint sync provider
|
||||
|
||||
Lighthouse supports fast sync from a recent finalized checkpoint.
|
||||
The checkpoint sync is done using a [public endpoint](#use-a-community-checkpoint-sync-endpoint)
|
||||
provided by the Ethereum community.
|
||||
|
||||
In [step 3](#step-3-run-lighthouse), when running Lighthouse,
|
||||
we will enable checkpoint sync by providing the URL to the `--checkpoint-sync-url` flag.
|
||||
|
||||
### Use a community checkpoint sync endpoint
|
||||
|
||||
The Ethereum community provides various [public endpoints](https://eth-clients.github.io/checkpoint-sync-endpoints/) for you to choose from for your initial checkpoint state. Select one for your network and use it as the URL.
|
||||
|
||||
For example, the URL for Sigma Prime's checkpoint sync server for mainnet is `https://mainnet.checkpoint.sigp.io`,
|
||||
which we will use in [step 3](#step-3-run-lighthouse).
|
||||
|
||||
## Step 3: Run Lighthouse
|
||||
|
||||
To run Lighthouse, we use the three flags from the steps above:
|
||||
- `--execution-endpoint`;
|
||||
- `--execution-jwt`; and
|
||||
- `--checkpoint-sync-url`.
|
||||
|
||||
Additionally, we run Lighthouse with the `--network` flag, which selects a network:
|
||||
|
||||
- `lighthouse` (no flag): Mainnet.
|
||||
- `lighthouse --network mainnet`: Mainnet.
|
||||
- `lighthouse --network goerli`: Goerli (testnet).
|
||||
|
||||
Using the correct `--network` flag is very important; using the wrong flag can
|
||||
result in penalties, slashings or lost deposits. As a rule of thumb, *always*
|
||||
provide a `--network` flag instead of relying on the default.
|
||||
|
||||
For the testnets we support [Goerli](https://goerli.net/) (`--network goerli`),
|
||||
[Sepolia](https://sepolia.dev/) (`--network sepolia`), and [Gnosis chain](https://www.gnosis.io/) (`--network gnosis`).
|
||||
|
||||
Minor modifications depend on if you want to run your node while [staking](#staking) or [non-staking](#non-staking).
|
||||
In the following, we will provide examples of what a Lighthouse setup could look like.
|
||||
|
||||
### Staking
|
||||
|
||||
```
|
||||
lighthouse bn \
|
||||
--network mainnet \
|
||||
--execution-endpoint http://localhost:8551 \
|
||||
--execution-jwt /secrets/jwt.hex \
|
||||
--checkpoint-sync-url https://mainnet.checkpoint.sigp.io \
|
||||
--http
|
||||
```
|
||||
|
||||
A Lighthouse beacon node can be configured to expose an HTTP server by supplying the `--http` flag.
|
||||
The default listen address is `127.0.0.1:5052`.
|
||||
The HTTP API is required for the beacon node to accept connections from the *validator client*, which manages keys.
|
||||
|
||||
### Non-staking
|
||||
|
||||
```
|
||||
lighthouse bn \
|
||||
--network mainnet \
|
||||
--execution-endpoint http://localhost:8551 \
|
||||
--execution-jwt /secrets/jwt.hex \
|
||||
--checkpoint-sync-url https://mainnet.checkpoint.sigp.io \
|
||||
--disable-deposit-contract-sync
|
||||
```
|
||||
|
||||
Since we are not staking, we can use the `--disable-deposit-contract-sync` flag.
|
||||
|
||||
---
|
||||
|
||||
Once Lighthouse runs, we can monitor the logs to see if it is syncing correctly.
|
||||
|
||||
## Step 4: Check logs
|
||||
Several logs help you identify if Lighthouse is running correctly.
|
||||
|
||||
### Logs - Checkpoint sync
|
||||
Lighthouse will print a message to indicate that checkpoint sync is being used:
|
||||
|
||||
```
|
||||
INFO Starting checkpoint sync remote_url: http://remote-bn:8000/, service: beacon
|
||||
```
|
||||
|
||||
After a short time (usually less than a minute), it will log the details of the checkpoint
|
||||
loaded from the remote beacon node:
|
||||
|
||||
```
|
||||
INFO Loaded checkpoint block and state state_root: 0xe8252c68784a8d5cc7e5429b0e95747032dd1dcee0d1dc9bdaf6380bf90bc8a6, block_root: 0x5508a20147299b1a7fe9dbea1a8b3bf979f74c52e7242039bd77cbff62c0695a, slot: 2034720, service: beacon
|
||||
```
|
||||
|
||||
Once the checkpoint is loaded Lighthouse will sync forwards to the head of the chain.
|
||||
|
||||
If a validator client is connected to the node then it will be able to start completing its duties
|
||||
as soon as forwards sync completes.
|
||||
|
||||
> **Security Note**: You should cross-reference the `block_root` and `slot` of the loaded checkpoint
|
||||
> against a trusted source like another [public endpoint](https://eth-clients.github.io/checkpoint-sync-endpoints/),
|
||||
> a friend's node, or a block explorer.
|
||||
|
||||
#### Backfilling Blocks
|
||||
|
||||
Once forwards sync completes, Lighthouse will commence a "backfill sync" to download the blocks
|
||||
from the checkpoint back to genesis.
|
||||
|
||||
The beacon node will log messages similar to the following each minute while it completes backfill
|
||||
sync:
|
||||
|
||||
```
|
||||
INFO Downloading historical blocks est_time: 5 hrs 0 mins, speed: 111.96 slots/sec, distance: 2020451 slots (40 weeks 0 days), service: slot_notifier
|
||||
```
|
||||
|
||||
Once backfill is complete, a `INFO Historical block download complete` log will be emitted.
|
||||
|
||||
Check out the [FAQ](./checkpoint-sync.md#faq) for more information on checkpoint sync.
|
||||
|
||||
### Logs - Syncing
|
||||
|
||||
You should see that Lighthouse remains in sync and marks blocks
|
||||
as `verified` indicating that they have been processed successfully by the execution engine:
|
||||
|
||||
```
|
||||
INFO Synced, slot: 3690668, block: 0x1244…cb92, epoch: 115333, finalized_epoch: 115331, finalized_root: 0x0764…2a3d, exec_hash: 0x929c…1ff6 (verified), peers: 78
|
||||
```
|
||||
|
||||
|
||||
## Step 5: Further readings
|
||||
|
||||
Several other resources are the next logical step to explore after running your beacon node:
|
||||
|
||||
- Learn how to [become a validator](./mainnet-validator.md);
|
||||
- Explore how to [manage your keys](./key-management.md);
|
||||
- Research on [validator management](./validator-management.md);
|
||||
- Dig into the [APIs](./api.md) that the beacon node and validator client provide;
|
||||
- Study even more about [checkpoint sync](./checkpoint-sync.md); or
|
||||
- Investigate what steps had to be taken in the past to execute a smooth [merge migration](./merge-migration.md).
|
||||
|
||||
Finally, if you a struggling with anything, join our [Discord](https://discord.gg/cyAszAh). We are happy to help!
|
||||
Loading…
Reference in New Issue
Block a user