Ethereum Proof-of-Stake Consensus Specifications
To learn more about proof-of-stake and sharding, see the PoS documentation, sharding documentation and the research compendium.
This repository hosts the current Ethereum proof-of-stake specifications. Discussions about design rationale and proposed changes can be brought up and discussed as issues. Solidified, agreed-upon changes to the spec can be made through pull requests.
Specs
Core specifications for Ethereum proof-of-stake clients can be found in specs. These are divided into features.
Features are researched and developed in parallel, and then consolidated into sequential upgrades when ready.
Stable Specifications
| Seq. |
Code Name |
Fork Epoch |
Specs |
| 0 |
Phase0 |
0 |
- Core
- The beacon chain
- Deposit contract
- Beacon chain fork choice
- Additions
- Honest validator guide
- P2P networking
- Weak subjectivity
|
| 1 |
Altair |
74240 |
- Core
- Beacon chain changes
- Altair fork
- Additions
- Light client sync protocol (full node, light client, networking)
- Honest validator guide changes
- P2P networking
|
| 2 |
Bellatrix
("The Merge") |
144896 |
- Core
- Beacon Chain changes
- Bellatrix fork
- Fork choice changes
- Additions
- Honest validator guide changes
- P2P networking
|
| 3 |
Capella |
194048 |
- Core
- Beacon chain changes
- Capella fork
- Additions
- Light client sync protocol changes (fork, full node, networking)
- Validator additions
- P2P networking
|
| 4 |
Deneb |
269568 |
- Core
- Beacon Chain changes
- Deneb fork
- Polynomial commitments
- Fork choice changes
- Additions
- Light client sync protocol changes (fork, full node, networking)
- Honest validator guide changes
- P2P networking
|
In-development Specifications
| Seq. |
Code Name |
Fork Epoch |
Specs |
| 5 |
Electra |
TBD |
- Core
- Beacon Chain changes
- Electra fork
- Additions
- Light client sync protocol changes (fork, networking)
- Honest validator guide changes
- P2P networking
|
Outdated Specifications
| Code Name or Topic |
Specs |
Notes |
| Sharding |
|
|
| Custody Game |
- Core
- Additions
- Honest validator guide changes
|
Dependent on sharding |
| Data Availability Sampling |
- Core
- Core types and functions
- Fork choice changes
- Additions
- P2P Networking
- Sampling process
|
- Dependent on sharding
- Technical explainer
|
Accompanying documents can be found in specs and include:
- SimpleSerialize (SSZ) spec
- Merkle proof formats
- General test format
Additional specifications for client implementers
Additional specifications and standards outside of requisite client functionality can be found in the following repos:
- Beacon APIs
- Engine APIs
- Beacon Metrics
Design goals
The following are the broad design goals for the Ethereum proof-of-stake consensus specifications:
- to minimize complexity, even at the cost of some losses in efficiency
- to remain live through major network partitions and when very large portions of nodes go offline
- to select all components such that they are either quantum secure or can be easily swapped out for quantum secure counterparts when available
- to utilize crypto and design techniques that allow for a large participation of validators in total and per unit time
- to allow for a typical consumer laptop with
O(C) resources to process/validate O(1) shards (including any system level validation such as the beacon chain)
Useful external resources
- Design Rationale
- Phase 0 Onboarding Document
- Combining GHOST and Casper paper
For spec contributors
Documentation on the different components used during spec writing can be found here:
- YAML Test Generators
- Executable Python Spec, with Py-tests
Online viewer of the latest release (latest master branch)
Ethereum Consensus Specs
Consensus spec tests
Conformance tests built from the executable python spec are available in the Ethereum Proof-of-Stake Consensus Spec Tests repo. Compressed tarballs are available in releases.
Installation and Usage
The consensus-specs repo can be used by running the tests locally or inside a docker container.
To run the tests locally:
- Clone the repository with
git clone https://github.com/ethereum/consensus-specs.git
- Switch to the directory
cd consensus-specs
- Install the dependencies with:
make install_test && make preinstallation && make pyspec
- Run the tests with
make citest
To run the tests inside a docker container:
- Switch to the directory with
cd scripts
- Run the script
./build_run_docker_tests.sh
- Find the results in a folder called
./testResults
- Find more ways to customize the script with
./build_run_docker_tests.sh --h
