@lodestar/api 1.47.0-dev.d2f4b96574 → 1.47.0-dev.d477ac6ef7

package/src/beacon/routes/validator.ts

@@ -1,9 +1,12 @@
-import {ContainerType, Type, ValueOf} from "@chainsafe/ssz";
+import {ByteListType, ContainerType, Type, ValueOf} from "@chainsafe/ssz";
 import {ChainForkConfig} from "@lodestar/config";
 import {
   ForkPostDeneb,
   ForkPostGloas,
   ForkPreDeneb,
+  MAX_BUILDER_ENTRIES,
+  MAX_BUILDER_PUBKEYS,
+  MAX_BUILDER_URL_SIZE,
   MIN_SEED_LOOKAHEAD,
   SLOTS_PER_EPOCH,
   VALIDATOR_REGISTRY_LIMIT,
@@ -76,15 +79,21 @@ export type ExtraProduceBlockOpts = {
   blindedLocal?: boolean;
 };
 
+/** Lodestar-specific (non-standardized) options */
+export type ExtraProduceBlockV4Opts = {
+  feeRecipient?: string;
+  strictFeeRecipientCheck?: boolean;
+};
+
 export const ProduceBlockV3MetaType = new ContainerType(
   {
     ...VersionType.fields,
     /** Specifies whether the response contains full or blinded block */
     executionPayloadBlinded: ssz.Boolean,
     /** Execution payload value in Wei */
-    executionPayloadValue: ssz.UintBn64,
+    executionPayloadValue: ssz.Wei,
     /** Consensus rewards paid to the proposer for this block, in Wei */
-    consensusBlockValue: ssz.UintBn64,
+    consensusBlockValue: ssz.Wei,
   },
   {jsonCase: "eth2"}
 );
@@ -98,16 +107,19 @@ export const ProduceBlockV4MetaType = new ContainerType(
   {
     ...VersionType.fields,
     /** Consensus rewards paid to the proposer for this block, in Wei */
-    consensusBlockValue: ssz.UintBn64,
+    consensusBlockValue: ssz.Wei,
     /** Local execution payload value when self-building, or builder bid value when committing to a bid, in Wei */
-    executionPayloadValue: ssz.UintBn64,
+    executionPayloadValue: ssz.Wei,
     /** Specifies whether the response contains full block contents or only the beacon block */
     executionPayloadIncluded: ssz.Boolean,
   },
   {jsonCase: "eth2"}
 );
 
-export type ProduceBlockV4Meta = ValueOf<typeof ProduceBlockV4MetaType>;
+export type ProduceBlockV4Meta = ValueOf<typeof ProduceBlockV4MetaType> & {
+  /** The url of the winning builder when the bid came through the builder API channel */
+  builderUrl?: string;
+};
 
 export const AttesterDutyType = new ContainerType(
   {
@@ -258,6 +270,59 @@ export const SignedProposerPreferencesListType = ArrayOf(
   (MIN_SEED_LOOKAHEAD + 1) * SLOTS_PER_EPOCH
 );
 
+// The url is UTF-8 bytes on the SSZ wire but a plain string in JSON
+class BuilderUrlType extends ByteListType {
+  fromJson(json: unknown): Uint8Array {
+    if (typeof json !== "string") {
+      throw Error("Builder url must be a string");
+    }
+    const value = new TextEncoder().encode(json);
+    if (value.length > this.limitBytes) {
+      throw Error(`Builder url must not exceed ${this.limitBytes} bytes`);
+    }
+    return value;
+  }
+  toJson(value: Uint8Array): unknown {
+    return new TextDecoder("utf8", {fatal: true}).decode(value);
+  }
+}
+
+export const BuilderEntryType = new ContainerType(
+  {
+    url: new BuilderUrlType(MAX_BUILDER_URL_SIZE),
+    auth: ssz.gloas.SignedBuilderRequestAuth,
+    builderPubkeys: ArrayOf(ssz.BLSPubkey, MAX_BUILDER_PUBKEYS),
+    maxExecutionPayment: ssz.Gwei,
+    minBid: ssz.Gwei,
+    builderBoostFactor: ssz.UintBn64,
+  },
+  {typeName: "BuilderEntry", jsonCase: "eth2"}
+);
+
+export const BuilderConfigType = new ContainerType(
+  {
+    minBid: ssz.Gwei,
+    builderBoostFactor: ssz.UintBn64,
+    builders: ArrayOf(BuilderEntryType, MAX_BUILDER_ENTRIES),
+  },
+  {typeName: "BuilderConfig", jsonCase: "eth2"}
+);
+
+export const BuilderPreferencesEntryType = new ContainerType(
+  {
+    proposerPubkey: ssz.BLSPubkey,
+    url: new BuilderUrlType(MAX_BUILDER_URL_SIZE),
+    auth: ssz.gloas.SignedBuilderRequestAuth,
+    maxExecutionPayment: ssz.Gwei,
+  },
+  {typeName: "BuilderPreferencesEntry", jsonCase: "eth2"}
+);
+
+export const BuilderPreferencesEntryListType = ArrayOf(
+  BuilderPreferencesEntryType,
+  MAX_BUILDER_ENTRIES * (MIN_SEED_LOOKAHEAD + 1) * SLOTS_PER_EPOCH
+);
+
 export type ValidatorIndices = ValueOf<typeof ValidatorIndicesType>;
 export type AttesterDuty = ValueOf<typeof AttesterDutyType>;
 export type AttesterDutyList = ValueOf<typeof AttesterDutyListType>;
@@ -285,6 +350,10 @@ export type LivenessResponseData = ValueOf<typeof LivenessResponseDataType>;
 export type LivenessResponseDataList = ValueOf<typeof LivenessResponseDataListType>;
 export type SignedValidatorRegistrationV1List = ValueOf<typeof SignedValidatorRegistrationV1ListType>;
 export type SignedProposerPreferencesList = ValueOf<typeof SignedProposerPreferencesListType>;
+export type BuilderEntry = ValueOf<typeof BuilderEntryType>;
+export type BuilderConfig = ValueOf<typeof BuilderConfigType>;
+export type BuilderPreferencesEntry = ValueOf<typeof BuilderPreferencesEntryType>;
+export type BuilderPreferencesEntryList = ValueOf<typeof BuilderPreferencesEntryListType>;
 
 // The beacon node does not return any data if there is no canonical block at the requested slot (missed slot).
 // In this case, we receive a success response (204) which is not handled as an error. The generic response
@@ -427,6 +496,9 @@ export type Endpoints = {
    * so there is no longer a concept of blinded or unblinded blocks. Builders release the payload later.
    * This endpoint is specific to the post-Gloas forks and is not backwards compatible with previous forks.
    *
+   * The required `BuilderConfig` request body carries the builder entries to solicit builder API
+   * bids from, plus the top-level `minBid` and `builderBoostFactor` that apply to p2p bids.
+   *
    * When self-building and `includePayload` is true, the response contains the full `BlockContents`
    * (block, execution payload envelope, KZG proofs and blobs) which enables stateless envelope
    * publishing via any beacon node. When `includePayload` is false, only the `BeaconBlock` is
@@ -434,7 +506,7 @@ export type Endpoints = {
    * When committing to a builder bid, only the `BeaconBlock` is returned in either case.
    */
   produceBlockV4: Endpoint<
-    "GET",
+    "POST",
     {
       /** The slot for which the block should be proposed */
       slot: Slot;
@@ -443,10 +515,10 @@ export type Endpoints = {
       /** Arbitrary data validator wants to include in block */
       graffiti?: string;
       skipRandaoVerification?: boolean;
-      builderBoostFactor?: UintBn64;
       /** Include execution payload envelope and blobs in the response when self-building */
       includePayload: boolean;
-    } & Omit<ExtraProduceBlockOpts, "blindedLocal">,
+      builderConfig: BuilderConfig;
+    } & ExtraProduceBlockV4Opts,
     {
       params: {slot: number};
       query: {
@@ -454,11 +526,11 @@ export type Endpoints = {
         graffiti?: string;
         skip_randao_verification?: string;
         fee_recipient?: string;
-        builder_selection?: string;
-        builder_boost_factor?: string;
         strict_fee_recipient_check?: boolean;
         include_payload: boolean;
       };
+      body: unknown;
+      headers: {[MetaHeader.Version]: string};
     },
     BeaconBlock<ForkPostGloas> | BlockContents<ForkPostGloas>,
     ProduceBlockV4Meta
@@ -688,6 +760,19 @@ export type Endpoints = {
     EmptyResponseData,
     EmptyMeta
   >;
+
+  /**
+   * Submit per-builder preferences for one or more proposers ahead of their proposal slot.
+   * The beacon node submits each entry to the builder API endpoint at the entry's url so
+   * builders hold the preferences before the bid request arrives.
+   */
+  submitBuilderPreferences: Endpoint<
+    "POST",
+    {builderPreferences: BuilderPreferencesEntryList},
+    {body: unknown; headers: {[MetaHeader.Version]: string}},
+    EmptyResponseData,
+    EmptyMeta
+  >;
 };
 
 export function getDefinitions(config: ChainForkConfig): RouteDefinitions<Endpoints> {
@@ -910,18 +995,17 @@ export function getDefinitions(config: ChainForkConfig): RouteDefinitions<Endpoi
     },
     produceBlockV4: {
       url: "/eth/v4/validator/blocks/{slot}",
-      method: "GET",
+      method: "POST",
       req: {
-        writeReq: ({
+        writeReqJson: ({
           slot,
           randaoReveal,
           graffiti,
           skipRandaoVerification,
           feeRecipient,
-          builderSelection,
-          builderBoostFactor,
           strictFeeRecipientCheck,
           includePayload,
+          builderConfig,
         }) => ({
           params: {slot},
           query: {
@@ -929,23 +1013,60 @@ export function getDefinitions(config: ChainForkConfig): RouteDefinitions<Endpoi
             graffiti: toGraffitiHex(graffiti),
             skip_randao_verification: writeSkipRandaoVerification(skipRandaoVerification),
             fee_recipient: feeRecipient,
-            builder_selection: builderSelection,
-            builder_boost_factor: builderBoostFactor?.toString(),
             strict_fee_recipient_check: strictFeeRecipientCheck,
             include_payload: includePayload,
           },
+          body: BuilderConfigType.toJson(builderConfig),
+          headers: {[MetaHeader.Version]: config.getForkName(slot)},
         }),
-        parseReq: ({params, query}) => ({
-          slot: params.slot,
-          randaoReveal: fromHex(query.randao_reveal),
-          graffiti: fromGraffitiHex(query.graffiti),
-          skipRandaoVerification: parseSkipRandaoVerification(query.skip_randao_verification),
-          feeRecipient: query.fee_recipient,
-          builderSelection: query.builder_selection as BuilderSelection,
-          builderBoostFactor: parseBuilderBoostFactor(query.builder_boost_factor),
-          strictFeeRecipientCheck: query.strict_fee_recipient_check,
-          includePayload: query.include_payload,
+        parseReqJson: ({params, query, body, headers}) => {
+          toForkName(fromHeaders(headers, MetaHeader.Version));
+          return {
+            slot: params.slot,
+            randaoReveal: fromHex(query.randao_reveal),
+            graffiti: fromGraffitiHex(query.graffiti),
+            skipRandaoVerification: parseSkipRandaoVerification(query.skip_randao_verification),
+            feeRecipient: query.fee_recipient,
+            strictFeeRecipientCheck: query.strict_fee_recipient_check,
+            includePayload: query.include_payload,
+            builderConfig: BuilderConfigType.fromJson(body),
+          };
+        },
+        writeReqSsz: ({
+          slot,
+          randaoReveal,
+          graffiti,
+          skipRandaoVerification,
+          feeRecipient,
+          strictFeeRecipientCheck,
+          includePayload,
+          builderConfig,
+        }) => ({
+          params: {slot},
+          query: {
+            randao_reveal: toHex(randaoReveal),
+            graffiti: toGraffitiHex(graffiti),
+            skip_randao_verification: writeSkipRandaoVerification(skipRandaoVerification),
+            fee_recipient: feeRecipient,
+            strict_fee_recipient_check: strictFeeRecipientCheck,
+            include_payload: includePayload,
+          },
+          body: BuilderConfigType.serialize(builderConfig),
+          headers: {[MetaHeader.Version]: config.getForkName(slot)},
         }),
+        parseReqSsz: ({params, query, body, headers}) => {
+          toForkName(fromHeaders(headers, MetaHeader.Version));
+          return {
+            slot: params.slot,
+            randaoReveal: fromHex(query.randao_reveal),
+            graffiti: fromGraffitiHex(query.graffiti),
+            skipRandaoVerification: parseSkipRandaoVerification(query.skip_randao_verification),
+            feeRecipient: query.fee_recipient,
+            strictFeeRecipientCheck: query.strict_fee_recipient_check,
+            includePayload: query.include_payload,
+            builderConfig: BuilderConfigType.deserialize(body),
+          };
+        },
         schema: {
           params: {slot: Schema.UintRequired},
           query: {
@@ -953,13 +1074,16 @@ export function getDefinitions(config: ChainForkConfig): RouteDefinitions<Endpoi
             graffiti: Schema.String,
             skip_randao_verification: Schema.String,
             fee_recipient: Schema.String,
-            builder_selection: Schema.String,
-            builder_boost_factor: Schema.String,
             strict_fee_recipient_check: Schema.Boolean,
             include_payload: Schema.BooleanRequired,
           },
+          body: Schema.Object,
+          headers: {[MetaHeader.Version]: Schema.String},
         },
       },
+      init: {
+        requestWireFormat: WireFormat.ssz,
+      },
       resp: {
         data: WithMeta(
           ({version, executionPayloadIncluded}) =>
@@ -971,18 +1095,23 @@ export function getDefinitions(config: ChainForkConfig): RouteDefinitions<Endpoi
         ),
         meta: {
           toJson: (meta) => ProduceBlockV4MetaType.toJson(meta),
-          fromJson: (val) => ProduceBlockV4MetaType.fromJson(val),
+          fromJson: (val, headers) => ({
+            ...ProduceBlockV4MetaType.fromJson(val),
+            builderUrl: headers?.get(MetaHeader.BuilderUrl) ?? undefined,
+          }),
           toHeadersObject: (meta) => ({
             [MetaHeader.Version]: meta.version,
             [MetaHeader.ConsensusBlockValue]: meta.consensusBlockValue.toString(),
             [MetaHeader.ExecutionPayloadValue]: meta.executionPayloadValue.toString(),
             [MetaHeader.ExecutionPayloadIncluded]: meta.executionPayloadIncluded.toString(),
+            ...(meta.builderUrl !== undefined ? {[MetaHeader.BuilderUrl]: meta.builderUrl} : {}),
           }),
           fromHeaders: (headers) => ({
             version: toForkName(headers.getRequired(MetaHeader.Version)),
             consensusBlockValue: BigInt(headers.getRequired(MetaHeader.ConsensusBlockValue)),
             executionPayloadValue: BigInt(headers.getRequired(MetaHeader.ExecutionPayloadValue)),
             executionPayloadIncluded: toBoolean(headers.getRequired(MetaHeader.ExecutionPayloadIncluded)),
+            builderUrl: headers.get(MetaHeader.BuilderUrl) ?? undefined,
           }),
         },
       },
@@ -1294,6 +1423,36 @@ export function getDefinitions(config: ChainForkConfig): RouteDefinitions<Endpoi
       },
       resp: EmptyResponseCodec,
     },
+    submitBuilderPreferences: {
+      url: "/eth/v1/validator/builder_preferences",
+      method: "POST",
+      req: {
+        writeReqJson: ({builderPreferences}) => ({
+          body: BuilderPreferencesEntryListType.toJson(builderPreferences),
+          headers: {[MetaHeader.Version]: config.getForkName(builderPreferences[0]?.auth.message.slot ?? 0)},
+        }),
+        parseReqJson: ({body, headers}) => {
+          toForkName(fromHeaders(headers, MetaHeader.Version));
+          return {builderPreferences: BuilderPreferencesEntryListType.fromJson(body)};
+        },
+        writeReqSsz: ({builderPreferences}) => ({
+          body: BuilderPreferencesEntryListType.serialize(builderPreferences),
+          headers: {[MetaHeader.Version]: config.getForkName(builderPreferences[0]?.auth.message.slot ?? 0)},
+        }),
+        parseReqSsz: ({body, headers}) => {
+          toForkName(fromHeaders(headers, MetaHeader.Version));
+          return {builderPreferences: BuilderPreferencesEntryListType.deserialize(body)};
+        },
+        schema: {
+          body: Schema.ObjectArray,
+          headers: {[MetaHeader.Version]: Schema.String},
+        },
+      },
+      resp: EmptyResponseCodec,
+      init: {
+        requestWireFormat: WireFormat.ssz,
+      },
+    },
   };
 }
 

package/src/beacon/server/events.ts

@@ -42,10 +42,15 @@ export function getRoutes(config: ChainForkConfig, methods: ApplicationMethods<E
               topics: req.query.topics,
               signal: controller.signal,
               onEvent: (event) => {
+                // Serialization is per event and must not tear down the stream. Throwing here is
+                // handled by the caller which logs it and keeps the subscription alive, the client
+                // only misses this single event instead of silently losing the whole stream.
+                const data = eventSerdes.toJson(event);
+
                 try {
-                  const data = eventSerdes.toJson(event);
                   res.raw.write(serializeSSEEvent({event: event.type, data}));
                 } catch (e) {
+                  // The connection itself is broken, there is no way to recover it
                   reject(e);
                 }
               },
@@ -58,10 +63,12 @@ export function getRoutes(config: ChainForkConfig, methods: ApplicationMethods<E
             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();
+          // Always end the response. If an error is thrown after the headers were sent, fastify can
+          // no longer write a status code and would leave the socket open, the client then waits
+          // forever on a stream that will never emit another event.
+          if (!res.raw.writableEnded && !res.raw.destroyed) res.raw.end();
         }
       },
     },

package/src/builder/routes.ts

@@ -1,16 +1,18 @@
 import {ChainForkConfig} from "@lodestar/config";
-import {ForkName, VALIDATOR_REGISTRY_LIMIT, isForkPostDeneb} from "@lodestar/params";
+import {ForkName, ForkPostGloas, VALIDATOR_REGISTRY_LIMIT, isForkPostDeneb} from "@lodestar/params";
 import {
   ArrayOf,
   BLSPubkey,
   ExecutionPayload,
   ExecutionPayloadAndBlobsBundle,
   Root,
+  SignedBeaconBlock,
   SignedBlindedBeaconBlock,
   SignedBuilderBid,
   Slot,
   WithOptionalBytes,
   bellatrix,
+  gloas,
   ssz,
 } from "@lodestar/types";
 import {fromHex, toPubkeyHex, toRootHex} from "@lodestar/utils";
@@ -23,7 +25,7 @@ import {
   EmptyResponseData,
   WithVersion,
 } from "../utils/codecs.js";
-import {getPostBellatrixForkTypes, getPostDenebForkTypes, toForkName} from "../utils/fork.js";
+import {getPostBellatrixForkTypes, getPostDenebForkTypes, getPostGloasForkTypes, 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";
@@ -35,6 +37,9 @@ import {WireFormat} from "../utils/wireFormat.js";
 // 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;
 
+// Same as `MaybeSignedBuilderBid`, the builder responds with 204 if no bid is available
+export type MaybeSignedExecutionPayloadBid = gloas.SignedExecutionPayloadBid | undefined;
+
 const RegistrationsType = ArrayOf(ssz.bellatrix.SignedValidatorRegistrationV1, VALIDATOR_REGISTRY_LIMIT);
 
 export type Endpoints = {
@@ -82,6 +87,45 @@ export type Endpoints = {
     EmptyResponseData,
     EmptyMeta
   >;
+
+  getExecutionPayloadBid: Endpoint<
+    "POST",
+    {
+      slot: Slot;
+      parentHash: Root;
+      parentRoot: Root;
+      proposerPubkey: BLSPubkey;
+      /** Authenticates the requesting proposer to the builder */
+      requestAuth: gloas.SignedBuilderRequestAuth;
+      /** Unix timestamp in milliseconds at which the request was sent */
+      dateMilliseconds: number;
+      /** The proposer's timeout for the request in milliseconds, measured from `dateMilliseconds` */
+      timeoutMs: number;
+    },
+    {
+      params: {slot: Slot; parent_hash: string; parent_root: string; proposer_pubkey: string};
+      body: unknown;
+      headers: {[MetaHeader.Version]: string; [MetaHeader.DateMilliseconds]: string; [MetaHeader.TimeoutMs]: string};
+    },
+    MaybeSignedExecutionPayloadBid,
+    VersionMeta
+  >;
+
+  submitSignedBeaconBlock: Endpoint<
+    "POST",
+    {signedBlock: WithOptionalBytes<SignedBeaconBlock<ForkPostGloas>>},
+    {body: unknown; headers: {[MetaHeader.Version]: string}},
+    EmptyResponseData,
+    EmptyMeta
+  >;
+
+  submitBuilderPreferences: Endpoint<
+    "POST",
+    {proposerPubkey: BLSPubkey; request: gloas.BuilderPreferencesRequest},
+    {params: {proposer_pubkey: string}; body: unknown; headers: {[MetaHeader.Version]: string}},
+    EmptyResponseData,
+    EmptyMeta
+  >;
 };
 
 export function getDefinitions(config: ChainForkConfig): RouteDefinitions<Endpoints> {
@@ -223,5 +267,186 @@ export function getDefinitions(config: ChainForkConfig): RouteDefinitions<Endpoi
       },
       resp: EmptyResponseCodec,
     },
+    getExecutionPayloadBid: {
+      url: "/eth/v1/builder/execution_payload_bid/{slot}/{parent_hash}/{parent_root}/{proposer_pubkey}",
+      method: "POST",
+      req: {
+        writeReqJson: ({slot, parentHash, parentRoot, proposerPubkey, requestAuth, dateMilliseconds, timeoutMs}) => ({
+          params: {
+            slot,
+            parent_hash: toRootHex(parentHash),
+            parent_root: toRootHex(parentRoot),
+            proposer_pubkey: toPubkeyHex(proposerPubkey),
+          },
+          body: ssz.gloas.SignedBuilderRequestAuth.toJson(requestAuth),
+          headers: {
+            [MetaHeader.Version]: config.getForkName(slot),
+            [MetaHeader.DateMilliseconds]: dateMilliseconds.toString(),
+            [MetaHeader.TimeoutMs]: timeoutMs.toString(),
+          },
+        }),
+        parseReqJson: ({params, body, headers}) => {
+          toForkName(fromHeaders(headers, MetaHeader.Version));
+          return {
+            slot: params.slot,
+            parentHash: fromHex(params.parent_hash),
+            parentRoot: fromHex(params.parent_root),
+            proposerPubkey: fromHex(params.proposer_pubkey),
+            requestAuth: ssz.gloas.SignedBuilderRequestAuth.fromJson(body),
+            dateMilliseconds: parseRequiredUintHeader(
+              fromHeaders(headers, MetaHeader.DateMilliseconds),
+              MetaHeader.DateMilliseconds
+            ),
+            timeoutMs: parseRequiredUintHeader(fromHeaders(headers, MetaHeader.TimeoutMs), MetaHeader.TimeoutMs),
+          };
+        },
+        writeReqSsz: ({slot, parentHash, parentRoot, proposerPubkey, requestAuth, dateMilliseconds, timeoutMs}) => ({
+          params: {
+            slot,
+            parent_hash: toRootHex(parentHash),
+            parent_root: toRootHex(parentRoot),
+            proposer_pubkey: toPubkeyHex(proposerPubkey),
+          },
+          body: ssz.gloas.SignedBuilderRequestAuth.serialize(requestAuth),
+          headers: {
+            [MetaHeader.Version]: config.getForkName(slot),
+            [MetaHeader.DateMilliseconds]: dateMilliseconds.toString(),
+            [MetaHeader.TimeoutMs]: timeoutMs.toString(),
+          },
+        }),
+        parseReqSsz: ({params, body, headers}) => {
+          toForkName(fromHeaders(headers, MetaHeader.Version));
+          return {
+            slot: params.slot,
+            parentHash: fromHex(params.parent_hash),
+            parentRoot: fromHex(params.parent_root),
+            proposerPubkey: fromHex(params.proposer_pubkey),
+            requestAuth: ssz.gloas.SignedBuilderRequestAuth.deserialize(body),
+            dateMilliseconds: parseRequiredUintHeader(
+              fromHeaders(headers, MetaHeader.DateMilliseconds),
+              MetaHeader.DateMilliseconds
+            ),
+            timeoutMs: parseRequiredUintHeader(fromHeaders(headers, MetaHeader.TimeoutMs), MetaHeader.TimeoutMs),
+          };
+        },
+        schema: {
+          params: {
+            slot: Schema.UintRequired,
+            parent_hash: Schema.StringRequired,
+            parent_root: Schema.StringRequired,
+            proposer_pubkey: Schema.StringRequired,
+          },
+          body: Schema.Object,
+          headers: {
+            [MetaHeader.Version]: Schema.String,
+            [MetaHeader.DateMilliseconds]: Schema.String,
+            [MetaHeader.TimeoutMs]: Schema.String,
+          },
+        },
+      },
+      resp: {
+        data: WithVersion<MaybeSignedExecutionPayloadBid, VersionMeta>(
+          (fork: ForkName) => getPostGloasForkTypes(fork).SignedExecutionPayloadBid
+        ),
+        meta: VersionCodec,
+      },
+      init: {
+        requestWireFormat: WireFormat.ssz,
+      },
+    },
+    submitSignedBeaconBlock: {
+      url: "/eth/v1/builder/beacon_blocks",
+      method: "POST",
+      req: {
+        writeReqJson: ({signedBlock}) => {
+          const fork = config.getForkName(signedBlock.data.message.slot);
+          return {
+            body: getPostGloasForkTypes(fork).SignedBeaconBlock.toJson(signedBlock.data),
+            headers: {
+              [MetaHeader.Version]: fork,
+            },
+          };
+        },
+        parseReqJson: ({body, headers}) => {
+          const fork = toForkName(fromHeaders(headers, MetaHeader.Version));
+          return {
+            signedBlock: {data: getPostGloasForkTypes(fork).SignedBeaconBlock.fromJson(body)},
+          };
+        },
+        writeReqSsz: ({signedBlock}) => {
+          const fork = config.getForkName(signedBlock.data.message.slot);
+          return {
+            body: signedBlock.bytes ?? getPostGloasForkTypes(fork).SignedBeaconBlock.serialize(signedBlock.data),
+            headers: {
+              [MetaHeader.Version]: fork,
+            },
+          };
+        },
+        parseReqSsz: ({body, headers}) => {
+          const fork = toForkName(fromHeaders(headers, MetaHeader.Version));
+          return {
+            signedBlock: {data: getPostGloasForkTypes(fork).SignedBeaconBlock.deserialize(body)},
+          };
+        },
+        schema: {
+          body: Schema.Object,
+          headers: {[MetaHeader.Version]: Schema.String},
+        },
+      },
+      resp: EmptyResponseCodec,
+      init: {
+        requestWireFormat: WireFormat.ssz,
+      },
+    },
+    submitBuilderPreferences: {
+      url: "/eth/v1/builder/builder_preferences/{proposer_pubkey}",
+      method: "POST",
+      req: {
+        writeReqJson: ({proposerPubkey, request}) => ({
+          params: {proposer_pubkey: toPubkeyHex(proposerPubkey)},
+          body: ssz.gloas.BuilderPreferencesRequest.toJson(request),
+          headers: {[MetaHeader.Version]: config.getForkName(request.auth.message.slot)},
+        }),
+        parseReqJson: ({params, body, headers}) => {
+          toForkName(fromHeaders(headers, MetaHeader.Version));
+          return {
+            proposerPubkey: fromHex(params.proposer_pubkey),
+            request: ssz.gloas.BuilderPreferencesRequest.fromJson(body),
+          };
+        },
+        writeReqSsz: ({proposerPubkey, request}) => ({
+          params: {proposer_pubkey: toPubkeyHex(proposerPubkey)},
+          body: ssz.gloas.BuilderPreferencesRequest.serialize(request),
+          headers: {[MetaHeader.Version]: config.getForkName(request.auth.message.slot)},
+        }),
+        parseReqSsz: ({params, body, headers}) => {
+          toForkName(fromHeaders(headers, MetaHeader.Version));
+          return {
+            proposerPubkey: fromHex(params.proposer_pubkey),
+            request: ssz.gloas.BuilderPreferencesRequest.deserialize(body),
+          };
+        },
+        schema: {
+          params: {proposer_pubkey: Schema.StringRequired},
+          body: Schema.Object,
+          headers: {[MetaHeader.Version]: Schema.String},
+        },
+      },
+      resp: EmptyResponseCodec,
+      init: {
+        requestWireFormat: WireFormat.ssz,
+      },
+    },
   };
 }
+
+function parseRequiredUintHeader(value: string, header: MetaHeader): number {
+  if (!/^\d+$/.test(value)) {
+    throw Error(`${header} must be a non-negative integer`);
+  }
+  const parsed = Number(value);
+  if (!Number.isSafeInteger(parsed)) {
+    throw Error(`${header} must be a safe integer`);
+  }
+  return parsed;
+}

package/src/keymanager/index.ts

@@ -7,6 +7,8 @@ import * as keymanager from "./client.js";
 
 export type {
   BuilderBoostFactorData,
+  BuilderConfigData,
+  BuilderEntryConfig,
   Endpoints,
   FeeRecipientData,
   GasLimitData,
@@ -19,7 +21,13 @@ export type {
   SignerDefinition,
   SlashingProtectionData,
 } from "./routes.js";
-export {DeleteRemoteKeyStatus, DeletionStatus, ImportRemoteKeyStatus, ImportStatus} from "./routes.js";
+export {
+  DeleteRemoteKeyStatus,
+  DeletionStatus,
+  ImportRemoteKeyStatus,
+  ImportStatus,
+  builderConfigDataFromJson,
+} from "./routes.js";
 
 export type {ApiClient};