There appears to be a few sync mechanisms in Substrate like full sync, fork sync, gap sync, warp sync, state sync, etc.

What is the complete picture of sync mechanisms/stages in Substrate are and how they relate to each other?

1 Answer 1


The original question mixes some high-level sync concepts with implementation details, I'll try to clarify.

From the point of view of a user there are 4 distinct sync modes:

  • Light sync - only downloads block headers and therefore transactions are not executed;
  • Full sync - "regular" sync where block headers and bodies are downloaded sequentially from genesis and transactions are executed (so state storage is maintained);
  • Light state sync - only downloads block headers but once the chain is synced it downloads the whole state of the best block (rather than executing the transactions from genesis in order to create it);
  • Warp sync - initially download the best finalized block and the whole state at this block, and finality proofs (currently from GRANDPA) for all validator set transitions from genesis up until the best finalized block. After the initial warp sync is done (and therefore the node is ready to import the latest blocks) historical blocks can be downloaded in the background.

Going back to terms pointed in the original question:

  • Gap sync is, optionally, used by warp sync to sync the historical blocks, i.e. the blocks from genesis up until the block we warped to;
  • State sync is used by light state sync and warp sync in order to download the latest state storage at a given block;
  • Fork sync is for tracking requests for syncing a specific chain (fork). It is only used after the node is fully synced (through any of the mechanisms above) and is following the latest blocks.
  • How do these map onto CLI though?: --sync <SYNC_MODE> Blockchain syncing mode. - full: Download and validate full blockchain history. - fast: Download blocks and the latest state only. - fast-unsafe: Same as fast, but skip downloading state proofs. - warp: Download the latest state and proof. [default: full] [possible values: full, fast, fast-unsafe, warp]
    – nazar-pc
    Commented Jul 15, 2022 at 19:04

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.