reth/docs/repo/layout.md

Project Layout

This repository contains several Rust crates that implement the different building blocks of an Ethereum node. The high-level structure of the repository is as follows:

Generally, reth is composed of a few components, with supporting crates. The main components can be defined as:

• Project Layout
  • Documentation
  • Binaries
  • Storage
  • Networking
    • Common
    • Discovery
    • Protocol
    • Downloaders
  • Consensus
  • Execution
  • Sync
  • RPC
    • Transports
    • Common
    • Utilities Crates
  • Payloads
  • Primitives
  • Optimism
  • Misc

The supporting crates are split into two categories: primitives and miscellaneous.

Documentation

Contributor documentation is in docs.

Binaries

All binaries are stored in bin.

Storage

These crates are related to the database.

• storage/codecs: Different storage codecs.
• storage/codecs/derive: Derive macros for storage codecs.
• storage/libmdbx-rs: Rust bindings for libmdbx. A fork of an earlier Apache-licensed version of libmdbx-rs.
• storage/db: Strongly typed Database abstractions (transactions, cursors, tables) over lower level database backends.
  • Implemented backends: mdbx
• storage/db-api: High-level database access traits used across storage crates.
• storage/db-common: Shared database helpers and utilities.
• storage/db-models: Typed database models for on-disk tables.
• storage/storage-api: Storage-facing APIs used by higher-level components.
• storage/provider: Traits which provide a higher level api over the database to access the Ethereum state and historical data (transactions, blocks etc.)
• storage/rpc-provider: Storage provider implementations tailored for RPC access patterns.
• storage/errors: Common error types used by storage crates.
• storage/nippy-jar: Compressed columnar storage for historical data.
• storage/zstd-compressors: Zstandard-based compressors used by storage components.

Networking

These crates are related to networking (P2P).

The networking component mainly lives in net/network, which handles:

• Message egress/ingress
• Peer management
• Session management

Common

• net/banlist: A simple peer banlist that can be used to ban peers or IP addresses.
  • Contains: Peer banlist.
• net/network-api: Contains traits that define the networking component as a whole. Other components that interface with the network stack only need to depend on this crate for the relevant types.
• net/nat: A small helper crate that resolves the external IP of the running node using various methods (such as a manually provided IP, using UPnP etc.)
• net/network-types: Common networking types (peer identifiers, capabilities, messages, etc.).
• net/p2p: Higher-level P2P networking helpers and utilities.
• net/peers: Peer set management, scoring and reputation support.

Discovery

• net/discv4: An implementation of the discv4 protocol
• net/discv5: An implementation of the discv5 node discovery protocol.
• net/dns: An implementation of node discovery via DNS (EIP-1459)

Protocol

• net/eth-wire: Implements the eth wire protocol and the RLPx networking stack.
• net/ecies: Implementation of the Elliptic Curve Integrated Encryption Scheme used in the RLPx handshake.
• net/eth-wire-types: Common types used by the eth wire protocol and RLPx networking stack.

Downloaders

• net/downloaders: Traits defining block body and header downloaders, as well as P2P implementations of both.

Consensus

Different consensus mechanisms.

• consensus/common: Common consensus functions and traits (e.g. fee calculation).
• consensus/consensus: Core consensus engine interfaces and implementations.
• consensus/debug-client: Utilities for interacting with the consensus engine in debugging and testing scenarios.

Execution

Crates related to transaction execution.

• revm: Revm utils and implementations specific to reth.
• evm: Traits for configuring an EVM specifics.
• execution-types: Commonly used types for (EVM) block execution.
• execution-errors: Commonly used error types used when doing block execution.

Sync

These crates implement the main syncing drivers of reth.

• stages/api: Public API for the staged sync pipeline.
• stages/stages: Implementations of the individual sync stages and the pipeline driver. This is used during initial sync and is faster than the tree-like structure for longer sync ranges.
• stages/types: Shared types used by the staged sync pipeline.

RPC

Crates related to the RPC component (including IPC transport)

The RPC component mainly lives in rpc/rpc, which implements the following namespaces:

• admin_
• debug_ (includes Geth-style tracing APIs)
• eth_
• net_
• trace_ (OpenEthereum-style tracing APIs)
• txpool_
• web3_

These RPC interface is defined in rpc/rpc-api.

The engine API (engine_) lives in rpc/rpc-engine-api (this is not an interface crate despite the confusing name).

There is also a crate to easily configure an RPC server: rpc/rpc-builder.

Transports

The RPC component is based on the jsonrpsee crate which provides JSONRPC over WebSockets and HTTP.

The IPC transport lives in rpc/ipc.

Common

• rpc/rpc-api: RPC traits
  • Supported transports: HTTP, WS, IPC
  • Supported namespaces: eth_, engine_, debug_
• rpc/rpc-eth-api: Reth RPC 'eth' namespace API (including interface and implementation), this crate is re-exported by rpc/rpc-api
• rpc/rpc-eth-types: Types supporting the implementation of 'eth' namespace RPC server API
• rpc/rpc-server-types: RPC server types and constants

Utilities Crates

• rpc/rpc-convert: This crate provides various helper functions to convert between reth primitive types and rpc types.
• rpc/layer: Some RPC middleware layers (e.g. AuthValidator, JwtAuthValidator)
• rpc/rpc-testing-util: Reth RPC testing helpers

Payloads

Crates related to building and validating payloads (blocks).

• transaction-pool: An in-memory pending transactions pool.
• payload/builder: Abstractions for payload building and a payload builder service that works with multiple kinds of payload resolvers.
• payload/basic: A basic payload generator.
• payload/builder-primitives: Common primitives used by payload builders.
• payload/primitives: Shared types used when building and validating payloads.
• payload/util: Utility helpers used by payload building and validation logic.
• payload/validator: Payload validation helpers and utilities.

Primitives

These crates define primitive types or algorithms.

• primitives: Commonly used types in Reth.
• primitives-traits: Common abstracted types in reth.
• trie: An implementation of a Merkle Patricia Trie used for various roots (e.g. the state root) in Ethereum.

Optimism

Crates related to the Optimism rollup live in optimism.

Ethereum-Specific Crates

Ethereum mainnet-specific implementations and primitives live in crates/ethereum/.

• reth-ethereum-engine-primitives (crates/ethereum/engine-primitives)
  Ethereum-specific types for engine API, consensus messages, and payload attributes.

• reth-ethereum-forks (crates/ethereum/hardforks)
  Mainnet-specific hardfork definitions, activation schedules, and feature flags.

• reth-ethereum-payload-builder (crates/ethereum/payload)
  Ethereum-tailored payload builder implementing mainnet block production rules.

Misc

Small utility crates.

• tasks: An executor-agnostic task abstraction, used to spawn tasks on different async executors. Supports blocking tasks and handles panics gracefully. A tokio implementation is provided by default.
• metrics/common: Common metrics types (e.g. metered channels)
• metrics: Reth use metrics for metrics collection, which is a lightweight metrics facade
• metrics/metrics-derive: A derive-style API for creating metrics
• metrics/reth-node-metrics: The implementation of metrics server, recorder, hooks.
• tracing: A small utility crate to install a uniform tracing subscriber
• fs-util: Small filesystem utilities shared across the node.
• tokio-util: Tokio-related utilities used by reth.
• static-file: Utilities for bundling and serving static files.
• tracing-otlp: Exporter for sending tracing spans to OTLP/OTel backends.
• errors: Common error types shared across multiple crates.
• e2e-test-utils: Helpers for end-to-end tests of the node.