# ethereum/execution-specs architecture

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

## Overview

##### Project Type and Purpose
This is an open-source Python library (“execution-specs”) that encodes the Ethereum execution client specification. It:
- Implements protocol “fork” logic and EVM semantics in Python modules (src/ethereum/…)
- Provides network-upgrade spec documents (network-upgrades/)
- Generates rendered documentation (static/, doc tooling)
- Ships CLI and helper scripts (scripts/)
- Includes extensive tests (tests/) and CI workflows (/.github/workflows/)

##### High-Level Component Analysis
Top-level directories indicate:
- src/ethereum – core Python packages broken into:
– “fork” modules per upgrade (frontier, berlin, london, …)
– VM implementation (interpreter, instructions, precompiles)
– Crypto & util support
– Genesis and network assets
– Optimized implementations (ethereum_optimized) and spec tooling (ethereum_spec_tools)
- network-upgrades – markdown specs of each hard-fork
- lists – EVM opcode definitions, signature type lists
- scripts – generation & helper scripts (genesis config, downloading clients)
- static – CSS override for docs
- tests – pytest test harness per fork, VM, tools, utilities
- . github/workflows – CI pipelines for tests and doc publishing

##### Key Architectural Patterns
- Modular fork-per-release structure: each hard-fork is self-contained for easy spec updates
- Layered EVM interpreter: instruction dispatch → interpreter → state transition → block processing
- Separation of concerns: spec code (src/ethereum), tooling (ethereum_spec_tools), assets, docs, CI

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Actors
    Developer["Developer"]:::actor

    %% Core Spec Library
    subgraph "Core Spec Library" 
        ForkModules["Fork Modules"]:::blue
        Interpreter["Interpreter"]:::blue
        Instructions["Instructions"]:::blue
        Precompiles["Precompiled Contracts"]:::blue
        Crypto["Crypto Support"]:::blue
        Utils["Utilities"]:::blue
        Assets["Genesis & Network Assets"]:::blue
        Optimized["Optimized Implementations"]:::blue
        SpecTools["Spec Tooling"]:::blue
    end

    %% Documentation and Site
    subgraph "Documentation" 
        NetDocs["Network Upgrade Documents"]:::orange
        Lists["Lists & Metadata"]:::green
        SigLists["Signature Types"]:::green
        DocsGen["Documentation Generator"]:::orange
        Site["Static Site (GitHub Pages)"]:::orange
        Static["Static Styles"]:::orange
    end

    %% Tools and CI
    Scripts["CLI & Helper Scripts"]:::green
    Tests["Testing Suite"]:::purple
    CI["CI/CD Pipeline"]:::purple

    %% External Services
    Codecov["Codecov"]:::purple
    GitPOAP["GitPOAP"]:::purple
    PyPI["PyPI"]:::purple

    %% Relationships
    Developer --> CoreSpec
    Developer --> NetDocs
    Developer --> Lists
    Developer --> Scripts
    Developer --> CI

    CoreSpec --> Tests
    CoreSpec --> Scripts
    CoreSpec --> DocsGen

    NetDocs --> DocsGen
    Lists --> DocsGen
    SigLists --> DocsGen

    Scripts --> Tests
    Scripts --> DocsGen

    DocsGen --> Site
    Static --> Site

    CI --> Tests
    CI --> Site
    CI --> Codecov
    CI --> GitPOAP
    CI --> PyPI

    %% Click Events
    click ForkModules "https://github.com/ethereum/execution-specs/tree/master/src/ethereum/frontier"
    click Interpreter "https://github.com/ethereum/execution-specs/blob/master/src/ethereum/frontier/vm/interpreter.py"
    click Instructions "https://github.com/ethereum/execution-specs/tree/master/src/ethereum/frontier/vm/instructions/"
    click Precompiles "https://github.com/ethereum/execution-specs/tree/master/src/ethereum/frontier/vm/precompiled_contracts/"
    click Crypto "https://github.com/ethereum/execution-specs/tree/master/src/ethereum/crypto/"
    click Utils "https://github.com/ethereum/execution-specs/tree/master/src/ethereum/utils/"
    click Assets "https://github.com/ethereum/execution-specs/tree/master/src/ethereum/assets/"
    click Optimized "https://github.com/ethereum/execution-specs/tree/master/src/ethereum_optimized/"
    click SpecTools "https://github.com/ethereum/execution-specs/blob/master/src/ethereum_spec_tools/docc.py"
    click NetDocs "https://github.com/ethereum/execution-specs/tree/master/network-upgrades/mainnet-upgrades/"
    click Lists "https://github.com/ethereum/execution-specs/tree/master/lists/evm/"
    click SigLists "https://github.com/ethereum/execution-specs/tree/master/lists/signature-types/"
    click Scripts "https://github.com/ethereum/execution-specs/tree/master/scripts/"
    click Static "https://github.com/ethereum/execution-specs/blob/master/static/custom.css"
    click Tests "https://github.com/ethereum/execution-specs/tree/master/tests/"
    click CI "https://github.com/ethereum/execution-specs/blob/master/ .github/workflows/test.yaml"
    click Codecov "https://github.com/ethereum/execution-specs/blob/master/ .github/workflows/test.yaml"
    click GitPOAP "https://github.com/ethereum/execution-specs/blob/master/ .github/workflows/gh-pages.yaml"
    click PyPI "https://github.com/ethereum/execution-specs/blob/master/ .github/workflows/gh-pages.yaml"

    %% Styles
    classDef blue fill:#D0E8FF,stroke:#005B99,stroke-width:2px;
    classDef green fill:#DFFFE0,stroke:#2E8B57,stroke-width:2px;
    classDef orange fill:#FFE9B3,stroke:#CC8400,stroke-width:2px;
    classDef purple fill:#E8D0FF,stroke:#800080,stroke-width:2px;
    classDef actor fill:#FFFFFF,stroke:#000000,stroke-width:2px,stroke-dasharray: 5 5;
```
