# lita-xyz/reva architecture

> Architecture diagram of the GitHub repository lita-xyz/reva, 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/lita-xyz/reva
- Repository: https://github.com/lita-xyz/reva

## Overview

##### Main Components
- Host Application: Represented by the “bin/host” directory. Its core responsibility is to fetch blockchain data via RPC calls (using provided block number and chain ID), process that data, and serialize it into an input file (e.g., bin/host/input/<chain_id>/<block_no>.bin).
- Client Applications: There are at least two clients – “client-eth” (for Ethereum) and “client-op” (for the OP Stack) found under “bin/client-eth” and “bin/client-op” respectively. Their role is to consume the input generated by the host and run or prove the computation inside the Valida VM.
- Executor Logic and Libraries: This includes several reusable crates in the “crates” directory (such as executor, mpt, primitives, storage). These libraries encapsulate core logic such as:
- Executor: Split into host and client parts (e.g., crates/executor/host and crates/executor/client) managing simulation and execution flows.
- MPT: Likely used for Merkle-Patricia Tree operations which are central to Ethereum state management.
- Primitives: Common data structures and definitions (like chain specifications and account proofs).
- Storage: Separate sub-crates (rpc-db and witness-db) that provide interfaces for storing the serialized input and proof data.
- External Tools & Environment:
- The repository requires the Valida tools (a custom runtime and Rust compiler) for building and running the binaries.
- Build systems (Cargo, Justfile, and scripts) and GitHub workflows for continuous integration, versioning, and deployment automation.

##### Relationships and Interactions
- Data Flow:
- External Input: The system starts with an external blockchain RPC call (using a provided RPC URL) initiated by the host application.
- Host Processing: The host application fetches block data, processes it using the shared libraries (executor, primitives, storage, etc.), and outputs a serialized binary file.
- Client Execution: The client applications (client-eth or client-op) then take the binary file as input to run the zero-knowledge proof generation or verification routines.
- Dependency & Layered Architecture:
- The host and client binaries both depend on the lower-level crates for domain logic (e.g., executor, mpt) and data structures (primitives).
- The architecture shows a clear separation of concerns: data gathering (host), data processing (shared libraries), and proof generation/execution (client).

##### Architectural Patterns and Technologies
- Separation of Concerns: Clear division between host (data preparation) and clients (execution/proving).
- Modular Design: Usage of Cargo workspaces (with multiple Cargo.toml files in subdirectories) to keep libraries and binaries decoupled yet interoperable.
- Targeted Compilation: The system uses custom compilation targets (e.g., "valida-unknown-baremetal-gnu") to aggregate code for the Valida VM environment.
- Continuous Integration & Tooling: GitHub workflows are set up (check “.github/workflows”) ensuring build automation and integration testing.
- Key Technologies:
- Rust (primary language)
- Valida VM and its custom toolchain (via cargo +valida)
- Zero-knowledge proofs technology, as inferred from the README description
- Reth framework functionalities (for interacting with the Ethereum network)

##### Final Advice for the Principal Software Engineer
- Component is clearly labeled with its directory or service name (for example, “Host (bin/host)”, “Client – Ethereum (bin/client-eth)”, “Client – OP (bin/client-op)”, “Executor Libraries (crates/executor)”, etc.).
- Remember to add notes or legends capturing the custom build targets (“valida-unknown-baremetal-gnu”) and the use of the Valida toolchain.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["External Blockchain RPC"]:::external
    B["Host Application (bin/host)"]:::binary
    C["Serialized Input File"]:::artifact
    D["Client – Ethereum (bin/client-eth)"]:::binary
    E["Client – OP Stack (bin/client-op)"]:::binary

    subgraph "Shared Libraries"
        F["Executor (Host Side) (crates/executor/host)"]:::library
        G["Executor (Client Side) (crates/executor/client)"]:::library
        H["MPT Library (crates/mpt)"]:::library
        I["Primitives Library (crates/primitives)"]:::library
        J["Storage – RPC Database (crates/storage/rpc-db)"]:::library
        K["Storage – Witness Database (crates/storage/witness-db)"]:::library
    end

    L["Valida Toolchain & VM"]:::external

    %% Main Flow
    A -->|"FetchRPC"| B
    B -->|"SerializeData"| C
    C -->|"RouteInput"| D
    C -->|"RouteInput"| E

    %% Host Dependencies
    B ---|"uses"| F
    B ---|"uses"| H
    B ---|"uses"| I
    B ---|"uses"| J
    B ---|"uses"| K

    %% Client – Ethereum Dependencies
    D ---|"uses"| G
    D ---|"uses"| H
    D ---|"uses"| I
    D ---|"uses"| J
    D ---|"uses"| K

    %% Client – OP Stack Dependencies
    E ---|"uses"| G
    E ---|"uses"| H
    E ---|"uses"| I
    E ---|"uses"| J
    E ---|"uses"| K

    %% Compilation dependency on Valida Toolchain & VM
    B ---|"compiledWith"| L
    D ---|"compiledWith"| L
    E ---|"compiledWith"| L

    %% Click Events
    click B "https://github.com/lita-xyz/reva/tree/main/bin/host"
    click D "https://github.com/lita-xyz/reva/tree/main/bin/client-eth"
    click E "https://github.com/lita-xyz/reva/tree/main/bin/client-op"
    click F "https://github.com/lita-xyz/reva/tree/main/crates/executor/host"
    click G "https://github.com/lita-xyz/reva/tree/main/crates/executor/client"
    click H "https://github.com/lita-xyz/reva/tree/main/crates/mpt"
    click I "https://github.com/lita-xyz/reva/tree/main/crates/primitives"
    click J "https://github.com/lita-xyz/reva/tree/main/crates/storage/rpc-db"
    click K "https://github.com/lita-xyz/reva/tree/main/crates/storage/witness-db"

    %% Styles
    classDef external fill:#F5B7B1,stroke:#922B21,stroke-width:2px;
    classDef binary fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef library fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef artifact fill:#ABEBC6,stroke:#27AE60,stroke-width:2px;
```
