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

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

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

The Ream node is operated via the CLI by running the ream 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

ream

A Rust implementation of the Ethereum Beam Chain specification.

$ ream --help

Usage: ream <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
  help             Print this message or the help of the given subcommand(s)

Options:
  -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>

Options:
  -v, --verbosity <VERBOSITY>  Verbosity level [default: 3]
      --network <NETWORK>      Provide a path to a YAML config file
  -h, --help                   Print help

ream beacon_node

Start the beacon node

$ ream beacon_node --help

Usage: ream beacon_node [OPTIONS]

Options:
  -v, --verbosity <VERBOSITY>
          Verbosity level [default: 3]
      --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
      --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.
      --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>
      --purge-db
          Purges the database.
      --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:
  -v, --verbosity <VERBOSITY>
          Verbosity level [default: 3]
      --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:
  -v, --verbosity <VERBOSITY>      Verbosity level [default: 3]
  -l, --lifetime <LIFETIME>        Account lifetime in 2 ** lifetime slots [default: 28]
  -c, --chunk-size <CHUNK_SIZE>    Chunk size for messages [default: 5]
  -s, --seed-phrase <SEED_PHRASE>  Seed phrase for key generation
  -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:
  -v, --verbosity <VERBOSITY>
          Verbosity level [default: 3]
      --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

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

ream Book