|
| 1 | +# Run a Node |
| 2 | + |
| 3 | +This document provides detail for users who want to run a Lighthouse beacon node. |
| 4 | +You should be finished with one [Installation](./installation.md) method of your choice to continue with the following steps: |
| 5 | + |
| 6 | +1. Set up an [execution node](#step-1-set-up-an-execution-node); |
| 7 | +1. Enable [checkpoint sync](#step-2-choose-a-checkpoint-sync-provider); |
| 8 | +1. Run [Lighthouse](#step-3-run-lighthouse); |
| 9 | +1. [Check logs](#step-4-check-logs); and |
| 10 | +1. [Further readings](#step-5-further-readings). |
| 11 | + |
| 12 | +Checkpoint sync is *optional*; however, we recommend it since it is substantially faster |
| 13 | +than syncing from genesis while still providing the same functionality. |
| 14 | + |
| 15 | +## Step 1: Set up an execution node |
| 16 | + |
| 17 | +The Lighthouse beacon node *must* connect to an execution engine in order to validate the transactions |
| 18 | +present in blocks. Two flags are used to configure this connection: |
| 19 | + |
| 20 | +- `--execution-endpoint`: the *URL* of the execution engine API. Often this will be |
| 21 | + `http://localhost:8551`. |
| 22 | +- `--execution-jwt`: the *path* to the file containing the JWT secret shared by Lighthouse and the |
| 23 | + execution engine. This is a mandatory form of authentication that ensures that Lighthouse |
| 24 | +has authority to control the execution engine. |
| 25 | + |
| 26 | +Each execution engine has its own flags for configuring the engine API and JWT. |
| 27 | +Please consult the relevant page of your execution engine for the required flags: |
| 28 | + |
| 29 | +- [Geth: Connecting to Consensus Clients](https://geth.ethereum.org/docs/interface/consensus-clients) |
| 30 | +- [Nethermind: Running Nethermind & CL](https://docs.nethermind.io/nethermind/first-steps-with-nethermind/running-nethermind-post-merge) |
| 31 | +- [Besu: Connect to Mainnet](https://besu.hyperledger.org/en/stable/public-networks/get-started/connect/mainnet/) |
| 32 | +- [Erigon: Beacon Chain (Consensus Layer)](https://github.com/ledgerwatch/erigon#beacon-chain-consensus-layer) |
| 33 | + |
| 34 | +The execution engine connection must be *exclusive*, i.e. you must have one execution node |
| 35 | +per beacon node. The reason for this is that the beacon node _controls_ the execution node. |
| 36 | + |
| 37 | +## Step 2: Choose a checkpoint sync provider |
| 38 | + |
| 39 | +Lighthouse supports fast sync from a recent finalized checkpoint. |
| 40 | +The checkpoint sync is done using a [public endpoint](#use-a-community-checkpoint-sync-endpoint) |
| 41 | +provided by the Ethereum community. |
| 42 | + |
| 43 | +In [step 3](#step-3-run-lighthouse), when running Lighthouse, |
| 44 | +we will enable checkpoint sync by providing the URL to the `--checkpoint-sync-url` flag. |
| 45 | + |
| 46 | +### Use a community checkpoint sync endpoint |
| 47 | + |
| 48 | +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. |
| 49 | + |
| 50 | +For example, the URL for Sigma Prime's checkpoint sync server for mainnet is `https://mainnet.checkpoint.sigp.io`, |
| 51 | +which we will use in [step 3](#step-3-run-lighthouse). |
| 52 | + |
| 53 | +## Step 3: Run Lighthouse |
| 54 | + |
| 55 | +To run Lighthouse, we use the three flags from the steps above: |
| 56 | +- `--execution-endpoint`; |
| 57 | +- `--execution-jwt`; and |
| 58 | +- `--checkpoint-sync-url`. |
| 59 | + |
| 60 | +Additionally, we run Lighthouse with the `--network` flag, which selects a network: |
| 61 | + |
| 62 | +- `lighthouse` (no flag): Mainnet. |
| 63 | +- `lighthouse --network mainnet`: Mainnet. |
| 64 | +- `lighthouse --network goerli`: Goerli (testnet). |
| 65 | + |
| 66 | +Using the correct `--network` flag is very important; using the wrong flag can |
| 67 | +result in penalties, slashings or lost deposits. As a rule of thumb, *always* |
| 68 | +provide a `--network` flag instead of relying on the default. |
| 69 | + |
| 70 | +For the testnets we support [Goerli](https://goerli.net/) (`--network goerli`), |
| 71 | +[Sepolia](https://sepolia.dev/) (`--network sepolia`), and [Gnosis chain](https://www.gnosis.io/) (`--network gnosis`). |
| 72 | + |
| 73 | +Minor modifications depend on if you want to run your node while [staking](#staking) or [non-staking](#non-staking). |
| 74 | +In the following, we will provide examples of what a Lighthouse setup could look like. |
| 75 | + |
| 76 | +### Staking |
| 77 | + |
| 78 | +``` |
| 79 | +lighthouse bn \ |
| 80 | + --network mainnet \ |
| 81 | + --execution-endpoint http://localhost:8551 \ |
| 82 | + --execution-jwt /secrets/jwt.hex \ |
| 83 | + --checkpoint-sync-url https://mainnet.checkpoint.sigp.io \ |
| 84 | + --http |
| 85 | +``` |
| 86 | + |
| 87 | +A Lighthouse beacon node can be configured to expose an HTTP server by supplying the `--http` flag. |
| 88 | +The default listen address is `127.0.0.1:5052`. |
| 89 | +The HTTP API is required for the beacon node to accept connections from the *validator client*, which manages keys. |
| 90 | + |
| 91 | +### Non-staking |
| 92 | + |
| 93 | +``` |
| 94 | +lighthouse bn \ |
| 95 | + --network mainnet \ |
| 96 | + --execution-endpoint http://localhost:8551 \ |
| 97 | + --execution-jwt /secrets/jwt.hex \ |
| 98 | + --checkpoint-sync-url https://mainnet.checkpoint.sigp.io \ |
| 99 | + --disable-deposit-contract-sync |
| 100 | +``` |
| 101 | + |
| 102 | +Since we are not staking, we can use the `--disable-deposit-contract-sync` flag. |
| 103 | + |
| 104 | +--- |
| 105 | + |
| 106 | +Once Lighthouse runs, we can monitor the logs to see if it is syncing correctly. |
| 107 | + |
| 108 | +## Step 4: Check logs |
| 109 | +Several logs help you identify if Lighthouse is running correctly. |
| 110 | + |
| 111 | +### Logs - Checkpoint sync |
| 112 | +Lighthouse will print a message to indicate that checkpoint sync is being used: |
| 113 | + |
| 114 | +``` |
| 115 | +INFO Starting checkpoint sync remote_url: http://remote-bn:8000/, service: beacon |
| 116 | +``` |
| 117 | + |
| 118 | +After a short time (usually less than a minute), it will log the details of the checkpoint |
| 119 | +loaded from the remote beacon node: |
| 120 | + |
| 121 | +``` |
| 122 | +INFO Loaded checkpoint block and state state_root: 0xe8252c68784a8d5cc7e5429b0e95747032dd1dcee0d1dc9bdaf6380bf90bc8a6, block_root: 0x5508a20147299b1a7fe9dbea1a8b3bf979f74c52e7242039bd77cbff62c0695a, slot: 2034720, service: beacon |
| 123 | +``` |
| 124 | + |
| 125 | +Once the checkpoint is loaded Lighthouse will sync forwards to the head of the chain. |
| 126 | + |
| 127 | +If a validator client is connected to the node then it will be able to start completing its duties |
| 128 | +as soon as forwards sync completes. |
| 129 | + |
| 130 | +> **Security Note**: You should cross-reference the `block_root` and `slot` of the loaded checkpoint |
| 131 | +> against a trusted source like another [public endpoint](https://eth-clients.github.io/checkpoint-sync-endpoints/), |
| 132 | +> a friend's node, or a block explorer. |
| 133 | +
|
| 134 | +#### Backfilling Blocks |
| 135 | + |
| 136 | +Once forwards sync completes, Lighthouse will commence a "backfill sync" to download the blocks |
| 137 | +from the checkpoint back to genesis. |
| 138 | + |
| 139 | +The beacon node will log messages similar to the following each minute while it completes backfill |
| 140 | +sync: |
| 141 | + |
| 142 | +``` |
| 143 | +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 |
| 144 | +``` |
| 145 | + |
| 146 | +Once backfill is complete, a `INFO Historical block download complete` log will be emitted. |
| 147 | + |
| 148 | +Check out the [FAQ](./checkpoint-sync.md#faq) for more information on checkpoint sync. |
| 149 | + |
| 150 | +### Logs - Syncing |
| 151 | + |
| 152 | +You should see that Lighthouse remains in sync and marks blocks |
| 153 | +as `verified` indicating that they have been processed successfully by the execution engine: |
| 154 | + |
| 155 | +``` |
| 156 | +INFO Synced, slot: 3690668, block: 0x1244…cb92, epoch: 115333, finalized_epoch: 115331, finalized_root: 0x0764…2a3d, exec_hash: 0x929c…1ff6 (verified), peers: 78 |
| 157 | +``` |
| 158 | + |
| 159 | + |
| 160 | +## Step 5: Further readings |
| 161 | + |
| 162 | +Several other resources are the next logical step to explore after running your beacon node: |
| 163 | + |
| 164 | +- Learn how to [become a validator](./mainnet-validator.md); |
| 165 | +- Explore how to [manage your keys](./key-management.md); |
| 166 | +- Research on [validator management](./validator-management.md); |
| 167 | +- Dig into the [APIs](./api.md) that the beacon node and validator client provide; |
| 168 | +- Study even more about [checkpoint sync](./checkpoint-sync.md); or |
| 169 | +- Investigate what steps had to be taken in the past to execute a smooth [merge migration](./merge-migration.md). |
| 170 | + |
| 171 | +Finally, if you a struggling with anything, join our [Discord](https://discord.gg/cyAszAh). We are happy to help! |
0 commit comments