@lodestar/state-transition 1.43.0-dev.be5f70c0c8 → 1.43.0-dev.c98da75ec7

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