2021-08-18 14:45:23 +00:00
# Ethereum Proof-of-Stake Consensus Specifications
2018-09-24 01:52:52 +00:00
2023-04-04 14:04:48 +00:00
[](https://discord.gg/qGpsxSA)
2018-12-15 14:28:13 +00:00
2022-11-02 19:26:59 +00:00
To learn more about proof-of-stake and sharding, see the [PoS documentation ](https://ethereum.org/en/developers/docs/consensus-mechanisms/pos/ ), [sharding documentation ](https://ethereum.org/en/upgrades/sharding/ ) and the [research compendium ](https://notes.ethereum.org/s/H1PGqDhpm ).
2018-11-06 08:02:55 +00:00
2021-08-18 14:45:23 +00:00
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.
2018-11-15 22:52:06 +00:00
2019-03-27 16:36:15 +00:00
## Specs
2018-11-15 22:52:06 +00:00
2020-05-06 10:03:48 +00:00
[](https://github.com/ethereum/eth2.0-specs/releases/) [](https://badge.fury.io/py/eth2spec)
2021-08-18 14:45:23 +00:00
Core specifications for Ethereum proof-of-stake clients can be found in [specs ](specs/ ). These are divided into features.
2021-03-27 00:10:13 +00:00
Features are researched and developed in parallel, and then consolidated into sequential upgrades when ready.
2020-05-06 10:03:48 +00:00
2022-05-31 18:33:12 +00:00
### Stable Specifications
2022-06-06 08:03:46 +00:00
| Seq. | Code Name | Fork Epoch | Specs |
2022-06-02 14:14:39 +00:00
| - | - | - | - |
2022-06-06 08:03:46 +00:00
| 0 | **Phase0** |`0` | < ul >< li > Core</ li >< ul >< li > [The beacon chain](specs/phase0/beacon-chain.md)</ li >< li > [Deposit contract](specs/phase0/deposit-contract.md)</ li >< li > [Beacon chain fork choice](specs/phase0/fork-choice.md)</ li ></ ul >< li > Additions</ li >< ul >< li > [Honest validator guide](specs/phase0/validator.md)</ li >< li > [P2P networking](specs/phase0/p2p-interface.md)</ li >< li > [Weak subjectivity](specs/phase0/weak-subjectivity.md)</ li ></ ul ></ ul > |
2022-05-03 13:30:45 +00:00
| 1 | **Altair** | `74240` | < ul >< li > Core</ li >< ul >< li > [Beacon chain changes](specs/altair/beacon-chain.md)</ li >< li > [Altair fork](specs/altair/fork.md)</ li ></ ul >< li > Additions</ li >< ul >< li > [Light client sync protocol](specs/altair/light-client/sync-protocol.md) ([full node](specs/altair/light-client/full-node.md), [light client ](specs/altair/light-client/light-client.md ), [networking ](specs/altair/light-client/p2p-interface.md ))</ li >< li > [Honest validator guide changes](specs/altair/validator.md)</ li >< li > [P2P networking](specs/altair/p2p-interface.md)</ li ></ ul ></ ul > |
2022-08-17 14:46:47 +00:00
| 2 | **Bellatrix** < br /> (["The Merge"](https://ethereum.org/en/upgrades/merge/)) | `144896` | < ul >< li > Core</ li >< ul >< li > [Beacon Chain changes](specs/bellatrix/beacon-chain.md)</ li >< li > [Bellatrix fork](specs/bellatrix/fork.md)</ li >< li > [Fork choice changes](specs/bellatrix/fork-choice.md)</ li ></ ul >< li > Additions</ li >< ul >< li > [Honest validator guide changes](specs/bellatrix/validator.md)</ li >< li > [P2P networking](specs/bellatrix/p2p-interface.md)</ li ></ ul ></ ul > |
2023-03-20 05:48:49 +00:00
| 3 | **Capella** | `194048` | < ul >< li > Core</ li >< ul >< li > [Beacon chain changes](specs/capella/beacon-chain.md)</ li >< li > [Capella fork](specs/capella/fork.md)</ li ></ ul >< li > Additions</ li >< ul >< li > [Light client sync protocol changes](specs/capella/light-client/sync-protocol.md) ([fork](specs/capella/light-client/fork.md), [full node ](specs/capella/light-client/full-node.md ), [networking ](specs/capella/light-client/p2p-interface.md ))</ li ></ ul >< ul >< li > [Validator additions](specs/capella/validator.md)</ li >< li > [P2P networking](specs/capella/p2p-interface.md)</ li ></ ul ></ ul > |
2024-02-08 14:34:59 +00:00
| 4 | **Deneb** | `269568` | < ul >< li > Core</ li >< ul >< li > [Beacon Chain changes](specs/deneb/beacon-chain.md)</ li >< li > [Deneb fork](specs/deneb/fork.md)</ li >< li > [Polynomial commitments](specs/deneb/polynomial-commitments.md)</ li >< li > [Fork choice changes](specs/deneb/fork-choice.md)</ li ></ ul >< li > Additions</ li >< ul >< li > [Light client sync protocol changes](specs/deneb/light-client/sync-protocol.md) ([fork](specs/deneb/light-client/fork.md), [full node ](specs/deneb/light-client/full-node.md ), [networking ](specs/deneb/light-client/p2p-interface.md ))</ li ></ ul >< ul >< li > [Honest validator guide changes](specs/deneb/validator.md)</ li >< li > [P2P networking](specs/deneb/p2p-interface.md)</ li ></ ul ></ ul > |
2022-05-31 18:33:12 +00:00
### In-development Specifications
2022-07-15 11:15:22 +00:00
| Code Name or Topic | Specs | Notes |
2022-05-31 18:33:12 +00:00
| - | - | - |
2024-06-21 08:59:13 +00:00
| Electra | < ul >< li > Core</ li >< ul >< li > [Beacon Chain changes](specs/electra/beacon-chain.md)</ li >< li > [EIP-6110 fork](specs/electra/fork.md)</ li ></ ul >< li > Additions</ li >< ul >< li > [Light client sync protocol changes](specs/electra/light-client/sync-protocol.md) ([fork](specs/electra/light-client/fork.md), [full node ](specs/electra/light-client/full-node.md ), [networking ](specs/electra/light-client/p2p-interface.md ))</ li ></ ul >< ul >< li > [Honest validator guide changes](specs/electra/validator.md)</ li ></ ul ></ ul > |
2023-02-14 15:50:00 +00:00
| Sharding (outdated) | < ul > < li > Core< / li > < ul > < li > [Beacon Chain changes](specs/_features/sharding/beacon-chain.md)< / li > < / ul > < li > Additions< / li > < ul > < li > [P2P networking](specs/_features/sharding/p2p-interface.md)< / li > < / ul > < / ul > |
| Custody Game (outdated) | < ul > < li > Core< / li > < ul > < li > [Beacon Chain changes](specs/_features/custody_game/beacon-chain.md)< / li > < / ul > < li > Additions< / li > < ul > < li > [Honest validator guide changes](specs/_features/custody_game/validator.md)< / li > < / ul > < / ul > | Dependent on sharding |
| Data Availability Sampling (outdated) | < ul > < li > Core< / li > < ul > < li > [Core types and functions](specs/_features/das/das-core.md)< / li > < li > [Fork choice changes](specs/_features/das/fork-choice.md)< / li > < / ul > < li > Additions< / li > < ul > < li > [P2P Networking](specs/_features/das/p2p-interface.md)< / li > < li > [Sampling process](specs/_features/das/sampling.md)< / li > < / ul > < / ul > | < ul > < li > Dependent on sharding< / li > < li > [Technical explainer](https://hackmd.io/@HWeNw8hNRimMm2m2GH56Cw/B1YJPGkpD)< / li > < / ul > |
2019-07-11 17:22:08 +00:00
2019-04-24 19:43:07 +00:00
### Accompanying documents can be found in [specs](specs) and include:
2020-01-10 18:42:55 +00:00
* [SimpleSerialize (SSZ) spec ](ssz/simple-serialize.md )
* [Merkle proof formats ](ssz/merkle-proofs.md )
* [General test format ](tests/formats/README.md )
2019-03-27 16:36:15 +00:00
2019-08-16 19:35:23 +00:00
## Additional specifications for client implementers
2019-08-19 17:06:37 +00:00
Additional specifications and standards outside of requisite client functionality can be found in the following repos:
2019-08-16 19:35:23 +00:00
2021-08-18 14:45:23 +00:00
* [Beacon APIs ](https://github.com/ethereum/beacon-apis )
2023-06-06 10:24:36 +00:00
* [Engine APIs ](https://github.com/ethereum/execution-apis/tree/main/src/engine )
2021-08-18 14:45:23 +00:00
* [Beacon Metrics ](https://github.com/ethereum/beacon-metrics/ )
2019-08-16 19:35:23 +00:00
2019-05-06 15:30:32 +00:00
## Design goals
2019-03-27 16:36:15 +00:00
2021-08-18 14:45:23 +00:00
The following are the broad design goals for the Ethereum proof-of-stake consensus specifications:
2018-11-15 22:52:06 +00:00
* to minimize complexity, even at the cost of some losses in efficiency
2018-11-26 22:57:01 +00:00
* to remain live through major network partitions and when very large portions of nodes go offline
2018-11-15 22:52:06 +00:00
* 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)
2019-03-27 16:36:15 +00:00
2019-08-16 17:01:48 +00:00
## Useful external resources
* [Design Rationale ](https://notes.ethereum.org/s/rkhCgQteN# )
* [Phase 0 Onboarding Document ](https://notes.ethereum.org/s/Bkn3zpwxB )
2020-03-11 20:52:31 +00:00
* [Combining GHOST and Casper paper ](https://arxiv.org/abs/2003.03052 )
2019-08-16 17:01:48 +00:00
2019-03-27 16:36:15 +00:00
## For spec contributors
Documentation on the different components used during spec writing can be found here:
2020-01-10 18:42:55 +00:00
* [YAML Test Generators ](tests/generators/README.md )
* [Executable Python Spec, with Py-tests ](tests/core/pyspec/README.md )
2021-08-18 14:45:23 +00:00
2023-04-18 10:31:34 +00:00
## Online viewer of the latest release (latest `master` branch)
[Ethereum Consensus Specs ](https://ethereum.github.io/consensus-specs/ )
2021-08-18 14:45:23 +00:00
## Consensus spec tests
Conformance tests built from the executable python spec are available in the [Ethereum Proof-of-Stake Consensus Spec Tests ](https://github.com/ethereum/consensus-spec-tests ) repo. Compressed tarballs are available in [releases ](https://github.com/ethereum/consensus-spec-tests/releases ).
2024-08-13 10:56:03 +00:00
## 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`
