diff --git a/Makefile b/Makefile index 3ae7133002..a54473f1a9 100644 --- a/Makefile +++ b/Makefile @@ -180,7 +180,8 @@ PYLINT_CONFIG = $(CURDIR)/pylint.ini PYLINT_SCOPE := $(foreach S,$(ALL_EXECUTABLE_SPEC_NAMES), $(PYSPEC_DIR)/eth2spec/$S) MYPY_SCOPE := $(foreach S,$(ALL_EXECUTABLE_SPEC_NAMES), -p eth2spec.$S) -MARKDOWN_FILES = $(wildcard $(SPEC_DIR)/*/*.md) \ +MARKDOWN_FILES = $(CURDIR)/README.md \ + $(wildcard $(SPEC_DIR)/*/*.md) \ $(wildcard $(SPEC_DIR)/*/*/*.md) \ $(wildcard $(SPEC_DIR)/_features/*/*.md) \ $(wildcard $(SPEC_DIR)/_features/*/*/*.md) \ diff --git a/README.md b/README.md index 4885ff71e5..163d13b37b 100644 --- a/README.md +++ b/README.md @@ -1,79 +1,64 @@ # Ethereum Proof-of-Stake Consensus Specifications [![Join the chat at https://discord.gg/qGpsxSA](https://img.shields.io/badge/chat-on%20discord-blue.svg)](https://discord.gg/qGpsxSA) +[![testgen](https://github.com/ethereum/consensus-specs/actions/workflows/generate_vectors.yml/badge.svg?branch=dev&event=schedule)](https://github.com/ethereum/consensus-specs/actions/workflows/generate_vectors.yml) -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). - -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. +This repository hosts the current Ethereum +[proof-of-stake](https://ethereum.org/en/developers/docs/consensus-mechanisms/pos/) specifications. +Discussions about design rationale and proposed changes can be brought up and discussed as issues. +Solidified, agreed-upon changes to the specifications can be made through pull requests. ## Specifications -[![GitHub release](https://img.shields.io/github/v/release/ethereum/consensus-specs)](https://github.com/ethereum/consensus-specs/releases/) [![PyPI version](https://badge.fury.io/py/eth2spec.svg)](https://badge.fury.io/py/eth2spec) [![testgen](https://github.com/ethereum/consensus-specs/actions/workflows/generate_vectors.yml/badge.svg?branch=dev&event=schedule)](https://github.com/ethereum/consensus-specs/actions/workflows/generate_vectors.yml) - -Core specifications for Ethereum proof-of-stake clients can be found in [specs](specs). These are divided into features. -Features are researched and developed in parallel, and then consolidated into sequential upgrades when ready. +Core specifications for Ethereum proof-of-stake clients can be found in [specs](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 | Links | -| - | - | - | - | -| 0 | **Phase0** |`0` | [Specs](specs/phase0), [Tests](tests/core/pyspec/eth2spec/test/phase0) | -| 1 | **Altair** | `74240` | [Specs](specs/altair), [Tests](tests/core/pyspec/eth2spec/test/altair) | -| 2 | **Bellatrix** | `144896` | [Specs](specs/bellatrix), [Tests](tests/core/pyspec/eth2spec/test/bellatrix) | -| 3 | **Capella** | `194048` | [Specs](specs/capella), [Tests](tests/core/pyspec/eth2spec/test/capella) | -| 4 | **Deneb** | `269568` | [Specs](specs/deneb), [Tests](tests/core/pyspec/eth2spec/test/deneb) | +| Seq. | Code Name | Fork Epoch | Links | +| ---- | ------------- | ---------- | ---------------------------------------------------------------------------- | +| 0 | **Phase0** | `0` | [Specs](specs/phase0), [Tests](tests/core/pyspec/eth2spec/test/phase0) | +| 1 | **Altair** | `74240` | [Specs](specs/altair), [Tests](tests/core/pyspec/eth2spec/test/altair) | +| 2 | **Bellatrix** | `144896` | [Specs](specs/bellatrix), [Tests](tests/core/pyspec/eth2spec/test/bellatrix) | +| 3 | **Capella** | `194048` | [Specs](specs/capella), [Tests](tests/core/pyspec/eth2spec/test/capella) | +| 4 | **Deneb** | `269568` | [Specs](specs/deneb), [Tests](tests/core/pyspec/eth2spec/test/deneb) | ### In-development Specifications -| Seq. | Code Name | Fork Epoch | Links | -| - | - | - | - | -| 5 | **Electra** | TBD | [Specs](specs/electra), [Tests](tests/core/pyspec/eth2spec/test/electra) | -| 6 | **Fulu** | TBD | [Specs](specs/fulu), [Tests](tests/core/pyspec/eth2spec/test/fulu) | - -### Accompanying documents can be found in [specs](specs) and include: - -* [SimpleSerialize (SSZ) spec](ssz/simple-serialize.md) -* [Merkle proof formats](ssz/merkle-proofs.md) -* [General test format](tests/formats/README.md) - -## Additional specifications for client implementers - -Additional specifications and standards outside of requisite client functionality can be found in the following repos: - -* [Beacon APIs](https://github.com/ethereum/beacon-apis) -* [Engine APIs](https://github.com/ethereum/execution-apis/tree/main/src/engine) -* [Beacon Metrics](https://github.com/ethereum/beacon-metrics) +| Seq. | Code Name | Fork Epoch | Links | +| ---- | ----------- | ---------- | ------------------------------------------------------------------------ | +| 5 | **Electra** | TBD | [Specs](specs/electra), [Tests](tests/core/pyspec/eth2spec/test/electra) | +| 6 | **Fulu** | TBD | [Specs](specs/fulu), [Tests](tests/core/pyspec/eth2spec/test/fulu) | -## Design goals +### Accompanying documents -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 +- [SimpleSerialize (SSZ) spec](ssz/simple-serialize.md) +- [Merkle proof formats](ssz/merkle-proofs.md) +- [General test format](tests/formats/README.md) -* [Design Rationale](https://notes.ethereum.org/s/rkhCgQteN#) -* [Phase 0 Onboarding Document](https://notes.ethereum.org/s/Bkn3zpwxB) -* [Combining GHOST and Casper paper](https://arxiv.org/abs/2003.03052) +### External specifications -## For spec contributors +Additional specifications and standards outside of requisite client functionality can be found in +the following repositories: -Documentation on the different components used during spec writing can be found here: -* [YAML Test Generators](tests/generators/README.md) -* [Executable Python Spec, with Py-tests](tests/core/pyspec/README.md) +- [Beacon APIs](https://github.com/ethereum/beacon-apis) +- [Engine APIs](https://github.com/ethereum/execution-apis/tree/main/src/engine) +- [Beacon Metrics](https://github.com/ethereum/beacon-metrics) +- [Builder Specs](https://github.com/ethereum/builder-specs) -## Online viewer of the latest release (latest `master` branch) +### Reference tests -[Ethereum Consensus Specs](https://ethereum.github.io/consensus-specs/) +Reference 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) repository. Compressed +tarballs are available for each release +[here](https://github.com/ethereum/consensus-spec-tests/releases). Nightly reference tests are +available +[here](https://github.com/ethereum/consensus-specs/actions/workflows/generate_vectors.yml). -## Consensus spec tests +## Contributors -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). - -## Installation and usage +### Installation and usage Clone the repository with: @@ -87,8 +72,28 @@ Switch to the directory: cd consensus-specs ``` -Run the tests: +View the help output: ```bash -make test +make help ``` + +### Design goals + +The following are the broad design goals for the Ethereum proof-of-stake consensus specifications: + +- Minimize complexity, even at the cost of some losses in efficiency. +- Remain live through major network partitions and when very large portions of nodes go offline. +- Select components that are quantum secure or easily swappable for quantum-secure alternatives. +- Utilize crypto and design techniques that allow for a large participation of validators. +- Minimize hardware requirements such that a consumer laptop can participate. + +### Useful resources + +- [Design Rationale](https://notes.ethereum.org/s/rkhCgQteN#) +- [Phase0 Onboarding Document](https://notes.ethereum.org/s/Bkn3zpwxB) +- [Combining GHOST and Casper paper](https://arxiv.org/abs/2003.03052) +- [Online specifications viewer](https://ethereum.github.io/consensus-specs/) +- [The Eth2 Book](https://eth2book.info) +- [PySpec Tests](tests/core/pyspec/README.md) +- [Reference Tests Generators](tests/generators/README.md)