@lodestar/fork-choice 1.51.0-dev.837363b869 → 1.51.0-dev.83aae9f53e

package/src/forkChoice/forkChoice.ts

@@ -86,8 +86,8 @@ export enum UpdateHeadOpt {
 
 export type UpdateAndGetHeadOpt =
   | {mode: UpdateHeadOpt.GetCanonicalHead}
-  | {mode: UpdateHeadOpt.GetProposerHead; secFromSlot: number; slot: Slot}
-  | {mode: UpdateHeadOpt.GetPredictedProposerHead; secFromSlot: number; slot: Slot};
+  | {mode: UpdateHeadOpt.GetProposerHead; msFromSlot: number; slot: Slot}
+  | {mode: UpdateHeadOpt.GetPredictedProposerHead; msFromSlot: number; slot: Slot};
 
 // the initial vote epoch for all validators
 const INIT_VOTE_SLOT: Slot = 0;
@@ -315,13 +315,13 @@ export class ForkChoice implements IForkChoice {
     const canonicalHeadBlock = mode === UpdateHeadOpt.GetPredictedProposerHead ? this.getHead() : this.updateHead();
     switch (mode) {
       case UpdateHeadOpt.GetPredictedProposerHead:
-        return {head: this.predictProposerHead(canonicalHeadBlock, opt.secFromSlot, opt.slot)};
+        return {head: this.predictProposerHead(canonicalHeadBlock, opt.msFromSlot, opt.slot)};
       case UpdateHeadOpt.GetProposerHead: {
         const {
           proposerHead: head,
           isHeadTimely,
           notReorgedReason,
-        } = this.getProposerHead(canonicalHeadBlock, opt.secFromSlot, opt.slot);
+        } = this.getProposerHead(canonicalHeadBlock, opt.msFromSlot, opt.slot);
         return {head, isHeadTimely, notReorgedReason};
       }
       case UpdateHeadOpt.GetCanonicalHead:
@@ -338,7 +338,7 @@ export class ForkChoice implements IForkChoice {
   // Note when proposer boost reorg is disabled, it always returns false
   shouldOverrideForkChoiceUpdate(
     headBlock: ProtoBlock,
-    secFromSlot: number,
+    msFromSlot: number,
     currentSlot: Slot
   ): ShouldOverrideForkChoiceUpdateResult {
     if (headBlock === null) {
@@ -369,7 +369,7 @@ export class ForkChoice implements IForkChoice {
 
     const currentTimeOk =
       headBlock.slot === currentSlot ||
-      (proposalSlot === currentSlot && this.isProposingOnTime(secFromSlot, currentSlot));
+      (proposalSlot === currentSlot && this.isProposingOnTime(msFromSlot, currentSlot));
 
     // Mirror the proposer equivocation branch of getProposerHead(). The head slot's attestations are
     // still queued at this point so the head is assumed weak, same as for the regular branch below.
@@ -422,6 +422,24 @@ export class ForkChoice implements IForkChoice {
     return this.protoArray.shouldExtendPayload(blockRoot, this.proposerBoostRoot);
   }
 
+  /** Inclusion list verdict for the payload of `blockRoot`, as reported by the execution engine */
+  recordPayloadInclusionListSatisfaction(blockRoot: RootHex, satisfied: boolean): boolean {
+    const changed = this.protoArray.recordPayloadInclusionListSatisfaction(blockRoot, satisfied);
+    if (changed && !satisfied) {
+      this.metrics?.forkChoice.unsatisfiedInclusionListBlocks.inc();
+      this.logger?.verbose("Payload does not satisfy the inclusion list constraints, not extending it", {blockRoot});
+    }
+    return changed;
+  }
+
+  isPayloadInclusionListSatisfied(blockRoot: RootHex): boolean {
+    return this.protoArray.isPayloadInclusionListSatisfied(blockRoot);
+  }
+
+  getPayloadInclusionListSatisfaction(blockRoot: RootHex): boolean | null {
+    return this.protoArray.getPayloadInclusionListSatisfaction(blockRoot);
+  }
+
   /** Spec: should_build_on_full(store, head, slot) */
   shouldBuildOnFull(head: ProtoBlock, slot: Slot): boolean {
     return this.protoArray.shouldBuildOnFull(head, slot);
@@ -437,7 +455,7 @@ export class ForkChoice implements IForkChoice {
    * By calling this function, we assume we are the proposer of next slot
    *
    */
-  predictProposerHead(headBlock: ProtoBlock, secFromSlot: number, currentSlot: Slot): ProtoBlock {
+  predictProposerHead(headBlock: ProtoBlock, msFromSlot: number, currentSlot: Slot): ProtoBlock {
     const {proposerBoost, proposerBoostReorg} = this.opts ?? {};
     // Skip re-org attempt if proposer boost (reorg) are disabled
     if (!proposerBoost || !proposerBoostReorg) {
@@ -450,7 +468,7 @@ export class ForkChoice implements IForkChoice {
     }
 
     const blockRoot = headBlock.blockRoot;
-    const result = this.shouldOverrideForkChoiceUpdate(headBlock, secFromSlot, currentSlot);
+    const result = this.shouldOverrideForkChoiceUpdate(headBlock, msFromSlot, currentSlot);
 
     if (result.shouldOverrideFcu) {
       this.logger?.verbose("Current head is weak. Predicting next block to be built on parent of head.", {
@@ -481,7 +499,7 @@ export class ForkChoice implements IForkChoice {
    */
   getProposerHead(
     headBlock: ProtoBlock,
-    secFromSlot: number,
+    msFromSlot: number,
     slot: Slot
   ): {proposerHead: ProtoBlock; isHeadTimely: boolean; notReorgedReason?: NotReorgedReason} {
     const isHeadTimely = headBlock.timeliness;
@@ -538,7 +556,7 @@ export class ForkChoice implements IForkChoice {
     }
 
     // Only re-org if we are proposing on-time
-    if (!this.isProposingOnTime(secFromSlot, slot)) {
+    if (!this.isProposingOnTime(msFromSlot, slot)) {
       return {proposerHead, isHeadTimely, notReorgedReason: NotReorgedReason.NotProposingOnTime};
     }
 
@@ -739,8 +757,8 @@ export class ForkChoice implements IForkChoice {
   onBlock(
     block: BeaconBlock,
     state: IBeaconStateView,
-    receiveDelaySec: number,
-    importDelaySec: number,
+    receiveDelayMs: number,
+    importDelayMs: number,
     currentSlot: Slot,
     executionStatus: BlockExecutionStatus,
     dataAvailabilityStatus: DataAvailabilityStatus
@@ -812,7 +830,7 @@ export class ForkChoice implements IForkChoice {
     // Decide whether this block should receive proposer boost, and whether the block is timely.
     // The store field `this.proposerBoostRoot` and `updateCheckpoints()` are mutated only after
     // `protoArray.onBlock()` succeeds
-    const isTimely = this.isBlockReceivedTimely(block, receiveDelaySec);
+    const isTimely = this.isBlockReceivedTimely(block, receiveDelayMs);
     const isProposerBoostBlock =
       this.opts?.proposerBoost === true &&
       isTimely &&
@@ -831,14 +849,17 @@ export class ForkChoice implements IForkChoice {
     const blockEpoch = computeEpochAtSlot(slot);
 
     // same logic to compute_pulled_up_tip in the spec, making it inline because of reusing variables
-    // If the parent checkpoints are already at the same epoch as the block being imported,
-    // it's impossible for the unrealized checkpoints to differ from the parent's. This
-    // holds true because:
+    // If the block has no slashings and the parent checkpoints are already at the same epoch as the
+    // block being imported, it's impossible for the unrealized checkpoints to differ from the parent's.
+    // This holds true because:
     //
     // 1. A child block cannot have lower FFG checkpoints than its parent.
     // 2. A block in epoch `N` cannot contain attestations which would justify an epoch higher than `N`.
     // 3. A block in epoch `N` cannot contain attestations which would finalize an epoch higher than `N - 1`.
     //
+    // Slashings are excluded because they can reduce the unslashed target balance of the child state
+    // and therefore lower its unrealized checkpoints.
+    //
     // This is an optimization. It should reduce the amount of times we run
     // `process_justification_and_finalization` by approximately 1/3rd when the chain is
     // performing optimally.
@@ -846,6 +867,8 @@ export class ForkChoice implements IForkChoice {
     let unrealizedFinalizedCheckpoint: CheckpointWithHex;
     if (this.opts?.computeUnrealized) {
       if (
+        block.body.proposerSlashings.length === 0 &&
+        block.body.attesterSlashings.length === 0 &&
         parentBlock.unrealizedJustifiedEpoch === blockEpoch &&
         parentBlock.unrealizedFinalizedEpoch + 1 >= blockEpoch
       ) {
@@ -883,8 +906,8 @@ export class ForkChoice implements IForkChoice {
       targetRoot: toRootHex(targetRoot),
       stateRoot: toRootHex(block.stateRoot),
       timeliness: isTimely,
-      ptcTimeliness: this.isBlockPtcTimely(block, receiveDelaySec),
-      importedTimely: this.isBlockImportedTimely(block, importDelaySec),
+      ptcTimeliness: this.isBlockPtcTimely(block, receiveDelayMs),
+      importedTimely: this.isBlockImportedTimely(block, importDelayMs),
       proposerIndex: block.proposerIndex,
 
       justifiedEpoch: stateJustifiedEpoch,
@@ -980,14 +1003,8 @@ export class ForkChoice implements IForkChoice {
    *
    * https://github.com/ethereum/consensus-specs/blob/v1.1.10/specs/phase0/fork-choice.md#on_attestation
    *
-   * It only approximates the specification since it does not perform
-   * `is_valid_indexed_attestation` since that should already have been called upstream and it's
-   * too expensive to call again.
-   *
-   * ## Notes:
-   *
-   * The supplied `attestation` **must** pass the `in_valid_indexed_attestation` function as it
-   * will not be run here.
+   * Does not run `is_valid_indexed_attestation`. The caller must ensure all of its
+   * validity requirements except index ordering: `attestingIndices` may be unsorted.
    */
   onAttestation(attestation: IndexedAttestation, attDataRoot: string, forceImport?: boolean): void {
     // Ignore any attestations to the zero hash.
@@ -1414,7 +1431,9 @@ export class ForkChoice implements IForkChoice {
    *
    * `ancestors` is the raw walk and includes the previous finalized block as its last element —
    * callers that don't want the boundary should slice it off themselves.
-   * Post-gloas for each block root, it returns exactly one variant of it.
+   * For Gloas parent blocks, `ancestors` contains the selected EMPTY or FULL variant.
+   * The other variant, if present in the traversed range, goes into `nonAncestors` with the same root.
+   * Exclude roots present in `ancestors` before pruning by block root.
    */
   getAllAncestorAndNonAncestorBlocks(
     blockRoot: RootHex,
@@ -1522,7 +1541,9 @@ export class ForkChoice implements IForkChoice {
 
   /** Very expensive function, iterates the entire ProtoArray. TODO: Is this function even necessary? */
   getBlockSummariesByParentRoot(parentRoot: RootHex): ProtoBlock[] {
-    return this.protoArray.nodes.filter((node) => node.parentRoot === parentRoot);
+    return this.protoArray.nodes.filter(
+      (node) => node.parentRoot === parentRoot && (!isGloasBlock(node) || node.payloadStatus === PayloadStatus.PENDING)
+    );
   }
 
   /** Very expensive function, iterates the entire ProtoArray. TODO: Is this function even necessary? */
@@ -1531,7 +1552,7 @@ export class ForkChoice implements IForkChoice {
     const blocksAtSlot: ProtoBlock[] = [];
     for (let i = 0, len = nodes.length; i < len; i++) {
       const node = nodes[i];
-      if (node.slot === slot) {
+      if (node.slot === slot && (!isGloasBlock(node) || node.payloadStatus === PayloadStatus.PENDING)) {
         blocksAtSlot.push(node);
       }
     }
@@ -1757,9 +1778,9 @@ export class ForkChoice implements IForkChoice {
    * Return true if the block is timely for the current slot.
    * Child class can overwrite this for testing purpose.
    */
-  protected isBlockReceivedTimely(block: BeaconBlock, blockDelaySec: number): boolean {
+  protected isBlockReceivedTimely(block: BeaconBlock, blockDelayMs: number): boolean {
     const fork = this.config.getForkName(block.slot);
-    const isBeforeLateBlockCutoff = blockDelaySec * 1000 < this.config.getAttestationDueMs(fork);
+    const isBeforeLateBlockCutoff = blockDelayMs < this.config.getAttestationDueMs(fork);
     return this.fcStore.currentSlot === block.slot && isBeforeLateBlockCutoff;
   }
 
@@ -1773,12 +1794,12 @@ export class ForkChoice implements IForkChoice {
    *
    * Child class can overwrite this for testing purpose.
    */
-  protected isBlockPtcTimely(block: BeaconBlock, blockDelaySec: number): boolean {
+  protected isBlockPtcTimely(block: BeaconBlock, blockDelayMs: number): boolean {
     const ptcThresholdMs = this.config.getSlotComponentDurationMs(
       this.config.getForkName(block.slot),
       this.config.PAYLOAD_ATTESTATION_DUE_BPS
     );
-    return this.fcStore.currentSlot === block.slot && blockDelaySec * 1000 < ptcThresholdMs;
+    return this.fcStore.currentSlot === block.slot && blockDelayMs < ptcThresholdMs;
   }
 
   /**
@@ -1786,9 +1807,9 @@ export class ForkChoice implements IForkChoice {
    * block was imported in a timely manner for its own slot.
    * This is not part of the spec, we use this to determine late canonical blocks.
    */
-  protected isBlockImportedTimely(block: BeaconBlock, importDelaySec: number): boolean {
+  protected isBlockImportedTimely(block: BeaconBlock, importDelayMs: number): boolean {
     const fork = this.config.getForkName(block.slot);
-    const isBeforeLateBlockCutoff = importDelaySec * 1000 < this.config.getAttestationDueMs(fork);
+    const isBeforeLateBlockCutoff = importDelayMs < this.config.getAttestationDueMs(fork);
     return this.fcStore.currentSlot === block.slot && isBeforeLateBlockCutoff;
   }
 
@@ -1873,10 +1894,10 @@ export class ForkChoice implements IForkChoice {
   /**
    * https://github.com/ethereum/consensus-specs/blob/v1.5.0/specs/phase0/fork-choice.md#is_proposing_on_time
    */
-  private isProposingOnTime(secFromSlot: number, slot: Slot): boolean {
+  private isProposingOnTime(msFromSlot: number, slot: Slot): boolean {
     const fork = this.config.getForkName(slot);
     const proposerReorgCutoff = this.config.getProposerReorgCutoffMs(fork);
-    return secFromSlot * 1000 <= proposerReorgCutoff;
+    return msFromSlot <= proposerReorgCutoff;
   }
 
   private getPreMergeExecStatus(executionStatus: BlockExecutionStatus): ExecutionStatus.PreMerge {

package/src/forkChoice/interface.ts

@@ -123,7 +123,7 @@ export interface IForkChoice {
    */
   shouldOverrideForkChoiceUpdate(
     headBlock: ProtoBlock,
-    secFromSlot: number,
+    msFromSlot: number,
     currentSlot: Slot
   ): ShouldOverrideForkChoiceUpdateResult;
   /**
@@ -159,8 +159,8 @@ export interface IForkChoice {
   onBlock(
     block: BeaconBlock,
     state: IBeaconStateView,
-    receiveDelaySec: number,
-    importDelaySec: number,
+    receiveDelayMs: number,
+    importDelayMs: number,
     currentSlot: Slot,
     executionStatus: BlockExecutionStatus,
     dataAvailabilityStatus: DataAvailabilityStatus
@@ -279,6 +279,12 @@ export interface IForkChoice {
   shouldExtendPayload(blockRoot: RootHex): boolean;
   /** Spec: should_build_on_full(store, head, slot) */
   shouldBuildOnFull(head: ProtoBlock, slot: Slot): boolean;
+  /** Inclusion list verdict for the payload of `blockRoot`, as reported by the execution engine. True if it changed */
+  recordPayloadInclusionListSatisfaction(blockRoot: RootHex, satisfied: boolean): boolean;
+  /** True once the payload is delivered and not recorded unsatisfied */
+  isPayloadInclusionListSatisfied(blockRoot: RootHex): boolean;
+  /** Engine verdict recorded for the payload of `blockRoot`, null when none was recorded */
+  getPayloadInclusionListSatisfaction(blockRoot: RootHex): boolean | null;
   getFinalizedBlock(): ProtoBlock;
   getJustifiedBlock(): ProtoBlock;
   getFinalizedCheckpointSlot(): Slot;
@@ -344,7 +350,9 @@ export interface IForkChoice {
    * `CheckpointWithHex` / finalized root without a specific payload-status variant in mind.
    */
   forwardIterateDescendantsDefaultStatus(blockRoot: RootHex): IterableIterator<ProtoBlock>;
+  /** One summary per block, its default variant (FULL pre-Gloas, PENDING for Gloas) */
   getBlockSummariesByParentRoot(parentRoot: RootHex): ProtoBlock[];
+  /** One summary per block, its default variant (FULL pre-Gloas, PENDING for Gloas) */
   getBlockSummariesAtSlot(slot: Slot): ProtoBlock[];
   /** Returns the distance of common ancestor of nodes to the max of the newNode and the prevNode. */
   getCommonAncestorDepth(prevBlock: ProtoBlock, newBlock: ProtoBlock): AncestorResult;

package/src/metrics.ts

@@ -19,6 +19,10 @@ export function getForkChoiceMetrics(register: MetricsRegisterExtra) {
         name: "beacon_fork_choice_requests_total",
         help: "Count of occasions where fork choice has tried to find a head",
       }),
+      unsatisfiedInclusionListBlocks: register.gauge({
+        name: "beacon_fork_choice_unsatisfied_inclusion_list_blocks_total",
+        help: "Count of payloads not extended because they did not satisfy the inclusion list constraints",
+      }),
       errors: register.gauge<{entrypoint: UpdateHeadOpt}>({
         name: "beacon_fork_choice_errors_total",
         help: "Count of occasions where fork choice has returned an error when trying to find a head",

package/src/protoArray/protoArray.ts

@@ -122,6 +122,11 @@ export class ProtoArray {
    * when called with the negative parameter value.
    */
   private ptcAttested = new Map<RootHex, BitArray>();
+  /**
+   * Execution engine inclusion list verdict per block, recorded on payload import from heze.
+   * Spec: heze/fork-choice.md#modified-store (payload_inclusion_list_satisfaction)
+   */
+  private payloadInclusionListSatisfaction = new Map<RootHex, boolean>();
 
   constructor({
     pruneThreshold,
@@ -938,6 +943,27 @@ export class ProtoArray {
     return this.getParentPayloadStatus(block) === PayloadStatus.FULL;
   }
 
+  /** Spec: heze/fork-choice.md#new-record_payload_inclusion_list_satisfaction. Returns whether the verdict changed */
+  recordPayloadInclusionListSatisfaction(blockRoot: RootHex, satisfied: boolean): boolean {
+    const previous = this.payloadInclusionListSatisfaction.get(blockRoot);
+    this.payloadInclusionListSatisfaction.set(blockRoot, satisfied);
+    return previous !== satisfied;
+  }
+
+  /**
+   * Spec: heze/fork-choice.md#new-is_payload_inclusion_list_satisfied
+   *
+   * False until the payload is delivered. A delivered payload without a verdict is pre-heze, where
+   * no inclusion list constraints apply.
+   */
+  isPayloadInclusionListSatisfied(blockRoot: RootHex): boolean {
+    return this.hasPayload(blockRoot) && this.payloadInclusionListSatisfaction.get(blockRoot) !== false;
+  }
+
+  getPayloadInclusionListSatisfaction(blockRoot: RootHex): boolean | null {
+    return this.payloadInclusionListSatisfaction.get(blockRoot) ?? null;
+  }
+
   /**
    * Determine if we should extend the payload (prefer FULL over EMPTY)
    * Spec: gloas/fork-choice.md#new-should_extend_payload
@@ -956,6 +982,10 @@ export class ProtoArray {
       return false;
     }
 
+    if (this.payloadInclusionListSatisfaction.get(blockRoot) === false) {
+      return false;
+    }
+
     // Condition 1: Payload is timely AND data is available
     if (this.isPayloadTimely(blockRoot) && this.isPayloadDataAvailable(blockRoot)) {
       return true;
@@ -1265,6 +1295,15 @@ export class ProtoArray {
 
     // For Gloas: check if from previous slot
     if (node.slot + 1 !== currentSlot) {
+      // During the block's own slot a payload known to not satisfy the inclusion list
+      // constraints ranks below its EMPTY variant, as it will from the next slot on
+      if (
+        node.slot === currentSlot &&
+        node.payloadStatus === PayloadStatus.FULL &&
+        this.payloadInclusionListSatisfaction.get(node.blockRoot) === false
+      ) {
+        return PayloadStatus.PENDING;
+      }
       return node.payloadStatus;
     }
 
@@ -1399,6 +1438,7 @@ export class ProtoArray {
       this.payloadTimelinessVotes.delete(root);
       this.ptcAttested.delete(root);
       this.payloadDataAvailabilityVotes.delete(root);
+      this.payloadInclusionListSatisfaction.delete(root);
     }
 
     // Store nodes prior to finalization