Skip to main content

Snapshots

Snapshots capture a node's view of the IOTA network at the end of an epoch.

info

While validators can enable snapshots, they are typically most valuable for full node operators. Therefore, in the following sections, we'll focus on snapshots from the perspective of full node operators.

Snapshots of the IOTA network enable full node operators a way to bootstrap a full node without having to execute all the transactions that occurred after genesis. You can upload snapshots to remote object stores like S3, Google Cloud Storage, Azure Blob Storage, and similar services. These services typically run the export process in the background so there is no degradation in performance for your full node. With snapshots stored in the cloud, you're more easily able to recover quickly from catastrophic failures in your system or hardware.

To maintain a healthy IOTA network, IOTA encourages the IOTA community to bring up additional snapshots to ensure stronger data availability across the network.

Formal snapshots​

info

Formal snapshots are not suitable for use if you are running an RPC node that does any historical data lookups. For more information on node data management, see Data Management.

Formal snapshots are database-agnostic, minimalistic snapshots containing only essential data for node restoration at a specific epoch, keeping their storage footprint small and restoration fast. Natively supported by IOTA protocol, this means the snapshot contents can be cryptographically verified against the committee's epoch-end commitment, a process that occurs automatically during restoration (unless explicitly bypassed).

The formal snapshots have the following properties:

  1. Minimalism: Formal snapshots contain the end of epoch live object set (the set of all object versions eligible for use as input objects for future transactions) plus a small per-epoch metadata file covering every epoch since genesis. IOTA syncs all other critical chain information from the chain or derives it. Thus, formal snapshots contain only the necessary data required for a node to startup at epoch boundary and participate in the network.
  2. Agnosticism: Formal snapshots are by nature agnostic to the underlying database choice or implementation of the protocol. As the live object set is protocol defined, so is the formal snapshot.
  3. Verifiability: Formal snapshots have first-class support in the core IOTA protocol. As such, they must be trustless/verifiable by the node operator upon download. To support this, the protocol signs a commitment to the live object state at end of epoch, which formal snapshots are checked against at restore time. If this verification fails, the node state is moved back to the state before the snapshot restore attempt.

Because these snapshots do not contain transaction history, they are most immediately useful for validators and state sync full nodes (SSFNs). Restoring from a formal snapshot also builds the gRPC index store by default (pass --skip-grpc-indexes to opt out), so a full node started with the gRPC API enabled serves it right away without re-indexing the restored state. You can upload snapshots to remote object stores like S3, Google Cloud Storage, Azure Blob Storage, and similar services. These services typically run the export process in the background so there is no degradation in performance for your full node. With snapshots stored in the cloud, you can recover from catastrophic failures in your system or hardware more efficiently.

Enabling snapshots​

A nodes does not take snapshots by default. To enable this feature you must apply specific configs to your node.

Follow these steps to change the configs for the node:

  1. Stop your node, if it's running.

  2. Open your fullnode.yaml file and apply config updates as the following. Using Amazon's S3 service as an example:

    state-snapshot-write-config:
       object-store-config:
          object-store: "S3"
          bucket: "`<BUCKET-NAME>`"
          aws-access-key-id: "`<ACCESS-KEY>`"
          aws-secret-access-key: "`<SHARED-KEY>`"
          aws-region: "`<BUCKET-REGION>`"
          object-store-connection-limit: 200
       concurrency: 10
    • object-store: The remote object store to upload snapshots. Set as Amazon's S3 service in the example.
    • bucket: The S3 bucket name to store the snapshots.
    • aws-access-key-id and aws-secret-access-key: AWS authentication information with write access to the bucket.
    • aws-region: Region where bucket exists.
    • object-store-connection-limit: Number of simultaneous connections to the object store.
    • concurrency: Number of concurrent uploads of snapshots to the object store.

  3. Save the fullnode.yaml file and restart the node.

Restoring a full node from snapshots​

To restore from a Formal snapshot, use the iota-tool binary. iota-tool can be downloaded along with other iota binaries. See Install IOTA for more details.

The following steps can be used to restore a node from a Formal snapshot:

  1. If it's running, stop the node.

  2. Pick your setup, network, and a snapshot epoch. Copy the resulting command and run it. The Docker command mounts $PWD/data/db and $PWD/data/config/genesis.blob, the layout used by the Docker setup, so run it from that setup's directory or adjust the mounts to your own paths:

    Loading snapshot picker…
    • --epoch / --latest: Pin a specific snapshot epoch, or always grab the most recent one.
    • --genesis: The path to the location of the network's genesis.blob.
    • --network: Network to download the snapshot for: mainnet, testnet, or devnet. Defaults to mainnet.
    • --path: Must equal the db-path from your node's configuration (default /opt/iota/db/authorities_db).
    • --skip-grpc-indexes: Skips building the gRPC index store during the restore. By default it is built from the same object stream that restores the state, so a full node started with the gRPC API enabled opens it in place instead of re-indexing the whole restored state on first start. Skip it only if the node will never serve the gRPC API.
    • --disable-progress-bar: Reports progress as a status line logged once per second instead of drawing progress bars.

Backfilling the full checkpoint summary history​

A node restored from a formal snapshot holds only the end-of-epoch checkpoint summaries (one per epoch). That is enough to run, but the node cannot serve historical checkpoint queries below its restore point, nor act as a complete summary source for peers syncing the header chain. To fill in every intermediate summary from the checkpoint archive, stop the node and run:

iota-tool backfill-checkpoint-summaries \
   --path "<PATH-TO-NODE-DB>/live" \
   --ingestion-url "https://checkpoints.<network>.iota.cafe/ingestion/historical" \
   --verbose
  • --path: The node's live database directory (the one containing checkpoints/, store/, and epochs/).
  • --ingestion-url: URL of the checkpoint archive to download summaries from — the same archive the node's state-sync fallback reads from (for example https://checkpoints.<network>.iota.cafe/ingestion/historical).
  • --num-parallel-downloads: Number of summaries to download in parallel. Defaults to a value based on the number of available cores, capped at 8.
  • --verbose: Enable verbose logging.
  • --disable-progress-bar: Reports progress as a status line logged once per second instead of drawing a progress bar.

Summaries are taken as-is from --ingestion-url without chain verification, so point it at the checkpoint archive you trust to serve this node's own chain. This only adds historical summaries below the node's existing watermarks — it never changes how far the node has synced or executed, and it never overwrites the summaries the node already has. It is safe to re-run.

IOTA Foundation managed snapshots​

The IOTA Foundation provides the public snapshot access: