Node Snapshots

Restoring from Snapshot

1. Prepare Data Directory:
   • Before running Docker for the first time, create the data directory on your host machine that will be mapped into the Docker container. This directory must match the volumes mapping in the docker-compose.yml file.
     mkdir ./reth-data
     
   • If you have previously run the node and have an existing data directory, stop the node (docker compose down), remove the contents of the existing directory (e.g. rm -rf ./reth-data/*), and proceed.
2. Choosing the chain: Use the --chain flag to select the network

   Network	--chain value
   Base Mainnet	base
   Base Sepolia	base-sepolia

3. Download Snapshot: V2 snapshots are split into many small, segmented files rather than a single archive. The CLI lists one archive snapshot because it contains all available files. The full and minimal options select progressively smaller subsets of that archive:

   Config	Flag	Mainnet size
   Minimal	--minimal	~782.5 GB
   Full	--full	~792.7 GB
   Archive	--archive	~4.3 TB
   Archive + Proofs	--archive --proofs	~4.9 TB

   • Minimal: the smallest set needed to boot (latest state and headers, plus the minimum required history). Use it for the fastest, smallest download when you don’t need historical data.
   • Full: full-node data matching the default full-node prune settings (state, headers, and a bounded window of transactions, receipts, and history). Use it for a standard full node without keeping the entire archive.
   • Archive: everything available, with all transactions, receipts, and account/storage history and no pruning. Use it when you need complete historical data (e.g. archive queries, indexing).
   • Archive + Proofs: everything in Archive, plus the proofs database for the historical proofs ExEx. Use it if you run the ExEx and want to skip the 24-48 hour backfill.
   Sizes are approximate Base Mainnet figures and grow over time. Check chain.base.org/snapshots for current sizes.
   Ensure you have enough free disk space to download the snapshot and extract its contents. The extracted data will be significantly larger than the archive.
   The above presets are convenient defaults that are available at chain.base.org/snapshots. You may still configure custom pruning flags with the RETH_PRUNING_ARGS variable in .env.mainnet (or .env.sepolia). It is required to download the archival snapshot and then configure your custom pruning args.
   # Minimal node on Base Mainnet
   base-reth-node download --minimal --datadir ./reth-data --chain base --resumable
   
   # Full node on Base Sepolia
   base-reth-node download --full --datadir ./reth-data --chain base-sepolia --resumable
   
   # Archive node with proofs on Base Mainnet
   base-reth-node download --archive --proofs --datadir ./reth-data --chain base --resumable
   
   Alternatively, for archival nodes only, you may run base-reth-node db migrate-v2. However, this is expected to take much longer than downloading. --resumable is also not supported in migrate-v2.
4. (Optional) - tuning download concurrency: The --download-concurrency flag controls how many simultaneous HTTP downloads run across the whole snapshot job. It defaults to 8, which is a good baseline for most machines. If you have high-end hardware, you can safely increase it to speed up the download. A good rule of thumb is 2× the number of physical CPU cores:
   # Example: a 16 physical-core machine
   base-reth-node download --full --datadir ./reth-data --chain base --download-concurrency 32
   
5. Start the Node: Now that the snapshot data is in place, return the root of your Base node folder and start the node:
   cd ..
   
   # Pull the published image
   docker compose up
   
   # Or compile the base/base tree locally
   docker compose up --build
   
   Your node should begin syncing from the last block in the snapshot.
6. Verify: Monitor the node logs (docker compose logs -f <service_name>) or use the sync monitoring command to ensure the node starts syncing from the snapshot’s block height.

Proofs Snapshots

base-reth-node download --archive --proofs --datadir ./reth-data --chain base --resumable

FAQ