From 4ba8aa949b4cca4d5211dc6474929f60e0ba46f0 Mon Sep 17 00:00:00 2001 From: Camembear Date: Fri, 23 Jan 2026 13:15:27 -0500 Subject: [PATCH 1/2] restructure quickstart: improve flow, verify checksums, add cross-links --- apps/core/content/nodes/quickstart.md | 241 +++++++++++++------------- 1 file changed, 122 insertions(+), 119 deletions(-) diff --git a/apps/core/content/nodes/quickstart.md b/apps/core/content/nodes/quickstart.md index a991921a..b0e888c3 100644 --- a/apps/core/content/nodes/quickstart.md +++ b/apps/core/content/nodes/quickstart.md @@ -17,35 +17,57 @@ head: # Berachain Node Quickstart -This guide will walk you through setting up an RPC node on a Linux or Mac computer. If you want to operate Berachain in a production environment, this guide will help you learn how the final system will operate. +A Berachain node consists of two clients running together: a **consensus client** (Beacon-Kit) and an **execution client** (Bera-Reth or Bera-Geth). This guide walks you through setting up both on a Linux or Mac computer. -For true production deployments, consider using the docker images accompanying our releases, or [the community-maintained ansible scripts](https://github.com/RhinoStake/ansible-berachain). +## Prerequisites -## Configurations +### Hardware -This quickstart describes both **mainnet** and **Bepolia** deployments. There are certain scenarios, specifically experimenting with validator and beacon-chain technology, where you're better off with a [local devnet from Beacon-Kit source](/nodes/kurtosis). +| Component | Requirement | +|-----------|-------------| +| **OS** | Linux AMD64, Linux ARM64 | +| **CPU / RAM** | 4 Physical Cores, 16GB RAM | +| **Storage** | 1TB minimum (more for long-term); Local SSD or on-instance storage preferred; network volumes require at least 1000 IOPS | -The scripts use a number of environment variables, created in `env.sh`, to store configuration preferences. Each execution client has its own approach to configuration, reflected in its `setup` and `run` scripts. +### Software -### Hardware Requirements +Install the required binaries before starting: -The following are required to run both the execution and consensus clients: +1. **Beacon-Kit**: Download the appropriate binary from the [releases page](https://github.com/berachain/beacon-kit/releases) for your OS and architecture. Make it executable and place it in your PATH (e.g., `~/.local/bin/`). +2. **Execution client**: Choose either [Bera-Reth](https://github.com/berachain/bera-reth/releases) or [Bera-Geth](https://github.com/berachain/bera-geth/releases). Download the binary for your OS and architecture, make it executable, and place it in your PATH. -- **OS**: Linux AMD64, Linux ARM64 -- **CPU**: 4 Physical Cores -- **RAM**: 16GB -- **Storage**: 1TB minimum; more for a long-term installation -- **Storage performance:** Local SSD or on-instance storage is best; for network volumes, provision at least 1000 IOPS +See [EVM Execution Clients](/nodes/evm-execution) for recommended versions. -### Software Requirements +Verify installation: +```bash +beacond version +bera-reth --version # or bera-geth version +``` + +## What You'll Do -You need [Beacon Kit](https://github.com/berachain/beacon-kit/releases) and one of either [Bera-Reth](https://github.com/berachain/bera-reth/releases) or [Bera-Geth](https://github.com/berachain/bera-geth/releases). [Consult this page](/nodes/evm-execution) for the recommended versions of Beacon Kit and execution clients. +1. **Download scripts** — clone helper scripts that automate configuration +2. **Configure environment** — set environment variables for your network (mainnet or Bepolia) and node identity +3. **Fetch parameters** — download genesis files and network configuration +4. **Set up Beacon-Kit** — initialize the consensus client and generate keys +5. **Set up execution client** — initialize Reth or Geth with the genesis state +6. **Fetch snapshots (optional)** — restore snapshots to speed up initial sync +7. **Fetch address book (optional)** — download peer list for faster startup +8. **Run both clients** — launch them in separate terminals; they communicate via JWT auth -These clients are easily compiled for experiments on a laptop. +Optional step 9 covers testing your node's RPC endpoints. + +:::tip Other deployment methods +For production deployments, consider [docker images](https://github.com/berachain/beacon-kit/pkgs/container/beacon-kit) or [community-maintained Ansible playbooks](https://github.com/RhinoStake/ansible-berachain) that deploy docker containers. For local experimentation with validator mechanics, see [Local Devnet with Kurtosis](/nodes/guides/kurtosis). +::: -## 1 - Download and Configure +## 1 - Download Scripts -Make an area to work in. If you're a Unix traditionalist, choose `/opt/beranode`. Then, clone the berachain node scripts. +Make an area to work in, then clone the Berachain node scripts. These scripts handle configuration, parameter fetching, and client startup. + +:::info +If you're a Unix traditionalist, use `/opt/beranode` as your working directory. +::: ```bash # FROM: $HOME @@ -67,6 +89,10 @@ The file `env.sh` contains environment variables used in the other scripts. `fetch-berachain-params.sh` obtains copies of the genesis file and other configuration files. Then we have `setup-` and `run-` scripts for various execution clients and `beacond`. +## 2 - Configure Environment + +Edit `env.sh` to set your node's configuration. Open the file and modify these values: + **File:** `./env.sh` (simplified) ```bash @@ -104,7 +130,7 @@ You should verify these constants: - **RETH_BIN** or other chain client: Set this to the full path where you installed the chain client. The expression provided finds it in your $PATH. - **CL_ETHRPC_PORT and EL_ETHRPC_PORT** are important for the exchange of consensus and transaction activity. We recommend these to be open for incoming connections on the advertised `MY_IP`. -## 2 - Fetch Parameters +## 3 - Fetch Parameters The `fetch-berachain-params.sh` script downloads the key network parameters for the chain you have configured. Invoke the script as follows to download the files and verify their integrity: @@ -113,22 +139,20 @@ The `fetch-berachain-params.sh` script downloads the key network parameters for ./fetch-berachain-params.sh; -# [Expected Output for mainnet - must match]: -# 77bc26d81f1c8c16070d3b641428901f seed-data-80094/eth-genesis.json -# 2deeecfe9ac40d6a8cced45cca3bf0bc seed-data-80094/eth-nether-genesis.json +# [Expected Output for mainnet - verify these checksums]: # c66dbea5ee3889e1d0a11f856f1ab9f0 seed-data-80094/genesis.json +# 6b333924b81a1935e51ac70e7d9d7cb0 seed-data-80094/eth-genesis.json # 5d0d482758117af8dfc20e1d52c31eef seed-data-80094/kzg-trusted-setup.json -# [Expected Output for bepolia - must match] -# 9e32b2a1a5eb434d7b2fbaa27752b751 seed-data-80069/eth-genesis.json -# 04e689193d6506f36abf98c23b75a07e seed-data-80069/eth-nether-genesis.json +# [Expected Output for bepolia - verify these checksums]: # a24fb9c7ddf3ebd557300e989d44b619 seed-data-80069/genesis.json +# c27c1162af33f7f5401bcef974a64454 seed-data-80069/eth-genesis.json # 5d0d482758117af8dfc20e1d52c31eef seed-data-80069/kzg-trusted-setup.json ``` -Check the signatures above against your results. Further confirmation of the consequences of these signatures is below. +Verify that the checksums for `genesis.json`, `eth-genesis.json`, and `kzg-trusted-setup.json` match the values above for your chosen network. -## 3 - Set Up Beacon-Kit +## 4 - Set Up Beacon-Kit The script `setup-beacond.sh` invokes `beacond init` and `beacond jwt generate`. This script: @@ -142,7 +166,7 @@ The script `setup-beacond.sh` invokes `beacond init` and `beacond jwt generate`. ./setup-beacond.sh; -# expected output: +# [Expected Output]: # BEACOND_DATA: /.../var/beacond # BEACOND_BIN: /.../bin/beacond # Version: v1.1.3 @@ -156,11 +180,13 @@ The script `setup-beacond.sh` invokes `beacond init` and `beacond jwt generate`. Your validator state root **must** agree with the value shown above for your chosen chain. -## 4 - Set Up the Execution Client +## 5 - Set Up the Execution Client The `setup-reth` and `setup-geth` scripts create a runtime directory and configuration for their respective chain clients. The scripts configure the node with pruning settings according to the `EL_ARCHIVE_NODE` setting in `env.sh`. -Here's an example of `setup-reth`: +**If you're using Bera-Reth**, run `setup-reth.sh`. **If you're using Bera-Geth**, run `setup-geth.sh` instead. + +Here's an example using `setup-reth`: ```bash # FROM: ~/beranode @@ -168,10 +194,6 @@ Here's an example of `setup-reth`: ./setup-reth.sh; # [Expected Output]: -# INFO Initialized tracing -# INFO reth init starting -# INFO Opening storage db_path="/.../reth/db" sf_path="/.../reth/static_files" -# INFO Verifying storage consistency. # INFO [BEPOLIA] Genesis block written hash=0x0207661de38f0e54ba91c8286096e72486784c79dc6a9681fc486b38335c042f # INFO [MAINNET] Genesis block written hash=0xd57819422128da1c44339fc7956662378c17e2213e669b427ac91cd11dfcfb38 # ✓ bera-reth set up. @@ -179,54 +201,59 @@ Here's an example of `setup-reth`: Your genesis block hash **must** agree with the above for your chosen chain. -## 5 - Fetch Snapshots (Optional) +## 6 - Fetch Snapshots (Optional) -Snapshots are collections of files from a node's backend that represent its state at a specific time. +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. -They are useful for fixing nodes that become corrupted, or when spinning up a new node. Restoring a snapshot is much faster than syncing from the network. +:::info +Do this step **before** starting your clients (Step 8). 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. In fact, syncing can be significantly faster when you restore both snapshots simultaneously. +Snapshots can be applied to both the consensus (beacond) and execution clients. Restoring both snapshots simultaneously provides the fastest sync. This tutorial fetches pruned snapshots. The script can fetch archive snapshots, too. -### 5a - Obtain Snapshot +### 6a - Obtain Snapshot 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, you can use Berachain official snaps which are capped to 10 Mbyte/sec. Review the script `fetch-berachain-snapshots.js`. The key variables are at [the top](https://github.com/berachain/guides/blob/main/apps/node-scripts/fetch-berachain-snapshot.js): - -**File:** `~/beranode/fetch-berachain-snapshots.js` +- Or, use the `fetch-berachain-snapshot.js` script to download official Berachain snapshots. The script fetches the latest snapshots from `snapshots.berachain.com` and automatically downloads both the beacon-kit and execution layer snapshots matching your configuration. -```nodejs -const snapshot_chain = "bera-testnet-snapshot" || "bera-snapshot"; -const el_client = 'reth' || 'geth'; -const geography = "na" || 'eu' || 'as'; // North America, EU, Asia -const snapshot_type = "pruned" || "archive"; -``` - -Revise the file as appropriate for your situation and geography, then run it: +The script uses command-line arguments. Run it with options: ```bash # FROM: ~/beranode -node fetch-berachain-snapshots.js; +# Default: reth, mainnet, pruned +node fetch-berachain-snapshot.js + +# Or specify options: +node fetch-berachain-snapshot.js --client geth --network testnet --type archive # [Expected Output]: -# Fetching bucket contents... -# Found snapshot_beacond_reth_full_v1.1.3_3768872.tar.lz4 in beacon_reth/pruned -# Downloading snapshot_beacond_reth_full_v1.1.3_3768872.tar.lz4 -# ... +# Bera Snapshot Downloader +# Network: mainnet | Client: reth | Type: pruned +# Fetching snapshot index... +# Will download: snapshot_beacon-kit-pruned_*.tar.lz4, snapshot_reth-pruned_*.tar.lz4 +# Downloading... +# ✓ All downloads completed! ``` -The download may take a while. +The script downloads snapshots to the `downloads/` directory. Both beacon-kit and execution layer snapshots are downloaded automatically. The download may take a while depending on your connection speed. -### 5b - Stop Clients +Available options: +- `--client` or `-c`: Execution client (`reth` or `geth`, default: `reth`) +- `--network` or `-n`: Network (`mainnet` or `testnet`, default: `mainnet`) +- `--type` or `-t`: Snapshot type (`pruned` or `archive`, default: `pruned`) +- `--help` or `-h`: Show help message -Shut down `beacond` and your Execution Layer. +### 6b - Stop Clients -### 5c - Clean Existing Chain Data +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 — to pick an example — reth data store: @@ -248,14 +275,16 @@ ls var/reth; rm -r var/reth/data; ``` -### 5d - Install Beacon-Kit Snapshot +### 6d - Install Beacon-Kit 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 -lz4 -d downloads/snapshot_beacond_reth_...tar.lz4 | tar xv -C var/beacond/; +# 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/ @@ -266,14 +295,16 @@ lz4 -d downloads/snapshot_beacond_reth_...tar.lz4 | tar xv -C var/beacond/; # ... ``` -### 5e - Install Execution Layer Snapshot +### 6e - Install Execution Layer Snapshot -The example below uses `reth`: +Extract the execution layer snapshot. The example below uses `reth` (for `geth`, use `var/geth/` or `var/bera-geth/`): ```bash # FROM: ~/beranode -lz4 -d downloads/snapshot_reth_pruned...tar.lz4 | tar xv -C var/reth/; +# Find the execution layer snapshot (filename pattern: snapshot_reth-* or snapshot_geth-*) +EL_SNAPSHOT=$(ls downloads/snapshot_reth-*.tar.lz4 downloads/snapshot_geth-*.tar.lz4 2>/dev/null | head -1) +lz4 -d "$EL_SNAPSHOT" | tar xv -C var/reth/; # [Expected Output]: # x data/ @@ -283,7 +314,7 @@ lz4 -d downloads/snapshot_reth_pruned...tar.lz4 | tar xv -C var/reth/; # x data/static_files/static_file_transactions_2500000_2999999 ``` -## 6 - Fetch Address Book (Optional) +## 7 - Fetch Address Book (Optional) The `beacond` address book contains a list of nodes to communicate with. Starting with one dramatically improves startup time. @@ -301,7 +332,7 @@ wget https://storage.googleapis.com/bera-testnet-snapshot-na/addrbook.json -O va # ‘var/beacond/config/addrbook.json’ saved ``` -## 7 - Run Both Clients +## 8 - Run Both Clients The following two scripts run the consensus and execution clients. @@ -360,21 +391,12 @@ Launch two terminal windows. In the first, run the consensus client: ./run-beacond.sh; # [Expected Output]: -# INFO Starting service type=telemetry -# INFO Starting service type=engine-client -# INFO Initializing connection to the execution client... service=engine.client dial_url=http://localhost:8551 -# INFO Waiting for execution client to start... 🍺🕔 service=engine.client dial_url=http://localhost:8551 -# -# [AFTER RETH STARTS] -# INFO Connected to execution client service=reporting -# INFO Reporting version service=reporting version=v1.1.3 system=darwin/arm64 eth_version=1.2.0 eth_name=Reth -# +# INFO Waiting for execution client to start... 🍺🕔 +# INFO Connected to execution client +# INFO Reporting version v1.1.3 # [AFTER BLOCKS START FLOWING] # INFO processExecutionPayload ... height=49 ... -# INFO Inserted new payload into execution chain ... payload_parent_block_hash=0x7f9f ... -# INFO Forkchoice updated ... head_block_hash=0xfb2ea... finalized_block_hash=0x7f9f1... # INFO Finalized block ... height=49 ... -# Committed state ... height=49 ... ``` In the second, run the execution client (corresponding to the one you chose). Here it is for Bera-Reth: @@ -385,27 +407,25 @@ In the second, run the execution client (corresponding to the one you chose). He ./run-reth.sh; # [Expected Output]: -# INFO Transaction pool initialized -# INFO P2P networking initialized -# INFO StaticFileProducer initialized -# INFO Pruner initialized -# INFO Consensus engine initialized -# INFO Engine API handler initialized -# INFO RPC auth server started url=127.0.0.1:8551 -# INFO RPC IPC server started path=/tmp/reth.ipc # INFO RPC HTTP server started url=0.0.0.0:8545 # INFO Starting consensus engine -# # [AFTER BLOCKS START FLOWING] -# INFO Forkchoice updated head_block_hash=0x7f9f131 ... -# INFO State root task finished ... number: 49, hash: 0xfb2ea8... # INFO Block added to canonical chain number=49 hash=0xfb2ea... -# INFO Canonical chain committed number=49 hash=0xfb2ea... ``` Initially this will not appear to respond, but within a minute blocks should begin flowing. There should not be a significant number of error messages, except for occasional minor complaints about disconnecting or slow peers. -## 8 - Testing Your Node +:::tip Your node is now running +Both clients are running and will begin syncing with the network. The node will continue syncing in the background. You can proceed to the optional testing steps below, or leave the clients running to complete their sync. +::: + +## 9 - Testing Your Node (Optional) + +Now that your RPC is running, verify that the network is working by performing a few RPC requests. + +:::tip +Make sure that your node is fully synced before proceeding with these steps. +::: ### 8a - Check Sync Status @@ -422,41 +442,16 @@ $BEACOND_BIN --home=$BEACOND_DATA status | jq; # [Expected Output]: # { -# "node_info": {... -# }, # "sync_info": { -# "latest_block_hash": "A72E1C5BD31B0E14604BB6DBA5A313F5B17F78FEE482453D9ED703E49D0C059B", -# "latest_app_hash": "FC649179895650C9B6EB4320A096F46D8882CAD3AAFEE1B0D997B338BDF31618", -# "latest_block_height": "1126228", // [!code ++] <---- CURRENT NETWORK BLOCK -# "latest_block_time": "2024-07-05T03:50:15.349853738Z", -# "earliest_block_hash": "F10DEBCEF3E370F813E93BD8BBFA3DAC0392E6C3E9A8A63871E932ACDE44EE1F", -# "earliest_app_hash": "E3B0C44298FC1C149AFBF4C8996FB92427AE41E4649B934CA495991B7852B855", -# "earliest_block_height": "1", -# "earliest_block_time": "2024-06-05T14:00:00Z", -# "catching_up": false // [!code ++] <---- IF `true` = STILL SYNCING -# }, -# "validator_info": { -# "address": "74F0F7AC6C37306E765487F8C43F01059EE28391", -# "pub_key": { -# "type": "cometbft/PubKeyBls12_381", -# "value": "i/z8e0Fz1+EiW1YGe9wdqCuAM9sny3r8s4gpjLlDHGFQfv36Vffq/+KoCJKuGRT8" -# }, -# "voting_power": "0" +# "latest_block_height": "1126228", // [!code ++] <---- CURRENT NETWORK BLOCK +# "catching_up": false // [!code ++] <---- IF `true` = STILL SYNCING # } # } ``` If `catching_up` is set to `true`, it is still syncing. -### 8b - Testing Local RPC Node - -Now that our RPC is running, let's verify that the network is working by performing a few RPC requests. - -:::tip -Make sure that your node is fully synced before proceeding with these steps. -::: - -### 8c - EL Block Number +### 8b - EL Block Number ```bash curl --location 'http://localhost:8545' \ @@ -477,7 +472,7 @@ curl --location 'http://localhost:8545' \ # } ``` -### 8d - CL Block Number +### 8c - CL Block Number ```bash curl -s http://localhost:26657/status | jq '.result.sync_info.latest_block_height'; @@ -485,3 +480,11 @@ curl -s http://localhost:26657/status | jq '.result.sync_info.latest_block_heigh # [Expected Output]: # 1653733 ``` + +## Next Steps + +Your node is now running and syncing. For production deployments, see: + +- **[Production Checklist](/nodes/production-checklist)** — Best practices for running nodes in production +- **[Monitoring](/nodes/monitoring)** — Set up monitoring and alerts for your node +- **[Become a Validator](/nodes/guides/validator)** — Guide to becoming a validator on Berachain From 508a05760bfcb9c922d49bd00f3b8d14320c03aa Mon Sep 17 00:00:00 2001 From: Camembear Date: Wed, 28 Jan 2026 16:36:31 -0500 Subject: [PATCH 2/2] pnpm format --- apps/core/content/nodes/quickstart.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/apps/core/content/nodes/quickstart.md b/apps/core/content/nodes/quickstart.md index b0e888c3..df296988 100644 --- a/apps/core/content/nodes/quickstart.md +++ b/apps/core/content/nodes/quickstart.md @@ -23,11 +23,11 @@ A Berachain node consists of two clients running together: a **consensus client* ### Hardware -| Component | Requirement | -|-----------|-------------| -| **OS** | Linux AMD64, Linux ARM64 | -| **CPU / RAM** | 4 Physical Cores, 16GB RAM | -| **Storage** | 1TB minimum (more for long-term); Local SSD or on-instance storage preferred; network volumes require at least 1000 IOPS | +| Component | Requirement | +| ------------- | ------------------------------------------------------------------------------------------------------------------------ | +| **OS** | Linux AMD64, Linux ARM64 | +| **CPU / RAM** | 4 Physical Cores, 16GB RAM | +| **Storage** | 1TB minimum (more for long-term); Local SSD or on-instance storage preferred; network volumes require at least 1000 IOPS | ### Software @@ -39,6 +39,7 @@ Install the required binaries before starting: See [EVM Execution Clients](/nodes/evm-execution) for recommended versions. Verify installation: + ```bash beacond version bera-reth --version # or bera-geth version @@ -244,6 +245,7 @@ node fetch-berachain-snapshot.js --client geth --network testnet --type archive The script downloads snapshots to the `downloads/` directory. Both beacon-kit and execution layer snapshots are downloaded automatically. The download may take a while depending on your connection speed. Available options: + - `--client` or `-c`: Execution client (`reth` or `geth`, default: `reth`) - `--network` or `-n`: Network (`mainnet` or `testnet`, default: `mainnet`) - `--type` or `-t`: Snapshot type (`pruned` or `archive`, default: `pruned`)