Eth1.0 Specifications

Description

This repository contains various specification related to the Ethereum 1.0 chain, specifically the pyspec, specifications for network upgrades, and the (deprecated) JSON-RPC API.

Ethereum Protocol Releases

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.

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

eth1.0-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/eth1.0-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                            # Runs tests.

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.