196 lines
7.7 KiB
Markdown
196 lines
7.7 KiB
Markdown
# Minimal Light Client
|
|
|
|
**Notice**: This document is a work-in-progress for researchers and implementers.
|
|
|
|
## 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)
|
|
- [Constants](#constants)
|
|
- [Configuration](#configuration)
|
|
- [Misc](#misc)
|
|
- [Containers](#containers)
|
|
- [`LightClientSnapshot`](#lightclientsnapshot)
|
|
- [`LightClientUpdate`](#lightclientupdate)
|
|
- [`LightClientStore`](#lightclientstore)
|
|
- [Helper functions](#helper-functions)
|
|
- [`get_subtree_index`](#get_subtree_index)
|
|
- [Light client state updates](#light-client-state-updates)
|
|
- [`validate_light_client_update`](#validate_light_client_update)
|
|
- [`apply_light_client_update`](#apply_light_client_update)
|
|
- [`process_light_client_update`](#process_light_client_update)
|
|
|
|
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
|
|
<!-- /TOC -->
|
|
|
|
## Introduction
|
|
|
|
Eth2 is designed to be light client friendly for constrained environments to
|
|
access Eth2 with reasonable safety and liveness.
|
|
Such environments include resource-constrained devices (e.g. phones for trust-minimised wallets)
|
|
and metered VMs (e.g. blockchain VMs for cross-chain bridges).
|
|
|
|
This document suggests a minimal light client design for the beacon chain that
|
|
uses sync committees introduced in [this beacon chain extension](./beacon-chain.md).
|
|
|
|
## Constants
|
|
|
|
| Name | Value |
|
|
| - | - |
|
|
| `FINALIZED_ROOT_INDEX` | `get_generalized_index(BeaconState, 'finalized_checkpoint', 'root')` |
|
|
| `NEXT_SYNC_COMMITTEE_INDEX` | `get_generalized_index(BeaconState, 'next_sync_committee')` |
|
|
|
|
## Configuration
|
|
|
|
### Misc
|
|
|
|
| Name | Value |
|
|
| - | - |
|
|
| `MIN_SYNC_COMMITTEE_PARTICIPANTS` | `1` |
|
|
|
|
## Containers
|
|
|
|
### `LightClientSnapshot`
|
|
|
|
```python
|
|
class LightClientSnapshot(Container):
|
|
# Beacon block header
|
|
header: BeaconBlockHeader
|
|
# Sync committees corresponding to the header
|
|
current_sync_committee: SyncCommittee
|
|
next_sync_committee: SyncCommittee
|
|
```
|
|
|
|
### `LightClientUpdate`
|
|
|
|
```python
|
|
class LightClientUpdate(Container):
|
|
# Update beacon block header
|
|
header: BeaconBlockHeader
|
|
# Next sync committee corresponding to the header
|
|
next_sync_committee: SyncCommittee
|
|
next_sync_committee_branch: Vector[Bytes32, floorlog2(NEXT_SYNC_COMMITTEE_INDEX)]
|
|
# Finality proof for the update header
|
|
finality_header: BeaconBlockHeader
|
|
finality_branch: Vector[Bytes32, floorlog2(FINALIZED_ROOT_INDEX)]
|
|
# Sync committee aggregate signature
|
|
sync_committee_bits: Bitvector[SYNC_COMMITTEE_SIZE]
|
|
sync_committee_signature: BLSSignature
|
|
# Fork version for the aggregate signature
|
|
fork_version: Version
|
|
```
|
|
|
|
### `LightClientStore`
|
|
|
|
```python
|
|
@dataclass
|
|
class LightClientStore(object):
|
|
snapshot: LightClientSnapshot
|
|
valid_updates: Set[LightClientUpdate]
|
|
```
|
|
|
|
## Helper functions
|
|
|
|
### `get_subtree_index`
|
|
|
|
```python
|
|
def get_subtree_index(generalized_index: GeneralizedIndex) -> uint64:
|
|
return uint64(generalized_index % 2**(floorlog2(generalized_index)))
|
|
```
|
|
|
|
## Light client state updates
|
|
|
|
A light client maintains its state in a `store` object of type `LightClientStore` and receives `update` objects of type `LightClientUpdate`. Every `update` triggers `process_light_client_update(store, update, current_slot)` where `current_slot` is the current slot based on some local clock.
|
|
|
|
#### `validate_light_client_update`
|
|
|
|
```python
|
|
def validate_light_client_update(snapshot: LightClientSnapshot,
|
|
update: LightClientUpdate,
|
|
genesis_validators_root: Root) -> None:
|
|
# Verify update slot is larger than snapshot slot
|
|
assert update.header.slot > snapshot.header.slot
|
|
|
|
# Verify update does not skip a sync committee period
|
|
snapshot_period = compute_epoch_at_slot(snapshot.header.slot) // EPOCHS_PER_SYNC_COMMITTEE_PERIOD
|
|
update_period = compute_epoch_at_slot(update.header.slot) // EPOCHS_PER_SYNC_COMMITTEE_PERIOD
|
|
assert update_period in (snapshot_period, snapshot_period + 1)
|
|
|
|
# Verify update header root is the finalized root of the finality header, if specified
|
|
if update.finality_header == BeaconBlockHeader():
|
|
signed_header = update.header
|
|
assert update.finality_branch == [Bytes32() for _ in range(floorlog2(FINALIZED_ROOT_INDEX))]
|
|
else:
|
|
signed_header = update.finality_header
|
|
assert is_valid_merkle_branch(
|
|
leaf=hash_tree_root(update.header),
|
|
branch=update.finality_branch,
|
|
depth=floorlog2(FINALIZED_ROOT_INDEX),
|
|
index=get_subtree_index(FINALIZED_ROOT_INDEX),
|
|
root=update.finality_header.state_root,
|
|
)
|
|
|
|
# Verify update next sync committee if the update period incremented
|
|
if update_period == snapshot_period:
|
|
sync_committee = snapshot.current_sync_committee
|
|
assert update.next_sync_committee_branch == [Bytes32() for _ in range(floorlog2(NEXT_SYNC_COMMITTEE_INDEX))]
|
|
else:
|
|
sync_committee = snapshot.next_sync_committee
|
|
assert is_valid_merkle_branch(
|
|
leaf=hash_tree_root(update.next_sync_committee),
|
|
branch=update.next_sync_committee_branch,
|
|
depth=floorlog2(NEXT_SYNC_COMMITTEE_INDEX),
|
|
index=get_subtree_index(NEXT_SYNC_COMMITTEE_INDEX),
|
|
root=update.header.state_root,
|
|
)
|
|
|
|
# Verify sync committee has sufficient participants
|
|
assert sum(update.sync_committee_bits) >= MIN_SYNC_COMMITTEE_PARTICIPANTS
|
|
|
|
# Verify sync committee aggregate signature
|
|
participant_pubkeys = [pubkey for (bit, pubkey) in zip(update.sync_committee_bits, sync_committee.pubkeys) if bit]
|
|
domain = compute_domain(DOMAIN_SYNC_COMMITTEE, update.fork_version, genesis_validators_root)
|
|
signing_root = compute_signing_root(signed_header, domain)
|
|
assert bls.FastAggregateVerify(participant_pubkeys, signing_root, update.sync_committee_signature)
|
|
```
|
|
|
|
#### `apply_light_client_update`
|
|
|
|
```python
|
|
def apply_light_client_update(snapshot: LightClientSnapshot, update: LightClientUpdate) -> None:
|
|
snapshot_period = compute_epoch_at_slot(snapshot.header.slot) // EPOCHS_PER_SYNC_COMMITTEE_PERIOD
|
|
update_period = compute_epoch_at_slot(update.header.slot) // EPOCHS_PER_SYNC_COMMITTEE_PERIOD
|
|
if update_period == snapshot_period + 1:
|
|
snapshot.current_sync_committee = snapshot.next_sync_committee
|
|
snapshot.next_sync_committee = update.next_sync_committee
|
|
snapshot.header = update.header
|
|
```
|
|
|
|
#### `process_light_client_update`
|
|
|
|
```python
|
|
def process_light_client_update(store: LightClientStore, update: LightClientUpdate, current_slot: Slot,
|
|
genesis_validators_root: Root) -> None:
|
|
validate_light_client_update(store.snapshot, update, genesis_validators_root)
|
|
store.valid_updates.add(update)
|
|
|
|
update_timeout = SLOTS_PER_EPOCH * EPOCHS_PER_SYNC_COMMITTEE_PERIOD
|
|
if (
|
|
sum(update.sync_committee_bits) * 3 >= len(update.sync_committee_bits) * 2
|
|
and update.finality_header != BeaconBlockHeader()
|
|
):
|
|
# Apply update if (1) 2/3 quorum is reached and (2) we have a finality proof.
|
|
# Note that (2) means that the current light client design needs finality.
|
|
# It may be changed to re-organizable light client design. See the on-going issue eth2.0-specs#2182.
|
|
apply_light_client_update(store.snapshot, update)
|
|
store.valid_updates = set()
|
|
elif current_slot > store.snapshot.header.slot + update_timeout:
|
|
# Forced best update when the update timeout has elapsed
|
|
apply_light_client_update(store.snapshot,
|
|
max(store.valid_updates, key=lambda update: sum(update.sync_committee_bits)))
|
|
store.valid_updates = set()
|
|
```
|