Ethereum Execution Layer Specifications

The Ethereum Execution Layer Specifications (EELS) are an executable Python reference implementation of Ethereum's execution layer, along with the test cases that verify it. It provides a shared, runnable description of consensus-critical behaviour, and the accompanying tests generate fixtures that can be used to validate execution client implementations.

Quick Start

execution-specs uses uv to manage the Python environment and dependencies, and just as a task runner for common commands (linting, building docs, generating fixtures). The commands below install both and set up the repo from scratch.

Requires a Unix-like shell. All platforms:

git clone https://github.com/ethereum/execution-specs
cd execution-specs
curl -LsSf https://astral.sh/uv/install.sh | sh
uv python install 3.12
uv python pin 3.12
uv sync
uv tool install --exclude-newer "10 days" rust-just
just shell-completions

Python 3.11–3.14 are supported; 3.12 tends to be the smoothest for local setup (pre-built wheels are available across the dependency set). For alternative just installation paths, macOS-specific installation notes, and troubleshooting, see Installation.

Reference EVM CLI

ethereum-spec-evm — a t8n transition tool, b11r block builder, and state-test runner that execute the spec directly — is provided by the ethereum-execution-testing workspace package rather than by ethereum-execution. Within a checkout it is available as uv run ethereum-spec-evm; for standalone installation (e.g. in client CI or fuzzing setups), see packages/testing/README.md.

Documentation

• Repo documentation (default branch/fork): https://steel.ethereum.foundation/docs/execution-specs/
• Protocol history: docs/specs/protocol_history.md
• Versioning scheme: docs/specs/spec_releases.md (PEP 440 compatible; hardfork encoded in the minor version, rcN marks devnets).

Contributing

Earnest contributions are welcome; drive-by contributions are not. See CONTRIBUTING.md for how to raise issues and pull requests. Further reading:

• Code Standards: Python coding preferences enforced in CI.
• Verifying Changes: Which local checks to run before opening a PR.
• Writing Specs: Style rules and ethereum_spec_tools utilities for changes under src/ethereum/.
• Writing Tests: For guidance on adding consensus tests under ./tests/.

This repository is maintained by the STEEL Team at the Ethereum Foundation.

Community and Support

Discussion around the initial specification of protocol changes happens on Ethereum Magicians, in pull requests on ethereum/EIPs, on the Ethereum R&D Discord (one of the channels in the Execution R&D category; for testing use #el-testing), and in the AllCoreDevs calls.

For tracking the status of upcoming Ethereum upgrades, see Forkcast: EIP inclusion, client implementation progress, and ACD call summaries.

For other help, see the Documentation section above, or reach out to one of the STEEL team members in the Ethereum R&D Discord.

Related projects

• ethereum/EIPs: The prose EIP documents that EELS implements.
• ethereum/execution-apis: The JSON-RPC API specification, which lives in a separate repository.
• ethereum/consensus-specs: The consensus-layer counterpart to this repository.

Production execution clients that implement the spec include besu, erigon, ethrex, geth, nethermind, and reth.

Responsible Disclosure of Vulnerabilities

[!CAUTION] Care is required when filing issues or PRs for functionality that is live on Ethereum mainnet. Please report vulnerabilities and verify bounty eligibility via the bug bounty program; see SECURITY.md for details.

• Please do not create a PR with a vulnerability visible.
• Please do not file a public ticket mentioning the vulnerability.

License

The Ethereum Execution Layer Specification is licensed under the Creative Commons Zero v1.0 Universal.