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

package/src/beacon/server/beacon.ts

@@ -0,0 +1,7 @@
+import {ChainForkConfig} from "@lodestar/config";
+import {ApplicationMethods, FastifyRoutes, createFastifyRoutes} from "../../utils/server/index.js";
+import {Endpoints, getDefinitions} from "../routes/beacon/index.js";
+
+export function getRoutes(config: ChainForkConfig, methods: ApplicationMethods<Endpoints>): FastifyRoutes<Endpoints> {
+  return createFastifyRoutes(getDefinitions(config), methods);
+}

package/src/beacon/server/config.ts

@@ -0,0 +1,7 @@
+import {ChainForkConfig} from "@lodestar/config";
+import {ApplicationMethods, FastifyRoutes, createFastifyRoutes} from "../../utils/server/index.js";
+import {Endpoints, getDefinitions} from "../routes/config.js";
+
+export function getRoutes(config: ChainForkConfig, methods: ApplicationMethods<Endpoints>): FastifyRoutes<Endpoints> {
+  return createFastifyRoutes(getDefinitions(config), methods);
+}

package/src/beacon/server/debug.ts

@@ -0,0 +1,7 @@
+import {ChainForkConfig} from "@lodestar/config";
+import {ApplicationMethods, FastifyRoutes, createFastifyRoutes} from "../../utils/server/index.js";
+import {Endpoints, getDefinitions} from "../routes/debug.js";
+
+export function getRoutes(config: ChainForkConfig, methods: ApplicationMethods<Endpoints>): FastifyRoutes<Endpoints> {
+  return createFastifyRoutes(getDefinitions(config), methods);
+}

package/src/beacon/server/events.ts

@@ -0,0 +1,73 @@
+import {ChainForkConfig} from "@lodestar/config";
+import {ApiError, ApplicationMethods, FastifyRoutes, createFastifyRoutes} from "../../utils/server/index.js";
+import {Endpoints, eventTypes, getDefinitions, getEventSerdes} from "../routes/events.js";
+
+export function getRoutes(config: ChainForkConfig, methods: ApplicationMethods<Endpoints>): FastifyRoutes<Endpoints> {
+  const eventSerdes = getEventSerdes(config);
+  const serverRoutes = createFastifyRoutes(getDefinitions(config), methods);
+
+  return {
+    // Non-JSON route. Server Sent Events (SSE)
+    eventstream: {
+      ...serverRoutes.eventstream,
+      handler: async (req, res) => {
+        const validTopics = new Set(Object.values(eventTypes));
+        for (const topic of req.query.topics) {
+          if (!validTopics.has(topic)) {
+            throw new ApiError(400, `Invalid topic: ${topic}`);
+          }
+        }
+
+        const controller = new AbortController();
+
+        try {
+          // Add injected headers from other plugins. This is required for fastify-cors for example
+          // From: https://github.com/NodeFactoryIo/fastify-sse-v2/blob/b1686a979fbf655fb9936c0560294a0c094734d4/src/plugin.ts
+          for (const [key, value] of Object.entries(res.getHeaders())) {
+            if (value !== undefined) res.raw.setHeader(key, value);
+          }
+
+          res.raw.setHeader("Content-Type", "text/event-stream");
+          res.raw.setHeader("Cache-Control", "no-cache,no-transform");
+          res.raw.setHeader("Connection", "keep-alive");
+          // It was reported that chrome and firefox do not play well with compressed event-streams https://github.com/lolo32/fastify-sse/issues/2
+          res.raw.setHeader("x-no-compression", 1);
+          // In case this beacon node is behind a NGINX, instruct it to disable buffering which can disrupt SSE by
+          // infinitely buffering it. http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffering
+          // Source: https://stackoverflow.com/questions/13672743/eventsource-server-sent-events-through-nginx
+          res.raw.setHeader("X-Accel-Buffering", "no");
+
+          await new Promise<void>((resolve, reject) => {
+            void methods.eventstream({
+              topics: req.query.topics,
+              signal: controller.signal,
+              onEvent: (event) => {
+                try {
+                  const data = eventSerdes.toJson(event);
+                  res.raw.write(serializeSSEEvent({event: event.type, data}));
+                } catch (e) {
+                  reject(e);
+                }
+              },
+            });
+
+            // The stream will never end by the server unless the node is stopped.
+            // In that case the BeaconNode class will call server.close() and end this connection.
+
+            // The client may disconnect and we need to clean the subscriptions.
+            req.socket.once("close", () => resolve());
+            req.socket.once("end", () => resolve());
+          });
+
+          // api.eventstream will never stop, so no need to ever call `res.raw.end();`
+        } finally {
+          controller.abort();
+        }
+      },
+    },
+  };
+}
+
+export function serializeSSEEvent(chunk: {event: string; data: unknown}): string {
+  return [`event: ${chunk.event}`, `data: ${JSON.stringify(chunk.data)}`, "\n"].join("\n");
+}

package/src/beacon/server/index.ts

@@ -0,0 +1,55 @@
+import type {FastifyInstance} from "fastify";
+import {ChainForkConfig} from "@lodestar/config";
+import {ApplicationMethods, FastifyRoute} from "../../utils/server/index.js";
+import {Endpoints} from "../routes/index.js";
+import * as beacon from "./beacon.js";
+import * as configApi 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 type BeaconApiMethods = {[K in keyof Endpoints]: ApplicationMethods<Endpoints[K]>};
+
+export function registerRoutes(
+  server: FastifyInstance,
+  config: ChainForkConfig,
+  methods: BeaconApiMethods,
+  enabledNamespaces: (keyof Endpoints)[]
+): void {
+  const routesByNamespace: {
+    // Enforces that we are declaring routes for every routeId in `Endpoints`
+    [K in keyof Endpoints]: () => {
+      // The Endpoints are enforced in each getRoutes return type
+      // biome-ignore lint/suspicious/noExplicitAny: We need to use `any` type here
+      [K2 in keyof Endpoints[K]]: FastifyRoute<any>;
+    };
+  } = {
+    // Initializes route types and their definitions
+    beacon: () => beacon.getRoutes(config, methods.beacon),
+    config: () => configApi.getRoutes(config, methods.config),
+    debug: () => debug.getRoutes(config, methods.debug),
+    events: () => events.getRoutes(config, methods.events),
+    lightclient: () => lightclient.getRoutes(config, methods.lightclient),
+    lodestar: () => lodestar.getRoutes(config, methods.lodestar),
+    node: () => node.getRoutes(config, methods.node),
+    proof: () => proof.getRoutes(config, methods.proof),
+    validator: () => validator.getRoutes(config, methods.validator),
+  };
+
+  for (const namespace of enabledNamespaces) {
+    const routes = routesByNamespace[namespace];
+    if (routes === undefined) {
+      throw Error(`Unknown api namespace ${namespace}`);
+    }
+
+    for (const route of Object.values(routes())) {
+      // Append the namespace as a tag for downstream consumption
+      route.schema.tags = [namespace];
+      server.route(route);
+    }
+  }
+}

package/src/beacon/server/lightclient.ts

@@ -0,0 +1,7 @@
+import {ChainForkConfig} from "@lodestar/config";
+import {ApplicationMethods, FastifyRoutes, createFastifyRoutes} from "../../utils/server/index.js";
+import {Endpoints, getDefinitions} from "../routes/lightclient.js";
+
+export function getRoutes(config: ChainForkConfig, methods: ApplicationMethods<Endpoints>): FastifyRoutes<Endpoints> {
+  return createFastifyRoutes(getDefinitions(config), methods);
+}

package/src/beacon/server/lodestar.ts

@@ -0,0 +1,7 @@
+import {ChainForkConfig} from "@lodestar/config";
+import {ApplicationMethods, FastifyRoutes, createFastifyRoutes} from "../../utils/server/index.js";
+import {Endpoints, getDefinitions} from "../routes/lodestar.js";
+
+export function getRoutes(config: ChainForkConfig, methods: ApplicationMethods<Endpoints>): FastifyRoutes<Endpoints> {
+  return createFastifyRoutes(getDefinitions(config), methods);
+}

package/src/beacon/server/node.ts

@@ -0,0 +1,7 @@
+import {ChainForkConfig} from "@lodestar/config";
+import {ApplicationMethods, FastifyRoutes, createFastifyRoutes} from "../../utils/server/index.js";
+import {Endpoints, getDefinitions} from "../routes/node.js";
+
+export function getRoutes(config: ChainForkConfig, methods: ApplicationMethods<Endpoints>): FastifyRoutes<Endpoints> {
+  return createFastifyRoutes(getDefinitions(config), methods);
+}

package/src/beacon/server/proof.ts

@@ -0,0 +1,7 @@
+import {ChainForkConfig} from "@lodestar/config";
+import {ApplicationMethods, FastifyRoutes, createFastifyRoutes} from "../../utils/server/index.js";
+import {Endpoints, getDefinitions} from "../routes/proof.js";
+
+export function getRoutes(config: ChainForkConfig, methods: ApplicationMethods<Endpoints>): FastifyRoutes<Endpoints> {
+  return createFastifyRoutes(getDefinitions(config), methods);
+}

package/src/beacon/server/validator.ts

@@ -0,0 +1,7 @@
+import {ChainForkConfig} from "@lodestar/config";
+import {ApplicationMethods, FastifyRoutes, createFastifyRoutes} from "../../utils/server/index.js";
+import {Endpoints, getDefinitions} from "../routes/validator.js";
+
+export function getRoutes(config: ChainForkConfig, methods: ApplicationMethods<Endpoints>): FastifyRoutes<Endpoints> {
+  return createFastifyRoutes(getDefinitions(config), methods);
+}

package/src/builder/client.ts

@@ -0,0 +1,9 @@
+import {ChainForkConfig} from "@lodestar/config";
+import {ApiClientMethods, IHttpClient, createApiClientMethods} from "../utils/client/index.js";
+import {Endpoints, getDefinitions} from "./routes.js";
+
+export type ApiClient = ApiClientMethods<Endpoints>;
+
+export function getClient(config: ChainForkConfig, httpClient: IHttpClient): ApiClient {
+  return createApiClientMethods(getDefinitions(config), httpClient);
+}

package/src/builder/index.ts

@@ -0,0 +1,26 @@
+import {ChainForkConfig} from "@lodestar/config";
+import {HttpClient, HttpClientModules, HttpClientOptions, IHttpClient} from "../utils/client/httpClient.js";
+import type {ApiClient} from "./client.js";
+import * as builder from "./client.js";
+import {Endpoints} from "./routes.js";
+
+// NOTE: Don't export server here so it's not bundled to all consumers
+
+export type {ApiClient, Endpoints};
+
+// Note: builder API does not have namespaces as routes are declared at the "root" namespace
+
+type ClientModules = HttpClientModules & {
+  config: ChainForkConfig;
+  httpClient?: IHttpClient;
+};
+
+/**
+ * REST HTTP client for builder routes
+ */
+export function getClient(opts: HttpClientOptions, modules: ClientModules): ApiClient {
+  const {config} = modules;
+  const httpClient = modules.httpClient ?? new HttpClient(opts, modules);
+
+  return builder.getClient(config, httpClient);
+}

package/src/builder/routes.ts

@@ -0,0 +1,227 @@
+import {ChainForkConfig} from "@lodestar/config";
+import {ForkName, VALIDATOR_REGISTRY_LIMIT, isForkPostDeneb} from "@lodestar/params";
+import {
+  BLSPubkey,
+  ExecutionPayload,
+  ExecutionPayloadAndBlobsBundle,
+  Root,
+  SignedBlindedBeaconBlock,
+  SignedBuilderBid,
+  Slot,
+  WithOptionalBytes,
+  bellatrix,
+  ssz,
+} from "@lodestar/types";
+import {fromHex, toPubkeyHex, toRootHex} from "@lodestar/utils";
+import {
+  ArrayOf,
+  EmptyArgs,
+  EmptyMeta,
+  EmptyRequest,
+  EmptyRequestCodec,
+  EmptyResponseCodec,
+  EmptyResponseData,
+  WithVersion,
+} from "../utils/codecs.js";
+import {getPostBellatrixForkTypes, getPostDenebForkTypes, toForkName} from "../utils/fork.js";
+import {fromHeaders} from "../utils/headers.js";
+import {Endpoint, RouteDefinitions, Schema} from "../utils/index.js";
+import {MetaHeader, VersionCodec, VersionMeta} from "../utils/metadata.js";
+import {WireFormat} from "../utils/wireFormat.js";
+
+// Mev-boost might not return any data if there are no bids from builders or min-bid threshold was not reached.
+// In this case, we receive a success response (204) which is not handled as an error. The generic response
+// handler already checks the status code and will not attempt to parse the body, but it will return no value.
+// It is important that this type indicates that there might be no value to ensure it is properly handled downstream.
+export type MaybeSignedBuilderBid = SignedBuilderBid | undefined;
+
+const RegistrationsType = ArrayOf(ssz.bellatrix.SignedValidatorRegistrationV1, VALIDATOR_REGISTRY_LIMIT);
+
+export type Endpoints = {
+  status: Endpoint<
+    // ⏎
+    "GET",
+    EmptyArgs,
+    EmptyRequest,
+    EmptyResponseData,
+    EmptyMeta
+  >;
+
+  registerValidator: Endpoint<
+    "POST",
+    {registrations: bellatrix.SignedValidatorRegistrationV1[]},
+    {body: unknown},
+    EmptyResponseData,
+    EmptyMeta
+  >;
+
+  getHeader: Endpoint<
+    "GET",
+    {
+      slot: Slot;
+      parentHash: Root;
+      proposerPubkey: BLSPubkey;
+    },
+    {params: {slot: Slot; parent_hash: string; pubkey: string}},
+    MaybeSignedBuilderBid,
+    VersionMeta
+  >;
+
+  submitBlindedBlock: Endpoint<
+    "POST",
+    {signedBlindedBlock: WithOptionalBytes<SignedBlindedBeaconBlock>},
+    {body: unknown; headers: {[MetaHeader.Version]: string}},
+    ExecutionPayload | ExecutionPayloadAndBlobsBundle,
+    VersionMeta
+  >;
+
+  submitBlindedBlockV2: Endpoint<
+    "POST",
+    {signedBlindedBlock: WithOptionalBytes<SignedBlindedBeaconBlock>},
+    {body: unknown; headers: {[MetaHeader.Version]: string}},
+    EmptyResponseData,
+    EmptyMeta
+  >;
+};
+
+export function getDefinitions(config: ChainForkConfig): RouteDefinitions<Endpoints> {
+  return {
+    status: {
+      url: "/eth/v1/builder/status",
+      method: "GET",
+      req: EmptyRequestCodec,
+      resp: EmptyResponseCodec,
+    },
+    registerValidator: {
+      url: "/eth/v1/builder/validators",
+      method: "POST",
+      req: {
+        writeReqJson: ({registrations}) => ({body: RegistrationsType.toJson(registrations)}),
+        parseReqJson: ({body}) => ({registrations: RegistrationsType.fromJson(body)}),
+        writeReqSsz: ({registrations}) => ({body: RegistrationsType.serialize(registrations)}),
+        parseReqSsz: ({body}) => ({registrations: RegistrationsType.deserialize(body)}),
+        schema: {body: Schema.ObjectArray},
+      },
+      resp: EmptyResponseCodec,
+      init: {
+        requestWireFormat: WireFormat.ssz,
+      },
+    },
+    getHeader: {
+      url: "/eth/v1/builder/header/{slot}/{parent_hash}/{pubkey}",
+      method: "GET",
+      req: {
+        writeReq: ({slot, parentHash, proposerPubkey: proposerPubKey}) => ({
+          params: {slot, parent_hash: toRootHex(parentHash), pubkey: toPubkeyHex(proposerPubKey)},
+        }),
+        parseReq: ({params}) => ({
+          slot: params.slot,
+          parentHash: fromHex(params.parent_hash),
+          proposerPubkey: fromHex(params.pubkey),
+        }),
+        schema: {
+          params: {slot: Schema.UintRequired, parent_hash: Schema.StringRequired, pubkey: Schema.StringRequired},
+        },
+      },
+      resp: {
+        data: WithVersion<MaybeSignedBuilderBid, VersionMeta>(
+          (fork: ForkName) => getPostBellatrixForkTypes(fork).SignedBuilderBid
+        ),
+        meta: VersionCodec,
+      },
+    },
+    submitBlindedBlock: {
+      url: "/eth/v1/builder/blinded_blocks",
+      method: "POST",
+      req: {
+        writeReqJson: ({signedBlindedBlock}) => {
+          const fork = config.getForkName(signedBlindedBlock.data.message.slot);
+          return {
+            body: getPostBellatrixForkTypes(fork).SignedBlindedBeaconBlock.toJson(signedBlindedBlock.data),
+            headers: {
+              [MetaHeader.Version]: fork,
+            },
+          };
+        },
+        parseReqJson: ({body, headers}) => {
+          const fork = toForkName(fromHeaders(headers, MetaHeader.Version));
+          return {
+            signedBlindedBlock: {data: getPostBellatrixForkTypes(fork).SignedBlindedBeaconBlock.fromJson(body)},
+          };
+        },
+        writeReqSsz: ({signedBlindedBlock}) => {
+          const fork = config.getForkName(signedBlindedBlock.data.message.slot);
+          return {
+            body:
+              signedBlindedBlock.bytes ??
+              getPostBellatrixForkTypes(fork).SignedBlindedBeaconBlock.serialize(signedBlindedBlock.data),
+            headers: {
+              [MetaHeader.Version]: fork,
+            },
+          };
+        },
+        parseReqSsz: ({body, headers}) => {
+          const fork = toForkName(fromHeaders(headers, MetaHeader.Version));
+          return {
+            signedBlindedBlock: {data: getPostBellatrixForkTypes(fork).SignedBlindedBeaconBlock.deserialize(body)},
+          };
+        },
+        schema: {
+          body: Schema.Object,
+          headers: {[MetaHeader.Version]: Schema.String},
+        },
+      },
+      resp: {
+        data: WithVersion<ExecutionPayload | ExecutionPayloadAndBlobsBundle, VersionMeta>((fork: ForkName) => {
+          return isForkPostDeneb(fork)
+            ? getPostDenebForkTypes(fork).ExecutionPayloadAndBlobsBundle
+            : getPostBellatrixForkTypes(fork).ExecutionPayload;
+        }),
+        meta: VersionCodec,
+      },
+    },
+    submitBlindedBlockV2: {
+      url: "/eth/v2/builder/blinded_blocks",
+      method: "POST",
+      req: {
+        writeReqJson: ({signedBlindedBlock}) => {
+          const fork = config.getForkName(signedBlindedBlock.data.message.slot);
+          return {
+            body: getPostBellatrixForkTypes(fork).SignedBlindedBeaconBlock.toJson(signedBlindedBlock.data),
+            headers: {
+              [MetaHeader.Version]: fork,
+            },
+          };
+        },
+        parseReqJson: ({body, headers}) => {
+          const fork = toForkName(fromHeaders(headers, MetaHeader.Version));
+          return {
+            signedBlindedBlock: {data: getPostBellatrixForkTypes(fork).SignedBlindedBeaconBlock.fromJson(body)},
+          };
+        },
+        writeReqSsz: ({signedBlindedBlock}) => {
+          const fork = config.getForkName(signedBlindedBlock.data.message.slot);
+          return {
+            body:
+              signedBlindedBlock.bytes ??
+              getPostBellatrixForkTypes(fork).SignedBlindedBeaconBlock.serialize(signedBlindedBlock.data),
+            headers: {
+              [MetaHeader.Version]: fork,
+            },
+          };
+        },
+        parseReqSsz: ({body, headers}) => {
+          const fork = toForkName(fromHeaders(headers, MetaHeader.Version));
+          return {
+            signedBlindedBlock: {data: getPostBellatrixForkTypes(fork).SignedBlindedBeaconBlock.deserialize(body)},
+          };
+        },
+        schema: {
+          body: Schema.Object,
+          headers: {[MetaHeader.Version]: Schema.String},
+        },
+      },
+      resp: EmptyResponseCodec,
+    },
+  };
+}

package/src/builder/server/index.ts

@@ -0,0 +1,19 @@
+import type {FastifyInstance} from "fastify";
+import {ChainForkConfig} from "@lodestar/config";
+import {AnyEndpoint} from "../../utils/codecs.js";
+import {ApplicationMethods, FastifyRoute, FastifyRoutes, createFastifyRoutes} from "../../utils/server/index.js";
+import {Endpoints, getDefinitions} from "../routes.js";
+
+export type BuilderApiMethods = ApplicationMethods<Endpoints>;
+
+export function getRoutes(config: ChainForkConfig, methods: BuilderApiMethods): FastifyRoutes<Endpoints> {
+  return createFastifyRoutes(getDefinitions(config), methods);
+}
+
+export function registerRoutes(server: FastifyInstance, config: ChainForkConfig, methods: BuilderApiMethods): void {
+  const routes = getRoutes(config, methods);
+
+  for (const route of Object.values(routes)) {
+    server.route(route as FastifyRoute<AnyEndpoint>);
+  }
+}

package/src/index.ts

@@ -0,0 +1,19 @@
+// Re-exporting beacon only for backwards compatibility
+export * from "./beacon/index.js";
+export {ApiError} from "./utils/client/error.js";
+export type {
+  ApiClientMethods,
+  HttpClientModules,
+  HttpClientOptions,
+  IHttpClient,
+  Metrics,
+} from "./utils/client/index.js";
+export {ApiResponse, HttpClient, defaultInit} from "./utils/client/index.js";
+export type {ApiRequestInit} from "./utils/client/request.js";
+export {HttpHeader, MediaType} from "./utils/headers.js";
+export type {HttpErrorCodes, HttpSuccessCodes} from "./utils/httpStatusCode.js";
+export {HttpStatusCode} from "./utils/httpStatusCode.js";
+export type {Endpoint} from "./utils/types.js";
+export {WireFormat} from "./utils/wireFormat.js";
+
+// NOTE: Don't export server here so it's not bundled to all consumers

package/src/keymanager/client.ts

@@ -0,0 +1,9 @@
+import {ChainForkConfig} from "@lodestar/config";
+import {ApiClientMethods, IHttpClient, createApiClientMethods} from "../utils/client/index.js";
+import {Endpoints, getDefinitions} from "./routes.js";
+
+export type ApiClient = ApiClientMethods<Endpoints>;
+
+export function getClient(config: ChainForkConfig, httpClient: IHttpClient): ApiClient {
+  return createApiClientMethods(getDefinitions(config), httpClient);
+}

package/src/keymanager/index.ts

@@ -0,0 +1,39 @@
+import {ChainForkConfig} from "@lodestar/config";
+import {HttpClient, HttpClientModules, HttpClientOptions, IHttpClient} from "../utils/client/index.js";
+import type {ApiClient} from "./client.js";
+import * as keymanager from "./client.js";
+
+// NOTE: Don't export server here so it's not bundled to all consumers
+
+export type {
+  BuilderBoostFactorData,
+  Endpoints,
+  FeeRecipientData,
+  GasLimitData,
+  GraffitiData,
+  KeystoreStr,
+  ProposerConfigResponse,
+  PubkeyHex,
+  RemoteSignerDefinition,
+  ResponseStatus,
+  SignerDefinition,
+  SlashingProtectionData,
+} from "./routes.js";
+export {DeleteRemoteKeyStatus, DeletionStatus, ImportRemoteKeyStatus, ImportStatus} from "./routes.js";
+
+export type {ApiClient};
+
+type ClientModules = HttpClientModules & {
+  config: ChainForkConfig;
+  httpClient?: IHttpClient;
+};
+
+/**
+ * REST HTTP client for keymanager routes
+ */
+export function getClient(opts: HttpClientOptions, modules: ClientModules): ApiClient {
+  const {config} = modules;
+  const httpClient = modules.httpClient ?? new HttpClient(opts, modules);
+
+  return keymanager.getClient(config, httpClient);
+}