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

package/src/utils/schema.ts

@@ -0,0 +1,141 @@
+import {MediaType} from "./headers.js";
+import {Endpoint, HeaderParams, PathParams, QueryParams} from "./types.js";
+
+// Reasoning: Allows to declare JSON schemas for server routes in a succinct typesafe way.
+// The enums exposed here are very feature incomplete but cover the minimum necessary for
+// the existing routes. Since the arguments for Ethereum Consensus server routes are very simple it suffice.
+
+type JsonSchema = Record<string, unknown>;
+type JsonSchemaObj = {
+  type: "object";
+  required: string[];
+  properties: Record<string, JsonSchema>;
+};
+type RequireSchema<T> = {[K in keyof T]-?: Schema};
+
+export type SchemaDefinition<ReqType extends Endpoint["request"]> = (ReqType["params"] extends PathParams
+  ? {params: RequireSchema<ReqType["params"]>}
+  : {params?: never}) &
+  (ReqType["query"] extends QueryParams ? {query: RequireSchema<ReqType["query"]>} : {query?: never}) &
+  (ReqType["headers"] extends HeaderParams ? {headers: RequireSchema<ReqType["headers"]>} : {headers?: never}) &
+  (ReqType extends {body: unknown} ? {body: Schema} : {body?: never});
+
+export enum Schema {
+  Uint,
+  UintRequired,
+  UintArray,
+  String,
+  StringRequired,
+  StringArray,
+  StringArrayRequired,
+  UintOrStringRequired,
+  UintOrStringArray,
+  Object,
+  ObjectArray,
+  AnyArray,
+  Boolean,
+}
+
+/**
+ * Return JSON schema from a Schema enum. Useful to declare schemas in a succinct format
+ */
+function getJsonSchemaItem(schema: Schema): JsonSchema {
+  switch (schema) {
+    case Schema.Uint:
+    case Schema.UintRequired:
+      return {type: "integer", minimum: 0};
+
+    case Schema.UintArray:
+      return {type: "array", items: {type: "integer", minimum: 0}};
+
+    case Schema.String:
+    case Schema.StringRequired:
+      return {type: "string"};
+
+    case Schema.StringArray:
+    case Schema.StringArrayRequired:
+      return {type: "array", items: {type: "string"}};
+
+    case Schema.UintOrStringRequired:
+      return {anyOf: [{type: "string"}, {type: "integer"}]};
+    case Schema.UintOrStringArray:
+      return {type: "array", items: {anyOf: [{type: "string"}, {type: "integer"}]}};
+
+    case Schema.Object:
+      return {type: "object"};
+
+    case Schema.ObjectArray:
+      return {type: "array", items: {type: "object"}};
+
+    case Schema.AnyArray:
+      return {type: "array"};
+
+    case Schema.Boolean:
+      return {type: "boolean"};
+  }
+}
+
+function isRequired(schema: Schema): boolean {
+  switch (schema) {
+    case Schema.UintRequired:
+    case Schema.StringRequired:
+    case Schema.UintOrStringRequired:
+    case Schema.StringArrayRequired:
+      return true;
+
+    default:
+      return false;
+  }
+}
+
+export function getFastifySchema<T extends Endpoint["request"]>(schemaDef: SchemaDefinition<T>): JsonSchema {
+  const schema: {params?: JsonSchemaObj; querystring?: JsonSchemaObj; headers?: JsonSchemaObj; body?: JsonSchema} = {};
+
+  if (schemaDef.body != null) {
+    schema.body = {
+      content: {
+        [MediaType.json]: {
+          schema: getJsonSchemaItem(schemaDef.body),
+        },
+        [MediaType.ssz]: {
+          schema: {},
+        },
+      },
+    };
+  }
+
+  if (schemaDef.params) {
+    schema.params = {type: "object", required: [], properties: {}};
+
+    for (const [key, def] of Object.entries<Schema>(schemaDef.params)) {
+      schema.params.properties[key] = getJsonSchemaItem(def);
+      if (isRequired(def)) {
+        schema.params.required.push(key);
+      }
+    }
+  }
+
+  if (schemaDef.query) {
+    schema.querystring = {type: "object", required: [], properties: {}};
+
+    for (const [key, def] of Object.entries<Schema>(schemaDef.query)) {
+      schema.querystring.properties[key] = getJsonSchemaItem(def);
+      if (isRequired(def)) {
+        schema.querystring.required.push(key);
+      }
+    }
+  }
+
+  if (schemaDef.headers) {
+    schema.headers = {type: "object", required: [], properties: {}};
+
+    for (const [key, def] of Object.entries<Schema>(schemaDef.headers)) {
+      schema.headers.properties[key] = getJsonSchemaItem(def);
+      if (isRequired(def)) {
+        schema.headers.required.push(key);
+      }
+    }
+  }
+
+  return schema;
+}

package/src/utils/serdes.ts

@@ -0,0 +1,120 @@
+import {JsonPath} from "@chainsafe/ssz";
+import {fromHex, toHex} from "@lodestar/utils";
+
+/**
+ * Serialize proof path to JSON.
+ * @param paths `[["finalized_checkpoint", 0, "root", 12000]]`
+ * @returns `['["finalized_checkpoint",0,"root",12000]']`
+ */
+export function querySerializeProofPathsArr(paths: JsonPath[]): string[] {
+  return paths.map((path) => JSON.stringify(path));
+}
+
+/**
+ * Deserialize JSON proof path to proof path
+ * @param pathStrs `['["finalized_checkpoint",0,"root",12000]']`
+ * @returns `[["finalized_checkpoint", 0, "root", 12000]]`
+ */
+export function queryParseProofPathsArr(pathStrs: string | string[]): JsonPath[] {
+  if (Array.isArray(pathStrs)) {
+    return pathStrs.map((pathStr) => queryParseProofPaths(pathStr));
+  }
+  return [queryParseProofPaths(pathStrs)];
+}
+
+/**
+ * Deserialize single JSON proof path to proof path
+ * @param pathStr `'["finalized_checkpoint",0,"root",12000]'`
+ * @returns `["finalized_checkpoint", 0, "root", 12000]`
+ */
+export function queryParseProofPaths(pathStr: string): JsonPath {
+  const path = JSON.parse(pathStr) as JsonPath;
+
+  if (!Array.isArray(path)) {
+    throw Error("Proof pathStr is not an array");
+  }
+
+  for (let i = 0; i < path.length; i++) {
+    const elType = typeof path[i];
+    if (elType !== "string" && elType !== "number") {
+      throw Error(`Proof pathStr[${i}] not string or number`);
+    }
+  }
+
+  return path;
+}
+
+export type U64 = number;
+export type U64Str = string;
+
+export function fromU64Str(u64Str: U64Str): number {
+  const u64 = parseInt(u64Str, 10);
+  if (!Number.isFinite(u64)) {
+    throw Error(`Invalid uin64 ${u64Str}`);
+  }
+  return u64;
+}
+
+export function toU64Str(u64: U64): U64Str {
+  return u64.toString(10);
+}
+
+export function fromU64StrOpt(u64Str: U64Str | undefined): U64 | undefined {
+  return u64Str !== undefined ? fromU64Str(u64Str) : undefined;
+}
+
+export function toU64StrOpt(u64: U64 | undefined): U64Str | undefined {
+  return u64 !== undefined ? toU64Str(u64) : undefined;
+}
+
+export function toValidatorIdsStr(ids?: (string | number)[]): string[] | undefined {
+  return ids?.map((id) => (typeof id === "string" ? id : toU64Str(id)));
+}
+
+export function fromValidatorIdsStr(ids?: string[]): (string | number)[] | undefined {
+  return ids?.map((id) => (typeof id === "string" && id.startsWith("0x") ? id : fromU64Str(id)));
+}
+
+const GRAFFITI_HEX_LENGTH = 66;
+
+export function toGraffitiHex(utf8?: string): string | undefined {
+  if (utf8 === undefined) {
+    return undefined;
+  }
+
+  const hex = toHex(new TextEncoder().encode(utf8));
+
+  if (hex.length > GRAFFITI_HEX_LENGTH) {
+    // remove characters from the end if hex string is too long
+    return hex.slice(0, GRAFFITI_HEX_LENGTH);
+  }
+
+  if (hex.length < GRAFFITI_HEX_LENGTH) {
+    // right-pad with zeros if hex string is too short
+    return hex.padEnd(GRAFFITI_HEX_LENGTH, "0");
+  }
+
+  return hex;
+}
+
+export function fromGraffitiHex(hex?: string): string | undefined {
+  if (hex === undefined) {
+    return undefined;
+  }
+  try {
+    return new TextDecoder("utf8").decode(fromHex(hex));
+  } catch (_e) {
+    // allow malformed graffiti hex string
+    return hex;
+  }
+}
+
+export function toBoolean(value: string): boolean {
+  value = value.toLowerCase();
+
+  if (value !== "true" && value !== "false") {
+    throw Error(`Invalid boolean ${value}`);
+  }
+
+  return value === "true";
+}

package/src/utils/server/error.ts

@@ -0,0 +1,9 @@
+import {HttpErrorCodes} from "../httpStatusCode.js";
+
+export class ApiError extends Error {
+  statusCode: HttpErrorCodes;
+  constructor(statusCode: HttpErrorCodes, message?: string) {
+    super(message);
+    this.statusCode = statusCode;
+  }
+}

package/src/utils/server/handler.ts

@@ -0,0 +1,149 @@
+import type * as fastify from "fastify";
+import {HttpHeader, MediaType, SUPPORTED_MEDIA_TYPES, parseAcceptHeader, parseContentTypeHeader} from "../headers.js";
+import {
+  Endpoint,
+  JsonRequestData,
+  JsonRequestMethods,
+  RequestData,
+  RequestWithBodyCodec,
+  RequestWithoutBodyCodec,
+  RouteDefinition,
+  SszRequestData,
+  SszRequestMethods,
+  isRequestWithoutBody,
+} from "../types.js";
+import {WireFormat, fromWireFormat, getWireFormat} from "../wireFormat.js";
+import {ApiError} from "./error.js";
+import {ApplicationMethod} from "./method.js";
+
+export type FastifyHandler<E extends Endpoint> = fastify.RouteHandlerMethod<
+  fastify.RawServerDefault,
+  fastify.RawRequestDefaultExpression<fastify.RawServerDefault>,
+  fastify.RawReplyDefaultExpression<fastify.RawServerDefault>,
+  {
+    Body: E["request"] extends JsonRequestData ? E["request"]["body"] : undefined;
+    Querystring: E["request"]["query"];
+    Params: E["request"]["params"];
+    Headers: E["request"]["headers"];
+  },
+  fastify.ContextConfigDefault
+>;
+
+export function createFastifyHandler<E extends Endpoint>(
+  definition: RouteDefinition<E>,
+  method: ApplicationMethod<E>,
+  _operationId: string
+): FastifyHandler<E> {
+  return async (req, resp) => {
+    // Determine response wire format first to inform application method
+    // about the preferable return type to avoid unnecessary serialization
+    let responseMediaType: MediaType | null;
+
+    const acceptHeader = req.headers.accept;
+    if (definition.resp.isEmpty) {
+      // Ignore Accept header, the response will be sent without body
+      responseMediaType = null;
+    } else if (acceptHeader === undefined) {
+      // Default to json to not force user to set header, e.g. when using curl
+      responseMediaType = MediaType.json;
+    } else {
+      const {onlySupport} = definition.resp;
+      const supportedMediaTypes = onlySupport !== undefined ? [fromWireFormat(onlySupport)] : SUPPORTED_MEDIA_TYPES;
+      responseMediaType = parseAcceptHeader(acceptHeader, supportedMediaTypes);
+
+      if (responseMediaType === null) {
+        throw new ApiError(406, `Accepted media types not supported: ${acceptHeader}`);
+      }
+    }
+    const responseWireFormat = responseMediaType !== null ? getWireFormat(responseMediaType) : null;
+
+    let requestWireFormat: WireFormat | null;
+    if (isRequestWithoutBody(definition)) {
+      requestWireFormat = null;
+    } else {
+      const contentType = req.headers[HttpHeader.ContentType];
+      if (contentType === undefined && req.body === undefined) {
+        // Default to json parser if body is omitted. This is not possible for most
+        // routes as request will fail schema validation before this handler is called
+        requestWireFormat = WireFormat.json;
+      } else {
+        if (contentType === undefined) {
+          throw new ApiError(400, "Content-Type header is required");
+        }
+        const requestMediaType = parseContentTypeHeader(contentType);
+        if (requestMediaType === null) {
+          throw new ApiError(415, `Unsupported media type: ${contentType.split(";", 1)[0]}`);
+        }
+        requestWireFormat = getWireFormat(requestMediaType);
+      }
+
+      const {onlySupport} = definition.req as RequestWithBodyCodec<E>;
+      if (onlySupport !== undefined && onlySupport !== requestWireFormat) {
+        throw new ApiError(415, `Endpoint only supports ${onlySupport.toUpperCase()} requests`);
+      }
+    }
+
+    let args: E["args"];
+    try {
+      switch (requestWireFormat) {
+        case WireFormat.json:
+          args = (definition.req as JsonRequestMethods<E>).parseReqJson(req as JsonRequestData);
+          break;
+        case WireFormat.ssz:
+          args = (definition.req as SszRequestMethods<E>).parseReqSsz(req as SszRequestData<E["request"]>);
+          break;
+        case null:
+          args = (definition.req as RequestWithoutBodyCodec<E>).parseReq(req as RequestData);
+          break;
+      }
+    } catch (e) {
+      if (e instanceof ApiError) throw e;
+      // Errors related to parsing should return 400 status code
+      throw new ApiError(400, (e as Error).message);
+    }
+
+    const response = await method(args, {
+      sszBytes: requestWireFormat === WireFormat.ssz ? (req.body as Uint8Array) : null,
+      returnBytes: responseWireFormat === WireFormat.ssz,
+    });
+
+    if (response?.status !== undefined) {
+      resp.statusCode = response.status;
+    }
+
+    switch (responseWireFormat) {
+      case WireFormat.json: {
+        const metaHeaders = definition.resp.meta.toHeadersObject(response?.meta);
+        metaHeaders[HttpHeader.ContentType] = MediaType.json;
+        void resp.headers(metaHeaders);
+        const data =
+          response?.data instanceof Uint8Array
+            ? definition.resp.data.toJson(definition.resp.data.deserialize(response.data, response.meta), response.meta)
+            : definition.resp.data.toJson(response?.data, response?.meta);
+        const metaJson = definition.resp.meta.toJson(response?.meta);
+        if (definition.resp.transform) {
+          return definition.resp.transform.toResponse(data, metaJson);
+        }
+        return {
+          data,
+          ...(metaJson as object),
+        };
+      }
+      case WireFormat.ssz: {
+        const metaHeaders = definition.resp.meta.toHeadersObject(response?.meta);
+        metaHeaders[HttpHeader.ContentType] = MediaType.ssz;
+        void resp.headers(metaHeaders);
+        const data =
+          response?.data instanceof Uint8Array
+            ? response.data
+            : definition.resp.data.serialize(response?.data, response?.meta);
+        // Fastify supports returning `Uint8Array` from handler and will efficiently
+        // convert it to a `Buffer` internally without copying the underlying `ArrayBuffer`
+        return data;
+      }
+      case null:
+        // Send response without body
+        return;
+    }
+  };
+}

package/src/utils/server/index.ts

@@ -0,0 +1,5 @@
+export * from "./error.js";
+export * from "./handler.js";
+export * from "./method.js";
+export * from "./parser.js";
+export * from "./route.js";

package/src/utils/server/method.ts

@@ -0,0 +1,38 @@
+import {EmptyMeta, EmptyResponseData} from "../codecs.js";
+import {HttpSuccessCodes} from "../httpStatusCode.js";
+import {Endpoint, HasOnlyOptionalProps} from "../types.js";
+
+type ApplicationResponseObject<E extends Endpoint> = {
+  /**
+   * Set non-200 success status code
+   */
+  status?: HttpSuccessCodes;
+} & (E["return"] extends EmptyResponseData
+  ? {data?: never}
+  : {data: E["return"] | (E["return"] extends undefined ? undefined : Uint8Array)}) &
+  (E["meta"] extends EmptyMeta ? {meta?: never} : {meta: E["meta"]});
+
+export type ApplicationResponse<E extends Endpoint> = HasOnlyOptionalProps<ApplicationResponseObject<E>> extends true
+  ? ApplicationResponseObject<E> | void
+  : ApplicationResponseObject<E>;
+
+export type ApiContext = {
+  /**
+   * Raw ssz bytes from request payload, only available for ssz requests
+   */
+  sszBytes?: Uint8Array | null;
+  /**
+   * Informs application method about preferable return type to avoid unnecessary serialization
+   */
+  returnBytes?: boolean;
+};
+
+type GenericOptions = Record<string, unknown>;
+
+export type ApplicationMethod<E extends Endpoint> = (
+  args: E["args"],
+  context?: ApiContext,
+  opts?: GenericOptions
+) => Promise<ApplicationResponse<E>>;
+
+export type ApplicationMethods<Es extends Record<string, Endpoint>> = {[K in keyof Es]: ApplicationMethod<Es[K]>};

package/src/utils/server/parser.ts

@@ -0,0 +1,15 @@
+import type * as fastify from "fastify";
+import {MediaType} from "../headers.js";
+
+export function addSszContentTypeParser(server: fastify.FastifyInstance): void {
+  server.addContentTypeParser(
+    MediaType.ssz,
+    {parseAs: "buffer"},
+    async (_request: fastify.FastifyRequest, payload: Buffer) => {
+      // We could just return the `Buffer` here which is a subclass of `Uint8Array` but downstream code does not require it
+      // and it's better to convert it here to avoid unexpected behavior such as `Buffer.prototype.slice` not copying memory
+      // See https://github.com/nodejs/node/issues/41588#issuecomment-1016269584
+      return new Uint8Array(payload.buffer, payload.byteOffset, payload.byteLength);
+    }
+  );
+}

package/src/utils/server/route.ts

@@ -0,0 +1,45 @@
+import type * as fastify from "fastify";
+import {mapValues} from "@lodestar/utils";
+import {getFastifySchema} from "../schema.js";
+import {Endpoint, RouteDefinition, RouteDefinitions} from "../types.js";
+import {toColonNotationPath} from "../urlFormat.js";
+import {FastifyHandler, createFastifyHandler} from "./handler.js";
+import {ApplicationMethod, ApplicationMethods} from "./method.js";
+
+export type FastifySchema = fastify.FastifySchema & {
+  operationId: string;
+  tags?: string[];
+};
+
+export type FastifyRoute<E extends Endpoint> = {
+  url: string;
+  method: fastify.HTTPMethods;
+  handler: FastifyHandler<E>;
+  schema: FastifySchema;
+};
+export type FastifyRoutes<Es extends Record<string, Endpoint>> = {[K in keyof Es]: FastifyRoute<Es[K]>};
+
+export function createFastifyRoute<E extends Endpoint>(
+  definition: RouteDefinition<E>,
+  method: ApplicationMethod<E>,
+  operationId: string
+): FastifyRoute<E> {
+  return {
+    url: toColonNotationPath(definition.url),
+    method: definition.method,
+    handler: createFastifyHandler(definition, method, operationId),
+    schema: {
+      ...getFastifySchema(definition.req.schema),
+      operationId,
+    },
+  };
+}
+
+export function createFastifyRoutes<Es extends Record<string, Endpoint>>(
+  definitions: RouteDefinitions<Es>,
+  methods: ApplicationMethods<Es>
+): FastifyRoutes<Es> {
+  return mapValues(definitions, (definition, operationId) =>
+    createFastifyRoute(definition, methods?.[operationId]?.bind(methods), operationId as string)
+  );
+}

package/src/utils/types.ts

@@ -0,0 +1,161 @@
+import {ExtraRequestInit} from "./client/request.js";
+import {EmptyMeta} from "./codecs.js";
+import {HeadersExtra} from "./headers.js";
+import {SchemaDefinition} from "./schema.js";
+import {WireFormat} from "./wireFormat.js";
+
+export type HasOnlyOptionalProps<T> = {
+  [K in keyof T]-?: object extends Pick<T, K> ? never : K;
+} extends {[K2 in keyof T]: never}
+  ? true
+  : false;
+
+export type PathParams = Record<string, string | number>;
+export type QueryParams = Record<string, string | number | boolean | (string | number)[]>;
+export type HeaderParams = Record<string, string>;
+
+export type RequestData<
+  P extends PathParams = PathParams,
+  Q extends QueryParams = QueryParams,
+  H extends HeaderParams = HeaderParams,
+> = {
+  params?: P;
+  query?: Q;
+  headers?: H;
+};
+
+export type JsonRequestData<
+  B = unknown,
+  P extends PathParams = PathParams,
+  Q extends QueryParams = QueryParams,
+  H extends HeaderParams = HeaderParams,
+> = RequestData<P, Q, H> & {
+  body?: B;
+};
+
+export type SszRequestData<P extends JsonRequestData> = Omit<P, "body"> &
+  ("body" extends keyof P ? (P["body"] extends void ? {body?: never} : {body: Uint8Array}) : {body?: never});
+
+export type HttpMethod = "GET" | "POST" | "DELETE";
+
+/**
+ * This type describes the general shape of a route
+ *
+ * This includes both http and application-level shape
+ * - The http method
+ *   - Used to more strictly enforce the shape of the request
+ * - The application-level parameters
+ *   - this enforces the shape of the input data passed by the client and to the route handler
+ * - The http request
+ *   - this enforces the shape of the querystring, url params, request body
+ * - The application-level return data
+ *   - this enforces the shape of the output data passed back to the client and returned by the route handler
+ * - The application-level return metadata
+ *   - this enforces the shape of the returned metadata, used informationally and to help decode the return data
+ */
+export type Endpoint<
+  Method extends HttpMethod = HttpMethod,
+  ArgsType = unknown,
+  RequestType extends Method extends "GET" ? RequestData : JsonRequestData = JsonRequestData,
+  ReturnType = unknown,
+  Meta = unknown,
+> = {
+  method: Method;
+  /** The parameters the client passes / server app code ingests */
+  args: ArgsType;
+  /** The parameters in the http request */
+  request: RequestType;
+  /** The return data */
+  return: ReturnType;
+  /** The return metadata */
+  meta: Meta;
+};
+
+// Request codec
+
+/** Encode / decode requests to & from function params, as well as schema definitions */
+export type RequestWithoutBodyCodec<E extends Endpoint> = {
+  writeReq: (p: E["args"]) => E["request"]; // client
+  parseReq: (r: E["request"]) => E["args"]; // server
+  schema: SchemaDefinition<E["request"]>;
+};
+
+export type JsonRequestMethods<E extends Endpoint> = {
+  writeReqJson: (p: E["args"]) => E["request"]; // client
+  parseReqJson: (r: E["request"]) => E["args"]; // server
+};
+
+export type SszRequestMethods<E extends Endpoint> = {
+  writeReqSsz: (p: E["args"]) => SszRequestData<E["request"]>; // client
+  parseReqSsz: (r: SszRequestData<E["request"]>) => E["args"]; // server
+};
+
+export type RequestWithBodyCodec<E extends Endpoint> = JsonRequestMethods<E> &
+  SszRequestMethods<E> & {
+    schema: SchemaDefinition<E["request"]>;
+    /** Support ssz-only or json-only requests */
+    onlySupport?: WireFormat;
+  };
+
+/**
+ * Handles translation between `Endpoint["args"]` and `Endpoint["request"]`
+ */
+export type RequestCodec<E extends Endpoint> = E["method"] extends "GET"
+  ? RequestWithoutBodyCodec<E>
+  : "body" extends keyof E["request"]
+    ? RequestWithBodyCodec<E>
+    : RequestWithoutBodyCodec<E>;
+
+export function isRequestWithoutBody<E extends Endpoint>(
+  definition: RouteDefinition<E>
+): definition is RouteDefinition<E> & {req: RequestWithoutBodyCodec<E>} {
+  return definition.method === "GET" || definition.req.schema.body === undefined;
+}
+
+// Response codec
+
+export type ResponseDataCodec<T, M> = {
+  toJson: (data: T, meta: M) => unknown; // server
+  fromJson: (data: unknown, meta: M) => T; // client
+  serialize: (data: T, meta: M) => Uint8Array; // server
+  deserialize: (data: Uint8Array, meta: M) => T; // client
+};
+
+export type ResponseMetadataCodec<T> = {
+  toJson: (val: T) => unknown; // server
+  fromJson: (val: unknown) => T; // client
+  toHeadersObject: (val: T) => Record<string, string>; // server
+  fromHeaders: (headers: HeadersExtra) => T; // server
+};
+
+export type ResponseCodec<E extends Endpoint> = {
+  data: ResponseDataCodec<E["return"], E["meta"]>;
+  meta: ResponseMetadataCodec<E["meta"]>;
+  /** Occasionally, json responses require an extra transformation to separate the data from metadata */
+  transform?: {
+    toResponse: (data: unknown, meta: unknown) => unknown;
+    fromResponse: (resp: unknown) => {
+      data: E["return"];
+    } & (E["meta"] extends EmptyMeta ? {meta?: never} : {meta: E["meta"]});
+  };
+  /** Support ssz-only or json-only responses */
+  onlySupport?: WireFormat;
+  /** Indicator used to handle empty responses */
+  isEmpty?: true;
+};
+
+/**
+ * Top-level definition of a route used by both the client and server
+ * - url and method
+ * - request and response codec
+ * - request json schema
+ */
+export type RouteDefinition<E extends Endpoint> = {
+  url: string;
+  method: E["method"];
+  req: RequestCodec<E>;
+  resp: ResponseCodec<E>;
+  init?: ExtraRequestInit;
+};
+
+export type RouteDefinitions<Es extends Record<string, Endpoint>> = {[K in keyof Es]: RouteDefinition<Es[K]>};