@lodestar/builder 1.48.0-dev.57c1e5614b → 1.48.0-dev.59456ca330

package/lib/services/blockObserver.js

@@ -0,0 +1,172 @@
+import { ApiError, routes } from "@lodestar/api";
+import { isForkPostGloas } from "@lodestar/params";
+import { isGloasBeaconBlock } from "@lodestar/types";
+import { TimeoutError, isErrorAborted, isFetchError, pruneSetToMax, retry, toRootHex } from "@lodestar/utils";
+const { EventType } = routes.events;
+/**
+ * Observes imported beacon blocks through the source beacon node API.
+ *
+ * Each block root is evaluated at most once while retained in the bounded seen set. Terminal failures remain consumed
+ * until normal FIFO eviction; reconnect, replay, and recovery policies are handled separately.
+ */
+export class BlockObserver {
+    config;
+    logger;
+    api;
+    fns = [];
+    seenBlockRoots = new Set();
+    retries;
+    retryDelay;
+    maxSeenBlockRoots;
+    constructor(config, logger, api, { retries = 5, retryDelay = 200, maxSeenBlockRoots = 256 } = {}) {
+        this.config = config;
+        this.logger = logger;
+        this.api = api;
+        this.retries = retries;
+        this.retryDelay = retryDelay;
+        this.maxSeenBlockRoots = maxSeenBlockRoots;
+    }
+    /**
+     * Register a block consumer. Consumers that require complete observation must register before {@link start}, because
+     * roots observed before registration remain consumed until normal FIFO eviction.
+     */
+    runOnBlock(fn) {
+        this.fns.push(fn);
+    }
+    start(signal) {
+        this.logger.info("Subscribing to block events", {
+            retries: this.retries,
+            retryDelay: this.retryDelay,
+            maxSeenBlockRoots: this.maxSeenBlockRoots,
+        });
+        this.api.events
+            .eventstream({
+            topics: [EventType.block],
+            signal,
+            onEvent: (event) => {
+                if (event.type !== EventType.block) {
+                    this.logger.debug("Ignoring unexpected beacon event", { eventType: event.type });
+                    return;
+                }
+                void this.processBlockEvent(event.message, signal);
+            },
+            onError: (error) => {
+                this.logger.error("Failed to receive block event", {}, error);
+            },
+            onClose: () => {
+                if (signal.aborted) {
+                    this.logger.debug("Closed stream for block events");
+                }
+                else {
+                    this.logger.error("Block event stream closed unexpectedly", {});
+                }
+            },
+        })
+            .catch((error) => {
+            this.logger.error("Failed to subscribe to block events", {}, error instanceof Error ? error : Error(String(error)));
+        });
+    }
+    async processBlockEvent(event, signal) {
+        try {
+            const { slot, block: blockRoot, executionOptimistic } = event;
+            if (this.seenBlockRoots.has(blockRoot)) {
+                this.logger.debug("Ignoring duplicate block event", { slot, blockRoot });
+                return;
+            }
+            this.seenBlockRoots.add(blockRoot);
+            pruneSetToMax(this.seenBlockRoots, this.maxSeenBlockRoots);
+            if (!isForkPostGloas(this.config.getForkName(slot))) {
+                this.logger.debug("Ignoring pre-Gloas block event", { slot, blockRoot });
+                return;
+            }
+            const response = await retry(async () => {
+                // TODO GLOAS: Remove this lookup once bid-selection notifications provide the required data.
+                const result = await this.api.beacon.getBlockV2({ blockId: blockRoot }, { signal });
+                result.assertOk();
+                return result;
+            }, {
+                retries: this.retries,
+                retryDelay: this.retryDelay,
+                signal,
+                shouldRetry: isRetryableBlockRetrievalError,
+                onRetry: (error, attempt) => {
+                    this.logger.debug("Retrying block retrieval", {
+                        slot,
+                        blockRoot,
+                        attempt,
+                        error: error.message,
+                    });
+                },
+            }).catch((error) => {
+                if (!isErrorAborted(error)) {
+                    this.logger.error("Failed to retrieve block referenced by block event", { slot, blockRoot }, error instanceof Error ? error : Error(String(error)));
+                }
+                return null;
+            });
+            if (response === null) {
+                return;
+            }
+            const { version } = response.meta();
+            if (!isForkPostGloas(version)) {
+                this.logger.warn("Ignoring block with unsupported fork version", { slot, blockRoot, fork: version });
+                return;
+            }
+            const block = response.value();
+            if (!isGloasBeaconBlock(block.message)) {
+                this.logger.warn("Block response version and body do not agree", { slot, blockRoot, fork: version });
+                return;
+            }
+            if (block.message.slot !== slot) {
+                this.logger.warn("Block response slot does not match block event", {
+                    slot,
+                    blockRoot,
+                    blockSlot: block.message.slot,
+                });
+                return;
+            }
+            const postGloasBlock = block;
+            const signedBid = postGloasBlock.message.body.signedExecutionPayloadBid;
+            const observedBlock = {
+                blockRoot,
+                slot,
+                executionOptimistic,
+                version,
+                block: postGloasBlock,
+                signedBid,
+            };
+            this.logger.debug("Observed post-Gloas block", {
+                slot,
+                blockRoot,
+                fork: version,
+                builderIndex: signedBid.message.builderIndex,
+                value: signedBid.message.value,
+                blockHash: toRootHex(signedBid.message.blockHash),
+                parentBlockHash: toRootHex(signedBid.message.parentBlockHash),
+            });
+            await Promise.all(this.fns.map(async (fn) => {
+                try {
+                    await fn(observedBlock);
+                }
+                catch (error) {
+                    if (isErrorAborted(error)) {
+                        return;
+                    }
+                    this.logger.error("Failed to process observed block", { slot, blockRoot }, error instanceof Error ? error : Error(String(error)));
+                }
+            }));
+        }
+        catch (error) {
+            if (isErrorAborted(error)) {
+                return;
+            }
+            this.logger.error("Failed to process block event", { slot: event.slot, blockRoot: event.block }, error instanceof Error ? error : Error(String(error)));
+        }
+    }
+}
+export function isRetryableBlockRetrievalError(error) {
+    if (error instanceof ApiError) {
+        return error.status === 404 || error.status >= 500;
+    }
+    return error instanceof TimeoutError || (isFetchError(error) && error.type !== "input");
+}
+//# sourceMappingURL=blockObserver.js.map

package/lib/services/blockObserver.js.map

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

package/lib/services/payloadStore.d.ts

@@ -0,0 +1,25 @@
+import { ForkPostGloas } from "@lodestar/params";
+import { BlobsBundle, ExecutionPayload, Root, RootHex, Slot, gloas } from "@lodestar/types";
+export type BuiltPayload = {
+    sourceId: string;
+    executionPayload: ExecutionPayload<ForkPostGloas>;
+    executionRequests: gloas.ExecutionRequests;
+    blobsBundle: BlobsBundle<ForkPostGloas>;
+    /** Value of the payload to the fee recipient in wei, as reported by the execution client */
+    executionPayloadValue: bigint;
+};
+export type StoredPayload = {
+    slot: Slot;
+    parentBlockRoot: Root;
+    blockHash: RootHex;
+    payload: BuiltPayload;
+};
+export declare class PayloadStore {
+    private readonly byBlockHash;
+    add(payload: StoredPayload): void;
+    get(blockHash: RootHex): StoredPayload | null;
+    has(blockHash: RootHex): boolean;
+    prune(currentSlot: Slot): void;
+    get size(): number;
+}
+//# sourceMappingURL=payloadStore.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"payloadStore.d.ts","sourceRoot":"","sources":["../../src/services/payloadStore.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,aAAa,EAAC,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAC,WAAW,EAAE,gBAAgB,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAC,MAAM,iBAAiB,CAAC;AAI1F,MAAM,MAAM,YAAY,GAAG;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,gBAAgB,EAAE,gBAAgB,CAAC,aAAa,CAAC,CAAC;IAClD,iBAAiB,EAAE,KAAK,CAAC,iBAAiB,CAAC;IAC3C,WAAW,EAAE,WAAW,CAAC,aAAa,CAAC,CAAC;IACxC,4FAA4F;IAC5F,qBAAqB,EAAE,MAAM,CAAC;CAC/B,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,IAAI,EAAE,IAAI,CAAC;IACX,eAAe,EAAE,IAAI,CAAC;IACtB,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,EAAE,YAAY,CAAC;CACvB,CAAC;AAKF,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAqC;IAEjE,GAAG,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI,CAEhC;IAED,GAAG,CAAC,SAAS,EAAE,OAAO,GAAG,aAAa,GAAG,IAAI,CAE5C;IAED,GAAG,CAAC,SAAS,EAAE,OAAO,GAAG,OAAO,CAE/B;IAED,KAAK,CAAC,WAAW,EAAE,IAAI,GAAG,IAAI,CAM7B;IAED,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF"}

package/lib/services/payloadStore.js

@@ -0,0 +1,25 @@
+/** Keep payloads for this many slots after their target slot, late blocks may still commit to them */
+const KEEP_SLOTS = 2;
+export class PayloadStore {
+    byBlockHash = new Map();
+    add(payload) {
+        this.byBlockHash.set(payload.blockHash, payload);
+    }
+    get(blockHash) {
+        return this.byBlockHash.get(blockHash) ?? null;
+    }
+    has(blockHash) {
+        return this.byBlockHash.has(blockHash);
+    }
+    prune(currentSlot) {
+        for (const [blockHash, { slot }] of this.byBlockHash) {
+            if (slot + KEEP_SLOTS < currentSlot) {
+                this.byBlockHash.delete(blockHash);
+            }
+        }
+    }
+    get size() {
+        return this.byBlockHash.size;
+    }
+}
+//# sourceMappingURL=payloadStore.js.map

package/lib/services/payloadStore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"payloadStore.js","sourceRoot":"","sources":["../../src/services/payloadStore.ts"],"names":[],"mappings":"AAqBA,sGAAsG;AACtG,MAAM,UAAU,GAAG,CAAC,CAAC;AAErB,MAAM,OAAO,YAAY;IACN,WAAW,GAAG,IAAI,GAAG,EAA0B,CAAC;IAEjE,GAAG,CAAC,OAAsB;QACxB,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,OAAO,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IACnD,CAAC;IAED,GAAG,CAAC,SAAkB;QACpB,OAAO,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,IAAI,CAAC;IACjD,CAAC;IAED,GAAG,CAAC,SAAkB;QACpB,OAAO,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IACzC,CAAC;IAED,KAAK,CAAC,WAAiB;QACrB,KAAK,MAAM,CAAC,SAAS,EAAE,EAAC,IAAI,EAAC,CAAC,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YACnD,IAAI,IAAI,GAAG,UAAU,GAAG,WAAW,EAAE,CAAC;gBACpC,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;YACrC,CAAC;QACH,CAAC;IACH,CAAC;IAED,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC;IAC/B,CAAC;CACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lodestar/builder",
-  "version": "1.48.0-dev.57c1e5614b",
+  "version": "1.48.0-dev.59456ca330",
   "description": "A Typescript implementation of the builder client",
   "author": "ChainSafe Systems",
   "license": "Apache-2.0",
@@ -48,16 +48,16 @@
   "dependencies": {
     "@chainsafe/lodestar-z": "catalog:",
     "@chainsafe/ssz": "^1.7.0",
-    "@lodestar/api": "^1.48.0-dev.57c1e5614b",
-    "@lodestar/config": "^1.48.0-dev.57c1e5614b",
-    "@lodestar/params": "^1.48.0-dev.57c1e5614b",
-    "@lodestar/state-transition": "^1.48.0-dev.57c1e5614b",
-    "@lodestar/types": "^1.48.0-dev.57c1e5614b",
-    "@lodestar/utils": "^1.48.0-dev.57c1e5614b"
+    "@lodestar/api": "^1.48.0-dev.59456ca330",
+    "@lodestar/config": "^1.48.0-dev.59456ca330",
+    "@lodestar/params": "^1.48.0-dev.59456ca330",
+    "@lodestar/state-transition": "^1.48.0-dev.59456ca330",
+    "@lodestar/types": "^1.48.0-dev.59456ca330",
+    "@lodestar/utils": "^1.48.0-dev.59456ca330"
   },
   "devDependencies": {
-    "@lodestar/logger": "^1.48.0-dev.57c1e5614b",
-    "@lodestar/test-utils": "^1.48.0-dev.57c1e5614b"
+    "@lodestar/logger": "^1.48.0-dev.59456ca330",
+    "@lodestar/test-utils": "^1.48.0-dev.59456ca330"
   },
-  "gitHead": "998308c37292db4af199b9d67be2a4866887da98"
+  "gitHead": "a0db83f84e4d5ea344e8a204cd14eea587d6ce66"
 }

package/src/builder.ts

@@ -7,15 +7,19 @@ import {waitForGenesis} from "./genesis.js";
 import {resolveBuilderIdentity} from "./identity.js";
 import {Metrics} from "./metrics.js";
 import {logNodeVersion, waitForNodeReady} from "./readiness.js";
+import {BlockObserver} from "./services/blockObserver.js";
 import {BuilderSigner, Keypair} from "./services/builderSigner.js";
 import {BuilderStatusTracker} from "./services/builderStatusTracker.js";
+import {PayloadStore} from "./services/payloadStore.js";
 
 export type BuilderModules = {
   opts: BuilderOptions;
   builderSigner: BuilderSigner;
+  blockObserver: BlockObserver;
   builderStatusTracker: BuilderStatusTracker;
   clock: IClock;
   index: BuilderIndex;
+  store: PayloadStore;
 };
 
 export type BuilderOptions = {
@@ -34,25 +38,31 @@ export type BuilderOptions = {
  */
 export class Builder {
   readonly builderSigner: BuilderSigner;
+  private readonly blockObserver: BlockObserver;
   private readonly builderStatusTracker: BuilderStatusTracker;
   private readonly controller: AbortController;
   private readonly clock: IClock;
   private readonly index: BuilderIndex;
   private readonly logger: Logger;
   private readonly executionFeeRecipient: ExecutionAddress;
+  private readonly store: PayloadStore;
 
-  constructor({opts, builderSigner, builderStatusTracker, clock, index}: BuilderModules) {
+  constructor({opts, builderSigner, blockObserver, builderStatusTracker, clock, index, store}: BuilderModules) {
     this.builderSigner = builderSigner;
+    this.blockObserver = blockObserver;
     this.builderStatusTracker = builderStatusTracker;
     this.clock = clock;
     this.controller = opts.abortController;
     this.logger = opts.logger;
     this.index = index;
+    this.store = store;
 
     this.executionFeeRecipient = opts.executionFeeRecipient;
 
+    this.clock.runEverySlot(async (slot) => this.onSlot(slot));
     this.clock.runEveryEpoch((epoch) => this.builderStatusTracker.poll(epoch));
     this.clock.start(this.controller.signal);
+    this.blockObserver.start(this.controller.signal);
 
     this.logger.info("Builder client initialized", {
       index: this.index,
@@ -89,8 +99,15 @@ export class Builder {
     );
 
     const builderStatusTracker = new BuilderStatusTracker(api, logger, index, opts.metrics);
+    const blockObserver = new BlockObserver(config, logger, api);
 
-    return new Builder({opts, builderSigner, builderStatusTracker, clock, index});
+    const store = new PayloadStore();
+
+    return new Builder({opts, builderSigner, blockObserver, builderStatusTracker, clock, index, store});
+  }
+
+  private async onSlot(slot: number): Promise<void> {
+    this.store.prune(slot);
   }
 
   async close(): Promise<void> {

package/src/identity.ts

@@ -1,12 +1,10 @@
 import {ApiClient, ApiError, HttpStatusCode, routes} from "@lodestar/api";
 import {ChainForkConfig} from "@lodestar/config";
 import {PAYLOAD_BUILDER_VERSION} from "@lodestar/params";
-import {IClock} from "@lodestar/state-transition";
+import {IClock, computeStartSlotAtEpoch} from "@lodestar/state-transition";
 import {BuilderIndex, BuilderStatus} from "@lodestar/types";
 import {ErrorAborted, Logger, TimeoutError, isFetchError, sleep, toHex} from "@lodestar/utils";
 
-export const WAITING_FOR_BUILDER_POLL_MS = 10 * 1000;
-
 export async function resolveBuilderIdentity(
   api: ApiClient,
   logger: Logger,
@@ -71,7 +69,7 @@ async function waitForBuilder(
         currentEpoch,
         slot: clock.getCurrentSlot(),
       });
-      await sleep(WAITING_FOR_BUILDER_POLL_MS, signal);
+      await sleep(msToNextEpochPoll(clock), signal);
       continue;
     }
 
@@ -87,7 +85,7 @@ async function waitForBuilder(
           currentEpoch,
           slot: clock.getCurrentSlot(),
         });
-        await sleep(WAITING_FOR_BUILDER_POLL_MS, signal);
+        await sleep(msToNextSlotPoll(clock), signal);
         continue;
       }
       throw e;
@@ -101,10 +99,11 @@ async function waitForBuilder(
     }
     if (builder?.status === "pending") {
       logger.info("Waiting for builder deposit to be finalized", {id, slot: clock.getCurrentSlot()});
+      await sleep(msToNextEpochPoll(clock), signal);
     } else {
       logger.info("Waiting for builder to be known to the beacon node", {id, slot: clock.getCurrentSlot()});
+      await sleep(msToNextSlotPoll(clock), signal);
     }
-    await sleep(WAITING_FOR_BUILDER_POLL_MS, signal);
   }
   throw new ErrorAborted("waitForBuilder");
 }
@@ -145,3 +144,11 @@ async function fetchBuilder(
     throw e;
   }
 }
+
+function msToNextEpochPoll(clock: IClock): number {
+  return clock.msToSlot(computeStartSlotAtEpoch(clock.getCurrentEpoch() + 1));
+}
+
+function msToNextSlotPoll(clock: IClock): number {
+  return clock.msToSlot(clock.getCurrentSlot() + 1);
+}

package/src/services/bidLedger.ts

@@ -0,0 +1,245 @@
+import {SLOTS_PER_EPOCH} from "@lodestar/params";
+import type {Epoch, RootHex, Slot} from "@lodestar/types";
+import {LodestarError} from "@lodestar/utils";
+
+export type SubmittedBid = {
+  slot: Slot;
+  parentBlockHash: RootHex;
+  parentBlockRoot: RootHex;
+  blockHash: RootHex;
+  valueGwei: number;
+  signedBidRoot: RootHex;
+};
+
+export type BidIdentity = Pick<SubmittedBid, "slot" | "parentBlockHash" | "parentBlockRoot" | "blockHash">;
+
+export type BidLedgerRecord = SubmittedBid & {
+  wonBlockRoots: RootHex[];
+};
+
+type RevealedPayload = {
+  slot: Slot;
+  blockHash: RootHex;
+  envelopeRoot: RootHex;
+  published: boolean;
+};
+
+type MutableBidLedgerRecord = SubmittedBid & {
+  wonBlockRoots: Set<RootHex>;
+  paymentSettled: boolean;
+};
+
+export enum BidLedgerErrorCode {
+  INVALID_BID_VALUE = "BID_LEDGER_ERROR_INVALID_BID_VALUE",
+  DUPLICATE_BID = "BID_LEDGER_ERROR_DUPLICATE_BID",
+  REVEAL_CONFLICT = "BID_LEDGER_ERROR_REVEAL_CONFLICT",
+  UNSETTLED_VALUE_OVERFLOW = "BID_LEDGER_ERROR_UNSETTLED_VALUE_OVERFLOW",
+}
+
+export type BidLedgerErrorType =
+  | {
+      code: BidLedgerErrorCode.INVALID_BID_VALUE;
+      valueGwei: number;
+    }
+  | {
+      code: BidLedgerErrorCode.DUPLICATE_BID;
+      slot: Slot;
+      parentBlockHash: RootHex;
+      parentBlockRoot: RootHex;
+    }
+  | {
+      code: BidLedgerErrorCode.REVEAL_CONFLICT;
+      blockRoot: RootHex;
+      blockHash: RootHex;
+      revealedBlockHash: RootHex;
+      envelopeRoot: RootHex;
+      revealedEnvelopeRoot: RootHex;
+    }
+  | {
+      code: BidLedgerErrorCode.UNSETTLED_VALUE_OVERFLOW;
+      currentEpoch: Epoch;
+    };
+
+export class BidLedgerError extends LodestarError<BidLedgerErrorType> {}
+
+const RECORD_RETENTION_EPOCHS = 3;
+const KEEP_SLOTS = RECORD_RETENTION_EPOCHS * SLOTS_PER_EPOCH;
+
+/** Tracks at most one bid per (slot, parentBlockHash, parentBlockRoot) and its reveal obligations. */
+export class BidLedger {
+  private readonly bidsBySlot = new Map<Slot, Map<string, MutableBidLedgerRecord>>();
+  private readonly revealedPayloadByBlockRoot = new Map<RootHex, RevealedPayload>();
+
+  hasSubmitted(slot: Slot, parentBlockHash: RootHex, parentBlockRoot: RootHex): boolean {
+    return this.bidsBySlot.get(slot)?.has(tupleKey(parentBlockHash, parentBlockRoot)) ?? false;
+  }
+
+  recordBid(bid: SubmittedBid): BidLedgerRecord {
+    if (!Number.isSafeInteger(bid.valueGwei) || bid.valueGwei < 0) {
+      throw new BidLedgerError(
+        {code: BidLedgerErrorCode.INVALID_BID_VALUE, valueGwei: bid.valueGwei},
+        `Invalid bid value valueGwei=${bid.valueGwei}`
+      );
+    }
+
+    let bidsForSlot = this.bidsBySlot.get(bid.slot);
+    if (bidsForSlot === undefined) {
+      bidsForSlot = new Map();
+      this.bidsBySlot.set(bid.slot, bidsForSlot);
+    }
+
+    const key = tupleKey(bid.parentBlockHash, bid.parentBlockRoot);
+    if (bidsForSlot.has(key)) {
+      throw new BidLedgerError(
+        {
+          code: BidLedgerErrorCode.DUPLICATE_BID,
+          slot: bid.slot,
+          parentBlockHash: bid.parentBlockHash,
+          parentBlockRoot: bid.parentBlockRoot,
+        },
+        `Bid already recorded slot=${bid.slot} parentBlockHash=${bid.parentBlockHash} parentBlockRoot=${bid.parentBlockRoot}`
+      );
+    }
+
+    const record = {...bid, wonBlockRoots: new Set<RootHex>(), paymentSettled: false};
+    bidsForSlot.set(key, record);
+    return toRecord(record);
+  }
+
+  recordWin(identity: BidIdentity & Pick<SubmittedBid, "signedBidRoot">, blockRoot: RootHex): BidLedgerRecord | null {
+    const record = this.getBid(identity.slot, identity.parentBlockHash, identity.parentBlockRoot);
+    if (record === null || record.blockHash !== identity.blockHash || record.signedBidRoot !== identity.signedBidRoot) {
+      return null;
+    }
+
+    record.wonBlockRoots.add(blockRoot);
+    return toRecord(record);
+  }
+
+  /** 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);
+    if (record === null || record.blockHash !== identity.blockHash || record.wonBlockRoots.size === 0) {
+      return null;
+    }
+
+    record.paymentSettled = true;
+    return toRecord(record);
+  }
+
+  canReveal(blockRoot: RootHex, blockHash: RootHex, envelopeRoot: RootHex): boolean {
+    const revealedPayload = this.revealedPayloadByBlockRoot.get(blockRoot);
+    return (
+      revealedPayload === undefined ||
+      (revealedPayload.blockHash === blockHash && revealedPayload.envelopeRoot === envelopeRoot)
+    );
+  }
+
+  hasRevealed(blockRoot: RootHex): boolean {
+    return this.revealedPayloadByBlockRoot.has(blockRoot);
+  }
+
+  hasPublishedReveal(blockRoot: RootHex): boolean {
+    return this.revealedPayloadByBlockRoot.get(blockRoot)?.published ?? false;
+  }
+
+  recordReveal(slot: Slot, blockRoot: RootHex, blockHash: RootHex, envelopeRoot: RootHex): void {
+    const revealedPayload = this.revealedPayloadByBlockRoot.get(blockRoot);
+    if (revealedPayload !== undefined) {
+      if (revealedPayload.blockHash !== blockHash || revealedPayload.envelopeRoot !== envelopeRoot) {
+        throw new BidLedgerError(
+          {
+            code: BidLedgerErrorCode.REVEAL_CONFLICT,
+            blockRoot,
+            blockHash,
+            revealedBlockHash: revealedPayload.blockHash,
+            envelopeRoot,
+            revealedEnvelopeRoot: revealedPayload.envelopeRoot,
+          },
+          `Different envelope already recorded blockRoot=${blockRoot} envelopeRoot=${revealedPayload.envelopeRoot}`
+        );
+      }
+      return;
+    }
+
+    this.revealedPayloadByBlockRoot.set(blockRoot, {slot, blockHash, envelopeRoot, published: false});
+  }
+
+  recordRevealPublished(slot: Slot, blockRoot: RootHex, blockHash: RootHex, envelopeRoot: RootHex): void {
+    this.recordReveal(slot, blockRoot, blockHash, envelopeRoot);
+    const revealedPayload = this.revealedPayloadByBlockRoot.get(blockRoot);
+    if (revealedPayload !== undefined) {
+      revealedPayload.published = true;
+    }
+  }
+
+  getUnsettledValueGwei(currentEpoch: Epoch): number {
+    let total = 0;
+    for (const bidsForSlot of this.bidsBySlot.values()) {
+      for (const record of bidsForSlot.values()) {
+        if (record.wonBlockRoots.size === 0 || record.paymentSettled) {
+          continue;
+        }
+
+        total += record.valueGwei;
+        if (!Number.isSafeInteger(total)) {
+          throw new BidLedgerError(
+            {code: BidLedgerErrorCode.UNSETTLED_VALUE_OVERFLOW, currentEpoch},
+            `Unsettled bid value exceeds the safe integer range currentEpoch=${currentEpoch}`
+          );
+        }
+      }
+    }
+    return total;
+  }
+
+  getBidsForSlot(slot: Slot): BidLedgerRecord[] {
+    return Array.from(this.bidsBySlot.get(slot)?.values() ?? [], toRecord);
+  }
+
+  prune(currentSlot: Slot): number {
+    let removed = 0;
+    for (const [slot, bidsForSlot] of this.bidsBySlot) {
+      if (slot >= currentSlot - KEEP_SLOTS) {
+        continue;
+      }
+
+      for (const [key, record] of bidsForSlot) {
+        if (record.wonBlockRoots.size === 0 || record.paymentSettled) {
+          bidsForSlot.delete(key);
+          removed++;
+        }
+      }
+      if (bidsForSlot.size === 0) {
+        this.bidsBySlot.delete(slot);
+      }
+    }
+
+    for (const [blockRoot, revealedPayload] of this.revealedPayloadByBlockRoot) {
+      if (revealedPayload.slot < currentSlot - KEEP_SLOTS) {
+        this.revealedPayloadByBlockRoot.delete(blockRoot);
+      }
+    }
+    return removed;
+  }
+
+  private getBid(slot: Slot, parentBlockHash: RootHex, parentBlockRoot: RootHex): MutableBidLedgerRecord | null {
+    return this.bidsBySlot.get(slot)?.get(tupleKey(parentBlockHash, parentBlockRoot)) ?? null;
+  }
+}
+
+function tupleKey(parentBlockHash: RootHex, parentBlockRoot: RootHex): string {
+  return `${parentBlockHash}:${parentBlockRoot}`;
+}
+
+function toRecord(record: MutableBidLedgerRecord): BidLedgerRecord {
+  return {
+    slot: record.slot,
+    parentBlockHash: record.parentBlockHash,
+    parentBlockRoot: record.parentBlockRoot,
+    blockHash: record.blockHash,
+    valueGwei: record.valueGwei,
+    signedBidRoot: record.signedBidRoot,
+    wonBlockRoots: Array.from(record.wonBlockRoots),
+  };
+}