diff --git a/src/pages/cli/download.mdx b/src/pages/cli/download.mdx index c60bc6b3..98fe2039 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. +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 ```bash @@ -19,23 +21,56 @@ tempo download [flags] | --- | --- | | `--chain ` | Target network (`mainnet`, `moderato`) | | `--datadir ` | Data directory for downloaded state | -| `-u, --url ` | Download a specific snapshot URL | +| `-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 | -| `--archive` | Download an archive snapshot. Recommended for partner validators and RPC nodes. | +| `--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. 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. | +| `--force` | Overwrite existing snapshot data while preserving `discovery-secret` and `known-peers.json`. | + +## Validator Migration Guidance + +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 +tempo download --chain mainnet --minimal --force +``` + +To migrate or replace a testnet validator snapshot, run: + +```bash +tempo download --chain moderato --minimal --force +``` + +`--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 -Download the latest recommended mainnet snapshot: +Open the interactive selector for mainnet: ```bash -tempo download --chain mainnet --archive +tempo download --chain mainnet ``` -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: @@ -50,10 +85,12 @@ List available snapshots for a specific chain: tempo download --list --chain moderato ``` -Resume an interrupted download: +If the data directory has limited free disk space, disable resumable downloads and stream the snapshot directly into extraction: ```bash -tempo download --archive --resumable +tempo download --chain mainnet --minimal --resumable=false ``` +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..afdb4847 100644 --- a/src/pages/guide/node/installation.mdx +++ b/src/pages/guide/node/installation.mdx @@ -46,17 +46,38 @@ 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. 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`. + +### 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 [Mainnet] +```bash [Validator mainnet] +tempo download --chain mainnet --minimal +``` +```bash [Validator testnet] +tempo download --chain moderato --minimal +``` +```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 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 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 e2d68d69..b8032763 100644 --- a/src/pages/guide/node/rpc.mdx +++ b/src/pages/guide/node/rpc.mdx @@ -16,7 +16,7 @@ Trusted (uncertified) RPC nodes will be deprecated. To run without trusting the ```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..56d9d532 100644 --- a/src/pages/guide/node/validator-setup.mdx +++ b/src/pages/guide/node/validator-setup.mdx @@ -85,17 +85,21 @@ 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. Validators should use `--minimal` when migrating to minimal snapshots, and should keep using `--minimal` for future validator replacements. ::::code-group ```bash [Mainnet] -tempo download --chain mainnet --archive +tempo download --chain mainnet --minimal ``` ```bash [Testnet] -tempo download --chain moderato --archive +tempo download --chain moderato --minimal ``` :::: +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 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: ::::code-group