Ream

What is Ream

Ream aims to be modular, contributor-friendly, and blazingly fast implementation of the Beam Chain specification. One of our goals is to build an ecosystem where developers can seamlessly build on Ream, saving time and avoiding the need to reinvent the wheel.

Join

Telegram

Quick Start

This guide will help you get a Ream node up and running quickly.

Build from Source

You can build Ream on Linux.

Dependencies

First install Rust using rustup:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

There are some other dependencies you need to install based on your operating system (OS):

  • Ubuntu/Debian: apt-get install libclang-dev pkg-config libssl-dev build-essential

Install cargo-sort and cargo-udeps tools.

cargo install cargo-udeps --locked
cargo install --git https://github.com/DevinR528/cargo-sort.git --rev 25a60ad860ce7cd0055abf4b69c18285cb07ab41 cargo-sort

Build Ream

Clone the repository and move to the directory:

git clone git@github.com:reamlabs/ream.git
cd ream

After everything is setup, you can start the build:

make build

Running a Lean Node

The quickest way to get started is to run a lean node on the Ephemery testnet:

cargo run --release -- --ephemeral lean_node \
    --network ephemery \
    --validator-registry-path ./bin/ream/assets/lean/validator_registry.yml

Understanding the Command

  • cargo run --release - Builds and runs Ream in release mode
  • --ephemeral - Run in ephemeral mode (data is not persisted)
  • lean_node - Start a lean consensus node
  • --network ephemery - Use the Ephemery network
  • --validator-registry-path - Path to the validator registry configuration

Metrics

To enable your node to expose metrics through Prometheus, add the --metrics flag:

cargo run --release -- --ephemeral lean_node \
    --network ephemery \
    --validator-registry-path ./bin/ream/assets/lean/validator_registry.yml \
    --metrics --metrics-address 0.0.0.0

By default, metrics are exposed on 127.0.0.1:8080.

For a complete list of all commands and flags for running a lean node, see the ream lean_node CLI Reference.

Visualizing Metrics with Grafana

The repository includes a pre-configured Prometheus and Grafana setup in the metrics/ directory. To run the metrics stack:

cd metrics
docker compose up

This will start:

  • Prometheus (scrapes metrics from your node)
  • Grafana (visualizes metrics with a pre-configured dashboard)

View the dashboard at http://localhost:3000 and use the default credentials: admin/admin.

Running a Local PQ Devnet

For local development and testing, you can run a local PQ devnet here.

Developer's Guide

The Developer's Guide contains detailed documentation about Ream's architecture, components, and implementation details to help developers understand and contribute to the codebase.

P2P Networking

This document describes the architecture of Ream's networking layer.

Architecture Overview

The networking stack is organized into 5 main layers:

┌──────────────────────────────────────────────────────────────────────────────┐
│                       ream-p2p::config::NetworkConfig                        │
│                    (Container for network configurations)                    │
│       ┌────────────────────────────┐  ┌────────────────────────────┐         │
│       │      DiscoveryConfig       │  │      GossipsubConfig       │         │
│       └────────────────────────────┘  └────────────────────────────┘         │
└─────────────────────────────────────┬────────────────────────────────────────┘
                                      │
                                      ▼
┌──────────────────────────────────────────────────────────────────────────────┐
│              ream-network-manager::service::NetworkManagerService            │
│ (Orchestrates between network components and the rest of the beacon client)  │
└─────────────────────────────────────┬────────────────────────────────────────┘
                                      │
                                      ▼
┌──────────────────────────────────────────────────────────────────────────────┐
│                         ream-p2p::network::Network                           │
│             (The network instance with initialized configurations)           │
└─────────────────────────────────────┬────────────────────────────────────────┘
                                      │
                                      ▼
┌──────────────────────────────────────────────────────────────────────────────┐
│                       ream-p2p::network::ReamBehaviour                       │
│                        (Handles ream's p2p behaviours)                       │
│  ┌───────────────────────┐┌───────────────────────┐┌──────────────────────┐  │
│  │   DiscoveryBehaviour  ││  GossipsubBehaviour   ││   ReqRespBehaviour   │  │
│  └───────────────────────┘└───────────────────────┘└──────────────────────┘  │
└──────────────────────────────────────────────────────────────────────────────┘
                                      │
                                      ▼
┌──────────────────────────────────────────────────────────────────────────────┐
│                            libp2p::swarm::Swarm                              │
│                      (Manages the p2p transport layer)                       │
└──────────────────────────────────────────────────────────────────────────────┘

Components

ream-p2p::config::NetworkConfig

The configuration container that holds all network-related settings:

  • DiscoveryConfig: Configuration for discv5 peer discovery including bootnodes, subnet subscriptions, and discovery parameters
  • GossipsubConfig: Configuration for gossipsub behavior including topics, message sizes, and propagation settings

ream-network-manager::service::NetworkManagerService

The NetworkManagerService acts as the entrypoint and central coordinator for all networking activities. It is responsible for:

  • Initializing network configurations
  • Creating and managing the Network component
  • Processing incoming network events (gossip messages, request/response)
  • Routing messages between the network layer and the beacon chain logic

ream-p2p::network::Network

The Network struct is the core P2P networking component that:

  • Creates and manages the libp2p swarm and all network behaviors (Discovery, Gossipsub, ReqResp)
  • Handles peer connections and disconnections
  • Coordinates between different protocol behaviors (GossipSub, Req/Resp, Discovery)
  • Provides the main event loop for processing network events
  • Maintains network state and peer information

ream-p2p::network::ReamBehaviour

The ReamBehaviour component creates and manages several behaviors:

  • Discovery Behaviour: Integrates with discv5 for peer discovery and subnet management
  • GossipSub Behaviour: Handles topic-based message propagation for consensus objects
  • Req/Resp Behaviour: Manages request-response protocols for block/blob synchronization

libp2p::swarm::Swarm

The libp2p swarm provides:

  • Unified interface for all network behaviors
  • Connection management and multiplexing
  • Transport layer abstraction

CLI Reference

Ream can be operated via the CLI by running either the ream lean_node or ream beacon_node command. To stop it, press ctrl-c. You may need to wait a bit as Ream tears down existing p2p connections or other cleanup tasks.

However, Ream has more commands:

ream

A Rust implementation of the Ethereum Beam Chain specification.

$ ream --help

Usage: ream [OPTIONS] <COMMAND>

Commands:
  lean_node             Start the lean node
  beacon_node           Start the beacon node
  validator_node        Start the validator node
  account_manager       Manage validator accounts
  voluntary_exit        Perform voluntary exit for a validator
  generate_private_key  Generate a secp256k1 keypair for lean node
  generate_keystore     Generate keystore file
  help                  Print this message or the help of the given subcommand(s)

Options:
  -v, --verbosity <VERBOSITY>  Verbosity level (1=error, 2=warn, 3=info, 4=debug, 5=trace) [default: 3]
      --data-dir <DATA_DIR>    The directory for storing application data. If used together with --ephemeral, new child directory will be created.
  -e, --ephemeral              Use new data directory, located in OS temporary directory. If used together with --data-dir, new directory will be created there instead.
      --purge-db               Purges the database.
  -h, --help                   Print help
  -V, --version                Print version

ream lean_node

Start the lean node

$ ream lean_node --help

Usage: ream lean_node [OPTIONS] --network <NETWORK> --validator-registry-path <VALIDATOR_REGISTRY_PATH>

Options:
      --network <NETWORK>
          Provide a path to a YAML config file, or use 'ephemery' for the Ephemery network
      --bootnodes <BOOTNODES>
          Bootnodes configuration: Use 'default' for network defaults, 'none' to disable, '/path/to/nodes.yaml' for a YAML file with ENRs, or comma-delimited base64-encoded ENRs [default: default]
      --validator-registry-path <VALIDATOR_REGISTRY_PATH>
          The path to the validator registry
      --node-id <NODE_ID>
          Node identifier for validator registry (e.g., 'ream_0', 'zeam_0') [default: ream]
      --private-key-path <PRIVATE_KEY_PATH>
          The path to the hex encoded secp256k1 libp2p key
      --socket-address <SOCKET_ADDRESS>
          Set P2P socket address [default: 0.0.0.0]
      --socket-port <SOCKET_PORT>
          Set P2P socket port (QUIC) [default: 9000]
      --http-address <HTTP_ADDRESS>
          Set HTTP address [default: 127.0.0.1]
      --http-port <HTTP_PORT>
          Set HTTP Port [default: 5052]
      --http-allow-origin

      --metrics
          Enable metrics
      --metrics-address <METRICS_ADDRESS>
          Set metrics address [default: 127.0.0.1]
      --metrics-port <METRICS_PORT>
          Set metrics port [default: 8080]
  -h, --help
          Print help

ream beacon_node

Start the beacon node

$ ream beacon_node --help

Usage: ream beacon_node [OPTIONS]

Options:
      --network <NETWORK>
          Choose mainnet, holesky, sepolia, hoodi, dev or provide a path to a YAML config file [default: mainnet]
      --http-address <HTTP_ADDRESS>
          Set HTTP address [default: 127.0.0.1]
      --http-port <HTTP_PORT>
          Set HTTP Port [default: 5052]
      --http-allow-origin

      --socket-address <SOCKET_ADDRESS>
          Set P2P socket address [default: 0.0.0.0]
      --socket-port <SOCKET_PORT>
          Set P2P socket port (TCP) [default: 9000]
      --discovery-port <DISCOVERY_PORT>
          Discovery 5 listening port (UDP) [default: 9000]
      --disable-discovery
          Disable Discv5
      --bootnodes <BOOTNODES>
          One or more comma-delimited base64-encoded ENR's of peers to initially connect to. Use 'default' to use the default bootnodes for the network. Use 'none' to disable bootnodes. [default: default]
      --checkpoint-sync-url <CHECKPOINT_SYNC_URL>
          Trusted RPC URL to initiate Checkpoint Sync.
      --weak-subjectivity-checkpoint <WEAK_SUBJECTIVITY_CHECKPOINT>
          Weak subjectivity checkpoint in format <0xblock_root>:<epoch>
      --execution-endpoint <EXECUTION_ENDPOINT>
          The URL of the execution endpoint. This is used to send requests to the engine api.
      --execution-jwt-secret <EXECUTION_JWT_SECRET>
          The JWT secret used to authenticate with the execution endpoint. This is used to send requests to the engine api.
  -h, --help
          Print help

ream validator_node

Start the validator node

$ ream validator_node --help

Usage: ream validator_node [OPTIONS] --import-keystores <IMPORT_KEYSTORES> --suggested-fee-recipient <SUGGESTED_FEE_RECIPIENT>

Options:
      --beacon-api-endpoint <BEACON_API_ENDPOINT>
          Set HTTP url of the beacon api endpoint [default: http://localhost:5052]
      --request-timeout <REQUEST_TIMEOUT>
          Set HTTP request timeout for beacon api calls [default: 60]
      --key-manager-http-address <KEY_MANAGER_HTTP_ADDRESS>
          Set HTTP address of the key manager server [default: 127.0.0.1]
      --key-manager-http-port <KEY_MANAGER_HTTP_PORT>
          Set HTTP Port of the key manager server [default: 8008]
      --network <NETWORK>
          Choose mainnet, holesky, sepolia, hoodi, dev or provide a path to a YAML config file [default: mainnet]
      --import-keystores <IMPORT_KEYSTORES>
          The directory for importing keystores
      --suggested-fee-recipient <SUGGESTED_FEE_RECIPIENT>
          The suggested fee recipient address where staking rewards would go to
      --password-file <PASSWORD_FILE>
          The plaintext password file to use for keystores
      --password <PASSWORD>
          The password to use for keystores. It's recommended to use password-file over this in order to prevent your keystore password from appearing in the shell history
      --enable-builder
          Enable external block builder
      --mev-relay-url <MEV_RELAY_URL>
          Set HTTP url of MEV relay to connect to for external block building. Will only be used if `enable_builder` is passed.
  -h, --help
          Print help

ream account_manager

Manage validator accounts

$ ream account_manager --help

Usage: ream account_manager [OPTIONS]

Options:
  -l, --lifetime <LIFETIME>
          Account lifetime in 2 ** lifetime slots [default: 18]
  -c, --chunk-size <CHUNK_SIZE>
          Chunk size for messages [default: 5]
  -s, --seed-phrase <SEED_PHRASE>
          Seed phrase for key generation
      --passphrase <PASSPHRASE>
          Optional BIP39 passphrase used with the seed phrase
      --activation-epoch <ACTIVATION_EPOCH>
          Activation epoch for the validator [default: 0]
      --num-active-epochs <NUM_ACTIVE_EPOCHS>
          Number of active epochs [default: 262144]
      --keystore-path <KEYSTORE_PATH>
          Path for keystore directory (relative to data-dir if not absolute)
  -h, --help
          Print help

ream voluntary_exit

Perform voluntary exit for a validator

$ ream voluntary_exit --help

Usage: ream voluntary_exit [OPTIONS] --import-keystores <IMPORT_KEYSTORES> --validator-index <VALIDATOR_INDEX>

Options:
      --beacon-api-endpoint <BEACON_API_ENDPOINT>
          Set HTTP url of the beacon api endpoint [default: http://localhost:5052]
      --request-timeout <REQUEST_TIMEOUT>
          Set HTTP request timeout for beacon api calls [default: 60]
      --network <NETWORK>
          Choose mainnet, holesky, sepolia, hoodi, dev or provide a path to a YAML config file [default: mainnet]
      --import-keystores <IMPORT_KEYSTORES>
          The directory for importing keystores
      --password-file <PASSWORD_FILE>
          The plaintext password file to use for keystores
      --password <PASSWORD>
          The password to use for keystores. It's recommended to use password-file over this in order to prevent your keystore password from appearing in the shell history
      --validator-index <VALIDATOR_INDEX>
          The validator index to exit
      --wait
          Wait until the validator has fully exited
  -h, --help
          Print help

ream generate_private_key

Generate a secp256k1 keypair for lean node

$ ream generate_private_key --help

Usage: ream generate_private_key --output-path <OUTPUT_PATH>

Options:
      --output-path <OUTPUT_PATH>  Output path for the hex encoded secp256k1 keypair
  -h, --help                       Print help

ream generate_keystore

Generate keystore file

$ ream generate_keystore --help

Usage: ream generate_keystore [OPTIONS]

Options:
      --output <OUTPUT>                              [default: keystore-hashsig.yaml]
      --number-of-validators <NUMBER_OF_VALIDATORS>  [default: 1]
      --number-of-keys <NUMBER_OF_KEYS>              [default: 1]
  -h, --help                                         Print help

Changelog

To view all Changes made to the project, run this in your terminal:

git log --pretty="-%s"

To add all Changes in a Changelog.md file, run this in your terminal: 

git log --pretty="- %s" > CHANGELOG.md