@lodestar/beacon-node 1.50.0 → 1.51.0-dev.02c5a19f35

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,64 +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 minDelayMs: number;
-  private readonly maxDelayMs: number;
+  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.minDelayMs = this.config.getSlotComponentDurationMs(RECONSTRUCTION_DELAY_MIN_BPS);
-    this.maxDelayMs = this.config.getSlotComponentDurationMs(RECONSTRUCTION_DELAY_MAX_BPS);
+    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;
-    const delay = this.minDelayMs + Math.random() * (this.maxDelayMs - this.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);
-      });
+    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);
+
+    // 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/archiveStore/utils/archiveBlocks.ts

@@ -3,7 +3,7 @@ import {ChainForkConfig} from "@lodestar/config";
 import {KeyValue} from "@lodestar/db";
 import {CheckpointWithHex, ExecutionStatus, IForkChoice, PayloadStatus, ProtoBlock} from "@lodestar/fork-choice";
 import {ForkSeq, SLOTS_PER_EPOCH} from "@lodestar/params";
-import {computeEpochAtSlot, computeStartSlotAtEpoch} from "@lodestar/state-transition";
+import {computeEpochAtSlot, computeStartSlotAtEpoch, getBlobDataRetentionStartEpoch} from "@lodestar/state-transition";
 import {Epoch, Slot} from "@lodestar/types";
 import {Logger, fromAsync, fromHex, prettyPrintIndices, toRootHex} from "@lodestar/utils";
 import {IBeaconDb} from "../../../db/index.js";
@@ -253,14 +253,13 @@ export async function archiveBlocks(
   }
 
   // Delete expired data column sidecars
-  // Keep only `[current_epoch - max(MIN_EPOCHS_FOR_DATA_COLUMN_SIDECARS_REQUESTS, archiveDataEpochs)]`
+  // Keep only `[min(compute_blob_data_retention_start_epoch(current_epoch), current_epoch - archiveDataEpochs)]`
   if (finalizedPostFulu) {
     if (archiveDataEpochs !== Infinity) {
-      const dataColumnSidecarsArchiveWindow = Math.max(
-        config.MIN_EPOCHS_FOR_DATA_COLUMN_SIDECARS_REQUESTS,
-        archiveDataEpochs ?? 0
+      const dataColumnSidecarsMinEpoch = Math.min(
+        getBlobDataRetentionStartEpoch(config, currentEpoch),
+        currentEpoch - (archiveDataEpochs ?? 0)
       );
-      const dataColumnSidecarsMinEpoch = currentEpoch - dataColumnSidecarsArchiveWindow;
       if (dataColumnSidecarsMinEpoch >= config.FULU_FORK_EPOCH) {
         const columnsPruneSlot = computeStartSlotAtEpoch(dataColumnSidecarsMinEpoch);
         const prunedColumnSlots = await db.dataColumns.pruneBefore(columnsPruneSlot);
@@ -439,7 +438,7 @@ async function migrateDataColumnSidecarsFromHotToColdDb(
       const blockEpoch = computeEpochAtSlot(block.slot);
       if (
         config.getForkSeq(block.slot) < ForkSeq.fulu ||
-        blockEpoch < currentEpoch - config.MIN_EPOCHS_FOR_DATA_COLUMN_SIDECARS_REQUESTS
+        blockEpoch < getBlobDataRetentionStartEpoch(config, currentEpoch)
       ) {
         continue;
       }

package/src/chain/blocks/blockInput/blockInput.ts

@@ -210,7 +210,7 @@ export class BlockInputPreData extends AbstractBlockInput<ForkPreDeneb, null> {
     this.blockPromise.resolve(state.block);
   }
 
-  static createFromBlock(props: AddBlock & CreateBlockInputMeta): BlockInputPreData {
+  static createFromBlock(props: AddBlock<ForkPreDeneb> & CreateBlockInputMeta): BlockInputPreData {
     const init: BlockInputInit = {
       daOutOfRange: props.daOutOfRange,
       timeCreated: props.seenTimestampSec,

package/src/chain/blocks/blockInput/utils.ts

@@ -1,6 +1,6 @@
 import {ChainForkConfig} from "@lodestar/config";
 import {ForkName, isForkPostDeneb, isForkPostFulu} from "@lodestar/params";
-import {computeEpochAtSlot} from "@lodestar/state-transition";
+import {computeEpochAtSlot, getBlobDataRetentionStartEpoch} from "@lodestar/state-transition";
 import {Epoch, Slot} from "@lodestar/types";
 
 export function isDaOutOfRange(
@@ -10,7 +10,7 @@ export function isDaOutOfRange(
   currentEpoch: Epoch
 ): boolean {
   if (isForkPostFulu(forkName)) {
-    return computeEpochAtSlot(blockSlot) < currentEpoch - config.MIN_EPOCHS_FOR_DATA_COLUMN_SIDECARS_REQUESTS;
+    return computeEpochAtSlot(blockSlot) < getBlobDataRetentionStartEpoch(config, currentEpoch);
   }
 
   if (isForkPostDeneb(forkName)) {

package/src/chain/blocks/importBlock.ts

@@ -45,7 +45,7 @@ import {isQueueErrorAborted} from "../../util/queue/index.js";
 import type {BeaconChain} from "../chain.js";
 import {ChainEvent, ReorgEventData} from "../emitter.js";
 import {ForkchoiceCaller} from "../forkChoice/index.js";
-import {REPROCESS_MIN_TIME_TO_NEXT_SLOT_SEC} from "../reprocess.js";
+import {REPROCESS_MIN_TIME_TO_NEXT_SLOT_BPS} from "../reprocess.js";
 import {toCheckpointHex} from "../stateCache/persistentCheckpointsCache.js";
 import {isBlockInputBlobs, isBlockInputColumns} from "./blockInput/blockInput.js";
 import {AttestationImportOpt, FullyVerifiedBlock, ImportBlockOpts} from "./types.js";
@@ -335,7 +335,8 @@ export async function importBlock(
       this.metrics.headSlot.set(newHead.slot);
       // Only track "recent" blocks. Otherwise sync can distort this metrics heavily.
       // We want to track recent blocks coming from gossip, unknown block sync, and API.
-      if (delaySec < (SLOTS_PER_EPOCH * this.config.SLOT_DURATION_MS) / 1000) {
+      const headFork = this.config.getForkName(newHead.slot);
+      if (delaySec < (SLOTS_PER_EPOCH * this.config.getSlotDurationMs(headFork)) / 1000) {
         this.metrics.importBlock.elapsedTimeTillBecomeHead.observe(delaySec);
         const cutOffSec = this.config.getAttestationDueMs(this.config.getForkName(blockSlot)) / 1000;
         if (delaySec > cutOffSec) {
@@ -457,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
@@ -467,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);
@@ -586,7 +583,7 @@ export async function importBlock(
     this.validatorMonitor?.registerSyncAggregateInBlock(
       blockEpoch,
       (block as altair.SignedBeaconBlock).message.body.syncAggregate,
-      fullyVerifiedBlock.postState.currentSyncCommitteeIndexed.validatorIndices
+      fullyVerifiedBlock.postState.currentSyncCommitteeValidatorIndices
     );
   }
 
@@ -600,7 +597,10 @@ export async function importBlock(
     }
   }
 
-  const advancedSlot = this.clock.slotWithFutureTolerance(REPROCESS_MIN_TIME_TO_NEXT_SLOT_SEC);
+  const reprocessGuardSec =
+    this.config.getSlotComponentDurationMs(this.config.getForkName(blockSlot), REPROCESS_MIN_TIME_TO_NEXT_SLOT_BPS) /
+    1000;
+  const advancedSlot = this.clock.slotWithFutureTolerance(reprocessGuardSec);
 
   // Gossip blocks need to be imported as soon as possible, waiting attestations could be processed
   // in the next event loop. See https://github.com/ChainSafe/lodestar/issues/4789

package/src/chain/blocks/importExecutionPayload.ts

@@ -1,3 +1,4 @@
+import {SerializedList} from "@chainsafe/ssz";
 import {routes} from "@lodestar/api";
 import {
   ExecutionStatus,
@@ -5,9 +6,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 +180,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
+        ? SerializedList.empty()
+        : 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 +221,8 @@ export async function importExecutionPayload(
       envelope.payload,
       payloadInput.getVersionedHashes(),
       envelope.parentBeaconBlockRoot,
-      envelope.executionRequests
+      envelope.executionRequests,
+      inclusionListTransactions
     ),
 
     opts.validSignature === true
@@ -250,6 +290,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

@@ -58,7 +58,7 @@ import {
 } from "@lodestar/types";
 import {Logger, fromHex, gweiToWei, isErrorAborted, pruneSetToMax, sleep, toRootHex} from "@lodestar/utils";
 import {ProcessShutdownCallback} from "@lodestar/validator";
-import {GENESIS_EPOCH, ZERO_HASH} from "../constants/index.js";
+import {GENESIS_EPOCH, HALF_SLOT_BPS, ZERO_HASH} from "../constants/index.js";
 import {IBeaconDb} from "../db/index.js";
 import {BLOB_SIDECARS_IN_WRAPPER_INDEX} from "../db/repositories/blobSidecars.js";
 import {decodeArchivedEnvelope} from "../db/repositories/index.js";
@@ -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);
 
@@ -1841,7 +1846,8 @@ export class BeaconChain implements IBeaconChain {
     const metrics = this.metrics;
     if (metrics && (slot + 1) % SLOTS_PER_EPOCH === 0) {
       // On the last slot of the epoch
-      sleep(this.config.SLOT_DURATION_MS / 2)
+      const fork = this.config.getForkName(slot);
+      sleep(this.config.getSlotComponentDurationMs(fork, HALF_SLOT_BPS))
         .then(() => this.validatorMonitor?.onceEveryEndOfEpoch(this.getHeadState()))
         .catch((e) => {
           if (!isErrorAborted(e)) this.logger.error("Error on validator monitor onceEveryEndOfEpoch", {slot}, e);

package/src/chain/errors/executionPayloadBid.ts

@@ -21,6 +21,8 @@ export enum ExecutionPayloadBidErrorCode {
   NO_MATCHING_PROPOSER_PREFERENCES = "EXECUTION_PAYLOAD_BID_ERROR_NO_MATCHING_PROPOSER_PREFERENCES",
   PROPOSER_PREFERENCES_FEE_RECIPIENT_MISMATCH = "EXECUTION_PAYLOAD_BID_ERROR_PROPOSER_PREFERENCES_FEE_RECIPIENT_MISMATCH",
   PROPOSER_PREFERENCES_GAS_LIMIT_MISMATCH = "EXECUTION_PAYLOAD_BID_ERROR_PROPOSER_PREFERENCES_GAS_LIMIT_MISMATCH",
+  INCLUSION_LIST_BITS_NOT_INCLUSIVE = "EXECUTION_PAYLOAD_BID_ERROR_INCLUSION_LIST_BITS_NOT_INCLUSIVE",
+  BEFORE_INCLUSION_LIST_DEADLINE = "EXECUTION_PAYLOAD_BID_ERROR_BEFORE_INCLUSION_LIST_DEADLINE",
 }
 
 export type ExecutionPayloadBidErrorType =
@@ -86,6 +88,16 @@ export type ExecutionPayloadBidErrorType =
       bidFeeRecipient: string;
       expectedFeeRecipient: string;
     }
+  | {
+      code: ExecutionPayloadBidErrorCode.INCLUSION_LIST_BITS_NOT_INCLUSIVE;
+      builderIndex: BuilderIndex;
+      slot: Slot;
+    }
+  | {
+      code: ExecutionPayloadBidErrorCode.BEFORE_INCLUSION_LIST_DEADLINE;
+      builderIndex: BuilderIndex;
+      slot: Slot;
+    }
   | {
       code: ExecutionPayloadBidErrorCode.PROPOSER_PREFERENCES_GAS_LIMIT_MISMATCH;
       builderIndex: BuilderIndex;

package/src/chain/errors/inclusionList.ts

@@ -0,0 +1,38 @@
+import {Epoch, RootHex, Slot, ValidatorIndex} from "@lodestar/types";
+import {GossipActionError} from "./gossipValidation.js";
+
+export enum InclusionListErrorCode {
+  EMPTY_TRANSACTIONS = "INCLUSION_LIST_ERROR_EMPTY_TRANSACTIONS",
+  MAXIMUM_SIZE_EXCEEDED = "INCLUSION_LIST_ERROR_MAXIMUM_SIZE_EXCEEDED",
+  EMPTY_TRANSACTION = "INCLUSION_LIST_ERROR_EMPTY_TRANSACTION",
+  INVALID_SLOT = "INCLUSION_LIST_ERROR_INVALID_SLOT",
+  MORE_THAN_TWO = "INCLUSION_LIST_ERROR_MORE_THAN_TWO",
+  VALIDATOR_NOT_IN_COMMITTEE = "INCLUSION_LIST_ERROR_VALIDATOR_NOT_IN_COMMITTEE",
+  UNKNOWN_DEPENDENT_ROOT = "INCLUSION_LIST_ERROR_UNKNOWN_DEPENDENT_ROOT",
+  INVALID_DEPENDENT_ROOT_SLOT = "INCLUSION_LIST_ERROR_INVALID_DEPENDENT_ROOT_SLOT",
+  INVALID_DEPENDENT_ROOT = "INCLUSION_LIST_ERROR_INVALID_DEPENDENT_ROOT",
+  MISSING_SHUFFLING = "INCLUSION_LIST_ERROR_MISSING_SHUFFLING",
+  INVALID_SIGNATURE = "INCLUSION_LIST_ERROR_INVALID_SIGNATURE",
+  PRE_HEZE_SLOT = "INCLUSION_LIST_ERROR_PRE_HEZE_SLOT",
+}
+
+export type InclusionListErrorType =
+  | {code: InclusionListErrorCode.EMPTY_TRANSACTIONS}
+  | {code: InclusionListErrorCode.MAXIMUM_SIZE_EXCEEDED; totalBytes: number; maxBytes: number}
+  | {code: InclusionListErrorCode.EMPTY_TRANSACTION; transactionIndex: number}
+  | {code: InclusionListErrorCode.INVALID_SLOT; inclusionListSlot: Slot; currentSlot: Slot}
+  | {code: InclusionListErrorCode.MORE_THAN_TWO; validatorIndex: ValidatorIndex}
+  | {code: InclusionListErrorCode.VALIDATOR_NOT_IN_COMMITTEE; validatorIndex: ValidatorIndex}
+  | {code: InclusionListErrorCode.UNKNOWN_DEPENDENT_ROOT; dependentRoot: RootHex}
+  | {
+      code: InclusionListErrorCode.INVALID_DEPENDENT_ROOT_SLOT;
+      dependentRoot: RootHex;
+      dependentSlot: Slot;
+      maxSlot: Slot;
+    }
+  | {code: InclusionListErrorCode.INVALID_DEPENDENT_ROOT; dependentRoot: RootHex; epoch: Epoch}
+  | {code: InclusionListErrorCode.MISSING_SHUFFLING; dependentRoot: RootHex; epoch: Epoch}
+  | {code: InclusionListErrorCode.INVALID_SIGNATURE}
+  | {code: InclusionListErrorCode.PRE_HEZE_SLOT; inclusionListSlot: Slot};
+
+export class InclusionListError extends GossipActionError<InclusionListErrorType> {}

package/src/chain/errors/index.ts

@@ -8,6 +8,7 @@ export * from "./envelopeReconstructionError.js";
 export * from "./executionPayloadBid.js";
 export * from "./executionPayloadEnvelope.js";
 export * from "./gossipValidation.js";
+export * from "./inclusionList.js";
 export * from "./payloadAttestation.js";
 export * from "./proposerPreferences.js";
 export * from "./proposerSlashingError.js";

package/src/chain/interface.ts

@@ -49,6 +49,7 @@ import {
   AttestationPool,
   DeferredVoluntaryExitPool,
   ExecutionPayloadBidPool,
+  InclusionListStore,
   OpPool,
   PayloadAttestationPool,
   ProposerPreferencesPool,
@@ -131,6 +132,7 @@ export interface IBeaconChain {
   readonly executionPayloadBidPool: ExecutionPayloadBidPool;
   readonly payloadAttestationPool: PayloadAttestationPool;
   readonly proposerPreferencesPool: ProposerPreferencesPool;
+  readonly inclusionListStore: InclusionListStore;
   readonly opPool: OpPool;
   readonly deferredVoluntaryExitPool: DeferredVoluntaryExitPool;
 
@@ -331,6 +333,7 @@ export type SSZObjectType =
   | "syncCommittee"
   | "contributionAndProof";
 
-export type CommonBlockBody = phase0.BeaconBlockBody &
+export type CommonBlockBody = Omit<phase0.BeaconBlockBody, "eth1Data" | "deposits"> &
+  Partial<Pick<phase0.BeaconBlockBody, "eth1Data" | "deposits">> &
   Pick<capella.BeaconBlockBody, "blsToExecutionChanges"> &
   Pick<altair.BeaconBlockBody, "syncAggregate">;