@lodestar/state-transition 1.43.0 → 1.44.0-dev.1d0e0b9081

package/src/block/processDepositRequest.ts

@@ -1,10 +1,10 @@
-import {BeaconConfig} from "@lodestar/config";
 import {FAR_FUTURE_EPOCH, ForkSeq, UNSET_DEPOSIT_REQUESTS_START_INDEX} from "@lodestar/params";
-import {BLSPubkey, Bytes32, PubkeyHex, UintNum64, electra, ssz} from "@lodestar/types";
+import {BLSPubkey, Bytes32, UintNum64, electra, ssz} from "@lodestar/types";
 import {toPubkeyHex} from "@lodestar/utils";
 import {CachedBeaconStateElectra, CachedBeaconStateGloas} from "../types.js";
 import {findBuilderIndexByPubkey, isBuilderWithdrawalCredential} from "../util/gloas.js";
 import {computeEpochAtSlot, isValidatorKnown} from "../util/index.js";
+import {PendingDepositsLookup} from "../util/pendingDepositsLookup.js";
 import {isValidDepositSignature} from "./processDeposit.js";
 
 /**
@@ -76,53 +76,60 @@ function addBuilderToRegistry(
   }
 }
 
-// TODO GLOAS: pendingValidatorPubkeys cache is currently naive and has room for improvement.
-// Currently the cache lives in process_block, but we should put it in epochCache or elsewhere that has longer
-// lifetime to avoid duplicated deposit signature computation
+// TODO GLOAS: the PendingDepositsLookup is currently scoped to a single envelope of
+// deposit-requests. We can track it as ephemeral within EpochCache and transfer to the next block
+// transition to reuse cached signature verifications.
 // See https://github.com/ChainSafe/lodestar/issues/9181
 export function processDepositRequest(
   fork: ForkSeq,
   state: CachedBeaconStateElectra | CachedBeaconStateGloas,
   depositRequest: electra.DepositRequest,
-  pendingValidatorPubkeysCache?: Set<PubkeyHex>
+  pendingDepositsLookup?: PendingDepositsLookup
 ): void {
   const {pubkey, withdrawalCredentials, amount, signature} = depositRequest;
 
-  // Check if this is a builder or validator deposit
   if (fork >= ForkSeq.gloas) {
     const stateGloas = state as CachedBeaconStateGloas;
-    const pendingValidatorPubkeys =
-      pendingValidatorPubkeysCache ?? getPendingValidatorPubkeys(state.config, stateGloas);
+    const lookup = pendingDepositsLookup ?? PendingDepositsLookup.build(stateGloas);
     const pubkeyHex = toPubkeyHex(pubkey);
     const builderIndex = findBuilderIndexByPubkey(stateGloas, pubkey);
     const validatorIndex = state.epochCtx.getValidatorIndex(pubkey);
 
-    // Regardless of the withdrawal credentials prefix, if a builder/validator
-    // already exists with this pubkey, apply the deposit to their balance
     const isBuilder = builderIndex !== null;
     const isValidator = isValidatorKnown(state, validatorIndex);
-    const isPendingValidator = pendingValidatorPubkeys.has(pubkeyHex);
 
-    if (isBuilder || (isBuilderWithdrawalCredential(withdrawalCredentials) && !isValidator && !isPendingValidator)) {
-      // Apply builder deposits immediately
+    if (isBuilder) {
+      // Top up an existing builder regardless of withdrawal credential prefix
       applyDepositForBuilder(stateGloas, pubkey, withdrawalCredentials, amount, signature, state.slot);
       return;
     }
 
-    // Keep the shared cache in sync: if this deposit has a valid signature, subsequent
-    // deposit requests for the same pubkey in this envelope must see it as a pending validator
+    // Only check the (expensive) "pending validator" condition when needed
     if (
-      pendingValidatorPubkeysCache &&
+      isBuilderWithdrawalCredential(withdrawalCredentials) &&
       !isValidator &&
-      !isPendingValidator &&
-      isValidDepositSignature(state.config, pubkey, withdrawalCredentials, amount, signature)
+      !lookup.hasPendingValidator(state.config, pubkeyHex)
     ) {
-      pendingValidatorPubkeys.add(pubkeyHex);
+      applyDepositForBuilder(stateGloas, pubkey, withdrawalCredentials, amount, signature, state.slot);
+      return;
     }
+
+    const pendingDeposit = ssz.electra.PendingDeposit.toViewDU({
+      pubkey,
+      withdrawalCredentials,
+      amount,
+      signature,
+      slot: state.slot,
+    });
+    // Keep the lookup in sync with state.pendingDeposits so later deposit-requests
+    // in the same envelope see this deposit
+    lookup.add(pendingDeposit, pubkeyHex);
+    state.pendingDeposits.push(pendingDeposit);
+    return;
   }
 
-  // Only set deposit_requests_start_index in Electra fork, not Gloas
-  if (fork < ForkSeq.gloas && state.depositRequestsStartIndex === UNSET_DEPOSIT_REQUESTS_START_INDEX) {
+  // Pre-Gloas (Electra) path
+  if (state.depositRequestsStartIndex === UNSET_DEPOSIT_REQUESTS_START_INDEX) {
     state.depositRequestsStartIndex = depositRequest.index;
   }
 
@@ -136,28 +143,3 @@ export function processDepositRequest(
   });
   state.pendingDeposits.push(pendingDeposit);
 }
-
-/**
- * Build a set of pubkeys (hex-encoded) from pending deposits that have valid signatures.
- * This is computed once and passed to each processDepositRequest call to avoid
- * repeatedly iterating state.pendingDeposits.
- *
- * Spec: https://github.com/ethereum/consensus-specs/blob/v1.7.0-alpha.3/specs/gloas/beacon-chain.md#new-is_pending_validator
- */
-export function getPendingValidatorPubkeys(config: BeaconConfig, state: CachedBeaconStateGloas): Set<PubkeyHex> {
-  const result = new Set<PubkeyHex>();
-  for (const pendingDeposit of state.pendingDeposits.getAllReadonly()) {
-    if (
-      isValidDepositSignature(
-        config,
-        pendingDeposit.pubkey,
-        pendingDeposit.withdrawalCredentials,
-        pendingDeposit.amount,
-        pendingDeposit.signature
-      )
-    ) {
-      result.add(toPubkeyHex(pendingDeposit.pubkey));
-    }
-  }
-  return result;
-}

package/src/block/processParentExecutionPayload.ts

@@ -3,8 +3,9 @@ import {BeaconBlock, electra, ssz} from "@lodestar/types";
 import {byteArrayEquals, toRootHex} from "@lodestar/utils";
 import {CachedBeaconStateGloas} from "../types.js";
 import {computeEpochAtSlot} from "../util/epoch.js";
+import {PendingDepositsLookup} from "../util/pendingDepositsLookup.js";
 import {processConsolidationRequest} from "./processConsolidationRequest.js";
-import {getPendingValidatorPubkeys, processDepositRequest} from "./processDepositRequest.js";
+import {processDepositRequest} from "./processDepositRequest.js";
 import {processWithdrawalRequest} from "./processWithdrawalRequest.js";
 
 /**
@@ -54,9 +55,9 @@ export function applyParentExecutionPayload(state: CachedBeaconStateGloas, reque
   // Process execution requests from parent's payload. The execution
   // requests are processed at state.slot (child's slot), not the parent's slot.
   if (requests.deposits.length > 0) {
-    const pendingValidatorPubkeys = getPendingValidatorPubkeys(state.config, state);
+    const pendingDepositsLookup = PendingDepositsLookup.build(state);
     for (const deposit of requests.deposits) {
-      processDepositRequest(fork, state, deposit, pendingValidatorPubkeys);
+      processDepositRequest(fork, state, deposit, pendingDepositsLookup);
     }
   }
 

package/src/lightClient/spec/index.ts

@@ -0,0 +1,101 @@
+import {BeaconConfig} from "@lodestar/config";
+import {UPDATE_TIMEOUT} from "@lodestar/params";
+import {
+  LightClientBootstrap,
+  LightClientFinalityUpdate,
+  LightClientOptimisticUpdate,
+  LightClientUpdate,
+  Slot,
+} from "@lodestar/types";
+import {computeSyncPeriodAtSlot} from "../../util/epoch.js";
+import {
+  type ProcessUpdateOpts,
+  getSyncCommitteeAtPeriod,
+  processLightClientUpdate,
+} from "./processLightClientUpdate.js";
+import {type ILightClientStore, LightClientStore, type 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 {
+  type ProcessUpdateOpts,
+  getSyncCommitteeAtPeriod,
+  isSafeLightClientUpdate,
+  processLightClientUpdate,
+} from "./processLightClientUpdate.js";
+export {
+  type ILightClientStore,
+  LightClientStore,
+  type LightClientStoreEvents,
+  type LightClientUpdateWithSummary,
+  type SyncCommitteeFast,
+} from "./store.js";
+export {
+  getSafetyThreshold,
+  isFinalityUpdate,
+  isSyncCommitteeUpdate,
+  isValidLightClientHeader,
+  normalizeMerkleBranch,
+  upgradeLightClientFinalityUpdate,
+  upgradeLightClientHeader,
+  upgradeLightClientOptimisticUpdate,
+  upgradeLightClientStore,
+  upgradeLightClientUpdate,
+} from "./utils.js";
+export {validateLightClientBootstrap} from "./validateLightClientBootstrap.js";
+export {validateLightClientUpdate} from "./validateLightClientUpdate.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/lightClient/spec/isBetterUpdate.ts

@@ -0,0 +1,94 @@
+import {SYNC_COMMITTEE_SIZE} from "@lodestar/params";
+import {LightClientUpdate, Slot} from "@lodestar/types";
+import {computeSyncPeriodAtSlot} from "../../util/epoch.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/lightClient/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} from "../../util/epoch.js";
+import {LightClientUpdateSummary, isBetterUpdate, toLightClientUpdateSummary} from "./isBetterUpdate.js";
+import {type ILightClientStore, MAX_SYNC_PERIODS_CACHE, type SyncCommitteeFast} from "./store.js";
+import {deserializeSyncCommittee, getSafetyThreshold, isSyncCommitteeUpdate, sumBits} 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
+  );
+}

package/src/lightClient/spec/store.ts

@@ -0,0 +1,106 @@
+import type {PublicKey} from "@chainsafe/blst";
+import {BeaconConfig} from "@lodestar/config";
+import {LightClientBootstrap, LightClientHeader, LightClientUpdate, SyncPeriod} from "@lodestar/types";
+import {computeSyncPeriodAtSlot} from "../../util/epoch.js";
+import type {LightClientUpdateSummary} from "./isBetterUpdate.js";
+import {deserializeSyncCommittee} from "./utils.js";
+
+export const MAX_SYNC_PERIODS_CACHE = 2;
+
+export interface ILightClientStore {
+  readonly config: BeaconConfig;
+
+  /** Map of trusted SyncCommittee to be used for sig validation */
+  readonly syncCommittees: Map<SyncPeriod, SyncCommitteeFast>;
+  /** Map of best valid updates */
+  readonly bestValidUpdates: Map<SyncPeriod, LightClientUpdateWithSummary>;
+
+  getMaxActiveParticipants(period: SyncPeriod): number;
+  setActiveParticipants(period: SyncPeriod, activeParticipants: number): void;
+
+  // Header that is finalized
+  finalizedHeader: LightClientHeader;
+
+  // Most recent available reasonably-safe header
+  optimisticHeader: LightClientHeader;
+}
+
+export interface LightClientStoreEvents {
+  onSetFinalizedHeader?: (header: LightClientHeader) => void;
+  onSetOptimisticHeader?: (header: LightClientHeader) => void;
+}
+
+export class LightClientStore implements ILightClientStore {
+  readonly syncCommittees = new Map<SyncPeriod, SyncCommitteeFast>();
+  readonly bestValidUpdates = new Map<SyncPeriod, LightClientUpdateWithSummary>();
+
+  private finalizedHeaderValue: LightClientHeader;
+  private optimisticHeaderValue: LightClientHeader;
+
+  private readonly maxActiveParticipants = new Map<SyncPeriod, number>();
+
+  constructor(
+    readonly config: BeaconConfig,
+    bootstrap: LightClientBootstrap,
+    private readonly events: LightClientStoreEvents
+  ) {
+    const bootstrapPeriod = computeSyncPeriodAtSlot(bootstrap.header.beacon.slot);
+    this.syncCommittees.set(bootstrapPeriod, deserializeSyncCommittee(bootstrap.currentSyncCommittee));
+    this.finalizedHeaderValue = bootstrap.header;
+    this.optimisticHeaderValue = bootstrap.header;
+  }
+
+  get finalizedHeader(): LightClientHeader {
+    return this.finalizedHeaderValue;
+  }
+
+  set finalizedHeader(value: LightClientHeader) {
+    this.finalizedHeaderValue = value;
+    this.events.onSetFinalizedHeader?.(value);
+  }
+
+  get optimisticHeader(): LightClientHeader {
+    return this.optimisticHeaderValue;
+  }
+
+  set optimisticHeader(value: LightClientHeader) {
+    this.optimisticHeaderValue = value;
+    this.events.onSetOptimisticHeader?.(value);
+  }
+
+  getMaxActiveParticipants(period: SyncPeriod): number {
+    const currMaxParticipants = this.maxActiveParticipants.get(period) ?? 0;
+    const prevMaxParticipants = this.maxActiveParticipants.get(period - 1) ?? 0;
+
+    return Math.max(currMaxParticipants, prevMaxParticipants);
+  }
+
+  setActiveParticipants(period: SyncPeriod, activeParticipants: number): void {
+    const maxActiveParticipants = this.maxActiveParticipants.get(period) ?? 0;
+    if (activeParticipants > maxActiveParticipants) {
+      this.maxActiveParticipants.set(period, activeParticipants);
+    }
+
+    // Prune old entries
+    for (const key of this.maxActiveParticipants.keys()) {
+      if (key < period - MAX_SYNC_PERIODS_CACHE) {
+        this.maxActiveParticipants.delete(key);
+      }
+    }
+  }
+}
+
+export type SyncCommitteeFast = {
+  pubkeys: PublicKey[];
+  aggregatePubkey: PublicKey;
+};
+
+export type LightClientUpdateWithSummary = {
+  update: LightClientUpdate;
+  summary: LightClientUpdateSummary;
+};
+
+// === storePeriod ? store.currentSyncCommittee : store.nextSyncCommittee;
+// if (!syncCommittee) {
+//   throw Error(`syncCommittee not available for signature period ${updateSignaturePeriod}`);
+// }