Skip to main content

Sync from genesis

A beacon node can also start from the very first state of the chain, the genesis state, and replay every block since. That takes days on mainnet, compared with minutes checkpoint sync.

Use checkpoint sync unless you have a reason not to

A checkpoint-synced node follows the same chain and runs validators just as well. Syncing from genesis only costs you time, unless one of the reasons below applies.

Operating system
Network

When to sync from genesis​

  • You need the historical states. Checkpoint sync with --enable-backfill brings back old blocks, but not the states before the checkpoint. An archive node that answers queries about any past slot needs them.
  • You don't want to take your starting point from another node. The node checks every block from genesis onward itself, instead of trusting a provider for a recent state.
Genesis sync still needs one known-good checkpoint

On proof of stake, a node that's been offline longer than the weak subjectivity period, a few weeks on mainnet, can't tell the real chain from a fake one built with old validator keys. A node syncing from genesis is in that position. Pass --weak-subjectivity-checkpoint with a recent block_root:epoch you got from a source you trust, and the node stops if the chain it syncs doesn't contain it.

Before you begin​

  • A beacon node with an empty data directory. If it already holds a database, the node carries on from there.
  • A connected execution client, with the folder layout from Connect your execution client.

Start the node​

  2. Start the beacon node. From the consensus folder:

    ./prysm.sh beacon-chain \
      --mainnet \
      --datadir=$HOME/ethereum/data/mainnet/beacon \
      --execution-endpoint=http://localhost:8551 \
      --jwt-secret=$HOME/ethereum/data/jwt.hex

    Running validators? Also add:

    --postpone-shutdown-for-proposals

    When you stop or restart the beacon node, it then waits until your validators' upcoming block proposals are done. Refer to the Don't restart just before a proposal page.

  3. Watch the logs. Once it has peers, the node logs its progress every few seconds:

    INFO initial-sync: Processing blocks batchSize=… blocksPerSecond=… estimatedTimeRemaining=… latestProcessedSlot/currentSlot=…/… peers=… startingFrom=0x…

    estimatedTimeRemaining tells you roughly when it will catch up. When it has, Prysm logs:

    INFO initial-sync: Synced to head of chain

Check that it works​

curl -s http://localhost:3500/eth/v1/node/syncing

While the node syncs, head_slot grows from 0 and sync_distance shrinks. When is_syncing is false, the node is following the chain, and the logs show a Synced new block line for every block.

Troubleshooting​

The node started from a checkpoint instead. --checkpoint-sync-url is still in your command or config file. Remove it, stop the node, and start it once with --force-clear-db.

Sync is slow or stalls. Prysm logs:

Waiting for enough suitable peers before syncing

The node needs peers to download blocks from. Check that your peer-to-peer ports are open.