@lodestar/beacon-node 1.47.0-dev.d2f4b96574 → 1.47.0-dev.d79d81f994

package/src/chain/validation/executionPayloadBid.ts

@@ -1,5 +1,4 @@
-import {PublicKey} from "@chainsafe/blst";
-import {IForkChoice, ProtoBlock} from "@lodestar/fork-choice";
+import {ProtoBlock} from "@lodestar/fork-choice";
 import {PAYLOAD_BUILDER_VERSION} from "@lodestar/params";
 import {
   computeEpochAtSlot,
@@ -47,11 +46,12 @@ function getMinBidValue(currentHighestBid: number): number {
 /**
  * Check whether a bid builds on one of the paths compatible with the local head branch.
  *
- * Building directly on the parent is allowed for proposer-boost reorgs outside epoch boundaries.
+ * Building directly on the parent is allowed for proposer-boost reorgs, including at epoch
+ * boundaries when the head is weak enough that a reorg onto the strong parent is predicted.
  * Otherwise the bid must build on the local head's full or empty payload variant, as selected for its slot.
  */
 function isBidCompatibleWithHead(
-  forkChoice: IForkChoice,
+  chain: IBeaconChain,
   head: ProtoBlock,
   bidSlot: Slot,
   bidParentBlockRoot: RootHex,
@@ -61,9 +61,13 @@ function isBidCompatibleWithHead(
   const buildsOnParentPayload = bidParentBlockHash === head.parentBlockHash;
 
   if (buildsOnParentBlock && buildsOnParentPayload) {
-    // The spec allows this at epoch boundaries, but Lodestar does not propagate these bids because validating
-    // them requires an epoch transition for a parent state that cannot be used for proposer-boost reorgs.
-    return !isStartSlotOfEpoch(bidSlot);
+    if (!isStartSlotOfEpoch(bidSlot)) {
+      return true;
+    }
+    // Epoch-boundary reorgs are allowed, but only propagate the bid if its parent matches the block
+    // we predict a proposer would reorg onto — predictProposerHead returns the strong parent only
+    // when the head is weak.
+    return chain.predictProposerHead().blockRoot === bidParentBlockRoot;
   }
 
   if (bidParentBlockRoot !== head.blockRoot) {
@@ -72,18 +76,168 @@ function isBidCompatibleWithHead(
 
   const buildsOnHeadPayload = bidParentBlockHash === head.executionPayloadBlockHash;
 
-  if (forkChoice.shouldBuildOnFull(head, bidSlot)) {
+  if (chain.forkChoice.shouldBuildOnFull(head, bidSlot)) {
     return buildsOnHeadPayload;
   }
 
   return buildsOnParentPayload;
 }
 
+/**
+ * Validation for bids submitted via the API by the operator's own builder.
+ *
+ * Only non-transient checks are applied: slot later than parent, zero execution payment, blob
+ * commitment count, builder eligibility, version and balance coverage, prev_randao, and signature.
+ * Transient gossip rules (head compatibility, first bid per tuple, value increment, proposer
+ * preferences) are not applied, since those only limit forwarding of peers' messages and the
+ * builder may legitimately bid on a branch this node does not consider head.
+ *
+ * Throws on any failed check. Also throws if the bid's parent block is unknown or its state is
+ * unavailable, since the checks cannot be evaluated against the parent branch.
+ */
 export async function validateApiExecutionPayloadBid(
   chain: IBeaconChain,
   signedExecutionPayloadBid: gloas.SignedExecutionPayloadBid
-): Promise<{proposerIndex: ValidatorIndex}> {
-  return validateExecutionPayloadBid(chain, signedExecutionPayloadBid);
+): Promise<void> {
+  const bid = signedExecutionPayloadBid.message;
+  const bidParentBlockRoot = toRootHex(bid.parentBlockRoot);
+
+  // [IGNORE] `bid.slot` is the current slot, or the next slot (`bid.slot - 1` is current), allowing for `MAXIMUM_GOSSIP_CLOCK_DISPARITY`.
+  if (
+    !chain.clock.isCurrentSlotGivenGossipDisparity(bid.slot) &&
+    !chain.clock.isCurrentSlotGivenGossipDisparity(bid.slot - 1)
+  ) {
+    throw new ExecutionPayloadBidError(GossipAction.IGNORE, {
+      code: ExecutionPayloadBidErrorCode.INVALID_SLOT,
+      builderIndex: bid.builderIndex,
+      slot: bid.slot,
+    });
+  }
+
+  // [IGNORE] `bid.parent_block_root` is the hash tree root of a known beacon block in fork choice.
+  // Moved earlier than the spec ordering so we can derive the proposer dependent root for the
+  // proposer-preferences lookup below from a known fork-choice block.
+  const parentBlock = chain.forkChoice.getBlockHexDefaultStatus(bidParentBlockRoot);
+  if (parentBlock === null) {
+    throw new ExecutionPayloadBidError(GossipAction.IGNORE, {
+      code: ExecutionPayloadBidErrorCode.UNKNOWN_BLOCK_ROOT,
+      parentBlockRoot: bidParentBlockRoot,
+    });
+  }
+
+  // [REJECT] The bid is for a higher slot than its parent block -- i.e.
+  // validate that `bid.slot` is greater than the slot of the block with root
+  // `bid.parent_block_root`.
+  if (bid.slot <= parentBlock.slot) {
+    throw new ExecutionPayloadBidError(GossipAction.REJECT, {
+      code: ExecutionPayloadBidErrorCode.NOT_LATER_THAN_PARENT,
+      parentSlot: parentBlock.slot,
+      slot: bid.slot,
+    });
+  }
+
+  // [REJECT] `bid.execution_payment` is zero.
+  if (bid.executionPayment !== 0n) {
+    throw new ExecutionPayloadBidError(GossipAction.REJECT, {
+      code: ExecutionPayloadBidErrorCode.NON_ZERO_EXECUTION_PAYMENT,
+      builderIndex: bid.builderIndex,
+      executionPayment: bid.executionPayment,
+    });
+  }
+
+  // [REJECT] The length of KZG commitments is less than or equal to the limitation defined in the
+  // consensus layer -- i.e. validate that
+  // `len(bid.blob_kzg_commitments) <= get_blob_parameters(compute_epoch_at_slot(bid.slot)).max_blobs_per_block`.
+  const blobKzgCommitmentsLen = bid.blobKzgCommitments.length;
+  const maxBlobsPerBlock = chain.config.getMaxBlobsPerBlock(computeEpochAtSlot(bid.slot));
+  if (blobKzgCommitmentsLen > maxBlobsPerBlock) {
+    throw new ExecutionPayloadBidError(GossipAction.REJECT, {
+      code: ExecutionPayloadBidErrorCode.TOO_MANY_KZG_COMMITMENTS,
+      blobKzgCommitmentsLen,
+      commitmentLimit: maxBlobsPerBlock,
+    });
+  }
+
+  const state = await chain.regen
+    .getBlockSlotState(parentBlock, bid.slot, {dontTransferCache: true}, RegenCaller.validateApiExecutionPayloadBid)
+    .catch(() => {
+      throw new ExecutionPayloadBidError(GossipAction.IGNORE, {
+        code: ExecutionPayloadBidErrorCode.UNKNOWN_BLOCK_ROOT,
+        parentBlockRoot: bidParentBlockRoot,
+      });
+    });
+
+  if (!isStatePostGloas(state)) {
+    throw new Error(`Expected gloas+ state for execution payload bid validation, got fork=${state.forkName}`);
+  }
+
+  // [REJECT] `bid.builder_index` is within bounds -- i.e. `bid.builder_index < len(state.builders)`.
+  // `state.getBuilder` returns a lazy SSZ `getReadonly` view that is not bounds-checked eagerly; an
+  // out-of-range index only throws (`LeafNode has no right node`) on deferred field access (e.g. inside
+  // `isActiveBuilder`), escaping a try/catch around `getBuilder`. Check the length explicitly instead.
+  if (bid.builderIndex >= state.getBuildersLength()) {
+    throw new ExecutionPayloadBidError(GossipAction.REJECT, {
+      code: ExecutionPayloadBidErrorCode.BUILDER_NOT_ELIGIBLE,
+      builderIndex: bid.builderIndex,
+    });
+  }
+
+  // [REJECT] `bid.builder_index` is a valid/active builder index -- i.e.
+  // `is_active_builder(state, bid.builder_index)` returns `True`.
+  const builder = state.getBuilder(bid.builderIndex);
+  if (!isActiveBuilder(builder, state.finalizedCheckpoint.epoch)) {
+    throw new ExecutionPayloadBidError(GossipAction.REJECT, {
+      code: ExecutionPayloadBidErrorCode.BUILDER_NOT_ELIGIBLE,
+      builderIndex: bid.builderIndex,
+    });
+  }
+
+  // [REJECT] The builder version is `PAYLOAD_BUILDER_VERSION` -- i.e.
+  // `state.builders[bid.builder_index].version == PAYLOAD_BUILDER_VERSION`.
+  if (builder.version !== PAYLOAD_BUILDER_VERSION) {
+    throw new ExecutionPayloadBidError(GossipAction.REJECT, {
+      code: ExecutionPayloadBidErrorCode.INVALID_BUILDER_VERSION,
+      builderIndex: bid.builderIndex,
+      version: builder.version,
+      expectedVersion: PAYLOAD_BUILDER_VERSION,
+    });
+  }
+
+  // [IGNORE] `bid.value` is less or equal than the builder's excess balance --
+  // i.e. `can_builder_cover_bid(state, builder_index, amount)` returns `True`.
+  if (!state.canBuilderCoverBid(bid.builderIndex, bid.value)) {
+    throw new ExecutionPayloadBidError(GossipAction.IGNORE, {
+      code: ExecutionPayloadBidErrorCode.BID_TOO_HIGH,
+      bidValue: bid.value,
+      builderBalance: builder.balance,
+    });
+  }
+
+  // [REJECT] `bid.prev_randao` is the correct RANDAO mix -- i.e. validate that
+  // `bid.prev_randao == get_randao_mix(parent_state, get_current_epoch(parent_state))`.
+  const randaoMix = state.getRandaoMix(computeEpochAtSlot(state.slot));
+  if (!byteArrayEquals(bid.prevRandao, randaoMix)) {
+    throw new ExecutionPayloadBidError(GossipAction.REJECT, {
+      code: ExecutionPayloadBidErrorCode.INVALID_PREV_RANDAO,
+      builderIndex: bid.builderIndex,
+      bidPrevRandao: toHex(bid.prevRandao),
+      expectedPrevRandao: toHex(randaoMix),
+    });
+  }
+
+  // [REJECT] `signed_execution_payload_bid.signature` is valid with respect to the `bid.builder_index`.
+  const signatureSet = createSingleSignatureSetFromComponents(
+    builder.pubkey,
+    getExecutionPayloadBidSigningRoot(chain.config, bid),
+    signedExecutionPayloadBid.signature
+  );
+  if (!(await chain.bls.verifySignatureSets([signatureSet]))) {
+    throw new ExecutionPayloadBidError(GossipAction.REJECT, {
+      code: ExecutionPayloadBidErrorCode.INVALID_SIGNATURE,
+      builderIndex: bid.builderIndex,
+      slot: bid.slot,
+    });
+  }
 }
 
 export async function validateGossipExecutionPayloadBid(
@@ -115,7 +269,7 @@ async function validateExecutionPayloadBid(
 
   // [IGNORE] The bid is compatible with the current head branch.
   const head = chain.forkChoice.getHead();
-  if (!isBidCompatibleWithHead(chain.forkChoice, head, bid.slot, bidParentBlockRoot, bidParentBlockHash)) {
+  if (!isBidCompatibleWithHead(chain, head, bid.slot, bidParentBlockRoot, bidParentBlockHash)) {
     throw new ExecutionPayloadBidError(GossipAction.IGNORE, {
       code: ExecutionPayloadBidErrorCode.INCOMPATIBLE_WITH_HEAD,
       slot: bid.slot,
@@ -314,11 +468,11 @@ async function validateExecutionPayloadBid(
   // increment, see https://github.com/ethereum/consensus-specs/pull/4831. This prevents spam
   // from builders submitting numerous bids with minimal value increments.
   const bestBid = chain.executionPayloadBidPool.getBestBid(bid.slot, bidParentBlockHash, bidParentBlockRoot);
-  if (bestBid !== null && bid.value < getMinBidValue(bestBid.message.value)) {
+  if (bestBid !== null && bid.value < getMinBidValue(bestBid.signedBid.message.value)) {
     throw new ExecutionPayloadBidError(GossipAction.IGNORE, {
       code: ExecutionPayloadBidErrorCode.BID_TOO_LOW,
       bidValue: bid.value,
-      currentHighestBid: bestBid.message.value,
+      currentHighestBid: bestBid.signedBid.message.value,
     });
   }
   // [IGNORE] `bid.value` is less or equal than the builder's excess balance --
@@ -345,7 +499,7 @@ async function validateExecutionPayloadBid(
 
   // [REJECT] `signed_execution_payload_bid.signature` is valid with respect to the `bid.builder_index`.
   const signatureSet = createSingleSignatureSetFromComponents(
-    PublicKey.fromBytes(builder.pubkey),
+    builder.pubkey,
     getExecutionPayloadBidSigningRoot(chain.config, bid),
     signedExecutionPayloadBid.signature
   );

package/src/chain/validation/executionPayloadEnvelope.ts

@@ -170,7 +170,6 @@ async function validateExecutionPayloadEnvelope(
   // by `verify_execution_payload_envelope_signature`.
   const signatureSet = getExecutionPayloadEnvelopeSignatureSet(
     chain.config,
-    chain.pubkeyCache,
     blockState,
     executionPayloadEnvelope,
     payloadInput.proposerIndex

package/src/chain/validation/payloadAttestationMessage.ts

@@ -1,6 +1,5 @@
 import {
-  computeEpochAtSlot,
-  createSingleSignatureSetFromComponents,
+  createIndexedSignatureSetFromComponents,
   getPayloadAttestationDataSigningRoot,
   isStatePostGloas,
 } from "@lodestar/state-transition";
@@ -36,7 +35,6 @@ async function validatePayloadAttestationMessage(
   prioritizeBls = false
 ): Promise<PayloadAttestationValidationResult> {
   const {data, validatorIndex} = payloadAttestationMessage;
-  const epoch = computeEpochAtSlot(data.slot);
 
   // [IGNORE] The message's slot is for the current slot (with a `MAXIMUM_GOSSIP_CLOCK_DISPARITY` allowance), i.e. `data.slot == current_slot`.
   if (!chain.clock.isCurrentSlotGivenGossipDisparity(data.slot)) {
@@ -48,9 +46,8 @@ async function validatePayloadAttestationMessage(
   }
 
   // [IGNORE] The `payload_attestation_message` is the first valid message received
-  // from the validator with index `payload_attestation_message.validator_index`.
-  // A single validator can participate PTC at most once per epoch
-  if (chain.seenPayloadAttesters.isKnown(epoch, validatorIndex)) {
+  // for the slot from the validator with index `payload_attestation_message.validator_index`.
+  if (chain.seenPayloadAttesters.isKnown(data.slot, validatorIndex)) {
     throw new PayloadAttestationError(GossipAction.IGNORE, {
       code: PayloadAttestationErrorCode.PAYLOAD_ATTESTATION_ALREADY_KNOWN,
       validatorIndex,
@@ -114,16 +111,8 @@ async function validatePayloadAttestationMessage(
   }
 
   // [REJECT] `payload_attestation_message.signature` is valid with respect to the validator's public key.
-  const validatorPubkey = chain.pubkeyCache.get(validatorIndex);
-  if (!validatorPubkey) {
-    throw new PayloadAttestationError(GossipAction.REJECT, {
-      code: PayloadAttestationErrorCode.INVALID_ATTESTER,
-      attesterIndex: validatorIndex,
-    });
-  }
-
-  const signatureSet = createSingleSignatureSetFromComponents(
-    validatorPubkey,
+  const signatureSet = createIndexedSignatureSetFromComponents(
+    validatorIndex,
     getPayloadAttestationDataSigningRoot(chain.config, data),
     payloadAttestationMessage.signature
   );
@@ -135,7 +124,7 @@ async function validatePayloadAttestationMessage(
   }
 
   // Valid
-  chain.seenPayloadAttesters.add(epoch, validatorIndex);
+  chain.seenPayloadAttesters.add(data.slot, validatorIndex);
 
   return {
     attDataRootHex: toRootHex(ssz.gloas.PayloadAttestationData.hashTreeRoot(data)),

package/src/chain/validation/proposerPreferences.ts

@@ -1,9 +1,9 @@
 import {IForkChoice, ProtoBlock} from "@lodestar/fork-choice";
-import {GENESIS_EPOCH, GENESIS_SLOT, MIN_SEED_LOOKAHEAD, SLOTS_PER_EPOCH} from "@lodestar/params";
+import {GENESIS_EPOCH, GENESIS_SLOT, MIN_SEED_LOOKAHEAD, SLOTS_PER_EPOCH, isForkPostGloas} from "@lodestar/params";
 import {
   computeEpochAtSlot,
   computeStartSlotAtEpoch,
-  createSingleSignatureSetFromComponents,
+  createIndexedSignatureSetFromComponents,
   getProposerPreferencesSigningRoot,
 } from "@lodestar/state-transition";
 import {Epoch, Slot, ValidatorIndex, gloas} from "@lodestar/types";
@@ -13,7 +13,7 @@ import {IBeaconChain} from "../index.js";
 
 /**
  * Validates a gossiped `SignedProposerPreferences` per
- * https://github.com/ethereum/consensus-specs/blob/v1.7.0-alpha.13/specs/gloas/p2p-interface.md#new-proposer_preferences
+ * https://github.com/ethereum/consensus-specs/blob/v1.7.0-alpha.14/specs/gloas/p2p-interface.md#new-proposer_preferences
  */
 export async function validateGossipProposerPreferences(
   chain: IBeaconChain,
@@ -24,6 +24,16 @@ export async function validateGossipProposerPreferences(
   const dependentRootHex = toRootHex(dependentRoot);
   const proposalEpoch = computeEpochAtSlot(proposalSlot);
 
+  // [IGNORE] The proposal epoch is after the Gloas upgrade
+  const proposalFork = chain.config.getForkName(proposalSlot);
+  if (!isForkPostGloas(proposalFork)) {
+    throw new ProposerPreferencesError(GossipAction.IGNORE, {
+      code: ProposerPreferencesErrorCode.PRE_GLOAS_PROPOSAL_SLOT,
+      proposalSlot,
+      proposalFork,
+    });
+  }
+
   // [IGNORE] `preferences.proposal_slot` is within the proposer lookahead,
   // allowing for `MAXIMUM_GOSSIP_CLOCK_DISPARITY`.
   const currentEpoch = computeEpochAtSlot(chain.clock.currentSlotWithGossipDisparity);
@@ -129,8 +139,8 @@ export async function validateGossipProposerPreferences(
   }
 
   // [REJECT] `signed_proposer_preferences.signature` is valid with respect to the validator's public key.
-  const signatureSet = createSingleSignatureSetFromComponents(
-    chain.pubkeyCache.getOrThrow(validatorIndex),
+  const signatureSet = createIndexedSignatureSetFromComponents(
+    validatorIndex,
     getProposerPreferencesSigningRoot(chain.config, preferences),
     signedProposerPreferences.signature
   );

package/src/chain/validation/proposerSlashing.ts

@@ -37,7 +37,7 @@ async function validateProposerSlashing(
   try {
     const proposer = state.getValidator(proposerSlashing.signedHeader1.message.proposerIndex);
     // verifySignature = false, verified in batch below
-    assertValidProposerSlashing(chain.config, chain.pubkeyCache, state.slot, proposerSlashing, proposer, false);
+    assertValidProposerSlashing(chain.config, state.slot, proposerSlashing, proposer, false);
   } catch (e) {
     throw new ProposerSlashingError(GossipAction.REJECT, {
       code: ProposerSlashingErrorCode.INVALID,

package/src/chain/validation/voluntaryExit.ts

@@ -9,12 +9,69 @@ import {
 import {IBeaconChain} from "../index.js";
 import {RegenCaller} from "../regen/index.js";
 
+export type ApiVoluntaryExitResult = {status: "published"} | {status: "deferred"; validity: VoluntaryExitValidity};
+
+// Variants that can become valid in a future epoch without user action.
+// - earlyEpoch: exit.message.epoch is in the future; valid once current epoch catches up
+// - shortTimeActive: validator active < SHARD_COMMITTEE_PERIOD; valid once enough time passes
+// - pendingWithdrawals: Electra; valid once pending partial withdrawals drain
+// Note: VoluntaryExitValidity.inactive is intentionally excluded. It conflates
+// "validator does not exist" (permanent) with "validator not yet activated"
+// (transient), and cleanly classifying it requires splitting the enum variant
+// upstream. Left for a future follow-up.
+
+export function isTransientExitValidity(v: VoluntaryExitValidity): boolean {
+  switch (v) {
+    case VoluntaryExitValidity.earlyEpoch:
+    case VoluntaryExitValidity.shortTimeActive:
+    case VoluntaryExitValidity.pendingWithdrawals:
+      return true;
+    case VoluntaryExitValidity.valid:
+    case VoluntaryExitValidity.inactive:
+    case VoluntaryExitValidity.alreadyExited:
+    case VoluntaryExitValidity.invalidSignature:
+      return false;
+  }
+}
+
+// Comments for each call are present inside `validateVoluntaryExit`.
 export async function validateApiVoluntaryExit(
   chain: IBeaconChain,
   voluntaryExit: phase0.SignedVoluntaryExit
-): Promise<void> {
+): Promise<ApiVoluntaryExitResult> {
   const prioritizeBls = true;
-  return validateVoluntaryExit(chain, voluntaryExit, prioritizeBls);
+
+  if (
+    chain.opPool.hasSeenVoluntaryExit(voluntaryExit.message.validatorIndex) ||
+    chain.deferredVoluntaryExitPool.has(voluntaryExit.message.validatorIndex)
+  ) {
+    throw new VoluntaryExitError(GossipAction.IGNORE, {
+      code: VoluntaryExitErrorCode.ALREADY_EXISTS,
+    });
+  }
+
+  const state = await chain.getHeadStateAtCurrentEpoch(RegenCaller.validateApiVoluntaryExit);
+  const validity = state.getVoluntaryExitValidity(voluntaryExit, false);
+
+  if (validity !== VoluntaryExitValidity.valid && !isTransientExitValidity(validity)) {
+    throw new VoluntaryExitError(GossipAction.REJECT, {
+      code: voluntaryExitValidityToErrorCode(validity),
+    });
+  }
+
+  const signatureSet = getVoluntaryExitSignatureSet(chain.config, state, voluntaryExit);
+  if (!(await chain.bls.verifySignatureSets([signatureSet], {batchable: true, priority: prioritizeBls}))) {
+    throw new VoluntaryExitError(GossipAction.REJECT, {
+      code: VoluntaryExitErrorCode.INVALID_SIGNATURE,
+    });
+  }
+
+  if (validity !== VoluntaryExitValidity.valid) {
+    // Transient failure — signature is good, defer
+    return {status: "deferred", validity};
+  }
+
+  return {status: "published"};
 }
 
 export async function validateGossipVoluntaryExit(

package/src/execution/builder/apiClient.ts

@@ -0,0 +1,244 @@
+import {routes} from "@lodestar/api";
+import {ApiClient as BuilderApi, getClient} from "@lodestar/api/builder";
+import {ChainForkConfig} from "@lodestar/config";
+import {Logger} from "@lodestar/logger";
+import {DOMAIN_BUILDER_REQUEST_AUTH, ForkPostGloas} from "@lodestar/params";
+import {
+  ZERO_HASH,
+  computeDomain,
+  computeSigningRoot,
+  createSingleSignatureSetFromComponents,
+} from "@lodestar/state-transition";
+import {BLSPubkey, Root, SignedBeaconBlock, Slot, WithOptionalBytes, gloas, ssz} from "@lodestar/types";
+import {isValidAsciiHttpUrl, toHex, toPrintableUrl} from "@lodestar/utils";
+import type {IBlsVerifier} from "../../chain/bls/index.js";
+import {Metrics} from "../../metrics/metrics.js";
+import {IClock} from "../../util/clock.js";
+
+/**
+ * Additional duration to account for potential event loop lag which causes
+ * builder bids to be rejected even though the response was sent in time.
+ */
+const EVENT_LOOP_LAG_BUFFER = 250;
+
+/**
+ * Duration given to a builder to provide a `SignedExecutionPayloadBid` before the deadline
+ * is reached, advertised on each bid request via the `X-Timeout-Ms` header. The p2p bid is
+ * selected after the same duration, only considering bids received up to that point.
+ */
+export const BUILDER_BID_DEADLINE_MS = 500;
+
+/** Local timeout for bid requests, event loop lag must not discard bids that arrived in time */
+export const BUILDER_BID_REQUEST_TIMEOUT_MS = BUILDER_BID_DEADLINE_MS + EVENT_LOOP_LAG_BUFFER;
+
+export type BuilderApiClientOpts = {
+  /** Timeout for builder api requests, bid requests always use `BUILDER_BID_REQUEST_TIMEOUT_MS` */
+  timeout?: number;
+  // Add User-Agent header to all requests
+  userAgent?: string;
+};
+
+type BuilderUrl = string;
+
+/** Decode the SSZ URL bytes without allowing replacement characters or unsafe header values. */
+export function decodeBuilderUrl(value: Uint8Array): BuilderUrl {
+  let url: string;
+  try {
+    url = new TextDecoder("utf8", {fatal: true}).decode(value);
+  } catch {
+    throw Error("Builder url must be valid UTF-8");
+  }
+  if (!isValidAsciiHttpUrl(url)) {
+    throw Error("Invalid builder url");
+  }
+  return url;
+}
+
+export type BuilderApiBid = {
+  url: BuilderUrl;
+  entry: routes.validator.BuilderEntry;
+  signedBid: gloas.SignedExecutionPayloadBid;
+  /** Time in milliseconds from the slot start when the bid was received */
+  receivedMs: number;
+};
+
+/**
+ * External builder integration post-gloas
+ *
+ * The builder set is driven by the resolved `BuilderConfig` the validator client supplies on
+ * each block production request, clients are dialed on demand based on the entry `url`.
+ */
+export class BuilderApiClient {
+  private readonly clients = new Map<BuilderUrl, BuilderApi>();
+
+  constructor(
+    private readonly opts: BuilderApiClientOpts,
+    private readonly config: ChainForkConfig,
+    private readonly clock: IClock,
+    private readonly bls: IBlsVerifier,
+    private readonly metrics: Metrics | null = null,
+    private readonly logger?: Logger
+  ) {}
+
+  /**
+   * Fan out bid requests to the builders named by the entries, one request per unique
+   * `(url, auth.message.data)` pair. Errors and empty responses (204) are logged and filtered
+   * out so a single unresponsive builder never fails block production.
+   */
+  async getExecutionPayloadBids(
+    entries: routes.validator.BuilderEntry[],
+    slot: Slot,
+    parentHash: Root,
+    parentRoot: Root,
+    proposerPubkey: BLSPubkey
+  ): Promise<BuilderApiBid[]> {
+    const seenRequests = new Set<string>();
+    const requests: {url: BuilderUrl; entry: routes.validator.BuilderEntry}[] = [];
+
+    for (const entry of entries) {
+      const urlForLog = Buffer.from(entry.url).toString("utf8");
+      let url: BuilderUrl;
+      try {
+        url = decodeBuilderUrl(entry.url);
+      } catch {
+        this.logger?.warn("Ignoring builder entry with invalid url", {slot, url: urlForLog});
+        continue;
+      }
+
+      const requestKey = `${url}-${toHex(entry.auth.message.data)}`;
+      if (seenRequests.has(requestKey)) {
+        continue;
+      }
+      seenRequests.add(requestKey);
+
+      // The builder rejects a mismatch, an entry naming a different slot is not used for a bid request
+      if (entry.auth.message.slot !== slot) {
+        this.logger?.warn("Ignoring builder entry with auth for different slot", {
+          slot,
+          authSlot: entry.auth.message.slot,
+          builder: toPrintableUrl(url),
+        });
+        continue;
+      }
+
+      requests.push({url, entry});
+    }
+
+    // Collected in arrival order so an earlier received bid wins ties during candidate ranking
+    const bids: BuilderApiBid[] = [];
+    await Promise.all(
+      requests.map(async ({url, entry}) => {
+        this.metrics?.builderApi.bidRequests.inc();
+        try {
+          const client = await this.getOrCreateClient(url, proposerPubkey, entry.auth);
+          const res = await client.getExecutionPayloadBid(
+            {
+              slot,
+              parentHash,
+              parentRoot,
+              proposerPubkey,
+              requestAuth: entry.auth,
+              dateMilliseconds: Date.now(),
+              timeoutMs: BUILDER_BID_DEADLINE_MS,
+            },
+            {timeoutMs: BUILDER_BID_REQUEST_TIMEOUT_MS}
+          );
+          const signedBid = res.value();
+          if (signedBid === undefined) {
+            this.logger?.debug("No bid received from builder", {slot, builder: toPrintableUrl(url)});
+            return;
+          }
+          this.metrics?.builderApi.bidsReceived.inc();
+          bids.push({url, entry, signedBid, receivedMs: this.clock.msFromSlot(slot)});
+        } catch (e) {
+          this.metrics?.builderApi.bidRequestErrors.inc();
+          this.logger?.warn("Failed to get bid from builder", {slot, builder: toPrintableUrl(url)}, e as Error);
+        }
+      })
+    );
+
+    return bids;
+  }
+
+  /** Forward a proposer's builder preferences to the builder at the given url */
+  async submitBuilderPreferences(
+    url: BuilderUrl,
+    proposerPubkey: BLSPubkey,
+    request: gloas.BuilderPreferencesRequest
+  ): Promise<void> {
+    try {
+      const client = await this.getOrCreateClient(url, proposerPubkey, request.auth);
+      (await client.submitBuilderPreferences({proposerPubkey, request})).assertOk();
+      this.metrics?.builderApi.preferencesForwarded.inc({status: "success"});
+    } catch (e) {
+      this.metrics?.builderApi.preferencesForwarded.inc({status: "error"});
+      throw e;
+    }
+  }
+
+  /**
+   * Submit the signed beacon block to the builder whose bid was included. The builder is
+   * then responsible for constructing and broadcasting the corresponding
+   * `SignedExecutionPayloadEnvelope`, no further action is required by the proposer.
+   */
+  async submitSignedBeaconBlock(
+    url: BuilderUrl,
+    signedBlock: WithOptionalBytes<SignedBeaconBlock<ForkPostGloas>>
+  ): Promise<void> {
+    const client = this.clients.get(url);
+    if (client === undefined) {
+      this.metrics?.builderApi.blockSubmissions.inc({status: "error"});
+      this.logger?.warn("Ignoring signed block submission to unauthenticated builder", {url});
+      return;
+    }
+
+    try {
+      (await client.submitSignedBeaconBlock({signedBlock}, {redirect: "manual"})).assertOk();
+      this.metrics?.builderApi.blockSubmissions.inc({status: "success"});
+    } catch (e) {
+      this.metrics?.builderApi.blockSubmissions.inc({status: "error"});
+      throw e;
+    }
+  }
+
+  private async getOrCreateClient(
+    url: BuilderUrl,
+    proposerPubkey: BLSPubkey,
+    auth: gloas.SignedBuilderRequestAuth
+  ): Promise<BuilderApi> {
+    if (auth.message.data.length === 0) {
+      throw Error("Builder request auth data must not be empty");
+    }
+
+    let client = this.clients.get(url);
+    if (client === undefined) {
+      const domain = computeDomain(DOMAIN_BUILDER_REQUEST_AUTH, this.config.GENESIS_FORK_VERSION, ZERO_HASH);
+      const signingRoot = computeSigningRoot(ssz.gloas.BuilderRequestAuth, auth.message, domain);
+      const signatureSet = createSingleSignatureSetFromComponents(proposerPubkey, signingRoot, auth.signature);
+
+      let isValid = false;
+      try {
+        isValid = await this.bls.verifySignatureSets([signatureSet]);
+      } catch {
+        // Malformed signatures are invalid request authentication.
+      }
+      if (!isValid) {
+        throw Error("Invalid builder request auth");
+      }
+
+      client = getClient(
+        {
+          baseUrl: url,
+          globalInit: {
+            timeoutMs: this.opts.timeout,
+            headers: this.opts.userAgent ? {"User-Agent": this.opts.userAgent} : undefined,
+          },
+        },
+        {config: this.config, metrics: this.metrics?.builderHttpClient, logger: this.logger}
+      );
+      this.clients.set(url, client);
+      this.logger?.debug("External builder registered", {url: toPrintableUrl(url)});
+    }
+    return client;
+  }
+}