# lambdaclass/ethrex architecture

> Architecture diagram of the GitHub repository lambdaclass/ethrex, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lambdaclass/ethrex
- Repository: https://github.com/lambdaclass/ethrex

## Overview

##### Main Components
- L1 Execution Client: Represent the core node that handles Ethereum execution, including the RPC endpoints (http and authenticated RPC), P2P networking (discovery, peer handling, and RLPx protocol), database (libmdbx or the in-memory engine), and EVM execution using backend engines (levm or revm).
- L2 Rollup Client: In a separate section or overlay, show the additional “sequencer” component that proposes blocks, the “prover” subsystem (split into an external proverClient and an internal proverServer), and the set of Solidity contracts deployed on L1 for state commitment and verification.
- Shared Subsystems: Include components for blockchain state management (the blockchain crate that includes state diffs, fork-choice, mempool), the VM component (crates/vm for execution, opcode handling, etc.), and common utility libraries for low-level types and serialization (common, rlp, trie).
- Networking & RPC: Illustrate the complete networking layer with its P2P protocols (discovery and sync via the networking crate) and the RPC layer that accepts both regular (eth) and administrative/control commands.
- Development & Testing Tools: Although not part of the runtime, include an auxiliary block (e.g., “Hive” and “ef_tests”) to indicate how end-to-end and spec compliance testing integrate with the system.

##### Component Relationships and Data Flows
- Interaction between the client and storage, how genesis and network parameters are loaded (from test_data and genesis files), and how configuration plays across several components.

##### Architectural Patterns and Design Principles
- Vertical Integration: Show that the client (both L1 and L2 variants) is vertically integrated with its own metrics, error handling, and configuration—these can be noted in sub-blocks or annotations.
- Dual-mode Operation: Clearly separate or annotate differences between the L1 and L2 modes. For example, note that the L2 mode includes extra modules (proposer, proverClient, proverServer, and smart contracts) compared to the L1 mode.

##### Relevant Technologies and Frameworks
- Rust and Cargo are the primary language/tools.
- The database subsystem uses libmdbx (or an in-memory variant).
- P2P networking (using protocols such as DISCv4, RLPx, and Kademlia) and RPC based on Ethereum’s specifications.
- Docker and Kurtosis are used for containerization and local testing; mention these as deployment tools if setting up environments.
- ZK-Rollup components (RISC-V zkVM integration for the L2 mode) should be highlighted.

## Diagram (Mermaid)

```mermaid
graph TD
  %% L1 Mode Components
  subgraph "L1 Mode"
    A["L1 Execution Client"]:::runtime
    A1["Etherex Core"]:::internal
    A2["CLI Interface"]:::internal
    A3["Networks Config"]:::internal
    B["RPC Layer (L1)"]:::rpc
    C["P2P Networking"]:::p2p
    D["Database/Storage"]:::database
    E1["EVM Engine (levm)"]:::evm
    E2["EVM Engine (revm)"]:::evm

    A1 --> A
    A2 --> A
    A3 --> A
    B --> A
    C --> A
    A --> D
    A --> E1
    A --> E2
  end

  %% Shared Subsystems
  subgraph "Shared Subsystems"
    F["Blockchain State Management"]:::shared
    G["VM & Opcode Handling"]:::shared
    H["Common Utilities"]:::shared
  end

  %% L2 Rollup Mode Components
  subgraph "L2 Rollup Mode"
    I["Sequencer (L2)"]:::l2
    J["Prover Subsystem (L2)"]:::l2
    K["L1 Rollup Contracts"]:::l2
    I ---|"async_proof"| J
    J --> K
    K --> A
  end

  %% Development & Testing Tools
  subgraph "Development & Testing Tools"
    L["ef_tests"]:::testing
    M["Hive Report"]:::testing
  end

  %% Connections from L1 Execution Client to Shared Subsystems
  A --> F
  A --> G
  A --> H

  %% Styles
  classDef runtime fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
  classDef rpc fill:#ABEBC6,stroke:#1D8348,stroke-width:2px;
  classDef p2p fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
  classDef database fill:#FAD7A0,stroke:#D35400,stroke-width:2px;
  classDef evm fill:#E8DAEF,stroke:#8E44AD,stroke-width:2px;
  classDef shared fill:#D5F5E3,stroke:#117864,stroke-width:2px;
  classDef l2 fill:#F5B7B1,stroke:#922B21,stroke-width:2px;
  classDef testing fill:#F2D7D5,stroke:#7B241C,stroke-width:2px;
  classDef internal fill:#D6EAF8,stroke:#2874A6,stroke-width:1px;

  %% Click Events for L1 Mode
  click A "https://github.com/lambdaclass/ethrex/tree/main/cmd/ethrex"
  click A1 "https://github.com/lambdaclass/ethrex/blob/main/cmd/ethrex/ethrex.rs"
  click A2 "https://github.com/lambdaclass/ethrex/blob/main/cmd/ethrex/cli.rs"
  click A3 "https://github.com/lambdaclass/ethrex/tree/main/cmd/ethrex/networks"
  click B "https://github.com/lambdaclass/ethrex/tree/main/crates/networking/rpc"
  click C "https://github.com/lambdaclass/ethrex/tree/main/crates/networking/p2p"
  click D "https://github.com/lambdaclass/ethrex/tree/main/crates/storage"
  click E1 "https://github.com/lambdaclass/ethrex/tree/main/crates/vm/backends/levm"
  click E2 "https://github.com/lambdaclass/ethrex/tree/main/crates/vm/backends/revm"

  %% Click Events for Shared Subsystems
  click F "https://github.com/lambdaclass/ethrex/tree/main/crates/blockchain"
  click G "https://github.com/lambdaclass/ethrex/tree/main/crates/vm"
  click H "https://github.com/lambdaclass/ethrex/tree/main/crates/common"

  %% Click Events for L2 Rollup Mode
  click I "https://github.com/lambdaclass/ethrex/tree/main/crates/l2/sequencer"
  click J "https://github.com/lambdaclass/ethrex/tree/main/crates/l2/prover"
  click K "https://github.com/lambdaclass/ethrex/tree/main/crates/l2/contracts"

  %% Click Events for Development & Testing Tools
  click L "https://github.com/lambdaclass/ethrex/tree/main/cmd/ef_tests"
  click M "https://github.com/lambdaclass/ethrex/tree/main/cmd/hive_report"
```
