Skip to content

Specs [EL]

Specs [EL] maintains the specification of Ethereum's execution layer and the tests that check clients against it. Both live in ethereum/execution-specs:

  • The specs (EELS): the Ethereum Execution Layer Specification, written in executable Python. It is both documentation and a reference implementation of the EVM and the state transition.
  • The tests: a Python test framework and the test cases written with it. The tests run against the specs to produce test vectors (fixtures), which execution layer clients run to check their implementations.

Until 2025 the tests lived in their own repository, ethereum/execution-spec-tests (EEST). The Weld moved them into execution-specs so that a spec change and its tests land in the same pull request.

What we maintain

Specifications

  • Maintain the execution layer specification as readable, executable Python.
  • Help EIP authors prototype their proposals in the specs. An EIP needs a reference implementation in the specs before it can be considered for inclusion in a fork.
  • Publish a diff between forks for every upgrade (for example, MODEXP changes in Osaka).
  • Publish the specs as the ethereum-execution package on PyPI.

Tests

  • Write test cases for every EIP in the next fork, and for the effort to scale the L1.
  • Generate and release the consensus test fixtures that every execution layer client runs in CI.
  • Write benchmark tests: computation- and state-heavy worst cases that help client teams prepare for higher gas limits.
  • Write zkEVM and stateless witness tests for the zkEVM effort.
  • Help client teams debug failing tests, and feed what we learn back into the specs and tests.

Running tests against clients

  • Consume: a family of Hive simulators that run fixtures against clients through the Engine API, RLP-encoded blocks at startup, or sync.
  • Execute: runs tests as transactions on live networks and devnets, or in Hive.

The docs compare all the ways to run tests.

Libraries and tools

  • ethereum/ethereum-types: types used by the specs.
  • ethereum/ethereum-rlp: Recursive Length Prefix (RLP) serialisation, as used by the specs.
  • docc, and its Rust port rdocc: the documentation generator that renders the specs.
  • gentest: generates a Python test case from a mainnet or devnet transaction hash.

How the work is organised

execution-specs uses a branch per fork:

  • mainnet: the specs of every fork that is live on mainnet.
  • forks/<fork>: the fork under active development. It is merged into mainnet once the fork goes live.
  • eips/<fork>/eip-<n>: one branch per EIP. It is merged into the fork branch once the EIP is confirmed for that fork.
  • devnets/<feature>/<n>: the combination of EIPs that a devnet runs.

The documentation is built for mainnet and for the fork in development.

How we release

Test fixtures are released with a release workflow. A maintainer starts it for a feature and version. The workflow builds the fixtures and drafts a pre-release, and a maintainer reviews it and publishes it. Publishing also builds the Hive simulator images for that release. Each release has a tracking issue, and a nightly run rehearses the release.

Release What it contains
tests@vX.Y.Z The fixtures every client should pass: all forks up to the one clients have on their main branch. Released when there are changes, often once or twice a week.
tests-<feature>-devnet@vX.Y.Z Fixtures for an active devnet, for example Glamsterdam, FOCIL or Bogota devnets. Advisory, not required to pass.
tests-benchmark@vX.Y.Z Benchmark fixtures at a range of gas limits.
tests-zkevm@vX.Y.Z zkEVM and stateless witness fixtures.
vX.Y.Z The ethereum-execution specs package on PyPI.

In tests@vX.Y.Z, X is the fork number, Y changes on a consensus-breaking change and Z on new tests or other changes. Clients can download the latest release with uv run consume cache --input=tests@latest. See Releases for details.

Current focus

  • Glamsterdam: finishing specs and tests for the Amsterdam execution layer upgrade as it moves from testnets to mainnet.
  • Hegotá: specifying and testing the EIPs proposed for the Bogota execution layer upgrade, and the devnets that try them out, including FOCIL together with Specs [CL].
  • Scaling the L1: benchmark and worst-case tests that help clients raise the gas limit safely, and test vectors for zkEVMs.
  • One test corpus: bringing the remaining tests from ethereum/tests into the new framework, so that clients have one source of consensus tests and retesteth can retire.

Resources