nanoreth/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 and end-user documentation is in book.

Binaries

All binaries are stored in bin.

Storage

These crates are related to the database.

• storage/codecs: Different 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/provider: Traits which provide a higher level api over the database to access the Ethereum state and historical data (transactions, blocks etc.)

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.)

Discovery

• net/discv4: An implementation of the discv4 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.

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/auto-seal: A consensus mechanism that auto-seals blocks for local development (also commonly known as "auto-mine")
• consensus/beacon: Consensus mechanism that handles messages from a beacon node ("eth2")

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.

• blockchain-tree: A tree-like structure for handling multiple chains of unfinalized blocks. This is the main component during live sync (i.e. syncing at the tip)
• stages: A pipelined sync, including implementation of various stages. This is used during initial sync and is faster than the tree-like structure for longer sync ranges.

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-types: Types relevant for the RPC endpoints above, grouped by namespace
• 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 implementation of 'eth' namespace RPC server API
• rpc/rpc-server-types: RPC server types and constants

Utilities Crates

• rpc/rpc-types-compat: This crate 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.

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 are lives in optimism.

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/metrics-derive: A derive-style API for creating metrics
• tracing: A small utility crate to install a uniform tracing subscriber