gezero / execution-specs

Specification for the Execution Layer. Tracking network upgrades.

Ethereum Execution Client Specifications

Description

This repository contains the consensus 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.

Ethereum Protocol Releases

Version and Code Name	Block No.	Released	Incl EIPs	Specs	Blog
Shanghai	TBD	TBD	TBD	Specification
Paris	TBD	TBD	TBD	Specification
Gray Glacier	15050000	2022-06-30	EIP-5133	Specification	Blog
Arrow Glacier	13773000	2021-12-09	EIP-4345	Specification	Blog
London	12965000	2021-08-05	EIP-1559 EIP-3198 EIP-3529 EIP-3541 EIP-3554	Specification	Blog
Berlin	12244000	2021-04-15	EIP-2565 EIP-2929 EIP-2718 EIP-2930	HFM-2070 Specification	Blog
Muir Glacier	9200000	2020-01-02	EIP-2384	HFM-2387	Blog
Istanbul	9069000	2019-12-07	EIP-152 EIP-1108 EIP-1344 EIP-1884 EIP-2028 EIP-2200	HFM-1679	Blog
Petersburg	7280000	2019-02-28	EIP-145 EIP-1014 EIP-1052 EIP-1234	HFM-1716	Blog
Constantinople	7280000	2019-02-28	EIP-145 EIP-1014 EIP-1052 EIP-1234 EIP-1283	HFM-1013	Blog
Byzantium	4370000	2017-10-16	EIP-100 EIP-140 EIP-196 EIP-197 EIP-198 EIP-211 EIP-214 EIP-649 EIP-658	HFM-609	Blog
Spurious Dragon	2675000	2016-11-22	EIP-155 EIP-160 EIP-161 EIP-170	HFM-607	Blog
Tangerine Whistle	2463000	2016-10-18	EIP-150	HFM-608	Blog
DAO Fork	1920000	2016-07-20		HFM-779	Blog
DAO Wars	aborted	aborted			Blog
Homestead	1150000	2016-03-14	EIP-2 EIP-7 EIP-8	HFM-606	Blog
Frontier Thawing	200000	2015-09-07			Blog
Frontier	1	2015-07-30			Blog

Some clarifications were enabled without protocol releases:

EIP	Block No.
EIP-2681	0
EIP-3607	0

Consensus Specification (work-in-progress)

The consensus specification is a python implementation of Ethereum that prioritizes readability and simplicity. It [will] accompanied by both narrative and API level documentation of the various components written in restructured text and rendered using Sphinx....

• Rendered specification

Usage

The Ethereum specification is maintained as a Python library, for better integration with tooling and testing.

Requires Python 3.8+

Building

Building the documentation is most easily done through tox:

$ tox -e doc

The path to the generated HTML will be printed to the console.

Live Preview

A live preview of the documentation can be viewed locally on port 8000 with the following command:

$ tox -e doc-autobuild

Development

Running the tests necessary to merge into the repository requires:

• Python 3.8.x (not 3.9 or later), and
• PyPy 7.3.x.
• geth installed and present in $PATH

These version ranges are necessary because, at the time of writing, PyPy is only compatible with Python 3.7.

execution-specs depends on a submodule that contains common tests that are run across all clients, so we need to clone the repo with the --recursive flag. Example:

$ git clone --recursive https://github.com/ethereum/execution-specs.git

Or, if you've already cloned the repository, you can fetch the submodules with:

$ git submodule update --init --recursive

The tests can be run with:

$ tox

The development tools can also be run outside of tox, and can automatically reformat the code:

$ pip install -e ".[doc,lint,test]" # Installs eth1spec, and development tools.
$ isort src                         # Organizes imports.
$ black src                         # Formats code.
$ flake8                            # Reports style/spelling/documentation errors.
$ mypy src                          # Verifies type annotations.
$ pytest -n 4                       # Runs tests parallelly.
$ pytest -m "not slow"              # Runs tests which execute quickly.

It is recommended to use a virtual environment to keep your system Python installation clean.

A trace of the EVM execution for any test case can be obtained by providing the --evm-trace argument to pytest. Note: Make sure to run the EVM trace on a small number of tests at a time. The log might otherwise get very big. Below is an example.

pytest tests/frontier/test_state_transition.py -k 'test_general_state_tests_new' --evm-trace

Contribution Guidelines

This specification aims to be:

1. Correct - Describe the intended behavior of the Ethereum blockchain, and any deviation from that is a bug.
2. Complete - Capture the entirety of consensus critical parts of Ethereum.
3. Accessible - Prioritize readability, clarity, and plain language over performance and brevity.

Spelling

Attempt to use descriptive English words (or very common abbreviations) in documentation and identifiers. If necessary, there is a custom dictionary whitelist.txt.

CLI Utilities ethereum_spec_tools

New Fork Tool

This tool can be used to creates the base code for a new fork by using the existing code from a given fork.

The command takes 4 arguments, 2 of which are optional

• from_fork: The fork name from which the code is to be duplicated. Eg. - "Tangerine Whistle"
• to_fork: The fork name of the new fork Eg - "Spurious Dragon"
• from_test (Optional): Name of the from fork within the test fixtures in case it is different from fork name. Eg. - "EIP150"
• to_test (Optional): Name of the to fork within the test fixtures in case it is different from fork name Eg - "EIP158"

As an example, if one wants to create baseline code for the Spurious Dragon fork from the Tangerine Whistle one

ethereum-spec-new-fork --from_fork="Tangerine Whistle" --to_fork="Spurious Dragon" --from_test=EIP150 --to_test=EIP158

The following will have to however, be updated manually

1. The fork number and MAINNET_FORK_BLOCK in init.py
2. Any absolute package imports from other forks eg. in trie.py
3. Package names under setup.cfg
4. Add the new fork to the monkey_patch() function in src/ethereum_optimized/init.py
5. Adjust the underline in fork/init.py