From 78d336e28d9352a94259394bbc24d271332d41b8 Mon Sep 17 00:00:00 2001 From: Etan Kissling Date: Tue, 3 May 2022 14:21:07 +0200 Subject: [PATCH 1/2] Describe light client sync process Provides documentation about the process that a light client may use to sync a local `LightClientStore`. --- README.md | 2 +- setup.py | 1 + specs/altair/light-client/light-client.md | 37 ++++++++++++++++++++++ specs/altair/light-client/sync-protocol.md | 1 + 4 files changed, 40 insertions(+), 1 deletion(-) create mode 100644 specs/altair/light-client/light-client.md diff --git a/README.md b/README.md index 5e2a0b19f..3a4b2c8c5 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,7 @@ Features are researched and developed in parallel, and then consolidated into se | Seq. | Code Name | Fork Epoch | Specs | | - | - | - | - | | 0 | **Phase0** |`0` | | -| 1 | **Altair** | `74240` | | +| 1 | **Altair** | `74240` | | | 2 | **Bellatrix**
(["The Merge"](https://ethereum.org/en/upgrades/merge/)) | TBD | | ### In-development Specifications diff --git a/setup.py b/setup.py index c8f0cea0c..5a88f7969 100644 --- a/setup.py +++ b/setup.py @@ -934,6 +934,7 @@ class PySpecCommand(Command): if self.spec_fork in (ALTAIR, BELLATRIX, CAPELLA, EIP4844): self.md_doc_paths += """ specs/altair/light-client/full-node.md + specs/altair/light-client/light-client.md specs/altair/light-client/sync-protocol.md specs/altair/beacon-chain.md specs/altair/bls.md diff --git a/specs/altair/light-client/light-client.md b/specs/altair/light-client/light-client.md new file mode 100644 index 000000000..78c02e205 --- /dev/null +++ b/specs/altair/light-client/light-client.md @@ -0,0 +1,37 @@ +# Altair Light Client -- Light Client + +**Notice**: This document is a work-in-progress for researchers and implementers. + +## Table of contents + + + + + +- [Introduction](#introduction) +- [Light client sync process](#light-client-sync-process) + + + + +## Introduction + +This document explains how light clients MAY obtain light client data to sync with the network. + +## Light client sync process + +1. The light client MUST be configured out-of-band with a spec/preset (including fork schedule), with `genesis_state` (including `genesis_time` and `genesis_validators_root`), and with a trusted block root. The trusted block SHOULD be within the weak subjectivity period, and its root SHOULD be from a finalized `Checkpoint`. + +2. The local clock is initialized based on the configured `genesis_time`, and the current fork digest is determined to browse for and connect to relevant light client data providers. + +3. The light client fetches a [`LightClientBootstrap`](./sync-protocol.md#lightclientbootstrap) object for the configured trusted block root. The `bootstrap` object is passed to [`initialize_light_client_store`](./sync-protocol.md#initialize_light_client_store) to obtain a local [`LightClientStore`](./sync-protocol.md#lightclientstore). + +4. The light client tracks the sync committee periods `finalized_period` from `store.finalized_header.slot`, `optimistic_period` from `store.optimistic_header.slot`, and `current_period` from `current_slot` based on the local clock. + + 1. When `finalized_period == optimistic_period` and [`is_next_sync_committee_known`](./sync-protocol.md#is_next_sync_committee_known) indicates `False`, the light client fetches a [`LightClientUpdate`](./sync-protocol.md#lightclientupdate) for `finalized_period`. If `finalized_period == current_period`, this fetch SHOULD be scheduled at a random time before `current_period` advances. + + 2. When `finalized_period + 1 < current_period`, the light client fetches a `LightClientUpdate` for each sync committee period in range `[finalized_period + 1, current_period)` (current period excluded) + + 3. When `finalized_period + 1 >= current_period`, the light client keeps observing [`LightClientFinalityUpdate`](./sync-protocol.md#lightclientfinalityupdate) and [`LightClientOptimisticUpdate`](./sync-protocol.md#lightclientoptimisticupdate). Received objects are passed to [`process_light_client_finality_update`](./sync-protocol.md#process_light_client_finality_update) and [`process_light_client_optimistic_update`](./sync-protocol.md#process_light_client_optimistic_update). This ensures that `finalized_header` and `optimistic_header` reflect the latest blocks. + +5. [`process_light_client_store_force_update`](./sync-protocol.md#process_light_client_store_force_update) MAY be called based on use case dependent heuristics if light client sync appears stuck. If available, falling back to an alternative syncing mechanism to cover the affected sync committee period is preferred. diff --git a/specs/altair/light-client/sync-protocol.md b/specs/altair/light-client/sync-protocol.md index 2fda56fc3..e385b5e44 100644 --- a/specs/altair/light-client/sync-protocol.md +++ b/specs/altair/light-client/sync-protocol.md @@ -51,6 +51,7 @@ uses sync committees introduced in [this beacon chain extension](./beacon-chain. Additional documents describe how the light client sync protocol can be used: - [Full node](./full-node.md) +- [Light client](./light-client.md) ## Constants From 8ced2c3ae10db0029968b569bf46f9081cf2fc04 Mon Sep 17 00:00:00 2001 From: Etan Kissling Date: Fri, 22 Jul 2022 17:46:07 +0200 Subject: [PATCH 2/2] Remove newlines between items for visual consistency --- specs/altair/light-client/light-client.md | 7 ------- 1 file changed, 7 deletions(-) diff --git a/specs/altair/light-client/light-client.md b/specs/altair/light-client/light-client.md index 78c02e205..318950437 100644 --- a/specs/altair/light-client/light-client.md +++ b/specs/altair/light-client/light-client.md @@ -21,17 +21,10 @@ This document explains how light clients MAY obtain light client data to sync wi ## Light client sync process 1. The light client MUST be configured out-of-band with a spec/preset (including fork schedule), with `genesis_state` (including `genesis_time` and `genesis_validators_root`), and with a trusted block root. The trusted block SHOULD be within the weak subjectivity period, and its root SHOULD be from a finalized `Checkpoint`. - 2. The local clock is initialized based on the configured `genesis_time`, and the current fork digest is determined to browse for and connect to relevant light client data providers. - 3. The light client fetches a [`LightClientBootstrap`](./sync-protocol.md#lightclientbootstrap) object for the configured trusted block root. The `bootstrap` object is passed to [`initialize_light_client_store`](./sync-protocol.md#initialize_light_client_store) to obtain a local [`LightClientStore`](./sync-protocol.md#lightclientstore). - 4. The light client tracks the sync committee periods `finalized_period` from `store.finalized_header.slot`, `optimistic_period` from `store.optimistic_header.slot`, and `current_period` from `current_slot` based on the local clock. - 1. When `finalized_period == optimistic_period` and [`is_next_sync_committee_known`](./sync-protocol.md#is_next_sync_committee_known) indicates `False`, the light client fetches a [`LightClientUpdate`](./sync-protocol.md#lightclientupdate) for `finalized_period`. If `finalized_period == current_period`, this fetch SHOULD be scheduled at a random time before `current_period` advances. - 2. When `finalized_period + 1 < current_period`, the light client fetches a `LightClientUpdate` for each sync committee period in range `[finalized_period + 1, current_period)` (current period excluded) - 3. When `finalized_period + 1 >= current_period`, the light client keeps observing [`LightClientFinalityUpdate`](./sync-protocol.md#lightclientfinalityupdate) and [`LightClientOptimisticUpdate`](./sync-protocol.md#lightclientoptimisticupdate). Received objects are passed to [`process_light_client_finality_update`](./sync-protocol.md#process_light_client_finality_update) and [`process_light_client_optimistic_update`](./sync-protocol.md#process_light_client_optimistic_update). This ensures that `finalized_header` and `optimistic_header` reflect the latest blocks. - 5. [`process_light_client_store_force_update`](./sync-protocol.md#process_light_client_store_force_update) MAY be called based on use case dependent heuristics if light client sync appears stuck. If available, falling back to an alternative syncing mechanism to cover the affected sync committee period is preferred.