Ethereum Execution Layer Specifications

!Python Versions

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):
• 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/.

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.

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.