@lodestar/light-client 1.35.0-dev.f80d2d52da → 1.35.0-dev.fcf8d024ea

package/src/index.ts

@@ -0,0 +1,340 @@
+import mitt from "mitt";
+import {BeaconConfig, ChainForkConfig, createBeaconConfig} from "@lodestar/config";
+import {EPOCHS_PER_SYNC_COMMITTEE_PERIOD} from "@lodestar/params";
+import {
+  LightClientBootstrap,
+  LightClientFinalityUpdate,
+  LightClientHeader,
+  LightClientOptimisticUpdate,
+  LightClientUpdate,
+  RootHex,
+  Slot,
+  SyncPeriod,
+  phase0,
+} from "@lodestar/types";
+import {fromHex, isErrorAborted, sleep, toRootHex} from "@lodestar/utils";
+import {LightclientEmitter, LightclientEvent} from "./events.js";
+import {LightclientSpec} from "./spec/index.js";
+import {ProcessUpdateOpts} from "./spec/processLightClientUpdate.js";
+import {validateLightClientBootstrap} from "./spec/validateLightClientBootstrap.js";
+import {LightClientTransport} from "./transport/interface.js";
+import {chunkifyInclusiveRange} from "./utils/chunkify.js";
+import {
+  computeEpochAtSlot,
+  computeSyncPeriodAtEpoch,
+  computeSyncPeriodAtSlot,
+  getCurrentSlot,
+  slotWithFutureTolerance,
+  timeUntilNextEpoch,
+} from "./utils/clock.js";
+import {ILcLogger, getConsoleLogger} from "./utils/logger.js";
+
+// Re-export types
+export {LightclientEvent} from "./events.js";
+export {upgradeLightClientFinalityUpdate, upgradeLightClientOptimisticUpdate} from "./spec/utils.js";
+export type {SyncCommitteeFast} from "./types.js";
+
+export type GenesisData = {
+  genesisTime: number;
+  genesisValidatorsRoot: RootHex | Uint8Array;
+};
+
+export type LightclientOpts = ProcessUpdateOpts;
+
+export type LightclientInitArgs = {
+  config: ChainForkConfig;
+  logger?: ILcLogger;
+  opts?: LightclientOpts;
+  genesisData: GenesisData;
+  transport: LightClientTransport;
+  bootstrap: LightClientBootstrap;
+};
+
+/** Provides some protection against a server client sending header updates too far away in the future */
+const MAX_CLOCK_DISPARITY_SEC = 10;
+/** Prevent responses that are too big and get truncated. No specific reasoning for 32 */
+const MAX_PERIODS_PER_REQUEST = 32;
+/** For mainnet preset 8 epochs, for minimal preset `EPOCHS_PER_SYNC_COMMITTEE_PERIOD / 2` */
+const LOOKAHEAD_EPOCHS_COMMITTEE_SYNC = Math.min(8, Math.ceil(EPOCHS_PER_SYNC_COMMITTEE_PERIOD / 2));
+/** Prevent infinite loops caused by sync errors */
+const ON_ERROR_RETRY_MS = 1000;
+
+// TODO: Customize with option
+const ALLOW_FORCED_UPDATES = true;
+
+export enum RunStatusCode {
+  uninitialized,
+  started,
+  syncing,
+  stopped,
+}
+type RunStatus =
+  | {code: RunStatusCode.uninitialized}
+  | {code: RunStatusCode.started; controller: AbortController}
+  | {code: RunStatusCode.syncing}
+  | {code: RunStatusCode.stopped};
+
+/**
+ * Server-based Lightclient. Current architecture diverges from the spec's proposed updated splitting them into:
+ * - Sync period updates: To advance to the next sync committee
+ * - Header updates: To get a more recent header signed by a known sync committee
+ *
+ * To stay synced to the current sync period it needs:
+ * - GET lightclient/committee_updates at least once per period.
+ *
+ * To get continuous header updates:
+ * - subscribe to SSE type lightclient_update
+ *
+ * To initialize, it needs:
+ * - GenesisData: To initialize the clock and verify signatures
+ *   - For known networks it's hardcoded in the source
+ *   - For unknown networks it can be provided by the user with a manual input
+ *   - For unknown test networks it can be queried from a trusted node at GET beacon/genesis
+ * - `beaconApiUrl`: To connect to a trustless beacon node
+ * - `LightclientStore`: To have an initial trusted SyncCommittee to start the sync
+ *   - For new lightclient instances, it can be queries from a trustless node at GET lightclient/bootstrap
+ *   - For existing lightclient instances, it should be retrieved from storage
+ *
+ * When to trigger a committee update sync:
+ *
+ *  period 0         period 1         period 2
+ * -|----------------|----------------|----------------|-> time
+ *              | now
+ *               - active current_sync_committee
+ *               - known next_sync_committee, signed by current_sync_committee
+ *
+ * - No need to query for period 0 next_sync_committee until the end of period 0
+ * - During most of period 0, current_sync_committee known, next_sync_committee unknown
+ * - At the end of period 0, get a sync committee update, and populate period 1's committee
+ *
+ * syncCommittees: Map<SyncPeriod, SyncCommittee>, limited to max of 2 items
+ */
+export class Lightclient {
+  readonly emitter: LightclientEmitter = mitt();
+  readonly config: BeaconConfig;
+  readonly logger: ILcLogger;
+  readonly genesisValidatorsRoot: Uint8Array;
+  readonly genesisTime: number;
+  private readonly transport: LightClientTransport;
+
+  private readonly lightclientSpec: LightclientSpec;
+
+  private runStatus: RunStatus = {code: RunStatusCode.stopped};
+
+  constructor({config, logger, genesisData, bootstrap, transport}: LightclientInitArgs) {
+    this.genesisTime = genesisData.genesisTime;
+    this.genesisValidatorsRoot =
+      typeof genesisData.genesisValidatorsRoot === "string"
+        ? fromHex(genesisData.genesisValidatorsRoot)
+        : genesisData.genesisValidatorsRoot;
+
+    this.config = createBeaconConfig(config, this.genesisValidatorsRoot);
+    this.logger = logger ?? getConsoleLogger();
+    this.transport = transport;
+    this.runStatus = {code: RunStatusCode.uninitialized};
+
+    this.lightclientSpec = new LightclientSpec(
+      this.config,
+      {
+        allowForcedUpdates: ALLOW_FORCED_UPDATES,
+        onSetFinalizedHeader: (header) => {
+          this.emitter.emit(LightclientEvent.lightClientFinalityHeader, header);
+          this.logger.debug("Updated state.finalizedHeader", {slot: header.beacon.slot});
+        },
+        onSetOptimisticHeader: (header) => {
+          this.emitter.emit(LightclientEvent.lightClientOptimisticHeader, header);
+          this.logger.debug("Updated state.optimisticHeader", {slot: header.beacon.slot});
+        },
+      },
+      bootstrap
+    );
+  }
+
+  get status(): RunStatusCode {
+    return this.runStatus.code;
+  }
+
+  // Embed lightweight clock. The epoch cycles are handled with `this.runLoop()`
+  get currentSlot(): number {
+    return getCurrentSlot(this.config, this.genesisTime);
+  }
+
+  static async initializeFromCheckpointRoot(
+    args: Omit<LightclientInitArgs, "bootstrap"> & {
+      checkpointRoot: phase0.Checkpoint["root"];
+    }
+  ): Promise<Lightclient> {
+    const {transport, checkpointRoot} = args;
+
+    // Fetch bootstrap state with proof at the trusted block root
+    const {data: bootstrap} = await transport.getBootstrap(toRootHex(checkpointRoot));
+
+    validateLightClientBootstrap(args.config, checkpointRoot, bootstrap);
+
+    return new Lightclient({...args, bootstrap});
+  }
+
+  /**
+   * @returns a `Promise` that will resolve once `runStatus` equals `RunStatusCode.started`
+   */
+  start(): Promise<void> {
+    const startPromise = new Promise<void>((resolve) => {
+      const resolveAndStopListening = (status: RunStatusCode): void => {
+        if (status === RunStatusCode.started) {
+          this.emitter.off(LightclientEvent.statusChange, resolveAndStopListening);
+          resolve();
+        }
+      };
+      this.emitter.on(LightclientEvent.statusChange, resolveAndStopListening);
+
+      // If already started, resolve immediately
+      // Checking after the event registration to remove potential for race conditions
+      resolveAndStopListening(this.runStatus.code);
+    });
+
+    // Do not block the event loop
+    void this.runLoop();
+
+    return startPromise;
+  }
+
+  stop(): void {
+    if (this.runStatus.code !== RunStatusCode.started) return;
+
+    this.runStatus.controller.abort();
+    this.updateRunStatus({code: RunStatusCode.stopped});
+  }
+
+  getHead(): LightClientHeader {
+    return this.lightclientSpec.store.optimisticHeader;
+  }
+
+  getFinalized(): LightClientHeader {
+    return this.lightclientSpec.store.finalizedHeader;
+  }
+
+  async sync(fromPeriod: SyncPeriod, toPeriod: SyncPeriod): Promise<void> {
+    const periodRanges = chunkifyInclusiveRange(fromPeriod, toPeriod, MAX_PERIODS_PER_REQUEST);
+
+    for (const [fromPeriodRng, toPeriodRng] of periodRanges) {
+      const count = toPeriodRng + 1 - fromPeriodRng;
+      const updates = await this.transport.getUpdates(fromPeriodRng, count);
+      for (const update of updates) {
+        this.processSyncCommitteeUpdate(update.data);
+        this.logger.debug("processed sync update", {slot: update.data.attestedHeader.beacon.slot});
+
+        // Yield to the macro queue, verifying updates is somewhat expensive and we want responsiveness
+        await new Promise((r) => setTimeout(r, 0));
+      }
+    }
+  }
+
+  private async runLoop(): Promise<void> {
+    while (true) {
+      const currentPeriod = computeSyncPeriodAtSlot(this.currentSlot);
+      // Check if we have a sync committee for the current clock period
+      if (!this.lightclientSpec.store.syncCommittees.has(currentPeriod)) {
+        // Stop head tracking
+        if (this.runStatus.code === RunStatusCode.started) {
+          this.runStatus.controller.abort();
+        }
+
+        // Go into sync mode
+        this.updateRunStatus({code: RunStatusCode.syncing});
+        const headPeriod = computeSyncPeriodAtSlot(this.getHead().beacon.slot);
+        this.logger.debug("Syncing", {lastPeriod: headPeriod, currentPeriod});
+
+        try {
+          await this.sync(headPeriod, currentPeriod);
+          this.logger.debug("Synced", {currentPeriod});
+        } catch (e) {
+          this.logger.error("Error sync", {}, e as Error);
+
+          // Retry in 1 second
+          await new Promise((r) => setTimeout(r, ON_ERROR_RETRY_MS));
+          continue;
+        }
+      }
+
+      // After successfully syncing, track head if not already
+      if (this.runStatus.code !== RunStatusCode.started) {
+        const controller = new AbortController();
+        this.updateRunStatus({code: RunStatusCode.started, controller});
+        this.logger.debug("Started tracking the head");
+
+        // Fetch latest optimistic head to prevent a potential 12 seconds lag between syncing and getting the first head,
+        // Don't retry, this is a non-critical UX improvement
+        try {
+          const update = await this.transport.getOptimisticUpdate();
+          this.processOptimisticUpdate(update.data);
+        } catch (e) {
+          this.logger.error("Error fetching getLatestHeadUpdate", {currentPeriod}, e as Error);
+        }
+
+        this.transport.onOptimisticUpdate(this.processOptimisticUpdate.bind(this));
+        this.transport.onFinalityUpdate(this.processFinalizedUpdate.bind(this));
+      }
+
+      // When close to the end of a sync period poll for sync committee updates
+      // Limit lookahead in case EPOCHS_PER_SYNC_COMMITTEE_PERIOD is configured to be very short
+
+      const currentEpoch = computeEpochAtSlot(this.currentSlot);
+      const epochsIntoPeriod = currentEpoch % EPOCHS_PER_SYNC_COMMITTEE_PERIOD;
+      // Start fetching updates with some lookahead
+      if (EPOCHS_PER_SYNC_COMMITTEE_PERIOD - epochsIntoPeriod <= LOOKAHEAD_EPOCHS_COMMITTEE_SYNC) {
+        const period = computeSyncPeriodAtEpoch(currentEpoch);
+        try {
+          await this.sync(period, period);
+        } catch (e) {
+          this.logger.error("Error re-syncing period", {period}, e as Error);
+        }
+      }
+
+      // Wait for the next epoch
+      try {
+        const runStatus = this.runStatus as {code: RunStatusCode.started; controller: AbortController}; // At this point, client is started
+        await sleep(timeUntilNextEpoch(this.config, this.genesisTime), runStatus.controller.signal);
+      } catch (e) {
+        if (isErrorAborted(e)) {
+          return;
+        }
+        throw e;
+      }
+    }
+  }
+
+  /**
+   * Processes new optimistic header updates in only known synced sync periods.
+   * This headerUpdate may update the head if there's enough participation.
+   */
+  private processOptimisticUpdate(optimisticUpdate: LightClientOptimisticUpdate): void {
+    this.lightclientSpec.onOptimisticUpdate(this.currentSlotWithTolerance(), optimisticUpdate);
+  }
+
+  /**
+   * Processes new header updates in only known synced sync periods.
+   * This headerUpdate may update the head if there's enough participation.
+   */
+  private processFinalizedUpdate(finalizedUpdate: LightClientFinalityUpdate): void {
+    this.lightclientSpec.onFinalityUpdate(this.currentSlotWithTolerance(), finalizedUpdate);
+  }
+
+  private processSyncCommitteeUpdate(update: LightClientUpdate): void {
+    this.lightclientSpec.onUpdate(this.currentSlotWithTolerance(), update);
+  }
+
+  private currentSlotWithTolerance(): Slot {
+    return slotWithFutureTolerance(this.config, this.genesisTime, MAX_CLOCK_DISPARITY_SEC);
+  }
+
+  private updateRunStatus(runStatus: RunStatus): void {
+    this.runStatus = runStatus;
+    this.emitter.emit(LightclientEvent.statusChange, this.runStatus.code);
+  }
+}
+
+import * as transport from "./transport.js";
+// To export these name spaces to the bundle JS
+import * as utils from "./utils.js";
+import * as validation from "./validation.js";
+export {utils, validation, transport};

package/src/spec/index.ts

@@ -0,0 +1,71 @@
+import {BeaconConfig} from "@lodestar/config";
+import {UPDATE_TIMEOUT} from "@lodestar/params";
+import {
+  LightClientBootstrap,
+  LightClientFinalityUpdate,
+  LightClientOptimisticUpdate,
+  LightClientUpdate,
+  Slot,
+} from "@lodestar/types";
+import {computeSyncPeriodAtSlot} from "../utils/index.js";
+import {ProcessUpdateOpts, getSyncCommitteeAtPeriod, processLightClientUpdate} from "./processLightClientUpdate.js";
+import {ILightClientStore, LightClientStore, LightClientStoreEvents} from "./store.js";
+import {ZERO_HEADER, ZERO_SYNC_COMMITTEE, getZeroFinalityBranch, getZeroSyncCommitteeBranch} from "./utils.js";
+
+export type {LightClientUpdateSummary} from "./isBetterUpdate.js";
+export {isBetterUpdate, toLightClientUpdateSummary} from "./isBetterUpdate.js";
+export {upgradeLightClientHeader} from "./utils.js";
+
+export class LightclientSpec {
+  readonly store: ILightClientStore;
+  readonly config: BeaconConfig;
+
+  constructor(
+    config: BeaconConfig,
+    private readonly opts: ProcessUpdateOpts & LightClientStoreEvents,
+    bootstrap: LightClientBootstrap
+  ) {
+    this.store = new LightClientStore(config, bootstrap, opts);
+    this.config = config;
+  }
+
+  onUpdate(currentSlot: Slot, update: LightClientUpdate): void {
+    processLightClientUpdate(this.config, this.store, currentSlot, this.opts, update);
+  }
+
+  onFinalityUpdate(currentSlot: Slot, finalityUpdate: LightClientFinalityUpdate): void {
+    this.onUpdate(currentSlot, {
+      attestedHeader: finalityUpdate.attestedHeader,
+      nextSyncCommittee: ZERO_SYNC_COMMITTEE,
+      nextSyncCommitteeBranch: getZeroSyncCommitteeBranch(this.config.getForkName(finalityUpdate.signatureSlot)),
+      finalizedHeader: finalityUpdate.finalizedHeader,
+      finalityBranch: finalityUpdate.finalityBranch,
+      syncAggregate: finalityUpdate.syncAggregate,
+      signatureSlot: finalityUpdate.signatureSlot,
+    });
+  }
+
+  onOptimisticUpdate(currentSlot: Slot, optimisticUpdate: LightClientOptimisticUpdate): void {
+    this.onUpdate(currentSlot, {
+      attestedHeader: optimisticUpdate.attestedHeader,
+      nextSyncCommittee: ZERO_SYNC_COMMITTEE,
+      nextSyncCommitteeBranch: getZeroSyncCommitteeBranch(this.config.getForkName(optimisticUpdate.signatureSlot)),
+      finalizedHeader: {beacon: ZERO_HEADER},
+      finalityBranch: getZeroFinalityBranch(this.config.getForkName(optimisticUpdate.signatureSlot)),
+      syncAggregate: optimisticUpdate.syncAggregate,
+      signatureSlot: optimisticUpdate.signatureSlot,
+    });
+  }
+
+  forceUpdate(currentSlot: Slot): void {
+    for (const bestValidUpdate of this.store.bestValidUpdates.values()) {
+      if (currentSlot > bestValidUpdate.update.finalizedHeader.beacon.slot + UPDATE_TIMEOUT) {
+        const updatePeriod = computeSyncPeriodAtSlot(bestValidUpdate.update.signatureSlot);
+        // Simulate process_light_client_store_force_update() by forcing to apply a bestValidUpdate
+        // https://github.com/ethereum/consensus-specs/blob/a57e15636013eeba3610ff3ade41781dba1bb0cd/specs/altair/light-client/sync-protocol.md?plain=1#L394
+        // Call for `updatePeriod + 1` to force the update at `update.signatureSlot` to be applied
+        getSyncCommitteeAtPeriod(this.store, updatePeriod + 1, this.opts);
+      }
+    }
+  }
+}

package/src/spec/isBetterUpdate.ts

@@ -0,0 +1,94 @@
+import {SYNC_COMMITTEE_SIZE} from "@lodestar/params";
+import {LightClientUpdate, Slot} from "@lodestar/types";
+import {computeSyncPeriodAtSlot} from "../utils/index.js";
+import {isFinalityUpdate, isSyncCommitteeUpdate, sumBits} from "./utils.js";
+
+/**
+ * Wrapper type for `isBetterUpdate()` so we can apply its logic without requiring the full LightClientUpdate type.
+ */
+export type LightClientUpdateSummary = {
+  activeParticipants: number;
+  attestedHeaderSlot: Slot;
+  signatureSlot: Slot;
+  finalizedHeaderSlot: Slot;
+  /** `if update.next_sync_committee_branch != [Bytes32() for _ in range(floorlog2(NEXT_SYNC_COMMITTEE_INDEX))]` */
+  isSyncCommitteeUpdate: boolean;
+  /** `if update.finality_branch != [Bytes32() for _ in range(floorlog2(FINALIZED_ROOT_INDEX))]` */
+  isFinalityUpdate: boolean;
+};
+
+/**
+ * Returns the update with more bits. On ties, prevUpdate is the better
+ *
+ * https://github.com/ethereum/consensus-specs/blob/be3c774069e16e89145660be511c1b183056017e/specs/altair/light-client/sync-protocol.md#is_better_update
+ */
+export function isBetterUpdate(newUpdate: LightClientUpdateSummary, oldUpdate: LightClientUpdateSummary): boolean {
+  // Compare supermajority (> 2/3) sync committee participation
+  const newNumActiveParticipants = newUpdate.activeParticipants;
+  const oldNumActiveParticipants = oldUpdate.activeParticipants;
+  const newHasSupermajority = newNumActiveParticipants * 3 >= SYNC_COMMITTEE_SIZE * 2;
+  const oldHasSupermajority = oldNumActiveParticipants * 3 >= SYNC_COMMITTEE_SIZE * 2;
+  if (newHasSupermajority !== oldHasSupermajority) {
+    return newHasSupermajority;
+  }
+  if (!newHasSupermajority && newNumActiveParticipants !== oldNumActiveParticipants) {
+    return newNumActiveParticipants > oldNumActiveParticipants;
+  }
+
+  // Compare presence of relevant sync committee
+  const newHasRelevantSyncCommittee =
+    newUpdate.isSyncCommitteeUpdate &&
+    computeSyncPeriodAtSlot(newUpdate.attestedHeaderSlot) === computeSyncPeriodAtSlot(newUpdate.signatureSlot);
+  const oldHasRelevantSyncCommittee =
+    oldUpdate.isSyncCommitteeUpdate &&
+    computeSyncPeriodAtSlot(oldUpdate.attestedHeaderSlot) === computeSyncPeriodAtSlot(oldUpdate.signatureSlot);
+  if (newHasRelevantSyncCommittee !== oldHasRelevantSyncCommittee) {
+    return newHasRelevantSyncCommittee;
+  }
+
+  // Compare indication of any finality
+  const newHasFinality = newUpdate.isFinalityUpdate;
+  const oldHasFinality = oldUpdate.isFinalityUpdate;
+  if (newHasFinality !== oldHasFinality) {
+    return newHasFinality;
+  }
+
+  // Compare sync committee finality
+  if (newHasFinality) {
+    const newHasSyncCommitteeFinality =
+      computeSyncPeriodAtSlot(newUpdate.finalizedHeaderSlot) === computeSyncPeriodAtSlot(newUpdate.attestedHeaderSlot);
+    const oldHasSyncCommitteeFinality =
+      computeSyncPeriodAtSlot(oldUpdate.finalizedHeaderSlot) === computeSyncPeriodAtSlot(oldUpdate.attestedHeaderSlot);
+    if (newHasSyncCommitteeFinality !== oldHasSyncCommitteeFinality) {
+      return newHasSyncCommitteeFinality;
+    }
+  }
+
+  // Tiebreaker 1: Sync committee participation beyond supermajority
+  if (newNumActiveParticipants !== oldNumActiveParticipants) {
+    return newNumActiveParticipants > oldNumActiveParticipants;
+  }
+
+  // Tiebreaker 2: Prefer older data (fewer changes to best)
+  if (newUpdate.attestedHeaderSlot !== oldUpdate.attestedHeaderSlot) {
+    return newUpdate.attestedHeaderSlot < oldUpdate.attestedHeaderSlot;
+  }
+  return newUpdate.signatureSlot < oldUpdate.signatureSlot;
+}
+
+export function isSafeLightClientUpdate(update: LightClientUpdateSummary): boolean {
+  return (
+    update.activeParticipants * 3 >= SYNC_COMMITTEE_SIZE * 2 && update.isFinalityUpdate && update.isSyncCommitteeUpdate
+  );
+}
+
+export function toLightClientUpdateSummary(update: LightClientUpdate): LightClientUpdateSummary {
+  return {
+    activeParticipants: sumBits(update.syncAggregate.syncCommitteeBits),
+    attestedHeaderSlot: update.attestedHeader.beacon.slot,
+    signatureSlot: update.signatureSlot,
+    finalizedHeaderSlot: update.finalizedHeader.beacon.slot,
+    isSyncCommitteeUpdate: isSyncCommitteeUpdate(update),
+    isFinalityUpdate: isFinalityUpdate(update),
+  };
+}

package/src/spec/processLightClientUpdate.ts

@@ -0,0 +1,119 @@
+import {ChainForkConfig} from "@lodestar/config";
+import {SYNC_COMMITTEE_SIZE} from "@lodestar/params";
+import {LightClientUpdate, Slot, SyncPeriod} from "@lodestar/types";
+import {pruneSetToMax} from "@lodestar/utils";
+import {computeSyncPeriodAtSlot, deserializeSyncCommittee, sumBits} from "../utils/index.js";
+import {LightClientUpdateSummary, isBetterUpdate, toLightClientUpdateSummary} from "./isBetterUpdate.js";
+import {ILightClientStore, MAX_SYNC_PERIODS_CACHE, SyncCommitteeFast} from "./store.js";
+import {getSafetyThreshold, isSyncCommitteeUpdate} from "./utils.js";
+import {validateLightClientUpdate} from "./validateLightClientUpdate.js";
+
+export interface ProcessUpdateOpts {
+  allowForcedUpdates?: boolean;
+  updateHeadersOnForcedUpdate?: boolean;
+}
+
+export function processLightClientUpdate(
+  config: ChainForkConfig,
+  store: ILightClientStore,
+  currentSlot: Slot,
+  opts: ProcessUpdateOpts,
+  update: LightClientUpdate
+): void {
+  if (update.signatureSlot > currentSlot) {
+    throw Error(`update slot ${update.signatureSlot} must not be in the future, current slot ${currentSlot}`);
+  }
+
+  const updateSignaturePeriod = computeSyncPeriodAtSlot(update.signatureSlot);
+  // TODO: Consider attempting to retrieve LightClientUpdate from transport if missing
+  // Note: store.getSyncCommitteeAtPeriod() may advance store
+  const syncCommittee = getSyncCommitteeAtPeriod(store, updateSignaturePeriod, opts);
+
+  validateLightClientUpdate(config, store, update, syncCommittee);
+
+  // Track the maximum number of active participants in the committee signatures
+  const syncCommitteeTrueBits = sumBits(update.syncAggregate.syncCommitteeBits);
+  store.setActiveParticipants(updateSignaturePeriod, syncCommitteeTrueBits);
+
+  // Update the optimistic header
+  if (
+    syncCommitteeTrueBits > getSafetyThreshold(store.getMaxActiveParticipants(updateSignaturePeriod)) &&
+    update.attestedHeader.beacon.slot > store.optimisticHeader.beacon.slot
+  ) {
+    store.optimisticHeader = update.attestedHeader;
+  }
+
+  // Update finalized header
+  if (
+    syncCommitteeTrueBits * 3 >= SYNC_COMMITTEE_SIZE * 2 &&
+    update.finalizedHeader.beacon.slot > store.finalizedHeader.beacon.slot
+  ) {
+    store.finalizedHeader = update.finalizedHeader;
+    if (store.finalizedHeader.beacon.slot > store.optimisticHeader.beacon.slot) {
+      store.optimisticHeader = store.finalizedHeader;
+    }
+  }
+
+  if (isSyncCommitteeUpdate(update)) {
+    // Update the best update in case we have to force-update to it if the timeout elapses
+    const bestValidUpdate = store.bestValidUpdates.get(updateSignaturePeriod);
+    const updateSummary = toLightClientUpdateSummary(update);
+    if (!bestValidUpdate || isBetterUpdate(updateSummary, bestValidUpdate.summary)) {
+      store.bestValidUpdates.set(updateSignaturePeriod, {update, summary: updateSummary});
+      pruneSetToMax(store.bestValidUpdates, MAX_SYNC_PERIODS_CACHE);
+    }
+
+    // Note: defer update next sync committee to a future getSyncCommitteeAtPeriod() call
+  }
+}
+
+export function getSyncCommitteeAtPeriod(
+  store: ILightClientStore,
+  period: SyncPeriod,
+  opts: ProcessUpdateOpts
+): SyncCommitteeFast {
+  const syncCommittee = store.syncCommittees.get(period);
+  if (syncCommittee) {
+    return syncCommittee;
+  }
+
+  const bestValidUpdate = store.bestValidUpdates.get(period - 1);
+  if (bestValidUpdate && (isSafeLightClientUpdate(bestValidUpdate.summary) || opts.allowForcedUpdates)) {
+    const {update} = bestValidUpdate;
+    const syncCommittee = deserializeSyncCommittee(update.nextSyncCommittee);
+    store.syncCommittees.set(period, syncCommittee);
+    pruneSetToMax(store.syncCommittees, MAX_SYNC_PERIODS_CACHE);
+    store.bestValidUpdates.delete(period - 1);
+
+    if (opts.updateHeadersOnForcedUpdate) {
+      // From https://github.com/ethereum/consensus-specs/blob/a57e15636013eeba3610ff3ade41781dba1bb0cd/specs/altair/light-client/sync-protocol.md?plain=1#L403
+      if (update.finalizedHeader.beacon.slot <= store.finalizedHeader.beacon.slot) {
+        update.finalizedHeader = update.attestedHeader;
+      }
+
+      // From https://github.com/ethereum/consensus-specs/blob/a57e15636013eeba3610ff3ade41781dba1bb0cd/specs/altair/light-client/sync-protocol.md?plain=1#L374
+      if (update.finalizedHeader.beacon.slot > store.finalizedHeader.beacon.slot) {
+        store.finalizedHeader = update.finalizedHeader;
+      }
+      if (store.finalizedHeader.beacon.slot > store.optimisticHeader.beacon.slot) {
+        store.optimisticHeader = store.finalizedHeader;
+      }
+    }
+
+    return syncCommittee;
+  }
+
+  const availableSyncCommittees = Array.from(store.syncCommittees.keys());
+  const availableBestValidUpdates = Array.from(store.bestValidUpdates.keys());
+  throw Error(
+    `No SyncCommittee for period ${period}` +
+      ` available syncCommittees ${JSON.stringify(availableSyncCommittees)}` +
+      ` available bestValidUpdates ${JSON.stringify(availableBestValidUpdates)}`
+  );
+}
+
+export function isSafeLightClientUpdate(update: LightClientUpdateSummary): boolean {
+  return (
+    update.activeParticipants * 3 >= SYNC_COMMITTEE_SIZE * 2 && update.isFinalityUpdate && update.isSyncCommitteeUpdate
+  );
+}