@lodestar/state-transition 1.43.0-dev.4358217e12 → 1.43.0-dev.4451fec75a

package/package.json

@@ -11,7 +11,7 @@
   "bugs": {
     "url": "https://github.com/ChainSafe/lodestar/issues"
   },
-  "version": "1.43.0-dev.4358217e12",
+  "version": "1.43.0-dev.4451fec75a",
   "type": "module",
   "exports": {
     ".": {
@@ -34,6 +34,11 @@
       "types": "./lib/slot/index.d.ts",
       "import": "./lib/slot/index.js"
     },
+    "./light-client": {
+      "bun": "./src/lightClient/spec/index.ts",
+      "types": "./lib/lightClient/spec/index.d.ts",
+      "import": "./lib/lightClient/spec/index.js"
+    },
     "./test-utils": {
       "bun": "./src/testUtils/index.ts",
       "types": "./lib/testUtils/index.d.ts",
@@ -62,19 +67,19 @@
   "dependencies": {
     "@chainsafe/as-sha256": "^1.2.0",
     "@chainsafe/blst": "^2.2.0",
-    "@chainsafe/persistent-merkle-tree": "^1.2.1",
+    "@chainsafe/persistent-merkle-tree": "^1.2.5",
     "@chainsafe/persistent-ts": "^1.0.0",
     "@chainsafe/pubkey-index-map": "^3.0.0",
     "@chainsafe/ssz": "^1.4.0",
     "@chainsafe/swap-or-not-shuffle": "^1.2.1",
-    "@lodestar/config": "^1.43.0-dev.4358217e12",
-    "@lodestar/params": "^1.43.0-dev.4358217e12",
-    "@lodestar/types": "^1.43.0-dev.4358217e12",
-    "@lodestar/utils": "^1.43.0-dev.4358217e12",
+    "@lodestar/config": "^1.43.0-dev.4451fec75a",
+    "@lodestar/params": "^1.43.0-dev.4451fec75a",
+    "@lodestar/types": "^1.43.0-dev.4451fec75a",
+    "@lodestar/utils": "^1.43.0-dev.4451fec75a",
     "@vekexasia/bigint-buffer2": "^1.1.1"
   },
   "devDependencies": {
-    "@lodestar/api": "^1.43.0-dev.4358217e12"
+    "@lodestar/api": "^1.43.0-dev.4451fec75a"
   },
   "keywords": [
     "ethereum",
@@ -82,5 +87,5 @@
     "beacon",
     "blockchain"
   ],
-  "gitHead": "b573e546006ca69dde6b249cb32a72502eff9f3d"
+  "gitHead": "69d7d9c6e242405ae8c43fdb382e166b74bba752"
 }

package/src/block/processConsolidationRequest.ts

@@ -46,7 +46,8 @@ export function processConsolidationRequest(
   }
 
   // If there is too little available consolidation churn limit, consolidation requests are ignored
-  if (getConsolidationChurnLimit(state.epochCtx) <= MIN_ACTIVATION_BALANCE) {
+  const fork = state.config.getForkSeq(state.slot);
+  if (getConsolidationChurnLimit(fork, state.epochCtx) <= MIN_ACTIVATION_BALANCE) {
     return;
   }
 

package/src/block/processParentExecutionPayload.ts

@@ -10,7 +10,7 @@ import {processWithdrawalRequest} from "./processWithdrawalRequest.js";
 /**
  * Process parent execution payload effects as the first step of processBlock.
  *
- * Spec: https://github.com/ethereum/consensus-specs/blob/v1.7.0-alpha.5/specs/gloas/beacon-chain.md#new-process_parent_execution_payload
+ * Spec: https://github.com/ethereum/consensus-specs/blob/v1.7.0-alpha.6/specs/gloas/beacon-chain.md#new-process_parent_execution_payload
  */
 export function processParentExecutionPayload(state: CachedBeaconStateGloas, block: BeaconBlock<ForkPostGloas>): void {
   const bid = block.body.signedExecutionPayloadBid.message;
@@ -42,7 +42,7 @@ export function processParentExecutionPayload(state: CachedBeaconStateGloas, blo
  * Called from processParentExecutionPayload during block processing, and from the validator during
  * block production before computing withdrawals.
  *
- * Spec: https://github.com/ethereum/consensus-specs/blob/v1.7.0-alpha.5/specs/gloas/beacon-chain.md#new-apply_parent_execution_payload
+ * Spec: https://github.com/ethereum/consensus-specs/blob/v1.7.0-alpha.6/specs/gloas/beacon-chain.md#new-apply_parent_execution_payload
  */
 export function applyParentExecutionPayload(state: CachedBeaconStateGloas, requests: electra.ExecutionRequests): void {
   const fork = state.config.getForkSeq(state.slot);
@@ -94,7 +94,7 @@ export function applyParentExecutionPayload(state: CachedBeaconStateGloas, reque
  * Settle a builder payment at the given index: move its withdrawal (if any) to the
  * pending withdrawals list and clear the payment slot.
  *
- * Spec: https://github.com/ethereum/consensus-specs/blob/v1.7.0-alpha.5/specs/gloas/beacon-chain.md#new-settle_builder_payment
+ * Spec: https://github.com/ethereum/consensus-specs/blob/v1.7.0-alpha.6/specs/gloas/beacon-chain.md#new-settle_builder_payment
  */
 function settleBuilderPayment(state: CachedBeaconStateGloas, paymentIndex: number): void {
   if (paymentIndex >= state.builderPendingPayments.length) {

package/src/block/processWithdrawals.ts

@@ -10,7 +10,6 @@ import {
 } from "@lodestar/params";
 import {BuilderIndex, ValidatorIndex, capella, ssz} from "@lodestar/types";
 import {byteArrayEquals, toRootHex} from "@lodestar/utils";
-import {ZERO_HASH} from "../constants/index.js";
 import {CachedBeaconStateCapella, CachedBeaconStateElectra, CachedBeaconStateGloas} from "../types.js";
 import {
   convertBuilderIndexToValidatorIndex,
@@ -31,15 +30,14 @@ export function processWithdrawals(
   state: CachedBeaconStateCapella | CachedBeaconStateElectra | CachedBeaconStateGloas,
   payload?: capella.FullOrBlindedExecutionPayload
 ): void {
-  // Return early if this is genesis block or the parent block is empty
+  // Return early if the parent block is empty
   if (fork >= ForkSeq.gloas) {
     const stateGloas = state as CachedBeaconStateGloas;
-    const isGenesisBlock = byteArrayEquals(stateGloas.latestBlockHash, ZERO_HASH);
     const isParentBlockEmpty = !byteArrayEquals(
       stateGloas.latestBlockHash,
       stateGloas.latestExecutionPayloadBid.blockHash
     );
-    if (isGenesisBlock || isParentBlockEmpty) {
+    if (isParentBlockEmpty) {
       return;
     }
   }

package/src/cache/epochCache.ts

@@ -38,9 +38,9 @@ import {
   computeEpochAtSlot,
   computeProposers,
   computeSyncPeriodAtEpoch,
-  getActivationChurnLimit,
   getChurnLimit,
   getSeed,
+  getValidatorActivationChurnLimit,
   isActiveValidator,
   isAggregatorFromCommitteeLength,
 } from "../util/index.js";
@@ -478,7 +478,7 @@ export class EpochCache {
     // the first block of the epoch process_block() call. So churnLimit must be computed at the end of the before epoch
     // transition and the result is valid until the end of the next epoch transition
     const churnLimit = getChurnLimit(config, currentShuffling.activeIndices.length);
-    const activationChurnLimit = getActivationChurnLimit(
+    const activationChurnLimit = getValidatorActivationChurnLimit(
       config,
       config.getForkSeq(state.slot),
       currentShuffling.activeIndices.length
@@ -652,7 +652,7 @@ export class EpochCache {
     // the first block of the epoch process_block() call. So churnLimit must be computed at the end of the before epoch
     // transition and the result is valid until the end of the next epoch transition
     this.churnLimit = getChurnLimit(this.config, this.currentShuffling.activeIndices.length);
-    this.activationChurnLimit = getActivationChurnLimit(
+    this.activationChurnLimit = getValidatorActivationChurnLimit(
       this.config,
       this.config.getForkSeq(state.slot),
       this.currentShuffling.activeIndices.length

package/src/epoch/processPendingDeposits.ts

@@ -5,7 +5,7 @@ import {CachedBeaconStateElectra, EpochTransitionCache} from "../types.js";
 import {increaseBalance} from "../util/balance.js";
 import {hasCompoundingWithdrawalCredential, isValidatorKnown} from "../util/electra.js";
 import {computeStartSlotAtEpoch} from "../util/epoch.js";
-import {getActivationExitChurnLimit} from "../util/validator.js";
+import {getActivationChurnLimit, getActivationExitChurnLimit} from "../util/validator.js";
 
 /**
  * Starting from Electra:
@@ -17,8 +17,11 @@ import {getActivationExitChurnLimit} from "../util/validator.js";
  * TODO Electra: Update ssz library to support batch push to `pendingDeposits`
  */
 export function processPendingDeposits(state: CachedBeaconStateElectra, cache: EpochTransitionCache): void {
+  const fork = state.config.getForkSeq(state.slot);
   const nextEpoch = state.epochCtx.epoch + 1;
-  const availableForProcessing = state.depositBalanceToConsume + BigInt(getActivationExitChurnLimit(state.epochCtx));
+  const churnLimit =
+    fork >= ForkSeq.gloas ? getActivationChurnLimit(state.epochCtx) : getActivationExitChurnLimit(state.epochCtx);
+  const availableForProcessing = state.depositBalanceToConsume + BigInt(churnLimit);
   let processedAmount = 0;
   let nextDepositIndex = 0;
   const depositsToPostpone = [];

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}`);
+// }