@lodestar/api 1.20.0-dev.f6d3bce802 → 1.20.0-dev.ff253a7e4b

package/lib/utils/server/handler.js

@@ -0,0 +1,109 @@
+import { HttpHeader, MediaType, SUPPORTED_MEDIA_TYPES, parseAcceptHeader, parseContentTypeHeader } from "../headers.js";
+import { isRequestWithoutBody, } from "../types.js";
+import { WireFormat, fromWireFormat, getWireFormat } from "../wireFormat.js";
+import { ApiError } from "./error.js";
+export function createFastifyHandler(definition, method, _operationId) {
+    return async (req, resp) => {
+        // Determine response wire format first to inform application method
+        // about the preferable return type to avoid unnecessary serialization
+        let responseMediaType;
+        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 || acceptHeader === "*/*") {
+            // 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 response;
+        try {
+            if (isRequestWithoutBody(definition)) {
+                response = await method(definition.req.parseReq(req), {
+                    sszBytes: null,
+                    returnBytes: responseWireFormat === WireFormat.ssz,
+                });
+            }
+            else {
+                const contentType = req.headers[HttpHeader.ContentType];
+                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]}`);
+                }
+                const requestWireFormat = getWireFormat(requestMediaType);
+                const { onlySupport } = definition.req;
+                if (onlySupport !== undefined && onlySupport !== requestWireFormat) {
+                    throw new ApiError(415, `Endpoint only supports ${onlySupport.toUpperCase()} requests`);
+                }
+                switch (requestWireFormat) {
+                    case WireFormat.json:
+                        response = await method(definition.req.parseReqJson(req), {
+                            sszBytes: null,
+                            returnBytes: responseWireFormat === WireFormat.ssz,
+                        });
+                        break;
+                    case WireFormat.ssz:
+                        response = await method(definition.req.parseReqSsz(req), {
+                            sszBytes: req.body,
+                            returnBytes: responseWireFormat === WireFormat.ssz,
+                        });
+                        break;
+                }
+            }
+        }
+        catch (e) {
+            if (e instanceof ApiError)
+                throw e;
+            // Errors related to parsing should return 400 status code
+            throw new ApiError(400, e.message);
+        }
+        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,
+                };
+            }
+            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;
+        }
+    };
+}
+//# sourceMappingURL=handler.js.map

package/lib/utils/server/handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler.js","sourceRoot":"","sources":["../../../src/utils/server/handler.ts"],"names":[],"mappings":"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"}

package/lib/utils/server/index.d.ts

@@ -1,5 +1,6 @@
-export * from "./genericJsonServer.js";
-export * from "./registerRoute.js";
-export * from "./errors.js";
-export * from "./types.js";
+export * from "./error.js";
+export * from "./handler.js";
+export * from "./method.js";
+export * from "./parser.js";
+export * from "./route.js";
 //# sourceMappingURL=index.d.ts.map

package/lib/utils/server/index.js

@@ -1,5 +1,6 @@
-export * from "./genericJsonServer.js";
-export * from "./registerRoute.js";
-export * from "./errors.js";
-export * from "./types.js";
+export * from "./error.js";
+export * from "./handler.js";
+export * from "./method.js";
+export * from "./parser.js";
+export * from "./route.js";
 //# sourceMappingURL=index.js.map

package/lib/utils/server/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/utils/server/index.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAC;AACvC,cAAc,oBAAoB,CAAC;AACnC,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/utils/server/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC"}

package/lib/utils/server/method.d.ts

@@ -0,0 +1,35 @@
+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]>;
+};
+export {};
+//# sourceMappingURL=method.d.ts.map

package/lib/utils/server/method.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=method.js.map

package/lib/utils/server/method.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"method.js","sourceRoot":"","sources":["../../../src/utils/server/method.ts"],"names":[],"mappings":""}

package/lib/utils/server/parser.d.ts

@@ -0,0 +1,3 @@
+import type * as fastify from "fastify";
+export declare function addSszContentTypeParser(server: fastify.FastifyInstance): void;
+//# sourceMappingURL=parser.d.ts.map

package/lib/utils/server/parser.js

@@ -0,0 +1,20 @@
+import { MediaType } from "../headers.js";
+export function addSszContentTypeParser(server) {
+    // Cache body schema symbol, does not change per request
+    let bodySchemaSymbol;
+    server.addContentTypeParser(MediaType.ssz, { parseAs: "buffer" }, async (request, payload) => {
+        if (bodySchemaSymbol === undefined) {
+            // Get body schema symbol to be able to access validation function
+            // https://github.com/fastify/fastify/blob/af2ccb5ff681c1d0ac22eb7314c6fa803f73c873/lib/symbols.js#L25
+            bodySchemaSymbol = Object.getOwnPropertySymbols(request.context).find((s) => s.description === "body-schema");
+        }
+        // JSON schema validation will be applied to `Buffer` object, it is required to override validation function
+        // See https://github.com/fastify/help/issues/1012, it is not possible right now to define a schema per content type
+        request.context[bodySchemaSymbol] = () => true;
+        // 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);
+    });
+}
+//# sourceMappingURL=parser.js.map

package/lib/utils/server/parser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.js","sourceRoot":"","sources":["../../../src/utils/server/parser.ts"],"names":[],"mappings":"AACA,OAAO,EAAC,SAAS,EAAC,MAAM,eAAe,CAAC;AAExC,MAAM,UAAU,uBAAuB,CAAC,MAA+B;IACrE,wDAAwD;IACxD,IAAI,gBAAoC,CAAC;IAEzC,MAAM,CAAC,oBAAoB,CACzB,SAAS,CAAC,GAAG,EACb,EAAC,OAAO,EAAE,QAAQ,EAAC,EACnB,KAAK,EAAE,OAA+B,EAAE,OAAe,EAAE,EAAE;QACzD,IAAI,gBAAgB,KAAK,SAAS,EAAE,CAAC;YACnC,kEAAkE;YAClE,sGAAsG;YACtG,gBAAgB,GAAG,MAAM,CAAC,qBAAqB,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,KAAK,aAAa,CAAC,CAAC;QAChH,CAAC;QACD,4GAA4G;QAC5G,oHAAoH;QACnH,OAAO,CAAC,OAA8C,CAAC,gBAA0B,CAAC,GAAG,GAAG,EAAE,CAAC,IAAI,CAAC;QAEjG,qHAAqH;QACrH,sHAAsH;QACtH,0EAA0E;QAC1E,OAAO,IAAI,UAAU,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,UAAU,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;IAChF,CAAC,CACF,CAAC;AACJ,CAAC"}

package/lib/utils/server/route.d.ts

@@ -0,0 +1,20 @@
+import type * as fastify from "fastify";
+import { Endpoint, RouteDefinition, RouteDefinitions } from "../types.js";
+import { FastifyHandler } 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 declare function createFastifyRoute<E extends Endpoint>(definition: RouteDefinition<E>, method: ApplicationMethod<E>, operationId: string): FastifyRoute<E>;
+export declare function createFastifyRoutes<Es extends Record<string, Endpoint>>(definitions: RouteDefinitions<Es>, methods: ApplicationMethods<Es>): FastifyRoutes<Es>;
+//# sourceMappingURL=route.d.ts.map

package/lib/utils/server/route.js

@@ -0,0 +1,19 @@
+import { mapValues } from "@lodestar/utils";
+import { getFastifySchema } from "../schema.js";
+import { toColonNotationPath } from "../urlFormat.js";
+import { createFastifyHandler } from "./handler.js";
+export function createFastifyRoute(definition, method, operationId) {
+    return {
+        url: toColonNotationPath(definition.url),
+        method: definition.method,
+        handler: createFastifyHandler(definition, method, operationId),
+        schema: {
+            ...getFastifySchema(definition.req.schema),
+            operationId,
+        },
+    };
+}
+export function createFastifyRoutes(definitions, methods) {
+    return mapValues(definitions, (definition, operationId) => createFastifyRoute(definition, methods?.[operationId]?.bind(methods), operationId));
+}
+//# sourceMappingURL=route.js.map

package/lib/utils/server/route.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"route.js","sourceRoot":"","sources":["../../../src/utils/server/route.ts"],"names":[],"mappings":"AACA,OAAO,EAAC,SAAS,EAAC,MAAM,iBAAiB,CAAC;AAC1C,OAAO,EAAC,gBAAgB,EAAC,MAAM,cAAc,CAAC;AAE9C,OAAO,EAAC,mBAAmB,EAAC,MAAM,iBAAiB,CAAC;AACpD,OAAO,EAAiB,oBAAoB,EAAC,MAAM,cAAc,CAAC;AAgBlE,MAAM,UAAU,kBAAkB,CAChC,UAA8B,EAC9B,MAA4B,EAC5B,WAAmB;IAEnB,OAAO;QACL,GAAG,EAAE,mBAAmB,CAAC,UAAU,CAAC,GAAG,CAAC;QACxC,MAAM,EAAE,UAAU,CAAC,MAAM;QACzB,OAAO,EAAE,oBAAoB,CAAC,UAAU,EAAE,MAAM,EAAE,WAAW,CAAC;QAC9D,MAAM,EAAE;YACN,GAAG,gBAAgB,CAAC,UAAU,CAAC,GAAG,CAAC,MAAM,CAAC;YAC1C,WAAW;SACZ;KACF,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,mBAAmB,CACjC,WAAiC,EACjC,OAA+B;IAE/B,OAAO,SAAS,CAAC,WAAW,EAAE,CAAC,UAAU,EAAE,WAAW,EAAE,EAAE,CACxD,kBAAkB,CAAC,UAAU,EAAE,OAAO,EAAE,CAAC,WAAW,CAAC,EAAE,IAAI,CAAC,OAAO,CAAC,EAAE,WAAqB,CAAC,CAC7F,CAAC;AACJ,CAAC"}

package/lib/utils/types.d.ts

@@ -1,117 +1,129 @@
-import { Type, ArrayType } from "@chainsafe/ssz";
-import { ForkName } from "@lodestar/params";
-import { ChainForkConfig } from "@lodestar/config";
-import { APIClientHandler, ApiClientResponseData, APIServerHandler, ClientApi } from "../interfaces.js";
-import { Schema, SchemaDefinition } from "./schema.js";
-export type RouteGroupDefinition<Api extends Record<string, APIServerHandler>, ReqTypes extends {
-    [K in keyof Api]: ReqGeneric;
-}> = {
-    routesData: RoutesData<Api>;
-    getReqSerializers: (config: ChainForkConfig) => ReqSerializers<Api, ReqTypes>;
-    getReturnTypes: (config: ChainForkConfig) => ReturnTypes<ClientApi<Api>>;
+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 {
+    [_ 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 RouteDef = {
-    url: string;
-    method: "GET" | "POST" | "DELETE";
-    statusOk?: number;
+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 ReqGeneric = {
-    params?: Record<string, string | number>;
-    query?: Record<string, string | number | boolean | (string | number)[]>;
-    body?: any;
-    headers?: Record<string, string[] | string | undefined>;
+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;
 };
-export type ReqEmpty = ReqGeneric;
-export type Resolves<T extends (...args: any) => any> = Awaited<ReturnType<T>>;
-export type TypeJson<T> = {
-    toJson(val: T): unknown;
-    fromJson(json: unknown): T;
+/** Encode / decode requests to & from function params, as well as schema definitions */
+export type RequestWithoutBodyCodec<E extends Endpoint> = {
+    writeReq: (p: E["args"]) => E["request"];
+    parseReq: (r: E["request"]) => E["args"];
+    schema: SchemaDefinition<E["request"]>;
 };
-export type ReqSerializer<Fn extends (...args: any) => any, ReqType extends ReqGeneric> = {
-    writeReq: (...args: Parameters<Fn>) => ReqType;
-    parseReq: (arg: ReqType) => Parameters<Fn>;
-    schema?: SchemaDefinition<ReqType>;
+export type JsonRequestMethods<E extends Endpoint> = {
+    writeReqJson: (p: E["args"]) => E["request"];
+    parseReqJson: (r: E["request"]) => E["args"];
 };
-export type ReqSerializers<Api extends Record<string, APIServerHandler>, ReqTypes extends {
-    [K in keyof Api]: ReqGeneric;
-}> = {
-    [K in keyof Api]: ReqSerializer<Api[K], ReqTypes[K]>;
+export type SszRequestMethods<E extends Endpoint> = {
+    writeReqSsz: (p: E["args"]) => SszRequestData<E["request"]>;
+    parseReqSsz: (r: SszRequestData<E["request"]>) => E["args"];
+};
+export type RequestWithBodyCodec<E extends Endpoint> = JsonRequestMethods<E> & SszRequestMethods<E> & {
+    schema: SchemaDefinition<E["request"]>;
+    /** Support ssz-only or json-only requests */
+    onlySupport?: WireFormat;
 };
-/** Curried definition to infer only one of the two generic types */
-export type ReqGenArg<Fn extends (...args: any) => any, ReqType extends ReqGeneric> = ReqSerializer<Fn, ReqType>;
-/** Shortcut for routes that have no params, query nor body */
-export declare const reqEmpty: ReqSerializer<() => void, ReqEmpty>;
-/** Shortcut for routes that have only body */
-export declare const reqOnlyBody: <T>(type: TypeJson<T>, bodySchema: Schema) => ReqGenArg<(arg: T) => Promise<void>, {
-    body: unknown;
-}>;
-/** SSZ factory helper + typed. limit = 1e6 as a big enough random number */
-export declare function ArrayOf<T>(elementType: Type<T>): ArrayType<Type<T>, unknown, unknown>;
-/**
- * SSZ factory helper + typed to return responses of type
- * ```
- * data: T
- * ```
- */
-export declare function ContainerData<T>(dataType: TypeJson<T>): TypeJson<{
-    data: T;
-}>;
-/**
- * SSZ factory helper + typed to return responses of type `{data: T; executionOptimistic: boolean}`
- */
-export declare function ContainerDataExecutionOptimistic<T>(dataType: TypeJson<T>): TypeJson<{
-    data: T;
-    executionOptimistic: boolean;
-}>;
-/**
- * SSZ factory helper + typed to return responses of type
- * ```
- * data: T
- * version: ForkName
- * ```
- */
-export declare function WithVersion<T>(getType: (fork: ForkName) => TypeJson<T>): TypeJson<{
-    data: T;
-    version: ForkName;
-}>;
-/**
- * SSZ factory helper to wrap an existing type with `{executionOptimistic: boolean}`
- */
-export declare function WithExecutionOptimistic<T extends {
-    data: unknown;
-}>(type: TypeJson<T>): TypeJson<T & {
-    executionOptimistic: boolean;
-}>;
 /**
- * SSZ factory helper to wrap an existing type with `{finalized: boolean}`
+ * Handles translation between `Endpoint["args"]` and `Endpoint["request"]`
  */
-export declare function WithFinalized<T extends {
-    data: unknown;
-}>(type: TypeJson<T>): TypeJson<T & {
-    finalized: boolean;
-}>;
+export type RequestCodec<E extends Endpoint> = E["method"] extends "GET" ? RequestWithoutBodyCodec<E> : "body" extends keyof E["request"] ? RequestWithBodyCodec<E> : RequestWithoutBodyCodec<E>;
+export declare function isRequestWithoutBody<E extends Endpoint>(definition: RouteDefinition<E>): definition is RouteDefinition<E> & {
+    req: RequestWithoutBodyCodec<E>;
+};
+export type ResponseDataCodec<T, M> = {
+    toJson: (data: T, meta: M) => unknown;
+    fromJson: (data: unknown, meta: M) => T;
+    serialize: (data: T, meta: M) => Uint8Array;
+    deserialize: (data: Uint8Array, meta: M) => T;
+};
+export type ResponseMetadataCodec<T> = {
+    toJson: (val: T) => unknown;
+    fromJson: (val: unknown) => T;
+    toHeadersObject: (val: T) => Record<string, string>;
+    fromHeaders: (headers: HeadersExtra) => T;
+};
+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;
+};
 /**
- * SSZ factory helper to wrap an existing type with `{executionPayloadValue: Wei, consensusBlockValue: Wei}`
+ * Top-level definition of a route used by both the client and server
+ * - url and method
+ * - request and response codec
+ * - request json schema
  */
-export declare function WithBlockValues<T extends {
-    data: unknown;
-}>(type: TypeJson<T>): TypeJson<T & {
-    executionPayloadValue: bigint;
-    consensusBlockValue: bigint;
-}>;
-type JsonCase = "snake" | "constant" | "camel" | "param" | "header" | "pascal" | "dot" | "notransform";
-/** Helper to only translate casing */
-export declare function jsonType<T extends Record<string, unknown> | Record<string, unknown>[] | unknown[]>(jsonCase: JsonCase): TypeJson<T>;
-/** Helper to not do any transformation with the type */
-export declare function sameType<T>(): TypeJson<T>;
-export type KeysOfNonVoidResolveValues<Api extends Record<string, APIClientHandler>> = {
-    [K in keyof Api]: ApiClientResponseData<Resolves<Api[K]>> extends void ? never : K;
-}[keyof Api];
-export type ReturnTypes<Api extends Record<string, APIClientHandler>> = {
-    [K in keyof Pick<Api, KeysOfNonVoidResolveValues<Api>>]: TypeJson<ApiClientResponseData<Resolves<Api[K]>>>;
+export type RouteDefinition<E extends Endpoint> = {
+    url: string;
+    method: E["method"];
+    req: RequestCodec<E>;
+    resp: ResponseCodec<E>;
+    init?: ExtraRequestInit;
 };
-export type RoutesData<Api extends Record<string, APIServerHandler>> = {
-    [K in keyof Api]: RouteDef;
+export type RouteDefinitions<Es extends Record<string, Endpoint>> = {
+    [K in keyof Es]: RouteDefinition<Es[K]>;
 };
-export {};
 //# sourceMappingURL=types.d.ts.map