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
Arrow Galcier (Planned)	13773000	TBD	EIP-4345	Specification	TBD
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

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.7+

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.7.x (not 3.8 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.

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.