How ethereum/execution-specs works
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