lighthouse/book/src/checkpoint-sync.md

Checkpoint Sync

Since version 2.0.0 Lighthouse supports syncing from a recent finalized checkpoint. This is substantially faster than syncing from genesis, while still providing all the same features.

If you would like 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, or a block explorer.

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/ ...

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.

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 this value are available in the 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 blob
• --checkpoint-block: accepts an SSZ-encoded SignedBeaconBlock blob

Both the state and block must be provided and must adhere to the Alignment Requirements described below.

Alignment Requirements

• The block must be a finalized block from an epoch boundary, i.e. block.slot() % 32 == 0.
• The state must be the state corresponding to block with state.slot() == block.slot() and state.hash_tree_root() == block.state_root().

These requirements are imposed to align with Lighthouse's database schema, and notably exclude finalized blocks from skipped slots. You can avoid alignment issues by using Automatic Checkpoint Sync, which will search for a suitable block and state pair.