Formal Snapshots

Formal snapshots provide a mechanism for a node to restore to a canonical state (the state of a full pruned and compacted node at the end of an epoch) at some prior point in time without having to execute all the transactions that have occurred since genesis. Unlike existing database snapshots, these formal snapshots have the following properties:

1. Minimalism: Formal snapshots currently contain only the end of epoch live object set (the set of all object versions eligible for use as input objects for future transactions). Sui 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 Sui 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 indexes, they are most immediately useful for validators and state sync Full nodes (SSFNs). 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 formal snapshots

Full nodes do not take formal snapshots by default. To enable this feature:

1. Stop your node, if it's running.
2. Open your fullnode.yaml config file.
3. Add an entry to the config file for state-snapshot-write-config. Using Google's GCS service as an example:

   state-snapshot-write-config:
     object-store-config:
       object-store: "GCS"
       bucket: "<BUCKET-NAME>"
       google-service-account: "<SERVICE-ACCOUNT-FILEPATH>"
       object-store-connection-limit: 20
    concurrency: 5
   • object-store: The remote object store to upload snapshots. Set as Google's GCS service in the example.
   • bucket: The GCS bucket name to store the snapshots.
   • google-service-account: Path to a GCS service account json file containing signing credentials.
   • aws-region: Region where buck exists.
   • object-store-connection-limit: Number of simultaneous connections to the object store.
4. Save the sui-node.yaml file and restart the node.

Restoring from formal snapshots

The full process of downloading, verifying, and restoring from a formal snapshot is handled by a single command in sui-tool. After running the snapshot restore tooling, the local node state reflects the canonical state at the end of the epoch to which you restored, at which point you can start the node normally. To restore from a snapshot:

1. Download the latest version of sui for your operating system.

2. Run sui-tool download-db-snapshot --formal, passing in the bucket name and authentication credentials as environment variables, and providing the bucket name, bucket type, epoch to restore to, and genesis blob.

      GCS_SNAPSHOT_SERVICE_ACCOUNT_FILE_PATH=<PATH-TO-SERVICE-ACCOUNT-JSON> AWS_ARCHIVE_ACCESS_KEY_ID=<YOUR-AWS-ACCESS-KEY> AWS_ARCHIVE_SECRET_ACCESS_KEY=<YOUR-AWS-SECRET-ACCESS-KEY> AWS_ARCHIVE_REGION=us-west-2 \
      sui-tool download-db-snapshot --formal --epoch 200 --genesis <PATH-TO-GENESIS-BLOB> --snapshot-bucket mysten-mainnet-formal --snapshot-bucket-type gcs --path <DB-PATH> --num-parallel-downloads 50

3. Make sure you update the ownership of the downloaded directory to the sui user (whichever linux user you run sui-node as) sudo chown -R sui:sui /opt/sui/db/authorities_db/full_node_db/live.

4. Start the Sui node.

info

When you restore a Full node from a snapshot, write it to the path /opt/sui/db/authorities_db/full_node_db. To restore a Validator node, use the path /opt/sui/db/authorities_db

GCS buckets used per environment

Mysten operated buckets. To access the Mysten operated buckets, you still need to provide valid credentials for signed access to GCS (snapshot bucket hosting) and AWS (archival hosting).

• Testnet: s3://mysten-testnet-formal/
• Mainnet: s3://mysten-mainnet-formal/