Ethereum Consensus Specifications is a formal specification repository that defines the proof-of-stake consensus protocol for Ethereum's consensus-layer clients.
The repository addresses the need for a precise, authoritative definition of how Ethereum's consensus mechanism operates. It organizes specifications by network upgrade, with each upgrade building incrementally on the previous one and specifying only the changes it introduces. Individual features are developed in parallel within a features directory and are integrated into an upgrade when ready. The specifications are maintained through a collaborative process where design rationale and proposed changes are discussed in issues, and agreed-upon modifications are implemented via pull requests.
Developers implementing consensus-layer clients, building tools that interact with the beacon chain, or contributing to Ethereum protocol development should use this repository as the canonical reference. It suits projects that need authoritative protocol definitions rather than implementations. The repository provides both stable specifications for deployed network upgrades and unstable specifications for upgrades under development. Rendered viewers and reference test suites are available to support implementation and validation work.
The project maintains active engagement with pull requests being reviewed and merged to incorporate protocol changes. Issues receive discussion and feedback on design decisions and proposed modifications. The repository includes comprehensive reference tests available both as release assets and through nightly builds, indicating ongoing validation of specification correctness. Documentation is actively maintained across multiple formats, including rendered viewers and external specification repositories covering related concerns such as beacon APIs, cryptography, and serialization standards.
