Skip to content

Local State Sync

yihuang edited this page Aug 31, 2023 · 15 revisions

In Cronos v1.0.12, we introduced a new set of commands to do local state sync, the full command help screen is like this:

$ cronosd snapshots --help
Manage local snapshots

Usage:
  cronosd snapshots [command]

Available Commands:
  delete      Delete a local snapshot
  dump        Dump the snapshot as portable archive format
  export      Export app state to snapshot store
  list        List local snapshots
  load        Load a snapshot archive file (.tar.gz) into snapshot store
  restore     Restore app state from local snapshot

Flags:
  -h, --help   help for snapshots

Global Flags:
      --home string         directory for config and data (default "/Users/yihuang/.cronos")
      --log_format string   The logging format (json|plain) (default "plain")
      --log_level string    The logging level (trace|debug|info|warn|error|fatal|panic) (default "info")
      --trace               print out full stack trace on errors

Use "cronosd snapshots [command] --help" for more information about a command.

Local State Sync

Before we dive into local state sync, let's understand the "normal" state sync first. After you setup state-sync in config and start the node, the node will do the following procedure:

  1. discover snapshots on the p2p network.
  2. verify the snapshot metadata by verifying the block headers between the snapshot and the trusted block height.
  3. download snapshot chunks from the p2p network.
  4. restore app state from the downloaded snapshot chunks.
  5. bootstrap cometbft state.
  6. start normal sync.

With "normal" state sync, the procedure is done automatically on startup, it works great when the state is small, but as the chain grows, the procedure becomes slow and unstable,

The new commands try to break down the procedure into smaller steps:

  1. discover and download snapshots from out-of-band communications, for example community can share the snapshots with a http server.

  2. user download the shared snapshots with whatever tools and import into local snapshot database.

    $ cronosd snapshots load /path/to/downloaded-snapshot.tar.gz
    $ cronosd snapshots list
    <height> <format>
    
  3. restore app state from the snapshot (this step is much faster with MemIAVL):

    cronosd snapshots restore <height> <format>
    

    3a. (Optional) If you want to enable versiondb together, you need to restore the versiondb from the snapshot as well:

    $ cronosd changeset restore-versiondb <height> <format>
    
  4. verify and bootstrap cometbft state based on current app state:

    cronosd tendermint bootstrap-state
    

    This step requires the statesync.* configurations in config.toml, the same as the normal state sync.

  5. start the node and sync normally.

Snapshot Provider

On the other hand, the snapshot providers can dump the local snapshots into a portable tarball using following command:

$ cronosd snapshots dump <height> <format> --output /path/to/snapshot.tar.gz

Normally the snapshots are generated automatically using config state-sync.snapshot-interval, with new commands, one can also manually export arbitrary version of state:

$ cronosd snapshots export --height <height>
$ cronosd snapshots list
<height> <format>
Clone this wiki locally