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
--jwt-secret /path/to/file 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.
Initialize a beacon node (optional)¶
If you would like to initialize your beacon node with the basic files required to run on a testnet or mainnet before actually running the node (Especially useful for configuring a new testnet), you can run the following command:
./lodestar init --network $NETWORK_NAME
By default, Lodestar stores all configuration and chain data at the path
Run a beacon node¶
To start a Lodestar beacon run the command:
./lodestar beacon --network $NETWORK_NAME
This will assume an eth1 client is available at the default location of
In case eth1 clients are available at different locations, use
--eth1.providerUrls to specify these locations in the command:
./lodestar beacon --network $NETWORK_NAME --eth1.providerUrls eth1.url1 eth1.url2
It is also possible to start a Lodestar beacon that does not follow the eth1 chain. For this, use the
eth1 option in the command:
./lodestar beacon --eth1 false --network $NETWORK_NAME
Immediately you should see confirmation that the node has started
Jul-09 17:32:34.895  info: Lodestar version=0.26.0 master 8058d367, network=prater Jul-09 17:32:34.920 [DB] info: Connected to LevelDB database name=/home/user/.local/share/lodestar/prater/chain-db Jul-09 17:32:46.419  info: Initializing beacon state slot=0, epoch=0, stateRoot=0x895390e92edc03df7096e9f51e51896e8dbe6e7e838180dadbfd869fdd77a659 Jul-09 17:33:13.502 [NETWORK] info: PeerId 16Uiu2HAmHXf37Pa4whSF1rdwWbkqDuiwd3U7wqTgadQVza48MTn4, Multiaddrs /ip4/127.0.0.1/tcp/9000 Jul-09 17:33:13.503  warn: Low peer count peers=0 Jul-09 17:33:13.504  info: Searching for peers - peers: 0 - finalized: 0 0x0000…0000 - head: 0 0x8c0e…ee87 - clockSlot: 780166 Jul-09 17:33:18.001  info: Searching for peers - peers: 0 - finalized: 0 0x0000…0000 - head: 0 0x8c0e…ee87 - clockSlot: 780166 Jul-09 17:33:30.000  info: Searching for peers - peers: 0 - finalized: 0 0x0000…0000 - head: 0 0x8c0e…ee87 - clockSlot: 780167 Jul-09 17:33:42.002  info: Searching for peers - peers: 0 - finalized: 0 0x0000…0000 - head: 0 0x8c0e…ee87 - clockSlot: 780168 Jul-09 17:33:54.000  info: Searching for peers - peers: 0 - finalized: 0 0x0000…0000 - head: 0 0x8c0e…ee87 - clockSlot: 780169 Jul-09 17:34:06.000  info: Searching for peers - peers: 0 - finalized: 0 0x0000…0000 - head: 0 0x8c0e…ee87 - clockSlot: 780170 Jul-09 17:34:18.386  info: Syncing - 30 days left - 0.297 slots/s - finalized: 0 0x0000…0000 - head: 30 0x0bcf…0506 - clockSlot: 780171 - peers: 1 Jul-09 17:34:30.448  info: Syncing - 8.1 days left - 1.12 slots/s - finalized: 2 0x8e30…3ce0 - head: 128 0xd4f1…d32b - clockSlot: 780172 - peers: 1 Jul-09 17:34:42.205  info: Syncing - 4.2 days left - 2.15 slots/s - finalized: 5 0x2811…5120 - head: 255 0x6c99…033b - clockSlot: 780173 - peers: 1 Jul-09 17:34:54.278  info: Syncing - 3 days left - 3.00 slots/s - finalized: 8 0x65e2…52a9 - head: 351 0x0f5a…1cd3 - clockSlot: 780174 - peers: 1
If your node is stuck with
Searching for peers review your network configuration to make sure your ports are open.
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/genesis (or from last saved state in db) in a network which is now far ahead, your node is susceptible to "long range attacks" via something called weak subjectivity. Read Vitalik's illuminating post on the same.
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 args 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.