# ethereum/hevm architecture

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

## Overview

##### Project Type and Purpose
- hevm is a Haskell‐based CLI tool and library that implements the Ethereum Virtual Machine (EVM) for symbolic execution, equivalence checking, and unit testing of smart contracts. It exposes a command‐line interface (CLI) front end and a rich core library of modules under src/EVM, and it integrates external SMT solvers and a small C FFI module (ethjet) for fast hashing.

##### File Structure
- Top‐level directories:
- cli/           → CLI entrypoint (cli/cli.hs)
- src/EVM/       → Core Haskell modules implementing EVM functionality (assembler, symbolic execution, SMT interface, etc.)
- ethjet/        → C source and headers providing fast Blake2 & Keccak via Haskell FFI
- bench/         → Benchmark drivers measuring performance of EVM operations
- test/          → Test suite, including blockchain tests, CLI tests, contract tests
- .github/       → CI and release workflows
- Configuration/build:
- hevm.cabal    → Cabal build instructions for library and hevm executable
- nix files     → Nix flake and lock to pin dependencies

##### Read the README for Additional Insights
- Core capabilities: symbolic execution, equivalence checking, support for Forge test suites
- External dependencies at runtime: z3, cvc5, bitwuzla (invoked as external processes)
- Development: uses nix for reproducible env, cabal for building/testing

a. Main Components
- CLI Frontend (“hevm” binary)
- Core EVM Library (Haskell modules under src/EVM)
- Native FFI Module (ethjet C code)
- External Solvers (Z3, CVC5, Bitwuzla)
- Benchmark Harness (bench/)
- Test Harness (test/)
b. Relationships & Interactions
- CLI → Core Library: dispatches subcommands (symbolic‐exec, equivalence, fuzz, test)
- Core Library → Ethjet FFI: calls into C for Blake2/TinyKeccak hashing
- Core Library → SMT Solvers: spawns/protocol‐talk to external solver processes
- Bench & Test Suites → Core Library: import and drive APIs for performance and correctness tests
- Nix/Cabal → Builds all components and orchestrates development environment
c. Architectural Patterns & Design Principles
- Modular layering:
- Pure core (EVM semantics, assembler, state transitions)
- Effect abstraction (monadic layers for IO, SMT interaction)
- CLI as thin orchestration layer
- Plugin‐style solver integration: external processes called via generic SMT interface
- C FFI for hot code paths (hash functions)
- Test‐driven reliability: extensive test directory, contract fixtures
d. Key Technologies
- Haskell (GHC, Cabal, modules under src/EVM)
- Nix flakes for reproducible dev environment
- C (ethjet) linked via Haskell FFI
- External tools: z3, cvc5, bitwuzla

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    CLI["hevm CLI"]:::cli
    click CLI "https://github.com/ethereum/hevm/blob/main/cli/cli.hs"

    %% Core Library Layer
    subgraph "EVM Core Library" 
        direction TB
        EVMEntry["Library Entry\n(src/EVM.hs)"]:::library
        click EVMEntry "https://github.com/ethereum/hevm/blob/main/src/EVM.hs"
        CoreModules["Core Modules\n(src/EVM/)"]:::library
        click CoreModules "https://github.com/ethereum/hevm/tree/main/src/EVM/"
        Assembler["Assembler\n(src/EVM/Assembler.hs)"]:::library
        click Assembler "https://github.com/ethereum/hevm/blob/main/src/EVM/Assembler.hs"
        SymExec["Symbolic Execution\n(src/EVM/SymExec.hs)"]:::library
        click SymExec "https://github.com/ethereum/hevm/blob/main/src/EVM/SymExec.hs"
        SMTInterface["SMT Interface\n(src/EVM/SMT.hs)"]:::library
        click SMTInterface "https://github.com/ethereum/hevm/blob/main/src/EVM/SMT.hs"
        Solvers["Solver Integration\n(src/EVM/Solvers.hs)"]:::library
        click Solvers "https://github.com/ethereum/hevm/blob/main/src/EVM/Solvers.hs"
    end

    %% Native FFI Layer
    NativeFFI["Ethjet FFI (C)"]:::native
    click NativeFFI "https://github.com/ethereum/hevm/tree/main/ethjet/"

    %% External Solvers
    ExternalSolvers["External SMT Solvers\n(Z3, CVC5, Bitwuzla)"]:::external

    %% Bench and Test Layers
    Bench["Benchmark Suite"]:::test
    click Bench "https://github.com/ethereum/hevm/blob/main/bench/bench.hs"
    TestSuite["Test Suite"]:::test
    click TestSuite "https://github.com/ethereum/hevm/tree/main/test/"

    %% Build Configuration
    subgraph "Build Config"
        direction TB
        Cabal["hevm.cabal"]:::external
        click Cabal "https://github.com/ethereum/hevm/blob/main/hevm.cabal"
        NixFlake["flake.nix\nflake.lock"]:::external
        click NixFlake "https://github.com/ethereum/hevm/blob/main/flake.nix"
        click NixFlake "https://github.com/ethereum/hevm/blob/main/flake.lock"
    end

    %% Connections
    CLI -->|"dispatches commands"| EVMEntry
    EVMEntry --> CoreModules
    CoreModules --> Assembler
    CoreModules --> SymExec
    CoreModules --> SMTInterface
    CoreModules --> Solvers
    CoreModules -->|"hash calls"| NativeFFI
    CoreModules <-->|"SMT protocol"| ExternalSolvers
    Bench -->|"drives API"| CoreModules
    TestSuite -->|"tests API"| CoreModules
    Cabal --> CLI
    Cabal --> CoreModules
    Cabal --> NativeFFI
    NixFlake --> Cabal

    %% Styles
    classDef cli fill:#D6EAF8,stroke:#2980B9,color:#154360
    classDef library fill:#D5F5E3,stroke:#27AE60,color:#145A32
    classDef native fill:#FAD7A0,stroke:#D35400,color:#7E5109
    classDef external fill:#D5D8DC,stroke:#7F8C8D,color:#2C3E50
    classDef test fill:#E8DAEF,stroke:#884EA0,color:#4A235A
```
