Altair Light Client -- Light Client¶
Notice: This document is a work-in-progress for researchers and implementers.
Table of contents¶
Introduction¶
This document explains how light clients MAY obtain light client data to sync with the network.
Light client sync process¶
- The light client MUST be configured out-of-band with a spec/preset (including fork schedule), with
genesis_state
(includinggenesis_time
andgenesis_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 finalizedCheckpoint
. - 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. - The light client fetches a
LightClientBootstrap
object for the configured trusted block root. Thebootstrap
object is passed toinitialize_light_client_store
to obtain a localLightClientStore
. - The light client tracks the sync committee periods
finalized_period
fromstore.finalized_header.beacon.slot
,optimistic_period
fromstore.optimistic_header.beacon.slot
, andcurrent_period
fromcurrent_slot
based on the local clock. - When
finalized_period == optimistic_period
andis_next_sync_committee_known
indicatesFalse
, the light client fetches aLightClientUpdate
forfinalized_period
. Iffinalized_period == current_period
, this fetch SHOULD be scheduled at a random time beforecurrent_period
advances. - When
finalized_period + 1 < current_period
, the light client fetches aLightClientUpdate
for each sync committee period in range[finalized_period + 1, current_period)
(current period excluded) - When
finalized_period + 1 >= current_period
, the light client keeps observingLightClientFinalityUpdate
andLightClientOptimisticUpdate
. Received objects are passed toprocess_light_client_finality_update
andprocess_light_client_optimistic_update
. This ensures thatfinalized_header
andoptimistic_header
reflect the latest blocks. 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.