diff --git a/docs.json b/docs.json index 55f4e5b..a2b8e48 100644 --- a/docs.json +++ b/docs.json @@ -289,6 +289,7 @@ "group": "Setup & Deployment", "pages": [ "nodes/operations/quickstart", + "nodes/operations/snapshots", "nodes/operations/self-hosted-rpc", "nodes/guides/local-devnet-docker", "nodes/guides/local-devnet-kurtosis", diff --git a/nodes/operations/quickstart.mdx b/nodes/operations/quickstart.mdx index 1a0dc65..7194dbb 100644 --- a/nodes/operations/quickstart.mdx +++ b/nodes/operations/quickstart.mdx @@ -71,6 +71,7 @@ ls; # README.md run-reth.sh setup-reth.sh # env.sh run-beacond.sh setup-beacond.sh # fetch-berachain-params.sh +# fetch-berachain-snapshot.js ``` The file `env.sh` contains environment variables used in the other scripts. @@ -181,118 +182,16 @@ The `setup-reth.sh` script creates the Reth datadir and initializes it with `--c ## Step 6 - Fetch snapshots (optional) -Snapshots are collections of files from a node's backend that represent its state at a specific time. Restoring a snapshot is much faster than syncing from the network, so this step can dramatically speed up your initial sync on a new node. +Restoring a snapshot is much faster than syncing from genesis. Do this **before** Step 7. - - Do this step **before** starting your clients (Step 7). If you've already started syncing, you'll - need to stop the clients, clean the data directories, then restore snapshots. - - -Snapshots can be applied to both the consensus (beacond) and execution clients. Restoring both snapshots simultaneously provides the fastest sync. - -### 6a - Obtain snapshots - -Berachain and the community offer snapshots for Mainnet and Bepolia. You can download snapshots at the following links. - -- [Awesome Berachain Validators](https://github.com/chuck-bear/awesome-berachain-validators) is a community-maintained list; all of them have great download speed. - -- Or, use the `fetch-berachain-snapshot.js` script — already on disk from Step 1 — downloads the latest official Berachain snapshots for both the beacon-kit consensus layer and the execution layer. It reads the snapshot index at `snapshots.berachain.com`, picks the most recent files matching your options, and saves them to a `downloads/` directory. - -```bash -# FROM: ~/beranode (or any directory — use -o to change download folder) - -# Default: mainnet, pruned -node fetch-berachain-snapshot.js - -# Examples: -node fetch-berachain-snapshot.js --network bepolia --type archive -node fetch-berachain-snapshot.js -o /var/snapshots --execution-only - -# [Expected Output]: -# Bera Snapshot Downloader -# ------------------------- -# Network: mainnet -# Client: reth -# Type: pruned -# -# Fetching snapshot index from: -# https://snapshots.berachain.com/index.csv -# [...] -# ✓ All downloads completed! -``` - -Available options: - -- `--network` or `-n`: `mainnet` or `bepolia` (default: `mainnet`) -- `--type` or `-t`: `pruned` or `archive` (default: `pruned`) -- `--output` or `-o`: Download directory (default: `downloads` in the current working directory) -- `--el-client`: Execution snapshot type prefix in the CSV (default: `reth`) -- `--beacon-only`: Beacon-kit snapshot only -- `--execution-only` or `--el-only`: Execution-layer snapshot only -- `--help` or `-h`: Show help message - -### 6b - Stop clients - -If you've already started your clients, shut down `beacond` and your execution client now. Otherwise, skip to 6c. - -### 6c - Clean existing chain data - -To clean the Beacon Kit and reth data store: +Official Berachain snapshots are available for +[Mainnet](https://snapshots.berachain.com) and [Bepolia](https://bepolia.snapshots.berachain.com/). Full restore commands and documentation are available on [Snapshots](/nodes/operations/snapshots). ```bash # FROM: ~/beranode -source env.sh; -$BEACOND_BIN --home $BEACOND_HOME comet unsafe-reset-all; - -# [Expected Output]: -# Removed all blockchain history dir=var/beacond/data -# Reset private validator file to genesis state key=.. - -ls var/reth/data; - -# [Expected Output]: -# (empty or prior db contents) - -rm -r var/reth/data; -mkdir -p var/reth/data; -``` - -### 6d - Install BeaconKit snapshot - -The snapshots distributed by Berachain are designed to be installed in the beacond home directory, which contains both `config` and `data`: - -```bash -# FROM: ~/beranode - -# Find the beacon-kit snapshot file (filename pattern: snapshot_beacon-kit-*) -BEACON_SNAPSHOT=$(ls downloads/snapshot_beacon-kit-*.tar.lz4 | head -1) -lz4 -d "$BEACON_SNAPSHOT" | tar xv -C var/beacond/; - -# [Expected Output]: -# x data/ -# x data/cs.wal/ -# x data/cs.wal/wal.10416 -# ... -``` - -### 6e - Install execution layer snapshot - -Official Reth snapshot archives list **`db/`**, **`rocksdb/`**, and **`blobstore/`** at the **root** of the tarball (not under a `data/` directory). Your `bera-reth node --datadir` must be the directory that contains those folders. In this layout that is `var/reth/data` (see `setup-reth.sh` / `env.sh`), so pass **`-C var/reth/data`** to `tar`. - -```bash -# FROM: ~/beranode - -# Find the execution layer snapshot -EL_SNAPSHOT=$(ls downloads/snapshot_reth-*.tar.lz4 | head -1) -lz4 -d "$EL_SNAPSHOT" | tar xv -C var/reth/data; - -# [Expected Output] (current official bundles): -# x db/ -# x db/mdbx.dat -# x rocksdb/ -# x blobstore/ -# ... +node fetch-berachain-snapshot.js --network mainnet --type pruned +node fetch-berachain-snapshot.js --network bepolia --type pruned ``` ## Step 7 - Run both clients diff --git a/nodes/operations/snapshots.mdx b/nodes/operations/snapshots.mdx new file mode 100644 index 0000000..5c21369 --- /dev/null +++ b/nodes/operations/snapshots.mdx @@ -0,0 +1,86 @@ +--- +title: "Snapshots" +--- + +A snapshot lets you set up a new node in hours, not days. Berachain publishes a new snapshot once each day, for Mainnet and for Bepolia. + + + Do this step before you start the clients. If you already started to sync, do these steps first: + stop both clients, delete the chain data, then restore the snapshot. + + +## Reth storage v1 vs v2 + +Bera-Reth, Berachain's execution client, is built on the upstream Reth project. Reth v2 added storage v2, a new on-disk layout that splits data by how the node uses it instead of holding everything in one database. + +Storage v2 uses less disk (~20%), performs faster, and is the default for new installations. +See [Reth's storage documentation](https://reth.rs/run/storage/). + +Berachain's official snapshots use storage v2, for both Mainnet and Bepolia. Some community node operators still publish storage v1 snapshots; see [Awesome Berachain Validators](https://github.com/chuck-bear/awesome-berachain-validators). + +To check which layout a datadir already uses, run `bera-reth db --datadir settings`. + + + Bera-Reth records the storage layout when it creates a datadir, and **does not change it later**. + Setting or clearing a flag on an existing datadir does not convert it. To move an existing node to + storage v2, restore a storage v2 snapshot into a new datadir. + + +## Migrating from storage v1 to v2 + +Restore a storage v2 snapshot into a new, empty datadir: the same procedure as a new node setup. This is the recommended path, and the steps below cover it. + +This procedure only affects the execution layer. Beacon Kit storage format has not changed. Your consensus-layer data and your validator keys are safe during this procedure. + +Do these steps to move an existing node to storage v2: + +1. Stop the execution client and Beacon-Kit. +2. Delete or preserve the old Bera-Reth datadir (example: `var/reth/data`). A storage v1 datadir and a storage v2 datadir are not compatible with each other. Keep a copy of the old datadir only if you want a way back to storage v1. +3. Restore a snapshot into the empty datadir; see [Restoring an official snapshot](#restoring-an-official-snapshot), below. +4. You do not need to change any configuration or startup options. Restart the Bera-Reth and Beacon-Kit. + +## `bera-reth download` and its options + +The `bera-reth download` command restores an execution-layer datadir from a storage v2 snapshot manifest. This is faster than a full network sync. + +After it extracts each file, `bera-reth download` checks that file against the manifest's checksum. If a file doesn't match, it deletes the file and downloads it again. A damaged or incomplete download can't leave you with a datadir that looks correct but isn't. + +**Required:** + +- **`--chain `**: chooses the network snapshot to download. +- **`--datadir `**: the target directory. Do not point this at a running node's data or storage v1 data. +- **`--manifest-url `**: the `manifest.json` URL for the snapshot you want. Copy it from the [Mainnet](https://snapshots.berachain.com/) or [Bepolia](https://bepolia.snapshots.berachain.com/) snapshot site. For a third-party snapshot, copy the URL that provider publishes. + +**Pick exactly one preset:** + +- **`--minimal`**: downloads the smallest working node. It can sync forward from the snapshot's block. Most operators should use this. +- **`--archive`**: downloads everything in the manifest: full transaction, receipt, and state-history data. This needs far more disk space and download time than `--minimal`. +- **`--full`**: downloads data matching a full, non-archive node's [default pruning settings](https://reth.rs/run/storage/pruning/). More than `--minimal` and far less than `--archive`. + +**Useful flags:** + +- **`--force`**: deletes the existing `db`, `rocksdb`, `static_files`, and `reth.toml` under `--datadir` first. Use this when the target directory already holds different or partial data. +- **`--print-plan-json`**: reads the manifest and prints the download plan, without downloading or writing anything. Safe to run against a real `--datadir`. Use it to check a manifest URL or estimate the download size before you restore. +- **`--download-concurrency `**: how many downloads run at once (default 8). Raise it on a fast connection; lower it if the source throttles or drops connections. + +You can run this command again on a datadir with a partial or damaged restore. This is safe, and often the fix: every file is checked against the manifest's checksum, and anything missing, wrong-sized, or failing that check is deleted and re-downloaded automatically. This check only covers the files in your chosen preset; restoring with `--minimal` doesn't check files outside it. + +Copy `` from the snapshot site for your network before you run these. + +## Restoring an official snapshot + +```bash +# Restore a pruned Bepolia node +bera-reth download --chain bepolia --datadir var/reth/data \ + --manifest-url --minimal + +# Restore a pruned Mainnet node +bera-reth download --chain mainnet --datadir var/reth/data \ + --manifest-url --minimal + +# Dry run - verifies snapshot files on disk +bera-reth download --chain bepolia --datadir var/reth/data \ + --manifest-url --minimal --print-plan-json +``` + +