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

package/src/transport/rest.ts

@@ -0,0 +1,89 @@
+import mitt, {Emitter as MittEmitter} from "mitt";
+import {type ApiClient, routes} from "@lodestar/api";
+import {type ForkName} from "@lodestar/params";
+import {
+  LightClientBootstrap,
+  LightClientFinalityUpdate,
+  LightClientOptimisticUpdate,
+  LightClientUpdate,
+  type SyncPeriod,
+} from "@lodestar/types";
+import {type LightClientTransport} from "./interface.js";
+
+export type LightClientRestEvents = {
+  [routes.events.EventType.lightClientFinalityUpdate]: (update: LightClientFinalityUpdate) => void;
+  [routes.events.EventType.lightClientOptimisticUpdate]: (update: LightClientOptimisticUpdate) => void;
+};
+
+export type LightClientRestEmitter = MittEmitter<LightClientRestEvents>;
+
+export class LightClientRestTransport implements LightClientTransport {
+  private controller = new AbortController();
+  private readonly eventEmitter: LightClientRestEmitter = mitt();
+  private subscribedEventstream = false;
+
+  constructor(private readonly api: ApiClient) {}
+
+  async getUpdates(
+    startPeriod: SyncPeriod,
+    count: number
+  ): Promise<
+    {
+      version: ForkName;
+      data: LightClientUpdate;
+    }[]
+  > {
+    const res = await this.api.lightclient.getLightClientUpdatesByRange({startPeriod, count});
+    const updates = res.value();
+    const {versions} = res.meta();
+    return updates.map((data, i) => ({data, version: versions[i]}));
+  }
+
+  async getOptimisticUpdate(): Promise<{version: ForkName; data: LightClientOptimisticUpdate}> {
+    const res = await this.api.lightclient.getLightClientOptimisticUpdate();
+    return {version: res.meta().version, data: res.value()};
+  }
+
+  async getFinalityUpdate(): Promise<{version: ForkName; data: LightClientFinalityUpdate}> {
+    const res = await this.api.lightclient.getLightClientFinalityUpdate();
+    return {version: res.meta().version, data: res.value()};
+  }
+
+  async getBootstrap(blockRoot: string): Promise<{version: ForkName; data: LightClientBootstrap}> {
+    const res = await this.api.lightclient.getLightClientBootstrap({blockRoot});
+    return {version: res.meta().version, data: res.value()};
+  }
+
+  onOptimisticUpdate(handler: (optimisticUpdate: LightClientOptimisticUpdate) => void): void {
+    this.subscribeEventstream();
+    this.eventEmitter.on(routes.events.EventType.lightClientOptimisticUpdate, handler);
+  }
+
+  onFinalityUpdate(handler: (finalityUpdate: LightClientFinalityUpdate) => void): void {
+    this.subscribeEventstream();
+    this.eventEmitter.on(routes.events.EventType.lightClientFinalityUpdate, handler);
+  }
+
+  private subscribeEventstream(): void {
+    if (this.subscribedEventstream) {
+      return;
+    }
+
+    void this.api.events.eventstream({
+      topics: [routes.events.EventType.lightClientOptimisticUpdate, routes.events.EventType.lightClientFinalityUpdate],
+      signal: this.controller.signal,
+      onEvent: (event) => {
+        switch (event.type) {
+          case routes.events.EventType.lightClientOptimisticUpdate:
+            this.eventEmitter.emit(routes.events.EventType.lightClientOptimisticUpdate, event.message.data);
+            break;
+
+          case routes.events.EventType.lightClientFinalityUpdate:
+            this.eventEmitter.emit(routes.events.EventType.lightClientFinalityUpdate, event.message.data);
+            break;
+        }
+      },
+    });
+    this.subscribedEventstream = true;
+  }
+}

package/src/transport.ts

@@ -0,0 +1,2 @@
+// This file exists to have proper namespace for the web bundle
+export * from "./transport/index.js";

package/src/types.ts

@@ -0,0 +1,20 @@
+import type {PublicKey} from "@chainsafe/bls/types";
+import {LightClientHeader, LightClientUpdate, SyncPeriod} from "@lodestar/types";
+
+export type LightClientStoreFast = {
+  snapshot: LightClientSnapshotFast;
+  bestUpdates: Map<SyncPeriod, LightClientUpdate>;
+};
+
+export type LightClientSnapshotFast = {
+  /** Beacon block header */
+  header: LightClientHeader;
+  /** Sync committees corresponding to the header */
+  currentSyncCommittee: SyncCommitteeFast;
+  nextSyncCommittee: SyncCommitteeFast;
+};
+
+export type SyncCommitteeFast = {
+  pubkeys: PublicKey[];
+  aggregatePubkey: PublicKey;
+};

package/src/utils/api.ts

@@ -0,0 +1,19 @@
+import {ApiClient, ApiRequestInit, getClient} from "@lodestar/api";
+import {ChainForkConfig, createChainForkConfig} from "@lodestar/config";
+import {NetworkName, networksChainConfig} from "@lodestar/config/networks";
+
+export function getApiFromUrl(url: string, network: NetworkName, init?: ApiRequestInit): ApiClient {
+  if (!(network in networksChainConfig)) {
+    throw Error(`Invalid network name "${network}". Valid options are: ${Object.keys(networksChainConfig).join()}`);
+  }
+
+  return getClient({urls: [url], globalInit: init}, {config: createChainForkConfig(networksChainConfig[network])});
+}
+
+export function getChainForkConfigFromNetwork(network: NetworkName): ChainForkConfig {
+  if (!(network in networksChainConfig)) {
+    throw Error(`Invalid network name "${network}". Valid options are: ${Object.keys(networksChainConfig).join()}`);
+  }
+
+  return createChainForkConfig(networksChainConfig[network]);
+}

package/src/utils/chunkify.ts

@@ -0,0 +1,26 @@
+/**
+ * Split an inclusive range into a sequence of contiguous inclusive ranges
+ * ```
+ * [[a,b], [c,d] ... Sn] = chunkifyInclusiveRange([a,z], n)
+ * // where
+ * [a,z] = [a,b] U [c,d] U ... U Sn
+ * ```
+ * @param from range start inclusive
+ * @param to range end inclusive
+ * @param chunks Maximum number of chunks, if range is big enough
+ */
+export function chunkifyInclusiveRange(from: number, to: number, itemsPerChunk: number): number[][] {
+  if (itemsPerChunk < 1) itemsPerChunk = 1;
+  const totalItems = to - from + 1;
+  // Enforce chunkCount >= 1
+  const chunkCount = Math.max(Math.ceil(totalItems / itemsPerChunk), 1);
+
+  const chunks: number[][] = [];
+  for (let i = 0; i < chunkCount; i++) {
+    const _from = from + i * itemsPerChunk;
+    const _to = Math.min(from + (i + 1) * itemsPerChunk - 1, to);
+    chunks.push([_from, _to]);
+    if (_to >= to) break;
+  }
+  return chunks;
+}

package/src/utils/clock.ts

@@ -0,0 +1,45 @@
+import {ChainConfig} from "@lodestar/config";
+import {EPOCHS_PER_SYNC_COMMITTEE_PERIOD, SLOTS_PER_EPOCH} from "@lodestar/params";
+import {Epoch, Slot, SyncPeriod} from "@lodestar/types";
+
+export function getCurrentSlot(config: ChainConfig, genesisTime: number): Slot {
+  const diffInSeconds = Date.now() / 1000 - genesisTime;
+  return Math.floor(diffInSeconds / config.SECONDS_PER_SLOT);
+}
+
+/** Returns the slot if the internal clock were advanced by `toleranceSec`. */
+export function slotWithFutureTolerance(config: ChainConfig, genesisTime: number, toleranceSec: number): Slot {
+  // this is the same to getting slot at now + toleranceSec
+  return getCurrentSlot(config, genesisTime - toleranceSec);
+}
+
+/**
+ * Return the epoch number at the given slot.
+ */
+export function computeEpochAtSlot(slot: Slot): Epoch {
+  return Math.floor(slot / SLOTS_PER_EPOCH);
+}
+
+/**
+ * Return the sync committee period at slot
+ */
+export function computeSyncPeriodAtSlot(slot: Slot): SyncPeriod {
+  return computeSyncPeriodAtEpoch(computeEpochAtSlot(slot));
+}
+
+/**
+ * Return the sync committee period at epoch
+ */
+export function computeSyncPeriodAtEpoch(epoch: Epoch): SyncPeriod {
+  return Math.floor(epoch / EPOCHS_PER_SYNC_COMMITTEE_PERIOD);
+}
+
+export function timeUntilNextEpoch(config: Pick<ChainConfig, "SECONDS_PER_SLOT">, genesisTime: number): number {
+  const milliSecondsPerEpoch = SLOTS_PER_EPOCH * config.SECONDS_PER_SLOT * 1000;
+  const msFromGenesis = Date.now() - genesisTime * 1000;
+  if (msFromGenesis >= 0) {
+    return milliSecondsPerEpoch - (msFromGenesis % milliSecondsPerEpoch);
+  }
+
+  return Math.abs(msFromGenesis % milliSecondsPerEpoch);
+}

package/src/utils/domain.ts

@@ -0,0 +1,44 @@
+// Only used by processDeposit +  lightclient
+
+import {Type} from "@chainsafe/ssz";
+import {Domain, DomainType, Epoch, Root, Version, phase0, ssz} from "@lodestar/types";
+
+/**
+ * Return the domain for the [[domainType]] and [[forkVersion]].
+ */
+export function computeDomain(domainType: DomainType, forkVersion: Version, genesisValidatorRoot: Root): Uint8Array {
+  const forkDataRoot = computeForkDataRoot(forkVersion, genesisValidatorRoot);
+  const domain = new Uint8Array(32);
+  domain.set(domainType, 0);
+  domain.set(forkDataRoot.slice(0, 28), 4);
+  return domain;
+}
+
+/**
+ * Return the ForkVersion at an epoch from a Fork type
+ */
+export function getForkVersion(fork: phase0.Fork, epoch: Epoch): Version {
+  return epoch < fork.epoch ? fork.previousVersion : fork.currentVersion;
+}
+
+/**
+ * Used primarily in signature domains to avoid collisions across forks/chains.
+ */
+export function computeForkDataRoot(currentVersion: Version, genesisValidatorsRoot: Root): Uint8Array {
+  const forkData: phase0.ForkData = {
+    currentVersion,
+    genesisValidatorsRoot,
+  };
+  return ssz.phase0.ForkData.hashTreeRoot(forkData);
+}
+
+/**
+ * Return the signing root of an object by calculating the root of the object-domain tree.
+ */
+export function computeSigningRoot<T>(type: Type<T>, sszObject: T, domain: Domain): Uint8Array {
+  const domainWrappedObject: phase0.SigningData = {
+    objectRoot: type.hashTreeRoot(sszObject),
+    domain,
+  };
+  return ssz.phase0.SigningData.hashTreeRoot(domainWrappedObject);
+}

package/src/utils/index.ts

@@ -0,0 +1,8 @@
+export * from "./api.js";
+export * from "./chunkify.js";
+export * from "./clock.js";
+export * from "./domain.js";
+export * from "./logger.js";
+export * from "./update.js";
+export * from "./utils.js";
+export * from "./verifyMerkleBranch.js";

package/src/utils/logger.ts

@@ -0,0 +1,29 @@
+/**
+ * biome-ignore lint/suspicious/noExplicitAny: We need to use `any` type here
+ * biome-ignore-all lint/suspicious/noConsole: The logger need to use the console
+ * */
+export type LogHandler = (message: string, context?: any, error?: Error) => void;
+
+export type ILcLogger = {
+  error: LogHandler;
+  warn: LogHandler;
+  info: LogHandler;
+  debug: LogHandler;
+};
+
+/**
+ * With `console` module and ignoring debug logs
+ */
+export function getConsoleLogger(opts?: {logDebug?: boolean}): ILcLogger {
+  return {
+    error: console.error,
+    warn: console.warn,
+    info: console.log,
+    debug: opts?.logDebug ? console.log : () => {},
+  };
+}
+
+/**
+ * @deprecated - Use `getConsoleLogger` instead.
+ */
+export const getLcLoggerConsole = getConsoleLogger;

package/src/utils/map.ts

@@ -0,0 +1,20 @@
+/**
+ * Prune an arbitrary set removing the first keys to have a set.size === maxItems.
+ * Returns the count of deleted items.
+ */
+export function pruneSetToMax<T>(set: Set<T> | Map<T, unknown>, maxItems: number): number {
+  let itemsToDelete = set.size - maxItems;
+  const deletedItems = Math.max(0, itemsToDelete);
+
+  if (itemsToDelete > 0) {
+    for (const key of set.keys()) {
+      set.delete(key);
+      itemsToDelete--;
+      if (itemsToDelete <= 0) {
+        break;
+      }
+    }
+  }
+
+  return deletedItems;
+}

package/src/utils/normalizeMerkleBranch.ts

@@ -0,0 +1,15 @@
+import {ZERO_HASH} from "../spec/utils.js";
+
+export const SYNC_COMMITTEES_DEPTH = 4;
+export const SYNC_COMMITTEES_INDEX = 11;
+
+/**
+ * Given merkle branch ``branch``, extend its depth according to ``depth``
+ * If given ``depth`` is less than the depth of ``branch``, it will return
+ * unmodified ``branch``
+ */
+export function normalizeMerkleBranch(branch: Uint8Array[], depth: number): Uint8Array[] {
+  const numExtraDepth = depth - branch.length;
+
+  return [...Array.from({length: numExtraDepth}, () => ZERO_HASH), ...branch];
+}

package/src/utils/update.ts

@@ -0,0 +1,30 @@
+import {SYNC_COMMITTEE_SIZE} from "@lodestar/params";
+import {Slot} from "@lodestar/types";
+
+export type LightclientUpdateStats = {
+  isFinalized: boolean;
+  participation: number;
+  slot: Slot;
+};
+
+/**
+ * Returns the update with more bits. On ties, newUpdate is the better
+ *
+ * Spec v1.0.1
+ * ```python
+ * max(store.valid_updates, key=lambda update: sum(update.sync_committee_bits)))
+ * ```
+ */
+export function isBetterUpdate(prev: LightclientUpdateStats, next: LightclientUpdateStats): boolean {
+  // Finalized if participation is over 66%
+  if (!prev.isFinalized && next.isFinalized && next.participation * 3 > SYNC_COMMITTEE_SIZE * 2) {
+    return true;
+  }
+
+  // Higher bit count
+  if (prev.participation > next.participation) return false;
+  if (prev.participation < next.participation) return true;
+
+  // else keep the oldest, lowest chance or re-org and requires less updating
+  return prev.slot > next.slot;
+}

package/src/utils/utils.ts

@@ -0,0 +1,95 @@
+import bls from "@chainsafe/bls";
+import type {PublicKey} from "@chainsafe/bls/types";
+import {BitArray} from "@chainsafe/ssz";
+import {ApiClient} from "@lodestar/api";
+import {Bytes32, Root, altair, ssz} from "@lodestar/types";
+import {BeaconBlockHeader} from "@lodestar/types/phase0";
+import {GenesisData} from "../index.js";
+import {SyncCommitteeFast} from "../types.js";
+
+export function sumBits(bits: BitArray): number {
+  return bits.getTrueBitIndexes().length;
+}
+
+export function isZeroHash(root: Root): boolean {
+  for (let i = 0; i < root.length; i++) {
+    if (root[i] !== 0) {
+      return false;
+    }
+  }
+  return true;
+}
+
+export function assertZeroHashes(rootArray: Root[], expectedLength: number, errorMessage: string): void {
+  if (rootArray.length !== expectedLength) {
+    throw Error(`Wrong length ${errorMessage}`);
+  }
+
+  for (const root of rootArray) {
+    if (!isZeroHash(root)) {
+      throw Error(`Not zeroed ${errorMessage}`);
+    }
+  }
+}
+
+/**
+ * Util to guarantee that all bits have a corresponding pubkey
+ */
+export function getParticipantPubkeys<T>(pubkeys: T[], bits: BitArray): T[] {
+  // BitArray.intersectValues() checks the length is correct
+  return bits.intersectValues(pubkeys);
+}
+
+export function toBlockHeader(block: altair.BeaconBlock): BeaconBlockHeader {
+  return {
+    slot: block.slot,
+    proposerIndex: block.proposerIndex,
+    parentRoot: block.parentRoot,
+    stateRoot: block.stateRoot,
+    bodyRoot: ssz.altair.BeaconBlockBody.hashTreeRoot(block.body),
+  };
+}
+
+function deserializePubkeys(pubkeys: altair.LightClientUpdate["nextSyncCommittee"]["pubkeys"]): PublicKey[] {
+  return pubkeys.map((pk) => bls.PublicKey.fromBytes(pk));
+}
+
+function serializePubkeys(pubkeys: PublicKey[]): altair.LightClientUpdate["nextSyncCommittee"]["pubkeys"] {
+  return pubkeys.map((pk) => pk.toBytes());
+}
+
+export function deserializeSyncCommittee(syncCommittee: altair.SyncCommittee): SyncCommitteeFast {
+  return {
+    pubkeys: deserializePubkeys(syncCommittee.pubkeys),
+    aggregatePubkey: bls.PublicKey.fromBytes(syncCommittee.aggregatePubkey),
+  };
+}
+
+export function serializeSyncCommittee(syncCommittee: SyncCommitteeFast): altair.SyncCommittee {
+  return {
+    pubkeys: serializePubkeys(syncCommittee.pubkeys),
+    aggregatePubkey: syncCommittee.aggregatePubkey.toBytes(),
+  };
+}
+
+export function isEmptyHeader(header: BeaconBlockHeader): boolean {
+  const emptyValue = ssz.phase0.BeaconBlockHeader.defaultValue();
+  return ssz.phase0.BeaconBlockHeader.equals(emptyValue, header);
+}
+
+// Thanks https://github.com/iliakan/detect-node/blob/master/index.esm.js
+export const isNode =
+  Object.prototype.toString.call(typeof process !== "undefined" ? process : 0) === "[object process]";
+
+export async function getGenesisData(api: Pick<ApiClient, "beacon">): Promise<GenesisData> {
+  const {genesisTime, genesisValidatorsRoot} = (await api.beacon.getGenesis()).value();
+
+  return {
+    genesisTime,
+    genesisValidatorsRoot,
+  };
+}
+
+export async function getFinalizedSyncCheckpoint(api: Pick<ApiClient, "beacon">): Promise<Bytes32> {
+  return (await api.beacon.getStateFinalityCheckpoints({stateId: "head"})).value().finalized.root;
+}

package/src/utils/verifyMerkleBranch.ts

@@ -0,0 +1,29 @@
+import {hasher} from "@chainsafe/persistent-merkle-tree";
+import {byteArrayEquals} from "@chainsafe/ssz";
+
+export const SYNC_COMMITTEES_DEPTH = 4;
+export const SYNC_COMMITTEES_INDEX = 11;
+
+/**
+ * Verify that the given ``leaf`` is on the merkle branch ``proof``
+ * starting with the given ``root``.
+ *
+ * Browser friendly version of verifyMerkleBranch
+ */
+export function isValidMerkleBranch(
+  leaf: Uint8Array,
+  proof: Uint8Array[],
+  depth: number,
+  index: number,
+  root: Uint8Array
+): boolean {
+  let value = leaf;
+  for (let i = 0; i < depth; i++) {
+    if (Math.floor(index / 2 ** i) % 2) {
+      value = hasher.digest64(proof[i], value);
+    } else {
+      value = hasher.digest64(value, proof[i]);
+    }
+  }
+  return byteArrayEquals(value, root);
+}

package/src/utils.ts

@@ -0,0 +1,2 @@
+// This file exists to have proper namespace for the web bundle
+export * from "./utils/index.js";