Skip to content

Cleanup readme #4272

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Apr 14, 2025
Merged

Cleanup readme #4272

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
b524adb
Do a major clean up of the readme
jtraglia Apr 14, 2025
5575f90
Add readme to automatically linted files
jtraglia Apr 14, 2025
f69038a
Remove "external" from a resources header
jtraglia Apr 14, 2025
2da8552
Fix some nits
jtraglia Apr 14, 2025
daebe50
Fix more nits
jtraglia Apr 14, 2025
2892bc8
Do "make help" instead of "make"
jtraglia Apr 14, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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) \
Expand Down
117 changes: 61 additions & 56 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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:

Expand All @@ -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)