@lodestar/beacon-node 1.51.0-dev.c99cf49add → 1.51.0-dev.e22f67e7bc

package/package.json

@@ -11,7 +11,7 @@
   "bugs": {
     "url": "https://github.com/ChainSafe/lodestar/issues"
   },
-  "version": "1.51.0-dev.c99cf49add",
+  "version": "1.51.0-dev.e22f67e7bc",
   "type": "module",
   "exports": {
     ".": {
@@ -127,17 +127,17 @@
     "@libp2p/prometheus-metrics": "^5.0.28",
     "@libp2p/tcp": "^11.0.27",
     "@libp2p/utils": "^7.4.0",
-    "@lodestar/api": "^1.51.0-dev.c99cf49add",
-    "@lodestar/config": "^1.51.0-dev.c99cf49add",
-    "@lodestar/db": "^1.51.0-dev.c99cf49add",
-    "@lodestar/fork-choice": "^1.51.0-dev.c99cf49add",
-    "@lodestar/logger": "^1.51.0-dev.c99cf49add",
-    "@lodestar/params": "^1.51.0-dev.c99cf49add",
-    "@lodestar/reqresp": "^1.51.0-dev.c99cf49add",
-    "@lodestar/state-transition": "^1.51.0-dev.c99cf49add",
-    "@lodestar/types": "^1.51.0-dev.c99cf49add",
-    "@lodestar/utils": "^1.51.0-dev.c99cf49add",
-    "@lodestar/validator": "^1.51.0-dev.c99cf49add",
+    "@lodestar/api": "^1.51.0-dev.e22f67e7bc",
+    "@lodestar/config": "^1.51.0-dev.e22f67e7bc",
+    "@lodestar/db": "^1.51.0-dev.e22f67e7bc",
+    "@lodestar/fork-choice": "^1.51.0-dev.e22f67e7bc",
+    "@lodestar/logger": "^1.51.0-dev.e22f67e7bc",
+    "@lodestar/params": "^1.51.0-dev.e22f67e7bc",
+    "@lodestar/reqresp": "^1.51.0-dev.e22f67e7bc",
+    "@lodestar/state-transition": "^1.51.0-dev.e22f67e7bc",
+    "@lodestar/types": "^1.51.0-dev.e22f67e7bc",
+    "@lodestar/utils": "^1.51.0-dev.e22f67e7bc",
+    "@lodestar/validator": "^1.51.0-dev.e22f67e7bc",
     "@multiformats/multiaddr": "^13.0.1",
     "datastore-core": "^12.0.1",
     "datastore-level": "^13.0.1",
@@ -159,8 +159,8 @@
     "@ethereumjs/rlp": "^4.0.1",
     "@libp2p/interface-internal": "^3.1.12",
     "@libp2p/logger": "^6.2.13",
-    "@lodestar/spec-test-util": "^1.51.0-dev.c99cf49add",
-    "@lodestar/test-utils": "^1.51.0-dev.c99cf49add",
+    "@lodestar/spec-test-util": "^1.51.0-dev.e22f67e7bc",
+    "@lodestar/test-utils": "^1.51.0-dev.e22f67e7bc",
     "@types/js-yaml": "^4.0.5",
     "@types/qs": "^6.9.7",
     "@types/tmp": "^0.2.3",
@@ -175,5 +175,5 @@
     "beacon",
     "blockchain"
   ],
-  "gitHead": "49fb87992415d69cef814473f10e7af82376a0da"
+  "gitHead": "566c479afefce96055ce784503d4c2c61c1eb607"
 }

package/src/api/impl/beacon/state/index.ts

@@ -17,6 +17,7 @@ import {
   isStatePostGloas,
 } from "@lodestar/state-transition";
 import {
+  BuilderIndex,
   ValidatorIndex,
   getBuilderStatus,
   getValidatorStatus,
@@ -29,6 +30,7 @@ import {ApiModules} from "../../types.js";
 import {assertUniqueItems} from "../../utils.js";
 import {
   filterStateValidatorsByStatus,
+  getBuilderIndexByPubkey,
   getStateBuilderIndex,
   getStateResponseWithRegen,
   getStateValidatorIndex,
@@ -170,8 +172,15 @@ export function getBeaconStateApi({
       if (builderIds.length) {
         assertUniqueItems(builderIds, "Duplicate builder IDs provided");
 
+        // There is no builder pubkey cache, scan the registry at most once per request
+        let builderIndexByPubkey: Map<string, BuilderIndex> | null = null;
+        const getBuilderIndexByPubkeyMap = () => {
+          builderIndexByPubkey ??= getBuilderIndexByPubkey(state);
+          return builderIndexByPubkey;
+        };
+
         for (const id of builderIds) {
-          const resp = getStateBuilderIndex(id, state);
+          const resp = getStateBuilderIndex(id, state, getBuilderIndexByPubkeyMap);
           if (resp.valid) {
             const builderIndex = resp.builderIndex;
             const builder = state.getBuilder(builderIndex);

package/src/api/impl/beacon/state/utils.ts

@@ -13,7 +13,7 @@ import {
   getValidatorStatus,
   phase0,
 } from "@lodestar/types";
-import {byteArrayEquals, fromHex} from "@lodestar/utils";
+import {fromHex, toHex} from "@lodestar/utils";
 import {IBeaconChain} from "../../../../chain/index.js";
 import {GENESIS_EPOCH} from "../../../../constants/index.js";
 import {IBeaconSync} from "../../../../sync/index.js";
@@ -118,9 +118,22 @@ type StateBuilderIndexResponse =
   | {valid: true; builderIndex: BuilderIndex}
   | {valid: false; code: number; reason: string};
 
+export function getBuilderIndexByPubkey(state: IBeaconStateViewGloas): Map<string, BuilderIndex> {
+  const builderIndexByPubkey = new Map<string, BuilderIndex>();
+  const buildersLength = state.getBuildersLength();
+  for (let builderIndex = 0; builderIndex < buildersLength; builderIndex++) {
+    const pubkeyHex = toHex(state.getBuilder(builderIndex).pubkey);
+    if (!builderIndexByPubkey.has(pubkeyHex)) {
+      builderIndexByPubkey.set(pubkeyHex, builderIndex);
+    }
+  }
+  return builderIndexByPubkey;
+}
+
 export function getStateBuilderIndex(
   id: routes.beacon.BuilderId | BLSPubkey,
-  state: IBeaconStateViewGloas
+  state: IBeaconStateViewGloas,
+  getBuilderIndexByPubkeyMap: () => Map<string, BuilderIndex>
 ): StateBuilderIndexResponse {
   if (typeof id === "string") {
     // mutate `id` and fallthrough to below
@@ -148,14 +161,11 @@ export function getStateBuilderIndex(
   }
 
   // typeof id === Uint8Array
-  // There is no builder pubkey cache, linear scan over the registry
-  const buildersLength = state.getBuildersLength();
-  for (let builderIndex = 0; builderIndex < buildersLength; builderIndex++) {
-    if (byteArrayEquals(state.getBuilder(builderIndex).pubkey, id)) {
-      return {valid: true, builderIndex};
-    }
+  const builderIndex = getBuilderIndexByPubkeyMap().get(toHex(id));
+  if (builderIndex === undefined) {
+    return {valid: false, code: 404, reason: "Builder pubkey not found in state"};
   }
-  return {valid: false, code: 404, reason: "Builder pubkey not found in state"};
+  return {valid: true, builderIndex};
 }
 
 export function filterStateValidatorsByStatus(

package/src/api/impl/debug/index.ts

@@ -114,6 +114,10 @@ export function getDebugApi({
                 unrealizedJustifiedRoot: node.unrealizedJustifiedRoot,
                 unrealizedFinalizedEpoch: node.unrealizedFinalizedEpoch,
                 unrealizedFinalizedRoot: node.unrealizedFinalizedRoot,
+                inclusionListSatisfied:
+                  node.payloadStatus === PayloadStatus.FULL
+                    ? forkChoice.getPayloadInclusionListSatisfaction(node.blockRoot)
+                    : null,
               },
             };
           }),

package/src/api/impl/validator/index.ts

@@ -18,6 +18,7 @@ import {
   isForkPostElectra,
   isForkPostFulu,
   isForkPostGloas,
+  isForkPostHeze,
 } from "@lodestar/params";
 import {
   DataAvailabilityStatus,
@@ -28,6 +29,7 @@ import {
   computeStartSlotAtEpoch,
   computeTimeAtSlot,
   getCurrentSlot,
+  getInclusionListCommittee,
   isStatePostAltair,
   isStatePostGloas,
   proposerShufflingDecisionRoot,
@@ -68,6 +70,7 @@ import {
 } from "@lodestar/utils";
 import {MAX_BUILDER_BOOST_FACTOR} from "@lodestar/validator";
 import {BlockInputSource} from "../../../chain/blocks/blockInput/types.js";
+import {InclusionListSource} from "../../../chain/blocks/types.js";
 import {
   AttestationError,
   AttestationErrorCode,
@@ -83,7 +86,11 @@ import {PREPARE_NEXT_SLOT_BPS} from "../../../chain/prepareNextSlot.js";
 import {BlockType, ProduceFullDeneb, ProduceFullGloas} from "../../../chain/produceBlock/index.js";
 import {RegenCaller} from "../../../chain/regen/index.js";
 import {CheckpointHex} from "../../../chain/stateCache/types.js";
-import {validateApiAggregateAndProof} from "../../../chain/validation/index.js";
+import {
+  InclusionListValidationResult,
+  validateApiAggregateAndProof,
+  validateGossipInclusionList,
+} from "../../../chain/validation/index.js";
 import {validateGossipProposerPreferences} from "../../../chain/validation/proposerPreferences.js";
 import {validateSyncCommitteeGossipContributionAndProof} from "../../../chain/validation/syncCommitteeContributionAndProof.js";
 import {ZERO_HASH} from "../../../constants/index.js";
@@ -247,13 +254,13 @@ export function getValidatorApi(
         genesisBlockRoot = state.computeAnchorCheckpoint().checkpoint.root;
       } else if (state.slot < SLOTS_PER_HISTORICAL_ROOT) {
         genesisBlockRoot = state.getBlockRootAtSlot(GENESIS_SLOT);
-      }
-
-      const blockRes = await chain.getCanonicalBlockAtSlot(GENESIS_SLOT);
-      if (blockRes) {
-        genesisBlockRoot = config
-          .getForkTypes(blockRes.block.message.slot)
-          .SignedBeaconBlock.hashTreeRoot(blockRes.block);
+      } else {
+        const blockRes = await chain.getCanonicalBlockAtSlot(GENESIS_SLOT);
+        if (blockRes) {
+          genesisBlockRoot = config
+            .getForkTypes(blockRes.block.message.slot)
+            .BeaconBlock.hashTreeRoot(blockRes.block.message);
+        }
       }
     }
 
@@ -1700,7 +1707,7 @@ export function getValidatorApi(
         }
       }
 
-      const dependentRoot = fromHex(state.getShufflingDecisionRoot(epoch)) || (await getGenesisBlockRoot(state));
+      const dependentRoot = fromHex(state.getShufflingDecisionRoot(epoch));
 
       return {
         data: duties,
@@ -1749,7 +1756,7 @@ export function getValidatorApi(
         }
       }
 
-      const dependentRoot = fromHex(state.getShufflingDecisionRoot(epoch)) || (await getGenesisBlockRoot(state));
+      const dependentRoot = fromHex(state.getShufflingDecisionRoot(epoch));
 
       return {
         data: duties,
@@ -2198,6 +2205,121 @@ export function getValidatorApi(
       }
     },
 
+    async produceInclusionList({slot}) {
+      notWhileSyncing(chain, sync.state);
+
+      if (!isForkPostHeze(chain.config.getForkName(slot))) {
+        throw new ApiError(400, `Producing inclusion list for pre-heze slot: ${slot}`);
+      }
+
+      await waitForSlot(slot); // Must never request for a future slot > currentSlot
+
+      const timer = metrics?.getInclusionListV1RequestsDuration.startTimer();
+      const transactions = await chain.executionEngine.getInclusionList();
+      timer?.();
+      metrics?.getInclusionListV1Requests.inc();
+
+      return {data: transactions, meta: {version: chain.config.getForkName(slot)}};
+    },
+
+    async getInclusionListCommitteeDuties({epoch, indices}) {
+      notWhileSyncing(chain, sync.state);
+
+      if (indices.length === 0) {
+        throw new ApiError(400, "No validator to get inclusion list committee duties");
+      }
+
+      if (!isForkPostHeze(chain.config.getForkName(computeStartSlotAtEpoch(epoch)))) {
+        throw new ApiError(400, `Requesting pre-heze inclusion list committee duties epoch: ${epoch}`);
+      }
+
+      // May request for an epoch that's in the future
+      await waitForNextClosestEpoch();
+
+      if (epoch > chain.clock.currentEpoch + 1) {
+        throw new ApiError(400, "Cannot get duties for epoch more than one ahead");
+      }
+
+      const head = chain.forkChoice.getHead();
+      const state = await chain.getHeadStateAtCurrentEpoch(RegenCaller.getDuties);
+
+      const pubkeys = getPubkeysForIndices(state, indices);
+      const requestedIndices = new Set(indices);
+      const epochStartSlot = computeStartSlotAtEpoch(epoch);
+      const shuffling = state.getShufflingAtEpoch(epoch);
+
+      // Validators set this as `dependent_root` on their inclusion lists
+      const dependentRoot = fromHex(state.getShufflingDecisionRoot(epoch));
+
+      // A validator can be on several slots' committees in an epoch; report the earliest, as for attester duties
+      const dutySlotByValidator = new Map<ValidatorIndex, Slot>();
+      for (let i = 0; i < SLOTS_PER_EPOCH; i++) {
+        const slot = epochStartSlot + i;
+        for (const validatorIndex of getInclusionListCommittee(shuffling, slot).validatorIndices) {
+          if (requestedIndices.has(validatorIndex) && !dutySlotByValidator.has(validatorIndex)) {
+            dutySlotByValidator.set(validatorIndex, slot);
+          }
+        }
+      }
+
+      const duties: routes.validator.InclusionListDuty[] = [];
+      for (let i = 0; i < indices.length; i++) {
+        const validatorIndex = indices[i];
+        const slot = dutySlotByValidator.get(validatorIndex);
+        if (slot !== undefined) {
+          duties.push({pubkey: pubkeys[i], validatorIndex, slot, dependentRoot});
+        }
+      }
+
+      return {
+        data: duties,
+        meta: {
+          dependentRoot: toRootHex(dependentRoot),
+          executionOptimistic: isOptimisticBlock(head),
+        },
+      };
+    },
+
+    async publishInclusionList({signedInclusionList}) {
+      notWhileSyncing(chain, sync.state);
+
+      const {slot} = signedInclusionList.message;
+      if (!isForkPostHeze(chain.config.getForkName(slot))) {
+        throw new ApiError(400, `Publishing pre-heze inclusion list slot: ${slot}`);
+      }
+
+      // Timeliness is judged on receipt, as for gossip, so a list submitted in time stays timely if validation is slow
+      const secFromSlot = chain.clock.secFromSlot(slot, Date.now() / 1000);
+      metrics?.inclusionListsReceived.inc({source: InclusionListSource.api});
+      metrics?.inclusionListTransactionsReceived.inc(
+        {source: InclusionListSource.api},
+        signedInclusionList.message.transactions.length
+      );
+
+      const timer = metrics?.inclusionListsValidationTime.startTimer();
+      let validationResult: InclusionListValidationResult;
+      try {
+        validationResult = await validateGossipInclusionList(chain, signedInclusionList);
+      } finally {
+        timer?.({source: InclusionListSource.api});
+      }
+      const {committeeIndices, totalBytes} = validationResult;
+      metrics?.inclusionListsValid.inc({source: InclusionListSource.api});
+      metrics?.inclusionListsValidSize.inc(totalBytes);
+
+      const isTimely =
+        secFromSlot >= 0 && secFromSlot * 1000 < chain.config.getInclusionListDueMs(chain.config.getForkName(slot));
+      chain.inclusionListStore.process(signedInclusionList, committeeIndices, isTimely);
+
+      chain.emitter.emit(routes.events.EventType.inclusionList, {
+        version: chain.config.getForkName(slot),
+        data: signedInclusionList,
+      });
+
+      await network.publishInclusionList(signedInclusionList);
+      metrics?.inclusionListsPublished.inc();
+    },
+
     async getExecutionPayloadEnvelope({slot, beaconBlockRoot}) {
       const fork = config.getForkName(slot);
 

package/src/chain/ColumnReconstructionTracker.ts

@@ -1,7 +1,10 @@
 import {ChainForkConfig} from "@lodestar/config";
+import {NUMBER_OF_COLUMNS} from "@lodestar/params";
+import {RootHex} from "@lodestar/types";
 import {Logger, sleep} from "@lodestar/utils";
 import {Metrics} from "../metrics/metrics.js";
 import {DataColumnReconstructionCode, recoverDataColumnSidecars} from "../util/dataColumns.js";
+import {JobItemQueue} from "../util/queue/index.js";
 import {BlockInputColumns} from "./blocks/blockInput/index.js";
 import {PayloadEnvelopeInput} from "./blocks/payloadEnvelopeInput/index.js";
 import {ChainEventEmitter} from "./emitter.js";
@@ -16,15 +19,22 @@ const RECONSTRUCTION_DELAY_MIN_BPS = 667;
  */
 const RECONSTRUCTION_DELAY_MAX_BPS = 1000;
 
+const QUEUE_MAX_LENGTH = 16;
+
+export type ColumnReconstructionInput = BlockInputColumns | PayloadEnvelopeInput;
+
 export type ColumnReconstructionTrackerInit = {
   logger: Logger;
   emitter: ChainEventEmitter;
   metrics: Metrics | null;
   config: ChainForkConfig;
+  signal: AbortSignal;
 };
 
 /**
- * Tracks column reconstruction attempts to avoid duplicate and multiple in-flight calls
+ * Runs column reconstruction one block root at a time, in trigger order. A trigger for a root that is
+ * queued or in flight is a no-op. A root is removed once its attempt finishes so a later column can
+ * retry a failed attempt.
  */
 export class ColumnReconstructionTracker {
   logger: Logger;
@@ -32,62 +42,71 @@ export class ColumnReconstructionTracker {
   metrics: Metrics | null;
   config: ChainForkConfig;
 
-  /**
-   * Track last attempted block root
-   *
-   * This is sufficient to avoid duplicate calls since we only call this
-   * function when we see a new data column sidecar from gossip.
-   */
-  lastBlockRootHex: string | null = null;
-  /** Track if a reconstruction attempt is in-flight */
-  running = false;
+  private readonly signal: AbortSignal;
+  private readonly pending = new Set<RootHex>();
+  private readonly queue: JobItemQueue<[ColumnReconstructionInput, number], void>;
 
   constructor(init: ColumnReconstructionTrackerInit) {
     this.logger = init.logger;
     this.emitter = init.emitter;
     this.metrics = init.metrics;
     this.config = init.config;
+    this.signal = init.signal;
+    this.queue = new JobItemQueue(
+      this.reconstruct,
+      {maxLength: QUEUE_MAX_LENGTH, signal: init.signal},
+      init.metrics?.columnReconstructionQueue
+    );
   }
 
-  triggerColumnReconstruction(input: BlockInputColumns | PayloadEnvelopeInput): void {
-    if (this.running) {
+  triggerColumnReconstruction(input: ColumnReconstructionInput): void {
+    if (this.pending.has(input.blockRootHex)) {
       return;
     }
 
-    if (this.lastBlockRootHex === input.blockRootHex) {
+    if (input.getAllColumns().length < NUMBER_OF_COLUMNS / 2) {
       return;
     }
 
-    // We don't care about the outcome of this call,
-    // just that it has been triggered for this block root.
-    this.running = true;
-    this.lastBlockRootHex = input.blockRootHex;
+    this.pending.add(input.blockRootHex);
+    void this.enqueue(input);
+  }
+
+  private async enqueue(input: ColumnReconstructionInput): Promise<void> {
+    try {
+      await this.queue.push(input, Date.now());
+    } catch (e) {
+      this.logger.debug(
+        "Data column sidecar reconstruction dropped",
+        {slot: input.slot, root: input.blockRootHex},
+        e as Error
+      );
+    } finally {
+      this.pending.delete(input.blockRootHex);
+    }
+  }
+
+  private reconstruct = async (input: ColumnReconstructionInput, queuedAtMs: number): Promise<void> => {
     const fork = this.config.getForkName(input.slot);
     const minDelayMs = this.config.getSlotComponentDurationMs(fork, RECONSTRUCTION_DELAY_MIN_BPS);
     const maxDelayMs = this.config.getSlotComponentDurationMs(fork, RECONSTRUCTION_DELAY_MAX_BPS);
     const delay = minDelayMs + Math.random() * (maxDelayMs - minDelayMs);
-    sleep(delay)
-      .then(() => {
-        const logCtx = {slot: input.slot, root: input.blockRootHex};
-        this.logger.debug("Attempting data column sidecar reconstruction", logCtx);
-        recoverDataColumnSidecars(input, this.emitter, this.metrics)
-          .then((result) => {
-            this.metrics?.recoverDataColumnSidecars.reconstructionResult.inc({result});
-            this.logger.debug("Data column sidecar reconstruction complete", {...logCtx, result});
-          })
-          .catch((e) => {
-            this.metrics?.recoverDataColumnSidecars.reconstructionResult.inc({
-              result: DataColumnReconstructionCode.Failed,
-            });
-            this.logger.debug("Error during data column sidecar reconstruction", logCtx, e as Error);
-          })
-          .finally(() => {
-            this.logger.debug("Data column sidecar reconstruction attempt finished", logCtx);
-            this.running = false;
-          });
-      })
-      .catch((err) => {
-        this.logger.debug("ColumnReconstructionTracker unreachable error", {}, err);
-      });
-  }
+
+    // The delay gives gossip a chance to deliver the remaining columns, so time already spent in the
+    // queue behind another root counts towards it
+    await sleep(delay - (Date.now() - queuedAtMs), this.signal);
+
+    const logCtx = {slot: input.slot, root: input.blockRootHex};
+    this.logger.debug("Attempting data column sidecar reconstruction", logCtx);
+    try {
+      const result = await recoverDataColumnSidecars(input, this.emitter, this.metrics);
+      this.metrics?.recoverDataColumnSidecars.reconstructionResult.inc({result});
+      this.logger.debug("Data column sidecar reconstruction complete", {...logCtx, result});
+    } catch (e) {
+      this.metrics?.recoverDataColumnSidecars.reconstructionResult.inc({result: DataColumnReconstructionCode.Failed});
+      this.logger.debug("Error during data column sidecar reconstruction", logCtx, e as Error);
+    } finally {
+      this.logger.debug("Data column sidecar reconstruction attempt finished", logCtx);
+    }
+  };
 }

package/src/chain/blocks/importBlock.ts

@@ -458,7 +458,8 @@ export async function importBlock(
      * - `headBlockHash !== null` -> Pre BELLATRIX_EPOCH
      * - `headBlockHash !== ZERO_HASH` -> Pre TTD
      */
-    const headBlockHash = this.forkChoice.getHead().executionPayloadBlockHash ?? ZERO_HASH_HEX;
+    const fcuHead = this.forkChoice.getHead();
+    const headBlockHash = fcuHead.executionPayloadBlockHash ?? ZERO_HASH_HEX;
     /**
      * After BELLATRIX_EPOCH and TTD it's okay to send a zero hash block hash for the finalized block. This will happen if
      * the current finalized block does not contain any execution payload at all (pre MERGE_EPOCH) or if it contains a
@@ -468,12 +469,7 @@ export async function importBlock(
     const finalizedBlockHash = getFinalizedExecutionBlockHash(this.forkChoice);
     if (headBlockHash !== ZERO_HASH_HEX) {
       this.executionEngine
-        .notifyForkchoiceUpdate(
-          this.config.getForkName(this.forkChoice.getHead().slot),
-          headBlockHash,
-          safeBlockHash,
-          finalizedBlockHash
-        )
+        .notifyForkchoiceUpdate(this.config.getForkName(fcuHead.slot), headBlockHash, safeBlockHash, finalizedBlockHash)
         .catch((e) => {
           if (!isErrorAborted(e) && !isQueueErrorAborted(e)) {
             this.logger.error("Error pushing notifyForkchoiceUpdate()", {headBlockHash, finalizedBlockHash}, e);

package/src/chain/blocks/importExecutionPayload.ts

@@ -5,9 +5,16 @@ import {
   getFinalizedExecutionBlockHash,
   getSafeExecutionBlockHash,
 } from "@lodestar/fork-choice";
-import {DataAvailabilityStatus, isStatePostGloas} from "@lodestar/state-transition";
+import {
+  DataAvailabilityStatus,
+  computeEpochAtSlot,
+  isStatePostGloas,
+  isStatePostHeze,
+} from "@lodestar/state-transition";
+import {RootHex, bellatrix} from "@lodestar/types";
 import {isErrorAborted} from "@lodestar/utils";
 import {ExecutionPayloadStatus} from "../../execution/index.js";
+import {getShufflingDependentRoot} from "../../util/dependentRoot.js";
 import {isQueueErrorAborted} from "../../util/queue/index.js";
 import {BeaconChain} from "../chain.js";
 import {RegenCaller} from "../regen/interface.js";
@@ -172,6 +179,37 @@ export async function importExecutionPayload(
     );
   }
 
+  // Timely inclusion lists of the preceding slot, keyed by that slot's dependent root on the block's branch and
+  // resolved from the parent, which is at or before that slot. Gossip validation only accepts lists whose dependent
+  // block is in fork choice, so a dependent root fork choice cannot resolve (below the anchor after checkpoint sync)
+  // keys no stored list
+  let inclusionListTransactions: bellatrix.Transactions | undefined;
+  if (isStatePostHeze(blockState)) {
+    const inclusionListSlot = protoBlock.slot - 1;
+    let dependentRoot: RootHex | null = null;
+    const parentBlock = this.forkChoice.getBlockHexDefaultStatus(protoBlock.parentRoot);
+    if (parentBlock !== null) {
+      try {
+        dependentRoot = getShufflingDependentRoot(
+          this.forkChoice,
+          computeEpochAtSlot(inclusionListSlot),
+          computeEpochAtSlot(parentBlock.slot),
+          parentBlock
+        );
+      } catch (e) {
+        this.logger.debug(
+          "Inclusion list dependent root not in fork choice, importing payload without lists",
+          {slot, root: blockRootHex},
+          e as Error
+        );
+      }
+    }
+    inclusionListTransactions =
+      dependentRoot === null
+        ? []
+        : this.inclusionListStore.getInclusionListTransactions(inclusionListSlot, dependentRoot, true);
+  }
+
   // 4a. Run EL and signature verification in parallel
   const logCtx = {slot, root: blockRootHex, executionBlock: envelope.payload.blockNumber};
   this.logger.debug("Call engine api newPayload", logCtx);
@@ -182,7 +220,8 @@ export async function importExecutionPayload(
       envelope.payload,
       payloadInput.getVersionedHashes(),
       envelope.parentBeaconBlockRoot,
-      envelope.executionRequests
+      envelope.executionRequests,
+      inclusionListTransactions
     ),
 
     opts.validSignature === true
@@ -250,6 +289,32 @@ export async function importExecutionPayload(
     }
   });
 
+  // A VALID payload that does not satisfy the inclusion list constraints is still imported, fork choice
+  // only records the verdict so should_extend_payload moves the head to the EMPTY variant, which the next
+  // proposer builds on.
+  // Recorded before the payload enters fork choice. A VALID response must carry a verdict, an
+  // optimistically imported payload counts as satisfied until the engine validates it, anything else as
+  // unsatisfied. A VALID response without a verdict violates the engine API, it is logged and treated as
+  // satisfied so a non-compliant engine does not orphan every payload
+  if (inclusionListTransactions !== undefined) {
+    if (execResult.status === ExecutionPayloadStatus.VALID && execResult.inclusionListSatisfied == null) {
+      this.logger.warn("Execution engine reported no inclusion list verdict, not enforcing inclusion lists", logCtx);
+    }
+    const satisfied =
+      execResult.status === ExecutionPayloadStatus.VALID
+        ? (execResult.inclusionListSatisfied ?? true)
+        : execResult.status === ExecutionPayloadStatus.SYNCING || execResult.status === ExecutionPayloadStatus.ACCEPTED;
+    this.forkChoice.recordPayloadInclusionListSatisfaction(blockRootHex, satisfied);
+    if (!satisfied) {
+      this.logger.verbose("Payload did not satisfy inclusion list constraints", {
+        ...logCtx,
+        blockHash: blockHashHex,
+        status: execResult.status,
+        inclusionListTransactions: inclusionListTransactions.length,
+      });
+    }
+  }
+
   // 6. Update fork choice, transitions the block's PENDING variant to FULL
   const execStatus = toForkChoiceExecutionStatus(execResult.status);
   this.forkChoice.onExecutionPayload(

package/src/chain/blocks/types.ts

@@ -12,6 +12,11 @@ export enum GossipedInputType {
   dataColumn = "data_column",
 }
 
+export enum InclusionListSource {
+  gossip = "gossip",
+  api = "api",
+}
+
 type DataColumnData = {
   dataColumn: fulu.DataColumnSidecar;
   dataColumnBytes: Uint8Array | null;

package/src/chain/chain.ts

@@ -100,6 +100,7 @@ import {
   AttestationPool,
   DeferredVoluntaryExitPool,
   ExecutionPayloadBidPool,
+  InclusionListStore,
   OpPool,
   PayloadAttestationPool,
   ProposerPreferencesPool,
@@ -198,6 +199,7 @@ export class BeaconChain implements IBeaconChain {
   readonly executionPayloadBidPool: ExecutionPayloadBidPool;
   readonly payloadAttestationPool: PayloadAttestationPool;
   readonly proposerPreferencesPool = new ProposerPreferencesPool();
+  readonly inclusionListStore: InclusionListStore;
   readonly opPool: OpPool;
   readonly deferredVoluntaryExitPool: DeferredVoluntaryExitPool;
 
@@ -335,6 +337,7 @@ export class BeaconChain implements IBeaconChain {
     this.payloadAttestationPool = new PayloadAttestationPool(config, clock, metrics);
     this.opPool = new OpPool(config);
     this.deferredVoluntaryExitPool = new DeferredVoluntaryExitPool(logger);
+    this.inclusionListStore = new InclusionListStore(config);
 
     this.seenAggregatedAttestations = new SeenAggregatedAttestations(metrics);
     this.seenContributionAndProof = new SeenContributionAndProof(metrics);
@@ -509,6 +512,7 @@ export class BeaconChain implements IBeaconChain {
       emitter,
       metrics,
       config,
+      signal,
     });
 
     this.archiveStore = new ArchiveStore(
@@ -1831,6 +1835,7 @@ export class BeaconChain implements IBeaconChain {
     this.executionPayloadBidPool.prune(slot);
     this.seenExecutionPayloadBids.prune(slot);
     this.proposerPreferencesPool.prune(slot);
+    this.inclusionListStore.prune(slot);
     this.seenAttestationDatas.onSlot(slot);
     this.reprocessController.onSlot(slot);