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

package/src/spec/store.ts

@@ -0,0 +1,105 @@
+import type {PublicKey} from "@chainsafe/bls/types";
+import {BeaconConfig} from "@lodestar/config";
+import {LightClientBootstrap, LightClientHeader, LightClientUpdate, SyncPeriod} from "@lodestar/types";
+import {computeSyncPeriodAtSlot, deserializeSyncCommittee} from "../utils/index.js";
+import {LightClientUpdateSummary} from "./isBetterUpdate.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 _finalizedHeader: LightClientHeader;
+  private _optimisticHeader: 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._finalizedHeader = bootstrap.header;
+    this._optimisticHeader = bootstrap.header;
+  }
+
+  get finalizedHeader(): LightClientHeader {
+    return this._finalizedHeader;
+  }
+
+  set finalizedHeader(value: LightClientHeader) {
+    this._finalizedHeader = value;
+    this.events.onSetFinalizedHeader?.(value);
+  }
+
+  get optimisticHeader(): LightClientHeader {
+    return this._optimisticHeader;
+  }
+
+  set optimisticHeader(value: LightClientHeader) {
+    this._optimisticHeader = 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}`);
+// }

package/src/spec/utils.ts

@@ -0,0 +1,266 @@
+import {BitArray, byteArrayEquals} from "@chainsafe/ssz";
+import {ChainForkConfig} from "@lodestar/config";
+import {
+  BLOCK_BODY_EXECUTION_PAYLOAD_DEPTH as EXECUTION_PAYLOAD_DEPTH,
+  BLOCK_BODY_EXECUTION_PAYLOAD_INDEX as EXECUTION_PAYLOAD_INDEX,
+  FINALIZED_ROOT_DEPTH,
+  FINALIZED_ROOT_DEPTH_ELECTRA,
+  ForkName,
+  ForkSeq,
+  NEXT_SYNC_COMMITTEE_DEPTH,
+  NEXT_SYNC_COMMITTEE_DEPTH_ELECTRA,
+  isForkPostElectra,
+} from "@lodestar/params";
+import {
+  BeaconBlockHeader,
+  LightClientFinalityUpdate,
+  LightClientHeader,
+  LightClientOptimisticUpdate,
+  LightClientUpdate,
+  Slot,
+  SyncCommittee,
+  isElectraLightClientUpdate,
+  ssz,
+} from "@lodestar/types";
+import {computeEpochAtSlot, computeSyncPeriodAtSlot, isValidMerkleBranch} from "../utils/index.js";
+import {normalizeMerkleBranch} from "../utils/normalizeMerkleBranch.js";
+import {LightClientStore} from "./store.js";
+
+export const GENESIS_SLOT = 0;
+export const ZERO_HASH = new Uint8Array(32);
+export const ZERO_PUBKEY = new Uint8Array(48);
+export const ZERO_SYNC_COMMITTEE = ssz.altair.SyncCommittee.defaultValue();
+export const ZERO_HEADER = ssz.phase0.BeaconBlockHeader.defaultValue();
+/** From https://notes.ethereum.org/@vbuterin/extended_light_client_protocol#Optimistic-head-determining-function */
+const SAFETY_THRESHOLD_FACTOR = 2;
+
+export function sumBits(bits: BitArray): number {
+  return bits.getTrueBitIndexes().length;
+}
+
+export function getSafetyThreshold(maxActiveParticipants: number): number {
+  return Math.floor(maxActiveParticipants / SAFETY_THRESHOLD_FACTOR);
+}
+
+export function getZeroSyncCommitteeBranch(fork: ForkName): Uint8Array[] {
+  const nextSyncCommitteeDepth = isForkPostElectra(fork)
+    ? NEXT_SYNC_COMMITTEE_DEPTH_ELECTRA
+    : NEXT_SYNC_COMMITTEE_DEPTH;
+
+  return Array.from({length: nextSyncCommitteeDepth}, () => ZERO_HASH);
+}
+
+export function getZeroFinalityBranch(fork: ForkName): Uint8Array[] {
+  const finalizedRootDepth = isForkPostElectra(fork) ? FINALIZED_ROOT_DEPTH_ELECTRA : FINALIZED_ROOT_DEPTH;
+
+  return Array.from({length: finalizedRootDepth}, () => ZERO_HASH);
+}
+
+export function isSyncCommitteeUpdate(update: LightClientUpdate): boolean {
+  return (
+    // Fast return for when constructing full LightClientUpdate from partial updates
+    update.nextSyncCommitteeBranch !==
+      getZeroSyncCommitteeBranch(isElectraLightClientUpdate(update) ? ForkName.electra : ForkName.altair) &&
+    update.nextSyncCommitteeBranch.some((branch) => !byteArrayEquals(branch, ZERO_HASH))
+  );
+}
+
+export function isFinalityUpdate(update: LightClientUpdate): boolean {
+  return (
+    // Fast return for when constructing full LightClientUpdate from partial updates
+    update.finalityBranch !==
+      getZeroFinalityBranch(isElectraLightClientUpdate(update) ? ForkName.electra : ForkName.altair) &&
+    update.finalityBranch.some((branch) => !byteArrayEquals(branch, ZERO_HASH))
+  );
+}
+
+export function isZeroedHeader(header: BeaconBlockHeader): boolean {
+  // Fast return for when constructing full LightClientUpdate from partial updates
+  return header === ZERO_HEADER || byteArrayEquals(header.bodyRoot, ZERO_HASH);
+}
+
+export function isZeroedSyncCommittee(syncCommittee: SyncCommittee): boolean {
+  // Fast return for when constructing full LightClientUpdate from partial updates
+  return syncCommittee === ZERO_SYNC_COMMITTEE || byteArrayEquals(syncCommittee.pubkeys[0], ZERO_PUBKEY);
+}
+
+export function upgradeLightClientHeader(
+  config: ChainForkConfig,
+  targetFork: ForkName,
+  header: LightClientHeader
+): LightClientHeader {
+  const headerFork = config.getForkName(header.beacon.slot);
+  if (ForkSeq[headerFork] >= ForkSeq[targetFork]) {
+    throw Error(`Invalid upgrade request from headerFork=${headerFork} to targetFork=${targetFork}`);
+  }
+
+  // We are modifying the same header object, may be we could create a copy, but its
+  // not required as of now
+  const upgradedHeader = header;
+  const startUpgradeFromFork = Object.values(ForkName)[ForkSeq[headerFork] + 1];
+
+  switch (startUpgradeFromFork) {
+    // biome-ignore lint/suspicious/useDefaultSwitchClauseLast: We want default to evaluate at first to throw error early
+    default:
+      throw Error(
+        `Invalid startUpgradeFromFork=${startUpgradeFromFork} for headerFork=${headerFork} in upgradeLightClientHeader to targetFork=${targetFork}`
+      );
+
+    case ForkName.altair:
+    // biome-ignore lint/suspicious/noFallthroughSwitchClause: We need fall-through behavior here
+    case ForkName.bellatrix:
+      // Break if no further upgradation is required else fall through
+      if (ForkSeq[targetFork] <= ForkSeq.bellatrix) break;
+
+    // biome-ignore lint/suspicious/noFallthroughSwitchClause: We need fall-through behavior here
+    case ForkName.capella:
+      (upgradedHeader as LightClientHeader<ForkName.capella>).execution =
+        ssz.capella.LightClientHeader.fields.execution.defaultValue();
+      (upgradedHeader as LightClientHeader<ForkName.capella>).executionBranch =
+        ssz.capella.LightClientHeader.fields.executionBranch.defaultValue();
+
+      // Break if no further upgradation is required else fall through
+      if (ForkSeq[targetFork] <= ForkSeq.capella) break;
+
+    // biome-ignore lint/suspicious/noFallthroughSwitchClause: We need fall-through behavior here
+    case ForkName.deneb:
+      (upgradedHeader as LightClientHeader<ForkName.deneb>).execution.blobGasUsed =
+        ssz.deneb.LightClientHeader.fields.execution.fields.blobGasUsed.defaultValue();
+      (upgradedHeader as LightClientHeader<ForkName.deneb>).execution.excessBlobGas =
+        ssz.deneb.LightClientHeader.fields.execution.fields.excessBlobGas.defaultValue();
+
+      // Break if no further upgradation is required else fall through
+      if (ForkSeq[targetFork] <= ForkSeq.deneb) break;
+
+    // biome-ignore lint/suspicious/noFallthroughSwitchClause: We need fall-through behavior here
+    case ForkName.electra:
+      // No changes to LightClientHeader in Electra
+
+      // Break if no further upgrades is required else fall through
+      if (ForkSeq[targetFork] <= ForkSeq.electra) break;
+
+    // biome-ignore lint/suspicious/noFallthroughSwitchClause: We need fall-through behavior here
+    case ForkName.fulu:
+      // No changes to LightClientHeader in Fulu
+
+      // Break if no further upgrades is required else fall through
+      if (ForkSeq[targetFork] <= ForkSeq.fulu) break;
+
+    case ForkName.gloas:
+      // No changes to LightClientHeader in Gloas
+
+      // Break if no further upgrades is required else fall through
+      if (ForkSeq[targetFork] <= ForkSeq.gloas) break;
+  }
+  return upgradedHeader;
+}
+
+export function isValidLightClientHeader(config: ChainForkConfig, header: LightClientHeader): boolean {
+  const epoch = computeEpochAtSlot(header.beacon.slot);
+
+  if (epoch < config.CAPELLA_FORK_EPOCH) {
+    return (
+      ((header as LightClientHeader<ForkName.capella>).execution === undefined ||
+        ssz.capella.ExecutionPayloadHeader.equals(
+          (header as LightClientHeader<ForkName.capella>).execution,
+          ssz.capella.LightClientHeader.fields.execution.defaultValue()
+        )) &&
+      ((header as LightClientHeader<ForkName.capella>).executionBranch === undefined ||
+        ssz.capella.LightClientHeader.fields.executionBranch.equals(
+          ssz.capella.LightClientHeader.fields.executionBranch.defaultValue(),
+          (header as LightClientHeader<ForkName.capella>).executionBranch
+        ))
+    );
+  }
+
+  if (
+    epoch < config.DENEB_FORK_EPOCH &&
+    (((header as LightClientHeader<ForkName.deneb>).execution.blobGasUsed &&
+      (header as LightClientHeader<ForkName.deneb>).execution.blobGasUsed !== BigInt(0)) ||
+      ((header as LightClientHeader<ForkName.deneb>).execution.excessBlobGas &&
+        (header as LightClientHeader<ForkName.deneb>).execution.excessBlobGas !== BigInt(0)))
+  ) {
+    return false;
+  }
+
+  return isValidMerkleBranch(
+    config
+      .getPostBellatrixForkTypes(header.beacon.slot)
+      .ExecutionPayloadHeader.hashTreeRoot((header as LightClientHeader<ForkName.capella>).execution),
+    (header as LightClientHeader<ForkName.capella>).executionBranch,
+    EXECUTION_PAYLOAD_DEPTH,
+    EXECUTION_PAYLOAD_INDEX,
+    header.beacon.bodyRoot
+  );
+}
+
+export function upgradeLightClientUpdate(
+  config: ChainForkConfig,
+  targetFork: ForkName,
+  update: LightClientUpdate
+): LightClientUpdate {
+  update.attestedHeader = upgradeLightClientHeader(config, targetFork, update.attestedHeader);
+  update.finalizedHeader = upgradeLightClientHeader(config, targetFork, update.finalizedHeader);
+  update.nextSyncCommitteeBranch = normalizeMerkleBranch(
+    update.nextSyncCommitteeBranch,
+    isForkPostElectra(targetFork) ? NEXT_SYNC_COMMITTEE_DEPTH_ELECTRA : NEXT_SYNC_COMMITTEE_DEPTH
+  );
+  update.finalityBranch = normalizeMerkleBranch(
+    update.finalityBranch,
+    isForkPostElectra(targetFork) ? FINALIZED_ROOT_DEPTH_ELECTRA : FINALIZED_ROOT_DEPTH
+  );
+
+  return update;
+}
+
+export function upgradeLightClientFinalityUpdate(
+  config: ChainForkConfig,
+  targetFork: ForkName,
+  finalityUpdate: LightClientFinalityUpdate
+): LightClientFinalityUpdate {
+  finalityUpdate.attestedHeader = upgradeLightClientHeader(config, targetFork, finalityUpdate.attestedHeader);
+  finalityUpdate.finalizedHeader = upgradeLightClientHeader(config, targetFork, finalityUpdate.finalizedHeader);
+  finalityUpdate.finalityBranch = normalizeMerkleBranch(
+    finalityUpdate.finalityBranch,
+    isForkPostElectra(targetFork) ? FINALIZED_ROOT_DEPTH_ELECTRA : FINALIZED_ROOT_DEPTH
+  );
+
+  return finalityUpdate;
+}
+
+export function upgradeLightClientOptimisticUpdate(
+  config: ChainForkConfig,
+  targetFork: ForkName,
+  optimisticUpdate: LightClientOptimisticUpdate
+): LightClientOptimisticUpdate {
+  optimisticUpdate.attestedHeader = upgradeLightClientHeader(config, targetFork, optimisticUpdate.attestedHeader);
+
+  return optimisticUpdate;
+}
+
+/**
+ * Currently this upgradation is not required because all processing is done based on the
+ * summary that the store generates and maintains. In case store needs to be saved to disk,
+ * this could be required depending on the format the store is saved to the disk
+ */
+export function upgradeLightClientStore(
+  config: ChainForkConfig,
+  targetFork: ForkName,
+  store: LightClientStore,
+  signatureSlot: Slot
+): LightClientStore {
+  const updateSignaturePeriod = computeSyncPeriodAtSlot(signatureSlot);
+  const bestValidUpdate = store.bestValidUpdates.get(updateSignaturePeriod);
+
+  if (bestValidUpdate) {
+    store.bestValidUpdates.set(updateSignaturePeriod, {
+      update: upgradeLightClientUpdate(config, targetFork, bestValidUpdate.update),
+      summary: bestValidUpdate.summary,
+    });
+  }
+
+  store.finalizedHeader = upgradeLightClientHeader(config, targetFork, store.finalizedHeader);
+  store.optimisticHeader = upgradeLightClientHeader(config, targetFork, store.optimisticHeader);
+
+  return store;
+}

package/src/spec/validateLightClientBootstrap.ts

@@ -0,0 +1,41 @@
+import {byteArrayEquals} from "@chainsafe/ssz";
+import {ChainForkConfig} from "@lodestar/config";
+import {isForkPostElectra} from "@lodestar/params";
+import {LightClientBootstrap, Root, ssz} from "@lodestar/types";
+import {toHex} from "@lodestar/utils";
+import {isValidMerkleBranch} from "../utils/verifyMerkleBranch.js";
+import {isValidLightClientHeader} from "./utils.js";
+
+const CURRENT_SYNC_COMMITTEE_INDEX = 22;
+const CURRENT_SYNC_COMMITTEE_DEPTH = 5;
+const CURRENT_SYNC_COMMITTEE_INDEX_ELECTRA = 22;
+const CURRENT_SYNC_COMMITTEE_DEPTH_ELECTRA = 6;
+
+export function validateLightClientBootstrap(
+  config: ChainForkConfig,
+  trustedBlockRoot: Root,
+  bootstrap: LightClientBootstrap
+): void {
+  const headerRoot = ssz.phase0.BeaconBlockHeader.hashTreeRoot(bootstrap.header.beacon);
+  const fork = config.getForkName(bootstrap.header.beacon.slot);
+
+  if (!isValidLightClientHeader(config, bootstrap.header)) {
+    throw Error("Bootstrap Header is not Valid Light Client Header");
+  }
+
+  if (!byteArrayEquals(headerRoot, trustedBlockRoot)) {
+    throw Error(`bootstrap header root ${toHex(headerRoot)} != trusted root ${toHex(trustedBlockRoot)}`);
+  }
+
+  if (
+    !isValidMerkleBranch(
+      ssz.altair.SyncCommittee.hashTreeRoot(bootstrap.currentSyncCommittee),
+      bootstrap.currentSyncCommitteeBranch,
+      isForkPostElectra(fork) ? CURRENT_SYNC_COMMITTEE_DEPTH_ELECTRA : CURRENT_SYNC_COMMITTEE_DEPTH,
+      isForkPostElectra(fork) ? CURRENT_SYNC_COMMITTEE_INDEX_ELECTRA : CURRENT_SYNC_COMMITTEE_INDEX,
+      bootstrap.header.beacon.stateRoot
+    )
+  ) {
+    throw Error("Invalid currentSyncCommittee merkle branch");
+  }
+}

package/src/spec/validateLightClientUpdate.ts

@@ -0,0 +1,154 @@
+import bls from "@chainsafe/bls";
+import type {PublicKey, Signature} from "@chainsafe/bls/types";
+import {ChainForkConfig} from "@lodestar/config";
+import {
+  DOMAIN_SYNC_COMMITTEE,
+  FINALIZED_ROOT_DEPTH,
+  FINALIZED_ROOT_DEPTH_ELECTRA,
+  FINALIZED_ROOT_INDEX,
+  FINALIZED_ROOT_INDEX_ELECTRA,
+  GENESIS_SLOT,
+  MIN_SYNC_COMMITTEE_PARTICIPANTS,
+  NEXT_SYNC_COMMITTEE_DEPTH,
+  NEXT_SYNC_COMMITTEE_DEPTH_ELECTRA,
+  NEXT_SYNC_COMMITTEE_INDEX,
+  NEXT_SYNC_COMMITTEE_INDEX_ELECTRA,
+} from "@lodestar/params";
+import {LightClientUpdate, Root, isElectraLightClientUpdate, ssz} from "@lodestar/types";
+import {SyncCommitteeFast} from "../types.js";
+import {isValidMerkleBranch} from "../utils/index.js";
+import {getParticipantPubkeys, sumBits} from "../utils/utils.js";
+import {ILightClientStore} from "./store.js";
+import {
+  ZERO_HASH,
+  isFinalityUpdate,
+  isSyncCommitteeUpdate,
+  isValidLightClientHeader,
+  isZeroedHeader,
+  isZeroedSyncCommittee,
+} from "./utils.js";
+
+export function validateLightClientUpdate(
+  config: ChainForkConfig,
+  store: ILightClientStore,
+  update: LightClientUpdate,
+  syncCommittee: SyncCommitteeFast
+): void {
+  // Verify sync committee has sufficient participants
+  if (sumBits(update.syncAggregate.syncCommitteeBits) < MIN_SYNC_COMMITTEE_PARTICIPANTS) {
+    throw Error("Sync committee has not sufficient participants");
+  }
+
+  if (!isValidLightClientHeader(config, update.attestedHeader)) {
+    throw Error("Attested Header is not Valid Light Client Header");
+  }
+
+  // Sanity check that slots are in correct order
+  if (update.signatureSlot <= update.attestedHeader.beacon.slot) {
+    throw Error(
+      `signature slot ${update.signatureSlot} must be after attested header slot ${update.attestedHeader.beacon.slot}`
+    );
+  }
+  if (update.attestedHeader.beacon.slot < update.finalizedHeader.beacon.slot) {
+    throw Error(
+      `attested header slot ${update.signatureSlot} must be after finalized header slot ${update.finalizedHeader.beacon.slot}`
+    );
+  }
+
+  // Verify that the `finality_branch`, if present, confirms `finalized_header`
+  // to match the finalized checkpoint root saved in the state of `attested_header`.
+  // Note that the genesis finalized checkpoint root is represented as a zero hash.
+  if (!isFinalityUpdate(update)) {
+    if (!isZeroedHeader(update.finalizedHeader.beacon)) {
+      throw Error("finalizedHeader must be zero for non-finality update");
+    }
+  } else {
+    let finalizedRoot: Root;
+
+    if (update.finalizedHeader.beacon.slot === GENESIS_SLOT) {
+      if (!isZeroedHeader(update.finalizedHeader.beacon)) {
+        throw Error("finalizedHeader must be zero for not finality update");
+      }
+      finalizedRoot = ZERO_HASH;
+    } else {
+      if (!isValidLightClientHeader(config, update.finalizedHeader)) {
+        throw Error("Finalized Header is not valid Light Client Header");
+      }
+
+      finalizedRoot = ssz.phase0.BeaconBlockHeader.hashTreeRoot(update.finalizedHeader.beacon);
+    }
+
+    if (
+      !isValidMerkleBranch(
+        finalizedRoot,
+        update.finalityBranch,
+        isElectraLightClientUpdate(update) ? FINALIZED_ROOT_DEPTH_ELECTRA : FINALIZED_ROOT_DEPTH,
+        isElectraLightClientUpdate(update) ? FINALIZED_ROOT_INDEX_ELECTRA : FINALIZED_ROOT_INDEX,
+        update.attestedHeader.beacon.stateRoot
+      )
+    ) {
+      throw Error("Invalid finality header merkle branch");
+    }
+  }
+
+  // Verify that the `next_sync_committee`, if present, actually is the next sync committee saved in the
+  // state of the `attested_header`
+  if (!isSyncCommitteeUpdate(update)) {
+    if (!isZeroedSyncCommittee(update.nextSyncCommittee)) {
+      throw Error("nextSyncCommittee must be zero for non sync committee update");
+    }
+  } else {
+    if (
+      !isValidMerkleBranch(
+        ssz.altair.SyncCommittee.hashTreeRoot(update.nextSyncCommittee),
+        update.nextSyncCommitteeBranch,
+        isElectraLightClientUpdate(update) ? NEXT_SYNC_COMMITTEE_DEPTH_ELECTRA : NEXT_SYNC_COMMITTEE_DEPTH,
+        isElectraLightClientUpdate(update) ? NEXT_SYNC_COMMITTEE_INDEX_ELECTRA : NEXT_SYNC_COMMITTEE_INDEX,
+        update.attestedHeader.beacon.stateRoot
+      )
+    ) {
+      throw Error("Invalid next sync committee merkle branch");
+    }
+  }
+
+  // Verify sync committee aggregate signature
+
+  const participantPubkeys = getParticipantPubkeys(syncCommittee.pubkeys, update.syncAggregate.syncCommitteeBits);
+
+  const signingRoot = ssz.phase0.SigningData.hashTreeRoot({
+    objectRoot: ssz.phase0.BeaconBlockHeader.hashTreeRoot(update.attestedHeader.beacon),
+    domain: store.config.getDomain(update.signatureSlot - 1, DOMAIN_SYNC_COMMITTEE),
+  });
+
+  if (!isValidBlsAggregate(participantPubkeys, signingRoot, update.syncAggregate.syncCommitteeSignature)) {
+    throw Error("Invalid aggregate signature");
+  }
+}
+
+/**
+ * Same as BLS.verifyAggregate but with detailed error messages
+ */
+function isValidBlsAggregate(publicKeys: PublicKey[], message: Uint8Array, signature: Uint8Array): boolean {
+  let aggPubkey: PublicKey;
+  try {
+    aggPubkey = bls.PublicKey.aggregate(publicKeys);
+  } catch (e) {
+    (e as Error).message = `Error aggregating pubkeys: ${(e as Error).message}`;
+    throw e;
+  }
+
+  let sig: Signature;
+  try {
+    sig = bls.Signature.fromBytes(signature, undefined, true);
+  } catch (e) {
+    (e as Error).message = `Error deserializing signature: ${(e as Error).message}`;
+    throw e;
+  }
+
+  try {
+    return sig.verify(aggPubkey, message);
+  } catch (e) {
+    (e as Error).message = `Error verifying signature: ${(e as Error).message}`;
+    throw e;
+  }
+}

package/src/transport/index.ts

@@ -0,0 +1,2 @@
+export * from "./interface.js";
+export * from "./rest.js";

package/src/transport/interface.ts

@@ -0,0 +1,37 @@
+import {ForkName} from "@lodestar/params";
+import {
+  LightClientBootstrap,
+  LightClientFinalityUpdate,
+  LightClientOptimisticUpdate,
+  LightClientUpdate,
+  SyncPeriod,
+} from "@lodestar/types";
+
+export interface LightClientTransport {
+  getUpdates(
+    startPeriod: SyncPeriod,
+    count: number
+  ): Promise<
+    {
+      version: ForkName;
+      data: LightClientUpdate;
+    }[]
+  >;
+  /**
+   * Returns the latest optimistic head update available. Clients should use the SSE type `light_client_optimistic_update`
+   * unless to get the very first head update after syncing, or if SSE are not supported by the server.
+   */
+  getOptimisticUpdate(): Promise<{version: ForkName; data: LightClientOptimisticUpdate}>;
+  getFinalityUpdate(): Promise<{version: ForkName; data: LightClientFinalityUpdate}>;
+  /**
+   * Fetch a bootstrapping state with a proof to a trusted block root.
+   * The trusted block root should be fetched with similar means to a weak subjectivity checkpoint.
+   * Only block roots for checkpoints are guaranteed to be available.
+   */
+  getBootstrap(blockRoot: string): Promise<{version: ForkName; data: LightClientBootstrap}>;
+
+  // registers handler for LightClientOptimisticUpdate. This can come either via sse or p2p
+  onOptimisticUpdate(handler: (optimisticUpdate: LightClientOptimisticUpdate) => void): void;
+  // registers handler for LightClientFinalityUpdate. This can come either via sse or p2p
+  onFinalityUpdate(handler: (finalityUpdate: LightClientFinalityUpdate) => void): void;
+}