@lodestar/beacon-node 1.47.0-dev.f591cb177e → 1.48.0-dev.67344272c0

package/lib/chain/validation/voluntaryExit.js

@@ -1,9 +1,54 @@
 import { VoluntaryExitValidity, getVoluntaryExitSignatureSet } from "@lodestar/state-transition";
 import { GossipAction, VoluntaryExitError, VoluntaryExitErrorCode, voluntaryExitValidityToErrorCode, } from "../errors/index.js";
 import { RegenCaller } from "../regen/index.js";
+// 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) {
+    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, voluntaryExit) {
     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(chain, voluntaryExit) {
     return validateVoluntaryExit(chain, voluntaryExit);

package/lib/chain/validation/voluntaryExit.js.map

@@ -1 +1 @@
-{"version":3,"file":"voluntaryExit.js","sourceRoot":"","sources":["../../../src/chain/validation/voluntaryExit.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,qBAAqB,EAAE,4BAA4B,EAAC,MAAM,4BAA4B,CAAC;AAE/F,OAAO,EACL,YAAY,EACZ,kBAAkB,EAClB,sBAAsB,EACtB,gCAAgC,GACjC,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAC,WAAW,EAAC,MAAM,mBAAmB,CAAC;AAE9C,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAC5C,KAAmB,EACnB,aAAyC;IAEzC,MAAM,aAAa,GAAG,IAAI,CAAC;IAC3B,OAAO,qBAAqB,CAAC,KAAK,EAAE,aAAa,EAAE,aAAa,CAAC,CAAC;AACpE,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,2BAA2B,CAC/C,KAAmB,EACnB,aAAyC;IAEzC,OAAO,qBAAqB,CAAC,KAAK,EAAE,aAAa,CAAC,CAAC;AACrD,CAAC;AAED,KAAK,UAAU,qBAAqB,CAClC,KAAmB,EACnB,aAAyC,EACzC,aAAa,GAAG,KAAK;IAErB,sGAAsG;IACtG,iDAAiD;IACjD,IAAI,KAAK,CAAC,MAAM,CAAC,oBAAoB,CAAC,aAAa,CAAC,OAAO,CAAC,cAAc,CAAC,EAAE,CAAC;QAC5E,MAAM,IAAI,kBAAkB,CAAC,YAAY,CAAC,MAAM,EAAE;YAChD,IAAI,EAAE,sBAAsB,CAAC,cAAc;SAC5C,CAAC,CAAC;IACL,CAAC;IAED,wDAAwD;IACxD,EAAE;IACF,gFAAgF;IAChF,6DAA6D;IAC7D,sGAAsG;IACtG,kGAAkG;IAClG,6CAA6C;IAC7C,MAAM,KAAK,GAAG,MAAM,KAAK,CAAC,0BAA0B,CAAC,WAAW,CAAC,2BAA2B,CAAC,CAAC;IAE9F,gFAAgF;IAChF,mDAAmD;IACnD,MAAM,QAAQ,GAAG,KAAK,CAAC,wBAAwB,CAAC,aAAa,EAAE,KAAK,CAAC,CAAC;IACtE,IAAI,QAAQ,KAAK,qBAAqB,CAAC,KAAK,EAAE,CAAC;QAC7C,MAAM,IAAI,kBAAkB,CAAC,YAAY,CAAC,MAAM,EAAE;YAChD,IAAI,EAAE,gCAAgC,CAAC,QAAQ,CAAC;SACjD,CAAC,CAAC;IACL,CAAC;IAED,MAAM,YAAY,GAAG,4BAA4B,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,EAAE,aAAa,CAAC,CAAC;IACtF,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,GAAG,CAAC,mBAAmB,CAAC,CAAC,YAAY,CAAC,EAAE,EAAC,SAAS,EAAE,IAAI,EAAE,QAAQ,EAAE,aAAa,EAAC,CAAC,CAAC,EAAE,CAAC;QACvG,MAAM,IAAI,kBAAkB,CAAC,YAAY,CAAC,MAAM,EAAE;YAChD,IAAI,EAAE,sBAAsB,CAAC,iBAAiB;SAC/C,CAAC,CAAC;IACL,CAAC;AACH,CAAC"}
+{"version":3,"file":"voluntaryExit.js","sourceRoot":"","sources":["../../../src/chain/validation/voluntaryExit.ts"],"names":[],"mappings":"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"}

package/lib/execution/builder/apiClient.d.ts

@@ -0,0 +1,70 @@
+import { routes } from "@lodestar/api";
+import { ChainForkConfig } from "@lodestar/config";
+import { Logger } from "@lodestar/logger";
+import { ForkPostGloas } from "@lodestar/params";
+import { BLSPubkey, Root, SignedBeaconBlock, Slot, WithOptionalBytes, gloas } from "@lodestar/types";
+import type { IBlsVerifier } from "../../chain/bls/index.js";
+import { Metrics } from "../../metrics/metrics.js";
+import { IClock } from "../../util/clock.js";
+/**
+ * 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 declare const BUILDER_BID_DEADLINE_MS = 500;
+/** Local timeout for bid requests, event loop lag must not discard bids that arrived in time */
+export declare const BUILDER_BID_REQUEST_TIMEOUT_MS: number;
+export type BuilderApiClientOpts = {
+    /** Timeout for builder api requests, bid requests always use `BUILDER_BID_REQUEST_TIMEOUT_MS` */
+    timeout?: number;
+    userAgent?: string;
+};
+type BuilderUrl = string;
+/** Decode the SSZ URL bytes without allowing replacement characters or unsafe header values. */
+export declare function decodeBuilderUrl(value: Uint8Array): BuilderUrl;
+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 declare class BuilderApiClient {
+    private readonly opts;
+    private readonly config;
+    private readonly clock;
+    private readonly bls;
+    private readonly metrics;
+    private readonly logger?;
+    private readonly clients;
+    constructor(opts: BuilderApiClientOpts, config: ChainForkConfig, clock: IClock, bls: IBlsVerifier, metrics?: Metrics | null, logger?: Logger | undefined);
+    /**
+     * 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.
+     */
+    getExecutionPayloadBids(entries: routes.validator.BuilderEntry[], slot: Slot, parentHash: Root, parentRoot: Root, proposerPubkey: BLSPubkey): Promise<BuilderApiBid[]>;
+    /** Forward a proposer's builder preferences to the builder at the given url */
+    submitBuilderPreferences(url: BuilderUrl, proposerPubkey: BLSPubkey, request: gloas.BuilderPreferencesRequest): Promise<void>;
+    /**
+     * 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.
+     */
+    submitSignedBeaconBlock(url: BuilderUrl, signedBlock: WithOptionalBytes<SignedBeaconBlock<ForkPostGloas>>): Promise<void>;
+    /**
+     * Establish the connection to every known builder outside the bid deadline, a cold TCP/TLS handshake
+     * to a distant builder can exhaust `BUILDER_BID_DEADLINE_MS` on its own, and a long idle connection
+     * may be half-open and only fail once written to.
+     */
+    checkStatus(): Promise<void>;
+    private getOrCreateClient;
+}
+export {};
+//# sourceMappingURL=apiClient.d.ts.map

package/lib/execution/builder/apiClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apiClient.d.ts","sourceRoot":"","sources":["../../../src/execution/builder/apiClient.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,MAAM,EAAC,MAAM,eAAe,CAAC;AAErC,OAAO,EAAC,eAAe,EAAC,MAAM,kBAAkB,CAAC;AACjD,OAAO,EAAC,MAAM,EAAC,MAAM,kBAAkB,CAAC;AACxC,OAAO,EAA8B,aAAa,EAAC,MAAM,kBAAkB,CAAC;AAO5E,OAAO,EAAC,SAAS,EAAE,IAAI,EAAE,iBAAiB,EAAE,IAAI,EAAE,iBAAiB,EAAE,KAAK,EAAM,MAAM,iBAAiB,CAAC;AAExG,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,0BAA0B,CAAC;AAC3D,OAAO,EAAC,OAAO,EAAC,MAAM,0BAA0B,CAAC;AACjD,OAAO,EAAC,MAAM,EAAC,MAAM,qBAAqB,CAAC;AAQ3C;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,MAAM,CAAC;AAE3C,gGAAgG;AAChG,eAAO,MAAM,8BAA8B,QAAkD,CAAC;AAE9F,MAAM,MAAM,oBAAoB,GAAG;IACjC,iGAAiG;IACjG,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,KAAK,UAAU,GAAG,MAAM,CAAC;AAEzB,gGAAgG;AAChG,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,UAAU,GAAG,UAAU,CAW9D;AAED,MAAM,MAAM,aAAa,GAAG;IAC1B,GAAG,EAAE,UAAU,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC,SAAS,CAAC,YAAY,CAAC;IACrC,SAAS,EAAE,KAAK,CAAC,yBAAyB,CAAC;IAC3C,yEAAyE;IACzE,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF;;;;;GAKG;AACH,qBAAa,gBAAgB;IAIzB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;IAR1B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqC;IAE7D,YACmB,IAAI,EAAE,oBAAoB,EAC1B,MAAM,EAAE,eAAe,EACvB,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,YAAY,EACjB,OAAO,GAAE,OAAO,GAAG,IAAW,EAC9B,MAAM,CAAC,EAAE,MAAM,YAAA,EAC9B;IAEJ;;;;OAIG;IACG,uBAAuB,CAC3B,OAAO,EAAE,MAAM,CAAC,SAAS,CAAC,YAAY,EAAE,EACxC,IAAI,EAAE,IAAI,EACV,UAAU,EAAE,IAAI,EAChB,UAAU,EAAE,IAAI,EAChB,cAAc,EAAE,SAAS,GACxB,OAAO,CAAC,aAAa,EAAE,CAAC,CAmE1B;IAED,+EAA+E;IACzE,wBAAwB,CAC5B,GAAG,EAAE,UAAU,EACf,cAAc,EAAE,SAAS,EACzB,OAAO,EAAE,KAAK,CAAC,yBAAyB,GACvC,OAAO,CAAC,IAAI,CAAC,CASf;IAED;;;;OAIG;IACG,uBAAuB,CAC3B,GAAG,EAAE,UAAU,EACf,WAAW,EAAE,iBAAiB,CAAC,iBAAiB,CAAC,aAAa,CAAC,CAAC,GAC/D,OAAO,CAAC,IAAI,CAAC,CAef;IAED;;;;OAIG;IACG,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,CAajC;YAEa,iBAAiB;CAwChC"}

package/lib/execution/builder/apiClient.js

@@ -0,0 +1,202 @@
+import { getClient } from "@lodestar/api/builder";
+import { DOMAIN_BUILDER_REQUEST_AUTH } from "@lodestar/params";
+import { ZERO_HASH, computeDomain, computeSigningRoot, createSingleSignatureSetFromComponents, } from "@lodestar/state-transition";
+import { ssz } from "@lodestar/types";
+import { isValidAsciiHttpUrl, toHex, toPrintableUrl } from "@lodestar/utils";
+/**
+ * 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;
+/** Decode the SSZ URL bytes without allowing replacement characters or unsafe header values. */
+export function decodeBuilderUrl(value) {
+    let url;
+    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;
+}
+/**
+ * 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 {
+    opts;
+    config;
+    clock;
+    bls;
+    metrics;
+    logger;
+    clients = new Map();
+    constructor(opts, config, clock, bls, metrics = null, logger) {
+        this.opts = opts;
+        this.config = config;
+        this.clock = clock;
+        this.bls = bls;
+        this.metrics = metrics;
+        this.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, slot, parentHash, parentRoot, proposerPubkey) {
+        const seenRequests = new Set();
+        const requests = [];
+        for (const entry of entries) {
+            const urlForLog = Buffer.from(entry.url).toString("utf8");
+            let url;
+            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 = [];
+        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);
+            }
+        }));
+        return bids;
+    }
+    /** Forward a proposer's builder preferences to the builder at the given url */
+    async submitBuilderPreferences(url, proposerPubkey, request) {
+        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, signedBlock) {
+        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;
+        }
+    }
+    /**
+     * Establish the connection to every known builder outside the bid deadline, a cold TCP/TLS handshake
+     * to a distant builder can exhaust `BUILDER_BID_DEADLINE_MS` on its own, and a long idle connection
+     * may be half-open and only fail once written to.
+     */
+    async checkStatus() {
+        await Promise.all(Array.from(this.clients.entries()).map(async ([url, client]) => {
+            try {
+                (await client.status()).assertOk();
+                this.metrics?.builderApi.statusChecks.inc({ status: "success" });
+                this.logger?.debug("Builder is ready", { builder: toPrintableUrl(url) });
+            }
+            catch (e) {
+                this.metrics?.builderApi.statusChecks.inc({ status: "error" });
+                this.logger?.warn("Builder status check failed", { builder: toPrintableUrl(url) }, e);
+            }
+        }));
+    }
+    async getOrCreateClient(url, proposerPubkey, auth) {
+        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;
+    }
+}
+//# sourceMappingURL=apiClient.js.map

package/lib/execution/builder/apiClient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"apiClient.js","sourceRoot":"","sources":["../../../src/execution/builder/apiClient.ts"],"names":[],"mappings":"AACA,OAAO,EAA0B,SAAS,EAAC,MAAM,uBAAuB,CAAC;AAGzE,OAAO,EAAC,2BAA2B,EAAgB,MAAM,kBAAkB,CAAC;AAC5E,OAAO,EACL,SAAS,EACT,aAAa,EACb,kBAAkB,EAClB,sCAAsC,GACvC,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAqE,GAAG,EAAC,MAAM,iBAAiB,CAAC;AACxG,OAAO,EAAC,mBAAmB,EAAE,KAAK,EAAE,cAAc,EAAC,MAAM,iBAAiB,CAAC;AAK3E;;;GAGG;AACH,MAAM,qBAAqB,GAAG,GAAG,CAAC;AAElC;;;;GAIG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,GAAG,CAAC;AAE3C,gGAAgG;AAChG,MAAM,CAAC,MAAM,8BAA8B,GAAG,uBAAuB,GAAG,qBAAqB,CAAC;AAW9F,gGAAgG;AAChG,MAAM,UAAU,gBAAgB,CAAC,KAAiB;IAChD,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,IAAI,WAAW,CAAC,MAAM,EAAE,EAAC,KAAK,EAAE,IAAI,EAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC7D,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,KAAK,CAAC,iCAAiC,CAAC,CAAC;IACjD,CAAC;IACD,IAAI,CAAC,mBAAmB,CAAC,GAAG,CAAC,EAAE,CAAC;QAC9B,MAAM,KAAK,CAAC,qBAAqB,CAAC,CAAC;IACrC,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAUD;;;;;GAKG;AACH,MAAM,OAAO,gBAAgB;IAIR,IAAI;IACJ,MAAM;IACN,KAAK;IACL,GAAG;IACH,OAAO;IACP,MAAM;IARR,OAAO,GAAG,IAAI,GAAG,EAA0B,CAAC;IAE7D,YACmB,IAA0B,EAC1B,MAAuB,EACvB,KAAa,EACb,GAAiB,EACjB,OAAO,GAAmB,IAAI,EAC9B,MAAe;oBALf,IAAI;sBACJ,MAAM;qBACN,KAAK;mBACL,GAAG;uBACH,OAAO;sBACP,MAAM;IACtB,CAAC;IAEJ;;;;OAIG;IACH,KAAK,CAAC,uBAAuB,CAC3B,OAAwC,EACxC,IAAU,EACV,UAAgB,EAChB,UAAgB,EAChB,cAAyB;QAEzB,MAAM,YAAY,GAAG,IAAI,GAAG,EAAU,CAAC;QACvC,MAAM,QAAQ,GAA8D,EAAE,CAAC;QAE/E,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;YAC5B,MAAM,SAAS,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;YAC1D,IAAI,GAAe,CAAC;YACpB,IAAI,CAAC;gBACH,GAAG,GAAG,gBAAgB,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;YACpC,CAAC;YAAC,MAAM,CAAC;gBACP,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,yCAAyC,EAAE,EAAC,IAAI,EAAE,GAAG,EAAE,SAAS,EAAC,CAAC,CAAC;gBACrF,SAAS;YACX,CAAC;YAED,MAAM,UAAU,GAAG,GAAG,GAAG,IAAI,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;YAC9D,IAAI,YAAY,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,CAAC;gBACjC,SAAS;YACX,CAAC;YACD,YAAY,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;YAE7B,iGAAiG;YACjG,IAAI,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,KAAK,IAAI,EAAE,CAAC;gBACrC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,qDAAqD,EAAE;oBACvE,IAAI;oBACJ,QAAQ,EAAE,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI;oBACjC,OAAO,EAAE,cAAc,CAAC,GAAG,CAAC;iBAC7B,CAAC,CAAC;gBACH,SAAS;YACX,CAAC;YAED,QAAQ,CAAC,IAAI,CAAC,EAAC,GAAG,EAAE,KAAK,EAAC,CAAC,CAAC;QAC9B,CAAC;QAED,2FAA2F;QAC3F,MAAM,IAAI,GAAoB,EAAE,CAAC;QACjC,MAAM,OAAO,CAAC,GAAG,CACf,QAAQ,CAAC,GAAG,CAAC,KAAK,EAAE,EAAC,GAAG,EAAE,KAAK,EAAC,EAAE,EAAE;YAClC,IAAI,CAAC,OAAO,EAAE,UAAU,CAAC,WAAW,CAAC,GAAG,EAAE,CAAC;YAC3C,IAAI,CAAC;gBACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,iBAAiB,CAAC,GAAG,EAAE,cAAc,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;gBAC7E,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,sBAAsB,CAC7C;oBACE,IAAI;oBACJ,UAAU;oBACV,UAAU;oBACV,cAAc;oBACd,WAAW,EAAE,KAAK,CAAC,IAAI;oBACvB,gBAAgB,EAAE,IAAI,CAAC,GAAG,EAAE;oBAC5B,SAAS,EAAE,uBAAuB;iBACnC,EACD,EAAC,SAAS,EAAE,8BAA8B,EAAC,CAC5C,CAAC;gBACF,MAAM,SAAS,GAAG,GAAG,CAAC,KAAK,EAAE,CAAC;gBAC9B,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;oBAC5B,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,8BAA8B,EAAE,EAAC,IAAI,EAAE,OAAO,EAAE,cAAc,CAAC,GAAG,CAAC,EAAC,CAAC,CAAC;oBACzF,OAAO;gBACT,CAAC;gBACD,IAAI,CAAC,OAAO,EAAE,UAAU,CAAC,YAAY,CAAC,GAAG,EAAE,CAAC;gBAC5C,IAAI,CAAC,IAAI,CAAC,EAAC,GAAG,EAAE,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,EAAC,CAAC,CAAC;YAC9E,CAAC;YAAC,OAAO,CAAC,EAAE,CAAC;gBACX,IAAI,CAAC,OAAO,EAAE,UAAU,CAAC,gBAAgB,CAAC,GAAG,EAAE,CAAC;gBAChD,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,gCAAgC,EAAE,EAAC,IAAI,EAAE,OAAO,EAAE,cAAc,CAAC,GAAG,CAAC,EAAC,EAAE,CAAU,CAAC,CAAC;YACxG,CAAC;QACH,CAAC,CAAC,CACH,CAAC;QAEF,OAAO,IAAI,CAAC;IACd,CAAC;IAED,+EAA+E;IAC/E,KAAK,CAAC,wBAAwB,CAC5B,GAAe,EACf,cAAyB,EACzB,OAAwC;QAExC,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,iBAAiB,CAAC,GAAG,EAAE,cAAc,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;YAC/E,CAAC,MAAM,MAAM,CAAC,wBAAwB,CAAC,EAAC,cAAc,EAAE,OAAO,EAAC,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC;YAC9E,IAAI,CAAC,OAAO,EAAE,UAAU,CAAC,oBAAoB,CAAC,GAAG,CAAC,EAAC,MAAM,EAAE,SAAS,EAAC,CAAC,CAAC;QACzE,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,IAAI,CAAC,OAAO,EAAE,UAAU,CAAC,oBAAoB,CAAC,GAAG,CAAC,EAAC,MAAM,EAAE,OAAO,EAAC,CAAC,CAAC;YACrE,MAAM,CAAC,CAAC;QACV,CAAC;IACH,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,uBAAuB,CAC3B,GAAe,EACf,WAAgE;QAEhE,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACrC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACzB,IAAI,CAAC,OAAO,EAAE,UAAU,CAAC,gBAAgB,CAAC,GAAG,CAAC,EAAC,MAAM,EAAE,OAAO,EAAC,CAAC,CAAC;YACjE,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,6DAA6D,EAAE,EAAC,GAAG,EAAC,CAAC,CAAC;YACxF,OAAO;QACT,CAAC;QAED,IAAI,CAAC;YACH,CAAC,MAAM,MAAM,CAAC,uBAAuB,CAAC,EAAC,WAAW,EAAC,EAAE,EAAC,QAAQ,EAAE,QAAQ,EAAC,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC;YACvF,IAAI,CAAC,OAAO,EAAE,UAAU,CAAC,gBAAgB,CAAC,GAAG,CAAC,EAAC,MAAM,EAAE,SAAS,EAAC,CAAC,CAAC;QACrE,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,IAAI,CAAC,OAAO,EAAE,UAAU,CAAC,gBAAgB,CAAC,GAAG,CAAC,EAAC,MAAM,EAAE,OAAO,EAAC,CAAC,CAAC;YACjE,MAAM,CAAC,CAAC;QACV,CAAC;IACH,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,WAAW;QACf,MAAM,OAAO,CAAC,GAAG,CACf,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,CAAC,EAAE,EAAE;YAC7D,IAAI,CAAC;gBACH,CAAC,MAAM,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC;gBACnC,IAAI,CAAC,OAAO,EAAE,UAAU,CAAC,YAAY,CAAC,GAAG,CAAC,EAAC,MAAM,EAAE,SAAS,EAAC,CAAC,CAAC;gBAC/D,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,kBAAkB,EAAE,EAAC,OAAO,EAAE,cAAc,CAAC,GAAG,CAAC,EAAC,CAAC,CAAC;YACzE,CAAC;YAAC,OAAO,CAAC,EAAE,CAAC;gBACX,IAAI,CAAC,OAAO,EAAE,UAAU,CAAC,YAAY,CAAC,GAAG,CAAC,EAAC,MAAM,EAAE,OAAO,EAAC,CAAC,CAAC;gBAC7D,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,6BAA6B,EAAE,EAAC,OAAO,EAAE,cAAc,CAAC,GAAG,CAAC,EAAC,EAAE,CAAU,CAAC,CAAC;YAC/F,CAAC;QACH,CAAC,CAAC,CACH,CAAC;IACJ,CAAC;IAEO,KAAK,CAAC,iBAAiB,CAC7B,GAAe,EACf,cAAyB,EACzB,IAAoC;QAEpC,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACnC,MAAM,KAAK,CAAC,6CAA6C,CAAC,CAAC;QAC7D,CAAC;QAED,IAAI,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACnC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACzB,MAAM,MAAM,GAAG,aAAa,CAAC,2BAA2B,EAAE,IAAI,CAAC,MAAM,CAAC,oBAAoB,EAAE,SAAS,CAAC,CAAC;YACvG,MAAM,WAAW,GAAG,kBAAkB,CAAC,GAAG,CAAC,KAAK,CAAC,kBAAkB,EAAE,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;YAC3F,MAAM,YAAY,GAAG,sCAAsC,CAAC,cAAc,EAAE,WAAW,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;YAEzG,IAAI,OAAO,GAAG,KAAK,CAAC;YACpB,IAAI,CAAC;gBACH,OAAO,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,mBAAmB,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC;YAC/D,CAAC;YAAC,MAAM,CAAC;gBACP,2DAA2D;YAC7D,CAAC;YACD,IAAI,CAAC,OAAO,EAAE,CAAC;gBACb,MAAM,KAAK,CAAC,8BAA8B,CAAC,CAAC;YAC9C,CAAC;YAED,MAAM,GAAG,SAAS,CAChB;gBACE,OAAO,EAAE,GAAG;gBACZ,UAAU,EAAE;oBACV,SAAS,EAAE,IAAI,CAAC,IAAI,CAAC,OAAO;oBAC5B,OAAO,EAAE,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,EAAC,YAAY,EAAE,IAAI,CAAC,IAAI,CAAC,SAAS,EAAC,CAAC,CAAC,CAAC,SAAS;iBAC/E;aACF,EACD,EAAC,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,iBAAiB,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAC,CACrF,CAAC;YACF,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;YAC9B,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,6BAA6B,EAAE,EAAC,GAAG,EAAE,cAAc,CAAC,GAAG,CAAC,EAAC,CAAC,CAAC;QAChF,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;CACF"}

package/lib/execution/builder/validateBid.d.ts

@@ -0,0 +1,23 @@
+import { routes } from "@lodestar/api";
+import { ProtoBlock } from "@lodestar/fork-choice";
+import { RootHex, Slot, gloas } from "@lodestar/types";
+import { IBeaconChain } from "../../chain/index.js";
+/** Return the counted bid payment in Gwei, saturated at uint64 max. */
+export declare function getBuilderBidTotalGwei(bid: gloas.ExecutionPayloadBid, maxExecutionPayment: bigint): bigint;
+/**
+ * Validate a bid received from a builder over the builder API in response to a bid request
+ * made during block production. Unlike gossip validation, the bid must match the requested
+ * slot and parent exactly, may carry a non-zero `executionPayment` which is counted at most at
+ * the entry's `maxExecutionPayment`, and is not subject to gossip anti-spam rules.
+ *
+ * Throws with a description of the failure, the caller drops the bid.
+ */
+export declare function validateBuilderApiExecutionPayloadBid(chain: IBeaconChain, signedExecutionPayloadBid: gloas.SignedExecutionPayloadBid, request: {
+    slot: Slot;
+    parentBlock: ProtoBlock;
+    parentBlockHash: RootHex;
+    parentBlockRoot: RootHex;
+    entry: routes.validator.BuilderEntry;
+    getParentExecutionRequests: () => Promise<gloas.ExecutionRequests>;
+}): Promise<void>;
+//# sourceMappingURL=validateBid.d.ts.map

package/lib/execution/builder/validateBid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validateBid.d.ts","sourceRoot":"","sources":["../../../src/execution/builder/validateBid.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,MAAM,EAAC,MAAM,eAAe,CAAC;AACrC,OAAO,EAAC,UAAU,EAAC,MAAM,uBAAuB,CAAC;AAUjD,OAAO,EAAC,OAAO,EAAE,IAAI,EAAE,KAAK,EAAC,MAAM,iBAAiB,CAAC;AAErD,OAAO,EAAC,YAAY,EAAC,MAAM,sBAAsB,CAAC;AAIlD,uEAAuE;AACvE,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,KAAK,CAAC,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,GAAG,MAAM,CAE1G;AAED;;;;;;;GAOG;AACH,wBAAsB,qCAAqC,CACzD,KAAK,EAAE,YAAY,EACnB,yBAAyB,EAAE,KAAK,CAAC,yBAAyB,EAC1D,OAAO,EAAE;IACP,IAAI,EAAE,IAAI,CAAC;IACX,WAAW,EAAE,UAAU,CAAC;IACxB,eAAe,EAAE,OAAO,CAAC;IACzB,eAAe,EAAE,OAAO,CAAC;IACzB,KAAK,EAAE,MAAM,CAAC,SAAS,CAAC,YAAY,CAAC;IACrC,0BAA0B,EAAE,MAAM,OAAO,CAAC,KAAK,CAAC,iBAAiB,CAAC,CAAC;CACpE,GACA,OAAO,CAAC,IAAI,CAAC,CA2If"}

package/lib/execution/builder/validateBid.js

@@ -0,0 +1,119 @@
+import { MAX_EXECUTION_PAYMENT, PAYLOAD_BUILDER_VERSION } from "@lodestar/params";
+import { computeEpochAtSlot, createSingleSignatureSetFromComponents, getExecutionPayloadBidSigningRoot, isActiveBuilder, isGasLimitTargetCompatible, isStatePostGloas, } from "@lodestar/state-transition";
+import { bigIntMin, byteArrayEquals, prettyGweiToEth, toHex, toRootHex } from "@lodestar/utils";
+import { RegenCaller } from "../../chain/regen/index.js";
+import { getShufflingDependentRoot } from "../../util/dependentRoot.js";
+/** Return the counted bid payment in Gwei, saturated at uint64 max. */
+export function getBuilderBidTotalGwei(bid, maxExecutionPayment) {
+    return bigIntMin(MAX_EXECUTION_PAYMENT, BigInt(bid.value) + bigIntMin(bid.executionPayment, maxExecutionPayment));
+}
+/**
+ * Validate a bid received from a builder over the builder API in response to a bid request
+ * made during block production. Unlike gossip validation, the bid must match the requested
+ * slot and parent exactly, may carry a non-zero `executionPayment` which is counted at most at
+ * the entry's `maxExecutionPayment`, and is not subject to gossip anti-spam rules.
+ *
+ * Throws with a description of the failure, the caller drops the bid.
+ */
+export async function validateBuilderApiExecutionPayloadBid(chain, signedExecutionPayloadBid, request) {
+    const bid = signedExecutionPayloadBid.message;
+    const { slot, parentBlock, parentBlockHash, parentBlockRoot, entry, getParentExecutionRequests } = request;
+    if (bid.slot !== slot) {
+        throw Error(`Bid slot=${bid.slot} does not match requested slot=${slot}`);
+    }
+    const bidParentBlockHash = toRootHex(bid.parentBlockHash);
+    const bidParentBlockRoot = toRootHex(bid.parentBlockRoot);
+    if (bidParentBlockHash !== parentBlockHash || bidParentBlockRoot !== parentBlockRoot) {
+        throw Error(`Bid parent parentBlockHash=${bidParentBlockHash} parentBlockRoot=${bidParentBlockRoot} does not match ` +
+            `requested parentBlockHash=${parentBlockHash} parentBlockRoot=${parentBlockRoot}`);
+    }
+    const totalPayment = getBuilderBidTotalGwei(bid, entry.maxExecutionPayment);
+    if (totalPayment < entry.minBid) {
+        throw Error(`Bid total payment=${prettyGweiToEth(totalPayment)} ` +
+            `(value=${prettyGweiToEth(bid.value)} ` +
+            `executionPayment=${prettyGweiToEth(bid.executionPayment)}) ` +
+            `is below minBid=${prettyGweiToEth(entry.minBid)}`);
+    }
+    const state = await chain.regen
+        .getBlockSlotState(parentBlock, slot, { dontTransferCache: true }, RegenCaller.validateGossipExecutionPayloadBid)
+        .catch((e) => {
+        throw Error(`Unable to regenerate state to validate bid: ${e.message}`);
+    });
+    if (!isStatePostGloas(state)) {
+        throw Error(`Expected gloas+ state for execution payload bid validation, got fork=${state.forkName}`);
+    }
+    if (bid.builderIndex >= state.getBuildersLength()) {
+        throw Error(`Bid builderIndex=${bid.builderIndex} is out of bounds`);
+    }
+    const builder = state.getBuilder(bid.builderIndex);
+    if (!isActiveBuilder(builder, state.finalizedCheckpoint.epoch)) {
+        throw Error(`Bid builderIndex=${bid.builderIndex} is not an active builder`);
+    }
+    if (builder.version !== PAYLOAD_BUILDER_VERSION) {
+        throw Error(`Invalid builder version=${builder.version} expected=${PAYLOAD_BUILDER_VERSION}`);
+    }
+    // A bid not signed by one of the builder pubkeys the entry accepts bids from must not be accepted
+    if (entry.builderPubkeys.length > 0 &&
+        !entry.builderPubkeys.some((pubkey) => byteArrayEquals(pubkey, builder.pubkey))) {
+        throw Error(`Bid builder pubkey=${toHex(builder.pubkey)} is not in the entry's ` +
+            `builderPubkeys=${entry.builderPubkeys.map(toHex).join(",")}`);
+    }
+    const blobKzgCommitmentsLen = bid.blobKzgCommitments.length;
+    const maxBlobsPerBlock = chain.config.getMaxBlobsPerBlock(computeEpochAtSlot(bid.slot));
+    if (blobKzgCommitmentsLen > maxBlobsPerBlock) {
+        throw Error(`Bid has too many KZG commitments len=${blobKzgCommitmentsLen} limit=${maxBlobsPerBlock}`);
+    }
+    // The coverage check only applies to the staked collateral payment, a pure execution
+    // layer payment bid has nothing to cover on-chain
+    if (bid.value > 0 && !state.canBuilderCoverBid(bid.builderIndex, bid.value)) {
+        throw Error(`Builder cannot cover bid value=${prettyGweiToEth(bid.value)} ` + `balance=${prettyGweiToEth(builder.balance)}`);
+    }
+    const randaoMix = state.getRandaoMix(computeEpochAtSlot(state.slot));
+    if (!byteArrayEquals(bid.prevRandao, randaoMix)) {
+        throw Error(`Invalid bid prevRandao=${toHex(bid.prevRandao)} expected=${toHex(randaoMix)}`);
+    }
+    // The parent's payload does not try to exit the builder
+    if (byteArrayEquals(bid.parentBlockHash, state.latestExecutionPayloadBid.blockHash)) {
+        const requests = await getParentExecutionRequests();
+        if (requests.builderExits.some((request) => byteArrayEquals(request.pubkey, builder.pubkey) &&
+            byteArrayEquals(request.sourceAddress, builder.executionAddress))) {
+            throw Error(`Bid builderIndex=${bid.builderIndex} may exit in the parent payload`);
+        }
+    }
+    // The builder must honor the proposer preferences it learned over gossip
+    const bidEpoch = computeEpochAtSlot(bid.slot);
+    const dependentRootHex = (() => {
+        try {
+            return getShufflingDependentRoot(chain.forkChoice, bidEpoch, computeEpochAtSlot(parentBlock.slot), parentBlock);
+        }
+        catch {
+            return null;
+        }
+    })();
+    if (dependentRootHex === null) {
+        throw Error(`Unable to resolve proposer preferences dependent root for bid slot=${bid.slot}`);
+    }
+    const proposerPreferences = chain.proposerPreferencesPool.get(bid.slot, dependentRootHex);
+    if (proposerPreferences === null) {
+        throw Error(`No proposer preferences found for bid slot=${bid.slot} dependentRoot=${dependentRootHex}`);
+    }
+    if (!byteArrayEquals(bid.feeRecipient, proposerPreferences.message.feeRecipient)) {
+        throw Error(`Bid feeRecipient=${toHex(bid.feeRecipient)} does not match ` +
+            `proposer preferences feeRecipient=${toHex(proposerPreferences.message.feeRecipient)}`);
+    }
+    const parentPayloadVariant = chain.forkChoice.getBlockHexAndBlockHash(bidParentBlockRoot, bidParentBlockHash);
+    if (parentPayloadVariant === null || parentPayloadVariant.executionPayloadBlockHash === null) {
+        throw Error(`Unable to resolve parent payload gas limit for bid parentBlockHash=${bidParentBlockHash}`);
+    }
+    const parentGasLimit = BigInt(parentPayloadVariant.executionPayloadGasLimit);
+    const targetGasLimit = proposerPreferences.message.targetGasLimit;
+    if (!isGasLimitTargetCompatible(parentGasLimit, bid.gasLimit, targetGasLimit)) {
+        throw Error(`Bid gasLimit=${bid.gasLimit} is not compatible with ` +
+            `parentGasLimit=${parentGasLimit} targetGasLimit=${targetGasLimit}`);
+    }
+    const signatureSet = createSingleSignatureSetFromComponents(builder.pubkey, getExecutionPayloadBidSigningRoot(chain.config, bid), signedExecutionPayloadBid.signature);
+    if (!(await chain.bls.verifySignatureSets([signatureSet]))) {
+        throw Error(`Invalid bid signature builderIndex=${bid.builderIndex}`);
+    }
+}
+//# sourceMappingURL=validateBid.js.map

package/lib/execution/builder/validateBid.js.map

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