From 89cf9e1e9535483b630a1be8fa8be0a266392ba1 Mon Sep 17 00:00:00 2001 From: Emma Jamieson-Hoare Date: Tue, 12 May 2026 17:16:19 +0100 Subject: [PATCH 1/7] docs: update validator snapshot guidance --- src/pages/cli/download.mdx | 25 +++++++++++++++++------- src/pages/guide/node/installation.mdx | 14 ++++++++++--- src/pages/guide/node/rpc.mdx | 2 +- src/pages/guide/node/validator-setup.mdx | 6 +++--- 4 files changed, 33 insertions(+), 14 deletions(-) diff --git a/src/pages/cli/download.mdx b/src/pages/cli/download.mdx index c60bc6b3..2e6cfa2b 100644 --- a/src/pages/cli/download.mdx +++ b/src/pages/cli/download.mdx @@ -7,6 +7,8 @@ description: Download chain snapshots for faster initial sync of a Tempo node. Download chain snapshots for faster initial sync. Fetches MDBX state and static files, and generates a `reth.toml` prune config for the target data directory. +By default, `tempo download` downloads a minimal snapshot, which is recommended for validators to save disk space. Use archive snapshots for RPC providers, indexers, and other workloads that need complete historical data. + ## Usage ```bash @@ -19,23 +21,30 @@ tempo download [flags] | --- | --- | | `--chain ` | Target network (`mainnet`, `moderato`) | | `--datadir ` | Data directory for downloaded state | -| `-u, --url ` | Download a specific snapshot URL | +| `--manifest-url ` | Download a specific modular snapshot manifest URL | | `--list` | List available snapshots | | `--resumable` | Resume an interrupted download | -| `--archive` | Download an archive snapshot. Recommended for partner validators and RPC nodes. | +| `--minimal` | Download a minimal snapshot. This is the default and is recommended for validators. | +| `--archive` | Download an archive snapshot. Recommended for RPC providers and indexers. | ## Examples -Download the latest recommended mainnet snapshot: +Download the latest mainnet validator snapshot: ```bash -tempo download --chain mainnet --archive +tempo download --chain mainnet +``` + +Download the latest testnet validator snapshot: + +```bash +tempo download --chain moderato ``` -Download the latest recommended testnet snapshot: +Download an archive snapshot for an RPC node: ```bash -tempo download --chain moderato --archive +tempo download --chain mainnet --archive ``` List available snapshots: @@ -53,7 +62,9 @@ tempo download --list --chain moderato Resume an interrupted download: ```bash -tempo download --archive --resumable +tempo download --resumable ``` +Use the [snapshots viewer](https://snapshots.tempo.xyz/) to compare snapshot profiles and copy generated commands. + Then start your node with [`tempo node`](/cli/node). diff --git a/src/pages/guide/node/installation.mdx b/src/pages/guide/node/installation.mdx index 318d42c5..664ff040 100644 --- a/src/pages/guide/node/installation.mdx +++ b/src/pages/guide/node/installation.mdx @@ -46,17 +46,25 @@ docker logs tempo ## Snapshots -Downloading a snapshot lets your node skip syncing from genesis and start participating much faster. This is recommended for both RPC nodes and validators. +Downloading a snapshot lets your node skip syncing from genesis and start participating much faster. By default, `tempo download` downloads a minimal snapshot, which is recommended for validators to save disk space. RPC providers, indexers, and other workloads that need complete historical data should use archive snapshots. ::::code-group -```bash [Mainnet] +```bash [Validator mainnet] +tempo download --chain mainnet +``` +```bash [Validator testnet] +tempo download --chain moderato +``` +```bash [Archive mainnet] tempo download --chain mainnet --archive ``` -```bash [Testnet] +```bash [Archive testnet] tempo download --chain moderato --archive ``` :::: +Use [snapshots.tempo.xyz](https://snapshots.tempo.xyz/) to compare minimal and archive sizes or copy generated `tempo download` commands. + ## Verifying Releases All release artifacts are cryptographically signed. We recommend verifying signatures before running any binary. diff --git a/src/pages/guide/node/rpc.mdx b/src/pages/guide/node/rpc.mdx index 95c6e1c1..c9fd33df 100644 --- a/src/pages/guide/node/rpc.mdx +++ b/src/pages/guide/node/rpc.mdx @@ -12,7 +12,7 @@ RPC nodes provide API access to the Tempo network without participating in conse ```bash /dev/null/quickstart.sh#L1-15 # Download snapshot (this will help you sync much faster) -tempo download --archive +tempo download --chain mainnet --archive # Run node tempo node \ diff --git a/src/pages/guide/node/validator-setup.mdx b/src/pages/guide/node/validator-setup.mdx index ebf392d4..223c7e71 100644 --- a/src/pages/guide/node/validator-setup.mdx +++ b/src/pages/guide/node/validator-setup.mdx @@ -85,14 +85,14 @@ Once the Tempo team adds your validator on-chain, it will enter the active set i The process for running a validator node is very similar to [running a full node](/guide/node/rpc). -You should start by downloading the latest snapshot. Downloading the snapshot allows your validator to start participating in consensus much faster. +You should start by downloading the latest snapshot. By default, `tempo download` downloads a minimal snapshot, which allows your validator to start participating in consensus much faster while avoiding archive data that validators do not need. ::::code-group ```bash [Mainnet] -tempo download --chain mainnet --archive +tempo download --chain mainnet ``` ```bash [Testnet] -tempo download --chain moderato --archive +tempo download --chain moderato ``` :::: From 3d663b0b04f3e6af7af84668154cc64d2fbd980a Mon Sep 17 00:00:00 2001 From: Emma Jamieson-Hoare Date: Wed, 20 May 2026 12:39:24 +0100 Subject: [PATCH 2/7] docs: clarify validator snapshot migration guidance --- src/pages/cli/download.mdx | 45 +++++++++++++++++++----- src/pages/guide/node/installation.mdx | 22 ++++++++---- src/pages/guide/node/validator-setup.mdx | 18 +++++++--- 3 files changed, 65 insertions(+), 20 deletions(-) diff --git a/src/pages/cli/download.mdx b/src/pages/cli/download.mdx index 2e6cfa2b..2f2456f0 100644 --- a/src/pages/cli/download.mdx +++ b/src/pages/cli/download.mdx @@ -7,7 +7,7 @@ description: Download chain snapshots for faster initial sync of a Tempo node. Download chain snapshots for faster initial sync. Fetches MDBX state and static files, and generates a `reth.toml` prune config for the target data directory. -By default, `tempo download` downloads a minimal snapshot, which is recommended for validators to save disk space. Use archive snapshots for RPC providers, indexers, and other workloads that need complete historical data. +By default, `tempo download` opens an interactive component selector. The selector starts on the Minimal preset, which is recommended for validators that have migrated to minimal snapshots. Validators that have not migrated yet should use Archive, as should RPC providers, indexers, and other workloads that need complete historical data. ## Usage @@ -21,24 +21,45 @@ tempo download [flags] | --- | --- | | `--chain ` | Target network (`mainnet`, `moderato`) | | `--datadir ` | Data directory for downloaded state | +| `-u, --url ` | Download a single legacy snapshot archive URL | | `--manifest-url ` | Download a specific modular snapshot manifest URL | | `--list` | List available snapshots | -| `--resumable` | Resume an interrupted download | -| `--minimal` | Download a minimal snapshot. This is the default and is recommended for validators. | -| `--archive` | Download an archive snapshot. Recommended for RPC providers and indexers. | +| `--resumable[=]` | Download to disk before extraction so interrupted downloads can resume. Enabled by default. | +| `--minimal` | Download the minimal component set. Use this for validators that have migrated to minimal snapshots. | +| `--full` | Download the full node component set. | +| `--archive`, `--all` | Download all available components. Recommended for RPC providers and indexers. | +| `-y, --non-interactive` | Skip the interactive selector and download the minimal component set unless explicit component flags are provided. | +| `--force` | Overwrite existing snapshot data while preserving `discovery-secret` and `known-peers.json`. | + +## Validator Migration Guidance + +Choose the snapshot profile that matches the validator's migration state: + +| Validator state | Snapshot profile | +| --- | --- | +| Already migrated to minimal snapshots | Use Minimal with `--minimal`, or accept the Minimal preset in the interactive selector. | +| Not migrated to minimal snapshots yet | Use Archive with `--archive` until the migration is complete. | + +When replacing snapshot data in an existing data directory, add `--force` after selecting the correct profile. This clears old snapshot files while preserving `discovery-secret` and `known-peers.json`. ## Examples -Download the latest mainnet validator snapshot: +Open the interactive selector for mainnet: ```bash tempo download --chain mainnet ``` -Download the latest testnet validator snapshot: +Download a minimal mainnet validator snapshot after migration: + +```bash +tempo download --chain mainnet --minimal +``` + +Download an archive mainnet validator snapshot before migration: ```bash -tempo download --chain moderato +tempo download --chain mainnet --archive ``` Download an archive snapshot for an RPC node: @@ -47,6 +68,12 @@ Download an archive snapshot for an RPC node: tempo download --chain mainnet --archive ``` +Replace existing snapshot data after choosing the correct profile: + +```bash +tempo download --chain mainnet --minimal --force +``` + List available snapshots: ```bash @@ -59,10 +86,10 @@ List available snapshots for a specific chain: tempo download --list --chain moderato ``` -Resume an interrupted download: +Disable resumable downloads and stream archives directly into extraction: ```bash -tempo download --resumable +tempo download --chain mainnet --minimal --resumable=false ``` Use the [snapshots viewer](https://snapshots.tempo.xyz/) to compare snapshot profiles and copy generated commands. diff --git a/src/pages/guide/node/installation.mdx b/src/pages/guide/node/installation.mdx index 664ff040..a1ff3ff4 100644 --- a/src/pages/guide/node/installation.mdx +++ b/src/pages/guide/node/installation.mdx @@ -46,14 +46,20 @@ docker logs tempo ## Snapshots -Downloading a snapshot lets your node skip syncing from genesis and start participating much faster. By default, `tempo download` downloads a minimal snapshot, which is recommended for validators to save disk space. RPC providers, indexers, and other workloads that need complete historical data should use archive snapshots. +Downloading a snapshot lets your node skip syncing from genesis and start participating much faster. By default, `tempo download` opens an interactive component selector. Validators that have migrated to minimal snapshots should use Minimal. Validators that have not migrated yet should use Archive, as should RPC providers, indexers, and other workloads that need complete historical data. ::::code-group -```bash [Validator mainnet] -tempo download --chain mainnet +```bash [Migrated mainnet] +tempo download --chain mainnet --minimal ``` -```bash [Validator testnet] -tempo download --chain moderato +```bash [Migrated testnet] +tempo download --chain moderato --minimal +``` +```bash [Not migrated mainnet] +tempo download --chain mainnet --archive +``` +```bash [Not migrated testnet] +tempo download --chain moderato --archive ``` ```bash [Archive mainnet] tempo download --chain mainnet --archive @@ -63,7 +69,11 @@ tempo download --chain moderato --archive ``` :::: -Use [snapshots.tempo.xyz](https://snapshots.tempo.xyz/) to compare minimal and archive sizes or copy generated `tempo download` commands. +Use [snapshots.tempo.xyz](https://snapshots.tempo.xyz/) to compare snapshot profiles or copy generated `tempo download` commands. + +:::note[Replacing existing snapshot data] +When replacing snapshot data in an existing data directory, add `--force` after selecting the right profile. `--force` overwrites snapshot data but preserves `discovery-secret` and `known-peers.json`. +::: ## Verifying Releases diff --git a/src/pages/guide/node/validator-setup.mdx b/src/pages/guide/node/validator-setup.mdx index 223c7e71..ae2949ff 100644 --- a/src/pages/guide/node/validator-setup.mdx +++ b/src/pages/guide/node/validator-setup.mdx @@ -85,17 +85,25 @@ Once the Tempo team adds your validator on-chain, it will enter the active set i The process for running a validator node is very similar to [running a full node](/guide/node/rpc). -You should start by downloading the latest snapshot. By default, `tempo download` downloads a minimal snapshot, which allows your validator to start participating in consensus much faster while avoiding archive data that validators do not need. +You should start by downloading the latest snapshot. If your validator has migrated to minimal snapshots, use Minimal. If it has not migrated yet, use Archive until that migration is complete. ::::code-group -```bash [Mainnet] -tempo download --chain mainnet +```bash [Migrated mainnet] +tempo download --chain mainnet --minimal ``` -```bash [Testnet] -tempo download --chain moderato +```bash [Migrated testnet] +tempo download --chain moderato --minimal +``` +```bash [Not migrated mainnet] +tempo download --chain mainnet --archive +``` +```bash [Not migrated testnet] +tempo download --chain moderato --archive ``` :::: +If you are replacing snapshot data in an existing data directory, add `--force` after the profile flag. This clears old snapshot files while preserving `discovery-secret` and `known-peers.json`. + Once you've downloaded the snapshot and have been whitelisted on-chain, you can proceed to run the validator node: ::::code-group From e494767053ceb2d192cd2de6ba991b7c895a965e Mon Sep 17 00:00:00 2001 From: Emma Jamieson-Hoare Date: Wed, 20 May 2026 12:43:37 +0100 Subject: [PATCH 3/7] docs: add snapshot profile self-check --- src/pages/cli/download.mdx | 4 ++++ src/pages/guide/node/installation.mdx | 4 ++++ src/pages/guide/node/validator-setup.mdx | 2 ++ 3 files changed, 10 insertions(+) diff --git a/src/pages/cli/download.mdx b/src/pages/cli/download.mdx index 2f2456f0..ae0c6eed 100644 --- a/src/pages/cli/download.mdx +++ b/src/pages/cli/download.mdx @@ -42,6 +42,10 @@ Choose the snapshot profile that matches the validator's migration state: When replacing snapshot data in an existing data directory, add `--force` after selecting the correct profile. This clears old snapshot files while preserving `discovery-secret` and `known-peers.json`. +:::note[Unsure which profile to use?] +If you are unsure which pruning configuration your validator is running, reach out to the Tempo team before replacing snapshot data. To check it yourself, inspect the node startup logs for the `Loaded storage settings` line and its `pruning_mode` field. Use `--minimal` only when `pruning_mode` is `minimal`; otherwise use `--archive` until the Tempo team confirms your validator has migrated. +::: + ## Examples Open the interactive selector for mainnet: diff --git a/src/pages/guide/node/installation.mdx b/src/pages/guide/node/installation.mdx index a1ff3ff4..498ade5d 100644 --- a/src/pages/guide/node/installation.mdx +++ b/src/pages/guide/node/installation.mdx @@ -75,6 +75,10 @@ Use [snapshots.tempo.xyz](https://snapshots.tempo.xyz/) to compare snapshot prof When replacing snapshot data in an existing data directory, add `--force` after selecting the right profile. `--force` overwrites snapshot data but preserves `discovery-secret` and `known-peers.json`. ::: +:::note[Unsure which profile to use?] +If you are unsure which pruning configuration your validator is running, reach out to the Tempo team before replacing snapshot data. To check it yourself, inspect the node startup logs for the `Loaded storage settings` line and its `pruning_mode` field. Use Minimal only when `pruning_mode` is `minimal`; otherwise use Archive until the Tempo team confirms your validator has migrated. +::: + ## Verifying Releases All release artifacts are cryptographically signed. We recommend verifying signatures before running any binary. diff --git a/src/pages/guide/node/validator-setup.mdx b/src/pages/guide/node/validator-setup.mdx index ae2949ff..c82f518a 100644 --- a/src/pages/guide/node/validator-setup.mdx +++ b/src/pages/guide/node/validator-setup.mdx @@ -104,6 +104,8 @@ tempo download --chain moderato --archive If you are replacing snapshot data in an existing data directory, add `--force` after the profile flag. This clears old snapshot files while preserving `discovery-secret` and `known-peers.json`. +If you are unsure which pruning configuration your validator is running, reach out to the Tempo team before replacing snapshot data. To check it yourself, inspect the node startup logs for the `Loaded storage settings` line and its `pruning_mode` field. Use `--minimal` only when `pruning_mode` is `minimal`; otherwise use `--archive` until the Tempo team confirms your validator has migrated. + Once you've downloaded the snapshot and have been whitelisted on-chain, you can proceed to run the validator node: ::::code-group From ffb3b2148d4867a4a3567821d4d1e359190e5465 Mon Sep 17 00:00:00 2001 From: Emma Jamieson-Hoare Date: Wed, 20 May 2026 13:01:46 +0100 Subject: [PATCH 4/7] docs: simplify snapshot profile guidance --- src/pages/cli/download.mdx | 31 ++++++++---------------- src/pages/guide/node/installation.mdx | 14 +++-------- src/pages/guide/node/validator-setup.mdx | 14 +++-------- 3 files changed, 18 insertions(+), 41 deletions(-) diff --git a/src/pages/cli/download.mdx b/src/pages/cli/download.mdx index ae0c6eed..7cb96c66 100644 --- a/src/pages/cli/download.mdx +++ b/src/pages/cli/download.mdx @@ -7,7 +7,7 @@ description: Download chain snapshots for faster initial sync of a Tempo node. Download chain snapshots for faster initial sync. Fetches MDBX state and static files, and generates a `reth.toml` prune config for the target data directory. -By default, `tempo download` opens an interactive component selector. The selector starts on the Minimal preset, which is recommended for validators that have migrated to minimal snapshots. Validators that have not migrated yet should use Archive, as should RPC providers, indexers, and other workloads that need complete historical data. +Running `tempo download` without a snapshot profile opens an interactive component selector. Passing a profile flag such as `--minimal` or `--archive` skips the selector. Validators should use `--minimal` for migrations and future replacements. RPC providers, indexers, and other workloads that need complete historical data should use `--archive`. ## Usage @@ -25,45 +25,34 @@ tempo download [flags] | `--manifest-url ` | Download a specific modular snapshot manifest URL | | `--list` | List available snapshots | | `--resumable[=]` | Download to disk before extraction so interrupted downloads can resume. Enabled by default. | -| `--minimal` | Download the minimal component set. Use this for validators that have migrated to minimal snapshots. | +| `--minimal` | Download the minimal component set without opening the interactive selector. Use this for validator migrations and future validator replacements. | | `--full` | Download the full node component set. | -| `--archive`, `--all` | Download all available components. Recommended for RPC providers and indexers. | +| `--archive`, `--all` | Download all available components without opening the interactive selector. Recommended for RPC providers and indexers. | | `-y, --non-interactive` | Skip the interactive selector and download the minimal component set unless explicit component flags are provided. | | `--force` | Overwrite existing snapshot data while preserving `discovery-secret` and `known-peers.json`. | ## Validator Migration Guidance -Choose the snapshot profile that matches the validator's migration state: - -| Validator state | Snapshot profile | -| --- | --- | -| Already migrated to minimal snapshots | Use Minimal with `--minimal`, or accept the Minimal preset in the interactive selector. | -| Not migrated to minimal snapshots yet | Use Archive with `--archive` until the migration is complete. | +Validators should use `--minimal` when migrating to minimal snapshots, and should keep using `--minimal` for future validator replacements. RPC providers, indexers, and other workloads that need complete historical data should use `--archive`. When replacing snapshot data in an existing data directory, add `--force` after selecting the correct profile. This clears old snapshot files while preserving `discovery-secret` and `known-peers.json`. :::note[Unsure which profile to use?] -If you are unsure which pruning configuration your validator is running, reach out to the Tempo team before replacing snapshot data. To check it yourself, inspect the node startup logs for the `Loaded storage settings` line and its `pruning_mode` field. Use `--minimal` only when `pruning_mode` is `minimal`; otherwise use `--archive` until the Tempo team confirms your validator has migrated. +If you are unsure which pruning configuration your validator is running, reach out to the Tempo team before replacing snapshot data. To check whether an existing validator is already migrated, inspect the node startup logs for the `Loaded storage settings` line and its `pruning_mode` field. If `pruning_mode` is `minimal`, no action is needed unless you are replacing the node. ::: ## Examples -Open the interactive selector for mainnet: +Download the latest recommended mainnet snapshot: ```bash tempo download --chain mainnet ``` -Download a minimal mainnet validator snapshot after migration: +Migrate or replace a mainnet validator snapshot: ```bash -tempo download --chain mainnet --minimal -``` - -Download an archive mainnet validator snapshot before migration: - -```bash -tempo download --chain mainnet --archive +tempo download --chain mainnet --minimal --force ``` Download an archive snapshot for an RPC node: @@ -72,10 +61,10 @@ Download an archive snapshot for an RPC node: tempo download --chain mainnet --archive ``` -Replace existing snapshot data after choosing the correct profile: +Migrate or replace a testnet validator snapshot: ```bash -tempo download --chain mainnet --minimal --force +tempo download --chain moderato --minimal --force ``` List available snapshots: diff --git a/src/pages/guide/node/installation.mdx b/src/pages/guide/node/installation.mdx index 498ade5d..7ce04def 100644 --- a/src/pages/guide/node/installation.mdx +++ b/src/pages/guide/node/installation.mdx @@ -46,21 +46,15 @@ docker logs tempo ## Snapshots -Downloading a snapshot lets your node skip syncing from genesis and start participating much faster. By default, `tempo download` opens an interactive component selector. Validators that have migrated to minimal snapshots should use Minimal. Validators that have not migrated yet should use Archive, as should RPC providers, indexers, and other workloads that need complete historical data. +Downloading a snapshot lets your node skip syncing from genesis and start participating much faster. Validators should use `--minimal` when migrating to minimal snapshots, and should keep using `--minimal` for future validator replacements. RPC providers, indexers, and other workloads that need complete historical data should use `--archive`. ::::code-group -```bash [Migrated mainnet] +```bash [Validator mainnet] tempo download --chain mainnet --minimal ``` -```bash [Migrated testnet] +```bash [Validator testnet] tempo download --chain moderato --minimal ``` -```bash [Not migrated mainnet] -tempo download --chain mainnet --archive -``` -```bash [Not migrated testnet] -tempo download --chain moderato --archive -``` ```bash [Archive mainnet] tempo download --chain mainnet --archive ``` @@ -76,7 +70,7 @@ When replacing snapshot data in an existing data directory, add `--force` after ::: :::note[Unsure which profile to use?] -If you are unsure which pruning configuration your validator is running, reach out to the Tempo team before replacing snapshot data. To check it yourself, inspect the node startup logs for the `Loaded storage settings` line and its `pruning_mode` field. Use Minimal only when `pruning_mode` is `minimal`; otherwise use Archive until the Tempo team confirms your validator has migrated. +If you are unsure which pruning configuration your validator is running, reach out to the Tempo team before replacing snapshot data. To check whether an existing validator is already migrated, inspect the node startup logs for the `Loaded storage settings` line and its `pruning_mode` field. If `pruning_mode` is `minimal`, no action is needed unless you are replacing the node. ::: ## Verifying Releases diff --git a/src/pages/guide/node/validator-setup.mdx b/src/pages/guide/node/validator-setup.mdx index c82f518a..56d9d532 100644 --- a/src/pages/guide/node/validator-setup.mdx +++ b/src/pages/guide/node/validator-setup.mdx @@ -85,26 +85,20 @@ Once the Tempo team adds your validator on-chain, it will enter the active set i The process for running a validator node is very similar to [running a full node](/guide/node/rpc). -You should start by downloading the latest snapshot. If your validator has migrated to minimal snapshots, use Minimal. If it has not migrated yet, use Archive until that migration is complete. +You should start by downloading the latest snapshot. Validators should use `--minimal` when migrating to minimal snapshots, and should keep using `--minimal` for future validator replacements. ::::code-group -```bash [Migrated mainnet] +```bash [Mainnet] tempo download --chain mainnet --minimal ``` -```bash [Migrated testnet] +```bash [Testnet] tempo download --chain moderato --minimal ``` -```bash [Not migrated mainnet] -tempo download --chain mainnet --archive -``` -```bash [Not migrated testnet] -tempo download --chain moderato --archive -``` :::: If you are replacing snapshot data in an existing data directory, add `--force` after the profile flag. This clears old snapshot files while preserving `discovery-secret` and `known-peers.json`. -If you are unsure which pruning configuration your validator is running, reach out to the Tempo team before replacing snapshot data. To check it yourself, inspect the node startup logs for the `Loaded storage settings` line and its `pruning_mode` field. Use `--minimal` only when `pruning_mode` is `minimal`; otherwise use `--archive` until the Tempo team confirms your validator has migrated. +If you are unsure which pruning configuration your validator is running, reach out to the Tempo team before replacing snapshot data. To check whether an existing validator is already migrated, inspect the node startup logs for the `Loaded storage settings` line and its `pruning_mode` field. If `pruning_mode` is `minimal`, no action is needed unless you are replacing the node. Once you've downloaded the snapshot and have been whitelisted on-chain, you can proceed to run the validator node: From 325e1060c72d15d54a8190555e6017cef473a7e3 Mon Sep 17 00:00:00 2001 From: Emma Jamieson-Hoare Date: Wed, 20 May 2026 14:45:07 +0100 Subject: [PATCH 5/7] docs: address snapshot download review feedback --- src/pages/cli/download.mdx | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/src/pages/cli/download.mdx b/src/pages/cli/download.mdx index 7cb96c66..f6022cb4 100644 --- a/src/pages/cli/download.mdx +++ b/src/pages/cli/download.mdx @@ -7,7 +7,7 @@ description: Download chain snapshots for faster initial sync of a Tempo node. Download chain snapshots for faster initial sync. Fetches MDBX state and static files, and generates a `reth.toml` prune config for the target data directory. -Running `tempo download` without a snapshot profile opens an interactive component selector. Passing a profile flag such as `--minimal` or `--archive` skips the selector. Validators should use `--minimal` for migrations and future replacements. RPC providers, indexers, and other workloads that need complete historical data should use `--archive`. +Running `tempo download` without a snapshot profile opens an interactive component selector. Passing a profile flag such as `--minimal` or `--archive` skips the selector. Validators should use `--minimal`. RPC providers, indexers, and other workloads that need complete historical data should use `--archive`. ## Usage @@ -33,7 +33,7 @@ tempo download [flags] ## Validator Migration Guidance -Validators should use `--minimal` when migrating to minimal snapshots, and should keep using `--minimal` for future validator replacements. RPC providers, indexers, and other workloads that need complete historical data should use `--archive`. +Validators should use `--minimal` when migrating to minimal snapshots, and should keep using `--minimal` for future validator replacements. When replacing snapshot data in an existing data directory, add `--force` after selecting the correct profile. This clears old snapshot files while preserving `discovery-secret` and `known-peers.json`. @@ -43,7 +43,7 @@ If you are unsure which pruning configuration your validator is running, reach o ## Examples -Download the latest recommended mainnet snapshot: +Open the interactive selector for mainnet: ```bash tempo download --chain mainnet @@ -55,16 +55,16 @@ Migrate or replace a mainnet validator snapshot: tempo download --chain mainnet --minimal --force ``` -Download an archive snapshot for an RPC node: +Migrate or replace a testnet validator snapshot: ```bash -tempo download --chain mainnet --archive +tempo download --chain moderato --minimal --force ``` -Migrate or replace a testnet validator snapshot: +Download an archive snapshot for an RPC node: ```bash -tempo download --chain moderato --minimal --force +tempo download --chain mainnet --archive ``` List available snapshots: @@ -79,7 +79,7 @@ List available snapshots for a specific chain: tempo download --list --chain moderato ``` -Disable resumable downloads and stream archives directly into extraction: +If the data directory has limited free disk space, disable resumable downloads and stream the snapshot directly into extraction: ```bash tempo download --chain mainnet --minimal --resumable=false From bfa94a86869ed8e34bcd71ee98c2e3d9f6acb43e Mon Sep 17 00:00:00 2001 From: Emma Jamieson-Hoare Date: Wed, 20 May 2026 16:20:47 +0100 Subject: [PATCH 6/7] docs: clarify validator snapshot guidance --- src/pages/cli/download.mdx | 32 +++++++++++++-------------- src/pages/guide/node/installation.mdx | 9 ++++---- 2 files changed, 20 insertions(+), 21 deletions(-) diff --git a/src/pages/cli/download.mdx b/src/pages/cli/download.mdx index f6022cb4..db6f545b 100644 --- a/src/pages/cli/download.mdx +++ b/src/pages/cli/download.mdx @@ -25,7 +25,7 @@ tempo download [flags] | `--manifest-url ` | Download a specific modular snapshot manifest URL | | `--list` | List available snapshots | | `--resumable[=]` | Download to disk before extraction so interrupted downloads can resume. Enabled by default. | -| `--minimal` | Download the minimal component set without opening the interactive selector. Use this for validator migrations and future validator replacements. | +| `--minimal` | Download the minimal component set without opening the interactive selector. Validators should use this profile. | | `--full` | Download the full node component set. | | `--archive`, `--all` | Download all available components without opening the interactive selector. Recommended for RPC providers and indexers. | | `-y, --non-interactive` | Skip the interactive selector and download the minimal component set unless explicit component flags are provided. | @@ -33,32 +33,32 @@ tempo download [flags] ## Validator Migration Guidance -Validators should use `--minimal` when migrating to minimal snapshots, and should keep using `--minimal` for future validator replacements. +Validators should use the minimal snapshot profile, even if the previous validator data directory used a different snapshot profile. -When replacing snapshot data in an existing data directory, add `--force` after selecting the correct profile. This clears old snapshot files while preserving `discovery-secret` and `known-peers.json`. - -:::note[Unsure which profile to use?] -If you are unsure which pruning configuration your validator is running, reach out to the Tempo team before replacing snapshot data. To check whether an existing validator is already migrated, inspect the node startup logs for the `Loaded storage settings` line and its `pruning_mode` field. If `pruning_mode` is `minimal`, no action is needed unless you are replacing the node. -::: - -## Examples - -Open the interactive selector for mainnet: +To migrate or replace a mainnet validator snapshot, run: ```bash -tempo download --chain mainnet +tempo download --chain mainnet --minimal --force ``` -Migrate or replace a mainnet validator snapshot: +To migrate or replace a testnet validator snapshot, run: ```bash -tempo download --chain mainnet --minimal --force +tempo download --chain moderato --minimal --force ``` -Migrate or replace a testnet validator snapshot: +`--force` clears old snapshot files in the target data directory while preserving `discovery-secret` and `known-peers.json`. + +:::note[Unsure which profile to use?] +If you are unsure which pruning configuration your validator is running, reach out to the Tempo team before replacing snapshot data. +::: + +## Examples + +Open the interactive selector for mainnet: ```bash -tempo download --chain moderato --minimal --force +tempo download --chain mainnet ``` Download an archive snapshot for an RPC node: diff --git a/src/pages/guide/node/installation.mdx b/src/pages/guide/node/installation.mdx index 7ce04def..5cf3f63a 100644 --- a/src/pages/guide/node/installation.mdx +++ b/src/pages/guide/node/installation.mdx @@ -46,7 +46,10 @@ docker logs tempo ## Snapshots -Downloading a snapshot lets your node skip syncing from genesis and start participating much faster. Validators should use `--minimal` when migrating to minimal snapshots, and should keep using `--minimal` for future validator replacements. RPC providers, indexers, and other workloads that need complete historical data should use `--archive`. +Downloading a snapshot lets your node skip syncing from genesis and start participating much faster. Choose the snapshot profile based on what the node does: + +- Validators should use `--minimal`. +- RPC providers, indexers, and other workloads that need complete historical data should use `--archive`. ::::code-group ```bash [Validator mainnet] @@ -69,10 +72,6 @@ Use [snapshots.tempo.xyz](https://snapshots.tempo.xyz/) to compare snapshot prof When replacing snapshot data in an existing data directory, add `--force` after selecting the right profile. `--force` overwrites snapshot data but preserves `discovery-secret` and `known-peers.json`. ::: -:::note[Unsure which profile to use?] -If you are unsure which pruning configuration your validator is running, reach out to the Tempo team before replacing snapshot data. To check whether an existing validator is already migrated, inspect the node startup logs for the `Loaded storage settings` line and its `pruning_mode` field. If `pruning_mode` is `minimal`, no action is needed unless you are replacing the node. -::: - ## Verifying Releases All release artifacts are cryptographically signed. We recommend verifying signatures before running any binary. From 7343c2be8ad72da1cd94e7d2db12b289047d7697 Mon Sep 17 00:00:00 2001 From: Emma Jamieson-Hoare Date: Wed, 20 May 2026 18:06:25 +0100 Subject: [PATCH 7/7] docs: explain minimal snapshot mode --- src/pages/cli/download.mdx | 6 ++++++ src/pages/guide/node/installation.mdx | 6 ++++++ 2 files changed, 12 insertions(+) diff --git a/src/pages/cli/download.mdx b/src/pages/cli/download.mdx index db6f545b..98fe2039 100644 --- a/src/pages/cli/download.mdx +++ b/src/pages/cli/download.mdx @@ -35,6 +35,12 @@ tempo download [flags] Validators should use the minimal snapshot profile, even if the previous validator data directory used a different snapshot profile. +### What is Minimal Mode? + +Minimal Mode is a Reth storage profile for nodes that need to follow the chain and serve recent state, such as validators. It keeps disk usage low by pruning older historical data. If the node serves historical RPC, indexing, archive, or tracing workloads, use `--archive` instead. + +See Reth's [Minimal Storage Mode](https://reth.rs/run/storage/minimal/) docs for the storage trade-offs. + To migrate or replace a mainnet validator snapshot, run: ```bash diff --git a/src/pages/guide/node/installation.mdx b/src/pages/guide/node/installation.mdx index 5cf3f63a..afdb4847 100644 --- a/src/pages/guide/node/installation.mdx +++ b/src/pages/guide/node/installation.mdx @@ -51,6 +51,12 @@ Downloading a snapshot lets your node skip syncing from genesis and start partic - Validators should use `--minimal`. - RPC providers, indexers, and other workloads that need complete historical data should use `--archive`. +### What is Minimal Mode? + +Minimal Mode is a Reth storage profile for nodes that need to follow the chain and serve recent state, such as validators. It keeps disk usage low by pruning older historical data. If the node serves historical RPC, indexing, archive, or tracing workloads, use `--archive` instead. + +See Reth's [Minimal Storage Mode](https://reth.rs/run/storage/minimal/) docs for the storage trade-offs. + ::::code-group ```bash [Validator mainnet] tempo download --chain mainnet --minimal