Consensus Layer Wiki Page (#246)

* 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]>
eth-protocol-fellows · Jul 30, 2024 · 35318ab · 35318ab
1 parent 2d66785
commit 35318ab
Show file tree

Hide file tree

Showing 30 changed files with 2,892 additions and 60 deletions.
diff --git a/docs/_sidebar.md b/docs/_sidebar.md
@@ -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

diff --git a/docs/images/cl/RANDAO.png b/docs/images/cl/RANDAO.png
diff --git a/docs/images/cl/blobs.png b/docs/images/cl/blobs.png
diff --git a/docs/images/cl/blockchain.svg b/docs/images/cl/blockchain.svg
diff --git a/docs/images/cl/blocktree.svg b/docs/images/cl/blocktree.svg
diff --git a/docs/images/cl/checkpoints.jpg b/docs/images/cl/checkpoints.jpg
diff --git a/docs/images/cl/cl-ideal.png b/docs/images/cl/cl-ideal.png
diff --git a/docs/images/cl/cl-networking-overview.webp b/docs/images/cl/cl-networking-overview.webp
diff --git a/docs/images/cl/cl-real.png b/docs/images/cl/cl-real.png
diff --git a/docs/images/cl/cl.png b/docs/images/cl/cl.png
diff --git a/docs/images/cl/client-architecture.png b/docs/images/cl/client-architecture.png
diff --git a/docs/images/cl/committees.png b/docs/images/cl/committees.png
diff --git a/docs/images/cl/el.png b/docs/images/cl/el.png
diff --git a/docs/images/cl/finalization.png b/docs/images/cl/finalization.png
diff --git a/docs/images/cl/network.png b/docs/images/cl/network.png
diff --git a/docs/images/cl/reorg-0.svg b/docs/images/cl/reorg-0.svg
diff --git a/docs/images/cl/reorg-1.svg b/docs/images/cl/reorg-1.svg
diff --git a/docs/images/cl/slots-and-epochs.png b/docs/images/cl/slots-and-epochs.png
diff --git a/docs/images/cl/validator-lifecycle.png b/docs/images/cl/validator-lifecycle.png
diff --git a/docs/images/cl/validators.png b/docs/images/cl/validators.png
diff --git a/docs/wiki/CL/beacon-api.md b/docs/wiki/CL/beacon-api.md
@@ -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
+```
diff --git a/docs/wiki/CL/cl-architecture.md b/docs/wiki/CL/cl-architecture.md
diff --git a/docs/wiki/CL/cl-networking.md b/docs/wiki/CL/cl-networking.md
@@ -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
 
@@ -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
diff --git a/docs/wiki/CL/client-architecture.md b/docs/wiki/CL/client-architecture.md
diff --git a/docs/wiki/CL/gasper.md b/docs/wiki/CL/gasper.md
@@ -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)