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

package/src/beacon/routes/debug.ts

@@ -0,0 +1,231 @@
+import {ContainerType, Type, ValueOf} from "@chainsafe/ssz";
+import {ChainForkConfig} from "@lodestar/config";
+import {BeaconState, StringType, fulu, ssz} from "@lodestar/types";
+import {
+  ArrayOf,
+  EmptyArgs,
+  EmptyMeta,
+  EmptyMetaCodec,
+  EmptyRequest,
+  EmptyRequestCodec,
+  WithVersion,
+} from "../../utils/codecs.js";
+import {
+  ExecutionOptimisticFinalizedAndVersionCodec,
+  ExecutionOptimisticFinalizedAndVersionMeta,
+} from "../../utils/metadata.js";
+import {Schema} from "../../utils/schema.js";
+import {Endpoint, RouteDefinitions} from "../../utils/types.js";
+import {WireFormat} from "../../utils/wireFormat.js";
+import {BlockArgs} from "./beacon/block.js";
+import {StateArgs} from "./beacon/state.js";
+
+const stringType = new StringType();
+const ProtoNodeType = new ContainerType(
+  {
+    executionPayloadBlockHash: stringType,
+    executionPayloadNumber: ssz.UintNum64,
+    executionStatus: stringType,
+    slot: ssz.Slot,
+    blockRoot: stringType,
+    parentRoot: stringType,
+    stateRoot: stringType,
+    targetRoot: stringType,
+    timeliness: ssz.Boolean,
+    justifiedEpoch: ssz.Epoch,
+    justifiedRoot: stringType,
+    finalizedEpoch: ssz.Epoch,
+    finalizedRoot: stringType,
+    unrealizedJustifiedEpoch: ssz.Epoch,
+    unrealizedJustifiedRoot: stringType,
+    unrealizedFinalizedEpoch: ssz.Epoch,
+    unrealizedFinalizedRoot: stringType,
+    parent: stringType,
+    weight: ssz.Uint32,
+    bestChild: stringType,
+    bestDescendant: stringType,
+  },
+  {jsonCase: "eth2"}
+);
+const DebugChainHeadType = new ContainerType(
+  {
+    slot: ssz.Slot,
+    root: stringType,
+    executionOptimistic: ssz.Boolean,
+  },
+  {jsonCase: "eth2"}
+);
+
+const ForkChoiceNodeType = new ContainerType(
+  {
+    slot: ssz.Slot,
+    blockRoot: stringType,
+    parentRoot: stringType,
+    justifiedEpoch: ssz.Epoch,
+    finalizedEpoch: ssz.Epoch,
+    weight: ssz.UintNum64,
+    validity: new StringType<"valid" | "invalid" | "optimistic">(),
+    executionBlockHash: stringType,
+  },
+  {jsonCase: "eth2"}
+);
+const ForkChoiceResponseType = new ContainerType(
+  {
+    justifiedCheckpoint: ssz.phase0.Checkpoint,
+    finalizedCheckpoint: ssz.phase0.Checkpoint,
+    forkChoiceNodes: ArrayOf(ForkChoiceNodeType),
+  },
+  {jsonCase: "eth2"}
+);
+
+const ProtoNodeListType = ArrayOf(ProtoNodeType);
+const DebugChainHeadListType = ArrayOf(DebugChainHeadType);
+
+type ProtoNodeList = ValueOf<typeof ProtoNodeListType>;
+type DebugChainHeadList = ValueOf<typeof DebugChainHeadListType>;
+type ForkChoiceResponse = ValueOf<typeof ForkChoiceResponseType>;
+
+export type Endpoints = {
+  /**
+   * Retrieves all possible chain heads (leaves of fork choice tree).
+   */
+  getDebugChainHeadsV2: Endpoint<
+    // ⏎
+    "GET",
+    EmptyArgs,
+    EmptyRequest,
+    DebugChainHeadList,
+    EmptyMeta
+  >;
+
+  /**
+   * Retrieves all current fork choice context
+   */
+  getDebugForkChoice: Endpoint<
+    // ⏎
+    "GET",
+    EmptyArgs,
+    EmptyRequest,
+    ForkChoiceResponse,
+    EmptyMeta
+  >;
+
+  /**
+   * Dump all ProtoArray's nodes to debug
+   */
+  getProtoArrayNodes: Endpoint<
+    // ⏎
+    "GET",
+    EmptyArgs,
+    EmptyRequest,
+    ProtoNodeList,
+    EmptyMeta
+  >;
+
+  /**
+   * Get full BeaconState object
+   * Returns full BeaconState object for given stateId.
+   * Depending on `Accept` header it can be returned either as json or as bytes serialized by SSZ
+   */
+  getStateV2: Endpoint<
+    "GET",
+    StateArgs,
+    {params: {state_id: string}},
+    BeaconState,
+    ExecutionOptimisticFinalizedAndVersionMeta
+  >;
+
+  /**
+   * Get data column sidecars
+   * Retrieves data column sidecars for a given block id.
+   */
+  getDebugDataColumnSidecars: Endpoint<
+    "GET",
+    BlockArgs & {
+      /**
+       * Array of indices for data column sidecars to request for in the specified block.
+       * This endpoint will only return columns that the node is actually custodying.
+       * If not specified, returns all data column sidecars that this node is custodying in the block.
+       */
+      indices?: number[];
+    },
+    {params: {block_id: string}; query: {indices?: number[]}},
+    fulu.DataColumnSidecars,
+    ExecutionOptimisticFinalizedAndVersionMeta
+  >;
+};
+
+export function getDefinitions(_config: ChainForkConfig): RouteDefinitions<Endpoints> {
+  return {
+    getDebugChainHeadsV2: {
+      url: "/eth/v2/debug/beacon/heads",
+      method: "GET",
+      req: EmptyRequestCodec,
+      resp: {
+        data: DebugChainHeadListType,
+        meta: EmptyMetaCodec,
+        onlySupport: WireFormat.json,
+      },
+    },
+    getDebugForkChoice: {
+      url: "/eth/v1/debug/fork_choice",
+      method: "GET",
+      req: EmptyRequestCodec,
+      resp: {
+        data: ForkChoiceResponseType,
+        meta: EmptyMetaCodec,
+        onlySupport: WireFormat.json,
+        transform: {
+          toResponse: (data) => ({
+            ...(data as ForkChoiceResponse),
+          }),
+          fromResponse: (resp) => ({
+            data: resp as ForkChoiceResponse,
+          }),
+        },
+      },
+    },
+    getProtoArrayNodes: {
+      url: "/eth/v0/debug/forkchoice",
+      method: "GET",
+      req: EmptyRequestCodec,
+      resp: {
+        data: ProtoNodeListType,
+        meta: EmptyMetaCodec,
+        onlySupport: WireFormat.json,
+      },
+    },
+    getStateV2: {
+      url: "/eth/v2/debug/beacon/states/{state_id}",
+      method: "GET",
+      req: {
+        writeReq: ({stateId}) => ({params: {state_id: stateId.toString()}}),
+        parseReq: ({params}) => ({stateId: params.state_id}),
+        schema: {
+          params: {state_id: Schema.StringRequired},
+        },
+      },
+      resp: {
+        data: WithVersion((fork) => ssz[fork].BeaconState as Type<BeaconState>),
+        meta: ExecutionOptimisticFinalizedAndVersionCodec,
+      },
+      init: {
+        // Default timeout is not sufficient to download state as JSON
+        timeoutMs: 5 * 60 * 1000,
+      },
+    },
+    getDebugDataColumnSidecars: {
+      url: "/eth/v1/debug/beacon/data_column_sidecars/{block_id}",
+      method: "GET",
+      req: {
+        writeReq: ({blockId, indices}) => ({params: {block_id: blockId.toString()}, query: {indices}}),
+        parseReq: ({params, query}) => ({blockId: params.block_id, indices: query.indices}),
+        schema: {params: {block_id: Schema.StringRequired}, query: {indices: Schema.UintArray}},
+      },
+      resp: {
+        data: ssz.fulu.DataColumnSidecars,
+        meta: ExecutionOptimisticFinalizedAndVersionCodec,
+      },
+    },
+  };
+}

package/src/beacon/routes/events.ts

@@ -0,0 +1,337 @@
+import {ContainerType, ListBasicType, ValueOf} from "@chainsafe/ssz";
+import {ChainForkConfig} from "@lodestar/config";
+import {ForkName, MAX_BLOB_COMMITMENTS_PER_BLOCK} from "@lodestar/params";
+import {
+  Attestation,
+  AttesterSlashing,
+  Epoch,
+  LightClientFinalityUpdate,
+  LightClientOptimisticUpdate,
+  RootHex,
+  SSEPayloadAttributes,
+  Slot,
+  StringType,
+  UintNum64,
+  altair,
+  capella,
+  electra,
+  phase0,
+  ssz,
+  sszTypesFor,
+} from "@lodestar/types";
+import {EmptyMeta, EmptyResponseCodec, EmptyResponseData} from "../../utils/codecs.js";
+import {getPostAltairForkTypes, getPostBellatrixForkTypes} from "../../utils/fork.js";
+import {Endpoint, RouteDefinitions, Schema} from "../../utils/index.js";
+import {VersionType} from "../../utils/metadata.js";
+
+const stringType = new StringType();
+export const blobSidecarSSE = new ContainerType(
+  {
+    blockRoot: stringType,
+    index: ssz.BlobIndex,
+    slot: ssz.Slot,
+    kzgCommitment: stringType,
+    versionedHash: stringType,
+  },
+  {typeName: "BlobSidecarSSE", jsonCase: "eth2"}
+);
+type BlobSidecarSSE = ValueOf<typeof blobSidecarSSE>;
+
+export const dataColumnSidecarSSE = new ContainerType(
+  {
+    blockRoot: stringType,
+    index: ssz.ColumnIndex,
+    slot: ssz.Slot,
+    kzgCommitments: new ListBasicType(stringType, MAX_BLOB_COMMITMENTS_PER_BLOCK),
+  },
+  {typeName: "DataColumnSidecarSSE", jsonCase: "eth2"}
+);
+type DataColumnSidecarSSE = ValueOf<typeof dataColumnSidecarSSE>;
+
+export enum EventType {
+  /**
+   * The node has finished processing, resulting in a new head. previous_duty_dependent_root is
+   * `get_block_root_at_slot(state, compute_start_slot_at_epoch(epoch - 1) - 1)` and
+   * current_duty_dependent_root is `get_block_root_at_slot(state, compute_start_slot_at_epoch(epoch) - 1)`.
+   * Both dependent roots use the genesis block root in the case of underflow.
+   */
+  head = "head",
+  /** The node has received a block (from P2P or API) that is successfully imported on the fork-choice `on_block` handler */
+  block = "block",
+  /** The node has received a block (from P2P or API) that passes validation rules of the `beacon_block` topic */
+  blockGossip = "block_gossip",
+  /** The node has received a valid attestation (from P2P or API) */
+  attestation = "attestation",
+  /** The node has received a valid SingleAttestation (from P2P or API) */
+  singleAttestation = "single_attestation",
+  /** The node has received a valid voluntary exit (from P2P or API) */
+  voluntaryExit = "voluntary_exit",
+  /** The node has received a valid proposer slashing (from P2P or API) */
+  proposerSlashing = "proposer_slashing",
+  /** The node has received a valid attester slashing (from P2P or API) */
+  attesterSlashing = "attester_slashing",
+  /** The node has received a valid blsToExecutionChange (from P2P or API) */
+  blsToExecutionChange = "bls_to_execution_change",
+  /** Finalized checkpoint has been updated */
+  finalizedCheckpoint = "finalized_checkpoint",
+  /** The node has reorganized its chain */
+  chainReorg = "chain_reorg",
+  /** The node has received a valid sync committee SignedContributionAndProof (from P2P or API) */
+  contributionAndProof = "contribution_and_proof",
+  /** New or better optimistic header update available */
+  lightClientOptimisticUpdate = "light_client_optimistic_update",
+  /** New or better finality update available */
+  lightClientFinalityUpdate = "light_client_finality_update",
+  /** Payload attributes for block proposal */
+  payloadAttributes = "payload_attributes",
+  /** The node has received a valid BlobSidecar (from P2P or API) */
+  blobSidecar = "blob_sidecar",
+  /** The node has received a valid DataColumnSidecar (from P2P or API) */
+  dataColumnSidecar = "data_column_sidecar",
+}
+
+export const eventTypes: {[K in EventType]: K} = {
+  [EventType.head]: EventType.head,
+  [EventType.block]: EventType.block,
+  [EventType.blockGossip]: EventType.blockGossip,
+  [EventType.attestation]: EventType.attestation,
+  [EventType.singleAttestation]: EventType.singleAttestation,
+  [EventType.voluntaryExit]: EventType.voluntaryExit,
+  [EventType.proposerSlashing]: EventType.proposerSlashing,
+  [EventType.attesterSlashing]: EventType.attesterSlashing,
+  [EventType.blsToExecutionChange]: EventType.blsToExecutionChange,
+  [EventType.finalizedCheckpoint]: EventType.finalizedCheckpoint,
+  [EventType.chainReorg]: EventType.chainReorg,
+  [EventType.contributionAndProof]: EventType.contributionAndProof,
+  [EventType.lightClientOptimisticUpdate]: EventType.lightClientOptimisticUpdate,
+  [EventType.lightClientFinalityUpdate]: EventType.lightClientFinalityUpdate,
+  [EventType.payloadAttributes]: EventType.payloadAttributes,
+  [EventType.blobSidecar]: EventType.blobSidecar,
+  [EventType.dataColumnSidecar]: EventType.dataColumnSidecar,
+};
+
+export type EventData = {
+  [EventType.head]: {
+    slot: Slot;
+    block: RootHex;
+    state: RootHex;
+    epochTransition: boolean;
+    previousDutyDependentRoot: RootHex;
+    currentDutyDependentRoot: RootHex;
+    executionOptimistic: boolean;
+  };
+  [EventType.block]: {
+    slot: Slot;
+    block: RootHex;
+    executionOptimistic: boolean;
+  };
+  [EventType.blockGossip]: {
+    slot: Slot;
+    block: RootHex;
+  };
+  [EventType.attestation]: Attestation;
+  [EventType.singleAttestation]: electra.SingleAttestation;
+  [EventType.voluntaryExit]: phase0.SignedVoluntaryExit;
+  [EventType.proposerSlashing]: phase0.ProposerSlashing;
+  [EventType.attesterSlashing]: AttesterSlashing;
+  [EventType.blsToExecutionChange]: capella.SignedBLSToExecutionChange;
+  [EventType.finalizedCheckpoint]: {
+    block: RootHex;
+    state: RootHex;
+    epoch: Epoch;
+    executionOptimistic: boolean;
+  };
+  [EventType.chainReorg]: {
+    slot: Slot;
+    depth: UintNum64;
+    oldHeadBlock: RootHex;
+    newHeadBlock: RootHex;
+    oldHeadState: RootHex;
+    newHeadState: RootHex;
+    epoch: Epoch;
+    executionOptimistic: boolean;
+  };
+  [EventType.contributionAndProof]: altair.SignedContributionAndProof;
+  [EventType.lightClientOptimisticUpdate]: {version: ForkName; data: LightClientOptimisticUpdate};
+  [EventType.lightClientFinalityUpdate]: {version: ForkName; data: LightClientFinalityUpdate};
+  [EventType.payloadAttributes]: {version: ForkName; data: SSEPayloadAttributes};
+  [EventType.blobSidecar]: BlobSidecarSSE;
+  [EventType.dataColumnSidecar]: DataColumnSidecarSSE;
+};
+
+export type BeaconEvent = {[K in EventType]: {type: K; message: EventData[K]}}[EventType];
+
+type EventstreamArgs = {
+  /** Event types to subscribe to */
+  topics: EventType[];
+  signal: AbortSignal;
+  onEvent: (event: BeaconEvent) => void;
+  onError?: (err: Error) => void;
+  onClose?: () => void;
+};
+
+export type Endpoints = {
+  /**
+   * Subscribe to beacon node events
+   * Provides endpoint to subscribe to beacon node Server-Sent-Events stream.
+   * Consumers should use [eventsource](https://html.spec.whatwg.org/multipage/server-sent-events.html#the-eventsource-interface)
+   * implementation to listen on those events.
+   *
+   * Returns if SSE stream has been opened.
+   */
+  eventstream: Endpoint<
+    // ⏎
+    "GET",
+    EventstreamArgs,
+    {query: {topics: EventType[]}},
+    EmptyResponseData,
+    EmptyMeta
+  >;
+};
+
+export function getDefinitions(_config: ChainForkConfig): RouteDefinitions<Endpoints> {
+  return {
+    eventstream: {
+      url: "/eth/v1/events",
+      method: "GET",
+      req: {
+        writeReq: ({topics}) => ({query: {topics}}),
+        parseReq: ({query}) => ({topics: query.topics}) as EventstreamArgs,
+        schema: {
+          query: {topics: Schema.StringArrayRequired},
+        },
+      },
+      resp: EmptyResponseCodec,
+    },
+  };
+}
+
+export type TypeJson<T> = {
+  toJson: (data: T) => unknown; // server
+  fromJson: (data: unknown) => T; // client
+};
+
+export function getTypeByEvent(config: ChainForkConfig): {[K in EventType]: TypeJson<EventData[K]>} {
+  const WithVersion = <T>(getType: (fork: ForkName) => TypeJson<T>): TypeJson<{data: T; version: ForkName}> => {
+    return {
+      toJson: ({data, version}) => ({
+        data: getType(version).toJson(data),
+        version,
+      }),
+      fromJson: (val) => {
+        const {version} = VersionType.fromJson(val);
+        return {
+          data: getType(version).fromJson((val as {data: unknown}).data),
+          version,
+        };
+      },
+    };
+  };
+
+  return {
+    [EventType.head]: new ContainerType(
+      {
+        slot: ssz.Slot,
+        block: stringType,
+        state: stringType,
+        epochTransition: ssz.Boolean,
+        previousDutyDependentRoot: stringType,
+        currentDutyDependentRoot: stringType,
+        executionOptimistic: ssz.Boolean,
+      },
+      {jsonCase: "eth2"}
+    ),
+
+    [EventType.block]: new ContainerType(
+      {
+        slot: ssz.Slot,
+        block: stringType,
+        executionOptimistic: ssz.Boolean,
+      },
+      {jsonCase: "eth2"}
+    ),
+    [EventType.blockGossip]: new ContainerType(
+      {
+        slot: ssz.Slot,
+        block: stringType,
+      },
+      {jsonCase: "eth2"}
+    ),
+
+    [EventType.attestation]: {
+      toJson: (attestation) => {
+        const fork = config.getForkName(attestation.data.slot);
+        return sszTypesFor(fork).Attestation.toJson(attestation);
+      },
+      fromJson: (attestation) => {
+        const fork = config.getForkName((attestation as Attestation).data.slot);
+        return sszTypesFor(fork).Attestation.fromJson(attestation);
+      },
+    },
+    [EventType.singleAttestation]: ssz.electra.SingleAttestation,
+    [EventType.voluntaryExit]: ssz.phase0.SignedVoluntaryExit,
+    [EventType.proposerSlashing]: ssz.phase0.ProposerSlashing,
+    [EventType.attesterSlashing]: {
+      toJson: (attesterSlashing) => {
+        const fork = config.getForkName(Number(attesterSlashing.attestation1.data.slot));
+        return sszTypesFor(fork).AttesterSlashing.toJson(attesterSlashing);
+      },
+      fromJson: (attesterSlashing) => {
+        const fork = config.getForkName(Number((attesterSlashing as AttesterSlashing).attestation1.data.slot));
+        return sszTypesFor(fork).AttesterSlashing.fromJson(attesterSlashing);
+      },
+    },
+    [EventType.blsToExecutionChange]: ssz.capella.SignedBLSToExecutionChange,
+
+    [EventType.finalizedCheckpoint]: new ContainerType(
+      {
+        block: stringType,
+        state: stringType,
+        epoch: ssz.Epoch,
+        executionOptimistic: ssz.Boolean,
+      },
+      {jsonCase: "eth2"}
+    ),
+
+    [EventType.chainReorg]: new ContainerType(
+      {
+        slot: ssz.Slot,
+        depth: ssz.UintNum64,
+        oldHeadBlock: stringType,
+        newHeadBlock: stringType,
+        oldHeadState: stringType,
+        newHeadState: stringType,
+        epoch: ssz.Epoch,
+        executionOptimistic: ssz.Boolean,
+      },
+      {jsonCase: "eth2"}
+    ),
+
+    [EventType.contributionAndProof]: ssz.altair.SignedContributionAndProof,
+    [EventType.payloadAttributes]: WithVersion((fork) => getPostBellatrixForkTypes(fork).SSEPayloadAttributes),
+    [EventType.blobSidecar]: blobSidecarSSE,
+    [EventType.dataColumnSidecar]: dataColumnSidecarSSE,
+
+    [EventType.lightClientOptimisticUpdate]: WithVersion(
+      (fork) => getPostAltairForkTypes(fork).LightClientOptimisticUpdate
+    ),
+    [EventType.lightClientFinalityUpdate]: WithVersion(
+      (fork) => getPostAltairForkTypes(fork).LightClientFinalityUpdate
+    ),
+  };
+}
+
+export function getEventSerdes(config: ChainForkConfig) {
+  const typeByEvent = getTypeByEvent(config);
+
+  return {
+    toJson: (event: BeaconEvent): unknown => {
+      const eventType = typeByEvent[event.type] as TypeJson<BeaconEvent["message"]>;
+      return eventType.toJson(event.message);
+    },
+    fromJson: (type: EventType, data: unknown): BeaconEvent["message"] => {
+      const eventType = typeByEvent[type] as TypeJson<BeaconEvent["message"]>;
+      return eventType.fromJson(data);
+    },
+  };
+}

package/src/beacon/routes/index.ts

@@ -0,0 +1,33 @@
+// biome-ignore assist/source/organizeImports: We want to keep these groups of imports together for better readability
+import {Endpoints as BeaconEndpoints} from "./beacon/index.js";
+import {Endpoints as ConfigEndpoints} from "./config.js";
+import {Endpoints as DebugEndpoints} from "./debug.js";
+import {Endpoints as EventsEndpoints} from "./events.js";
+import {Endpoints as LightclientEndpoints} from "./lightclient.js";
+import {Endpoints as LodestarEndpoints} from "./lodestar.js";
+import {Endpoints as NodeEndpoints} from "./node.js";
+import {Endpoints as ProofEndpoints} from "./proof.js";
+import {Endpoints as ValidatorEndpoints} from "./validator.js";
+
+import * as beacon from "./beacon/index.js";
+import * as config from "./config.js";
+import * as debug from "./debug.js";
+import * as events from "./events.js";
+import * as lightclient from "./lightclient.js";
+import * as lodestar from "./lodestar.js";
+import * as node from "./node.js";
+import * as proof from "./proof.js";
+import * as validator from "./validator.js";
+export {beacon, config, debug, events, lightclient, lodestar, node, proof, validator};
+
+export type Endpoints = {
+  beacon: BeaconEndpoints;
+  config: ConfigEndpoints;
+  debug: DebugEndpoints;
+  events: EventsEndpoints;
+  lightclient: LightclientEndpoints;
+  lodestar: LodestarEndpoints;
+  node: NodeEndpoints;
+  proof: ProofEndpoints;
+  validator: ValidatorEndpoints;
+};