From 614ada6fc856a2baeb0f6546b7374186e31cddb2 Mon Sep 17 00:00:00 2001 From: Camembear Date: Wed, 2 Sep 2026 14:30:12 -0400 Subject: [PATCH 1/2] Restore snapshots in Quickstart with one shell command. Step 6 runs fetch-berachain-snapshot.sh into the Quickstart datadirs. Storage v2 is the same env and a second command on the same page. --- SOURCE_MAP.md | 1 + nodes/operations/quickstart.mdx | 130 ++++++++------------------------ 2 files changed, 33 insertions(+), 98 deletions(-) diff --git a/SOURCE_MAP.md b/SOURCE_MAP.md index 1ed6f68..732a5d7 100644 --- a/SOURCE_MAP.md +++ b/SOURCE_MAP.md @@ -20,6 +20,7 @@ Repository names ending in `/` refer to verified local checkouts. Their filesyst | Proof of Liquidity (PoL), BGT, BeraChef, Reward Vaults, incentives | `contracts/` | `src/pol/`; for example, `src/pol/rewards/BeraChef.sol` owns commission and reward allocation | | Consensus client, validators, genesis, `nodes/beaconkit/**`, `nodes/architecture/**` | `beacon-kit/` | Release tags, configuration, command surface, and network artifacts | | Execution client | `bera-reth/` | Releases and configuration | +| Node operations Quickstart snapshot restore (`nodes/operations/quickstart`) | `guides/apps/node-scripts/` | `fetch-berachain-snapshot.sh`, `fetch-berachain-snapshot-v2.sh`, `env.sh`, `lib-snapshot.sh` | | Governance proposals | `brips/` | Proposal text | | Cross-repository protocol terms | `UBIQUITOUS_LANGUAGE.md` | Use for names and relationships after verifying mutable values against source | | Deployed PoL addresses | `contracts-internal/script/pol/POLAddresses.sol` | Follow the address pipeline in `CONTRIBUTING.md` instead of editing generated output | diff --git a/nodes/operations/quickstart.mdx b/nodes/operations/quickstart.mdx index 1a0dc65..03f7c26 100644 --- a/nodes/operations/quickstart.mdx +++ b/nodes/operations/quickstart.mdx @@ -68,13 +68,15 @@ rm -r guides; ls; # [Expected output, edited for clarity] -# README.md run-reth.sh setup-reth.sh -# env.sh run-beacond.sh setup-beacond.sh -# fetch-berachain-params.sh +# README.md run-reth.sh setup-reth.sh +# env.sh run-beacond.sh setup-beacond.sh +# fetch-berachain-params.sh fetch-berachain-snapshot.sh +# fetch-berachain-snapshot-v2.sh ``` The file `env.sh` contains environment variables used in the other scripts. `fetch-berachain-params.sh` downloads consensus-layer configuration files. +`fetch-berachain-snapshot.sh` restores official snapshots into the client data directories. `setup-` and `run-` scripts start the execution client and `beacond`. ## Step 2 - Configure environment @@ -89,13 +91,14 @@ export CHAIN=mainnet # mainnet or bepolia export MONIKER_NAME=camembera export WALLET_ADDRESS_FEE_RECIPIENT=0x8b30eb59e9b2354825503d5e60845eb41d4caf36 export EL_ARCHIVE_NODE=false # set to true if you want to run an archive node on CL and EL -export MY_IP=`curl -s canhazip.com` +export MY_IP=`curl -s ipv4.canhazip.com` # VALUES YOU MIGHT WANT TO CHANGE export LOG_DIR=$(pwd)/logs -export JWT_PATH=$BEACOND_CONFIG/jwt.hex export BEACOND_BIN=$(command -v beacond || echo $(pwd)/beacond) export BEACOND_DATA=$(pwd)/var/beacond +export BEACOND_CONFIG=$BEACOND_DATA/config +export JWT_PATH=$BEACOND_CONFIG/jwt.hex export RETH_BIN=$(command -v bera-reth || echo $(pwd)/bera-reth) ``` @@ -105,13 +108,16 @@ You need to set these constants: 2. **MONIKER_NAME**: A name of your choice for your node. 3. **WALLET_ADDRESS_FEE_RECIPIENT**: The address that receives priority fees for blocks sealed by your node. If your node will not be a validator, this won't matter. 4. **EL_ARCHIVE_NODE**: Set to `true` if you want the execution client to be a full archive node. -5. **MY_IP**: Sets the IP address your chain clients advertise to other peers on the network. In a cloud environment such as AWS or GCP where you are behind a NAT gateway, you **must** specify this address or allow the default `curl canhazip.com` to auto-detect it. +5. **MY_IP**: Sets the IP address your chain clients advertise to other peers on the network. In a cloud environment such as AWS or GCP where you are behind a NAT gateway, you **must** specify this address or allow the default `curl ipv4.canhazip.com` to auto-detect it. + +RPC ports default to 26657 (consensus) and 8545 (execution). Set `PORT_BASE=30000` in the environment before sourcing `env.sh` only if those ports are already taken. You should verify these constants: - **LOG_DIR**: This directory stores log files. - **BEACOND_BIN**: Set this to the full path where you installed `beacond`. The expression provided finds it in your $PATH. - **BEACOND_DATA**: Set this to where the consensus data and config should be kept. +- **BEACOND_CONFIG**: Derived from `BEACOND_DATA`. Do not change it. - **RETH_BIN**: Set this to the full path where you installed `bera-reth`. The expression provided finds it in your $PATH. ## Step 3 - Fetch parameters @@ -184,116 +190,42 @@ The `setup-reth.sh` script creates the Reth datadir and initializes it with `--c 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. - 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. + Do this step **before** starting your clients (Step 7). If you have already started syncing, stop + the clients, then run the restore again. The script replaces a fresh `setup-reth.sh` datadir. Pass + `--force` if the target directories contain unexpected files. -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. +After steps 1 through 5, source `env.sh` and run `fetch-berachain-snapshot.sh`. The script needs `curl`, `lz4`, and `tar` on your PATH. It downloads the latest official pruned snapshots from `snapshots.berachain.com` (Mainnet) or `bepolia.snapshots.berachain.com` (Bepolia) and extracts them into `$BEACOND_DATA` and `$RETH_DATA`. It does not overwrite `config/priv_validator_key.json` or `config/jwt.hex`. If `data/priv_validator_state.json` is missing, it writes genesis state so `beacond` can start. ```bash -# FROM: ~/beranode (or any directory — use -o to change download folder) - -# Default: mainnet, pruned -node fetch-berachain-snapshot.js +# FROM: ~/beranode -# Examples: -node fetch-berachain-snapshot.js --network bepolia --type archive -node fetch-berachain-snapshot.js -o /var/snapshots --execution-only +. ./env.sh +./fetch-berachain-snapshot.sh # [Expected Output]: -# Bera Snapshot Downloader +# Bera Snapshot Restore # ------------------------- # 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: - -```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; +# ... +# Snapshot restore complete. ``` -### 6d - Install BeaconKit snapshot +Pass `--network bepolia` when `CHAIN` in `env.sh` is not already `bepolia`. Pass `--type archive` for archive snapshots. `./fetch-berachain-snapshot.sh --help` lists the remaining flags. -The snapshots distributed by Berachain are designed to be installed in the beacond home directory, which contains both `config` and `data`: +Storage v2 uses the same `env.sh` and datadirs. `fetch-berachain-snapshot-v2.sh` reads `v2//catalog.csv`, streams the BeaconKit tarball into `$BEACOND_DATA/data`, and restores Bera-Reth with `bera-reth download --manifest-url`. Pruned execution restore requires `--minimal`, which Bera-Reth v1.4.4 does not have; the script fails closed unless your binary supports that flag. ```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 -# ... +. ./env.sh +./fetch-berachain-snapshot-v2.sh ``` -### 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; +The Mainnet v2 catalog uses the same URL shape and is not published yet. A missing catalog is a generic HTTP or parse error, not a fallback to v1. -# [Expected Output] (current official bundles): -# x db/ -# x db/mdbx.dat -# x rocksdb/ -# x blobstore/ -# ... -``` +Community snapshots are listed at [Awesome Berachain Validators](https://github.com/chuck-bear/awesome-berachain-validators). ## Step 7 - Run both clients @@ -368,7 +300,8 @@ If `catching_up` is set to `true`, it is still syncing. ### EL block number ```bash -curl --location 'http://localhost:8545' \ +. ./env.sh +curl --location "http://localhost:$EL_ETHRPC_PORT" \ --header 'Content-Type: application/json' \ --data '{ "jsonrpc":"2.0", @@ -388,7 +321,8 @@ curl --location 'http://localhost:8545' \ ### CL block number ```bash -curl -s http://localhost:26657/status | jq '.result.sync_info.latest_block_height'; +. ./env.sh +curl -s "http://localhost:$CL_ETHRPC_PORT/status" | jq '.result.sync_info.latest_block_height'; # [Expected Output]: # 1653733 From 36e6f9b2cdefefbf0cbe541233e7c64bf440ce6a Mon Sep 17 00:00:00 2001 From: Camembear Date: Wed, 2 Sep 2026 14:52:23 -0400 Subject: [PATCH 2/2] Drop v2 restore from Quickstart and stop requiring env.sh. --- SOURCE_MAP.md | 2 +- nodes/operations/quickstart.mdx | 42 ++++++++++++++------------------- 2 files changed, 19 insertions(+), 25 deletions(-) diff --git a/SOURCE_MAP.md b/SOURCE_MAP.md index 732a5d7..5616326 100644 --- a/SOURCE_MAP.md +++ b/SOURCE_MAP.md @@ -20,7 +20,7 @@ Repository names ending in `/` refer to verified local checkouts. Their filesyst | Proof of Liquidity (PoL), BGT, BeraChef, Reward Vaults, incentives | `contracts/` | `src/pol/`; for example, `src/pol/rewards/BeraChef.sol` owns commission and reward allocation | | Consensus client, validators, genesis, `nodes/beaconkit/**`, `nodes/architecture/**` | `beacon-kit/` | Release tags, configuration, command surface, and network artifacts | | Execution client | `bera-reth/` | Releases and configuration | -| Node operations Quickstart snapshot restore (`nodes/operations/quickstart`) | `guides/apps/node-scripts/` | `fetch-berachain-snapshot.sh`, `fetch-berachain-snapshot-v2.sh`, `env.sh`, `lib-snapshot.sh` | +| Node operations Quickstart snapshot restore (`nodes/operations/quickstart`) | `guides/apps/node-scripts/` | `fetch-berachain-snapshot.sh`, `env.sh`, `lib-snapshot.sh` | | Governance proposals | `brips/` | Proposal text | | Cross-repository protocol terms | `UBIQUITOUS_LANGUAGE.md` | Use for names and relationships after verifying mutable values against source | | Deployed PoL addresses | `contracts-internal/script/pol/POLAddresses.sol` | Follow the address pipeline in `CONTRIBUTING.md` instead of editing generated output | diff --git a/nodes/operations/quickstart.mdx b/nodes/operations/quickstart.mdx index 03f7c26..56aaf91 100644 --- a/nodes/operations/quickstart.mdx +++ b/nodes/operations/quickstart.mdx @@ -71,7 +71,6 @@ ls; # README.md run-reth.sh setup-reth.sh # env.sh run-beacond.sh setup-beacond.sh # fetch-berachain-params.sh fetch-berachain-snapshot.sh -# fetch-berachain-snapshot-v2.sh ``` The file `env.sh` contains environment variables used in the other scripts. @@ -110,8 +109,6 @@ You need to set these constants: 4. **EL_ARCHIVE_NODE**: Set to `true` if you want the execution client to be a full archive node. 5. **MY_IP**: Sets the IP address your chain clients advertise to other peers on the network. In a cloud environment such as AWS or GCP where you are behind a NAT gateway, you **must** specify this address or allow the default `curl ipv4.canhazip.com` to auto-detect it. -RPC ports default to 26657 (consensus) and 8545 (execution). Set `PORT_BASE=30000` in the environment before sourcing `env.sh` only if those ports are already taken. - You should verify these constants: - **LOG_DIR**: This directory stores log files. @@ -120,6 +117,20 @@ You should verify these constants: - **BEACOND_CONFIG**: Derived from `BEACOND_DATA`. Do not change it. - **RETH_BIN**: Set this to the full path where you installed `bera-reth`. The expression provided finds it in your $PATH. +### Port allocation + +When `PORT_BASE` is unset, the scripts use these defaults: + +| Port | Client | Use | +| ----- | --------- | -------------------------------- | +| 26657 | BeaconKit | Consensus RPC | +| 26656 | BeaconKit | Consensus P2P | +| 8545 | Bera-Reth | Execution RPC | +| 8551 | Bera-Reth | Engine API (JWT) | +| 30303 | Bera-Reth | Discovery and transaction gossip | + +Set `PORT_BASE=30000` in your shell before running the setup and run scripts only if those ports are already taken or undesirable. The scripts then listen on `PORT_BASE` through `PORT_BASE+7` (consensus RPC at `PORT_BASE`, execution RPC at `PORT_BASE+3`, execution P2P at `PORT_BASE+5`). + ## Step 3 - Fetch parameters The `fetch-berachain-params.sh` script downloads consensus-layer network parameters for the chain you configured: @@ -195,12 +206,11 @@ Snapshots are collections of files from a node's backend that represent its stat `--force` if the target directories contain unexpected files. -After steps 1 through 5, source `env.sh` and run `fetch-berachain-snapshot.sh`. The script needs `curl`, `lz4`, and `tar` on your PATH. It downloads the latest official pruned snapshots from `snapshots.berachain.com` (Mainnet) or `bepolia.snapshots.berachain.com` (Bepolia) and extracts them into `$BEACOND_DATA` and `$RETH_DATA`. It does not overwrite `config/priv_validator_key.json` or `config/jwt.hex`. If `data/priv_validator_state.json` is missing, it writes genesis state so `beacond` can start. +After steps 1 through 5, run `fetch-berachain-snapshot.sh`. The script needs `curl`, `lz4`, and `tar` on your PATH. It reads `CHAIN` and the data directories from `env.sh`, downloads the latest official pruned snapshots from `snapshots.berachain.com` (Mainnet) or `bepolia.snapshots.berachain.com` (Bepolia), and extracts them into those directories. It does not overwrite `config/priv_validator_key.json` or `config/jwt.hex`. If `data/priv_validator_state.json` is missing, it writes genesis state so `beacond` can start. ```bash # FROM: ~/beranode -. ./env.sh ./fetch-berachain-snapshot.sh # [Expected Output]: @@ -214,19 +224,6 @@ After steps 1 through 5, source `env.sh` and run `fetch-berachain-snapshot.sh`. Pass `--network bepolia` when `CHAIN` in `env.sh` is not already `bepolia`. Pass `--type archive` for archive snapshots. `./fetch-berachain-snapshot.sh --help` lists the remaining flags. -Storage v2 uses the same `env.sh` and datadirs. `fetch-berachain-snapshot-v2.sh` reads `v2//catalog.csv`, streams the BeaconKit tarball into `$BEACOND_DATA/data`, and restores Bera-Reth with `bera-reth download --manifest-url`. Pruned execution restore requires `--minimal`, which Bera-Reth v1.4.4 does not have; the script fails closed unless your binary supports that flag. - -```bash -# FROM: ~/beranode - -. ./env.sh -./fetch-berachain-snapshot-v2.sh -``` - -The Mainnet v2 catalog uses the same URL shape and is not published yet. A missing catalog is a generic HTTP or parse error, not a fallback to v1. - -Community snapshots are listed at [Awesome Berachain Validators](https://github.com/chuck-bear/awesome-berachain-validators). - ## Step 7 - Run both clients Launch two terminal windows. In the first, run the consensus client: @@ -281,10 +278,9 @@ To check the sync status of the consensus layer, in another terminal run the fol # FROM: ~/beranode set -e -. ./env.sh # Don't have jq? `brew install jq` -$BEACOND_BIN --home=$BEACOND_DATA status | jq; +beacond --home=var/beacond status | jq; # [Expected Output]: # { @@ -300,8 +296,7 @@ If `catching_up` is set to `true`, it is still syncing. ### EL block number ```bash -. ./env.sh -curl --location "http://localhost:$EL_ETHRPC_PORT" \ +curl --location 'http://localhost:8545' \ --header 'Content-Type: application/json' \ --data '{ "jsonrpc":"2.0", @@ -321,8 +316,7 @@ curl --location "http://localhost:$EL_ETHRPC_PORT" \ ### CL block number ```bash -. ./env.sh -curl -s "http://localhost:$CL_ETHRPC_PORT/status" | jq '.result.sync_info.latest_block_height'; +curl -s http://localhost:26657/status | jq '.result.sync_info.latest_block_height'; # [Expected Output]: # 1653733