@lodestar/fork-choice 1.51.0-dev.83da04fef3 → 1.51.0-dev.8d5cdd33be

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};
     }
 
@@ -675,7 +693,20 @@ export class ForkChoice implements IForkChoice {
     }
 
     // findHead returns the ProtoNode representing the head
-    const head = this.protoArray.findHead(this.fcStore.justified.checkpoint.rootHex, currentSlot);
+    let head: ProtoNode;
+    try {
+      head = this.protoArray.findHead(this.fcStore.justified.checkpoint.rootHex, currentSlot);
+    } catch (e) {
+      // A poisoned tree never recovers, shut the node down instead of failing every head computation
+      if (
+        e instanceof ProtoArrayError &&
+        (e.type.code === ProtoArrayErrorCode.INVALID_LVH_EXECUTION_RESPONSE ||
+          e.type.code === ProtoArrayErrorCode.INVALID_JUSTIFIED_EXECUTION_STATUS)
+      ) {
+        this.irrecoverableError = e;
+      }
+      throw e;
+    }
 
     this.head = head;
     return this.head;
@@ -735,12 +766,15 @@ export class ForkChoice implements IForkChoice {
    *
    * `justifiedBalances` balances of justified state which is updated synchronously.
    * This ensures that the forkchoice is never out of sync.
+   *
+   * A block whose parent payload chain was invalidated is rejected. `executionStatus` is ignored for a gloas
+   * block: it has no payload of its own and inherits the status of the parent variant it builds on.
    */
   onBlock(
     block: BeaconBlock,
     state: IBeaconStateView,
-    receiveDelaySec: number,
-    importDelaySec: number,
+    receiveDelayMs: number,
+    importDelayMs: number,
     currentSlot: Slot,
     executionStatus: BlockExecutionStatus,
     dataAvailabilityStatus: DataAvailabilityStatus
@@ -763,6 +797,19 @@ export class ForkChoice implements IForkChoice {
       });
     }
 
+    // An execution engine verdict can invalidate the parent while this block is being verified. Inserting the
+    // block would put a viable node below an invalidated one, or poison the tree if this block is VALID
+    if (parentBlock.executionStatus === ExecutionStatus.Invalid) {
+      throw new ForkChoiceError({
+        code: ForkChoiceErrorCode.INVALID_BLOCK,
+        err: {
+          code: InvalidBlockCode.PARENT_EXECUTION_INVALID,
+          root: parentRootHex,
+          hash: parentHashHex,
+        },
+      });
+    }
+
     // Blocks cannot be in the future. If they are, their consideration must be delayed until
     // the are in the past.
     //
@@ -812,7 +859,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 +878,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 +896,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 +935,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,
@@ -919,7 +971,9 @@ export class ForkChoice implements IForkChoice {
               executionPayloadBlockHash: parentBlockHashFromBid,
               executionPayloadNumber: parentMeta.number,
               executionPayloadGasLimit: parentMeta.gasLimit,
-              executionStatus: this.getPostMergeExecStatus(executionStatus),
+              // The parent's default (PENDING) variant does not reflect a SYNCING parent payload, inheriting
+              // from the variant matching the bid's parent block hash keeps that payload from being marked VALID
+              executionStatus: this.getPostMergeExecStatus(parentBlock.executionStatus),
               dataAvailabilityStatus,
             };
           })()
@@ -980,14 +1034,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.
@@ -1126,6 +1174,19 @@ export class ForkChoice implements IForkChoice {
     executionStatus: PayloadExecutionStatus,
     dataAvailabilityStatus: DataAvailabilityStatus
   ): void {
+    // Same guard as onBlock: the PENDING variant carries the status of the payload chain this block builds on
+    const pendingBlock = this.getBlockHexDefaultStatus(blockRoot);
+    if (pendingBlock?.executionStatus === ExecutionStatus.Invalid) {
+      throw new ForkChoiceError({
+        code: ForkChoiceErrorCode.INVALID_BLOCK,
+        err: {
+          code: InvalidBlockCode.PARENT_EXECUTION_INVALID,
+          root: pendingBlock.parentRoot,
+          hash: pendingBlock.executionPayloadBlockHash,
+        },
+      });
+    }
+
     this.protoArray.onExecutionPayload(
       blockRoot,
       this.fcStore.currentSlot,
@@ -1414,7 +1475,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 +1585,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 +1596,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);
       }
     }
@@ -1568,13 +1633,14 @@ export class ForkChoice implements IForkChoice {
    * justified's status as well as validate the terminal conditions if terminal block
    * becomes valid
    */
-  validateLatestHash(execResponse: LVHExecResponse): void {
+  validateLatestHash(execResponse: LVHExecResponse, opts?: {strict?: boolean}): boolean {
     try {
-      this.protoArray.validateLatestHash(execResponse, this.fcStore.currentSlot);
+      return this.protoArray.validateLatestHash(execResponse, this.fcStore.currentSlot, opts);
     } catch (e) {
       if (e instanceof ProtoArrayError && e.type.code === ProtoArrayErrorCode.INVALID_LVH_EXECUTION_RESPONSE) {
         this.irrecoverableError = e;
       }
+      return false;
     }
   }
 
@@ -1757,9 +1823,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 +1839,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 +1852,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 +1939,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;
   /**
@@ -155,12 +155,15 @@ export interface IForkChoice {
    * ## Notes:
    *
    * The supplied block **must** pass the `state_transition` function as it will not be run here.
+   *
+   * Throws `InvalidBlockCode.PARENT_EXECUTION_INVALID` if the parent payload chain was invalidated.
+   * `executionStatus` is ignored for a gloas block, it inherits the status of the parent variant it builds on.
    */
   onBlock(
     block: BeaconBlock,
     state: IBeaconStateView,
-    receiveDelaySec: number,
-    importDelaySec: number,
+    receiveDelayMs: number,
+    importDelayMs: number,
     currentSlot: Slot,
     executionStatus: BlockExecutionStatus,
     dataAvailabilityStatus: DataAvailabilityStatus
@@ -279,6 +282,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,14 +353,17 @@ 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;
   /**
-   * Optimistic sync validate till validated latest hash, invalidate any decendant branch if invalidated branch decendant provided
+   * Apply an execution engine verdict with a latest valid hash, see `ProtoArray.validateLatestHash`.
+   * Returns whether any execution status changed. A consensus failure is recorded in `irrecoverableError`.
    */
-  validateLatestHash(execResponse: LVHExecResponse): void;
+  validateLatestHash(execResponse: LVHExecResponse, opts?: {strict?: boolean}): boolean;
 
   /**
    * A dependent root is the block root of the last block before the state transition that decided a specific shuffling

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",
@@ -28,6 +32,11 @@ export function getForkChoiceMetrics(register: MetricsRegisterExtra) {
         name: "beacon_fork_choice_changed_head_total",
         help: "Count of occasions fork choice has found a new head",
       }),
+      executionInvalidations: register.gauge<{source: string}>({
+        name: "beacon_fork_choice_execution_invalidations_total",
+        help: "Count of execution engine INVALID verdicts applied to fork choice, by verdict source",
+        labelNames: ["source"],
+      }),
       reorg: register.gauge({
         name: "beacon_fork_choice_reorg_total",
         help: "Count of occasions fork choice has switched to a different chain",

package/src/protoArray/interface.ts

@@ -55,6 +55,8 @@ export function isGloasBlock(block: ProtoBlock): block is ProtoBlock & {parentBl
 export type LVHValidResponse = {
   executionStatus: ExecutionStatus.Valid;
   latestValidExecHash: RootHex;
+  /** Resolves the exact node to validate when several nodes carry the same payload hash (gloas variants) */
+  blockRoot?: RootHex;
 };
 export type LVHInvalidResponse = {
   executionStatus: ExecutionStatus.Invalid;