@lodestar/builder 1.50.0-dev.814fe8c461 → 1.50.0-dev.82f05c43ff

package/lib/services/payloadOrchestrator.d.ts

@@ -0,0 +1,42 @@
+import { LodestarError } from "@lodestar/utils";
+import { type BuildRequest, type BuiltPayload, type PayloadSource } from "./payloadSource.js";
+export type PayloadBuildJob = {
+    /** Jobs with the same ID share one build and its result. */
+    id: string;
+    request: BuildRequest;
+    /** Unix timestamp in milliseconds at which the prepared payload should be retrieved. */
+    getPayloadAt: number;
+};
+export type PayloadOrchestratorOptions = {
+    /** Maximum time in milliseconds to wait for payload retrieval. */
+    getPayloadTimeout: number;
+};
+export declare enum PayloadOrchestratorErrorCode {
+    PREPARE_DEADLINE_REACHED = "PAYLOAD_ORCHESTRATOR_ERROR_PREPARE_DEADLINE_REACHED",
+    PREPARE_TIMEOUT = "PAYLOAD_ORCHESTRATOR_ERROR_PREPARE_TIMEOUT",
+    GET_PAYLOAD_TIMEOUT = "PAYLOAD_ORCHESTRATOR_ERROR_GET_PAYLOAD_TIMEOUT"
+}
+export type PayloadOrchestratorErrorType = {
+    code: PayloadOrchestratorErrorCode.PREPARE_DEADLINE_REACHED;
+    jobId: string;
+    getPayloadAt: number;
+} | {
+    code: PayloadOrchestratorErrorCode.PREPARE_TIMEOUT | PayloadOrchestratorErrorCode.GET_PAYLOAD_TIMEOUT;
+    jobId: string;
+};
+export declare class PayloadOrchestratorError extends LodestarError<PayloadOrchestratorErrorType> {
+}
+/**
+ * Prepares a payload and retrieves it at the requested time. Preparation retries missing payload IDs until the
+ * retrieval time. Transport-level retries remain owned by the source.
+ */
+export declare class PayloadOrchestrator {
+    private readonly source;
+    private readonly options;
+    private readonly signal;
+    private readonly jobs;
+    constructor(source: PayloadSource, options: PayloadOrchestratorOptions, signal: AbortSignal);
+    run(job: PayloadBuildJob): Promise<BuiltPayload>;
+    private runJob;
+}
+//# sourceMappingURL=payloadOrchestrator.d.ts.map

package/lib/services/payloadOrchestrator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payloadOrchestrator.d.ts","sourceRoot":"","sources":["../../src/services/payloadOrchestrator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,aAAa,EAA0C,MAAM,iBAAiB,CAAC;AACvF,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,aAAa,EAGnB,MAAM,oBAAoB,CAAC;AAI5B,MAAM,MAAM,eAAe,GAAG;IAC5B,4DAA4D;IAC5D,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,YAAY,CAAC;IACtB,wFAAwF;IACxF,YAAY,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,0BAA0B,GAAG;IACvC,kEAAkE;IAClE,iBAAiB,EAAE,MAAM,CAAC;CAC3B,CAAC;AAEF,oBAAY,4BAA4B;IACtC,wBAAwB,wDAAwD;IAChF,eAAe,+CAA+C;IAC9D,mBAAmB,mDAAmD;CACvE;AAED,MAAM,MAAM,4BAA4B,GACpC;IACE,IAAI,EAAE,4BAA4B,CAAC,wBAAwB,CAAC;IAC5D,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;CACtB,GACD;IACE,IAAI,EAAE,4BAA4B,CAAC,eAAe,GAAG,4BAA4B,CAAC,mBAAmB,CAAC;IACtG,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEN,qBAAa,wBAAyB,SAAQ,aAAa,CAAC,4BAA4B,CAAC;CAAG;AAE5F;;;GAGG;AACH,qBAAa,mBAAmB;IAI5B,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM;IALzB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA4C;IAEjE,YACmB,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,0BAA0B,EACnC,MAAM,EAAE,WAAW,EAClC;IAEJ,GAAG,CAAC,GAAG,EAAE,eAAe,GAAG,OAAO,CAAC,YAAY,CAAC,CAQ/C;YAEa,MAAM;CAwCrB"}

package/lib/services/payloadOrchestrator.js

@@ -0,0 +1,60 @@
+import { LodestarError, TimeoutError, retry, sleep, withTimeout } from "@lodestar/utils";
+import { PayloadSourceError, PayloadSourceErrorCode, } from "./payloadSource.js";
+const PREPARE_RETRY_DELAY = 100;
+export var PayloadOrchestratorErrorCode;
+(function (PayloadOrchestratorErrorCode) {
+    PayloadOrchestratorErrorCode["PREPARE_DEADLINE_REACHED"] = "PAYLOAD_ORCHESTRATOR_ERROR_PREPARE_DEADLINE_REACHED";
+    PayloadOrchestratorErrorCode["PREPARE_TIMEOUT"] = "PAYLOAD_ORCHESTRATOR_ERROR_PREPARE_TIMEOUT";
+    PayloadOrchestratorErrorCode["GET_PAYLOAD_TIMEOUT"] = "PAYLOAD_ORCHESTRATOR_ERROR_GET_PAYLOAD_TIMEOUT";
+})(PayloadOrchestratorErrorCode || (PayloadOrchestratorErrorCode = {}));
+export class PayloadOrchestratorError extends LodestarError {
+}
+/**
+ * Prepares a payload and retrieves it at the requested time. Preparation retries missing payload IDs until the
+ * retrieval time. Transport-level retries remain owned by the source.
+ */
+export class PayloadOrchestrator {
+    source;
+    options;
+    signal;
+    jobs = new Map();
+    constructor(source, options, signal) {
+        this.source = source;
+        this.options = options;
+        this.signal = signal;
+    }
+    run(job) {
+        const { id } = job;
+        let promise = this.jobs.get(id);
+        if (promise === undefined) {
+            promise = this.runJob(job).finally(() => this.jobs.delete(id));
+            this.jobs.set(id, promise);
+        }
+        return promise;
+    }
+    async runJob({ id, request, getPayloadAt }) {
+        const prepareTimeout = getPayloadAt - Date.now();
+        if (!(prepareTimeout > 0)) {
+            throw new PayloadOrchestratorError({ code: PayloadOrchestratorErrorCode.PREPARE_DEADLINE_REACHED, jobId: id, getPayloadAt }, `Payload preparation deadline reached jobId=${id} getPayloadAt=${getPayloadAt}`);
+        }
+        const handle = await withTimeout((signal = this.signal) => retry(() => this.source.prepare(request, signal), {
+            retries: Infinity,
+            retryDelay: PREPARE_RETRY_DELAY,
+            shouldRetry: (error) => error instanceof PayloadSourceError && error.type.code === PayloadSourceErrorCode.NO_PAYLOAD_ID,
+            signal,
+        }), prepareTimeout, this.signal).catch((error) => {
+            if (error instanceof TimeoutError) {
+                throw new PayloadOrchestratorError({ code: PayloadOrchestratorErrorCode.PREPARE_TIMEOUT, jobId: id });
+            }
+            throw error;
+        });
+        await sleep(getPayloadAt - Date.now(), this.signal);
+        return withTimeout((signal = this.signal) => this.source.getPayload(handle, signal), this.options.getPayloadTimeout, this.signal).catch((error) => {
+            if (error instanceof TimeoutError) {
+                throw new PayloadOrchestratorError({ code: PayloadOrchestratorErrorCode.GET_PAYLOAD_TIMEOUT, jobId: id });
+            }
+            throw error;
+        });
+    }
+}
+//# sourceMappingURL=payloadOrchestrator.js.map

package/lib/services/payloadOrchestrator.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lodestar/builder",
-  "version": "1.50.0-dev.814fe8c461",
+  "version": "1.50.0-dev.82f05c43ff",
   "description": "A Typescript implementation of the builder client",
   "author": "ChainSafe Systems",
   "license": "Apache-2.0",
@@ -47,17 +47,17 @@
   ],
   "dependencies": {
     "@chainsafe/lodestar-z": "catalog:",
-    "@chainsafe/ssz": "^1.8.0",
-    "@lodestar/api": "^1.50.0-dev.814fe8c461",
-    "@lodestar/config": "^1.50.0-dev.814fe8c461",
-    "@lodestar/params": "^1.50.0-dev.814fe8c461",
-    "@lodestar/state-transition": "^1.50.0-dev.814fe8c461",
-    "@lodestar/types": "^1.50.0-dev.814fe8c461",
-    "@lodestar/utils": "^1.50.0-dev.814fe8c461"
+    "@chainsafe/ssz": "^1.8.1",
+    "@lodestar/api": "^1.50.0-dev.82f05c43ff",
+    "@lodestar/config": "^1.50.0-dev.82f05c43ff",
+    "@lodestar/params": "^1.50.0-dev.82f05c43ff",
+    "@lodestar/state-transition": "^1.50.0-dev.82f05c43ff",
+    "@lodestar/types": "^1.50.0-dev.82f05c43ff",
+    "@lodestar/utils": "^1.50.0-dev.82f05c43ff"
   },
   "devDependencies": {
-    "@lodestar/logger": "^1.50.0-dev.814fe8c461",
-    "@lodestar/test-utils": "^1.50.0-dev.814fe8c461"
+    "@lodestar/logger": "^1.50.0-dev.82f05c43ff",
+    "@lodestar/test-utils": "^1.50.0-dev.82f05c43ff"
   },
-  "gitHead": "f8cfef9ffe414aba7e36b26e5fcfdf7c1135e7e8"
+  "gitHead": "aa535ba9e1da82967b49356035d948d5b35fedae"
 }

package/src/builder.ts

@@ -147,6 +147,9 @@ export class Builder {
         onEvent: (event) => {
           void this.onEvent(event);
         },
+        onOpen: () => {
+          void this.fetchProposerPreferences(api);
+        },
         onError: (error) => {
           if (!signal.aborted) this.logger.error("Failed to receive builder event", {topics: topics.join(",")}, error);
         },
@@ -169,6 +172,31 @@ export class Builder {
       });
   }
 
+  /**
+   * Proposer preferences are only broadcast once per proposal slot, fetch the ones the beacon node
+   * already knows to cover those missed while not connected, e.g. after a restart
+   */
+  private async fetchProposerPreferences(api: ApiClient): Promise<void> {
+    const signal = this.controller.signal;
+
+    try {
+      const preferences = (await api.beacon.getProposerPreferences({}, {signal})).value();
+      for (const signedProposerPreferences of preferences) {
+        // Does not replace preferences already received from the event stream
+        this.proposerPreferencesTracker.onProposerPreferences(signedProposerPreferences);
+      }
+      this.logger.verbose("Fetched proposer preferences", {count: preferences.length});
+    } catch (error) {
+      if (!signal.aborted && !isErrorAborted(error)) {
+        this.logger.warn(
+          "Failed to fetch proposer preferences",
+          {},
+          error instanceof Error ? error : Error(String(error))
+        );
+      }
+    }
+  }
+
   private async onEvent(event: routes.events.BeaconEvent): Promise<void> {
     const signal = this.controller.signal;
     if (signal.aborted) return;

package/src/services/bidLedger.ts

@@ -128,6 +128,11 @@ export class BidLedger {
     return toRecord(record);
   }
 
+  hasWon(identity: BidIdentity, blockRoot: RootHex): boolean {
+    const record = this.getBid(identity.slot, identity.parentBlockHash, identity.parentBlockRoot);
+    return record !== null && record.blockHash === identity.blockHash && record.wonBlockRoots.has(blockRoot);
+  }
+
   /** Release a winning bid liability only after its payment is known to be reflected in Builder balance. */
   recordPaymentSettled(identity: BidIdentity): BidLedgerRecord | null {
     const record = this.getBid(identity.slot, identity.parentBlockHash, identity.parentBlockRoot);

package/src/services/bidSelector.ts

@@ -0,0 +1,138 @@
+import type {ChainForkConfig} from "@lodestar/config";
+import type {ForkPostGloas} from "@lodestar/params";
+import type {BuilderIndex, RootHex, SignedBeaconBlock, Slot} from "@lodestar/types";
+import {sszTypesFor} from "@lodestar/types";
+import {LodestarError, toRootHex} from "@lodestar/utils";
+import type {BidIdentity, BidLedger, BidLedgerRecord} from "./bidLedger.js";
+
+export type ObservedPostGloasBlock = {
+  blockRoot: RootHex;
+  slot: Slot;
+  version: ForkPostGloas;
+  block: SignedBeaconBlock<ForkPostGloas>;
+};
+
+export type BidSelectorModules = {
+  config: ChainForkConfig;
+  ledger: BidLedger;
+  builderIndex: BuilderIndex;
+};
+
+export enum BidSelectionIgnoreReason {
+  FOREIGN_BUILDER = "foreign_builder",
+}
+
+export type BidSelectionResult =
+  | {
+      status: "selected";
+      blockRoot: RootHex;
+      bid: BidLedgerRecord;
+    }
+  | {
+      status: "ignored";
+      reason: BidSelectionIgnoreReason;
+    };
+
+export enum BidSelectorErrorCode {
+  BLOCK_ROOT_MISMATCH = "BID_SELECTOR_ERROR_BLOCK_ROOT_MISMATCH",
+  BLOCK_SLOT_MISMATCH = "BID_SELECTOR_ERROR_BLOCK_SLOT_MISMATCH",
+  BLOCK_FORK_MISMATCH = "BID_SELECTOR_ERROR_BLOCK_FORK_MISMATCH",
+  BID_SLOT_MISMATCH = "BID_SELECTOR_ERROR_BID_SLOT_MISMATCH",
+  UNKNOWN_BID = "BID_SELECTOR_ERROR_UNKNOWN_BID",
+}
+
+export type BidSelectorErrorType =
+  | {
+      code: BidSelectorErrorCode.BLOCK_ROOT_MISMATCH;
+      blockRoot: RootHex;
+      computedBlockRoot: RootHex;
+    }
+  | {
+      code: BidSelectorErrorCode.BLOCK_SLOT_MISMATCH;
+      slot: Slot;
+      blockSlot: Slot;
+    }
+  | {
+      code: BidSelectorErrorCode.BLOCK_FORK_MISMATCH;
+      version: ForkPostGloas;
+      blockFork: string;
+    }
+  | {
+      code: BidSelectorErrorCode.BID_SLOT_MISMATCH;
+      slot: Slot;
+      bidSlot: Slot;
+    }
+  | {
+      code: BidSelectorErrorCode.UNKNOWN_BID;
+      slot: Slot;
+      parentBlockHash: RootHex;
+      parentBlockRoot: RootHex;
+      blockHash: RootHex;
+      signedBidRoot: RootHex;
+    };
+
+export class BidSelectorError extends LodestarError<BidSelectorErrorType> {}
+
+/** Matches an imported post-Gloas block to an exact local bid and records the win. */
+export class BidSelector {
+  constructor(private readonly modules: BidSelectorModules) {}
+
+  match(observed: ObservedPostGloasBlock): BidSelectionResult {
+    const {block, blockRoot, slot, version} = observed;
+    const {builderIndex, config, ledger} = this.modules;
+    const blockSlot = block.message.slot;
+
+    if (blockSlot !== slot) {
+      throw new BidSelectorError(
+        {code: BidSelectorErrorCode.BLOCK_SLOT_MISMATCH, slot, blockSlot},
+        `Observed block slot does not match fetched block slot=${slot} blockSlot=${blockSlot}`
+      );
+    }
+
+    const blockFork = config.getForkName(slot);
+    if (blockFork !== version) {
+      throw new BidSelectorError(
+        {code: BidSelectorErrorCode.BLOCK_FORK_MISMATCH, version, blockFork},
+        `Observed block fork does not match configured fork version=${version} blockFork=${blockFork}`
+      );
+    }
+
+    const computedBlockRoot = toRootHex(config.getForkTypes(slot).BeaconBlock.hashTreeRoot(block.message));
+    if (computedBlockRoot !== blockRoot) {
+      throw new BidSelectorError(
+        {code: BidSelectorErrorCode.BLOCK_ROOT_MISMATCH, blockRoot, computedBlockRoot},
+        `Observed block root does not match fetched block blockRoot=${blockRoot} computedBlockRoot=${computedBlockRoot}`
+      );
+    }
+
+    const bid = block.message.body.signedExecutionPayloadBid.message;
+    if (bid.slot !== slot) {
+      throw new BidSelectorError(
+        {code: BidSelectorErrorCode.BID_SLOT_MISMATCH, slot, bidSlot: bid.slot},
+        `Selected bid slot does not match block slot=${slot} bidSlot=${bid.slot}`
+      );
+    }
+    if (bid.builderIndex !== builderIndex) {
+      return {status: "ignored", reason: BidSelectionIgnoreReason.FOREIGN_BUILDER};
+    }
+
+    const identity: BidIdentity = {
+      slot,
+      parentBlockHash: toRootHex(bid.parentBlockHash),
+      parentBlockRoot: toRootHex(bid.parentBlockRoot),
+      blockHash: toRootHex(bid.blockHash),
+    };
+    const signedBidRoot = toRootHex(
+      sszTypesFor(version, "SignedExecutionPayloadBid").hashTreeRoot(block.message.body.signedExecutionPayloadBid)
+    );
+    const localBid = ledger.recordWin({...identity, signedBidRoot}, blockRoot);
+    if (localBid === null) {
+      throw new BidSelectorError(
+        {code: BidSelectorErrorCode.UNKNOWN_BID, ...identity, signedBidRoot},
+        `Selected bid is not in the local ledger slot=${slot} blockHash=${identity.blockHash} signedBidRoot=${signedBidRoot}`
+      );
+    }
+
+    return {status: "selected", blockRoot, bid: localBid};
+  }
+}

package/src/services/envelopePublisher.ts

@@ -0,0 +1,154 @@
+import {type ApiClient, routes} from "@lodestar/api";
+import {type BuilderIndex, type RootHex, type gloas, ssz} from "@lodestar/types";
+import {LodestarError, defer, toRootHex} from "@lodestar/utils";
+import type {BidIdentity, BidLedger} from "./bidLedger.js";
+import type {BuilderSigner} from "./builderSigner.js";
+import type {ExecutionPayloadEnvelopeContents} from "./executionPayloadEnvelope.js";
+
+export type EnvelopeSelectionIdentity = BidIdentity & {blockRoot: RootHex};
+
+export type EnvelopePublisherModules = {
+  api: ApiClient;
+  signer: BuilderSigner;
+  ledger: BidLedger;
+  builderIndex: BuilderIndex;
+};
+
+export enum EnvelopePublisherErrorCode {
+  BUILDER_INDEX_MISMATCH = "ENVELOPE_PUBLISHER_ERROR_BUILDER_INDEX_MISMATCH",
+  SELECTION_NOT_RECORDED = "ENVELOPE_PUBLISHER_ERROR_SELECTION_NOT_RECORDED",
+}
+
+export type EnvelopePublisherErrorType =
+  | {
+      code: EnvelopePublisherErrorCode.BUILDER_INDEX_MISMATCH;
+      builderIndex: BuilderIndex;
+      envelopeBuilderIndex: BuilderIndex;
+    }
+  | ({code: EnvelopePublisherErrorCode.SELECTION_NOT_RECORDED} & EnvelopeSelectionIdentity);
+
+export class EnvelopePublisherError extends LodestarError<EnvelopePublisherErrorType> {}
+
+export type EnvelopePublicationResult =
+  | {status: "published"; signedEnvelope: gloas.SignedExecutionPayloadEnvelope}
+  | {status: "duplicate"};
+
+type ActivePublication = {
+  controller: AbortController;
+  promise: Promise<EnvelopePublicationResult>;
+  waiters: number;
+};
+
+/** Signs and submits an envelope for a recorded local selection. */
+export class EnvelopePublisher {
+  private readonly activePublications = new Map<RootHex, ActivePublication>();
+
+  constructor(private readonly modules: EnvelopePublisherModules) {}
+
+  async publish(contents: ExecutionPayloadEnvelopeContents, signal: AbortSignal): Promise<EnvelopePublicationResult> {
+    signal.throwIfAborted();
+
+    const {api, builderIndex, ledger, signer} = this.modules;
+    const {envelope} = contents;
+    if (envelope.builderIndex !== builderIndex) {
+      throw new EnvelopePublisherError(
+        {
+          code: EnvelopePublisherErrorCode.BUILDER_INDEX_MISMATCH,
+          builderIndex,
+          envelopeBuilderIndex: envelope.builderIndex,
+        },
+        `Envelope builder index does not match local builder index builderIndex=${builderIndex} envelopeBuilderIndex=${envelope.builderIndex}`
+      );
+    }
+
+    const identity: EnvelopeSelectionIdentity = {
+      slot: envelope.payload.slotNumber,
+      parentBlockHash: toRootHex(envelope.payload.parentHash),
+      parentBlockRoot: toRootHex(envelope.parentBeaconBlockRoot),
+      blockHash: toRootHex(envelope.payload.blockHash),
+      blockRoot: toRootHex(envelope.beaconBlockRoot),
+    };
+    if (!ledger.hasWon(identity, identity.blockRoot)) {
+      throw new EnvelopePublisherError(
+        {code: EnvelopePublisherErrorCode.SELECTION_NOT_RECORDED, ...identity},
+        `Envelope selection is not recorded slot=${identity.slot} blockRoot=${identity.blockRoot} blockHash=${identity.blockHash}`
+      );
+    }
+
+    const envelopeRoot = toRootHex(ssz.gloas.ExecutionPayloadEnvelope.hashTreeRoot(envelope));
+    ledger.recordReveal(identity.slot, identity.blockRoot, identity.blockHash, envelopeRoot);
+    if (ledger.hasPublishedReveal(identity.blockRoot)) {
+      return {status: "duplicate"};
+    }
+
+    let publication = this.activePublications.get(identity.blockRoot);
+    if (publication === undefined) {
+      const controller = new AbortController();
+      publication = {
+        controller,
+        waiters: 0,
+        promise: this.publishEnvelope(contents, identity, envelopeRoot, api, ledger, signer, controller.signal).finally(
+          () => {
+            if (this.activePublications.get(identity.blockRoot)?.controller === controller) {
+              this.activePublications.delete(identity.blockRoot);
+            }
+          }
+        ),
+      };
+      this.activePublications.set(identity.blockRoot, publication);
+    }
+    return this.waitForPublication(identity.blockRoot, publication, signal);
+  }
+
+  private async waitForPublication(
+    blockRoot: RootHex,
+    publication: ActivePublication,
+    signal: AbortSignal
+  ): Promise<EnvelopePublicationResult> {
+    const aborted = defer<never>();
+    const onAbort = (): void => aborted.reject(signal.reason);
+    publication.waiters++;
+    signal.addEventListener("abort", onAbort, {once: true});
+    if (signal.aborted) onAbort();
+
+    try {
+      return await Promise.race([publication.promise, aborted.promise]);
+    } finally {
+      signal.removeEventListener("abort", onAbort);
+      publication.waiters--;
+      if (publication.waiters === 0 && signal.aborted) {
+        if (this.activePublications.get(blockRoot) === publication) {
+          this.activePublications.delete(blockRoot);
+        }
+        publication.controller.abort(signal.reason);
+      }
+    }
+  }
+
+  private async publishEnvelope(
+    contents: ExecutionPayloadEnvelopeContents,
+    identity: EnvelopeSelectionIdentity,
+    envelopeRoot: RootHex,
+    api: ApiClient,
+    ledger: BidLedger,
+    signer: BuilderSigner,
+    signal: AbortSignal
+  ): Promise<EnvelopePublicationResult> {
+    const signedEnvelope = signer.signExecutionPayloadEnvelope(contents.envelope);
+
+    const response = await api.beacon.publishExecutionPayloadEnvelope(
+      {
+        signedEnvelopeOrContents: {
+          signedExecutionPayloadEnvelope: signedEnvelope,
+          kzgProofs: contents.kzgProofs,
+          blobs: contents.blobs,
+        },
+        broadcastValidation: routes.beacon.BroadcastValidation.gossip,
+      },
+      {signal}
+    );
+    response.assertOk();
+    ledger.recordRevealPublished(identity.slot, identity.blockRoot, identity.blockHash, envelopeRoot);
+    return {status: "published", signedEnvelope};
+  }
+}

package/src/services/executionPayloadEnvelope.ts

@@ -0,0 +1,156 @@
+import type {BuilderIndex, RootHex, Slot, deneb, gloas} from "@lodestar/types";
+import {ssz} from "@lodestar/types";
+import {LodestarError, byteArrayEquals, fromHex, toRootHex} from "@lodestar/utils";
+import type {StoredPayload} from "./payloadStore.js";
+
+export type ExecutionPayloadEnvelopeInput = {
+  blockRoot: RootHex;
+  builderIndex: BuilderIndex;
+  selectedBid: gloas.ExecutionPayloadBid;
+  storedPayload: StoredPayload;
+};
+
+export type ExecutionPayloadEnvelopeContents = {
+  envelope: gloas.ExecutionPayloadEnvelope;
+  kzgProofs: deneb.KZGProofs;
+  blobs: deneb.Blobs;
+};
+
+export enum ExecutionPayloadEnvelopeErrorCode {
+  SLOT_MISMATCH = "EXECUTION_PAYLOAD_ENVELOPE_ERROR_SLOT_MISMATCH",
+  PARENT_BLOCK_ROOT_MISMATCH = "EXECUTION_PAYLOAD_ENVELOPE_ERROR_PARENT_BLOCK_ROOT_MISMATCH",
+  PARENT_BLOCK_HASH_MISMATCH = "EXECUTION_PAYLOAD_ENVELOPE_ERROR_PARENT_BLOCK_HASH_MISMATCH",
+  BLOCK_HASH_MISMATCH = "EXECUTION_PAYLOAD_ENVELOPE_ERROR_BLOCK_HASH_MISMATCH",
+  BUILDER_INDEX_MISMATCH = "EXECUTION_PAYLOAD_ENVELOPE_ERROR_BUILDER_INDEX_MISMATCH",
+  BLOB_KZG_COMMITMENTS_MISMATCH = "EXECUTION_PAYLOAD_ENVELOPE_ERROR_BLOB_KZG_COMMITMENTS_MISMATCH",
+  EXECUTION_REQUESTS_ROOT_MISMATCH = "EXECUTION_PAYLOAD_ENVELOPE_ERROR_EXECUTION_REQUESTS_ROOT_MISMATCH",
+}
+
+export type ExecutionPayloadEnvelopeErrorType =
+  | {
+      code: ExecutionPayloadEnvelopeErrorCode.BUILDER_INDEX_MISMATCH;
+      builderIndex: BuilderIndex;
+      bidBuilderIndex: BuilderIndex;
+    }
+  | {code: ExecutionPayloadEnvelopeErrorCode.BLOB_KZG_COMMITMENTS_MISMATCH}
+  | {
+      code: ExecutionPayloadEnvelopeErrorCode.EXECUTION_REQUESTS_ROOT_MISMATCH;
+      bidExecutionRequestsRoot: RootHex;
+      payloadExecutionRequestsRoot: RootHex;
+    }
+  | {
+      code: ExecutionPayloadEnvelopeErrorCode.PARENT_BLOCK_ROOT_MISMATCH;
+      bidParentBlockRoot: RootHex;
+      storedParentBlockRoot: RootHex;
+    }
+  | {
+      code: ExecutionPayloadEnvelopeErrorCode.SLOT_MISMATCH;
+      bidSlot: Slot;
+      payloadSlot: Slot;
+    }
+  | {
+      code: ExecutionPayloadEnvelopeErrorCode.PARENT_BLOCK_HASH_MISMATCH;
+      bidParentBlockHash: RootHex;
+      payloadParentBlockHash: RootHex;
+    }
+  | {
+      code: ExecutionPayloadEnvelopeErrorCode.BLOCK_HASH_MISMATCH;
+      bidBlockHash: RootHex;
+      payloadBlockHash: RootHex;
+    };
+
+export class ExecutionPayloadEnvelopeError extends LodestarError<ExecutionPayloadEnvelopeErrorType> {}
+
+/** The caller must have matched the selected bid to its local ledger record. */
+export function createExecutionPayloadEnvelopeContents({
+  blockRoot,
+  builderIndex,
+  selectedBid,
+  storedPayload,
+}: ExecutionPayloadEnvelopeInput): ExecutionPayloadEnvelopeContents {
+  if (builderIndex !== selectedBid.builderIndex) {
+    throw new ExecutionPayloadEnvelopeError({
+      code: ExecutionPayloadEnvelopeErrorCode.BUILDER_INDEX_MISMATCH,
+      builderIndex,
+      bidBuilderIndex: selectedBid.builderIndex,
+    });
+  }
+
+  const bidParentBlockRoot = toRootHex(selectedBid.parentBlockRoot);
+  const storedParentBlockRoot = toRootHex(storedPayload.parentBlockRoot);
+  if (storedParentBlockRoot !== bidParentBlockRoot) {
+    throw new ExecutionPayloadEnvelopeError(
+      {
+        code: ExecutionPayloadEnvelopeErrorCode.PARENT_BLOCK_ROOT_MISMATCH,
+        bidParentBlockRoot,
+        storedParentBlockRoot,
+      },
+      `Selected bid beacon parent does not match retained payload bidParentBlockRoot=${bidParentBlockRoot} storedParentBlockRoot=${storedParentBlockRoot}`
+    );
+  }
+
+  const {payload} = storedPayload;
+  const payloadSlot = payload.executionPayload.slotNumber;
+  if (payloadSlot !== selectedBid.slot) {
+    throw new ExecutionPayloadEnvelopeError(
+      {code: ExecutionPayloadEnvelopeErrorCode.SLOT_MISMATCH, bidSlot: selectedBid.slot, payloadSlot},
+      `Selected bid slot does not match payload slot bidSlot=${selectedBid.slot} payloadSlot=${payloadSlot}`
+    );
+  }
+
+  const payloadParentBlockHash = toRootHex(payload.executionPayload.parentHash);
+  const bidParentBlockHash = toRootHex(selectedBid.parentBlockHash);
+  if (payloadParentBlockHash !== bidParentBlockHash) {
+    throw new ExecutionPayloadEnvelopeError(
+      {
+        code: ExecutionPayloadEnvelopeErrorCode.PARENT_BLOCK_HASH_MISMATCH,
+        bidParentBlockHash,
+        payloadParentBlockHash,
+      },
+      `Selected bid parent does not match payload parent bidParentBlockHash=${bidParentBlockHash} payloadParentBlockHash=${payloadParentBlockHash}`
+    );
+  }
+
+  const payloadBlockHash = toRootHex(payload.executionPayload.blockHash);
+  const bidBlockHash = toRootHex(selectedBid.blockHash);
+  if (payloadBlockHash !== bidBlockHash) {
+    throw new ExecutionPayloadEnvelopeError(
+      {
+        code: ExecutionPayloadEnvelopeErrorCode.BLOCK_HASH_MISMATCH,
+        bidBlockHash,
+        payloadBlockHash,
+      },
+      `Selected bid block hash does not match payload bidBlockHash=${bidBlockHash} payloadBlockHash=${payloadBlockHash}`
+    );
+  }
+
+  if (
+    !ssz.gloas.ExecutionPayloadBid.fields.blobKzgCommitments.equals(
+      selectedBid.blobKzgCommitments,
+      payload.blobsBundle.commitments
+    )
+  ) {
+    throw new ExecutionPayloadEnvelopeError({code: ExecutionPayloadEnvelopeErrorCode.BLOB_KZG_COMMITMENTS_MISMATCH});
+  }
+
+  const executionRequestsRoot = ssz.gloas.ExecutionRequests.hashTreeRoot(payload.executionRequests);
+  if (!byteArrayEquals(executionRequestsRoot, selectedBid.executionRequestsRoot)) {
+    throw new ExecutionPayloadEnvelopeError({
+      code: ExecutionPayloadEnvelopeErrorCode.EXECUTION_REQUESTS_ROOT_MISMATCH,
+      bidExecutionRequestsRoot: toRootHex(selectedBid.executionRequestsRoot),
+      payloadExecutionRequestsRoot: toRootHex(executionRequestsRoot),
+    });
+  }
+
+  return {
+    envelope: {
+      payload: payload.executionPayload,
+      executionRequests: payload.executionRequests,
+      builderIndex,
+      beaconBlockRoot: fromHex(blockRoot),
+      parentBeaconBlockRoot: selectedBid.parentBlockRoot,
+    },
+    kzgProofs: payload.blobsBundle.proofs,
+    blobs: payload.blobsBundle.blobs,
+  };
+}