gnosis/lighthouse
1
0
Fork 0
mirror of https://github.com/sigp/lighthouse.git synced 2026-03-14 18:32:42 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update Lighthouse book Sec 3-6 and FAQ (#4221)

Browse Source 
## Issue Addressed

Update Lighthouse book to include latest information especially after Capella upgrade

## Proposed Changes

Notable changes:
- Combine Sec 4.1 & 6.1 into Sec 4, because Sec 6.1 is importing validator key which is a required step when want to run a validator
- Combine Sec 5.1 & 5.2 with Sec 5, and move Sec 5 to under Sec 9
- Added partial withdrawals in Sec 6



## Additional Info

Please provide any additional information. For example, future considerations
or information useful for reviewers.


Co-authored-by: chonghe <tanck2005@gmail.com>
This commit is contained in:
chonghe
2023-05-05 00:51:56 +00:00
parent b1416c8a43
commit 45835f6a6b
21 changed files with 522 additions and 604 deletions
Download Patch File Download Diff File Expand all files Collapse all files

131
book/src/run_a_node.md
View File

@@ -1,77 +1,43 @@
# Run a Node
This document provides detail for users who want to run a Lighthouse beacon node.
This section provides the 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).
1. Create a [JWT secret file](#step-1-create-a-jwt-secret-file)
1. Set up an [execution node](#step-2-set-up-an-execution-node);
1. Set up a [beacon node](#step-3-set-up-a-beacon-node-using-lighthouse);
1. [Check logs for sync status](#step-4-check-logs);
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:
## Step 1: Create a JWT secret file
A JWT secret file is used to secure the communication between the execution client and the consensus client. In this step, we will create a JWT secret file which will be used in later steps.
- `--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.
```bash
sudo mkdir -p /secrets
openssl rand -hex 32 | tr -d "\n" | sudo tee /secrets/jwt.hex
```
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:
## Step 2: Set up an execution node
- [Geth: Connecting to Consensus Clients](https://geth.ethereum.org/docs/getting-started/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 Lighthouse beacon node *must* connect to an execution engine in order to validate the transactions present in blocks. 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. Select an execution client from the list below and run it:
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
- [Nethermind](https://docs.nethermind.io/nethermind/first-steps-with-nethermind/running-nethermind-post-merge)
- [Besu](https://besu.hyperledger.org/en/stable/public-networks/get-started/connect/mainnet/)
- [Erigon](https://github.com/ledgerwatch/erigon#beacon-chain-consensus-layer)
- [Geth](https://geth.ethereum.org/docs/getting-started/consensus-clients)
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.
> Note: Each execution engine has its own flags for configuring the engine API and JWT secret to connect to a beacon node. Please consult the relevant page of your execution engine as above for the required flags.
### 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.
Once the execution client is up, just let it continue running. The execution client will start syncing when it connects to a beacon node. Depending on the execution client and computer hardware specifications, syncing can take from a few hours to a few days. You can safely proceed to Step 3 to set up a beacon node while the execution client is still syncing.
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: Set up a beacon node using 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.
In this step, we will set up a beacon node. Use the following command to start a beacon node that connects to the execution node:
### Staking
@@ -84,9 +50,30 @@ lighthouse bn \
--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.
> Note: If you download the binary file, you need to navigate to the directory of the binary file to run the above command.
Notable flags:
- `--network` flag, which selects a network:
- `lighthouse` (no flag): Mainnet.
- `lighthouse --network mainnet`: Mainnet.
- `lighthouse --network goerli`: Goerli (testnet).
- `lighthouse --network sepolia`: Sepolia (testnet).
- `lighthouse --network gnosis`: Gnosis chain
> Note: 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.
- `--execution-endpoint`: the URL of the execution engine API. If the execution engine is running on the same computer with the default port, this will be
`http://localhost:8551`.
- `--execution-jwt`: the path to the JWT secret file shared by Lighthouse and the
execution engine. This is a mandatory form of authentication which ensures that Lighthouse has the authority to control the execution engine.
- `--checkpoint-sync-url`: Lighthouse supports fast sync from a recent finalized checkpoint. Checkpoint sync is *optional*; however, we **highly recommend** it since it is substantially faster than syncing from genesis while still providing the same functionality. The checkpoint sync is done using [public endpoints](https://eth-clients.github.io/checkpoint-sync-endpoints/) provided by the Ethereum community. For example, in the above command, we use the URL for Sigma Prime's checkpoint sync server for mainnet `https://mainnet.checkpoint.sigp.io`.
- `--http`: to expose an HTTP server of the beacon chain. The default listening address is `http://localhost:5052`. The HTTP API is required for the beacon node to accept connections from the *validator client*, which manages keys.
If you intend to run the beacon node without running the validator client (e.g., for non-staking purposes such as supporting the network), you can modify the above command so that the beacon node is configured for non-staking purposes:
### Non-staking
@@ -99,17 +86,19 @@ lighthouse bn \
--disable-deposit-contract-sync
```
Since we are not staking, we can use the `--disable-deposit-contract-sync` flag.
Since we are not staking, we can use the `--disable-deposit-contract-sync` flag to disable syncing of deposit logs from the execution node.
---
Once Lighthouse runs, we can monitor the logs to see if it is syncing correctly.
## Step 4: Check logs
## Step 4: Check logs for sync status
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:
If you run Lighthouse with the flag `--checkpoint-sync-url`, 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
@@ -122,16 +111,17 @@ 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.
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.
If a validator client is connected to the beacon node it will be able to start its duties as soon as forwards sync completes, which typically takes 1-2 minutes.
> Note: If you have an existing Lighthouse database, you will need to delete the database by using the `--purge-db` flag or manually delete the database with `sudo rm -r /path_to_database/beacon`. If you do use a `--purge-db` flag, once checkpoint sync is complete, you can remove the flag upon a restart.
> **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
### Backfilling Blocks
Once forwards sync completes, Lighthouse will commence a "backfill sync" to download the blocks
from the checkpoint back to genesis.
@@ -156,16 +146,17 @@ as `verified` indicating that they have been processed successfully by the execu
INFO Synced, slot: 3690668, block: 0x1244…cb92, epoch: 115333, finalized_epoch: 115331, finalized_root: 0x0764…2a3d, exec_hash: 0x929c…1ff6 (verified), peers: 78
```
Once you see the above message - congratulations! This means that your node is synced and you have contributed to the decentralization and security of the Ethereum network.
## Step 5: Further readings
## 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);
- If you intend to run a validator, proceed 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!
Finally, if you are struggling with anything, join our [Discord](https://discord.gg/cyAszAh). We are happy to help!