Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Checkpoint Sync

Lighthouse supports syncing from a recent finalized checkpoint. This is substantially faster than syncing from genesis, while still providing all the same features. Checkpoint sync is also safer as it protects the node from long-range attacks. Since v4.6.0, checkpoint sync is required by default and genesis sync will no longer work without the use of --allow-insecure-genesis-sync.

To quickly get started with checkpoint sync, read the sections below on:

  1. Automatic Checkpoint Sync
  2. Backfilling Blocks

The remaining sections are for more advanced use-cases (archival nodes).

Automatic Checkpoint Sync

To begin checkpoint sync you will need HTTP API access to another synced beacon node. Enable checkpoint sync by providing the other beacon node's URL to --checkpoint-sync-url, alongside any other flags:

lighthouse bn --checkpoint-sync-url "http://remote-bn:5052" ...

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

After a short time (usually less than a minute), it will log the details of the checkpoint loaded from the remote beacon node:

INFO Loaded checkpoint block and state       state_root: 0xe8252c68784a8d5cc7e5429b0e95747032dd1dcee0d1dc9bdaf6380bf90bc8a6, block_root: 0x5508a20147299b1a7fe9dbea1a8b3bf979f74c52e7242039bd77cbff62c0695a, slot: 2034720, service: beacon

Security Note: You should cross-reference the block_root and slot of the loaded checkpoint against a trusted source like a friend's node, a block explorer or some public endpoints.

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.

Use a community checkpoint sync endpoint

The Ethereum community provides various public endpoints for you to choose from for your initial checkpoint state. Select one for your network and use it as the url for the --checkpoint-sync-url flag. e.g.

lighthouse bn --checkpoint-sync-url https://example.com/ ...

Adjusting the timeout

If the beacon node fails to start due to a timeout from the checkpoint sync server, you can try running it again with a longer timeout by adding the flag --checkpoint-sync-url-timeout.

lighthouse bn --checkpoint-sync-url-timeout 300 --checkpoint-sync-url https://example.com/ ...

The flag takes a value in seconds. For more information see lighthouse bn --help.

Backfilling Blocks

Once forwards sync completes, Lighthouse will commence a "backfill sync" to download the blocks from the checkpoint back to genesis.

The beacon node will log messages similar to the following each minute while it completes backfill sync:

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

Once backfill is complete, a INFO Historical block download complete log will be emitted.

Note: Since v4.1.0, Lighthouse implements rate-limited backfilling to mitigate validator performance issues after a recent checkpoint sync. This means that the speed at which historical blocks are downloaded is limited, typically to less than 20 slots/sec. This will not affect validator performance. However, if you would still prefer to sync the chain as fast as possible, you can add the flag --disable-backfill-rate-limiting to the beacon node.

Note: Since v4.2.0, Lighthouse limits the backfill sync to only sync backwards to the weak subjectivity point (approximately 5 months). This will help to save disk space. However, if you would like to sync back to the genesis, you can add the flag --genesis-backfill to the beacon node.

FAQ

  1. What if I have an existing database? How can I use checkpoint sync?

    The existing beacon database needs to be deleted before Lighthouse will attempt checkpoint sync. You can do this by providing the --purge-db flag, or by manually deleting <DATADIR>/beacon.

  2. Why is checkpoint sync faster?

    Checkpoint sync prioritises syncing to the head of the chain quickly so that the node can perform its duties. Additionally, it only has to perform lightweight verification of historic blocks: it checks the hash chain integrity & proposer signature rather than computing the full state transition.

  3. Is checkpoint sync less secure?

    No, in fact it is more secure! Checkpoint sync guards against long-range attacks that genesis sync does not. This is due to a property of Proof of Stake consensus known as Weak Subjectivity.

Reconstructing States

This section is only relevant if you are interested in running an archival node for analysis purposes.

After completing backfill sync the node's database will differ from a genesis-synced node in the lack of historic states. You do not need these states to run a staking node, but they are required for historical API calls (as used by block explorers and researchers).

You can opt-in to reconstructing all of the historic states by providing the --reconstruct-historic-states flag to the beacon node at any point (before, during or after sync).

The database keeps track of three markers to determine the availability of historic blocks and states:

  • oldest_block_slot: All blocks with slots greater than or equal to this value are available in the database. Additionally, the genesis block is always available.
  • state_lower_limit: All states with slots less than or equal to this value are available in the database. The minimum value is 0, indicating that the genesis state is always available.
  • state_upper_limit: All states with slots greater than or equal to min(split.slot, state_upper_limit) are available in the database. In the case where the state_upper_limit is higher than the split.slot, this means states are not being written to the freezer database.

Reconstruction runs from the state lower limit to the upper limit, narrowing the window of unavailable states as it goes. It will log messages like the following to show its progress:

INFO State reconstruction in progress        remaining: 747519, slot: 466944, service: freezer_db

Important information to be aware of:

  • Reconstructed states will consume several gigabytes or hundreds of gigabytes of disk space, depending on the database configuration used.
  • Reconstruction will only begin once backfill sync has completed and oldest_block_slot is equal to 0.
  • While reconstruction is running the node will temporarily pause migrating new data to the freezer database. This will lead to the database increasing in size temporarily (by a few GB per day) until state reconstruction completes.
  • It is safe to interrupt state reconstruction by gracefully terminating the node – it will pick up from where it left off when it restarts.
  • You can start reconstruction from the HTTP API, and view its progress. See the /lighthouse/database APIs.

For more information on historic state storage see the Database Configuration page.

Manual Checkpoint Sync

This section is only relevant if you want to manually provide the checkpoint state and block instead of fetching them from a URL.

To manually specify a checkpoint use the following two flags:

  • --checkpoint-state: accepts an SSZ-encoded BeaconState file
  • --checkpoint-block: accepts an SSZ-encoded SignedBeaconBlock file
  • --checkpoint-blobs: accepts an SSZ-encoded Blobs file

The command is as following:

curl -H "Accept: application/octet-stream" "http://localhost:5052/eth/v2/debug/beacon/states/$SLOT" > state.ssz
curl -H "Accept: application/octet-stream" "http://localhost:5052/eth/v2/beacon/blocks/$SLOT" > block.ssz
curl -H "Accept: application/octet-stream" "http://localhost:5052/eth/v1/beacon/blob_sidecars/$SLOT" > blobs.ssz

where $SLOT is the slot number. A slot which is an epoch boundary slot (i.e., first slot of an epoch) should always be used for manual checkpoint sync.

If the block contains blobs, all state, block and blobs must be provided and must point to the same slot. The state may be from the same slot as the block (unadvanced), or advanced to an epoch boundary, in which case it will be assumed to be finalized at that epoch.