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