@lodestar/api 1.35.0-dev.f80d2d52da → 1.35.0-dev.fcf8d024ea

package/src/beacon/routes/lightclient.ts

@@ -0,0 +1,241 @@
+import {ListCompositeType, ValueOf} from "@chainsafe/ssz";
+import {BeaconConfig, ChainForkConfig, createBeaconConfig} from "@lodestar/config";
+import {NetworkName, genesisData} from "@lodestar/config/networks";
+import {ForkName, SLOTS_PER_EPOCH, ZERO_HASH} from "@lodestar/params";
+import {
+  LightClientBootstrap,
+  LightClientFinalityUpdate,
+  LightClientOptimisticUpdate,
+  LightClientUpdate,
+  SyncPeriod,
+  ssz,
+} from "@lodestar/types";
+import {fromHex} from "@lodestar/utils";
+import {
+  EmptyArgs,
+  EmptyMeta,
+  EmptyMetaCodec,
+  EmptyRequest,
+  EmptyRequestCodec,
+  WithVersion,
+} from "../../utils/codecs.js";
+import {getPostAltairForkTypes, toForkName} from "../../utils/fork.js";
+import {Endpoint, RouteDefinitions, Schema} from "../../utils/index.js";
+import {MetaHeader, VersionCodec, VersionMeta} from "../../utils/metadata.js";
+
+export const HashListType = new ListCompositeType(ssz.Root, 10000);
+export type HashList = ValueOf<typeof HashListType>;
+
+export type Endpoints = {
+  /**
+   * Returns an array of best updates given a `startPeriod` and `count` number of sync committee period to return.
+   * Best is defined by (in order of priority):
+   * - Is finalized update
+   * - Has most bits
+   * - Oldest update
+   */
+  getLightClientUpdatesByRange: Endpoint<
+    "GET",
+    {startPeriod: SyncPeriod; count: number},
+    {query: {start_period: number; count: number}},
+    LightClientUpdate[],
+    {versions: ForkName[]}
+  >;
+
+  /**
+   * 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.
+   */
+  getLightClientOptimisticUpdate: Endpoint<
+    // ⏎
+    "GET",
+    EmptyArgs,
+    EmptyRequest,
+    LightClientOptimisticUpdate,
+    VersionMeta
+  >;
+
+  getLightClientFinalityUpdate: Endpoint<
+    // ⏎
+    "GET",
+    EmptyArgs,
+    EmptyRequest,
+    LightClientFinalityUpdate,
+    VersionMeta
+  >;
+
+  /**
+   * 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.
+   */
+  getLightClientBootstrap: Endpoint<
+    "GET",
+    {blockRoot: string},
+    {params: {block_root: string}},
+    LightClientBootstrap,
+    VersionMeta
+  >;
+
+  /**
+   * Returns an array of sync committee hashes based on the provided period and count
+   */
+  getLightClientCommitteeRoot: Endpoint<
+    "GET",
+    {startPeriod: SyncPeriod; count: number},
+    {query: {start_period: number; count: number}},
+    HashList,
+    EmptyMeta
+  >;
+};
+
+export function getDefinitions(config: ChainForkConfig): RouteDefinitions<Endpoints> {
+  // Cache config so fork digests don't need to be recomputed
+  let beaconConfig: BeaconConfig | undefined;
+
+  const cachedBeaconConfig = (): BeaconConfig => {
+    if (beaconConfig === undefined) {
+      const genesisValidatorsRoot = genesisData[config.CONFIG_NAME as NetworkName]?.genesisValidatorsRoot;
+      beaconConfig = createBeaconConfig(config, genesisValidatorsRoot ? fromHex(genesisValidatorsRoot) : ZERO_HASH);
+    }
+    return beaconConfig;
+  };
+
+  return {
+    getLightClientUpdatesByRange: {
+      url: "/eth/v1/beacon/light_client/updates",
+      method: "GET",
+      req: {
+        writeReq: ({startPeriod, count}) => ({query: {start_period: startPeriod, count}}),
+        parseReq: ({query}) => ({startPeriod: query.start_period, count: query.count}),
+        schema: {query: {start_period: Schema.UintRequired, count: Schema.UintRequired}},
+      },
+      resp: {
+        data: {
+          toJson: (data, meta) => {
+            const json: unknown[] = [];
+            for (const [i, update] of data.entries()) {
+              json.push(getPostAltairForkTypes(meta.versions[i]).LightClientUpdate.toJson(update));
+            }
+            return json;
+          },
+          fromJson: (data, meta) => {
+            const updates = data as unknown[];
+            const value: LightClientUpdate[] = [];
+            for (let i = 0; i < updates.length; i++) {
+              const version = meta.versions[i];
+              value.push(getPostAltairForkTypes(version).LightClientUpdate.fromJson(updates[i]));
+            }
+            return value;
+          },
+          serialize: (data, meta) => {
+            const chunks: Uint8Array[] = [];
+            for (const [i, update] of data.entries()) {
+              const version = meta.versions[i];
+              const config = cachedBeaconConfig();
+              const epoch = Math.floor(update.attestedHeader.beacon.slot / SLOTS_PER_EPOCH);
+              const forkDigest = config.forkBoundary2ForkDigest(config.getForkBoundaryAtEpoch(epoch));
+              const serialized = getPostAltairForkTypes(version).LightClientUpdate.serialize(update);
+              const length = ssz.UintNum64.serialize(4 + serialized.length);
+              chunks.push(length, forkDigest, serialized);
+            }
+            return Buffer.concat(chunks);
+          },
+          deserialize: (data) => {
+            let offset = 0;
+            const updates: LightClientUpdate[] = [];
+            while (offset < data.length) {
+              const length = ssz.UintNum64.deserialize(data.subarray(offset, offset + 8));
+              const forkDigest = ssz.ForkDigest.deserialize(data.subarray(offset + 8, offset + 12));
+              const {fork: version} = cachedBeaconConfig().forkDigest2ForkBoundary(forkDigest);
+              updates.push(
+                getPostAltairForkTypes(version).LightClientUpdate.deserialize(
+                  data.subarray(offset + 12, offset + 8 + length)
+                )
+              );
+              offset += 8 + length;
+            }
+            return updates;
+          },
+        },
+        meta: {
+          toJson: (meta) => meta,
+          fromJson: (val) => val as {versions: ForkName[]},
+          toHeadersObject: (meta) => ({
+            [MetaHeader.Version]: meta.versions.join(","),
+          }),
+          fromHeaders: (headers) => {
+            const versions = headers.getOrDefault(MetaHeader.Version, "");
+            return {versions: versions === "" ? [] : (versions.split(",") as ForkName[])};
+          },
+        },
+        transform: {
+          toResponse: (data, meta) => {
+            const updates = data as unknown[];
+            const resp: unknown[] = [];
+            for (let i = 0; i < updates.length; i++) {
+              resp.push({data: updates[i], version: (meta as {versions: string[]}).versions[i]});
+            }
+            return resp;
+          },
+          fromResponse: (resp) => {
+            if (!Array.isArray(resp)) {
+              throw Error("JSON is not an array");
+            }
+            const updates: LightClientUpdate[] = [];
+            const meta: {versions: ForkName[]} = {versions: []};
+            for (const {data, version} of resp as {data: LightClientUpdate; version: string}[]) {
+              updates.push(data);
+              meta.versions.push(toForkName(version));
+            }
+            return {data: updates, meta};
+          },
+        },
+      },
+    },
+    getLightClientOptimisticUpdate: {
+      url: "/eth/v1/beacon/light_client/optimistic_update",
+      method: "GET",
+      req: EmptyRequestCodec,
+      resp: {
+        data: WithVersion((fork) => getPostAltairForkTypes(fork).LightClientOptimisticUpdate),
+        meta: VersionCodec,
+      },
+    },
+    getLightClientFinalityUpdate: {
+      url: "/eth/v1/beacon/light_client/finality_update",
+      method: "GET",
+      req: EmptyRequestCodec,
+      resp: {
+        data: WithVersion((fork) => getPostAltairForkTypes(fork).LightClientFinalityUpdate),
+        meta: VersionCodec,
+      },
+    },
+    getLightClientBootstrap: {
+      url: "/eth/v1/beacon/light_client/bootstrap/{block_root}",
+      method: "GET",
+      req: {
+        writeReq: ({blockRoot}) => ({params: {block_root: blockRoot}}),
+        parseReq: ({params}) => ({blockRoot: params.block_root}),
+        schema: {params: {block_root: Schema.StringRequired}},
+      },
+      resp: {
+        data: WithVersion((fork) => getPostAltairForkTypes(fork).LightClientBootstrap),
+        meta: VersionCodec,
+      },
+    },
+    getLightClientCommitteeRoot: {
+      url: "/eth/v0/beacon/light_client/committee_root",
+      method: "GET",
+      req: {
+        writeReq: ({startPeriod, count}) => ({query: {start_period: startPeriod, count}}),
+        parseReq: ({query}) => ({startPeriod: query.start_period, count: query.count}),
+        schema: {query: {start_period: Schema.UintRequired, count: Schema.UintRequired}},
+      },
+      resp: {
+        data: HashListType,
+        meta: EmptyMetaCodec,
+      },
+    },
+  };
+}

package/src/beacon/routes/lodestar.ts

@@ -0,0 +1,456 @@
+import {ContainerType, ValueOf} from "@chainsafe/ssz";
+import {ChainForkConfig} from "@lodestar/config";
+import {Epoch, RootHex, Slot, ssz} from "@lodestar/types";
+import {
+  ArrayOf,
+  EmptyArgs,
+  EmptyMeta,
+  EmptyRequest,
+  EmptyRequestCodec,
+  EmptyResponseCodec,
+  EmptyResponseData,
+  JsonOnlyResponseCodec,
+} from "../../utils/codecs.js";
+import {Endpoint, RouteDefinitions, Schema} from "../../utils/index.js";
+import {
+  ExecutionOptimisticFinalizedAndVersionCodec,
+  ExecutionOptimisticFinalizedAndVersionMeta,
+} from "../../utils/metadata.js";
+import {StateArgs} from "./beacon/state.js";
+import {FilterGetPeers, NodePeer, PeerDirection, PeerState} from "./node.js";
+
+export type SyncChainDebugState = {
+  targetRoot: string | null;
+  targetSlot: number | null;
+  syncType: string;
+  status: string;
+  startEpoch: number;
+  peers: number;
+  // biome-ignore lint/suspicious/noExplicitAny: We need to use `any` type here
+  batches: any[];
+};
+
+export type GossipQueueItem = {
+  topic: unknown;
+  propagationSource: string;
+  data: Uint8Array;
+  addedTimeMs: number;
+  seenTimestampSec: number;
+};
+
+export type PeerScoreStat = {
+  peerId: string;
+  lodestarScore: number;
+  gossipScore: number;
+  ignoreNegativeGossipScore: boolean;
+  score: number;
+  lastUpdate: number;
+};
+
+export type GossipPeerScoreStat = {
+  peerId: string;
+  // + Other un-typed options
+};
+
+export type RegenQueueItem = {
+  key: string;
+  args: unknown;
+  addedTimeMs: number;
+};
+
+export type BlockProcessorQueueItem = {
+  blockSlots: Slot[];
+  jobOpts: Record<string, string | number | boolean | undefined>;
+  addedTimeMs: number;
+};
+
+export type StateCacheItem = {
+  slot: Slot;
+  root: RootHex;
+  /** Total number of reads */
+  reads: number;
+  /** Unix timestamp (ms) of the last read */
+  lastRead: number;
+  checkpointState: boolean;
+};
+
+export type LodestarNodePeer = NodePeer & {
+  agentVersion: string;
+  status: unknown | null;
+  metadata: unknown | null;
+  agentClient: string;
+  lastReceivedMsgUnixTsMs: number;
+  lastStatusUnixTsMs: number;
+  connectedUnixTsMs: number;
+};
+
+export type BlacklistedBlock = {root: RootHex; slot: Slot | null};
+
+export type LodestarThreadType = "main" | "network" | "discv5";
+
+const HistoricalSummariesResponseType = new ContainerType(
+  {
+    slot: ssz.Slot,
+    historicalSummaries: ssz.capella.HistoricalSummaries,
+    proof: ArrayOf(ssz.Bytes8),
+  },
+  {jsonCase: "eth2"}
+);
+
+export type HistoricalSummariesResponse = ValueOf<typeof HistoricalSummariesResponseType>;
+
+export type Endpoints = {
+  /** Trigger to write a heapdump to disk at `dirpath`. May take > 1min */
+  writeHeapdump: Endpoint<
+    "POST",
+    {thread?: LodestarThreadType; dirpath?: string},
+    {query: {thread?: LodestarThreadType; dirpath?: string}},
+    {filepath: string},
+    EmptyMeta
+  >;
+  /** Trigger to write 10m network thread profile to disk */
+  writeProfile: Endpoint<
+    "POST",
+    {
+      thread?: LodestarThreadType;
+      duration?: number;
+      dirpath?: string;
+    },
+    {query: {thread?: LodestarThreadType; duration?: number; dirpath?: string}},
+    {filepath: string},
+    EmptyMeta
+  >;
+  /** TODO: description */
+  getLatestWeakSubjectivityCheckpointEpoch: Endpoint<
+    // ⏎
+    "GET",
+    EmptyArgs,
+    EmptyRequest,
+    Epoch,
+    EmptyMeta
+  >;
+  /** TODO: description */
+  getSyncChainsDebugState: Endpoint<
+    // ⏎
+    "GET",
+    EmptyArgs,
+    EmptyRequest,
+    SyncChainDebugState[],
+    EmptyMeta
+  >;
+  /** Dump all items in a gossip queue, by gossipType */
+  getGossipQueueItems: Endpoint<
+    // ⏎
+    "GET",
+    {gossipType: string},
+    {params: {gossipType: string}},
+    unknown[],
+    EmptyMeta
+  >;
+  /** Dump all items in the regen queue */
+  getRegenQueueItems: Endpoint<
+    // ⏎
+    "GET",
+    EmptyArgs,
+    EmptyRequest,
+    RegenQueueItem[],
+    EmptyMeta
+  >;
+  /** Dump all items in the block processor queue */
+  getBlockProcessorQueueItems: Endpoint<
+    // ⏎
+    "GET",
+    EmptyArgs,
+    EmptyRequest,
+    BlockProcessorQueueItem[],
+    EmptyMeta
+  >;
+  /** Dump a summary of the states in the block state cache and checkpoint state cache */
+  getStateCacheItems: Endpoint<
+    // ⏎
+    "GET",
+    EmptyArgs,
+    EmptyRequest,
+    StateCacheItem[],
+    EmptyMeta
+  >;
+  /** Dump peer gossip stats by peer */
+  getGossipPeerScoreStats: Endpoint<
+    // ⏎
+    "GET",
+    EmptyArgs,
+    EmptyRequest,
+    GossipPeerScoreStat[],
+    EmptyMeta
+  >;
+  /** Dump lodestar score stats by peer */
+  getLodestarPeerScoreStats: Endpoint<
+    // ⏎
+    "GET",
+    EmptyArgs,
+    EmptyRequest,
+    PeerScoreStat[],
+    EmptyMeta
+  >;
+  /** Run GC with `global.gc()` */
+  runGC: Endpoint<
+    // ⏎
+    "POST",
+    EmptyArgs,
+    EmptyRequest,
+    EmptyResponseData,
+    EmptyMeta
+  >;
+  /** Drop all states in the state cache */
+  dropStateCache: Endpoint<
+    // ⏎
+    "POST",
+    EmptyArgs,
+    EmptyRequest,
+    EmptyResponseData,
+    EmptyMeta
+  >;
+
+  /** Connect to peer at this multiaddress */
+  connectPeer: Endpoint<
+    // ⏎
+    "POST",
+    {peerId: string; multiaddrs: string[]},
+    {query: {peerId: string; multiaddr: string[]}},
+    EmptyResponseData,
+    EmptyMeta
+  >;
+  /** Disconnect peer */
+  disconnectPeer: Endpoint<
+    // ⏎
+    "POST",
+    {peerId: string},
+    {query: {peerId: string}},
+    EmptyResponseData,
+    EmptyMeta
+  >;
+  /** Same to node api with new fields */
+  getPeers: Endpoint<
+    "GET",
+    FilterGetPeers,
+    {query: {state?: PeerState[]; direction?: PeerDirection[]}},
+    LodestarNodePeer[],
+    {count: number}
+  >;
+
+  /** Returns root/slot of blacklisted blocks */
+  getBlacklistedBlocks: Endpoint<
+    // ⏎
+    "GET",
+    EmptyArgs,
+    EmptyRequest,
+    BlacklistedBlock[],
+    EmptyMeta
+  >;
+
+  /** Returns historical summaries and proof for a given state ID */
+  getHistoricalSummaries: Endpoint<
+    // ⏎
+    "GET",
+    StateArgs,
+    {params: {state_id: string}},
+    HistoricalSummariesResponse,
+    ExecutionOptimisticFinalizedAndVersionMeta
+  >;
+
+  /** Dump Discv5 Kad values */
+  discv5GetKadValues: Endpoint<
+    // ⏎
+    "GET",
+    EmptyArgs,
+    EmptyRequest,
+    string[],
+    EmptyMeta
+  >;
+
+  /**
+   * Dump level-db entry keys for a given Bucket declared in code, or for all buckets.
+   */
+  dumpDbBucketKeys: Endpoint<
+    "GET",
+    {
+      /** Must be the string name of a bucket entry: `allForks_blockArchive` */
+      bucket: string;
+    },
+    {params: {bucket: string}},
+    string[],
+    EmptyMeta
+  >;
+
+  /** Return all entries in the StateArchive index with bucket index_stateArchiveRootIndex */
+  dumpDbStateIndex: Endpoint<
+    // ⏎
+    "GET",
+    EmptyArgs,
+    EmptyRequest,
+    {root: RootHex; slot: Slot}[],
+    EmptyMeta
+  >;
+};
+
+export function getDefinitions(_config: ChainForkConfig): RouteDefinitions<Endpoints> {
+  return {
+    writeHeapdump: {
+      url: "/eth/v1/lodestar/write_heapdump",
+      method: "POST",
+      req: {
+        writeReq: ({thread, dirpath}) => ({query: {thread, dirpath}}),
+        parseReq: ({query}) => ({thread: query.thread, dirpath: query.dirpath}),
+        schema: {query: {thread: Schema.String, dirpath: Schema.String}},
+      },
+      resp: JsonOnlyResponseCodec,
+    },
+    writeProfile: {
+      url: "/eth/v1/lodestar/write_profile",
+      method: "POST",
+      req: {
+        writeReq: ({thread, duration, dirpath}) => ({query: {thread, duration, dirpath}}),
+        parseReq: ({query}) => ({thread: query.thread, duration: query.duration, dirpath: query.dirpath}),
+        schema: {query: {thread: Schema.String, duration: Schema.Uint, dirpath: Schema.String}},
+      },
+      resp: JsonOnlyResponseCodec,
+    },
+    getLatestWeakSubjectivityCheckpointEpoch: {
+      url: "/eth/v1/lodestar/ws_epoch",
+      method: "GET",
+      req: EmptyRequestCodec,
+      resp: JsonOnlyResponseCodec,
+    },
+    getSyncChainsDebugState: {
+      url: "/eth/v1/lodestar/sync_chains_debug_state",
+      method: "GET",
+      req: EmptyRequestCodec,
+      resp: JsonOnlyResponseCodec,
+    },
+    getGossipQueueItems: {
+      url: "/eth/v1/lodestar/gossip_queue_items/:gossipType",
+      method: "GET",
+      req: {
+        writeReq: ({gossipType}) => ({params: {gossipType}}),
+        parseReq: ({params}) => ({gossipType: params.gossipType}),
+        schema: {params: {gossipType: Schema.StringRequired}},
+      },
+      resp: JsonOnlyResponseCodec,
+    },
+    getRegenQueueItems: {
+      url: "/eth/v1/lodestar/regen_queue_items",
+      method: "GET",
+      req: EmptyRequestCodec,
+      resp: JsonOnlyResponseCodec,
+    },
+    getBlockProcessorQueueItems: {
+      url: "/eth/v1/lodestar/block_processor_queue_items",
+      method: "GET",
+      req: EmptyRequestCodec,
+      resp: JsonOnlyResponseCodec,
+    },
+    getStateCacheItems: {
+      url: "/eth/v1/lodestar/state_cache_items",
+      method: "GET",
+      req: EmptyRequestCodec,
+      resp: JsonOnlyResponseCodec,
+    },
+    getGossipPeerScoreStats: {
+      url: "/eth/v1/lodestar/gossip_peer_score_stats",
+      method: "GET",
+      req: EmptyRequestCodec,
+      resp: JsonOnlyResponseCodec,
+    },
+    getLodestarPeerScoreStats: {
+      url: "/eth/v1/lodestar/lodestar_peer_score_stats",
+      method: "GET",
+      req: EmptyRequestCodec,
+      resp: JsonOnlyResponseCodec,
+    },
+    runGC: {
+      url: "/eth/v1/lodestar/gc",
+      method: "POST",
+      req: EmptyRequestCodec,
+      resp: EmptyResponseCodec,
+    },
+    dropStateCache: {
+      url: "/eth/v1/lodestar/drop_state_cache",
+      method: "POST",
+      req: EmptyRequestCodec,
+      resp: EmptyResponseCodec,
+    },
+    connectPeer: {
+      url: "/eth/v1/lodestar/connect_peer",
+      method: "POST",
+      req: {
+        writeReq: ({peerId, multiaddrs}) => ({query: {peerId, multiaddr: multiaddrs}}),
+        parseReq: ({query}) => ({peerId: query.peerId, multiaddrs: query.multiaddr}),
+        schema: {query: {peerId: Schema.StringRequired, multiaddr: Schema.StringArray}},
+      },
+      resp: EmptyResponseCodec,
+    },
+    disconnectPeer: {
+      url: "/eth/v1/lodestar/disconnect_peer",
+      method: "POST",
+      req: {
+        writeReq: ({peerId}) => ({query: {peerId}}),
+        parseReq: ({query}) => ({peerId: query.peerId}),
+        schema: {query: {peerId: Schema.StringRequired}},
+      },
+      resp: EmptyResponseCodec,
+    },
+    getPeers: {
+      url: "/eth/v1/lodestar/peers",
+      method: "GET",
+      req: {
+        writeReq: ({state, direction}) => ({query: {state, direction}}),
+        parseReq: ({query}) => ({state: query.state, direction: query.direction}),
+        schema: {query: {state: Schema.StringArray, direction: Schema.StringArray}},
+      },
+      resp: JsonOnlyResponseCodec,
+    },
+    getBlacklistedBlocks: {
+      url: "/eth/v1/lodestar/blacklisted_blocks",
+      method: "GET",
+      req: EmptyRequestCodec,
+      resp: JsonOnlyResponseCodec,
+    },
+    getHistoricalSummaries: {
+      url: "/eth/v1/lodestar/states/{state_id}/historical_summaries",
+      method: "GET",
+      req: {
+        writeReq: ({stateId}) => ({params: {state_id: stateId.toString()}}),
+        parseReq: ({params}) => ({stateId: params.state_id}),
+        schema: {
+          params: {state_id: Schema.StringRequired},
+        },
+      },
+      resp: {
+        data: HistoricalSummariesResponseType,
+        meta: ExecutionOptimisticFinalizedAndVersionCodec,
+      },
+    },
+    discv5GetKadValues: {
+      url: "/eth/v1/debug/discv5_kad_values",
+      method: "GET",
+      req: EmptyRequestCodec,
+      resp: JsonOnlyResponseCodec,
+    },
+    dumpDbBucketKeys: {
+      url: "/eth/v1/debug/dump_db_bucket_keys/:bucket",
+      method: "GET",
+      req: {
+        writeReq: ({bucket}) => ({params: {bucket}}),
+        parseReq: ({params}) => ({bucket: params.bucket}),
+        schema: {params: {bucket: Schema.String}},
+      },
+      resp: JsonOnlyResponseCodec,
+    },
+    dumpDbStateIndex: {
+      url: "/eth/v1/debug/dump_db_state_index",
+      method: "GET",
+      req: EmptyRequestCodec,
+      resp: JsonOnlyResponseCodec,
+    },
+  };
+}