@lodestar/beacon-node 1.51.0-dev.75239241d4 → 1.51.0-dev.782eaff74d

package/src/chain/blocks/importBlock.ts

@@ -21,7 +21,7 @@ import {
   IBeaconStateView,
   RootCache,
   computeEpochAtSlot,
-  computeTimeAtSlot,
+  computeTimeAtSlotMs,
   getBeaconCommittees,
   isStatePostAltair,
   isStatePostBellatrix,
@@ -105,8 +105,9 @@ export async function importBlock(
   const currentEpoch = computeEpochAtSlot(currentSlot);
   const blockEpoch = computeEpochAtSlot(blockSlot);
   const prevFinalizedEpoch = this.forkChoice.getFinalizedCheckpoint().epoch;
-  const receiveDelaySec =
-    fullyVerifiedBlock.seenTimestampSec - computeTimeAtSlot(this.config, blockSlot, postState.genesisTime);
+  const receiveDelayMs =
+    Math.round(fullyVerifiedBlock.seenTimestampSec * 1000) -
+    computeTimeAtSlotMs(this.config, blockSlot, postState.genesisTime * 1000);
   const recvToValLatency = Date.now() / 1000 - (opts.seenTimestampSec ?? Date.now() / 1000);
   const fork = this.config.getForkSeq(blockSlot);
 
@@ -148,12 +149,12 @@ export async function importBlock(
     executionStatus = parentBlock.executionStatus;
   }
 
-  const importDelaySec = this.clock.secFromSlot(blockSlot);
+  const importDelayMs = this.clock.msFromSlot(blockSlot);
   const blockSummary = this.forkChoice.onBlock(
     block.message,
     postState,
-    receiveDelaySec,
-    importDelaySec,
+    receiveDelayMs,
+    importDelayMs,
     currentSlot,
     executionStatus,
     dataAvailabilityStatus
@@ -417,7 +418,7 @@ export async function importBlock(
         //  4) Block meets the criteria of being re-orged out (this is also checked inside the function)
         const result = this.forkChoice.shouldOverrideForkChoiceUpdate(
           blockSummary,
-          this.clock.secFromSlot(currentSlot),
+          this.clock.msFromSlot(currentSlot),
           currentSlot
         );
         shouldOverrideFcu = result.shouldOverrideFcu;
@@ -458,7 +459,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 +470,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

@@ -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

@@ -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);
@@ -1483,10 +1486,10 @@ export class BeaconChain implements IBeaconChain {
     this.metrics?.forkChoice.requests.inc();
     const timer = this.metrics?.forkChoice.findHead.startTimer({caller: FindHeadFnName.predictProposerHead});
     const slot = this.clock.currentSlot;
-    const secFromSlot = this.clock.secFromSlot(slot);
+    const msFromSlot = this.clock.msFromSlot(slot);
 
     try {
-      return this.forkChoice.updateAndGetHead({mode: UpdateHeadOpt.GetPredictedProposerHead, secFromSlot, slot}).head;
+      return this.forkChoice.updateAndGetHead({mode: UpdateHeadOpt.GetPredictedProposerHead, msFromSlot, slot}).head;
     } catch (e) {
       this.metrics?.forkChoice.errors.inc({entrypoint: UpdateHeadOpt.GetPredictedProposerHead});
       throw e;
@@ -1498,13 +1501,13 @@ export class BeaconChain implements IBeaconChain {
   getProposerHead(slot: Slot): ProtoBlock {
     this.metrics?.forkChoice.requests.inc();
     const timer = this.metrics?.forkChoice.findHead.startTimer({caller: FindHeadFnName.getProposerHead});
-    const secFromSlot = this.clock.secFromSlot(slot);
+    const msFromSlot = this.clock.msFromSlot(slot);
 
     try {
       // Do not emit head event here, when proposing we rely on the one emitted when importing our own block
       const {head, isHeadTimely, notReorgedReason} = this.forkChoice.updateAndGetHead({
         mode: UpdateHeadOpt.GetProposerHead,
-        secFromSlot,
+        msFromSlot,
         slot,
       });
 
@@ -1832,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);
 

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;
 

package/src/chain/opPools/inclusionListStore.ts

@@ -0,0 +1,208 @@
+import {BitArray, SerializedList} from "@chainsafe/ssz";
+import {BeaconConfig} from "@lodestar/config";
+import {INCLUSION_LIST_COMMITTEE_SIZE} from "@lodestar/params";
+import {RootHex, Slot, ValidatorIndex, bellatrix, heze, ssz} from "@lodestar/types";
+import {MapDef, toHex, toRootHex} from "@lodestar/utils";
+
+export enum InclusionListInsertOutcome {
+  /** Stored as a new entry. */
+  New = "New",
+  /** Slot is older than the prune horizon. */
+  Old = "Old",
+  /** Identical inclusion list already stored. */
+  Seen = "Seen",
+  /** New equivocation evidence: this validator already has a different inclusion list stored. */
+  Equivocating = "Equivocating",
+  /** Validator was already marked as an equivocator for this `(slot, dependent_root)`. */
+  SubsequentEquivocation = "SubsequentEquivocation",
+}
+
+type InclusionListEntry = {
+  signedInclusionList: heze.SignedInclusionList;
+  /** Positions of the validator in `get_inclusion_list_committee(state, slot)`, several when the committee cycles */
+  committeeIndices: number[];
+  /** Received before the inclusion list deadline of its slot. */
+  timely: boolean;
+};
+
+/**
+ * Spec `InclusionListStore`: inclusion lists keyed by `(slot, dependent_root)`, one per validator index.
+ * The committee position is recorded at insert time (gossip validation resolves it) so the bit-oriented
+ * reads need no shuffling lookup. Signed lists are kept so InclusionListsByIndices can serve them.
+ * A validator's first list stays stored and an equivocation marks the validator so reads skip it.
+ */
+export class InclusionListStore {
+  /** slot -> dependent_root -> validator index -> entry */
+  private readonly inclusionLists = new MapDef<Slot, MapDef<RootHex, Map<ValidatorIndex, InclusionListEntry>>>(
+    () => new MapDef<RootHex, Map<ValidatorIndex, InclusionListEntry>>(() => new Map())
+  );
+  /** slot -> dependent_root -> equivocating validator indices */
+  private readonly equivocators = new MapDef<Slot, MapDef<RootHex, Set<ValidatorIndex>>>(
+    () => new MapDef<RootHex, Set<ValidatorIndex>>(() => new Set())
+  );
+  /** slot -> dependent_root -> validator index -> count, for the p2p "first or second message" rule */
+  private readonly seenCounts = new MapDef<Slot, MapDef<RootHex, Map<ValidatorIndex, number>>>(
+    () => new MapDef<RootHex, Map<ValidatorIndex, number>>(() => new Map())
+  );
+
+  private lowestPermissibleSlot = 0;
+
+  constructor(private readonly config: BeaconConfig) {}
+
+  get size(): number {
+    let count = 0;
+    for (const byDependentRoot of this.inclusionLists.values()) {
+      for (const entries of byDependentRoot.values()) {
+        count += entries.size;
+      }
+    }
+    return count;
+  }
+
+  /**
+   * Late lists are stored with `timely=false` rather than dropped: they still count toward the
+   * non-timely view used to validate another node's `inclusion_list_bits`.
+   */
+  process(
+    signedInclusionList: heze.SignedInclusionList,
+    committeeIndices: number[],
+    timely: boolean
+  ): InclusionListInsertOutcome {
+    const inclusionList = signedInclusionList.message;
+    const {slot, validatorIndex} = inclusionList;
+
+    if (slot < this.lowestPermissibleSlot) {
+      return InclusionListInsertOutcome.Old;
+    }
+
+    const dependentRoot = toRootHex(inclusionList.dependentRoot);
+    const stored = this.inclusionLists.getOrDefault(slot).getOrDefault(dependentRoot);
+
+    const entry = stored.get(validatorIndex);
+    if (entry !== undefined) {
+      if (ssz.heze.InclusionList.equals(entry.signedInclusionList.message, inclusionList)) {
+        return InclusionListInsertOutcome.Seen;
+      }
+      const equivocators = this.equivocators.getOrDefault(slot).getOrDefault(dependentRoot);
+      if (equivocators.has(validatorIndex)) {
+        return InclusionListInsertOutcome.SubsequentEquivocation;
+      }
+      equivocators.add(validatorIndex);
+      return InclusionListInsertOutcome.Equivocating;
+    }
+
+    stored.set(validatorIndex, {signedInclusionList, committeeIndices, timely});
+    return InclusionListInsertOutcome.New;
+  }
+
+  /** Count a valid message of `validatorIndex` for the first-or-second message gossip rule */
+  markSeen(slot: Slot, dependentRoot: RootHex, validatorIndex: ValidatorIndex): void {
+    const counts = this.seenCounts.getOrDefault(slot).getOrDefault(dependentRoot);
+    counts.set(validatorIndex, (counts.get(validatorIndex) ?? 0) + 1);
+  }
+
+  /** Gossip rule: at most two valid messages per validator for a `(slot, dependent_root)` */
+  seenTwice(slot: Slot, dependentRoot: RootHex, validatorIndex: ValidatorIndex): boolean {
+    return (this.seenCounts.get(slot)?.get(dependentRoot)?.get(validatorIndex) ?? 0) >= 2;
+  }
+
+  /** Deduplicated transactions from valid, non-equivocating inclusion lists at `(slot, dependentRoot)`. */
+  getInclusionListTransactions(slot: Slot, dependentRoot: RootHex, onlyTimely = true): bellatrix.Transactions {
+    const transactions: Uint8Array[] = [];
+    const seen = new Set<string>();
+
+    for (const {signedInclusionList} of this.getEligible(slot, dependentRoot, onlyTimely)) {
+      for (const transaction of signedInclusionList.message.transactions) {
+        const key = toHex(transaction);
+        if (!seen.has(key)) {
+          seen.add(key);
+          transactions.push(transaction);
+        }
+      }
+    }
+
+    return SerializedList.fromArray(transactions);
+  }
+
+  /** Bit `i` is set when committee member `i` submitted a valid, non-equivocating inclusion list */
+  getInclusionListBits(slot: Slot, dependentRoot: RootHex, onlyTimely = true): BitArray {
+    const bits = BitArray.fromBitLen(INCLUSION_LIST_COMMITTEE_SIZE);
+    for (const {committeeIndices} of this.getEligible(slot, dependentRoot, onlyTimely)) {
+      for (const committeeIndex of committeeIndices) {
+        bits.set(committeeIndex, true);
+      }
+    }
+    return bits;
+  }
+
+  /**
+   * True if `bits` has a bit set for every bit set in the local inclusion list bits.
+   *
+   * Intentionally deviates from the spec by only checking against timely lists, where the proposer would check
+   * against every list it observed (only_timely=False in
+   * https://github.com/ethereum/consensus-specs/blob/v1.7.0-beta.4/specs/heze/validator.md#signed-execution-payload-bid).
+   * A bid that passed gossip must stay eligible, otherwise a list released after the deadline voids every bid and
+   * a high early bid with empty bits crowds out the rest without ever paying.
+   */
+  isInclusionListBitsInclusive(slot: Slot, dependentRoot: RootHex, bits: BitArray): boolean {
+    for (const {committeeIndices} of this.getEligible(slot, dependentRoot, true)) {
+      if (committeeIndices.some((committeeIndex) => !bits.get(committeeIndex))) {
+        return false;
+      }
+    }
+    return true;
+  }
+
+  /** Inclusion lists for the given committee positions, to serve InclusionListsByIndices. */
+  getByIndices(slot: Slot, dependentRoot: RootHex, indices: BitArray): heze.SignedInclusionList[] {
+    const out: heze.SignedInclusionList[] = [];
+    for (const {signedInclusionList, committeeIndices} of this.getEligible(slot, dependentRoot, false)) {
+      if (committeeIndices.some((committeeIndex) => indices.get(committeeIndex))) {
+        out.push(signedInclusionList);
+      }
+    }
+    return out;
+  }
+
+  /** Lists are retained for MIN_SLOTS_FOR_INCLUSION_LISTS_REQUESTS slots so InclusionListsByIndices can serve them */
+  prune(clockSlot: Slot): void {
+    const horizon = clockSlot - this.config.MIN_SLOTS_FOR_INCLUSION_LISTS_REQUESTS;
+
+    for (const slot of this.inclusionLists.keys()) {
+      if (slot < horizon) {
+        this.inclusionLists.delete(slot);
+      }
+    }
+    for (const slot of this.equivocators.keys()) {
+      if (slot < horizon) {
+        this.equivocators.delete(slot);
+      }
+    }
+    for (const slot of this.seenCounts.keys()) {
+      if (slot < horizon) {
+        this.seenCounts.delete(slot);
+      }
+    }
+
+    this.lowestPermissibleSlot = Math.max(horizon, 0);
+  }
+
+  /** Entries at `(slot, dependentRoot)` from non-equivocating validators, timely when required. */
+  private *getEligible(slot: Slot, dependentRoot: RootHex, onlyTimely: boolean): Generator<InclusionListEntry> {
+    const stored = this.inclusionLists.get(slot)?.get(dependentRoot);
+    if (!stored || stored.size === 0) {
+      return;
+    }
+    const equivocators = this.equivocators.get(slot)?.get(dependentRoot);
+
+    for (const [validatorIndex, entry] of stored) {
+      if (equivocators?.has(validatorIndex)) {
+        continue;
+      }
+      if (onlyTimely && !entry.timely) {
+        continue;
+      }
+      yield entry;
+    }
+  }
+}

package/src/chain/opPools/index.ts

@@ -2,6 +2,7 @@ export {AggregatedAttestationPool} from "./aggregatedAttestationPool.js";
 export {AttestationPool} from "./attestationPool.js";
 export {DeferredVoluntaryExitPool} from "./deferredVoluntaryExitPool.js";
 export {ExecutionPayloadBidPool, type PooledExecutionPayloadBid} from "./executionPayloadBidPool.js";
+export {InclusionListInsertOutcome, InclusionListStore} from "./inclusionListStore.js";
 export {OpPool} from "./opPool.js";
 export {PayloadAttestationPool} from "./payloadAttestationPool.js";
 export {ProposerPreferencesPool} from "./proposerPreferencesPool.js";