From 08a41539ba925edbae7714f7006bc85a4d34b1a8 Mon Sep 17 00:00:00 2001 From: John Martin Date: Wed, 24 Jan 2024 10:11:15 -0800 Subject: [PATCH 1/3] merge formal snapshot and snapshots docs --- .../guides/operator/formal-snapshot.mdx | 64 ------------------- docs/content/guides/operator/snapshots.mdx | 15 ++++- docs/content/sidebars/guides.js | 1 - 3 files changed, 13 insertions(+), 67 deletions(-) delete mode 100644 docs/content/guides/operator/formal-snapshot.mdx diff --git a/docs/content/guides/operator/formal-snapshot.mdx b/docs/content/guides/operator/formal-snapshot.mdx deleted file mode 100644 index c62b892924cf7..0000000000000 --- a/docs/content/guides/operator/formal-snapshot.mdx +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: Formal Snapshots -description: 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. ---- - -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. -1. **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. -1. **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: - ```yaml - state-snapshot-write-config: - object-store-config: - object-store: "GCS" - bucket: "" - google-service-account: "" - 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. -1. 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= AWS_ARCHIVE_ACCESS_KEY_ID= AWS_ARCHIVE_SECRET_ACCESS_KEY= AWS_ARCHIVE_REGION=us-west-2 \ - sui-tool download-db-snapshot --formal --epoch 200 --genesis --snapshot-bucket mysten-mainnet-formal --snapshot-bucket-type gcs --path --num-parallel-downloads 50 - ``` - -1. 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`. -1. 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/` diff --git a/docs/content/guides/operator/snapshots.mdx b/docs/content/guides/operator/snapshots.mdx index c47a56a45e179..9c2ba08362c02 100644 --- a/docs/content/guides/operator/snapshots.mdx +++ b/docs/content/guides/operator/snapshots.mdx @@ -25,6 +25,16 @@ Formal snapshots are not suitable for use if you are running an RPC node that do You can configure a Full node snapshot to generate a state snapshot at the end of each epoch. A single Full node can generate RocksDB snapshots, Formal snapshots, or both. +## 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. +1. **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. +1. **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 snapshots Full nodes do not take snapshots by default. To enable this feature you must apply specific configs to your Full node. @@ -60,8 +70,9 @@ Add an entry to the config file for `db-checkpoint-config`. Using Amazon's S3 se Add an entry to the config file for `db-checkpoint-config`. Using Amazon's S3 service as an example: ```yaml - state-snapshot-write-config: - object-store-config: + db-checkpoint-config: + state-snapshot-write-config: + object-store-config: object-store: "S3" bucket: "" aws-access-key-id: “” diff --git a/docs/content/sidebars/guides.js b/docs/content/sidebars/guides.js index cf6a9332e018f..270eab632323d 100644 --- a/docs/content/sidebars/guides.js +++ b/docs/content/sidebars/guides.js @@ -168,7 +168,6 @@ const guides = [ 'guides/operator/validator-committee', 'guides/operator/validator-tasks', 'guides/operator/node-tools', - 'guides/operator/formal-snapshot', 'guides/operator/exchange-integration', ], }, From edd22ee03cb14473af78795e48331230ebbb112e Mon Sep 17 00:00:00 2001 From: John Martin Date: Wed, 24 Jan 2024 12:16:31 -0800 Subject: [PATCH 2/3] fix config --- docs/content/guides/operator/snapshots.mdx | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/docs/content/guides/operator/snapshots.mdx b/docs/content/guides/operator/snapshots.mdx index 9c2ba08362c02..3650dfd9771b4 100644 --- a/docs/content/guides/operator/snapshots.mdx +++ b/docs/content/guides/operator/snapshots.mdx @@ -68,17 +68,16 @@ Add an entry to the config file for `db-checkpoint-config`. Using Amazon's S3 se ### Enabling Formal snapshots -Add an entry to the config file for `db-checkpoint-config`. Using Amazon's S3 service as an example: + Add an entry to the config file for `state-snapshot-write-config`. Using Amazon's S3 service as an example: ```yaml - db-checkpoint-config: - state-snapshot-write-config: - object-store-config: - object-store: "S3" - bucket: "" - aws-access-key-id: “” - aws-secret-access-key: “” - aws-region: "" - object-store-connection-limit: 200 + state-snapshot-write-config: + object-store-config: + object-store: "S3" + bucket: "" + aws-access-key-id: “” + aws-secret-access-key: “” + aws-region: "" + object-store-connection-limit: 200 ``` The configuration settings shown in the example are specific to AWS S3, but GCS, Azure Storage, and Cloudflare R2 are all supported. From c558fdc26e4a20e21e10e7911abbb9c097ae3d0e Mon Sep 17 00:00:00 2001 From: John Martin Date: Wed, 24 Jan 2024 14:37:56 -0800 Subject: [PATCH 3/3] renames --- docs/content/guides/operator/snapshots.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/content/guides/operator/snapshots.mdx b/docs/content/guides/operator/snapshots.mdx index 3650dfd9771b4..d7a4bb7b46c88 100644 --- a/docs/content/guides/operator/snapshots.mdx +++ b/docs/content/guides/operator/snapshots.mdx @@ -1,5 +1,5 @@ --- -title: Snapshots +title: Database Snapshots description: Database snapshots of the Sui network enable Full node operators a way to bootstrap a Full node without having to execute all the transactions that occurred after genesis. --- @@ -45,7 +45,7 @@ Follow these steps to change the configs for a Full node: 2. Open your fullnode.yaml config file and apply config updates as the following sections show. 3. Save the fullnode.yaml file and restart the node. -### Enabling RocksDB snapshots +### Enabling DB snapshots Add an entry to the config file for `db-checkpoint-config`. Using Amazon's S3 service as an example: ```yaml