213 lines
7.0 KiB
Markdown
213 lines
7.0 KiB
Markdown
# Ethereum 2.0 Light Client Support
|
|
|
|
## Table of contents
|
|
|
|
<!-- TOC -->
|
|
<!-- 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)
|
|
- [Custom types](#custom-types)
|
|
- [Constants](#constants)
|
|
- [Configuration](#configuration)
|
|
- [Misc](#misc)
|
|
- [Time parameters](#time-parameters)
|
|
- [Domain types](#domain-types)
|
|
- [Containers](#containers)
|
|
- [Extended containers](#extended-containers)
|
|
- [`BeaconBlockBody`](#beaconblockbody)
|
|
- [`BeaconState`](#beaconstate)
|
|
- [New containers](#new-containers)
|
|
- [`SyncCommittee`](#synccommittee)
|
|
- [Helper functions](#helper-functions)
|
|
- [Misc](#misc-1)
|
|
- [`compactify_validator`](#compactify_validator)
|
|
- [`decompactify_validator`](#decompactify_validator)
|
|
- [Beacon state accessors](#beacon-state-accessors)
|
|
- [`get_sync_committee_indices`](#get_sync_committee_indices)
|
|
- [`get_sync_committee`](#get_sync_committee)
|
|
- [Block processing](#block-processing)
|
|
- [Sync committee processing](#sync-committee-processing)
|
|
- [Epoch processing](#epoch-processing)
|
|
- [Final updates](#final-updates)
|
|
|
|
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
|
|
<!-- /TOC -->
|
|
|
|
## Introduction
|
|
|
|
This is a standalone beacon chain patch adding light client support via sync committees.
|
|
|
|
## Custom types
|
|
|
|
| Name | SSZ equivalent | Description |
|
|
| - | - | - |
|
|
| `CompactValidator` | `uint64` | a compact validator |
|
|
|
|
## Constants
|
|
|
|
| Name | Value |
|
|
| - | - |
|
|
| `BASE_REWARDS_PER_EPOCH` | `uint64(5)` |
|
|
|
|
## Configuration
|
|
|
|
### Misc
|
|
|
|
| Name | Value |
|
|
| - | - |
|
|
| `MAX_SYNC_COMMITTEE_SIZE` | `uint64(2**8)` (= 256) |
|
|
|
|
### Time parameters
|
|
|
|
| Name | Value | Unit | Duration |
|
|
| - | - | :-: | :-: |
|
|
| `EPOCHS_PER_SYNC_COMMITTEE_PERIOD` | `Epoch(2**8)` (= 256) | epochs | ~27 hours |
|
|
|
|
### Domain types
|
|
|
|
| Name | Value |
|
|
| - | - |
|
|
| `DOMAIN_SYNC_COMMITTEE` | `DomainType('0x07000000')` |
|
|
|
|
## Containers
|
|
|
|
### Extended containers
|
|
|
|
#### `BeaconBlockBody`
|
|
|
|
```python
|
|
class BeaconBlockBody(phase0.BeaconBlockBody):
|
|
# Light client
|
|
sync_committee_bits: Bitlist[MAX_SYNC_COMMITTEE_SIZE]
|
|
sync_committee_signature: BLSSignature
|
|
```
|
|
|
|
#### `BeaconState`
|
|
|
|
```python
|
|
class BeaconState(phase0.BeaconState):
|
|
# Light client
|
|
current_sync_committee: SyncCommittee
|
|
next_sync_committee: SyncCommittee
|
|
```
|
|
|
|
### New containers
|
|
|
|
#### `SyncCommittee`
|
|
|
|
```python
|
|
class SyncCommittee(Container):
|
|
pubkeys: List[BLSPubkey, MAX_SYNC_COMMITTEE_SIZE]
|
|
pubkeys_aggregate: BLSPubkey
|
|
compact_validators: List[CompactValidator, MAX_SYNC_COMMITTEE_SIZE]
|
|
```
|
|
|
|
## Helper functions
|
|
|
|
### Misc
|
|
|
|
#### `compactify_validator`
|
|
|
|
```python
|
|
def compactify_validator(index: ValidatorIndex, slashed: bool, effective_balance: Gwei) -> CompactValidator:
|
|
"""
|
|
Return the compact validator for a given validator index, slashed status and effective balance.
|
|
"""
|
|
return CompactValidator((index << 16) + (slashed << 15) + uint64(effective_balance // EFFECTIVE_BALANCE_INCREMENT))
|
|
```
|
|
|
|
#### `decompactify_validator`
|
|
|
|
```python
|
|
def decompactify_validator(compact_validator: CompactValidator) -> Tuple[ValidatorIndex, bool, Gwei]:
|
|
"""
|
|
Return the validator index, slashed status and effective balance for a given compact validator.
|
|
"""
|
|
index = ValidatorIndex(compact_validator >> 16) # from bits 16-63
|
|
slashed = bool((compact_validator >> 15) % 2) # from bit 15
|
|
effective_balance = Gwei(compact_validator & (2**15 - 1)) * EFFECTIVE_BALANCE_INCREMENT # from bits 0-14
|
|
return (index, slashed, effective_balance)
|
|
```
|
|
|
|
### Beacon state accessors
|
|
|
|
#### `get_sync_committee_indices`
|
|
|
|
```python
|
|
def get_sync_committee_indices(state: BeaconState, epoch: Epoch) -> Sequence[ValidatorIndex]:
|
|
"""
|
|
Return the sync committee indices for a given state and epoch.
|
|
"""
|
|
base_epoch = Epoch((max(epoch // EPOCHS_PER_SYNC_COMMITTEE_PERIOD, 1) - 1) * EPOCHS_PER_SYNC_COMMITTEE_PERIOD)
|
|
active_validator_count = uint64(len(get_active_validator_indices(state, base_epoch)))
|
|
sync_committee_size = min(active_validator_count, MAX_SYNC_COMMITTEE_SIZE)
|
|
seed = get_seed(state, base_epoch, DOMAIN_SYNC_COMMITTEE)
|
|
return [compute_shuffled_index(uint64(i), active_validator_count, seed) for i in range(sync_committee_size)]
|
|
```
|
|
|
|
#### `get_sync_committee`
|
|
|
|
```python
|
|
def get_sync_committee(state: BeaconState, epoch: Epoch) -> SyncCommittee:
|
|
"""
|
|
Return the sync committee for a given state and epoch.
|
|
"""
|
|
indices = get_sync_committee_indices(state, epoch)
|
|
validators = [state.validators[index] for index in indices]
|
|
pubkeys = [validator.pubkey for validator in validators]
|
|
compact_validators = [compactify_validator(i, v.slashed, v.effective_balance) for i, v in zip(indices, validators)]
|
|
return SyncCommittee(pubkeys, bls.AggregatePKs(pubkeys), compact_validators)
|
|
```
|
|
|
|
### Block processing
|
|
|
|
```python
|
|
def process_block(state: BeaconState, block: BeaconBlock) -> None:
|
|
phase0.process_block(state, block)
|
|
process_sync_committee(state, block.body)
|
|
```
|
|
|
|
#### Sync committee processing
|
|
|
|
```python
|
|
def process_sync_committee(state: BeaconState, body: BeaconBlockBody) -> None:
|
|
# Verify sync committee bitfield length
|
|
committee_indices = get_sync_committee_indices(state, get_current_epoch(state))
|
|
assert len(body.sync_committee_bits) == len(committee_indices)
|
|
|
|
# Verify sync committee aggregate signature signing over the previous slot block root
|
|
previous_slot = max(state.slot, Slot(1)) - Slot(1)
|
|
participant_indices = [committee_indices[i] for i in range(len(committee_indices)) if body.sync_committee_bits[i]]
|
|
participant_pubkeys = [state.validators[participant_index].pubkey for participant_index in participant_indices]
|
|
domain = get_domain(state, DOMAIN_SYNC_COMMITTEE, compute_epoch_at_slot(previous_slot))
|
|
signing_root = compute_signing_root(get_block_root_at_slot(state, previous_slot), domain)
|
|
assert bls.FastAggregateVerify(participant_pubkeys, signing_root, body.sync_committee_signature)
|
|
|
|
# Reward sync committee participants
|
|
participant_rewards = Gwei(0)
|
|
active_validator_count = uint64(len(get_active_validator_indices(state, get_current_epoch(state))))
|
|
for participant_index in participant_indices:
|
|
base_reward = get_base_reward(state, participant_index)
|
|
reward = Gwei(base_reward * active_validator_count // len(committee_indices) // SLOTS_PER_EPOCH)
|
|
increase_balance(state, participant_index, reward)
|
|
participant_rewards += reward
|
|
|
|
# Reward beacon proposer
|
|
increase_balance(state, get_beacon_proposer_index(state), Gwei(participant_rewards // PROPOSER_REWARD_QUOTIENT))
|
|
```
|
|
|
|
### Epoch processing
|
|
|
|
#### Final updates
|
|
|
|
```python
|
|
def process_final_updates(state: BeaconState) -> None:
|
|
phase0.process_final_updates(state)
|
|
next_epoch = get_current_epoch(state) + Epoch(1)
|
|
if next_epoch % EPOCHS_PER_SYNC_COMMITTEE_PERIOD == 0:
|
|
state.current_sync_committee = state.next_sync_committee
|
|
state.next_sync_committee = get_sync_committee(state, next_epoch + EPOCHS_PER_SYNC_COMMITTEE_PERIOD)
|
|
```
|