From 06d9fd8cd31c06eb49036283d04226877b12e21e Mon Sep 17 00:00:00 2001 From: Etan Kissling Date: Tue, 3 May 2022 12:15:04 +0200 Subject: [PATCH 1/2] Add `LightClient(Finality|Optimistic)Update` Introduces reduced `LightClientUpdate` structures to allow keeping track of the latest `finalized_header` and `optimistic_header`. This may also help in scheduling the next query for a full `LightClientUpdate` once sync committee finality has been reached. --- specs/altair/light-client/full-node.md | 30 +++++++++ specs/altair/light-client/sync-protocol.md | 71 +++++++++++++++++++++- 2 files changed, 100 insertions(+), 1 deletion(-) diff --git a/specs/altair/light-client/full-node.md b/specs/altair/light-client/full-node.md index a7dd551015..09810a0373 100644 --- a/specs/altair/light-client/full-node.md +++ b/specs/altair/light-client/full-node.md @@ -14,6 +14,8 @@ - [Deriving light client data](#deriving-light-client-data) - [`create_light_client_bootstrap`](#create_light_client_bootstrap) - [`create_light_client_update`](#create_light_client_update) + - [`create_light_client_finality_update`](#create_light_client_finality_update) + - [`create_light_client_optimistic_update`](#create_light_client_optimistic_update) @@ -133,3 +135,31 @@ Full nodes SHOULD provide the best derivable `LightClientUpdate` (according to ` - `LightClientUpdate` are assigned to sync committee periods based on their `attested_header.slot` - `LightClientUpdate` are only considered if `compute_sync_committee_period(compute_epoch_at_slot(update.attested_header.slot)) == compute_sync_committee_period(compute_epoch_at_slot(update.signature_slot))` - Only `LightClientUpdate` with `next_sync_committee` as selected by fork choice are provided, regardless of ranking by `is_better_update`. To uniquely identify a non-finalized sync committee fork, all of `period`, `current_sync_committee` and `next_sync_committee` need to be incorporated, as sync committees may reappear over time. + +### `create_light_client_finality_update` + +```python +def create_light_client_finality_update(update: LightClientUpdate) -> LightClientFinalityUpdate: + return LightClientFinalityUpdate( + attested_header=update.attested_header, + finalized_header=update.finalized_header, + finality_branch=update.finality_branch, + sync_aggregate=update.sync_aggregate, + signature_slot=update.signature_slot, + ) +``` + +Full nodes SHOULD provide the `LightClientFinalityUpdate` with the highest `attested_header.slot` (if multiple, highest `signature_slot`) as selected by fork choice, and SHOULD support a push mechanism to deliver new `LightClientFinalityUpdate` whenever `finalized_header` changes. + +### `create_light_client_optimistic_update` + +```python +def create_light_client_optimistic_update(update: LightClientUpdate) -> LightClientOptimisticUpdate: + return LightClientOptimisticUpdate( + attested_header=update.attested_header, + sync_aggregate=update.sync_aggregate, + signature_slot=update.signature_slot, + ) +``` + +Full nodes SHOULD provide the `LightClientOptimisticUpdate` with the highest `attested_header.slot` (if multiple, highest `signature_slot`) as selected by fork choice, and SHOULD support a push mechanism to deliver new `LightClientOptimisticUpdate` whenever `attested_header` changes. diff --git a/specs/altair/light-client/sync-protocol.md b/specs/altair/light-client/sync-protocol.md index 217171db18..08581fd889 100644 --- a/specs/altair/light-client/sync-protocol.md +++ b/specs/altair/light-client/sync-protocol.md @@ -15,6 +15,8 @@ - [Containers](#containers) - [`LightClientBootstrap`](#lightclientbootstrap) - [`LightClientUpdate`](#lightclientupdate) + - [`LightClientFinalityUpdate`](#lightclientfinalityupdate) + - [`LightClientOptimisticUpdate`](#lightclientoptimisticupdate) - [`LightClientStore`](#lightclientstore) - [Helper functions](#helper-functions) - [`is_sync_committee_update`](#is_sync_committee_update) @@ -31,6 +33,8 @@ - [`validate_light_client_update`](#validate_light_client_update) - [`apply_light_client_update`](#apply_light_client_update) - [`process_light_client_update`](#process_light_client_update) + - [`process_light_client_finality_update`](#process_light_client_finality_update) + - [`process_light_client_optimistic_update`](#process_light_client_optimistic_update) @@ -96,6 +100,33 @@ class LightClientUpdate(Container): signature_slot: Slot ``` +### `LightClientFinalityUpdate` + +```python +class LightClientFinalityUpdate(Container): + # The beacon block header that is attested to by the sync committee + attested_header: BeaconBlockHeader + # The finalized beacon block header attested to by Merkle branch + finalized_header: BeaconBlockHeader + finality_branch: Vector[Bytes32, floorlog2(FINALIZED_ROOT_INDEX)] + # Sync committee aggregate signature + sync_aggregate: SyncAggregate + # Slot at which the aggregate signature was created (untrusted) + signature_slot: Slot +``` + +### `LightClientOptimisticUpdate` + +```python +class LightClientOptimisticUpdate(Container): + # The beacon block header that is attested to by the sync committee + attested_header: BeaconBlockHeader + # Sync committee aggregate signature + sync_aggregate: SyncAggregate + # Slot at which the aggregate signature was created (untrusted) + signature_slot: Slot +``` + ### `LightClientStore` ```python @@ -250,7 +281,7 @@ def initialize_light_client_store(trusted_block_root: Root, ## Light client state updates -A light client receives `update` objects of type `LightClientUpdate`. Every `update` triggers `process_light_client_update(store, update, current_slot, genesis_validators_root)` where `current_slot` is the current slot based on a local clock. `process_slot_for_light_client_store` is triggered every time the current slot increments. +A light client receives `update`, `finality_update` and `optimistic_update` objects of type `LightClientUpdate`, `LightClientFinalityUpdate` and `LightClientOptimisticUpdate`. Every `update` triggers `process_light_client_update(store, update, current_slot, genesis_validators_root)` where `current_slot` is the current slot based on a local clock. Likewise, every `finality_update` triggers `process_light_client_finality_update`, and every `optimistic_update` triggers `process_light_client_optimistic_update`. `process_slot_for_light_client_store` is triggered every time the current slot increments. ### `process_slot_for_light_client_store` @@ -420,3 +451,41 @@ def process_light_client_update(store: LightClientStore, apply_light_client_update(store, update) store.best_valid_update = None ``` + +### `process_light_client_finality_update` + +```python +def process_light_client_finality_update(store: LightClientStore, + finality_update: LightClientFinalityUpdate, + current_slot: Slot, + genesis_validators_root: Root) -> None: + update = LightClientUpdate( + attested_header=finality_update.attested_header, + next_sync_committee=SyncCommittee(), + next_sync_committee_branch=[Bytes32() for _ in range(floorlog2(NEXT_SYNC_COMMITTEE_INDEX))], + finalized_header=finality_update.finalized_header, + finality_branch=finality_update.finality_branch, + sync_aggregate=finality_update.sync_aggregate, + signature_slot=finality_update.signature_slot, + ) + process_light_client_update(store, update, current_slot, genesis_validators_root) +``` + +### `process_light_client_optimistic_update` + +```python +def process_light_client_optimistic_update(store: LightClientStore, + optimistic_update: LightClientOptimisticUpdate, + current_slot: Slot, + genesis_validators_root: Root) -> None: + update = LightClientUpdate( + attested_header=optimistic_update.attested_header, + next_sync_committee=SyncCommittee(), + next_sync_committee_branch=[Bytes32() for _ in range(floorlog2(NEXT_SYNC_COMMITTEE_INDEX))], + finalized_header=BeaconBlockHeader(), + finality_branch=[Bytes32() for _ in range(floorlog2(FINALIZED_ROOT_INDEX))], + sync_aggregate=optimistic_update.sync_aggregate, + signature_slot=optimistic_update.signature_slot, + ) + process_light_client_update(store, update, current_slot, genesis_validators_root) +``` From 95019bb9a997e7fd4276d4370cd27f0f1a69fa68 Mon Sep 17 00:00:00 2001 From: Etan Kissling Date: Wed, 20 Jul 2022 17:50:18 +0200 Subject: [PATCH 2/2] Improve readability of intro text Co-authored-by: Hsiao-Wei Wang --- specs/altair/light-client/sync-protocol.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/specs/altair/light-client/sync-protocol.md b/specs/altair/light-client/sync-protocol.md index 08581fd889..627049a43f 100644 --- a/specs/altair/light-client/sync-protocol.md +++ b/specs/altair/light-client/sync-protocol.md @@ -281,7 +281,11 @@ def initialize_light_client_store(trusted_block_root: Root, ## Light client state updates -A light client receives `update`, `finality_update` and `optimistic_update` objects of type `LightClientUpdate`, `LightClientFinalityUpdate` and `LightClientOptimisticUpdate`. Every `update` triggers `process_light_client_update(store, update, current_slot, genesis_validators_root)` where `current_slot` is the current slot based on a local clock. Likewise, every `finality_update` triggers `process_light_client_finality_update`, and every `optimistic_update` triggers `process_light_client_optimistic_update`. `process_slot_for_light_client_store` is triggered every time the current slot increments. +- A light client receives objects of type `LightClientUpdate`, `LightClientFinalityUpdate` and `LightClientOptimisticUpdate`: + - **`update: LightClientUpdate`**: Every `update` triggers `process_light_client_update(store, update, current_slot, genesis_validators_root)` where `current_slot` is the current slot based on a local clock. + - **`finality_update: LightClientFinalityUpdate`**: Every `finality_update` triggers `process_light_client_finality_update(store, finality_update, current_slot, genesis_validators_root)`. + - **`optimistic_update: LightClientOptimisticUpdate`**: Every `optimistic_update` triggers `process_light_client_optimistic_update(store, optimistic_update, current_slot, genesis_validators_root)`. +- `process_slot_for_light_client_store` is triggered every time the current slot increments. ### `process_slot_for_light_client_store`