@lodestar/builder 1.51.0-dev.a736f94f66 → 1.51.0-dev.ab919f3073

package/lib/services/bidder.d.ts

@@ -0,0 +1,56 @@
+import { ApiClient, routes } from "@lodestar/api";
+import { ChainForkConfig } from "@lodestar/config";
+import { IClock } from "@lodestar/state-transition";
+import { BuilderIndex, BuilderStatus, ExecutionAddress } from "@lodestar/types";
+import { Logger } from "@lodestar/utils";
+import { Metrics } from "../metrics.js";
+import { BidLedger } from "./bidLedger.js";
+import { BidPolicy } from "./bidPolicy.js";
+import { BidPublisher } from "./bidPublisher.js";
+import { PayloadOrchestrator } from "./payloadOrchestrator.js";
+import { PayloadStore } from "./payloadStore.js";
+import { ProposerPreferencesTracker } from "./proposerPreferencesTracker.js";
+export type PayloadAttributesEvent = routes.events.EventData[routes.events.EventType.payloadAttributes];
+export type BidderOptions = {
+    /** Point within the slot before the proposal slot at which the payload is retrieved and bid on, in basis points */
+    deadlineBps: number;
+    /** Do not bid while the builder balance is below this value */
+    minOperatingBalanceGwei: number;
+};
+export type BidderModules = {
+    config: ChainForkConfig;
+    logger: Logger;
+    clock: IClock;
+    api: ApiClient;
+    orchestrator: PayloadOrchestrator;
+    payloadStore: PayloadStore;
+    ledger: BidLedger;
+    policy: BidPolicy;
+    bidPublisher: BidPublisher;
+    proposerPreferencesTracker: ProposerPreferencesTracker;
+    getBuilderStatus: () => {
+        status: BuilderStatus | undefined;
+        balance: number | undefined;
+    };
+    builderIndex: BuilderIndex;
+    executionFeeRecipient: ExecutionAddress;
+    metrics: Metrics | null;
+    signal: AbortSignal;
+};
+/**
+ * Bids once per proposal slot and parent: starts a payload build when the beacon node emits payload attributes,
+ * retrieves the payload at the deadline, prices it and publishes the signed bid.
+ */
+export declare class Bidder {
+    private readonly modules;
+    private readonly opts;
+    private readonly activeBuilds;
+    constructor(modules: BidderModules, opts: BidderOptions);
+    onPayloadAttributes(event: PayloadAttributesEvent): Promise<void>;
+    /**
+     * Dependent root of the proposer duties in the given epoch, identifies the proposer preferences to bid against.
+     * Not cached, a reorg can change the dependent root within an epoch. Active builds already coalesce repeated attributes.
+     */
+    private getDependentRoot;
+}
+//# sourceMappingURL=bidder.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"bidder.d.ts","sourceRoot":"","sources":["../../src/services/bidder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,SAAS,EAAE,MAAM,EAAC,MAAM,eAAe,CAAC;AAChD,OAAO,EAAC,eAAe,EAAC,MAAM,kBAAkB,CAAC;AAEjD,OAAO,EAAC,MAAM,EAAqB,MAAM,4BAA4B,CAAC;AACtE,OAAO,EAAC,YAAY,EAAE,aAAa,EAAS,gBAAgB,EAAiB,MAAM,iBAAiB,CAAC;AACrG,OAAO,EAAc,MAAM,EAAoD,MAAM,iBAAiB,CAAC;AACvG,OAAO,EAAY,OAAO,EAAC,MAAM,eAAe,CAAC;AACjD,OAAO,EAAC,SAAS,EAAC,MAAM,gBAAgB,CAAC;AACzC,OAAO,EAAC,SAAS,EAAC,MAAM,gBAAgB,CAAC;AACzC,OAAO,EAAC,YAAY,EAAC,MAAM,mBAAmB,CAAC;AAE/C,OAAO,EAAC,mBAAmB,EAAC,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAC,YAAY,EAAC,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAC,0BAA0B,EAAC,MAAM,iCAAiC,CAAC;AAE3E,MAAM,MAAM,sBAAsB,GAAG,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,iBAAiB,CAAC,CAAC;AAExG,MAAM,MAAM,aAAa,GAAG;IAC1B,mHAAmH;IACnH,WAAW,EAAE,MAAM,CAAC;IACpB,+DAA+D;IAC/D,uBAAuB,EAAE,MAAM,CAAC;CACjC,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,MAAM,EAAE,eAAe,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,SAAS,CAAC;IACf,YAAY,EAAE,mBAAmB,CAAC;IAClC,YAAY,EAAE,YAAY,CAAC;IAC3B,MAAM,EAAE,SAAS,CAAC;IAClB,MAAM,EAAE,SAAS,CAAC;IAClB,YAAY,EAAE,YAAY,CAAC;IAC3B,0BAA0B,EAAE,0BAA0B,CAAC;IACvD,gBAAgB,EAAE,MAAM;QAAC,MAAM,EAAE,aAAa,GAAG,SAAS,CAAC;QAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAA;KAAC,CAAC;IACzF,YAAY,EAAE,YAAY,CAAC;IAC3B,qBAAqB,EAAE,gBAAgB,CAAC;IACxC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,WAAW,CAAC;CACrB,CAAC;AAEF;;;GAGG;AACH,qBAAa,MAAM;IAIf,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAJvB,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAqB;IAElD,YACmB,OAAO,EAAE,aAAa,EACtB,IAAI,EAAE,aAAa,EAClC;IAEE,mBAAmB,CAAC,KAAK,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CA+HtE;IAED;;;OAGG;YACW,gBAAgB;CAG/B"}

package/lib/services/bidder.js

@@ -0,0 +1,144 @@
+import { ForkName, MIN_DEPOSIT_AMOUNT, isForkPostGloas } from "@lodestar/params";
+import { computeEpochAtSlot } from "@lodestar/state-transition";
+import { GWEI_TO_WEI, isErrorAborted, prettyGweiToEth, toHex, toRootHex } from "@lodestar/utils";
+import { BidResult } from "../metrics.js";
+import { createExecutionPayloadBid } from "./executionPayloadBid.js";
+/**
+ * Bids once per proposal slot and parent: starts a payload build when the beacon node emits payload attributes,
+ * retrieves the payload at the deadline, prices it and publishes the signed bid.
+ */
+export class Bidder {
+    modules;
+    opts;
+    activeBuilds = new Set();
+    constructor(modules, opts) {
+        this.modules = modules;
+        this.opts = opts;
+    }
+    async onPayloadAttributes(event) {
+        const { clock, config, ledger, logger, metrics, orchestrator, proposerPreferencesTracker } = this.modules;
+        if (!isForkPostGloas(event.version)) {
+            return;
+        }
+        const data = event.data;
+        const slot = data.proposalSlot;
+        const parentBlockRoot = toRootHex(data.parentBlockRoot);
+        const parentBlockHash = toRootHex(data.parentBlockHash);
+        const logCtx = { slot, parentBlockRoot, parentBlockHash };
+        if (slot <= clock.getCurrentSlot()) {
+            logger.debug("Ignoring payload attributes for past slot", logCtx);
+            return;
+        }
+        // TODO: the beacon node emits payload attributes once per slot, late in the slot and only for the parent
+        // payload variant it would build on, revisit to start the build earlier and to bid on both variants
+        const buildId = `${slot}:${parentBlockRoot}:${parentBlockHash}`;
+        if (this.activeBuilds.has(buildId) || ledger.hasSubmitted(slot, parentBlockHash, parentBlockRoot)) {
+            return;
+        }
+        this.activeBuilds.add(buildId);
+        try {
+            // Heze bids require inclusion list bits which are not tracked yet
+            if (event.version !== ForkName.gloas) {
+                logger.warn("Bidding is not supported for fork", { ...logCtx, fork: event.version });
+                return;
+            }
+            const dependentRoot = await this.getDependentRoot(computeEpochAtSlot(slot), this.modules.signal);
+            const proposerPreferences = proposerPreferencesTracker.get(slot, dependentRoot);
+            if (proposerPreferences === null) {
+                logger.debug("No proposer preferences known for slot, not bidding", { ...logCtx, dependentRoot });
+                metrics?.bids.total.inc({ result: BidResult.noProposerPreferences });
+                return;
+            }
+            const { feeRecipient, targetGasLimit } = proposerPreferences.message;
+            // The payload is retrieved in the slot before the proposal slot, use the timing of that slot
+            const buildFork = config.getForkName(slot - 1);
+            const msToDeadline = clock.msToSlot(slot) -
+                config.getSlotDurationMs(buildFork) +
+                config.getSlotComponentDurationMs(buildFork, this.opts.deadlineBps);
+            logger.verbose("Preparing payload build", { ...logCtx, msToDeadline, targetGasLimit });
+            const payload = await orchestrator.run({
+                id: buildId,
+                request: {
+                    fork: event.version,
+                    forkchoiceState: {
+                        headBlockHash: parentBlockHash,
+                        safeBlockHash: toRootHex(data.safeBlockHash),
+                        finalizedBlockHash: toRootHex(data.finalizedBlockHash),
+                    },
+                    payloadAttributes: {
+                        ...data.payloadAttributes,
+                        suggestedFeeRecipient: toHex(this.modules.executionFeeRecipient),
+                        targetGasLimit,
+                    },
+                },
+                getPayloadAt: Date.now() + msToDeadline,
+            });
+            const { status, balance } = this.modules.getBuilderStatus();
+            if (status !== "active" || balance === undefined) {
+                logger.warn("Builder is not active, not bidding", { ...logCtx, status });
+                metrics?.bids.total.inc({ result: BidResult.inactive });
+                return;
+            }
+            if (balance < this.opts.minOperatingBalanceGwei) {
+                logger.warn("Builder balance below operating minimum, not bidding", {
+                    ...logCtx,
+                    balance: prettyGweiToEth(balance),
+                    minOperatingBalance: prettyGweiToEth(this.opts.minOperatingBalanceGwei),
+                });
+                metrics?.bids.total.inc({ result: BidResult.lowBalance });
+                return;
+            }
+            const unsettledGwei = ledger.getUnsettledValueGwei(computeEpochAtSlot(slot));
+            const coverableGwei = Math.max(balance - MIN_DEPOSIT_AMOUNT - unsettledGwei, 0);
+            const payloadValueGwei = Number(payload.executionPayloadValue / GWEI_TO_WEI);
+            const value = this.modules.policy.computeValue({ payloadValueGwei, coverableGwei });
+            if (value === null) {
+                logger.info("Bid policy declined to bid", { ...logCtx, payloadValueGwei, coverableGwei, unsettledGwei });
+                metrics?.bids.total.inc({ result: BidResult.policyDeclined });
+                return;
+            }
+            const { executionPayload } = payload;
+            const blockHash = toRootHex(executionPayload.blockHash);
+            this.modules.payloadStore.add({ slot, parentBlockRoot: data.parentBlockRoot, blockHash, payload });
+            const bid = createExecutionPayloadBid({
+                slot,
+                parentBlockRoot: data.parentBlockRoot,
+                prevRandao: data.payloadAttributes.prevRandao,
+                builderIndex: this.modules.builderIndex,
+                feeRecipient,
+                value,
+                payload: { ...payload, fork: ForkName.gloas },
+            });
+            await this.modules.bidPublisher.publish(bid, this.modules.signal);
+            metrics?.bids.total.inc({ result: BidResult.published });
+            logger.info("Published execution payload bid", {
+                ...logCtx,
+                blockHash,
+                value: prettyGweiToEth(value),
+                payloadValue: prettyGweiToEth(payloadValueGwei),
+                feeRecipient: toHex(feeRecipient),
+                gasLimit: executionPayload.gasLimit,
+                transactions: executionPayload.transactions.length,
+                blobs: bid.blobKzgCommitments.length,
+                secFromSlot: clock.secFromSlot(slot),
+            });
+        }
+        catch (e) {
+            if (!isErrorAborted(e)) {
+                metrics?.bids.total.inc({ result: BidResult.error });
+                logger.error("Failed to bid", logCtx, e);
+            }
+        }
+        finally {
+            this.activeBuilds.delete(buildId);
+        }
+    }
+    /**
+     * Dependent root of the proposer duties in the given epoch, identifies the proposer preferences to bid against.
+     * Not cached, a reorg can change the dependent root within an epoch. Active builds already coalesce repeated attributes.
+     */
+    async getDependentRoot(epoch, signal) {
+        return (await this.modules.api.validator.getProposerDutiesV2({ epoch }, { signal })).meta().dependentRoot;
+    }
+}
+//# sourceMappingURL=bidder.js.map

package/lib/services/bidder.js.map

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

package/lib/services/payloadOrchestrator.d.ts

@@ -21,14 +21,18 @@ export type PayloadOrchestratorErrorType = {
     jobId: string;
     getPayloadAt: number;
 } | {
-    code: PayloadOrchestratorErrorCode.PREPARE_TIMEOUT | PayloadOrchestratorErrorCode.GET_PAYLOAD_TIMEOUT;
+    code: PayloadOrchestratorErrorCode.PREPARE_TIMEOUT;
+    jobId: string;
+    lastError: string | null;
+} | {
+    code: 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.
+ * Prepares a payload and retrieves it at the requested time. A missing payload ID is retried until the
+ * retrieval time, the execution client may not have imported the parent payload yet. Other errors fail the build.
  */
 export declare class PayloadOrchestrator {
     private readonly source;

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

@@ -1 +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"}
+{"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,CAAC;IACnD,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B,GACD;IACE,IAAI,EAAE,4BAA4B,CAAC,mBAAmB,CAAC;IACvD,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;CA+CrB"}

package/lib/services/payloadOrchestrator.js

@@ -10,8 +10,8 @@ export var 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.
+ * Prepares a payload and retrieves it at the requested time. A missing payload ID is retried until the
+ * retrieval time, the execution client may not have imported the parent payload yet. Other errors fail the build.
  */
 export class PayloadOrchestrator {
     source;
@@ -37,14 +37,18 @@ export class PayloadOrchestrator {
         if (!(prepareTimeout > 0)) {
             throw new PayloadOrchestratorError({ code: PayloadOrchestratorErrorCode.PREPARE_DEADLINE_REACHED, jobId: id, getPayloadAt }, `Payload preparation deadline reached jobId=${id} getPayloadAt=${getPayloadAt}`);
         }
+        let lastError = null;
         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,
+            onRetry: (error) => {
+                lastError = error;
+            },
             signal,
         }), prepareTimeout, this.signal).catch((error) => {
             if (error instanceof TimeoutError) {
-                throw new PayloadOrchestratorError({ code: PayloadOrchestratorErrorCode.PREPARE_TIMEOUT, jobId: id });
+                throw new PayloadOrchestratorError({ code: PayloadOrchestratorErrorCode.PREPARE_TIMEOUT, jobId: id, lastError: lastError?.message ?? null }, `Payload preparation timed out jobId=${id} lastError=${lastError?.message}`);
             }
             throw error;
         });

package/lib/services/payloadOrchestrator.js.map

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

package/lib/services/revealer.d.ts

@@ -0,0 +1,35 @@
+import { ChainForkConfig } from "@lodestar/config";
+import { IClock } from "@lodestar/state-transition";
+import { BuilderIndex } from "@lodestar/types";
+import { Logger } from "@lodestar/utils";
+import { Metrics } from "../metrics.js";
+import { BidSelector } from "./bidSelector.js";
+import { ObservedBlock } from "./blockObserver.js";
+import { EnvelopePublisher } from "./envelopePublisher.js";
+import { PayloadStore } from "./payloadStore.js";
+export type RevealerOptions = {
+    /**
+     * Latest point within the block's slot at which a reveal may start, in basis points.
+     * Defaults to the network's PAYLOAD_ATTESTATION_DUE_BPS
+     */
+    cutoffBps: number;
+};
+export type RevealerModules = {
+    config: ChainForkConfig;
+    logger: Logger;
+    clock: IClock;
+    bidSelector: BidSelector;
+    payloadStore: PayloadStore;
+    envelopePublisher: EnvelopePublisher;
+    builderIndex: BuilderIndex;
+    metrics: Metrics | null;
+    signal: AbortSignal;
+};
+/** Reveals the payload once a block committing to one of our bids is imported by the beacon node. */
+export declare class Revealer {
+    private readonly modules;
+    private readonly opts;
+    constructor(modules: RevealerModules, opts: RevealerOptions);
+    onBlock(observed: ObservedBlock): Promise<void>;
+}
+//# sourceMappingURL=revealer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"revealer.d.ts","sourceRoot":"","sources":["../../src/services/revealer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,eAAe,EAAC,MAAM,kBAAkB,CAAC;AACjD,OAAO,EAAC,MAAM,EAAC,MAAM,4BAA4B,CAAC;AAClD,OAAO,EAAC,YAAY,EAAC,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAC,MAAM,EAAC,MAAM,iBAAiB,CAAC;AACvC,OAAO,EAAC,OAAO,EAAe,MAAM,eAAe,CAAC;AACpD,OAAO,EAAC,WAAW,EAAC,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAC,aAAa,EAAC,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAC,iBAAiB,EAAC,MAAM,wBAAwB,CAAC;AAEzD,OAAO,EAAC,YAAY,EAAC,MAAM,mBAAmB,CAAC;AAE/C,MAAM,MAAM,eAAe,GAAG;IAC5B;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,MAAM,EAAE,eAAe,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,WAAW,CAAC;IACzB,YAAY,EAAE,YAAY,CAAC;IAC3B,iBAAiB,EAAE,iBAAiB,CAAC;IACrC,YAAY,EAAE,YAAY,CAAC;IAC3B,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,WAAW,CAAC;CACrB,CAAC;AAEF,qGAAqG;AACrG,qBAAa,QAAQ;IAEjB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAFvB,YACmB,OAAO,EAAE,eAAe,EACxB,IAAI,EAAE,eAAe,EACpC;IAEE,OAAO,CAAC,QAAQ,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAgDpD;CACF"}

package/lib/services/revealer.js

@@ -0,0 +1,56 @@
+import { RevealResult } from "../metrics.js";
+import { createExecutionPayloadEnvelopeContents } from "./executionPayloadEnvelope.js";
+/** Reveals the payload once a block committing to one of our bids is imported by the beacon node. */
+export class Revealer {
+    modules;
+    opts;
+    constructor(modules, opts) {
+        this.modules = modules;
+        this.opts = opts;
+    }
+    async onBlock(observed) {
+        const { bidSelector, clock, config, envelopePublisher, logger, metrics, payloadStore } = this.modules;
+        const selection = bidSelector.match(observed);
+        if (selection.status !== "selected") {
+            return;
+        }
+        metrics?.bids.won.inc();
+        const { blockRoot, slot } = observed;
+        const { blockHash } = selection.bid;
+        const logCtx = { slot, blockRoot, blockHash };
+        const storedPayload = payloadStore.get(blockHash);
+        if (storedPayload === null) {
+            logger.error("Payload of selected bid is not retained, cannot reveal", logCtx);
+            metrics?.reveals.total.inc({ result: RevealResult.unknownPayload });
+            return;
+        }
+        const msFromSlot = clock.msFromSlot(slot);
+        const cutoffMs = config.getSlotComponentDurationMs(config.getForkName(slot), this.opts.cutoffBps);
+        if (msFromSlot > cutoffMs) {
+            logger.warn("Block with our bid arrived after reveal cutoff, not revealing", { ...logCtx, msFromSlot, cutoffMs });
+            metrics?.reveals.total.inc({ result: RevealResult.late });
+            return;
+        }
+        const contents = createExecutionPayloadEnvelopeContents({
+            blockRoot,
+            builderIndex: this.modules.builderIndex,
+            selectedBid: observed.signedBid.message,
+            storedPayload,
+        });
+        try {
+            await envelopePublisher.publish(contents, this.modules.signal);
+        }
+        catch (e) {
+            metrics?.reveals.total.inc({ result: RevealResult.error });
+            throw e;
+        }
+        metrics?.reveals.total.inc({ result: RevealResult.published });
+        logger.info("Revealed execution payload", {
+            ...logCtx,
+            blobs: contents.blobs.length,
+            transactions: contents.envelope.payload.transactions.length,
+            secFromSlot: clock.secFromSlot(slot),
+        });
+    }
+}
+//# sourceMappingURL=revealer.js.map

package/lib/services/revealer.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lodestar/builder",
-  "version": "1.51.0-dev.a736f94f66",
+  "version": "1.51.0-dev.ab919f3073",
   "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.1",
-    "@lodestar/api": "^1.51.0-dev.a736f94f66",
-    "@lodestar/config": "^1.51.0-dev.a736f94f66",
-    "@lodestar/params": "^1.51.0-dev.a736f94f66",
-    "@lodestar/state-transition": "^1.51.0-dev.a736f94f66",
-    "@lodestar/types": "^1.51.0-dev.a736f94f66",
-    "@lodestar/utils": "^1.51.0-dev.a736f94f66"
+    "@chainsafe/ssz": "^1.9.0",
+    "@lodestar/api": "^1.51.0-dev.ab919f3073",
+    "@lodestar/config": "^1.51.0-dev.ab919f3073",
+    "@lodestar/params": "^1.51.0-dev.ab919f3073",
+    "@lodestar/state-transition": "^1.51.0-dev.ab919f3073",
+    "@lodestar/types": "^1.51.0-dev.ab919f3073",
+    "@lodestar/utils": "^1.51.0-dev.ab919f3073"
   },
   "devDependencies": {
-    "@lodestar/logger": "^1.51.0-dev.a736f94f66",
-    "@lodestar/test-utils": "^1.51.0-dev.a736f94f66"
+    "@lodestar/logger": "^1.51.0-dev.ab919f3073",
+    "@lodestar/test-utils": "^1.51.0-dev.ab919f3073"
   },
-  "gitHead": "eb9190aa94c96a495ba10f26583df00910f35366"
+  "gitHead": "ad189abc417dde323db703fab9c72dba01a735cc"
 }

package/src/builder.ts

@@ -1,5 +1,6 @@
 import {ApiClient, routes} from "@lodestar/api";
 import {ChainForkConfig, assertEqualParams, createBeaconConfig} from "@lodestar/config";
+import {SLOTS_PER_EPOCH} from "@lodestar/params";
 import {Clock, ClockOptions, IClock} from "@lodestar/state-transition";
 import {BuilderIndex, ExecutionAddress} from "@lodestar/types";
 import {Logger, isErrorAborted, toHex, toRootHex} from "@lodestar/utils";
@@ -7,11 +8,26 @@ import {waitForGenesis} from "./genesis.js";
 import {resolveBuilderIdentity} from "./identity.js";
 import {Metrics} from "./metrics.js";
 import {logNodeVersion, waitForNodeReady} from "./readiness.js";
+import {Bidder, BidderOptions} from "./services/bidder.js";
+import {BidLedger} from "./services/bidLedger.js";
+import {ProportionalBidPolicy, ProportionalBidPolicyOpts} from "./services/bidPolicy.js";
+import {BidPublisher} from "./services/bidPublisher.js";
+import {BidSelector} from "./services/bidSelector.js";
 import {BlockObserver} from "./services/blockObserver.js";
 import {BuilderSigner, Keypair} from "./services/builderSigner.js";
 import {BuilderStatusTracker} from "./services/builderStatusTracker.js";
+import {EnvelopePublisher} from "./services/envelopePublisher.js";
+import {PayloadOrchestrator} from "./services/payloadOrchestrator.js";
+import {PayloadSource} from "./services/payloadSource.js";
 import {PayloadStore} from "./services/payloadStore.js";
 import {ProposerPreferencesTracker} from "./services/proposerPreferencesTracker.js";
+import {Revealer} from "./services/revealer.js";
+
+// Payments of won bids are assumed to be reflected in the builder balance after this many slots.
+// The payment is queued as a builder withdrawal at the epoch transition after the bid epoch and only debited once that
+// withdrawal is processed, so with a backlog of withdrawals the ledger releases the reservation before the balance drops.
+// Reconciling against the pending payments and pending withdrawals of the state is a follow-up.
+const PAYMENT_SETTLEMENT_SLOTS = 3 * SLOTS_PER_EPOCH;
 
 export type BuilderModules = {
   opts: BuilderOptions;
@@ -22,6 +38,9 @@ export type BuilderModules = {
   clock: IClock;
   index: BuilderIndex;
   payloadStore: PayloadStore;
+  ledger: BidLedger;
+  bidder: Bidder;
+  revealer: Revealer;
 };
 
 export type BuilderOptions = {
@@ -31,8 +50,20 @@ export type BuilderOptions = {
   abortController: AbortController;
   api: ApiClient;
   clock?: ClockOptions;
+  /** Fee recipient of built payloads, receives priority fees and MEV */
   executionFeeRecipient: ExecutionAddress;
   metrics: Metrics | null;
+  /** Payload construction engine, an execution client is one implementation */
+  payloadSource: PayloadSource;
+  bidding: BidderOptions &
+    ProportionalBidPolicyOpts & {
+      /** Maximum time in milliseconds to wait for payload retrieval at the bid deadline */
+      getPayloadTimeout: number;
+    };
+  reveal: {
+    /** Defaults to PAYLOAD_ATTESTATION_DUE_BPS of the network */
+    cutoffBps?: number;
+  };
 };
 
 /**
@@ -49,6 +80,9 @@ export class Builder {
   private readonly logger: Logger;
   private readonly executionFeeRecipient: ExecutionAddress;
   private readonly payloadStore: PayloadStore;
+  private readonly ledger: BidLedger;
+  private readonly bidder: Bidder;
+  private readonly revealer: Revealer;
 
   constructor({
     opts,
@@ -59,6 +93,9 @@ export class Builder {
     clock,
     index,
     payloadStore,
+    ledger,
+    bidder,
+    revealer,
   }: BuilderModules) {
     this.builderSigner = builderSigner;
     this.blockObserver = blockObserver;
@@ -69,9 +106,13 @@ export class Builder {
     this.logger = opts.logger;
     this.index = index;
     this.payloadStore = payloadStore;
+    this.ledger = ledger;
+    this.bidder = bidder;
+    this.revealer = revealer;
 
     this.executionFeeRecipient = opts.executionFeeRecipient;
 
+    this.blockObserver.runOnBlock((block) => this.revealer.onBlock(block));
     this.clock.runEverySlot(async (slot) => this.onSlot(slot));
     this.clock.runEveryEpoch((epoch) => this.builderStatusTracker.poll(epoch));
     this.clock.start(this.controller.signal);
@@ -80,6 +121,9 @@ export class Builder {
     this.logger.info("Builder client initialized", {
       index: this.index,
       executionFeeRecipient: toHex(this.executionFeeRecipient),
+      payloadSource: opts.payloadSource.id,
+      shareBps: opts.bidding.shareBps,
+      deadlineBps: opts.bidding.deadlineBps,
     });
   }
 
@@ -112,10 +156,60 @@ export class Builder {
     );
 
     const builderStatusTracker = new BuilderStatusTracker(api, logger, index, opts.metrics);
+    await builderStatusTracker.poll(clock.getCurrentEpoch());
     const blockObserver = new BlockObserver(config, logger, api);
     const proposerPreferencesTracker = new ProposerPreferencesTracker();
 
     const payloadStore = new PayloadStore();
+    const ledger = new BidLedger();
+    const signal = opts.abortController.signal;
+
+    const bidder = new Bidder(
+      {
+        config,
+        logger,
+        clock,
+        api,
+        orchestrator: new PayloadOrchestrator(
+          opts.payloadSource,
+          {getPayloadTimeout: opts.bidding.getPayloadTimeout},
+          signal
+        ),
+        payloadStore,
+        ledger,
+        policy: new ProportionalBidPolicy(opts.bidding),
+        bidPublisher: new BidPublisher({
+          api,
+          config,
+          signer: builderSigner,
+          ledger,
+          builderIndex: index,
+          hasPayload: ({blockHash}) => payloadStore.has(blockHash),
+        }),
+        proposerPreferencesTracker,
+        getBuilderStatus: () => builderStatusTracker.getStatus(),
+        builderIndex: index,
+        executionFeeRecipient: opts.executionFeeRecipient,
+        metrics: opts.metrics,
+        signal,
+      },
+      opts.bidding
+    );
+
+    const revealer = new Revealer(
+      {
+        config,
+        logger,
+        clock,
+        bidSelector: new BidSelector({config, ledger, builderIndex: index}),
+        payloadStore,
+        envelopePublisher: new EnvelopePublisher({api, signer: builderSigner, ledger, builderIndex: index}),
+        builderIndex: index,
+        metrics: opts.metrics,
+        signal,
+      },
+      {cutoffBps: opts.reveal.cutoffBps ?? config.PAYLOAD_ATTESTATION_DUE_BPS}
+    );
 
     return new Builder({
       opts,
@@ -126,19 +220,28 @@ export class Builder {
       clock,
       index,
       payloadStore,
+      ledger,
+      bidder,
+      revealer,
     });
   }
 
   private async onSlot(slot: number): Promise<void> {
     this.payloadStore.prune(slot);
     this.proposerPreferencesTracker.prune(slot);
+    this.ledger.settlePaymentsBefore(slot - PAYMENT_SETTLEMENT_SLOTS);
+    this.ledger.prune(slot);
   }
 
   private subscribeToEvents(api: ApiClient): void {
     const signal = this.controller.signal;
     if (signal.aborted) return;
 
-    const topics = [routes.events.EventType.block, routes.events.EventType.proposerPreferences];
+    const topics = [
+      routes.events.EventType.block,
+      routes.events.EventType.proposerPreferences,
+      routes.events.EventType.payloadAttributes,
+    ];
     this.logger.verbose("Subscribing to builder events", {topics: topics.join(",")});
     api.events
       .eventstream({
@@ -209,6 +312,9 @@ export class Builder {
         case routes.events.EventType.proposerPreferences:
           this.proposerPreferencesTracker.onProposerPreferences(event.message.data);
           break;
+        case routes.events.EventType.payloadAttributes:
+          await this.bidder.onPayloadAttributes(event.message);
+          break;
       }
     } catch (error) {
       if (!signal.aborted && !isErrorAborted(error)) {