Skip to content

Commit 9231f97

Browse files
g11techunnawutsyjn99
authored
feat: add 3sf forkchoice specs (leanEthereum#29)
* feat: add devnet0 STF for chain-ing and 3sf mini * add genesis initalization * improvements and cleanup * add main STF * add block processing * properly process historical blockhashes and justified slots before voting * add the voting processing from 3sf mini * further voting process refinements * add is justifiable slot * further improvs * Update docs/client/chain.md Co-authored-by: Unnawut Leepaisalsuwanna <921194+unnawut@users.noreply.github.com> * Update docs/client/chain.md Co-authored-by: Unnawut Leepaisalsuwanna <921194+unnawut@users.noreply.github.com> * Update docs/client/chain.md * Update docs/client/chain.md * apply votes * fix the mini 3sf book keeping * python fix * add get_justifications and set_justifications impl * add lean devnet0 forkchoice * forkchoice updates * updates * complete the forkchoice lifecylce * add validator attestation construction * add on block fc processing * add block proposal * improve the on_tick to take care of registered validator * cleanup and formatting * aligning the validator attestation process with the forkchoice * fix parent root references * Update docs/client/forkchoice.md Co-authored-by: Jun Song <87601811+syjn99@users.noreply.github.com> * improvements * Update docs/client/forkchoice.md Co-authored-by: Jun Song <87601811+syjn99@users.noreply.github.com> * Update docs/client/forkchoice.md Co-authored-by: Jun Song <87601811+syjn99@users.noreply.github.com> * Update docs/client/forkchoice.md Co-authored-by: Jun Song <87601811+syjn99@users.noreply.github.com> * update on attestation * Update docs/client/forkchoice.md Co-authored-by: Jun Song <87601811+syjn99@users.noreply.github.com> * add a very basic validation * python syntax fixes and safe target min score as 2/3rd ceiling * improve vote construction * bring the vote construction back to validator * slight formating, small typo fix and renaming * lint * Update docs/client/forkchoice.md Co-authored-by: Jun Song <87601811+syjn99@users.noreply.github.com> * Update docs/client/validator.md Co-authored-by: Jun Song <87601811+syjn99@users.noreply.github.com> * Update docs/client/forkchoice.md Co-authored-by: Jun Song <87601811+syjn99@users.noreply.github.com> * Update docs/client/forkchoice.md Co-authored-by: Jun Song <87601811+syjn99@users.noreply.github.com> * Update docs/client/validator.md Co-authored-by: Jun Song <87601811+syjn99@users.noreply.github.com> * fix store --------- Co-authored-by: Unnawut Leepaisalsuwanna <921194+unnawut@users.noreply.github.com> Co-authored-by: Jun Song <87601811+syjn99@users.noreply.github.com>
1 parent d0033cd commit 9231f97

4 files changed

Lines changed: 457 additions & 13 deletions

File tree

docs/client/chain.md

Lines changed: 14 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
# Lean Consensus Experimental Chain
2+
23
<!-- mdformat-toc start --slug=github --no-anchors --maxlevel=6 --minlevel=2 -->
34

45
- [Introduction](#introduction)
@@ -32,15 +33,14 @@ This document specs the behavior and functionality of the lean chain. This is a
3233
| 0 | minimal consensus | Sep 2025 |
3334
| 1 | pq signature | Oct 2025 |
3435

35-
3636
### Devnet 0 Functionality
3737

3838
1. Chain-ing: This is beacon style chaining via `latest_block_header` in state verified against parent hash of the new block. LMD-Ghost (without application of beacon chain style filter block tree)
39-
2. 3SF mini justification & finalization: Departing from the beacon chain epoch centric processing, the lean chain employs a slightly translated version of the 3SF mini where all validators vote every slot.
40-
3. Empty signatures: Since we will be moving to post quantum signatures `Devnet1` onwards, `Devnet0` data is generated with zero bytes signatures with no signature verification involved. This means voting is a trusted process where the client creates a vote as per their assigned validators.
41-
4. No Aggregation: The votes casted in the network are simply consumed and packed without aggregation. Beacon style aggregation will be introduced in the Devnet 2.
42-
5. Round robin proposals: The proposal assignment process has also been kept simple to just assign the proposals based on a round robin process based on the validator index. This makes proposal also a trusted process where the client proposes a block as per their assigned validators.
43-
5. Simplified Validators: There is no validator deposit, activation, withdrawal or slashing making the validator lifecycle super simple. Each validator has the weight of `1` and since validators don't even generate signatures, there is no validator tracking in the state. Validators are assigned to the clients based on a config file.
39+
1. 3SF mini justification & finalization: Departing from the beacon chain epoch centric processing, the lean chain employs a slightly translated version of the 3SF mini where all validators vote every slot.
40+
1. Empty signatures: Since we will be moving to post quantum signatures `Devnet1` onwards, `Devnet0` data is generated with zero bytes signatures with no signature verification involved. This means voting is a trusted process where the client creates a vote as per their assigned validators.
41+
1. No Aggregation: The votes casted in the network are simply consumed and packed without aggregation. Beacon style aggregation will be introduced in the Devnet 2.
42+
1. Round robin proposals: The proposal assignment process has also been kept simple to just assign the proposals based on a round robin process based on the validator index. This makes proposal also a trusted process where the client proposes a block as per their assigned validators.
43+
1. Simplified Validators: There is no validator deposit, activation, withdrawal or slashing making the validator lifecycle super simple. Each validator has the weight of `1` and since validators don't even generate signatures, there is no validator tracking in the state. Validators are assigned to the clients based on a config file.
4444

4545
## Configuration
4646

@@ -71,10 +71,10 @@ _Note:_ The definitions below are for specification purposes and are not necessa
7171
Returns a map of `root -> justifications` constructed from the flattened data in
7272
the state:
7373

74-
- `state.justifications_roots` which is a list of block roots that are under
75-
voting consideration
76-
- `state.justifications_validators` which are flattened list of validator ids
77-
which have voted for the respective roots
74+
- `state.justifications_roots` which is a list of block roots that are under
75+
voting consideration
76+
- `state.justifications_validators` which are flattened list of validator ids
77+
which have voted for the respective roots
7878

7979
A client implementation may cache this map on the first construction for performance.
8080

@@ -143,10 +143,11 @@ def is_justifiable_slot(finalized_slot: int, candidate: int):
143143
The genesis for lean devnets especially `Devnet0` is rather simple. This can even be generated by clients locally:
144144
Let `genesis_state = generate_genesis_state(genesis_time, num_validators)`
145145
where:
146-
- `genesis_time` is the configured time for the genesis slot
147-
- `num_validators` is the configured number of validators to run the chain with
148146

149-
Even though `Devnet0` has no individual validators tracking, there would also be no need for `genesis_validators_root` going further as well because the state and hence state root would already encode the genesis validator's array.
147+
- `genesis_time` is the configured time for the genesis slot
148+
- `num_validators` is the configured number of validators to run the chain with
149+
150+
Even though `Devnet0` has no individual validators tracking, there would also be no need for `genesis_validators_root` going further as well because the state and hence state root would already encode the genesis validator's array.
150151

151152
### Genesis state
152153

docs/client/containers.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
<!-- mdformat-toc start --slug=github --no-anchors --maxlevel=6 --minlevel=2 -->
22

3+
- [Encoding](#encoding)
34
- [`Config`](#config)
45
- [`Checkpoint`](#checkpoint)
56
- [`State`](#state)
@@ -16,6 +17,10 @@
1617

1718
# Containers
1819

20+
## Encoding
21+
22+
The containers for various blockchain consensus objects are primarily SSZ objects. To be more prover friendly, the Poseidon2 hasher will be used for hash tree rooting of these objects. However `devnet0` & `devnet1` continue to use the sha256 hasher.
23+
1924
## `Config`
2025

2126
```python

0 commit comments

Comments
 (0)