@lodestar/beacon-node 1.50.1 → 1.51.0-dev.0586e6e617

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)
@@ -70,7 +70,8 @@ export function getExecutionEngineHttp(
             jwtId: opts.jwtId,
             clientVersion: formatClientVersionHeader(getLodestarClientVersion(opts)),
             metrics,
-          })
+          }),
+          metrics
         );
 
   modules.logger.info("Execution client", {urls: opts.urls.map(toPrintableUrl).toString(), engineApi});

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/jsonRpcHttpClient.ts

@@ -284,7 +284,12 @@ export class JsonRpcHttpClient implements IJsonRpcHttpClient {
       });
 
       const streamTimer = this.metrics?.streamTime.startTimer({routeId});
-      const bodyText = await res.text();
+      let bodyText: string;
+      try {
+        bodyText = await res.text();
+      } finally {
+        streamTimer?.();
+      }
       this.metrics?.responseBytes.inc({routeId}, bodyText.length);
       if (!res.ok) {
         // Infura errors:
@@ -292,10 +297,12 @@ export class JsonRpcHttpClient implements IJsonRpcHttpClient {
         throw new HttpRpcError(res.status, `${res.statusText}: ${bodyText.slice(0, maxStringLengthToPrint)}`);
       }
 
-      const bodyJson = parseJson<R>(bodyText);
-      streamTimer?.();
-
-      return bodyJson;
+      const parseTimer = this.metrics?.responseParseTime.startTimer({routeId, encoding: "json"});
+      try {
+        return parseJson<R>(bodyText);
+      } finally {
+        parseTimer?.();
+      }
     } catch (e) {
       this.metrics?.requestErrors.inc({routeId});
       if (controller.signal.aborted) {

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);
+}

package/src/execution/engine/restTransport.ts

@@ -1,9 +1,19 @@
 import {Type} from "@chainsafe/ssz";
 import {CELLS_PER_EXT_BLOB, ForkName, ForkSeq, isForkPostBellatrix} from "@lodestar/params";
-import {ExecutionPayload, ExecutionRequests, Root, RootHex, capella, deneb, electra, gloas} from "@lodestar/types";
+import {
+  ExecutionPayload,
+  ExecutionRequests,
+  Root,
+  RootHex,
+  bellatrix,
+  capella,
+  deneb,
+  electra,
+  gloas,
+} from "@lodestar/types";
 import {BlobAndProof} from "@lodestar/types/deneb";
 import {BlobAndProofV2} from "@lodestar/types/fulu";
-import {LodestarError, fromHex, strip0xPrefix, toHex, toRootHex} from "@lodestar/utils";
+import {EndTimer, LodestarError, fromHex, strip0xPrefix, toHex, toRootHex} from "@lodestar/utils";
 import {isValidBlobVersionedHashes} from "./blobVersionedHashes.js";
 import {
   ClientCode,
@@ -48,6 +58,7 @@ import {
   executionForkName,
 } from "./sszTypes.js";
 import {ForkchoiceUpdatedResult, GetPayloadResult, IEngineTransport, PayloadStatusResult} from "./transport.js";
+import {EngineTransportMetrics} from "./transportMetrics.js";
 import {
   ExecutionPayloadBodyV2,
   assertReqSizeLimit,
@@ -102,7 +113,10 @@ export function formatClientVersionHeader(clientVersion: ClientVersion): string
 export class RestEngineTransport implements IEngineTransport {
   private limits = DEFAULT_LIMITS;
 
-  constructor(private readonly client: EngineRestHttpClient) {}
+  constructor(
+    private readonly client: EngineRestHttpClient,
+    private readonly metrics?: EngineTransportMetrics | null
+  ) {}
 
   get emitter(): JsonRpcHttpClientEventEmitter {
     return this.client.emitter;
@@ -114,7 +128,7 @@ export class RestEngineTransport implements IEngineTransport {
       {method: "GET", path: "/capabilities", responseType: "json"},
       getCapabilitiesOpts
     );
-    const capabilities = parseJson(body, "getCapabilities");
+    const capabilities = parseJson(body, "getCapabilities", this.metrics);
     if (
       !isRecord(capabilities) ||
       !Array.isArray(capabilities.supported_forks) ||
@@ -220,7 +234,7 @@ export class RestEngineTransport implements IEngineTransport {
       {method: "POST", path: "/payloads", executionFork: toExecutionForkName(fork), body, responseType: "ssz"},
       notifyNewPayloadOpts
     );
-    return toPayloadStatusResult(deserializeResponse(PayloadStatus, res.body, "notifyNewPayload"));
+    return toPayloadStatusResult(deserializeResponse(PayloadStatus, res.body, "notifyNewPayload", this.metrics));
   }
 
   async forkchoiceUpdated(
@@ -268,7 +282,12 @@ export class RestEngineTransport implements IEngineTransport {
       {method: "POST", path: "/forkchoice", executionFork: toExecutionForkName(fork), body, responseType: "ssz"},
       fcUReqOpts
     );
-    const {payloadStatus, payloadId} = deserializeResponse(ForkchoiceUpdateResponse, res.body, "forkchoiceUpdated");
+    const {payloadStatus, payloadId} = deserializeResponse(
+      ForkchoiceUpdateResponse,
+      res.body,
+      "forkchoiceUpdated",
+      this.metrics
+    );
     return {
       payloadStatus: toPayloadStatusResult(payloadStatus),
       payloadId: payloadId.length > 0 ? toHex(payloadId[0]) : null,
@@ -289,7 +308,8 @@ export class RestEngineTransport implements IEngineTransport {
       const {payload, blockValue, blobsBundle, executionRequests, shouldOverrideBuilder} = deserializeResponse(
         BuiltPayloadGloas,
         res.body,
-        "getPayload"
+        "getPayload",
+        this.metrics
       );
       return {
         executionPayload: payload,
@@ -303,7 +323,8 @@ export class RestEngineTransport implements IEngineTransport {
       const {payload, blockValue, blobsBundle, executionRequests, shouldOverrideBuilder} = deserializeResponse(
         BuiltPayloadFulu,
         res.body,
-        "getPayload"
+        "getPayload",
+        this.metrics
       );
       return {
         executionPayload: payload,
@@ -317,7 +338,8 @@ export class RestEngineTransport implements IEngineTransport {
       const {payload, blockValue, blobsBundle, executionRequests, shouldOverrideBuilder} = deserializeResponse(
         BuiltPayloadElectra,
         res.body,
-        "getPayload"
+        "getPayload",
+        this.metrics
       );
       return {
         executionPayload: payload,
@@ -331,15 +353,16 @@ export class RestEngineTransport implements IEngineTransport {
       const {payload, blockValue, blobsBundle, shouldOverrideBuilder} = deserializeResponse(
         BuiltPayloadDeneb,
         res.body,
-        "getPayload"
+        "getPayload",
+        this.metrics
       );
       return {executionPayload: payload, executionPayloadValue: blockValue, blobsBundle, shouldOverrideBuilder};
     }
     if (ForkSeq[fork] >= ForkSeq.capella) {
-      const {payload, blockValue} = deserializeResponse(BuiltPayloadCapella, res.body, "getPayload");
+      const {payload, blockValue} = deserializeResponse(BuiltPayloadCapella, res.body, "getPayload", this.metrics);
       return {executionPayload: payload, executionPayloadValue: blockValue, shouldOverrideBuilder: false};
     }
-    const {payload, blockValue} = deserializeResponse(BuiltPayloadBellatrix, res.body, "getPayload");
+    const {payload, blockValue} = deserializeResponse(BuiltPayloadBellatrix, res.body, "getPayload", this.metrics);
     return {executionPayload: payload, executionPayloadValue: blockValue, shouldOverrideBuilder: false};
   }
 
@@ -356,7 +379,7 @@ export class RestEngineTransport implements IEngineTransport {
       },
       getPayloadBodiesByHashOpts
     );
-    const bodies = deserializeBodiesResponse(ForkName.gloas, res.body);
+    const bodies = deserializeBodiesResponse(ForkName.gloas, res.body, this.metrics);
     if (bodies.length !== blockHashes.length) {
       throw Error(`Invalid bodies response length=${bodies.length} blockHashes=${blockHashes.length}`);
     }
@@ -374,7 +397,7 @@ export class RestEngineTransport implements IEngineTransport {
       return versionedHashes.map(() => null);
     }
 
-    const {entries} = deserializeResponse(BlobsV1Response, res.body, "getBlobsV1");
+    const {entries} = deserializeResponse(BlobsV1Response, res.body, "getBlobsV1", this.metrics);
     if (entries.length !== versionedHashes.length) {
       throw Error(`Invalid blobs/v1 response length=${entries.length} versionedHashes=${versionedHashes.length}`);
     }
@@ -397,7 +420,7 @@ export class RestEngineTransport implements IEngineTransport {
       return null;
     }
 
-    const {entries} = deserializeResponse(BlobsV2Response, res.body, "getBlobsV2", {reuseBytes: true});
+    const {entries} = deserializeResponse(BlobsV2Response, res.body, "getBlobsV2", this.metrics, {reuseBytes: true});
     if (entries.length !== versionedHashes.length) {
       throw Error(`Invalid blobs/v2 response length=${entries.length} versionedHashes=${versionedHashes.length}`);
     }
@@ -418,7 +441,7 @@ export class RestEngineTransport implements IEngineTransport {
       {method: "GET", path: "/identity", responseType: "json"},
       getClientVersionOpts
     );
-    const versions = parseJson(body, "getClientVersion");
+    const versions = parseJson(body, "getClientVersion", this.metrics);
     if (!Array.isArray(versions)) {
       throw new EngineRestResponseError("getClientVersion", "Expected an array of client versions");
     }
@@ -441,6 +464,10 @@ export class RestEngineTransport implements IEngineTransport {
       };
     });
   }
+
+  getInclusionList(): Promise<bellatrix.Transactions> {
+    throw Error("engine_getInclusionListV1 is not available over the REST engine API");
+  }
 }
 
 function toPayloadAttributesBellatrix(attributes: PayloadAttributes) {
@@ -502,36 +529,54 @@ function toPayloadStatusResult(payloadStatus: PayloadStatusSsz): PayloadStatusRe
   }
 }
 
-function deserializeBodiesResponse(fork: ForkName, data: Uint8Array): (ExecutionPayloadBodyV2 | null)[] {
+function deserializeBodiesResponse(
+  fork: ForkName,
+  data: Uint8Array,
+  metrics?: EngineTransportMetrics | null
+): (ExecutionPayloadBodyV2 | null)[] {
   if (ForkSeq[fork] >= ForkSeq.gloas) {
-    return deserializeResponse(BodiesResponseGloas, data, "getPayloadBodiesByHash").entries.map((entry) =>
+    return deserializeResponse(BodiesResponseGloas, data, "getPayloadBodiesByHash", metrics).entries.map((entry) =>
       entry.available ? entry.body : null
     );
   }
   if (ForkSeq[fork] >= ForkSeq.capella) {
-    return deserializeResponse(BodiesResponseCapella, data, "getPayloadBodiesByHash").entries.map((entry) =>
+    return deserializeResponse(BodiesResponseCapella, data, "getPayloadBodiesByHash", metrics).entries.map((entry) =>
       entry.available ? {...entry.body, blockAccessList: null} : null
     );
   }
-  return deserializeResponse(BodiesResponseBellatrix, data, "getPayloadBodiesByHash").entries.map((entry) =>
+  return deserializeResponse(BodiesResponseBellatrix, data, "getPayloadBodiesByHash", metrics).entries.map((entry) =>
     entry.available ? {transactions: entry.body.transactions, withdrawals: null, blockAccessList: null} : null
   );
 }
 
 /** A 2xx response that does not decode is an execution client error, not an unreachable client */
-function deserializeResponse<T>(type: Type<T>, body: Uint8Array, routeId: string, opts?: {reuseBytes?: boolean}): T {
+function deserializeResponse<T>(
+  type: Type<T>,
+  body: Uint8Array,
+  routeId: string,
+  metrics?: EngineTransportMetrics | null,
+  opts?: {reuseBytes?: boolean}
+): T {
+  const timer = metrics?.responseParseTime.startTimer({routeId, encoding: "ssz"});
   try {
     return type.deserialize(body, opts);
   } catch (e) {
     throw new EngineRestResponseError(routeId, `Invalid SSZ: ${(e as Error).message}`);
+  } finally {
+    timer?.();
   }
 }
 
-function parseJson(body: Uint8Array, routeId: string): unknown {
+function parseJson(body: Uint8Array, routeId: string, metrics?: EngineTransportMetrics | null): unknown {
+  let timer: EndTimer | undefined;
   try {
-    return JSON.parse(textDecoder.decode(body));
+    const text = textDecoder.decode(body);
+    timer = metrics?.responseParseTime.startTimer({routeId, encoding: "json"});
+    return JSON.parse(text);
   } catch (e) {
     throw new EngineRestResponseError(routeId, `Invalid JSON: ${(e as Error).message}`);
+  } finally {
+    timer?.();
   }
 }
 

package/src/execution/engine/transport.ts

@@ -1,5 +1,5 @@
 import {ForkName} 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 {ClientVersion, ExecutionPayloadStatus, PayloadAttributes, PayloadId, VersionedHashes} from "./interface.js";
@@ -10,6 +10,8 @@ export type PayloadStatusResult = {
   status: ExecutionPayloadStatus;
   latestValidHash: RootHex | null;
   validationError: string | null;
+  /** PayloadStatusV2: whether a VALID payload satisfied the inclusion list constraints, null otherwise */
+  inclusionListSatisfied?: boolean | null;
 };
 
 export type ForkchoiceUpdatedResult = {
@@ -38,7 +40,8 @@ export interface IEngineTransport {
     executionPayload: ExecutionPayload,
     versionedHashes?: VersionedHashes,
     parentBeaconBlockRoot?: Root,
-    executionRequests?: ExecutionRequests
+    executionRequests?: ExecutionRequests,
+    inclusionListTransactions?: bellatrix.Transactions
   ): Promise<PayloadStatusResult>;
 
   forkchoiceUpdated(
@@ -58,4 +61,6 @@ export interface IEngineTransport {
   getBlobsV2(versionedHashes: VersionedHashes, buffers?: Uint8Array[]): Promise<BlobAndProofV2[] | null>;
 
   getClientVersion(clientVersion: ClientVersion): Promise<ClientVersion[]>;
+
+  getInclusionList(): Promise<bellatrix.Transactions>;
 }

package/src/execution/engine/transportMetrics.ts

@@ -1,4 +1,4 @@
-import {Counter} from "@lodestar/utils";
+import {Counter, Histogram} from "@lodestar/utils";
 
 /**
  * Common metrics type for both json rpc and ssz transport.
@@ -6,4 +6,5 @@ import {Counter} from "@lodestar/utils";
 export type EngineTransportMetrics = {
   requestBytes: Counter<{routeId: string}>;
   responseBytes: Counter<{routeId: string}>;
+  responseParseTime: Histogram<{routeId: string; encoding: "json" | "ssz"}>;
 };