From 716ebe459fa7efdec911810ecbeb64e44c56532d Mon Sep 17 00:00:00 2001 From: William Law Date: Mon, 20 Jul 2026 15:02:11 -0400 Subject: [PATCH 1/8] feat(v2-snapshots): add docs for v2-storage snapshots --- docs/base-chain/node-operators/snapshots.mdx | 101 ++++++++++--------- 1 file changed, 51 insertions(+), 50 deletions(-) diff --git a/docs/base-chain/node-operators/snapshots.mdx b/docs/base-chain/node-operators/snapshots.mdx index d74693c54..2260d478d 100644 --- a/docs/base-chain/node-operators/snapshots.mdx +++ b/docs/base-chain/node-operators/snapshots.mdx @@ -1,82 +1,83 @@ --- title: Node Snapshots sidebarTitle: Snapshots -description: Download and restore Base node snapshots to significantly reduce initial sync time for both archive and pruned nodes. +description: Download and restore Base node snapshots to significantly reduce initial sync time for minimal, full, and archive nodes. --- -Using a snapshot significantly reduces the initial time required to sync a Base node. Snapshots are updated regularly. +Using a snapshot significantly reduces the initial time required to sync a Base node. Snapshots let you stand up a node in a fraction of the time by downloading a recent copy of the chain's state and history instead of syncing from genesis. Snapshots are updated regularly. If you're a prospective or current Base node operator, you can restore from a snapshot to speed up your initial sync. Follow the steps below carefully. -## Restoring from Snapshot + +For a browsable, interactive experience (including custom component selection), see the snapshots UI. This guide documents the three most common configurations plus the flags most people need. + -These steps assume you are in the cloned `node` directory (the one containing `docker-compose.yml`). +## Quick start -1. **Install aria2c**: Snapshot downloads require `aria2c`, a resumable downloader that handles the periodic connection interruptions imposed by Cloudflare. If you don't have it installed: +Download a snapshot with the `download` subcommand, choosing a configuration and the chain you want: - - ```bash macOS - brew install aria2 - ``` +```bash +# Minimal node on Base Mainnet +base download --minimal --chain base - ```bash Ubuntu / Debian - sudo apt-get install aria2 - ``` - +# Full node on Base Sepolia +base download --full --chain base-sepolia +``` -2. **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. - ```bash - 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. +When the download finishes, the command prints the exact node command to run next, for example: -3. **Download Snapshot**: Choose the appropriate snapshot for your network and client from the table below. Download it into the `node` directory. +```bash +base node --chain base +``` - | Network | Snapshot Type | Download Command | - | -------- | ------------- | ---------------- | - | Testnet | Archive (recommended)| `aria2c -c -x 16 -s 16 "https://sepolia-reth-archive-snapshots.base.org/$(curl -s https://sepolia-reth-archive-snapshots.base.org/latest)"` | - | Testnet | Pruned | `aria2c -c -x 16 -s 16 "https://sepolia-reth-pruned-snapshots.base.org/$(curl -s https://sepolia-reth-pruned-snapshots.base.org/latest)"` | - | Mainnet | Archive (recommended)| `aria2c -c -x 16 -s 16 "https://mainnet-reth-archive-snapshots.base.org/$(curl -s https://mainnet-reth-archive-snapshots.base.org/latest)"` | - | Mainnet | Pruned | `aria2c -c -x 16 -s 16 "https://mainnet-reth-pruned-snapshots.base.org/$(curl -s https://mainnet-reth-pruned-snapshots.base.org/latest)"` | +Your node should begin syncing from the last block in the snapshot. - - Ensure you have enough free disk space to download the snapshot archive (`.tar.gz` / `.tar.zst` file) _and_ extract its contents. The extracted data will be significantly larger than the archive. - + +Ensure you have enough free disk space to download the snapshot _and_ extract its contents. The extracted data will be significantly larger than the download. + -4. **Extract Snapshot**: Untar the downloaded snapshot archive. Replace `snapshot-filename` with the actual downloaded filename: +## Configurations - ```bash - tar -xzvf +There are three built-in configurations. Pick one; they are mutually exclusive. - # For .tar.zst - tar -I zstd -xvf - ``` +| Config | Flag | What you get | Use when | +| ------------ | ----------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------- | +| **Minimal** | `--minimal` | The smallest set needed to boot: latest state + headers (plus the minimum required history). | You want the fastest, smallest download and don't need historical data. | +| **Full** | `--full` | Full-node data matching the default full-node prune settings (state, headers, and a bounded window of transactions, receipts, and history). | You want a standard full node without keeping the entire archive. | +| **Archive** | `--archive` | Everything available — all transactions, receipts, and account/storage history, with no pruning. | You need complete historical data (e.g. archive queries, indexing). | -5. **Move Data**: The extraction process will likely create a `reth` directory. +## Choosing the chain - * Move the *contents* of that directory into the data directory you created in Step 1: +Use the `--chain` flag to select the network: - ```bash - mv ./reth/* ./reth-data/ - rm -rf ./reth # Clean up empty extracted folder - ``` +| Network | `--chain` value | +| ------------- | --------------- | +| Base Mainnet | `base` | +| Base Sepolia | `base-sepolia` | - * The goal is to have the chain data directories (e.g., `chaindata`, `nodes`, `segments`, etc.) directly inside `./reth-data`, not in a nested subfolder. +## Optional: tuning download concurrency -6. **Start the Node**: Now that the snapshot data is in place, return the root of your Base node folder and start the node: +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. - ```bash - cd .. - docker compose up --build - ``` +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**: - Your node should begin syncing from the last block in the snapshot. +```bash +# Example: a 16 physical-core machine +base download --full --chain base --download-concurrency 32 +``` -7. **Verify and Clean Up**: Monitor the node logs (`docker compose logs -f `) or use the [sync monitoring](/base-chain/node-operators/run-a-base-node#syncing) command to ensure the node starts syncing from the snapshot's block height. Once confirmed, you can safely delete the downloaded snapshot archive (`.tar.gz` file) to free up disk space. +Leave it at the default if you're unsure. + +## Verify and clean up + +Monitor the node logs or use the [sync monitoring](/base-chain/node-operators/run-a-base-node#syncing) command to ensure the node starts syncing from the snapshot's block height. Once confirmed, you can safely delete the downloaded snapshot archive to free up disk space. ## Proofs Snapshots + +V2 Proofs Snapshots are coming soon. + + If you are running the [historical proofs ExEx](/base-chain/node-operators/run-a-base-node#enable-historical-proofs-rpcs), snapshots of the proofs database are available to skip the 24-48 hour backfill. | Network | Download Command | @@ -84,7 +85,7 @@ If you are running the [historical proofs ExEx](/base-chain/node-operators/run-a | Testnet | `aria2c -c -x 16 -s 16 "https://sepolia-reth-proofs-snapshots.base.org/$(curl -s https://sepolia-reth-proofs-snapshots.base.org/latest)"` | | Mainnet | `aria2c -c -x 16 -s 16 "https://mainnet-reth-proofs-snapshots.base.org/$(curl -s https://mainnet-reth-proofs-snapshots.base.org/latest)"` | -The restore process is the same as above — follow the [Restoring from Snapshot](#restoring-from-snapshot) steps using this archive instead. +Download the proofs archive with `aria2c`, extract it, and move its contents into your proofs data directory before starting the node. ## FAQ From 0eb65ecf7739e45e6ba3f33058505c4cc43422ea Mon Sep 17 00:00:00 2001 From: William Law Date: Mon, 20 Jul 2026 15:25:32 -0400 Subject: [PATCH 2/8] edits --- docs/base-chain/node-operators/snapshots.mdx | 89 ++++++++------------ 1 file changed, 36 insertions(+), 53 deletions(-) diff --git a/docs/base-chain/node-operators/snapshots.mdx b/docs/base-chain/node-operators/snapshots.mdx index 2260d478d..149b88c46 100644 --- a/docs/base-chain/node-operators/snapshots.mdx +++ b/docs/base-chain/node-operators/snapshots.mdx @@ -1,76 +1,59 @@ --- title: Node Snapshots sidebarTitle: Snapshots -description: Download and restore Base node snapshots to significantly reduce initial sync time for minimal, full, and archive nodes. +description: Download and restore Base node snapshots to significantly reduce initial sync time for nodes. --- -Using a snapshot significantly reduces the initial time required to sync a Base node. Snapshots let you stand up a node in a fraction of the time by downloading a recent copy of the chain's state and history instead of syncing from genesis. Snapshots are updated regularly. +Using a snapshot significantly reduces the initial time required to sync a Base node. Snapshots are updated regularly. If you're a prospective or current Base node operator, you can restore from a snapshot to speed up your initial sync. Follow the steps below carefully. - -For a browsable, interactive experience (including custom component selection), see the snapshots UI. This guide documents the three most common configurations plus the flags most people need. - - -## Quick start - -Download a snapshot with the `download` subcommand, choosing a configuration and the chain you want: - -```bash -# Minimal node on Base Mainnet -base download --minimal --chain base - -# Full node on Base Sepolia -base download --full --chain base-sepolia -``` - -When the download finishes, the command prints the exact node command to run next, for example: - -```bash -base node --chain base -``` - -Your node should begin syncing from the last block in the snapshot. - - -Ensure you have enough free disk space to download the snapshot _and_ extract its contents. The extracted data will be significantly larger than the download. - +## Restoring from Snapshot -## Configurations +These steps assume you are in the cloned `node` directory (the one containing `docker-compose.yml`). -There are three built-in configurations. Pick one; they are mutually exclusive. +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. + ```bash + 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. -| Config | Flag | What you get | Use when | -| ------------ | ----------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------- | -| **Minimal** | `--minimal` | The smallest set needed to boot: latest state + headers (plus the minimum required history). | You want the fastest, smallest download and don't need historical data. | -| **Full** | `--full` | Full-node data matching the default full-node prune settings (state, headers, and a bounded window of transactions, receipts, and history). | You want a standard full node without keeping the entire archive. | -| **Archive** | `--archive` | Everything available — all transactions, receipts, and account/storage history, with no pruning. | You need complete historical data (e.g. archive queries, indexing). | +2. **Download Snapshot**: Choose the appropriate snapshot for your network and client from the table below. -## Choosing the chain + | Config | Flag | What you get | Use when | + |--------------|-------------|------------------------------------------------------------------------------|-------------------------------------------------------------| + | **Minimal** | `--minimal` | The smallest set needed to boot: latest state + headers (plus the minimum required history). | You want the fastest, smallest download and don't need historical data. | + | **Full** | `--full` | Full-node data matching the default full-node prune settings (state, headers, and a bounded window of transactions, receipts, and history). | You want a standard full node without keeping the entire archive. | + | **Archive** | `--archive` | Everything available — all transactions, receipts, and account/storage history, with no pruning. | You need complete historical data (e.g. archive queries, indexing). | -Use the `--chain` flag to select the network: + + 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. + -| Network | `--chain` value | -| ------------- | --------------- | -| Base Mainnet | `base` | -| Base Sepolia | `base-sepolia` | +3. **Choosing the chain**: Use the `--chain` flag to select the network -## Optional: tuning download concurrency + | Network | `--chain` value | + |---------------|-----------------| + | Base Mainnet | `base` | + | Base Sepolia | `base-sepolia` | -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. +4. **(Optional) - tuning download concurrency:** -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**: +6. **Start the Node**: Now that the snapshot data is in place, return the root of your Base node folder and start the node: -```bash -# Example: a 16 physical-core machine -base download --full --chain base --download-concurrency 32 -``` + 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. -Leave it at the default if you're unsure. + 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**: -## Verify and clean up + ```bash + # Example: a 16 physical-core machine + base download --full --chain base --download-concurrency 32 + ``` -Monitor the node logs or use the [sync monitoring](/base-chain/node-operators/run-a-base-node#syncing) command to ensure the node starts syncing from the snapshot's block height. Once confirmed, you can safely delete the downloaded snapshot archive to free up disk space. +7. **Verify and Clean Up**: Monitor the node logs (`docker compose logs -f `) or use the [sync monitoring](/base-chain/node-operators/run-a-base-node#syncing) command to ensure the node starts syncing from the snapshot's block height. Once confirmed, you can safely delete the downloaded snapshot archive (`.tar.gz` file) to free up disk space. ## Proofs Snapshots @@ -85,7 +68,7 @@ If you are running the [historical proofs ExEx](/base-chain/node-operators/run-a | Testnet | `aria2c -c -x 16 -s 16 "https://sepolia-reth-proofs-snapshots.base.org/$(curl -s https://sepolia-reth-proofs-snapshots.base.org/latest)"` | | Mainnet | `aria2c -c -x 16 -s 16 "https://mainnet-reth-proofs-snapshots.base.org/$(curl -s https://mainnet-reth-proofs-snapshots.base.org/latest)"` | -Download the proofs archive with `aria2c`, extract it, and move its contents into your proofs data directory before starting the node. +The restore process is the same as above — follow the [Restoring from Snapshot](#restoring-from-snapshot) steps using this archive instead. ## FAQ From f9996fc8b097b3e697e9551bc8245fe7b0814943 Mon Sep 17 00:00:00 2001 From: William Law Date: Mon, 20 Jul 2026 15:29:05 -0400 Subject: [PATCH 3/8] floww --- docs/base-chain/node-operators/snapshots.mdx | 22 +++++++++++++------- 1 file changed, 15 insertions(+), 7 deletions(-) diff --git a/docs/base-chain/node-operators/snapshots.mdx b/docs/base-chain/node-operators/snapshots.mdx index 149b88c46..8b8c0d41c 100644 --- a/docs/base-chain/node-operators/snapshots.mdx +++ b/docs/base-chain/node-operators/snapshots.mdx @@ -19,7 +19,14 @@ These steps assume you are in the cloned `node` directory (the one containing `d ``` - 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. **Download Snapshot**: Choose the appropriate snapshot for your network and client from the table below. +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**: Choose the appropriate snapshot for your network and client from the table below. | Config | Flag | What you get | Use when | |--------------|-------------|------------------------------------------------------------------------------|-------------------------------------------------------------| @@ -31,12 +38,13 @@ These steps assume you are in the cloned `node` directory (the one containing `d 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. -3. **Choosing the chain**: Use the `--chain` flag to select the network + ```bash + # Minimal node on Base Mainnet + base download --minimal --datadir ./reth-data --chain base - | Network | `--chain` value | - |---------------|-----------------| - | Base Mainnet | `base` | - | Base Sepolia | `base-sepolia` | + # Full node on Base Sepolia + base download --full --datadir ./reth-data --chain base-sepolia + ``` 4. **(Optional) - tuning download concurrency:** @@ -50,7 +58,7 @@ These steps assume you are in the cloned `node` directory (the one containing `d ```bash # Example: a 16 physical-core machine - base download --full --chain base --download-concurrency 32 + base download --full --datadir ./reth-data --chain base --download-concurrency 32 ``` 7. **Verify and Clean Up**: Monitor the node logs (`docker compose logs -f `) or use the [sync monitoring](/base-chain/node-operators/run-a-base-node#syncing) command to ensure the node starts syncing from the snapshot's block height. Once confirmed, you can safely delete the downloaded snapshot archive (`.tar.gz` file) to free up disk space. From 3fdcbfbcd6ddae55d89f331cf7f5be1972262835 Mon Sep 17 00:00:00 2001 From: William Law Date: Mon, 20 Jul 2026 15:49:01 -0400 Subject: [PATCH 4/8] keep parts of the setup --- docs/base-chain/node-operators/snapshots.mdx | 20 ++++++++++++++++---- 1 file changed, 16 insertions(+), 4 deletions(-) diff --git a/docs/base-chain/node-operators/snapshots.mdx b/docs/base-chain/node-operators/snapshots.mdx index 8b8c0d41c..36ba3e644 100644 --- a/docs/base-chain/node-operators/snapshots.mdx +++ b/docs/base-chain/node-operators/snapshots.mdx @@ -12,21 +12,33 @@ If you're a prospective or current Base node operator, you can restore from a sn These steps assume you are in the cloned `node` directory (the one containing `docker-compose.yml`). -1. **Prepare Data Directory**: +1. **Install aria2c**: Snapshot downloads require `aria2c`, a resumable downloader that handles the periodic connection interruptions imposed by Cloudflare. If you don't have it installed: + + + ```bash macOS + brew install aria2 + ``` + + ```bash Ubuntu / Debian + sudo apt-get install aria2 + ``` + + +2. **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. ```bash 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 +3. **Choosing the chain**: Use the `--chain` flag to select the network | Network | `--chain` value | |---------------|-----------------| | Base Mainnet | `base` | | Base Sepolia | `base-sepolia` | -3. **Download Snapshot**: Choose the appropriate snapshot for your network and client from the table below. +4. **Download Snapshot**: Choose the appropriate snapshot for your network and client from the table below. | Config | Flag | What you get | Use when | |--------------|-------------|------------------------------------------------------------------------------|-------------------------------------------------------------| @@ -46,7 +58,7 @@ These steps assume you are in the cloned `node` directory (the one containing `d base download --full --datadir ./reth-data --chain base-sepolia ``` -4. **(Optional) - tuning download concurrency:** +5. **(Optional) - tuning download concurrency:** 6. **Start the Node**: Now that the snapshot data is in place, return the root of your Base node folder and start the node: From 427bb1b13ebf440923034eb31e0b02afa823d30b Mon Sep 17 00:00:00 2001 From: William Law Date: Wed, 22 Jul 2026 11:54:11 -0400 Subject: [PATCH 5/8] resumeable and migrate-v2 --- docs/base-chain/node-operators/snapshots.mdx | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/docs/base-chain/node-operators/snapshots.mdx b/docs/base-chain/node-operators/snapshots.mdx index 36ba3e644..9459f9295 100644 --- a/docs/base-chain/node-operators/snapshots.mdx +++ b/docs/base-chain/node-operators/snapshots.mdx @@ -52,15 +52,15 @@ These steps assume you are in the cloned `node` directory (the one containing `d ```bash # Minimal node on Base Mainnet - base download --minimal --datadir ./reth-data --chain base + base download --minimal --datadir ./reth-data --chain base --resumable # Full node on Base Sepolia - base download --full --datadir ./reth-data --chain base-sepolia + base download --full --datadir ./reth-data --chain base-sepolia --resumable ``` -5. **(Optional) - tuning download concurrency:** + Alternatively, for archival nodes only, you may run `base db migrate-v2`. However, this is expected to take **much** longer than downloading. `--resumeable` is also not supported in `migrate-v2`. -6. **Start the Node**: Now that the snapshot data is in place, return the root of your Base node folder and start the node: +5. **(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. @@ -73,6 +73,15 @@ These steps assume you are in the cloned `node` directory (the one containing `d base download --full --datadir ./reth-data --chain base --download-concurrency 32 ``` +6. **Start the Node**: Now that the snapshot data is in place, return the root of your Base node folder and start the node: + + ```bash + cd .. + docker compose up --build + ``` + + Your node should begin syncing from the last block in the snapshot. + 7. **Verify and Clean Up**: Monitor the node logs (`docker compose logs -f `) or use the [sync monitoring](/base-chain/node-operators/run-a-base-node#syncing) command to ensure the node starts syncing from the snapshot's block height. Once confirmed, you can safely delete the downloaded snapshot archive (`.tar.gz` file) to free up disk space. ## Proofs Snapshots From 4ca320b01fc316fbd600d535856b4a8c1a32ed69 Mon Sep 17 00:00:00 2001 From: roethke Date: Wed, 22 Jul 2026 09:45:19 -0700 Subject: [PATCH 6/8] link base cli, fix step cross-refs --- docs/base-chain/node-operators/snapshots.mdx | 70 ++++++++++++++------ 1 file changed, 48 insertions(+), 22 deletions(-) diff --git a/docs/base-chain/node-operators/snapshots.mdx b/docs/base-chain/node-operators/snapshots.mdx index 9459f9295..f2e20435a 100644 --- a/docs/base-chain/node-operators/snapshots.mdx +++ b/docs/base-chain/node-operators/snapshots.mdx @@ -12,33 +12,25 @@ If you're a prospective or current Base node operator, you can restore from a sn These steps assume you are in the cloned `node` directory (the one containing `docker-compose.yml`). -1. **Install aria2c**: Snapshot downloads require `aria2c`, a resumable downloader that handles the periodic connection interruptions imposed by Cloudflare. If you don't have it installed: - - - ```bash macOS - brew install aria2 - ``` - - ```bash Ubuntu / Debian - sudo apt-get install aria2 - ``` - + +These steps use the `base` CLI to download snapshots. If you don't already have it, follow the [installation instructions](https://github.com/base/base#install-binaries) to install it first. + -2. **Prepare Data Directory**: +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. ```bash 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. -3. **Choosing the chain**: Use the `--chain` flag to select the network +2. **Choosing the chain**: Use the `--chain` flag to select the network | Network | `--chain` value | |---------------|-----------------| | Base Mainnet | `base` | | Base Sepolia | `base-sepolia` | -4. **Download Snapshot**: Choose the appropriate snapshot for your network and client from the table below. +3. **Download Snapshot**: Choose the appropriate snapshot for your network and client from the table below. | Config | Flag | What you get | Use when | |--------------|-------------|------------------------------------------------------------------------------|-------------------------------------------------------------| @@ -58,9 +50,9 @@ These steps assume you are in the cloned `node` directory (the one containing `d base download --full --datadir ./reth-data --chain base-sepolia --resumable ``` - Alternatively, for archival nodes only, you may run `base db migrate-v2`. However, this is expected to take **much** longer than downloading. `--resumeable` is also not supported in `migrate-v2`. + Alternatively, for archival nodes only, you may run `base db migrate-v2`. However, this is expected to take **much** longer than downloading. `--resumable` is also not supported in `migrate-v2`. -5. **(Optional) - tuning download concurrency:** +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. @@ -73,16 +65,16 @@ These steps assume you are in the cloned `node` directory (the one containing `d base download --full --datadir ./reth-data --chain base --download-concurrency 32 ``` -6. **Start the Node**: Now that the snapshot data is in place, return the root of your Base node folder and start the node: +5. **Start the Node**: Now that the snapshot data is in place, return the root of your Base node folder and start the node: ```bash cd .. docker compose up --build ``` - Your node should begin syncing from the last block in the snapshot. + Your node should begin syncing from the last block in the snapshot. -7. **Verify and Clean Up**: Monitor the node logs (`docker compose logs -f `) or use the [sync monitoring](/base-chain/node-operators/run-a-base-node#syncing) command to ensure the node starts syncing from the snapshot's block height. Once confirmed, you can safely delete the downloaded snapshot archive (`.tar.gz` file) to free up disk space. +6. **Verify**: Monitor the node logs (`docker compose logs -f `) or use the [sync monitoring](/base-chain/node-operators/run-a-base-node#syncing) command to ensure the node starts syncing from the snapshot's block height. ## Proofs Snapshots @@ -92,21 +84,55 @@ V2 Proofs Snapshots are coming soon. If you are running the [historical proofs ExEx](/base-chain/node-operators/run-a-base-node#enable-historical-proofs-rpcs), snapshots of the proofs database are available to skip the 24-48 hour backfill. +Proofs snapshots are still distributed as archives, so you'll need `aria2c`, a resumable downloader that handles the periodic connection interruptions imposed by Cloudflare. If you don't have it installed: + + +```bash macOS +brew install aria2 +``` + +```bash Ubuntu / Debian +sudo apt-get install aria2 +``` + + | Network | Download Command | | ------- | ---------------- | | Testnet | `aria2c -c -x 16 -s 16 "https://sepolia-reth-proofs-snapshots.base.org/$(curl -s https://sepolia-reth-proofs-snapshots.base.org/latest)"` | | Mainnet | `aria2c -c -x 16 -s 16 "https://mainnet-reth-proofs-snapshots.base.org/$(curl -s https://mainnet-reth-proofs-snapshots.base.org/latest)"` | -The restore process is the same as above — follow the [Restoring from Snapshot](#restoring-from-snapshot) steps using this archive instead. + +Ensure you have enough free disk space to download the snapshot archive (`.tar.gz` / `.tar.zst` file) _and_ extract its contents. The extracted data will be significantly larger than the archive. + + +Once downloaded, extract the archive. Replace `snapshot-filename` with the actual downloaded filename: + +```bash +tar -xzvf + +# For .tar.zst +tar -I zstd -xvf +``` + +The extraction process will likely create a `reth` directory. Move the _contents_ of that directory into the data directory you created in [**Prepare Data Directory**](#restoring-from-snapshot) in the section above: + +```bash +mv ./reth/* ./reth-data/ +rm -rf ./reth # Clean up empty extracted folder +``` + +The goal is to have the chain data directories (e.g., `chaindata`, `nodes`, `segments`, etc.) directly inside `./reth-data`, not in a nested subfolder. Once confirmed, you can safely delete the downloaded snapshot archive (`.tar.gz` file) to free up disk space. + +Then continue from [**Start the Node**](#start-the-node) in the section above. ## FAQ - + In Reth, a "full" node is just a pruned node with a specific preset rather than a distinct node type. Reth's `--full` preset retains the last **10,064 blocks** (~1.4 days on Ethereum; ~5-6 hours on Base due to faster block times). -Base's _pruned_ snapshot uses a 31-day rolling retention window instead. If a smaller storage footprint is preferred, you can override `reth.toml` to match the 10,064-block preset. +Base's `--full` snapshot uses a 31-day rolling retention window instead. If a smaller storage footprint is preferred, you can override `reth.toml` to match the 10,064-block preset. From 21e5ede234b19a8a7d881660de3a5264e6cf4672 Mon Sep 17 00:00:00 2001 From: William Law Date: Wed, 22 Jul 2026 14:03:15 -0400 Subject: [PATCH 7/8] typo --- docs/base-chain/node-operators/snapshots.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/base-chain/node-operators/snapshots.mdx b/docs/base-chain/node-operators/snapshots.mdx index f2e20435a..195aa0409 100644 --- a/docs/base-chain/node-operators/snapshots.mdx +++ b/docs/base-chain/node-operators/snapshots.mdx @@ -44,10 +44,10 @@ These steps use the `base` CLI to download snapshots. If you don't already have ```bash # Minimal node on Base Mainnet - base download --minimal --datadir ./reth-data --chain base --resumable + base-reth-node download --minimal --datadir ./reth-data --chain base --resumable # Full node on Base Sepolia - base download --full --datadir ./reth-data --chain base-sepolia --resumable + base-reth-node download --full --datadir ./reth-data --chain base-sepolia --resumable ``` Alternatively, for archival nodes only, you may run `base db migrate-v2`. However, this is expected to take **much** longer than downloading. `--resumable` is also not supported in `migrate-v2`. @@ -62,7 +62,7 @@ These steps use the `base` CLI to download snapshots. If you don't already have ```bash # Example: a 16 physical-core machine - base download --full --datadir ./reth-data --chain base --download-concurrency 32 + 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: From cd374138cf767414b72a3c114a7685f569c6d271 Mon Sep 17 00:00:00 2001 From: William Law Date: Wed, 22 Jul 2026 14:04:54 -0400 Subject: [PATCH 8/8] fix typo --- docs/base-chain/node-operators/snapshots.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/base-chain/node-operators/snapshots.mdx b/docs/base-chain/node-operators/snapshots.mdx index 195aa0409..3189b4d45 100644 --- a/docs/base-chain/node-operators/snapshots.mdx +++ b/docs/base-chain/node-operators/snapshots.mdx @@ -13,7 +13,7 @@ If you're a prospective or current Base node operator, you can restore from a sn These steps assume you are in the cloned `node` directory (the one containing `docker-compose.yml`). -These steps use the `base` CLI to download snapshots. If you don't already have it, follow the [installation instructions](https://github.com/base/base#install-binaries) to install it first. +These steps use the `base-reth-node` CLI to download snapshots. If you don't already have it, follow the [installation instructions](https://github.com/base/base#install-binaries) to install it first. 1. **Prepare Data Directory**: