Skip to content

Commit 3434cc6

Browse files
authored
Revamp the README (#5581)
I felt that the README could use some general improvements. I have reorganized the sections, simplified sentences, updated links, etc.
1 parent 939afbc commit 3434cc6

1 file changed

Lines changed: 30 additions & 68 deletions

File tree

README.md

Lines changed: 30 additions & 68 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,18 @@
1-
# Ethereum Proof-of-Stake Consensus Specifications
1+
# Ethereum Consensus Specifications
22

33
[![tests](https://github.com/ethereum/consensus-specs/actions/workflows/tests.yml/badge.svg?branch=master&event=schedule)](https://github.com/ethereum/consensus-specs/actions/workflows/tests.yml)
44
[![image](https://img.shields.io/pypi/v/eth-consensus-specs.svg)](https://pypi.python.org/pypi/eth-consensus-specs)
55
[![image](https://img.shields.io/pypi/l/eth-consensus-specs.svg)](https://pypi.python.org/pypi/eth-consensus-specs)
66
[![Discord](https://img.shields.io/badge/Discord-%235865F2.svg?logo=discord&logoColor=white)](https://discord.gg/qGpsxSA)
77

8-
This repository hosts the current Ethereum
8+
This repository hosts the Ethereum
99
[proof-of-stake](https://ethereum.org/en/developers/docs/consensus-mechanisms/pos/)
10-
specifications. Discussions about design rationale and proposed changes can be
11-
brought up and discussed as issues. Solidified, agreed-upon changes to the
12-
specifications can be made through pull requests.
13-
14-
## Specifications
15-
16-
Core specifications for Ethereum proof-of-stake clients can be found in
17-
[specs](specs). These are divided into [features](specs/_features). Features are
18-
researched and developed in parallel, and then consolidated into sequential
19-
upgrades when ready.
10+
specifications for consensus-layer clients. Design rationale and proposed
11+
changes are discussed in issues. Agreed-upon changes are made through pull
12+
requests. Specifications can be found in [specs](specs), arranged by upgrade.
13+
Each upgrade builds on the previous, specifying only what it changes. Individual
14+
[features](specs/_features) are developed in parallel and are folded into an
15+
upgrade when ready.
2016

2117
### Stable specifications
2218

@@ -37,72 +33,38 @@ upgrades when ready.
3733
| 7 | **Gloas** | TBD | [Spec](specs/gloas) |
3834
| 8 | **Heze** | TBD | [Spec](specs/heze) |
3935

40-
### External specifications
36+
### Rendered viewers
4137

42-
- [Deposit Contract](https://github.com/ethereum/solidity-deposit-contract)
43-
- [Beacon APIs](https://github.com/ethereum/beacon-apis)
44-
- [Engine APIs](https://github.com/ethereum/execution-apis/tree/main/src/engine)
45-
- [Beacon Metrics](https://github.com/ethereum/beacon-metrics)
46-
- [Builder Specs](https://github.com/ethereum/builder-specs)
47-
- [Cryptography Specs](https://github.com/ethereum/cryptography-specs)
48-
- [SimpleSerialize (SSZ) Specs](https://github.com/ethereum/ssz-specs)
38+
- https://ethereum.github.io/spec-viewer/
39+
- https://ethereum.github.io/consensus-specs/
4940

5041
### Reference tests
5142

52-
- Stable reference tests are available as
53-
[release assets](https://github.com/ethereum/consensus-specs/releases).
54-
- Unstable reference tests are available as
55-
[nightly builds](https://github.com/ethereum/consensus-specs/actions/workflows/tests.yml).
56-
57-
## Contributors
58-
59-
### Prerequisites
60-
61-
Install [`uv`](https://docs.astral.sh/uv/) with:
62-
63-
```
64-
curl -LsSf https://astral.sh/uv/install.sh | sh
65-
```
66-
67-
### Installation and usage
68-
69-
Clone the repository with:
70-
71-
```
72-
git clone git@github.com:ethereum/consensus-specs.git
73-
```
74-
75-
Switch to the directory:
76-
77-
```
78-
cd consensus-specs
79-
```
80-
81-
View the help output:
82-
83-
```
84-
make help
85-
```
43+
- [Release assets](https://github.com/ethereum/consensus-specs/releases)
44+
- [Nightly artifacts](https://github.com/ethereum/consensus-specs/actions/workflows/tests.yml)
8645

8746
### Design goals
8847

89-
The following are the broad design goals for the Ethereum proof-of-stake
90-
consensus specifications:
91-
9248
- Minimize complexity, even at the cost of some losses in efficiency.
93-
- Remain live through major network partitions and when very large portions of
94-
nodes go offline.
95-
- Select components that are quantum secure or easily swappable for
96-
quantum-secure alternatives.
97-
- Utilize crypto and design techniques that allow for a large participation of
98-
validators.
49+
- Remain live through major network partitions and mass node outages.
50+
- Select components that are quantum-secure or easy to swap out.
51+
- Use crypto and design techniques that support a large validator set.
9952
- Minimize hardware requirements such that a consumer laptop can participate.
10053

54+
### External specifications
55+
56+
- [Beacon APIs](https://github.com/ethereum/beacon-apis)
57+
- [Beacon Metrics](https://github.com/ethereum/beacon-metrics)
58+
- [Builder Specs](https://github.com/ethereum/builder-specs)
59+
- [Cryptography Specs](https://github.com/ethereum/cryptography-specs)
60+
- [Deposit Contract](https://github.com/ethereum/solidity-deposit-contract)
61+
- [Engine APIs](https://github.com/ethereum/execution-apis/tree/main/src/engine)
62+
- [SimpleSerialize Specs](https://github.com/ethereum/ssz-specs)
63+
10164
### Useful resources
10265

10366
- [Design Rationale](https://notes.ethereum.org/s/rkhCgQteN#)
104-
- [Phase0 Onboarding Document](https://notes.ethereum.org/s/Bkn3zpwxB)
105-
- [Combining GHOST and Casper paper](https://arxiv.org/abs/2003.03052)
106-
- [Specifications viewer (zensical)](https://ethereum.github.io/consensus-specs/)
107-
- [Specifications viewer (jtraglia)](https://jtraglia.github.io/eth-spec-viewer/)
108-
- [The Eth2 Book](https://eth2book.info)
67+
- [Phase0 for Humans](https://notes.ethereum.org/s/Bkn3zpwxB)
68+
- [Combining GHOST and Casper](https://arxiv.org/abs/2003.03052)
69+
- [Vitalik's annotated spec](https://github.com/ethereum/annotated-spec)
70+
- [Upgrading Ethereum](https://eth2book.info)

0 commit comments

Comments
 (0)