2019-04-22 13:20:48 +00:00
# Ethereum 2.0 Phase 0 -- Beacon Chain Fork Choice
2019-05-06 15:30:32 +00:00
**Notice**: This document is a work-in-progress for researchers and implementers.
2019-04-22 13:20:48 +00:00
## Table of contents
<!-- TOC -->
2019-12-10 14:17:06 +00:00
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE - RUN doctoc TO UPDATE -->
- [Introduction ](#introduction )
- [Fork choice ](#fork-choice )
- [Configuration ](#configuration )
- [Helpers ](#helpers )
- [`LatestMessage` ](#latestmessage )
- [`Store` ](#store )
2020-01-14 00:02:02 +00:00
- [`get_forkchoice_store` ](#get_forkchoice_store )
2019-12-12 16:48:53 +00:00
- [`get_slots_since_genesis` ](#get_slots_since_genesis )
2019-12-10 14:17:06 +00:00
- [`get_current_slot` ](#get_current_slot )
- [`compute_slots_since_epoch_start` ](#compute_slots_since_epoch_start )
- [`get_ancestor` ](#get_ancestor )
- [`get_latest_attesting_balance` ](#get_latest_attesting_balance )
- [`filter_block_tree` ](#filter_block_tree )
- [`get_filtered_block_tree` ](#get_filtered_block_tree )
- [`get_head` ](#get_head )
- [`should_update_justified_checkpoint` ](#should_update_justified_checkpoint )
2020-01-15 23:03:07 +00:00
- [`on_attestation` helpers ](#on_attestation-helpers )
- [`validate_on_attestation` ](#validate_on_attestation )
- [`store_target_checkpoint_state` ](#store_target_checkpoint_state )
- [`update_latest_messages` ](#update_latest_messages )
2019-12-10 14:17:06 +00:00
- [Handlers ](#handlers )
- [`on_tick` ](#on_tick )
- [`on_block` ](#on_block )
- [`on_attestation` ](#on_attestation )
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
2019-04-22 13:20:48 +00:00
<!-- /TOC -->
## Introduction
2020-01-10 18:42:55 +00:00
This document is the beacon chain fork choice spec, part of Ethereum 2.0 Phase 0. It assumes the [beacon chain state transition function spec ](./beacon-chain.md ).
2019-04-24 19:37:50 +00:00
2019-06-15 22:42:03 +00:00
## Fork choice
2020-03-11 21:03:14 +00:00
The head block root associated with a `store` is defined as `get_head(store)` . At genesis, let `store = get_forkchoice_store(genesis_state)` and update `store` by running:
2019-06-15 22:42:03 +00:00
2019-06-30 19:25:58 +00:00
- `on_tick(time)` whenever `time > store.time` where `time` is the current Unix time
2019-11-21 22:13:45 +00:00
- `on_block(block)` whenever a block `block: SignedBeaconBlock` is received
2019-06-30 19:25:58 +00:00
- `on_attestation(attestation)` whenever an attestation `attestation` is received
2019-06-15 22:42:03 +00:00
*Notes*:
2019-06-21 10:13:22 +00:00
1) **Leap seconds** : Slots will last `SECONDS_PER_SLOT + 1` or `SECONDS_PER_SLOT - 1` seconds around leap seconds. This is automatically handled by [UNIX time ](https://en.wikipedia.org/wiki/Unix_time ).
2019-06-15 22:42:03 +00:00
2) **Honest clocks** : Honest nodes are assumed to have clocks synchronized within `SECONDS_PER_SLOT` seconds of each other.
2020-01-10 18:42:55 +00:00
3) **Eth1 data** : The large `ETH1_FOLLOW_DISTANCE` specified in the [honest validator document ](./validator.md ) should ensure that `state.latest_eth1_data` of the canonical Ethereum 2.0 chain remains consistent with the canonical Ethereum 1.0 chain. If not, emergency manual intervention will be required.
2019-06-20 10:58:05 +00:00
4) **Manual forks** : Manual forks may arbitrarily change the fork choice rule but are expected to be enacted at epoch transitions, with the fork details reflected in `state.fork` .
2019-06-21 17:18:24 +00:00
5) **Implementation** : The implementation found in this specification is constructed for ease of understanding rather than for optimization in computation, space, or any other resource. A number of optimized alternatives can be found [here ](https://github.com/protolambda/lmd-ghost ).
2019-06-15 22:42:03 +00:00
2019-11-05 15:55:34 +00:00
### Configuration
| Name | Value | Unit | Duration |
| - | - | :-: | :-: |
2019-11-05 19:51:47 +00:00
| `SAFE_SLOTS_TO_UPDATE_JUSTIFIED` | `2**3` (= 8) | slots | 96 seconds |
2019-11-05 15:55:34 +00:00
2019-06-20 10:58:05 +00:00
### Helpers
2019-04-22 13:20:48 +00:00
2019-06-25 20:42:37 +00:00
#### `LatestMessage`
```python
@dataclass (eq=True, frozen=True)
class LatestMessage(object):
epoch: Epoch
2019-11-12 20:29:58 +00:00
root: Root
2019-06-25 20:42:37 +00:00
```
2019-06-15 22:42:03 +00:00
#### `Store`
```python
2019-06-17 14:48:33 +00:00
@dataclass
class Store(object):
2019-06-30 18:00:22 +00:00
time: uint64
2019-11-05 15:55:34 +00:00
genesis_time: uint64
2019-06-25 03:01:15 +00:00
justified_checkpoint: Checkpoint
finalized_checkpoint: Checkpoint
2019-11-07 00:10:32 +00:00
best_justified_checkpoint: Checkpoint
2020-03-10 19:20:57 +00:00
blocks: Dict[Root, BeaconBlock] = field(default_factory=dict)
2019-11-12 20:29:58 +00:00
block_states: Dict[Root, BeaconState] = field(default_factory=dict)
2019-06-21 18:55:55 +00:00
checkpoint_states: Dict[Checkpoint, BeaconState] = field(default_factory=dict)
2019-06-25 20:42:37 +00:00
latest_messages: Dict[ValidatorIndex, LatestMessage] = field(default_factory=dict)
2019-06-15 22:42:03 +00:00
```
2019-04-22 13:20:48 +00:00
2020-01-14 00:02:02 +00:00
#### `get_forkchoice_store`
The provided anchor-state will be regarded as a trusted state, to not roll back beyond.
This should be the genesis state for a full client.
2019-04-22 13:20:48 +00:00
2020-03-11 22:41:27 +00:00
*Note* With regards to fork choice, block headers are interchangeable with blocks. The spec is likely to move to headers for reduced overhead in test vectors and better encapsulation. Full implementations store blocks as part of their database and will often use full blocks when dealing with production fork choice.
_The block for `anchor_root` is incorrectly initialized to the block header, rather than the full block. This does not affect functionality but will be cleaned up in subsequent releases._
2019-06-15 22:42:03 +00:00
```python
2020-01-14 00:02:02 +00:00
def get_forkchoice_store(anchor_state: BeaconState) -> Store:
anchor_block_header = anchor_state.latest_block_header.copy()
if anchor_block_header.state_root == Bytes32():
anchor_block_header.state_root = hash_tree_root(anchor_state)
anchor_root = hash_tree_root(anchor_block_header)
anchor_epoch = get_current_epoch(anchor_state)
justified_checkpoint = Checkpoint(epoch=anchor_epoch, root=anchor_root)
finalized_checkpoint = Checkpoint(epoch=anchor_epoch, root=anchor_root)
2019-06-20 18:50:17 +00:00
return Store(
2020-02-22 18:06:31 +00:00
time=anchor_state.genesis_time + SECONDS_PER_SLOT * anchor_state.slot,
2020-01-14 00:02:02 +00:00
genesis_time=anchor_state.genesis_time,
2019-06-21 18:55:55 +00:00
justified_checkpoint=justified_checkpoint,
finalized_checkpoint=finalized_checkpoint,
2019-11-07 00:10:32 +00:00
best_justified_checkpoint=justified_checkpoint,
2020-01-14 00:02:02 +00:00
blocks={anchor_root: anchor_block_header},
block_states={anchor_root: anchor_state.copy()},
checkpoint_states={justified_checkpoint: anchor_state.copy()},
2019-06-20 18:50:17 +00:00
)
2019-06-15 22:42:03 +00:00
```
2019-04-22 13:20:48 +00:00
2019-12-10 02:02:16 +00:00
#### `get_slots_since_genesis`
```python
2019-12-10 17:12:51 +00:00
def get_slots_since_genesis(store: Store) -> int:
return (store.time - store.genesis_time) // SECONDS_PER_SLOT
2019-12-10 02:02:16 +00:00
```
2019-11-07 00:20:21 +00:00
#### `get_current_slot`
2019-11-05 15:55:34 +00:00
```python
def get_current_slot(store: Store) -> Slot:
2019-12-10 17:12:51 +00:00
return Slot(GENESIS_SLOT + get_slots_since_genesis(store))
2019-11-05 15:55:34 +00:00
```
2019-11-07 00:20:21 +00:00
#### `compute_slots_since_epoch_start`
```python
def compute_slots_since_epoch_start(slot: Slot) -> int:
return slot - compute_start_slot_at_epoch(compute_epoch_at_slot(slot))
```
2019-06-15 22:42:03 +00:00
#### `get_ancestor`
2019-04-22 13:20:48 +00:00
2019-06-15 22:42:03 +00:00
```python
2019-11-12 20:29:58 +00:00
def get_ancestor(store: Store, root: Root, slot: Slot) -> Root:
2019-06-15 22:42:03 +00:00
block = store.blocks[root]
2019-07-20 00:13:31 +00:00
if block.slot > slot:
return get_ancestor(store, block.parent_root, slot)
elif block.slot == slot:
return root
else:
2020-01-21 00:40:36 +00:00
# root is older than queried slot, thus a skip slot. Return earliest root prior to slot
return root
2019-06-15 22:42:03 +00:00
```
2019-04-22 13:20:48 +00:00
2019-06-20 10:58:05 +00:00
#### `get_latest_attesting_balance`
2019-04-22 13:20:48 +00:00
```python
2019-11-12 20:29:58 +00:00
def get_latest_attesting_balance(store: Store, root: Root) -> Gwei:
2019-06-21 18:55:55 +00:00
state = store.checkpoint_states[store.justified_checkpoint]
2019-06-25 17:48:55 +00:00
active_indices = get_active_validator_indices(state, get_current_epoch(state))
2019-06-19 18:27:54 +00:00
return Gwei(sum(
2019-06-25 17:48:55 +00:00
state.validators[i].effective_balance for i in active_indices
2019-06-30 20:59:12 +00:00
if (i in store.latest_messages
and get_ancestor(store, store.latest_messages[i].root, store.blocks[root].slot) == root)
2019-06-19 18:27:54 +00:00
))
2019-04-22 13:20:48 +00:00
```
2019-11-25 22:06:33 +00:00
#### `filter_block_tree`
```python
2019-11-25 22:44:22 +00:00
def filter_block_tree(store: Store, block_root: Root, blocks: Dict[Root, BeaconBlock]) -> bool:
2019-11-25 22:06:33 +00:00
block = store.blocks[block_root]
children = [
root for root in store.blocks.keys()
2019-11-25 22:44:22 +00:00
if store.blocks[root].parent_root == block_root
2019-11-25 22:06:33 +00:00
]
# If any children branches contain expected finalized/justified checkpoints,
# add to filtered block-tree and signal viability to parent.
if any(children):
2019-12-08 18:50:04 +00:00
filter_block_tree_result = [filter_block_tree(store, child, blocks) for child in children]
if any(filter_block_tree_result):
2019-11-25 22:06:33 +00:00
blocks[block_root] = block
return True
return False
# If leaf block, check finalized/justified checkpoints as matching latest.
head_state = store.block_states[block_root]
2019-11-25 22:44:22 +00:00
2019-12-04 23:50:48 +00:00
correct_justified = (
store.justified_checkpoint.epoch == GENESIS_EPOCH
or head_state.current_justified_checkpoint == store.justified_checkpoint
)
correct_finalized = (
store.finalized_checkpoint.epoch == GENESIS_EPOCH
or head_state.finalized_checkpoint == store.finalized_checkpoint
)
# If expected finalized/justified, add to viable block-tree and signal viability to parent.
if correct_justified and correct_finalized:
2019-11-25 22:06:33 +00:00
blocks[block_root] = block
return True
2019-12-04 23:50:48 +00:00
# Otherwise, branch not viable
2019-11-25 22:06:33 +00:00
return False
```
#### `get_filtered_block_tree`
```python
def get_filtered_block_tree(store: Store) -> Dict[Root, BeaconBlock]:
2019-12-04 23:50:48 +00:00
"""
2019-12-25 17:51:29 +00:00
Retrieve a filtered block tree from ``store``, only returning branches
2019-12-04 23:50:48 +00:00
whose leaf state's justified/finalized info agrees with that in ``store``.
"""
base = store.justified_checkpoint.root
2019-11-25 22:44:22 +00:00
blocks: Dict[Root, BeaconBlock] = {}
2019-12-04 23:50:48 +00:00
filter_block_tree(store, base, blocks)
2019-11-25 22:06:33 +00:00
return blocks
```
2019-06-15 22:42:03 +00:00
#### `get_head`
2019-04-22 13:20:48 +00:00
```python
2019-11-12 20:29:58 +00:00
def get_head(store: Store) -> Root:
2019-12-04 23:50:48 +00:00
# Get filtered block tree that only includes viable branches
2019-11-25 22:06:33 +00:00
blocks = get_filtered_block_tree(store)
2019-06-15 22:42:03 +00:00
# Execute the LMD-GHOST fork choice
2019-06-21 18:55:55 +00:00
head = store.justified_checkpoint.root
2019-10-23 00:37:15 +00:00
justified_slot = compute_start_slot_at_epoch(store.justified_checkpoint.epoch)
2019-06-15 22:42:03 +00:00
while True:
2019-06-20 20:48:10 +00:00
children = [
2019-11-25 22:06:33 +00:00
root for root in blocks.keys()
if blocks[root].parent_root == head and blocks[root].slot > justified_slot
2019-06-20 20:48:10 +00:00
]
2019-04-22 13:20:48 +00:00
if len(children) == 0:
return head
2019-06-20 10:58:05 +00:00
# Sort by latest attesting balance with ties broken lexicographically
head = max(children, key=lambda root: (get_latest_attesting_balance(store, root), root))
2019-06-15 22:42:03 +00:00
```
2019-11-05 15:55:34 +00:00
#### `should_update_justified_checkpoint`
```python
2019-11-07 00:10:32 +00:00
def should_update_justified_checkpoint(store: Store, new_justified_checkpoint: Checkpoint) -> bool:
2019-11-07 18:51:53 +00:00
"""
To address the bouncing attack, only update conflicting justified
checkpoints in the fork choice if in the early slots of the epoch.
Otherwise, delay incorporation of new justified checkpoint until next epoch boundary.
See https://ethresear.ch/t/prevention-of-bouncing-attack-on-ffg/6114 for more detailed analysis and discussion.
"""
2019-11-07 00:20:21 +00:00
if compute_slots_since_epoch_start(get_current_slot(store)) < SAFE_SLOTS_TO_UPDATE_JUSTIFIED:
2019-11-05 15:55:34 +00:00
return True
2020-01-21 00:40:36 +00:00
justified_slot = compute_start_slot_at_epoch(store.justified_checkpoint.epoch)
if not get_ancestor(store, new_justified_checkpoint.root, justified_slot) == store.justified_checkpoint.root:
2019-11-05 15:55:34 +00:00
return False
return True
```
2020-01-15 23:03:07 +00:00
#### `on_attestation` helpers
##### `validate_on_attestation`
```python
def validate_on_attestation(store: Store, attestation: Attestation) -> None:
target = attestation.data.target
# Attestations must be from the current or previous epoch
current_epoch = compute_epoch_at_slot(get_current_slot(store))
# Use GENESIS_EPOCH for previous when genesis to avoid underflow
previous_epoch = current_epoch - 1 if current_epoch > GENESIS_EPOCH else GENESIS_EPOCH
2020-04-30 06:27:02 +00:00
# If attestation target is from a future epoch, delay consideration until the epoch arrives
2020-01-15 23:03:07 +00:00
assert target.epoch in [current_epoch, previous_epoch]
assert target.epoch == compute_epoch_at_slot(attestation.data.slot)
# Attestations target be for a known block. If target block is unknown, delay consideration until the block is found
assert target.root in store.blocks
# Attestations must be for a known block. If block is unknown, delay consideration until the block is found
assert attestation.data.beacon_block_root in store.blocks
# Attestations must not be for blocks in the future. If not, the attestation should not be considered
assert store.blocks[attestation.data.beacon_block_root].slot < = attestation.data.slot
# Attestations can only affect the fork choice of subsequent slots.
# Delay consideration in the fork choice until their slot is in the past.
assert get_current_slot(store) >= attestation.data.slot + 1
```
##### `store_target_checkpoint_state`
```python
def store_target_checkpoint_state(store: Store, target: Checkpoint) -> None:
# Store target checkpoint state if not yet seen
if target not in store.checkpoint_states:
base_state = store.block_states[target.root].copy()
process_slots(base_state, compute_start_slot_at_epoch(target.epoch))
store.checkpoint_states[target] = base_state
```
##### `update_latest_messages`
```python
def update_latest_messages(store: Store, attesting_indices: Sequence[ValidatorIndex], attestation: Attestation) -> None:
target = attestation.data.target
beacon_block_root = attestation.data.beacon_block_root
for i in attesting_indices:
if i not in store.latest_messages or target.epoch > store.latest_messages[i].epoch:
store.latest_messages[i] = LatestMessage(epoch=target.epoch, root=beacon_block_root)
```
2019-06-15 22:42:03 +00:00
### Handlers
#### `on_tick`
```python
2019-06-30 18:00:22 +00:00
def on_tick(store: Store, time: uint64) -> None:
2019-11-05 15:55:34 +00:00
previous_slot = get_current_slot(store)
# update store time
2019-06-15 22:42:03 +00:00
store.time = time
2019-11-05 15:55:34 +00:00
current_slot = get_current_slot(store)
2019-11-05 18:02:58 +00:00
# Not a new epoch, return
2019-11-07 18:51:53 +00:00
if not (current_slot > previous_slot and compute_slots_since_epoch_start(current_slot) == 0):
2019-11-05 15:55:34 +00:00
return
2019-11-07 18:51:53 +00:00
# Update store.justified_checkpoint if a better checkpoint is known
2019-11-07 00:10:32 +00:00
if store.best_justified_checkpoint.epoch > store.justified_checkpoint.epoch:
store.justified_checkpoint = store.best_justified_checkpoint
2019-04-22 13:20:48 +00:00
```
2019-05-01 23:10:01 +00:00
2019-06-15 22:42:03 +00:00
#### `on_block`
2019-05-01 23:10:01 +00:00
2019-06-15 22:42:03 +00:00
```python
2019-11-21 22:13:45 +00:00
def on_block(store: Store, signed_block: SignedBeaconBlock) -> None:
block = signed_block.message
2019-06-21 11:00:42 +00:00
# Make a copy of the state to avoid mutability issues
2019-06-25 03:09:57 +00:00
assert block.parent_root in store.block_states
2019-06-25 03:01:15 +00:00
pre_state = store.block_states[block.parent_root].copy()
2019-06-21 10:19:08 +00:00
# Blocks cannot be in the future. If they are, their consideration must be delayed until the are in the past.
2019-12-10 17:12:51 +00:00
assert get_current_slot(store) >= block.slot
2019-06-15 22:42:03 +00:00
# Add new block to the store
2019-11-21 22:13:45 +00:00
store.blocks[hash_tree_root(block)] = block
2020-01-21 01:10:39 +00:00
# Check that block is later than the finalized epoch slot (optimization to reduce calls to get_ancestor)
2020-01-21 00:40:36 +00:00
finalized_slot = compute_start_slot_at_epoch(store.finalized_checkpoint.epoch)
2020-01-21 01:10:39 +00:00
assert block.slot > finalized_slot
2020-01-22 21:31:23 +00:00
# Check block is a descendant of the finalized block at the checkpoint finalized slot
2020-01-21 00:40:36 +00:00
assert get_ancestor(store, hash_tree_root(block), finalized_slot) == store.finalized_checkpoint.root
2020-01-21 01:10:39 +00:00
2019-06-15 22:42:03 +00:00
# Check the block is valid and compute the post-state
2019-11-21 22:13:45 +00:00
state = state_transition(pre_state, signed_block, True)
2019-06-20 20:48:10 +00:00
# Add new state for this block to the store
2019-11-21 22:13:45 +00:00
store.block_states[hash_tree_root(block)] = state
2019-06-21 18:55:55 +00:00
# Update justified checkpoint
2019-06-25 03:43:05 +00:00
if state.current_justified_checkpoint.epoch > store.justified_checkpoint.epoch:
2019-12-09 23:47:43 +00:00
if state.current_justified_checkpoint.epoch > store.best_justified_checkpoint.epoch:
store.best_justified_checkpoint = state.current_justified_checkpoint
2019-11-05 15:55:34 +00:00
if should_update_justified_checkpoint(store, state.current_justified_checkpoint):
store.justified_checkpoint = state.current_justified_checkpoint
2019-06-21 18:55:55 +00:00
# Update finalized checkpoint
2019-06-25 03:43:05 +00:00
if state.finalized_checkpoint.epoch > store.finalized_checkpoint.epoch:
store.finalized_checkpoint = state.finalized_checkpoint
2020-01-21 01:50:50 +00:00
finalized_slot = compute_start_slot_at_epoch(store.finalized_checkpoint.epoch)
# Update justified if new justified is later than store justified
# or if store justified is not in chain with finalized checkpoint
if (
state.current_justified_checkpoint.epoch > store.justified_checkpoint.epoch
or get_ancestor(store, store.justified_checkpoint.root, finalized_slot) != store.finalized_checkpoint.root
):
store.justified_checkpoint = state.current_justified_checkpoint
2019-06-15 22:42:03 +00:00
```
2019-05-01 23:10:01 +00:00
2019-06-15 22:42:03 +00:00
#### `on_attestation`
```python
def on_attestation(store: Store, attestation: Attestation) -> None:
2019-11-12 23:24:33 +00:00
"""
Run ``on_attestation`` upon receiving a new ``attestation`` from either within a block or directly on the wire.
An ``attestation`` that is asserted as invalid may be valid at a later time,
consider scheduling it for later processing in such case.
"""
2020-01-15 23:03:07 +00:00
validate_on_attestation(store, attestation)
store_target_checkpoint_state(store, attestation.data.target)
2019-06-20 20:48:10 +00:00
2020-01-15 23:03:07 +00:00
# Get state at the `target` to fully validate attestation
target_state = store.checkpoint_states[attestation.data.target]
2019-06-30 09:02:18 +00:00
indexed_attestation = get_indexed_attestation(target_state, attestation)
2019-06-30 22:10:28 +00:00
assert is_valid_indexed_attestation(target_state, indexed_attestation)
2019-06-20 20:48:10 +00:00
2020-01-15 23:03:07 +00:00
# Update latest messages for attesting indices
update_latest_messages(store, indexed_attestation.attesting_indices, attestation)
2019-06-15 22:42:03 +00:00
```