IMPORTANT: Read this first if you're planning to use it for Monad.
This fork implements the execution layer client features specific to Monad.
It mainly serves as an alternative implementation of https://github.com/category-labs/monad, and a tool to generate (fill) spec tests for it to consume.
- Install
uv:curl -LsSf https://astral.sh/uv/install.sh | sh - Clone and setup:
git clone --depth 1 https://github.com/monad-developers/execution-specs
cd execution-specs
uv python install 3.12
uv python pin 3.12
uv sync --all-extras- Fill all monadized spec tests as of writing this (see below for explanation of flags):
uv run fill --clean -m "blockchain_test or transaction_test" --from MONAD_EIGHT --until MONAD_NINE --chain-id 143 -n auto tests- The test fixtures to be found in
fixtures/directory under repo root.
(c.f. somewhat outdated upstream "Getting started")
Filling tests is the process of running Python generators of spec tests like ones you can find here, to generate JSON files with test fixtures. The fixtures are then in turn consumed by monad. In the process of filling the tests, the Python implementation of Monad execution layer is used to produce reference results including the state root.
-m blockchain_test or transaction_test: causes these two flavors of fixtures to be generatedblockchain_testis the currently supported bymonadflavor of a spec test checking correctness of the state transition. Note this includesblockchain_test_from_state_test, meaning that allstate_test(...)fillers are includedtransaction_testis also supported, tests only correctness of static transaction checks
--from MONAD_EIGHT --until MONAD_NINE: hardforks for which to generate fixtures. Must match with those defined inmonad, inclusive--chain-id 143: must be specified for signatures and EIP-7702 to work correctly-n auto: frompytest, parallel execution of teststests: root directory to traverse to discover tests- inside the tests are organized by EIP/MIP and the hardfork when they became relevant. For Monad these are
monad_eightandmonad_nineas of writing this. Here hardfork is informative only, doesn't need to match withmonad. - note that tests relevant for previous hardforks, e.g.
tests/prague/eip7702_set_code_tx, are filled for hardforks requested with--from,--untilflags, respecting any constraints the test itself might define. In other words, in the invocation above, EIP-7702 tests will be filled
- inside the tests are organized by EIP/MIP and the hardfork when they became relevant. For Monad these are
pytest flags are in general supported, while --traces will give you detailed EVM step traces. Refer to https://eest.ethereum.org/main/filling_tests/ for more details.
- not all Ethereum-only features have been switched off, e.g. eth-specific system contracts and tx types are available in the monadized
execution-specsimplementation. We're skipping their respective spec tests, and we don't have tests testing lack of these features in Monad. - we're going to be keeping up with upstream changes (currently
forks/amsterdambranch). This should work by opening a PR with the upstream changes to be commit-merged into our default branch (currentlyforks/monad_nine). - when adding a new Monad-hardfork we should use the
ethereum-spec-new-forktool provided to clone the parent hardfork into the new hardfork. If that new Monad-hardfork also adopts upstream (Ethereum) hardfork improvements, you will need to apply these yourself.
This repository contains the specifications related to the Ethereum execution client, specifically the pyspec and specifications for network upgrades. The JSON-RPC API specification can be found in a separate repository.
Note: Starting with Paris, updates are no longer rolled out based on block numbers. Paris was enabled once proof-of-work Total Difficulty reached 58750000000000000000000. As of Shanghai (at 1681338455), upgrade activation is based on timestamps.
Some clarifications were enabled without protocol releases:
| EIP | Block No. |
|---|---|
| EIP-2681 | 0 |
| EIP-3607 | 0 |
| EIP-7523 | 15537394 |
| EIP-7610 | 0 |
The execution specification is a python implementation of Ethereum that prioritizes readability and simplicity. It will be accompanied by both narrative and API level documentation of the various components written in markdown and rendered using docc...
The Ethereum specification is maintained as a Python library, for better integration with tooling and testing.
Requires Python 3.11+
Building the spec documentation is most easily done through tox:
uvx --with=tox-uv tox -e spec-docsThe path to the generated HTML will be printed to the console.
To view the updated local documentation, run:
uv run mkdocs servethen connect to localhost:8000 in a browser
The Ethereum Execution Layer Specification code is licensed under the Creative Commons Zero v1.0 Universal.