The following instructions are required to setup and run a Lodestar beacon node.
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.
For a complete list of beacon node CLI commands and options, see the Command Line Reference
To select a known testnet or mainnet, use the
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.
Configure the Lodestar JWT authentication token¶
Post-Merge Ethereum will require secure authentication with the Engine API connection on your chosen Execution node.
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¶
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. Save this secret key into a text file and note where you store this file.
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¶
For Go Ethereum:
--authrpc.jwtsecret /data/jwtsecret flag to configure the secret. Use their documentation here.
--JsonRpc.JwtSecretFile /data/jwtsecret flag to configure the secret. Use their documentation here.
--engine-jwt-secret=<FILE> flag to configure the secret. Use their documentation here.
--authrpc.jwtsecret flag to configure the secret. Use their documentation here.
Run a beacon node¶
To start a Lodestar beacon run the command:
./lodestar beacon --network $NETWORK_NAME --jwtSecret $JWT_SECRET_PATH
This will assume an execution-layer client is available at the default
In case execution-layer clients are available at different locations, use
--execution.urls to specify these locations in the command:
./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
pr-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
If your node is stuck with
Searching for peers review your network configuration to make sure your ports are open.
By default, Lodestar stores all configuration and chain data at the path
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 or reach out to us in Discord. Just by reporting anomalies you are helping accelerate the progress of Ethereum Consensus, thanks for contributing!
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.
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..
If you have a synced beacon node available (e.g., your friend's node or an infrastructure provider) and a trusted checkpoint you can rely on, you can start off your beacon node in under a minute! And at the same time kicking the "long range attack" in its butt!
Just supply these extra arguments to your beacon node command:
--checkpointSyncUrl <synced node url> [--wssCheckpoint <trusted checkpoint in root:epoch format>]
In case you really trust
checkpointSyncUrl then you may skip providing
wssCheckpoint, which will then result into your beacon node syncing and starting off the recently finalized state from the trusted URL.
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.
Taking too 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.
It is possible to force syncing from 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¶
Lodestar beacon sync log aims to provide information of utmost importance about your node and yet be succinct at the same time. You may see the sync logs in the following format:
[Sync status] - [ Slot info ] - [Head info] - [Exec block info] - [Finalized info] - [Peers info]
See the following example of different kinds of sync log:
Apr-20 15:24:08.034 info: Searching peers - peers: 0 - slot: 6265018 - head: 6264018 0xed93…7b0a - exec-block: syncing(17088476 0x9649…) - finalized: 0xbf30…7e7c:195777 Apr-20 15:24:17.000 info: Searching peers - peers: 0 - slot: 6265019 - head: 6264018 0xed93…7b0a - exec-block: syncing(17088476 0x9649…) - finalized: 0xbf30…7e7c:195777
Apr-20 15:13:41.298 info: Syncing - 2.5 minutes left - 2.78 slots/s - slot: 6264966 - head: 6262966 0x5cec…f5b8 - exec-block: valid(17088105 0x6f74…) - finalized: 0x5cc0…3874:195764 - peers: 1 Apr-20 15:13:41.298 info: Syncing - 2 minutes left - 2.78 slots/s - slot: 6264967 - head: 6263965 0x5cec…f5b8 - exec-block: valid(17088105 0x6f74…) - finalized: 0x5cc0…3874:195764 - peers: 1
Apr-20 15:13:53.151 info: Syncing - 1.6 minutes left - 3.82 slots/s - slot: 6264967 - head: (slot -360) 0xe0cf…9f3c - exec-block: valid(17088167 0x2d6a…) - finalized: 0x8f3f…2f81:195766 - peers: 5 Apr-20 15:14:05.425 info: Syncing - 1.1 minutes left - 4.33 slots/s - slot: 6264968 - head: (slot -297) 0x3655…1658 - exec-block: valid(17088231 0xdafd…) - finalized: 0x9475…425a:195769 - peers: 2 Apr-20 15:14:53.001 info: Syncing - 9 seconds left - 5.00 slots/s - slot: 6264972 - head: (slot -45) 0x44e4…20a4 - exec-block: valid(17088475 0xca61…) - finalized: 0x9cbd…ba83:195776 - peers: 8
Apr-20 15:15:01.443[network] info: Subscribed gossip core topics Apr-20 15:15:01.446[sync] info: Subscribed gossip core topics Apr-20 15:15:05.000 info: Synced - slot: 6264973 - head: 0x90ea…c655 - exec-block: valid(17088521 0xca9b…) - finalized: 0x6981…682f:195778 - peers: 6 Apr-20 15:15:17.003 info: Synced - slot: 6264974 - head: 0x4f7e…0e3a - exec-block: valid(17088522 0x08b1…) - finalized: 0x6981…682f:195778 - peers: 6
Apr-20 15:15:41.001 info: Synced - slot: 6264976 - head: (slot -1) 0x17c6…71a7 - exec-block: valid(17088524 0x5bc1…) - finalized: 0x6981…682f:195778 - peers: 8 Apr-20 15:15:53.001 info: Synced - slot: 6264977 - head: (slot -2) 0x17c6…71a7 - exec-block: valid(17088524 0x5bc1…) - finalized: 0x6981…682f:195778 - peers: 8
Apr-20 15:16:05.000 info: Synced - slot: 6264978 - head: 0xc9fd…28c5 - exec-block: valid(17088526 0xb5bf…) - finalized: 0x6981…682f:195778 - peers: 8 Apr-20 15:16:17.017 info: Synced - slot: 6264979 - head: 0xde91…d4cb - exec-block: valid(17088527 0xa488…) - finalized: 0x6981…682f:195778 - peers: 7
Sync status: Takes three values :
Syncing(along with sync speed info) or
Searchingif node is is still looking for viable peers from where it can download blocks.
Slot (clock) info: What is the current ongoing slot as per the chain genesis
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.
Execution block info: It provides the execution information about the head whether its confirmed
validor execution layer is still
syncingto it, as well as its number and a short hash to easy identification.
Finalized info: What is the current local
finalizedcheckpoint in the format of
[checkpoint root]:[checkpoint epoch], for e.g.:
Peer info: Current total number of outbound or inbound peers, for e.g.:
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 for more details.