# ethereum/evmone architecture

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

- Interactive diagram: https://gitdiagram.com/ethereum/evmone
- Repository: https://github.com/ethereum/evmone

## Overview

##### Project type and purpose
- evmone is a high-performance, standalone C++ library that implements the Ethereum Virtual Machine (EVM) and exposes the EVMC API for integration with Ethereum clients (e.g., geth).
- It provides two interpreters (Baseline and Advanced) and supports precompiled contracts.

##### File structure
- Top-level:
- CMakeLists.txt, Dockerfile, .gitignore, README.md – build and meta files
- cmake/ – build toolchain and dependency management (Hunter)
- /evmone & include/evmmax – public headers for the EVM implementations
- lib/evmone & lib/evmmax – core source code (execution engines)
- lib/evmone_precompiles – implementations of Ethereum precompiled contracts
- test/ – extensive test suites: unit tests, benchmarks, integration, fuzzing
- Patterns:
- Modular source layout, separating core engine, precompiles, interfaces
- CMake with custom modules for dependency resolution (Hunter, GMP finder)

##### Key insights from README
- Targets C++20, depends on intx (256-bit ints) and ethash (Keccak).
- Exposes EVMC ABI: a thin interface layer.
- Two interpreters:
a. Baseline—simple dispatch, minimal analysis
b. Advanced—pre-computed block metrics, indirect call threading, heavy analysis

##### Main components
a. External Ethereum Client
– Calls into EVMC API (shared library)
b. EVMC Interface Layer
– Entry point for host calls: init, execute, destroy
c. EVM Core
– Dispatcher that calls into either Baseline or Advanced interpreter
d. Baseline Interpreter Module
– Minimal JUMPDEST analysis, straightforward fetch–decode–execute loop
e. Advanced Interpreter Module
– Bytecode analyzer (block cost & stack pre-compute)
– Indirect call threading dispatch table
f. Precompiles Module
– Collection of built-in “system contracts” (blake2b, secp256k1, etc.)
g. EOF Parser & Validator
– Parses and validates EVM Object Format at deploy time (optional re-validate)
h. External Dependencies
– intx library (256-bit integers)
– ethash library (Keccak)
– GMP (optional, for full precompile support)

##### Relationships and data flows
- Client → EVMC Interface → EVM Core
- EVM Core → [Baseline | Advanced] → Execution State
- During execution:
- Bytecode is fetched from Execution State → Interpreter
- Interpreter may invoke Precompiles → Execution State
- EOF Parser hooks into EVMC Interface on init or validation calls
- External libs (intx, ethash, GMP) are linked into Precompiles or Core as needed

##### Architectural patterns & design principles
- Plugin architecture via EVMC ABI
- Strategy pattern for interpreter selection (Baseline vs Advanced)
- Modular layering: Interface → Core → Interpreter → Precompiles
- Separation of concerns: parsing/validation vs analysis vs execution

##### Detailed elements
- EVMC API boundary and shared library target (`libevmone.so`)
- Bytecode validation/analysis pipeline (EOF Parser → Bytecode Analyzer)
- Execution pipeline (fetch→decode→execute loop)
- Two interpreter strategies as interchangeable modules
- Precompiles registry and invocation path
- External dependencies and build-time configuration (CMake/Hunter)

## Diagram (Mermaid)

```mermaid
flowchart TD
    ExternalClient["Ethereum Client"]:::external
    subgraph "EVMC Plugin Boundary"
        EVMCInterface["EVMC Interface Layer"]:::interface
    end
    subgraph "EVMone Core"
        EVMCore["EVM Core (Dispatcher)"]:::core
        subgraph "Interpreters"
            Baseline["Baseline Interpreter"]:::module
            Advanced["Advanced Interpreter"]:::module
        end
        Precompiles["Precompiles Module"]:::module
        EVMMAX["EVMMAX (GMP-backed precompiles)"]:::module
        EOFParser["EOF Parser & Validator"]:::parser
    end
    subgraph "External Dependencies"
        Intx["intx Library"]:::deps
        Ethash["ethash Library"]:::deps
        GMP["GMP (optional)"]:::deps
    end
    Build["CMake/Hunter Modules"]:::deps

    ExternalClient -->|"evmc_execute"| EVMCInterface
    EVMCInterface -->|"dispatch()"| EVMCore
    EVMCore -->|"baseline strategy"| Baseline
    EVMCore -->|"advanced strategy"| Advanced
    EVMCore -->|"invoke precompile"| Precompiles
    EVMCore -->|"invoke evmmax"| EVMMAX
    EVMCInterface -->|"validate_eof"| EOFParser

    Precompiles --> Intx
    Precompiles --> Ethash
    Precompiles --> GMP
    EVMCore --> Ethash

    Intx --> Build
    Ethash --> Build
    GMP --> Build

    click EVMCInterface "https://github.com/ethereum/evmone/blob/master/include/evmone/evmone.h"
    click EVMCore "https://github.com/ethereum/evmone/blob/master/lib/evmone/vm.cpp"
    click Baseline "https://github.com/ethereum/evmone/blob/master/lib/evmone/baseline_execution.cpp"
    click Advanced "https://github.com/ethereum/evmone/blob/master/lib/evmone/advanced_execution.cpp"
    click Precompiles "https://github.com/ethereum/evmone/tree/master/lib/evmone_precompiles/"
    click EVMMAX "https://github.com/ethereum/evmone/blob/master/include/evmmax/evmmax.hpp"
    click EOFParser "https://github.com/ethereum/evmone/blob/master/lib/evmone/eof.cpp"
    click Build "https://github.com/ethereum/evmone/tree/master/cmake/"

    classDef external fill:#f9f,stroke:#333,stroke-width:1px
    classDef interface fill:#bbf,stroke:#333,stroke-width:1px
    classDef core fill:#bfb,stroke:#333,stroke-width:1px
    classDef module fill:#ffb,stroke:#333,stroke-width:1px
    classDef parser fill:#fbf,stroke:#333,stroke-width:1px
    classDef deps fill:#eef,stroke:#333,stroke-width:1px
```
