@lodestar/beacon-node 1.51.0-dev.837363b869 → 1.51.0-dev.83aae9f53e

package/src/db/repositories/dataColumnSidecarArchive.ts

@@ -15,6 +15,8 @@ const SLOT_BYTE_SIZE = 8;
  * Indexed data by `slot` + `columnIndex`
  */
 export class DataColumnSidecarArchiveRepository extends PrefixedRepository<Slot, ColumnIndex, DataColumnSidecar> {
+  private prunedBeforeSlot: Slot | null = null;
+
   constructor(config: ChainForkConfig, db: Db) {
     const bucket = Bucket.allForks_dataColumnSidecarsArchive;
     // Type won't be used since we select it dynamically based on fork
@@ -70,4 +72,22 @@ export class DataColumnSidecarArchiveRepository extends PrefixedRepository<Slot,
       encodeNumberForDbKey(0, COLUMN_INDEX_BYTE_SIZE),
     ]);
   }
+
+  /**
+   * Deletes all entries before `slot`. Prunes only delete from the start of the bucket, so the first prune
+   * compacts the range to drop tombstones of earlier runs and later prunes resume where the previous one ended.
+   */
+  async pruneBefore(slot: Slot): Promise<Slot[]> {
+    if (this.prunedBeforeSlot === null) {
+      await this.db.compactRange(this.wrapKey(this.getMinKeyRaw(0)), this.wrapKey(this.getMinKeyRaw(slot)));
+    } else if (slot <= this.prunedBeforeSlot) {
+      return [];
+    }
+
+    const keys = await this.keys({gte: {prefix: this.prunedBeforeSlot ?? 0, id: 0}, lt: {prefix: slot, id: 0}});
+    const slots = [...new Set(keys.map(({prefix}) => prefix))];
+    if (slots.length > 0) await this.deleteMany(slots);
+    this.prunedBeforeSlot = slot;
+    return slots;
+  }
 }

package/src/execution/builder/apiClient.ts

@@ -19,21 +19,20 @@ import {IClock} from "../../util/clock.js";
  * Additional duration to account for potential event loop lag which causes
  * builder bids to be rejected even though the response was sent in time.
  */
-const EVENT_LOOP_LAG_BUFFER = 250;
+export const BUILDER_BID_LAG_BUFFER_MS = 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.
+ * Default 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. Bids received via
+ * p2p are given the same time to bid up.
  */
-export const BUILDER_BID_DEADLINE_MS = 500;
-
-/** Local timeout for bid requests, event loop lag must not discard bids that arrived in time */
-export const BUILDER_BID_REQUEST_TIMEOUT_MS = BUILDER_BID_DEADLINE_MS + EVENT_LOOP_LAG_BUFFER;
+export const DEFAULT_BUILDER_BID_DEADLINE_MS = 500;
 
 export type BuilderApiClientOpts = {
-  /** Timeout for builder api requests, bid requests always use `BUILDER_BID_REQUEST_TIMEOUT_MS` */
+  /** Timeout for builder api requests, bid requests are bounded by `bidDeadline` instead */
   timeout?: number;
+  /** Time builders are given to provide a bid once block production starts, in milliseconds */
+  bidDeadline?: number;
   // Add User-Agent header to all requests
   userAgent?: string;
 };
@@ -69,6 +68,7 @@ export type BuilderApiBid = {
  * each block production request, clients are dialed on demand based on the entry `url`.
  */
 export class BuilderApiClient {
+  readonly bidDeadline: number;
   private readonly clients = new Map<BuilderUrl, BuilderApi>();
 
   constructor(
@@ -78,7 +78,9 @@ export class BuilderApiClient {
     private readonly bls: IBlsVerifier,
     private readonly metrics: Metrics | null = null,
     private readonly logger?: Logger
-  ) {}
+  ) {
+    this.bidDeadline = opts.bidDeadline ?? DEFAULT_BUILDER_BID_DEADLINE_MS;
+  }
 
   /**
    * Fan out bid requests to the builders named by the entries, one request per unique
@@ -139,9 +141,10 @@ export class BuilderApiClient {
               proposerPubkey,
               requestAuth: entry.auth,
               dateMilliseconds: Date.now(),
-              timeoutMs: BUILDER_BID_DEADLINE_MS,
+              timeoutMs: this.bidDeadline,
             },
-            {timeoutMs: BUILDER_BID_REQUEST_TIMEOUT_MS}
+            // Event loop lag must not discard bids that arrived in time
+            {timeoutMs: this.bidDeadline + BUILDER_BID_LAG_BUFFER_MS}
           );
           const signedBid = res.value();
           if (signedBid === undefined) {
@@ -203,7 +206,7 @@ export class BuilderApiClient {
 
   /**
    * 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
+   * to a distant builder can exhaust the bid deadline on its own, and a long idle connection
    * may be half-open and only fail once written to.
    */
   async checkStatus(): Promise<void> {

package/src/execution/builder/http.ts

@@ -20,6 +20,7 @@ import {
 } from "@lodestar/types";
 import {toPrintableUrl} from "@lodestar/utils";
 import {Metrics} from "../../metrics/metrics.js";
+import {DEFAULT_BUILDER_BID_DEADLINE_MS} from "./apiClient.js";
 import {ValidatorRegistration, ValidatorRegistrationCache} from "./cache.js";
 import {IExecutionBuilder} from "./interface.js";
 
@@ -29,6 +30,8 @@ export type ExecutionBuilderHttpOpts = {
   timeout?: number;
   faultInspectionWindow?: number;
   allowedFaults?: number;
+  /** Post-gloas only, time builders are given to provide a bid once block production starts, in milliseconds */
+  bidDeadline?: number;
 
   // Only required for merge-mock runs, no need to expose it to cli
   issueLocalFcUWithFeeRecipient?: string;
@@ -40,6 +43,7 @@ export const defaultExecutionBuilderHttpOpts: ExecutionBuilderHttpOpts = {
   enabled: false,
   url: "http://localhost:8661",
   timeout: 12000,
+  bidDeadline: DEFAULT_BUILDER_BID_DEADLINE_MS,
 };
 
 export enum BuilderStatus {

package/src/execution/builder/validateBid.ts

@@ -1,6 +1,6 @@
 import {routes} from "@lodestar/api";
 import {ProtoBlock} from "@lodestar/fork-choice";
-import {MAX_EXECUTION_PAYMENT, PAYLOAD_BUILDER_VERSION} from "@lodestar/params";
+import {MAX_EXECUTION_PAYMENT, PAYLOAD_BUILDER_VERSION, isForkPostHeze} from "@lodestar/params";
 import {
   computeEpochAtSlot,
   createSingleSignatureSetFromComponents,
@@ -9,7 +9,7 @@ import {
   isGasLimitTargetCompatible,
   isStatePostGloas,
 } from "@lodestar/state-transition";
-import {RootHex, Slot, gloas} from "@lodestar/types";
+import {RootHex, Slot, gloas, heze} from "@lodestar/types";
 import {bigIntMin, byteArrayEquals, prettyGweiToEth, toHex, toRootHex} from "@lodestar/utils";
 import {IBeaconChain} from "../../chain/index.js";
 import {RegenCaller} from "../../chain/regen/index.js";
@@ -41,6 +41,7 @@ export async function validateBuilderApiExecutionPayloadBid(
   }
 ): Promise<void> {
   const bid = signedExecutionPayloadBid.message;
+  const fork = chain.config.getForkName(bid.slot);
   const {slot, parentBlock, parentBlockHash, parentBlockRoot, entry, getParentExecutionRequests} = request;
 
   if (bid.slot !== slot) {
@@ -76,6 +77,26 @@ export async function validateBuilderApiExecutionPayloadBid(
     );
   }
 
+  // Same check as bid gossip (only_timely=True), not the proposer's full view from validator.md: a list released
+  // after the deadline would void every bid, and a high bid that went stale after gossip could crowd out the rest unpaid
+  if (isForkPostHeze(fork)) {
+    const {inclusionListBits} = bid as heze.ExecutionPayloadBid;
+    const inclusionListSlot = bid.slot - 1;
+    const dependentRoot = getShufflingDependentRoot(
+      chain.forkChoice,
+      computeEpochAtSlot(inclusionListSlot),
+      computeEpochAtSlot(parentBlock.slot),
+      parentBlock
+    );
+    if (!chain.inclusionListStore.isInclusionListBitsInclusive(inclusionListSlot, dependentRoot, inclusionListBits)) {
+      const expectedBits = chain.inclusionListStore.getInclusionListBits(inclusionListSlot, dependentRoot);
+      throw Error(
+        `Bid inclusionListBits=${toHex(inclusionListBits.uint8Array)} is not inclusive of ` +
+          `timely inclusion lists expected=${toHex(expectedBits.uint8Array)}`
+      );
+    }
+  }
+
   const state = await chain.regen
     .getBlockSlotState(parentBlock, slot, {dontTransferCache: true}, RegenCaller.validateGossipExecutionPayloadBid)
     .catch((e: Error) => {

package/src/execution/engine/blobVersionedHashes.ts

@@ -7,7 +7,7 @@ import {VersionedHashes} from "./interface.js";
  * Skip unrelated fields without decoding or copying them, including untrusted nested access lists.
  * The EL remains responsible for the other transaction validity checks.
  */
-export function isValidBlobVersionedHashes(transactions: Uint8Array[], expected: VersionedHashes): boolean {
+export function isValidBlobVersionedHashes(transactions: Iterable<Uint8Array>, expected: VersionedHashes): boolean {
   let index = 0;
   for (const transaction of transactions) {
     if (transaction.length === 0) return false;

package/src/execution/engine/disabled.ts

@@ -28,4 +28,8 @@ export class ExecutionEngineDisabled implements IExecutionEngine {
   getBlobs(): Promise<never> {
     throw Error("Execution engine disabled");
   }
+
+  getInclusionList(): Promise<never> {
+    throw Error("Execution engine disabled");
+  }
 }

package/src/execution/engine/http.ts

@@ -8,7 +8,7 @@ import {
   isForkPostBellatrix,
   isForkPostFulu,
 } from "@lodestar/params";
-import {BlobsBundle, ExecutionPayload, ExecutionRequests, Root, RootHex, Wei} from "@lodestar/types";
+import {BlobsBundle, ExecutionPayload, ExecutionRequests, Root, RootHex, Wei, bellatrix} from "@lodestar/types";
 import {BlobAndProof} from "@lodestar/types/deneb";
 import {BlobAndProofV2} from "@lodestar/types/fulu";
 import {isErrorAborted} from "@lodestar/utils";
@@ -224,9 +224,13 @@ export class ExecutionEngineHttp implements IExecutionEngine {
     executionPayload: ExecutionPayload,
     versionedHashes?: VersionedHashes,
     parentBlockRoot?: Root,
-    executionRequests?: ExecutionRequests
+    executionRequests?: ExecutionRequests,
+    inclusionListTransactions?: bellatrix.Transactions
   ): Promise<ExecutePayloadResponse> {
     // Validate before queueing, argument errors must not be reported as an unavailable execution client
+    if (ForkSeq[fork] >= ForkSeq.heze && inclusionListTransactions === undefined) {
+      throw Error(`inclusionListTransactions required in notifyNewPayload for fork=${fork}`);
+    }
     if (ForkSeq[fork] >= ForkSeq.deneb) {
       if (versionedHashes === undefined) {
         throw Error(`versionedHashes required in notifyNewPayload for fork=${fork}`);
@@ -243,7 +247,14 @@ export class ExecutionEngineHttp implements IExecutionEngine {
     try {
       result = await this.enqueue(() =>
         this.withTransport(fork, undefined, (transport) =>
-          transport.newPayload(fork, executionPayload, versionedHashes, parentBlockRoot, executionRequests)
+          transport.newPayload(
+            fork,
+            executionPayload,
+            versionedHashes,
+            parentBlockRoot,
+            executionRequests,
+            inclusionListTransactions
+          )
         )
       );
     } catch (e) {
@@ -264,7 +275,12 @@ export class ExecutionEngineHttp implements IExecutionEngine {
 
     switch (status) {
       case ExecutionPayloadStatus.VALID:
-        return {status, latestValidHash: latestValidHash ?? "0x0", validationError: null};
+        return {
+          status,
+          latestValidHash: latestValidHash ?? "0x0",
+          validationError: null,
+          inclusionListSatisfied: result.inclusionListSatisfied ?? null,
+        };
 
       case ExecutionPayloadStatus.INVALID:
         // As per latest specs if latestValidHash can be null and it would mean only
@@ -348,7 +364,14 @@ export class ExecutionEngineHttp implements IExecutionEngine {
           }
 
           const payloadAttributesRpc = serializePayloadAttributes(payloadAttributes);
-          this.payloadIdCache.add({headBlockHash, finalizedBlockHash, ...payloadAttributesRpc}, payloadId);
+          this.payloadIdCache.add(
+            {
+              headBlockHash,
+              ...payloadAttributesRpc,
+              inclusionListTransactions: payloadAttributes.inclusionListTransactions,
+            },
+            payloadId
+          );
           void this.prunePayloadIdCache();
         }
         return payloadId;
@@ -423,6 +446,18 @@ export class ExecutionEngineHttp implements IExecutionEngine {
     return this.withTransport(undefined, "v1", (transport) => transport.getBlobsV1(versionedHashes));
   }
 
+  /**
+   * `engine_getInclusionListV1`, JSON-RPC only as the REST engine API defines no inclusion list route.
+   * Queued so it runs after the forkchoiceUpdated of a payload imported just before, which prunes that
+   * payload's transactions from the mempool the list is built from.
+   */
+  async getInclusionList(): Promise<bellatrix.Transactions> {
+    return this.enqueue(() => {
+      this.metrics?.engineApiRequests.inc({transport: "json-rpc"});
+      return this.jsonRpc.getInclusionList();
+    });
+  }
+
   private enqueue<T>(job: () => Promise<T>): Promise<T> {
     return this.queue.push(job) as Promise<T>;
   }

package/src/execution/engine/index.ts

@@ -17,8 +17,8 @@ import {EngineRestHttpClient} from "./restHttpClient.js";
 import {RestEngineTransport, formatClientVersionHeader} from "./restTransport.js";
 import {ExecutionEngineMockJsonRpcClient, JsonRpcBackend} from "./utils.js";
 
-export {ExecutionEngineHttp, ExecutionEngineDisabled, defaultExecutionEngineHttpOpts, engineApiModes};
 export type {EngineApiMode};
+export {ExecutionEngineDisabled, ExecutionEngineHttp, defaultExecutionEngineHttpOpts, engineApiModes};
 
 export type ExecutionEngineOpts =
   | ({mode?: "http"} & ExecutionEngineHttpOpts)

package/src/execution/engine/interface.ts

@@ -9,14 +9,23 @@ import {
   ForkPreFulu,
   WITHDRAWAL_REQUEST_TYPE,
 } from "@lodestar/params";
-import {BlobsBundle, ExecutionPayload, ExecutionRequests, Root, RootHex, Wei, capella} from "@lodestar/types";
+import {
+  BlobsBundle,
+  ExecutionPayload,
+  ExecutionRequests,
+  Root,
+  RootHex,
+  Wei,
+  bellatrix,
+  capella,
+} from "@lodestar/types";
 import {BlobAndProof} from "@lodestar/types/deneb";
 import {BlobAndProofV2} from "@lodestar/types/fulu";
 import {PayloadId, PayloadIdCache, WithdrawalV1} from "./payloadIdCache.js";
 import {ExecutionPayloadBodyV2} from "./types.js";
 import {DATA} from "./utils.js";
 
-export {PayloadIdCache, type PayloadId, type WithdrawalV1};
+export {type PayloadId, PayloadIdCache, type WithdrawalV1};
 export type ClientVersion = routes.node.ClientVersion;
 export const ClientCode = routes.node.ClientCode;
 
@@ -73,7 +82,13 @@ export type ExecutePayloadResponse =
       latestValidHash: null;
       validationError: null;
     }
-  | {status: ExecutionPayloadStatus.VALID; latestValidHash: RootHex; validationError: null}
+  | {
+      status: ExecutionPayloadStatus.VALID;
+      latestValidHash: RootHex;
+      validationError: null;
+      /** PayloadStatusV2: whether the payload satisfied the inclusion list constraints */
+      inclusionListSatisfied?: boolean | null;
+    }
   | {status: ExecutionPayloadStatus.INVALID; latestValidHash: RootHex | null; validationError: string | null}
   | {
       status:
@@ -99,6 +114,8 @@ export type PayloadAttributes = {
   parentBeaconBlockRoot?: Uint8Array;
   slotNumber?: number; // EIP-7843
   targetGasLimit?: bigint; // GLOAS (PayloadAttributesV4, execution-apis#796)
+  /** Transactions the built payload must include (PayloadAttributesV5, HEZE:EIP-7805) */
+  inclusionListTransactions?: bellatrix.Transactions;
 };
 
 export type VersionedHashes = Uint8Array[];
@@ -129,9 +146,16 @@ export interface IExecutionEngine {
     executionPayload: ExecutionPayload,
     versionedHashes?: VersionedHashes,
     parentBeaconBlockRoot?: Root,
-    executionRequests?: ExecutionRequests
+    executionRequests?: ExecutionRequests,
+    inclusionListTransactions?: bellatrix.Transactions
   ): Promise<ExecutePayloadResponse>;
 
+  /**
+   * Transactions the execution layer wants included in the next payload. Parameterless since
+   * execution-apis#609: the execution layer builds against its own view of the head.
+   */
+  getInclusionList(): Promise<bellatrix.Transactions>;
+
   /**
    * Signal fork choice updates
    * This function performs two actions atomically:

package/src/execution/engine/jsonRpcTransport.ts

@@ -1,5 +1,5 @@
 import {ForkName, ForkSeq} from "@lodestar/params";
-import {ExecutionPayload, ExecutionRequests, Root, RootHex} from "@lodestar/types";
+import {ExecutionPayload, ExecutionRequests, Root, RootHex, bellatrix} from "@lodestar/types";
 import {BlobAndProof} from "@lodestar/types/deneb";
 import {BlobAndProofV2} from "@lodestar/types/fulu";
 import {strip0xPrefix} from "@lodestar/utils";
@@ -16,10 +16,12 @@ import {
   deserializeBlobAndProofsV2,
   deserializeBlobAndProofsV2IntoBytes,
   deserializeExecutionPayloadBodyV2,
+  deserializeInclusionList,
   parseExecutionPayload,
   serializeBeaconBlockRoot,
   serializeExecutionPayload,
   serializeExecutionRequests,
+  serializeInclusionList,
   serializePayloadAttributes,
   serializeVersionedHashes,
 } from "./types.js";
@@ -40,6 +42,7 @@ const getPayloadBodiesByHashOpts: ReqOpts = {routeId: "getPayloadBodiesByHash"};
 const getBlobsV1Opts: ReqOpts = {routeId: "getBlobsV1"};
 const getBlobsV2Opts: ReqOpts = {routeId: "getBlobsV2"};
 const getClientVersionOpts: ReqOpts = {routeId: "getClientVersion"};
+const getInclusionListOpts: ReqOpts = {routeId: "getInclusionList"};
 
 /**
  * Legacy `engine_*` JSON-RPC methods
@@ -57,7 +60,8 @@ export class JsonRpcEngineTransport implements IEngineTransport {
     executionPayload: ExecutionPayload,
     versionedHashes?: VersionedHashes,
     parentBeaconBlockRoot?: Root,
-    executionRequests?: ExecutionRequests
+    executionRequests?: ExecutionRequests,
+    inclusionListTransactions?: bellatrix.Transactions
   ): Promise<PayloadStatusResult> {
     const serializedExecutionPayload = serializeExecutionPayload(fork, executionPayload);
 
@@ -76,6 +80,28 @@ export class JsonRpcEngineTransport implements IEngineTransport {
         if (executionRequests === undefined) {
           throw Error(`executionRequests required in notifyNewPayload for fork=${fork}`);
         }
+        if (ForkSeq[fork] >= ForkSeq.heze) {
+          if (inclusionListTransactions === undefined) {
+            throw Error(`inclusionListTransactions required in notifyNewPayload for fork=${fork}`);
+          }
+          const method = "engine_newPayloadV6";
+          return this.rpc.fetchWithRetries<
+            EngineApiRpcReturnTypes[typeof method],
+            EngineApiRpcParamTypes[typeof method]
+          >(
+            {
+              method,
+              params: [
+                serializedExecutionPayload,
+                serializedVersionedHashes,
+                serializedParentBeaconBlockRoot,
+                serializeExecutionRequests(fork, executionRequests),
+                serializeInclusionList(inclusionListTransactions),
+              ],
+            },
+            notifyNewPayloadOpts
+          );
+        }
         const method = ForkSeq[fork] >= ForkSeq.gloas ? "engine_newPayloadV5" : "engine_newPayloadV4";
         return this.rpc.fetchWithRetries<EngineApiRpcReturnTypes[typeof method], EngineApiRpcParamTypes[typeof method]>(
           {
@@ -113,13 +139,15 @@ export class JsonRpcEngineTransport implements IEngineTransport {
     payloadAttributes?: PayloadAttributes
   ): Promise<ForkchoiceUpdatedResult> {
     const method =
-      ForkSeq[fork] >= ForkSeq.gloas
-        ? "engine_forkchoiceUpdatedV4"
-        : ForkSeq[fork] >= ForkSeq.deneb
-          ? "engine_forkchoiceUpdatedV3"
-          : ForkSeq[fork] >= ForkSeq.capella
-            ? "engine_forkchoiceUpdatedV2"
-            : "engine_forkchoiceUpdatedV1";
+      ForkSeq[fork] >= ForkSeq.heze
+        ? "engine_forkchoiceUpdatedV5"
+        : ForkSeq[fork] >= ForkSeq.gloas
+          ? "engine_forkchoiceUpdatedV4"
+          : ForkSeq[fork] >= ForkSeq.deneb
+            ? "engine_forkchoiceUpdatedV3"
+            : ForkSeq[fork] >= ForkSeq.capella
+              ? "engine_forkchoiceUpdatedV2"
+              : "engine_forkchoiceUpdatedV1";
     const payloadAttributesRpc = payloadAttributes ? serializePayloadAttributes(payloadAttributes) : undefined;
     // If we are just fcUing and not asking execution for payload, retry is not required
     // and we can move on, as the next fcU will be issued soon on the new slot
@@ -244,4 +272,13 @@ export class JsonRpcEngineTransport implements IEngineTransport {
       return {code, name: cv.name, version: cv.version, commit: strip0xPrefix(cv.commit)};
     });
   }
+
+  async getInclusionList(): Promise<bellatrix.Transactions> {
+    const method = "engine_getInclusionListV1";
+    const response = await this.rpc.fetchWithRetries<
+      EngineApiRpcReturnTypes[typeof method],
+      EngineApiRpcParamTypes[typeof method]
+    >({method, params: []}, getInclusionListOpts);
+    return deserializeInclusionList(response);
+  }
 }

package/src/execution/engine/mock.ts

@@ -1,4 +1,5 @@
 import crypto from "node:crypto";
+import {SerializedList} from "@chainsafe/ssz";
 import {ChainConfig} from "@lodestar/config";
 import {
   BLOB_TX_TYPE,
@@ -137,10 +138,12 @@ export class ExecutionEngineMockBackend implements JsonRpcBackend {
       engine_newPayloadV3: this.notifyNewPayload.bind(this),
       engine_newPayloadV4: this.notifyNewPayload.bind(this),
       engine_newPayloadV5: this.notifyNewPayload.bind(this),
+      engine_newPayloadV6: this.notifyNewPayload.bind(this),
       engine_forkchoiceUpdatedV1: this.notifyForkchoiceUpdate.bind(this),
       engine_forkchoiceUpdatedV2: this.notifyForkchoiceUpdate.bind(this),
       engine_forkchoiceUpdatedV3: this.notifyForkchoiceUpdate.bind(this),
       engine_forkchoiceUpdatedV4: this.notifyForkchoiceUpdate.bind(this),
+      engine_forkchoiceUpdatedV5: this.notifyForkchoiceUpdate.bind(this),
       engine_getPayloadV1: this.getPayloadV1.bind(this),
       engine_getPayloadV2: this.getPayloadV5.bind(this),
       engine_getPayloadV3: this.getPayloadV5.bind(this),
@@ -151,6 +154,7 @@ export class ExecutionEngineMockBackend implements JsonRpcBackend {
       engine_getClientVersionV1: this.getClientVersionV1.bind(this),
       engine_getBlobsV1: this.getBlobs.bind(this),
       engine_getBlobsV2: this.getBlobsV2.bind(this),
+      engine_getInclusionListV1: this.getInclusionList.bind(this),
     };
   }
 
@@ -234,7 +238,13 @@ export class ExecutionEngineMockBackend implements JsonRpcBackend {
     // IF the payload has been fully validated while processing the call
     // RETURN payload status from the Payload validation process
     // If validation succeeds, the response MUST contain {status: VALID, latestValidHash: payload.blockHash}
-    return {status: ExecutionPayloadStatus.VALID, latestValidHash: blockHash, validationError: null};
+    // The mock does not check inclusion list constraints, so every payload satisfies them (PayloadStatusV2)
+    return {
+      status: ExecutionPayloadStatus.VALID,
+      latestValidHash: blockHash,
+      validationError: null,
+      inclusionListSatisfied: true,
+    };
   }
 
   /**
@@ -343,14 +353,14 @@ export class ExecutionEngineMockBackend implements JsonRpcBackend {
       executionPayload.gasUsed = Math.floor(0.5 * INTEROP_GAS_LIMIT);
       executionPayload.timestamp = payloadAttributes.timestamp;
       executionPayload.blockHash = crypto.randomBytes(32);
-      executionPayload.transactions = [];
+      const transactions: Uint8Array[] = [];
 
       // Between 0 and 4 transactions for all forks
       const eip1559TxCount = Math.round(4 * Math.random());
       for (let i = 0; i < eip1559TxCount; i++) {
         const tx = crypto.randomBytes(512);
         tx[0] = TX_TYPE_EIP1559;
-        executionPayload.transactions.push(tx);
+        transactions.push(tx);
       }
 
       const commitments: deneb.KZGCommitment[] = [];
@@ -364,7 +374,7 @@ export class ExecutionEngineMockBackend implements JsonRpcBackend {
           const blob = generateRandomBlob();
           const commitment = kzg.blobToKzgCommitment(blob);
           const {proofs: cellProofs} = kzg.computeCellsAndKzgProofs(blob);
-          executionPayload.transactions.push(transactionForKzgCommitment(commitment));
+          transactions.push(transactionForKzgCommitment(commitment));
           commitments.push(commitment);
           blobs.push(blob);
           proofs.push(...cellProofs);
@@ -376,12 +386,13 @@ export class ExecutionEngineMockBackend implements JsonRpcBackend {
           const blob = generateRandomBlob();
           const commitment = kzg.blobToKzgCommitment(blob);
           const proof = kzg.computeBlobKzgProof(blob, commitment);
-          executionPayload.transactions.push(transactionForKzgCommitment(commitment));
+          transactions.push(transactionForKzgCommitment(commitment));
           commitments.push(commitment);
           blobs.push(blob);
           proofs.push(proof);
         }
       }
+      executionPayload.transactions = SerializedList.fromArray(transactions);
 
       if (ForkSeq[fork] >= ForkSeq.capella) {
         (executionPayload as ExecutionPayload<ForkPostCapella>).withdrawals = ssz.capella.Withdrawals.defaultValue();
@@ -409,7 +420,12 @@ export class ExecutionEngineMockBackend implements JsonRpcBackend {
       // IF the payload is deemed VALID and the build process has begun
       // {payloadStatus: {status: VALID, latestValidHash: forkchoiceState.headBlockHash, validationError: null}, payloadId: buildProcessId}
       return {
-        payloadStatus: {status: ExecutionPayloadStatus.VALID, latestValidHash: null, validationError: null},
+        payloadStatus: {
+          status: ExecutionPayloadStatus.VALID,
+          latestValidHash: null,
+          validationError: null,
+          inclusionListSatisfied: true,
+        },
         payloadId: String(payloadId as number),
       };
     }
@@ -418,7 +434,12 @@ export class ExecutionEngineMockBackend implements JsonRpcBackend {
     // IF the payload is deemed VALID and a build process hasn't been started
     // {payloadStatus: {status: VALID, latestValidHash: forkchoiceState.headBlockHash, validationError: null}, payloadId: null}
     return {
-      payloadStatus: {status: ExecutionPayloadStatus.VALID, latestValidHash: null, validationError: null},
+      payloadStatus: {
+        status: ExecutionPayloadStatus.VALID,
+        latestValidHash: null,
+        validationError: null,
+        inclusionListSatisfied: true,
+      },
       payloadId: null,
     };
   }
@@ -487,6 +508,10 @@ export class ExecutionEngineMockBackend implements JsonRpcBackend {
     return null;
   }
 
+  private getInclusionList(): EngineApiRpcReturnTypes["engine_getInclusionListV1"] {
+    return [];
+  }
+
   private timestampToFork(timestamp: number): ForkPostBellatrix {
     if (timestamp >= this.gloasForkTimestamp) return ForkName.gloas;
     if (timestamp >= this.fuluForkTimestamp) return ForkName.fulu;

package/src/execution/engine/payloadIdCache.ts

@@ -1,4 +1,6 @@
+import {byteArrayEquals} from "@chainsafe/ssz";
 import {SLOTS_PER_EPOCH} from "@lodestar/params";
+import {bellatrix} from "@lodestar/types";
 import {pruneSetToMax} from "@lodestar/utils";
 import {PayloadAttributesRpc} from "./types.js";
 import {DATA, QUANTITY} from "./utils.js";
@@ -17,13 +19,18 @@ export type WithdrawalV1 = {
   amount: QUANTITY;
 };
 
-type FcuAttributes = {headBlockHash: DATA; finalizedBlockHash: DATA} & Omit<PayloadAttributesRpc, "withdrawals">;
+type FcuAttributes = {headBlockHash: DATA} & Omit<PayloadAttributesRpc, "withdrawals" | "inclusionListTransactions"> & {
+    inclusionListTransactions?: bellatrix.Transactions;
+  };
 
 export class PayloadIdCache {
-  private readonly payloadIdByFcuAttributes = new Map<string, {payloadId: PayloadId; fullKey: string}>();
+  private readonly payloadIdByFcuAttributes = new Map<
+    string,
+    {payloadId: PayloadId; fullKey: string; inclusionListTransactions?: bellatrix.Transactions}
+  >();
 
-  getFullKey({headBlockHash, finalizedBlockHash, timestamp, prevRandao, suggestedFeeRecipient}: FcuAttributes): string {
-    return `${headBlockHash}-${finalizedBlockHash}-${timestamp}-${prevRandao}-${suggestedFeeRecipient}`;
+  getFullKey({headBlockHash, timestamp, prevRandao, suggestedFeeRecipient}: FcuAttributes): string {
+    return `${headBlockHash}-${timestamp}-${prevRandao}-${suggestedFeeRecipient}`;
   }
   getKey({timestamp}: Pick<FcuAttributes, "timestamp">): string {
     return timestamp;
@@ -37,7 +44,8 @@ export class PayloadIdCache {
   add(fcuAttributes: FcuAttributes, payloadId: PayloadId): void {
     const key = this.getKey(fcuAttributes);
     const fullKey = this.getFullKey(fcuAttributes);
-    this.payloadIdByFcuAttributes.set(key, {payloadId, fullKey});
+    const {inclusionListTransactions} = fcuAttributes;
+    this.payloadIdByFcuAttributes.set(key, {payloadId, fullKey, inclusionListTransactions});
   }
 
   prune(): void {
@@ -49,6 +57,16 @@ export class PayloadIdCache {
     const key = this.getKey(fcuAttributes);
     const fullKey = this.getFullKey(fcuAttributes);
     const payloadInfo = this.payloadIdByFcuAttributes.get(key);
-    return payloadInfo?.fullKey === fullKey ? payloadInfo.payloadId : undefined;
+    return payloadInfo?.fullKey === fullKey &&
+      isSameInclusionList(payloadInfo.inclusionListTransactions, fcuAttributes.inclusionListTransactions)
+      ? payloadInfo.payloadId
+      : undefined;
   }
 }
+
+function isSameInclusionList(a?: bellatrix.Transactions, b?: bellatrix.Transactions): boolean {
+  if (a === undefined || b === undefined) {
+    return a === b;
+  }
+  return byteArrayEquals(a.bytes, b.bytes);
+}