Skip to content
Ashen Docs

State Sync & Checkpoints

Source: src/storage/snapshot.rs, src/rpc/node_rpc_v1.idl

Overview

Section titled “Overview”

State sync uses checkpoints and snapshots to bootstrap new nodes quickly. A snapshot packages a verified checkpoint plus the data needed to prove chain continuity and finalized history membership.

A snapshot includes:

  • Block headers from genesis (or a trusted height) to the checkpoint
  • Finalized history MMR entries (for membership proofs)
  • Checkpoint metadata (height + state root)
  • Validator sets for finality verification
  • Finality proof for the checkpoint block (if available)

Checkpoints

Section titled “Checkpoints”

A checkpoint is a state root committed at a specific height. It anchors state sync and lets nodes verify they rebuilt the same state.

RPCs:

  • get_checkpoint(height) → metadata + archive descriptor (if available)
  • list_checkpoints(limit) → descending list

Snapshots (Fast Sync)

Section titled “Snapshots (Fast Sync)”

There are two ways to consume snapshots:

1) Light Snapshot (proof-first)

Section titled “1) Light Snapshot (proof-first)”

get_light_snapshot(height) returns a compact proof bundle:

  • checkpoint metadata
  • checkpoint block header
  • MMR membership proof for the checkpoint block
  • optional finality proof
  • validator set

This is used to verify a checkpoint against a trusted MMR root.

2) Snapshot Chunk Streaming (full state)

Section titled “2) Snapshot Chunk Streaming (full state)”

get_snapshot_chunk streams state entries in chunks:

get_snapshot_chunk({ height, offset, limit })

Response includes:

  • state_root for validation
  • total_entries
  • entries (address, key, value)
  • has_more

For import, admins can call:

import_snapshot_chunk({ height, state_root, entries, finalize })

finalize=true triggers a state root verification at the end of import.

Verification Rules

Section titled “Verification Rules”

The snapshot module enforces:

  1. Header chain continuity (parent hashes match)
  2. MMR root recomputation from entries
  3. Finality proof validates against validator set
  4. Checkpoint state root matches header state root

If any check fails, the snapshot is rejected.

Error Cases

Section titled “Error Cases”

Common errors include:

  • SNAPSHOT_MMR_ROOT_MISMATCH
  • SNAPSHOT_MMR_COUNT_MISMATCH
  • FINALITY_PROOF_INVALID
  • STATE_ROOT_MISMATCH
Section titled “Related Docs”
  • docs-site/src/content/docs/upcoming/finalized-mmr-proofs.md
  • docs/design/light-client-mmr-onchain.md
  • docs/design/chainstore-hardening.md