# beacon chain light client design doc The following document contains notes about the design/implementation of a beacon chain light client using standard APIs and protocol features as of the recent Altair hard fork of the beacon chain. I'll call this type of light client "stage 0" to differentiate it from later "stages" that use more advanced networking constructs supporting the light client ecosystem. ## supporting material The primary outcome of a "stage 0" light client is software that can execute the sync protocol defined here: https://github.com/ethereum/consensus-specs/blob/dev/specs/altair/sync-protocol.md A node implementing this protocol can sync to the finalized head of the beacon chain with minimal trust assumptions. The rest of this document assumes familiarity with concepts, definitions, etc. in the sync protocol document. ## "stage 0" design We assume a basic server/client architecture with two components: 1) light client server 2) light client ### light client server The server component leverages a "full" beacon node. The "full" node maintains the beacon chain implementing the block processing and fork choice facilities to provide the chain abstraction to consumers. A natural implementation of this role will be a server using the [standard beacon node HTTP APIs](https://github.com/ethereum/beacon-APIs) to manufacture `LightClientUpdate`s as defined in the sync protocol document. This server will expose its own HTTP APIs that conforming light clients can leverage to receive these updates. At a high-level, the light client server should for each `block` build a `LightClientUpdate`: - includes the header of this `block` - provide `next_sync_committee` data if the light client requests it - if a new block has been finalized, provide the additional "update" header along w/ the "finality" header - include the `SyncAggregate` information from this `block` - include the corresponding `fork_version` Note that unless a new block has been finalized, the `LightClientUpdate` includes each new root the sync committee has signed off on under the `LightClientUpdate.header`. If a new block *has* been finalized, the light client server can provide this information trustlessly by including the (recently) signed header as the `LightClientUpdate.finality_header` and the header that _was_ finalized as the `LightClientUpdate.header`. ### light client The light client component connects to a light client server to receive `LightClientUpdate`s. This role implements the spec in the sync protocol document to provide users of a light client with a recent snapshot of the network as defined by the `LightClientSnapshot` type. At a high-level, the light client should poll a light client server once per slot to get a `LightClientUpdate` which should be processed according to the sync protocol spec. ## bootstrapping aside from the "steady state" operation outlined above, each role needs some initial information to begin. ## bootstrapping a light client server rough steps to bootstrap a light client server: - use configuration to determine the current slot, epoch, and sync committee period - determine the current fork version (for signature verification) * /eth/v1/config/fork_schedule - determine the sync committees * /eth/v1/beacon/states/{state_id}/sync_committees * note: the server will need to query the attached beacon node for the next sync committee when it is known. ## bootstrapping a light client - needs trusted `LightClientSnapshot`