Skip to content

Commit 1bc84ae

Browse files
MegaRedHandMegaRedHand
authored
docs: add fork logic spec (#5)
* Altair * Bellatrix * Capella
1 parent fdf073e commit 1bc84ae

File tree

1 file changed

+290
-0
lines changed

1 file changed

+290
-0
lines changed

‎spec/fork.md

Lines changed: 290 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,290 @@
1+
# Fork Logic
2+
3+
## Table of contents
4+
5+
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
6+
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
7+
8+
- [Introduction](#introduction)
9+
- [Configuration](#configuration)
10+
- [Helper functions](#helper-functions)
11+
- [Misc](#misc)
12+
- [`compute_fork_version`](#compute_fork_version)
13+
- [Fork to Altair](#fork-to-altair)
14+
- [Fork trigger](#fork-trigger)
15+
- [Upgrading the state](#upgrading-the-state)
16+
17+
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
18+
19+
## Introduction
20+
21+
This document describes the process of the upgrade of the beacon chain.
22+
23+
## Configuration
24+
25+
Warning: this configuration is not definitive.
26+
27+
| Name | Value |
28+
| - | - |
29+
| `ALTAIR_FORK_VERSION` | `Version('0x01000000')` |
30+
| `ALTAIR_FORK_EPOCH` | `Epoch(74240)` (Oct 27, 2021, 10:56:23am UTC) |
31+
| `BELLATRIX_FORK_VERSION` | `Version('0x02000000')` |
32+
| `BELLATRIX_FORK_EPOCH` | `Epoch(144896)` (Sept 6, 2022, 11:34:47am UTC) |
33+
| `CAPELLA_FORK_VERSION` | `Version('0x03000000')` |
34+
| `CAPELLA_FORK_EPOCH` | `Epoch(194048)` (April 12, 2023, 10:27:35pm UTC) |
35+
36+
## Helper functions
37+
38+
### Misc
39+
40+
#### `compute_fork_version`
41+
42+
```python
43+
def compute_fork_version(epoch: Epoch) -> Version:
44+
"""
45+
Return the fork version at the given ``epoch``.
46+
"""
47+
if epoch >= CAPELLA_FORK_EPOCH:
48+
return CAPELLA_FORK_VERSION
49+
if epoch >= BELLATRIX_FORK_EPOCH:
50+
return BELLATRIX_FORK_VERSION
51+
if epoch >= ALTAIR_FORK_EPOCH:
52+
return ALTAIR_FORK_VERSION
53+
return GENESIS_FORK_VERSION
54+
```
55+
56+
## Fork to Altair
57+
58+
### Fork trigger
59+
60+
The fork is triggered at epoch `ALTAIR_FORK_EPOCH`.
61+
62+
Note that for the pure Altair networks, we don't apply `upgrade_to_altair` since it starts with Altair version logic.
63+
64+
### Upgrading the state
65+
66+
If `state.slot % SLOTS_PER_EPOCH == 0` and `compute_epoch_at_slot(state.slot) == ALTAIR_FORK_EPOCH`, an irregular state change is made to upgrade to Altair.
67+
68+
The upgrade occurs after the completion of the inner loop of `process_slots` that sets `state.slot` equal to `ALTAIR_FORK_EPOCH * SLOTS_PER_EPOCH`.
69+
Care must be taken when transitioning through the fork boundary as implementations will need a modified [state transition function](../phase0/beacon-chain.md#beacon-chain-state-transition-function) that deviates from the Phase 0 document.
70+
In particular, the outer `state_transition` function defined in the Phase 0 document will not expose the precise fork slot to execute the upgrade in the presence of skipped slots at the fork boundary. Instead the logic must be within `process_slots`.
71+
72+
```python
73+
def translate_participation(state: BeaconState, pending_attestations: Sequence[phase0.PendingAttestation]) -> None:
74+
for attestation in pending_attestations:
75+
data = attestation.data
76+
inclusion_delay = attestation.inclusion_delay
77+
# Translate attestation inclusion info to flag indices
78+
participation_flag_indices = get_attestation_participation_flag_indices(state, data, inclusion_delay)
79+
80+
# Apply flags to all attesting validators
81+
epoch_participation = state.previous_epoch_participation
82+
for index in get_attesting_indices(state, data, attestation.aggregation_bits):
83+
for flag_index in participation_flag_indices:
84+
epoch_participation[index] = add_flag(epoch_participation[index], flag_index)
85+
86+
87+
def upgrade_to_altair(pre: phase0.BeaconState) -> BeaconState:
88+
epoch = phase0.get_current_epoch(pre)
89+
post = BeaconState(
90+
# Versioning
91+
genesis_time=pre.genesis_time,
92+
genesis_validators_root=pre.genesis_validators_root,
93+
slot=pre.slot,
94+
fork=Fork(
95+
previous_version=pre.fork.current_version,
96+
current_version=ALTAIR_FORK_VERSION,
97+
epoch=epoch,
98+
),
99+
# History
100+
latest_block_header=pre.latest_block_header,
101+
block_roots=pre.block_roots,
102+
state_roots=pre.state_roots,
103+
historical_roots=pre.historical_roots,
104+
# Eth1
105+
eth1_data=pre.eth1_data,
106+
eth1_data_votes=pre.eth1_data_votes,
107+
eth1_deposit_index=pre.eth1_deposit_index,
108+
# Registry
109+
validators=pre.validators,
110+
balances=pre.balances,
111+
# Randomness
112+
randao_mixes=pre.randao_mixes,
113+
# Slashings
114+
slashings=pre.slashings,
115+
# Participation
116+
previous_epoch_participation=[ParticipationFlags(0b0000_0000) for _ in range(len(pre.validators))],
117+
current_epoch_participation=[ParticipationFlags(0b0000_0000) for _ in range(len(pre.validators))],
118+
# Finality
119+
justification_bits=pre.justification_bits,
120+
previous_justified_checkpoint=pre.previous_justified_checkpoint,
121+
current_justified_checkpoint=pre.current_justified_checkpoint,
122+
finalized_checkpoint=pre.finalized_checkpoint,
123+
# Inactivity
124+
inactivity_scores=[uint64(0) for _ in range(len(pre.validators))],
125+
)
126+
# Fill in previous epoch participation from the pre state's pending attestations
127+
translate_participation(post, pre.previous_epoch_attestations)
128+
129+
# Fill in sync committees
130+
# Note: A duplicate committee is assigned for the current and next committee at the fork boundary
131+
post.current_sync_committee = get_next_sync_committee(post)
132+
post.next_sync_committee = get_next_sync_committee(post)
133+
return post
134+
```
135+
136+
## Fork to Bellatrix
137+
138+
### Fork trigger
139+
140+
TBD. Social consensus, along with state conditions such as epoch boundary, finality, deposits, active validator count, etc. may be part of the decision process to trigger the fork. For now we assume the condition will be triggered at epoch `BELLATRIX_FORK_EPOCH`.
141+
142+
Note that for the pure Bellatrix networks, we don't apply `upgrade_to_bellatrix` since it starts with Bellatrix version logic.
143+
144+
### Upgrading the state
145+
146+
As with the Phase0-to-Altair upgrade, the `state_transition` is modified to upgrade the `BeaconState`.
147+
The `BeaconState` upgrade runs as part of `process_slots`, slots with missing block proposals do not affect the upgrade time.
148+
149+
If `state.slot % SLOTS_PER_EPOCH == 0` and `compute_epoch_at_slot(state.slot) == BELLATRIX_FORK_EPOCH`, an irregular state change is made to upgrade to Bellatrix.
150+
The upgrade occurs after the completion of the inner loop of `process_slots` that sets `state.slot` equal to `BELLATRIX_FORK_EPOCH * SLOTS_PER_EPOCH`.
151+
152+
When multiple upgrades are scheduled for the same epoch (common for test-networks),
153+
all the upgrades run in sequence before resuming the regular state transition.
154+
155+
```python
156+
def upgrade_to_bellatrix(pre: altair.BeaconState) -> BeaconState:
157+
epoch = altair.get_current_epoch(pre)
158+
post = BeaconState(
159+
# Versioning
160+
genesis_time=pre.genesis_time,
161+
genesis_validators_root=pre.genesis_validators_root,
162+
slot=pre.slot,
163+
fork=Fork(
164+
previous_version=pre.fork.current_version,
165+
current_version=BELLATRIX_FORK_VERSION,
166+
epoch=epoch,
167+
),
168+
# History
169+
latest_block_header=pre.latest_block_header,
170+
block_roots=pre.block_roots,
171+
state_roots=pre.state_roots,
172+
historical_roots=pre.historical_roots,
173+
# Eth1
174+
eth1_data=pre.eth1_data,
175+
eth1_data_votes=pre.eth1_data_votes,
176+
eth1_deposit_index=pre.eth1_deposit_index,
177+
# Registry
178+
validators=pre.validators,
179+
balances=pre.balances,
180+
# Randomness
181+
randao_mixes=pre.randao_mixes,
182+
# Slashings
183+
slashings=pre.slashings,
184+
# Participation
185+
previous_epoch_participation=pre.previous_epoch_participation,
186+
current_epoch_participation=pre.current_epoch_participation,
187+
# Finality
188+
justification_bits=pre.justification_bits,
189+
previous_justified_checkpoint=pre.previous_justified_checkpoint,
190+
current_justified_checkpoint=pre.current_justified_checkpoint,
191+
finalized_checkpoint=pre.finalized_checkpoint,
192+
# Inactivity
193+
inactivity_scores=pre.inactivity_scores,
194+
# Sync
195+
current_sync_committee=pre.current_sync_committee,
196+
next_sync_committee=pre.next_sync_committee,
197+
# Execution-layer
198+
latest_execution_payload_header=ExecutionPayloadHeader(),
199+
)
200+
201+
return post
202+
```
203+
204+
## Fork to Capella
205+
206+
### Fork trigger
207+
208+
The fork is triggered at epoch `CAPELLA_FORK_EPOCH`.
209+
210+
Note that for the pure Capella networks, we don't apply `upgrade_to_capella` since it starts with Capella version logic.
211+
212+
### Upgrading the state
213+
214+
If `state.slot % SLOTS_PER_EPOCH == 0` and `compute_epoch_at_slot(state.slot) == CAPELLA_FORK_EPOCH`,
215+
an irregular state change is made to upgrade to Capella.
216+
217+
The upgrade occurs after the completion of the inner loop of `process_slots` that sets `state.slot` equal to `CAPELLA_FORK_EPOCH * SLOTS_PER_EPOCH`.
218+
Care must be taken when transitioning through the fork boundary as implementations will need a modified [state transition function](../phase0/beacon-chain.md#beacon-chain-state-transition-function) that deviates from the Phase 0 document.
219+
In particular, the outer `state_transition` function defined in the Phase 0 document will not expose the precise fork slot to execute the upgrade in the presence of skipped slots at the fork boundary. Instead, the logic must be within `process_slots`.
220+
221+
```python
222+
def upgrade_to_capella(pre: bellatrix.BeaconState) -> BeaconState:
223+
epoch = bellatrix.get_current_epoch(pre)
224+
latest_execution_payload_header = ExecutionPayloadHeader(
225+
parent_hash=pre.latest_execution_payload_header.parent_hash,
226+
fee_recipient=pre.latest_execution_payload_header.fee_recipient,
227+
state_root=pre.latest_execution_payload_header.state_root,
228+
receipts_root=pre.latest_execution_payload_header.receipts_root,
229+
logs_bloom=pre.latest_execution_payload_header.logs_bloom,
230+
prev_randao=pre.latest_execution_payload_header.prev_randao,
231+
block_number=pre.latest_execution_payload_header.block_number,
232+
gas_limit=pre.latest_execution_payload_header.gas_limit,
233+
gas_used=pre.latest_execution_payload_header.gas_used,
234+
timestamp=pre.latest_execution_payload_header.timestamp,
235+
extra_data=pre.latest_execution_payload_header.extra_data,
236+
base_fee_per_gas=pre.latest_execution_payload_header.base_fee_per_gas,
237+
block_hash=pre.latest_execution_payload_header.block_hash,
238+
transactions_root=pre.latest_execution_payload_header.transactions_root,
239+
withdrawals_root=Root(), # [New in Capella]
240+
)
241+
post = BeaconState(
242+
# Versioning
243+
genesis_time=pre.genesis_time,
244+
genesis_validators_root=pre.genesis_validators_root,
245+
slot=pre.slot,
246+
fork=Fork(
247+
previous_version=pre.fork.current_version,
248+
current_version=CAPELLA_FORK_VERSION,
249+
epoch=epoch,
250+
),
251+
# History
252+
latest_block_header=pre.latest_block_header,
253+
block_roots=pre.block_roots,
254+
state_roots=pre.state_roots,
255+
historical_roots=pre.historical_roots,
256+
# Eth1
257+
eth1_data=pre.eth1_data,
258+
eth1_data_votes=pre.eth1_data_votes,
259+
eth1_deposit_index=pre.eth1_deposit_index,
260+
# Registry
261+
validators=pre.validators,
262+
balances=pre.balances,
263+
# Randomness
264+
randao_mixes=pre.randao_mixes,
265+
# Slashings
266+
slashings=pre.slashings,
267+
# Participation
268+
previous_epoch_participation=pre.previous_epoch_participation,
269+
current_epoch_participation=pre.current_epoch_participation,
270+
# Finality
271+
justification_bits=pre.justification_bits,
272+
previous_justified_checkpoint=pre.previous_justified_checkpoint,
273+
current_justified_checkpoint=pre.current_justified_checkpoint,
274+
finalized_checkpoint=pre.finalized_checkpoint,
275+
# Inactivity
276+
inactivity_scores=pre.inactivity_scores,
277+
# Sync
278+
current_sync_committee=pre.current_sync_committee,
279+
next_sync_committee=pre.next_sync_committee,
280+
# Execution-layer
281+
latest_execution_payload_header=latest_execution_payload_header,
282+
# Withdrawals
283+
next_withdrawal_index=WithdrawalIndex(0), # [New in Capella]
284+
next_withdrawal_validator_index=ValidatorIndex(0), # [New in Capella]
285+
# Deep history valid from Capella onwards
286+
historical_summaries=List[HistoricalSummary, HISTORICAL_ROOTS_LIMIT]([]), # [New in Capella]
287+
)
288+
289+
return post
290+
```

0 commit comments

Comments
 (0)