Skip to content

Commit

Permalink
Consensus Layer Wiki Page (#246)
Browse files Browse the repository at this point in the history
* CL init, Update overview of CL

* Update ordering

* Add validators section to overview

* add iamges; added Beacon chain explainer; checkpoints and finality; slots and epochs

* Added validator life cylce

* fix typo; update wordlist

* Update state of validators

* Improve flow of the page;added simpler explanations; added some links

* add introduction; minor fixes

* Minor typos ffix

* add introduction; added byzantine generals problem

* revamp overview structure

* fix dark background in svg

* complete overview of CL; added cl-architecture structure

* Added Blocktree and fork-choice rules

* fix some typos; update wordlist

* add reorgs and reversion

* Add liveness and safey comparision

* Add some more details on consensus protocol

* Add architecture and blobs

* stf; control flow

* fix a broken link; added gasper file

* Use consistent naming for PoW and PoS

* Complete cl-architecture

* Update structure of cl-networking

* fix typos; added words to wordlist

* remove whitespace

* address some nits

* Omit some redudant content

* remove redundant content; fix broken links

* Update proposer and validator set wording

Co-authored-by: Mário Havel <[email protected]>

* Address some more nits

* Add resources; omit whitespace

* fix typos

* Update wordlist

* nit: grammar

Co-authored-by: rahul <[email protected]>

* nit: space

Co-authored-by: rahul <[email protected]>

* nit: word

Co-authored-by: rahul <[email protected]>

* nit: word

Co-authored-by: rahul <[email protected]>

* clean up

Co-authored-by: rahul <[email protected]>

* nit: spell

Co-authored-by: rahul <[email protected]>

* nit: content captilization

* Update wordlist

* nit: diagram name

Co-authored-by: rahul <[email protected]>

* nit: word

Co-authored-by: rahul <[email protected]>

* nit: clean up

Co-authored-by: rahul <[email protected]>

* nit: clean up

Co-authored-by: rahul <[email protected]>

* nit: title

Co-authored-by: rahul <[email protected]>

* nit: wording

Co-authored-by: rahul <[email protected]>

* nit: title

Co-authored-by: rahul <[email protected]>

* fix flow for the transition

* Update beacon-api.md

---------

Co-authored-by: Mário Havel <[email protected]>
Co-authored-by: rahul <[email protected]>
  • Loading branch information
3 people authored Jul 30, 2024
1 parent 2d66785 commit 35318ab
Show file tree
Hide file tree
Showing 30 changed files with 2,892 additions and 60 deletions.
6 changes: 3 additions & 3 deletions docs/_sidebar.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,11 +42,11 @@
- [RLP Serialization](/wiki/EL/RLP.md)
- Consensus Layer
- [Overview](/wiki/CL/overview.md)
- [Client architecture](/wiki/CL/cl-architecture.md)
- [CL Networking](/wiki/CL/cl-networking.md)
- [CL Specs](/wiki/CL/cl-specs.md)
- [Client architecture](/wiki/CL/client-architecture.md)
- [CL Clients](/wiki/CL/cl-clients.md)
- [Beacon API](/wiki/CL/beacon-api.md)
- [CL Networking](/wiki/CL/cl-networking.md)
- [CL Clients](/wiki/CL/cl-clients.md)
- [SSZ Serialization](/wiki/CL/SSZ.md)
- [Merkleization](/wiki/CL/merkleization.md)
- Development
Expand Down
Binary file added docs/images/cl/RANDAO.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/cl/blobs.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
491 changes: 491 additions & 0 deletions docs/images/cl/blockchain.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
657 changes: 657 additions & 0 deletions docs/images/cl/blocktree.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/cl/checkpoints.jpg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/cl/cl-ideal.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/cl/cl-networking-overview.webp
Binary file not shown.
Binary file added docs/images/cl/cl-real.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/cl/cl.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/cl/client-architecture.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/cl/committees.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/cl/el.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/cl/finalization.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/cl/network.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
478 changes: 478 additions & 0 deletions docs/images/cl/reorg-0.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
518 changes: 518 additions & 0 deletions docs/images/cl/reorg-1.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/cl/slots-and-epochs.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/cl/validator-lifecycle.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/cl/validators.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
61 changes: 57 additions & 4 deletions docs/wiki/CL/beacon-api.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,60 @@
# Beacon API
# Beacon Chain Spec and APIs

> :warning: This article is a [stub](https://en.wikipedia.org/wiki/Wikipedia:Stub), help the wiki by [contributing](/contributing.md) and expanding it.
At the core of Ethereum Proof-of-Stake is a system chain called the "Beacon Chain". The beacon chain stores and manages the registry of validators. In the initial deployment phases of Proof-of-Stake, the only mechanism to become a validator is to make a one-way(withdrawable after Capella) ETH transaction to a deposit contract on the Ethereum proof-of-work chain. Activation as a validator happens when deposit receipts are processed by the Beacon Chain, the activation balance is reached, and a queuing process is completed. Exit is either voluntary or done forcibly as a penalty for misbehavior. The primary source of load on the beacon chain is "attestations". Attestations are simultaneously availability votes for a shard block (in a later upgrade) and proof-of-stake votes for a beacon block (Phase 0).

Beacon API is the endpoint provided by consensus layer clients. It's the interface for interacting with consensus for users and validators.
This section will cover some important parts of Beacon Chain Spec and APIs. Also checkout complete [Beacon Chain Spec](https://github.com/ethereum/consensus-specs/blob/dev/specs/phase0/beacon-chain.md) and [Beacon API reference](https://ethereum.github.io/beacon-APIs/#/).

Check the [Beacon API reference](https://ethereum.github.io/beacon-APIs/#/).
Beacon API is the REST endpoint provided by consensus layer clients (beacon nodes). It's the interface to read information about the consensus and used by validator clients.

## Containers

`BeaconState`

```python
class BeaconState(Container):
# Versioning
genesis_time: uint64
genesis_validators_root: Root
slot: Slot
fork: Fork
# History
latest_block_header: BeaconBlockHeader
block_roots: Vector[Root, SLOTS_PER_HISTORICAL_ROOT]
state_roots: Vector[Root, SLOTS_PER_HISTORICAL_ROOT]
historical_roots: List[Root, HISTORICAL_ROOTS_LIMIT]
# Eth1
eth1_data: Eth1Data
eth1_deposit_index: uint64
application_state_root: Bytes32
# Registry
validators: List[Validator, VALIDATOR_REGISTRY_LIMIT]
balances: List[Gwei, VALIDATOR_REGISTRY_LIMIT]
# Randomness
randao_mixes: Vector[Bytes32, EPOCHS_PER_HISTORICAL_VECTOR]
# Slashings
slashings: Vector[Gwei, EPOCHS_PER_SLASHINGS_VECTOR]
# Attestations
previous_epoch_attestations: List[PendingAttestation, MAX_ATTESTATIONS * SLOTS_PER_EPOCH]
current_epoch_attestations: List[PendingAttestation, MAX_ATTESTATIONS * SLOTS_PER_EPOCH]
# Finality
justification_bits: Bitvector[JUSTIFICATION_BITS_LENGTH] # Bit set for every recent justified epoch
previous_justified_checkpoint: Checkpoint # Previous epoch snapshot
current_justified_checkpoint: Checkpoint
finalized_checkpoint: Checkpoint
```

#### `BeaconBlockBody`

```python
class BeaconBlockBody(Container):
randao_reveal: BLSSignature
eth1_data: Eth1Data # Eth1 data vote
graffiti: Bytes32 # Arbitrary data
# Operations
proposer_slashings: List[ProposerSlashing, MAX_PROPOSER_SLASHINGS]
attester_slashings: List[AttesterSlashing, MAX_ATTESTER_SLASHINGS]
attestations: List[Attestation, MAX_ATTESTATIONS]
deposits: List[Deposit, MAX_DEPOSITS]
voluntary_exits: List[SignedVoluntaryExit, MAX_VOLUNTARY_EXITS]
application_payload: ApplicationPayload
```
246 changes: 246 additions & 0 deletions docs/wiki/CL/cl-architecture.md

Large diffs are not rendered by default.

38 changes: 13 additions & 25 deletions docs/wiki/CL/cl-networking.md
Original file line number Diff line number Diff line change
@@ -1,46 +1,33 @@
# Networking

The Consensus clients use [libp2p][libp2p] as the peer-to-peer protocol,
[discv5][discv5] for peer discovery, [libp2p-noise][libp2p-noise] for
encryption, [SSZ][ssz] for encoding, and, optionally, [Snappy][snappy] for
compression.
The Consensus clients use [libp2p][libp2p] as the peer-to-peer protocol, [discv5][discv5] for peer discovery, [libp2p-noise][libp2p-noise] for encryption, [SSZ][ssz] for encoding, and, optionally, [Snappy][snappy] for compression.

## ENR (Ethereum Node Records)

## discv5


## Specs

The [Phase 0 -- Networking][consensus-networking] page specifies the network
fundamentals, protocols, and rationale/design choices.
The [Phase 0 -- Networking][consensus-networking] page specifies the network fundamentals, protocols, and rationale/design choices.

## libp2p - P2P protocol

[libp2p][libp2p] is used as the peer-to-peer protocol.
[libp2p and Ethereum][libp2p-and-eth] is a great article for a deep-dive on the
history of libp2p, and its adoption in the Consensus clients.
[libp2p][libp2p] is used as the peer-to-peer protocol. [libp2p and Ethereum][libp2p-and-eth] is a great article for a deep-dive on the history of libp2p, and its adoption in the Consensus clients.

## libp2p-noise - Encryption

The [Noise framework][noise-framework] is not a protocol itself, but a framework
for designing key exchange protocols. The [specification][noise-specification]
is a great place to start.
The [Noise framework][noise-framework] is not a protocol itself, but a framework for designing key exchange protocols. The [specification][noise-specification] is a great place to start.

There are many [patterns][noise-patterns] which describe the key exchange
process. The pattern used in the consensus clients is [`XX`][noise-xx]
(transmit-transmit), meaning that both the initiator, and responder transmit
their public key in the initial stages of the key exchange.
There are many [patterns][noise-patterns] which describe the key exchange process. The pattern used in the consensus clients is [`XX`][noise-xx] (transmit-transmit), meaning that both the initiator, and responder transmit their public key in the initial stages of the key exchange.

## SSZ - Encoding

[Simple serialize (SSZ)][ssz] replaces the [RLP][rlp] serialization used on the
execution layer everywhere across the consensus layer except the peer discovery
protocol. SSZ is designed to be deterministic and also to Merkleize efficiently.
SSZ can be thought of as having two components: a serialization scheme and a
Merkleization scheme that is designed to work efficiently with the serialized
data structure.
[Simple serialize (SSZ)][ssz] replaces the [RLP][rlp] serialization used on the execution layer everywhere across the consensus layer except the peer discovery protocol. SSZ is designed to be deterministic and also to Merkleize efficiently. SSZ can be thought of as having two components: a serialization scheme and a Merkleization scheme that is designed to work efficiently with the serialized data structure.

## Snappy - Compression

[Snappy][snappy] is a compression scheme created by engineers at Google in 2011.
It's main design considerations prioritize compression/decompression speed,
while still having a reasonable compression ratio.
[Snappy][snappy] is a compression scheme created by engineers at Google in 2011. It's main design considerations prioritize compression/decompression speed, while still having a reasonable compression ratio.

## Related R&D

Expand All @@ -67,3 +54,4 @@ while still having a reasonable compression ratio.
[rlp]: https://ethereum.org/developers/docs/data-structures-and-encoding/rlp
[snappy]: https://en.wikipedia.org/wiki/Snappy_(compression)
[ssz]: https://ethereum.org/developers/docs/data-structures-and-encoding/ssz
[blog]: https://medium.com/coinmonks/dissecting-the-ethereum-networking-stack-node-discovery-4b3f7895f83f
10 changes: 0 additions & 10 deletions docs/wiki/CL/client-architecture.md

This file was deleted.

40 changes: 40 additions & 0 deletions docs/wiki/CL/gasper.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
# Gasper

## LMD GHOST (Latest Message Driven -- Greediest Heaviest Observed SubTree)

<!--
- What is lmd-ghost
- How subtree is selected
- fork-choice
- protocol
-->

## Casper FFG (Friendly Finality Gadget)

<!--
- justified chain
- checkpoints and finality
- gst, gat, synchronised
-->


- Hybrid Fork-choice (Refer pos-evolution in ethereum post/book)
Possible attacks
- simple ex-ante reorg
- weighted proposer boost

Solutions:
- view-merge strategy


## Resources

- [Combining GHOST and Casper](https://arxiv.org/pdf/2003.03052)
- [Yang X Zhang- Combining GHOST and Casper](https://www.youtube.com/watch?v=V0RjGmFE35U)
- [Introduction to Gasper from Ethereum.org](https://ethereum.org/en/developers/docs/consensus-mechanisms/pos/gasper/)
- [Evolution of Ethereum PoS Consensus Protocol](https://github.com/ethereum/pos-evolution/blob/master/pos-evolution.md)
- [Goldfish](https://arxiv.org/pdf/2209.03255)
- [Casper FFG](https://arxiv.org/pdf/1710.09437)
- [LMD Ghost](https://inevitableeth.com/home/ethereum/network/consensus/lmd-ghost)
- [RLMD GHOST with Luca Zanolini](https://www.youtube.com/watch?v=F2olypDSVnA)
- [Comparison of different LMD Ghost Implementations by ProtoLambda](https://github.com/protolambda/lmd-ghost)
Loading

0 comments on commit 35318ab

Please sign in to comment.