@lodestar/fork-choice 1.47.0-dev.4546ac1229 → 1.47.0-dev.467f8a72f2

package/package.json

@@ -11,7 +11,7 @@
   "bugs": {
     "url": "https://github.com/ChainSafe/lodestar/issues"
   },
-  "version": "1.47.0-dev.4546ac1229",
+  "version": "1.47.0-dev.467f8a72f2",
   "type": "module",
   "exports": {
     ".": {
@@ -39,12 +39,12 @@
     "check-readme": "pnpm exec tsx ../../scripts/check_readme.ts"
   },
   "dependencies": {
-    "@chainsafe/ssz": "^1.6.2",
-    "@lodestar/config": "^1.47.0-dev.4546ac1229",
-    "@lodestar/params": "^1.47.0-dev.4546ac1229",
-    "@lodestar/state-transition": "^1.47.0-dev.4546ac1229",
-    "@lodestar/types": "^1.47.0-dev.4546ac1229",
-    "@lodestar/utils": "^1.47.0-dev.4546ac1229"
+    "@chainsafe/ssz": "^1.6.3",
+    "@lodestar/config": "^1.47.0-dev.467f8a72f2",
+    "@lodestar/params": "^1.47.0-dev.467f8a72f2",
+    "@lodestar/state-transition": "^1.47.0-dev.467f8a72f2",
+    "@lodestar/types": "^1.47.0-dev.467f8a72f2",
+    "@lodestar/utils": "^1.47.0-dev.467f8a72f2"
   },
   "keywords": [
     "ethereum",
@@ -52,5 +52,5 @@
     "beacon",
     "blockchain"
   ],
-  "gitHead": "31803130df8f6b6df2ceb25881cacc72aedc3fae"
+  "gitHead": "d1ecccd7a8a218fbd449653fcb7c4cbf6b78ff9b"
 }

package/src/forkChoice/forkChoice.ts

@@ -365,6 +365,21 @@ export class ForkChoice implements IForkChoice {
       return {shouldOverrideFcu: false, reason: NotReorgedReason.ParentBlockNotAvailable};
     }
 
+    const currentTimeOk =
+      headBlock.slot === currentSlot ||
+      (proposalSlot === currentSlot && this.isProposingOnTime(secFromSlot, 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.
+    if (currentTimeOk && this.isProposerEquivocation(headBlock)) {
+      this.logger?.verbose("Head proposer equivocated. Should override forkchoice update", {
+        blockRoot: headBlock.blockRoot,
+        slot: currentSlot,
+        proposerIndex: headBlock.proposerIndex,
+      });
+      return {shouldOverrideFcu: true, parentBlock};
+    }
+
     const {prelimProposerHead, prelimNotReorgedReason} = this.getPreliminaryProposerHead(
       headBlock,
       parentBlock,
@@ -375,9 +390,6 @@ export class ForkChoice implements IForkChoice {
       return {shouldOverrideFcu: false, reason: prelimNotReorgedReason ?? NotReorgedReason.Unknown};
     }
 
-    const currentTimeOk =
-      headBlock.slot === currentSlot ||
-      (proposalSlot === currentSlot && this.isProposingOnTime(secFromSlot, currentSlot));
     if (!currentTimeOk) {
       return {shouldOverrideFcu: false, reason: NotReorgedReason.ReorgMoreThanOneSlot};
     }
@@ -462,7 +474,8 @@ export class ForkChoice implements IForkChoice {
    * https://github.com/ethereum/consensus-specs/pull/3034 for info about proposer boost reorg
    * This function should only be called during block proposal and only be called after `updateHead()` in `updateAndGetHead()`
    *
-   * Same as https://github.com/ethereum/consensus-specs/blob/v1.4.0-beta.4/specs/phase0/fork-choice.md#get_proposer_head
+   * https://github.com/ethereum/consensus-specs/blob/v1.7.0-alpha.14/specs/phase0/fork-choice.md#get_proposer_head
+   * https://github.com/ethereum/consensus-specs/blob/v1.7.0-alpha.14/specs/gloas/fork-choice.md#modified-get_proposer_head
    */
   getProposerHead(
     headBlock: ProtoBlock,
@@ -493,6 +506,29 @@ export class ForkChoice implements IForkChoice {
       return {proposerHead, isHeadTimely, notReorgedReason: NotReorgedReason.ParentBlockNotAvailable};
     }
 
+    // Half of single_slot_reorg check in the spec is done in getPreliminaryProposerHead()
+    const currentTimeOk = headBlock.slot + 1 === slot;
+    const isProposerBoostWornOff = this.proposerBoostRoot !== headBlock.blockRoot;
+
+    // Re-org more aggressively if there is a proposer equivocation in the previous slot, skipping the
+    // regular reorg conditions. Any known equivocation counts here, timely or not.
+    if (
+      currentTimeOk &&
+      isProposerBoostWornOff &&
+      this.isProposerEquivocation(headBlock) &&
+      this.isHeadWeak(headBlock.blockRoot)
+    ) {
+      this.logger?.verbose("Performing single-slot reorg to remove weak head of equivocating proposer", {
+        slot,
+        proposerHead: parentBlock.blockRoot,
+        weakHead: headBlock.blockRoot,
+        proposerIndex: headBlock.proposerIndex,
+      });
+      proposerHead = parentBlock;
+
+      return {proposerHead, isHeadTimely};
+    }
+
     const {prelimProposerHead, prelimNotReorgedReason} = this.getPreliminaryProposerHead(headBlock, parentBlock, slot);
 
     if (prelimProposerHead === headBlock && prelimNotReorgedReason !== undefined) {
@@ -505,14 +541,11 @@ export class ForkChoice implements IForkChoice {
     }
 
     // No reorg if attempted reorg is more than a single slot
-    // Half of single_slot_reorg check in the spec is done in getPreliminaryProposerHead()
-    const currentTimeOk = headBlock.slot + 1 === slot;
     if (!currentTimeOk) {
       return {proposerHead, isHeadTimely, notReorgedReason: NotReorgedReason.ReorgMoreThanOneSlot};
     }
 
     // No reorg if proposer boost is still in effect
-    const isProposerBoostWornOff = this.proposerBoostRoot !== headBlock.blockRoot;
     if (!isProposerBoostWornOff) {
       return {proposerHead, isHeadTimely, notReorgedReason: NotReorgedReason.ProposerBoostNotWornOff};
     }
@@ -591,32 +624,48 @@ export class ForkChoice implements IForkChoice {
     computeDeltasMetrics?.newVoteValidators.set(newVoteValidators);
 
     this.balances = newBalances;
-    /**
-     * The structure in line with deltas to propagate boost up the branch
-     * starting from the proposerIndex
-     */
-    let proposerBoost: {root: RootHex; score: bigint} | null = null;
-    if (this.opts?.proposerBoost && this.proposerBoostRoot) {
-      const proposerBoostScore =
-        this.justifiedProposerBoostScore ??
-        getCommitteeFraction(this.fcStore.justified.totalBalance, {
-          slotsPerEpoch: SLOTS_PER_EPOCH,
-          committeePercent: this.config.PROPOSER_SCORE_BOOST,
-        });
-      proposerBoost = {root: this.proposerBoostRoot, score: proposerBoostScore};
-      this.justifiedProposerBoostScore = proposerBoostScore;
-    }
 
     const currentSlot = this.fcStore.currentSlot;
-    this.protoArray.applyScoreChanges({
-      attestationDeltas,
-      proposerBoost,
+    const checkpoints = {
       justifiedEpoch: this.fcStore.justified.checkpoint.epoch,
       justifiedRoot: this.fcStore.justified.checkpoint.rootHex,
       finalizedEpoch: this.fcStore.finalizedCheckpoint.epoch,
       finalizedRoot: this.fcStore.finalizedCheckpoint.rootHex,
       currentSlot,
-    });
+    };
+
+    const boostedBlock =
+      this.opts?.proposerBoost && this.proposerBoostRoot ? this.getBlockHexDefaultStatus(this.proposerBoostRoot) : null;
+
+    if (boostedBlock && isGloasBlock(boostedBlock)) {
+      // should_apply_proposer_boost judges the parent against the attestations known to the store,
+      // via is_head_weak (which also assumes equivocators' votes were already discounted before
+      // their balance is added back). Apply the attestation deltas first so the decision reads
+      // post-delta scores, then apply the boost in a second pass.
+      // TODO GLOAS: applyScoreChanges() updates weights and best child/descendant in one call;
+      // splitting them would let the two passes update weights and recompute best child/descendant
+      // once at the end.
+      // https://github.com/ethereum/consensus-specs/blob/v1.7.0-alpha.14/specs/gloas/fork-choice.md#new-should_apply_proposer_boost
+      this.protoArray.applyScoreChanges({attestationDeltas, proposerBoost: null, ...checkpoints});
+      const proposerBoost = this.shouldApplyProposerBoost() ? this.getProposerBoost() : null;
+      // The first pass already rolled back the previous boost and left a coherent tree, so a
+      // withheld boost needs no second pass
+      if (proposerBoost !== null) {
+        this.protoArray.applyScoreChanges({
+          attestationDeltas: new Array<number>(this.protoArray.nodes.length).fill(0),
+          proposerBoost,
+          ...checkpoints,
+        });
+      }
+    } else {
+      // Pre-gloas the boost is unconditional, so attestation deltas and boost deltas can propagate
+      // up the branch in a single pass
+      this.protoArray.applyScoreChanges({
+        attestationDeltas,
+        proposerBoost: boostedBlock ? this.getProposerBoost() : null,
+        ...checkpoints,
+      });
+    }
 
     // findHead returns the ProtoNode representing the head
     const head = this.protoArray.findHead(this.fcStore.justified.checkpoint.rootHex, currentSlot);
@@ -826,6 +875,8 @@ export class ForkChoice implements IForkChoice {
       targetRoot: toRootHex(targetRoot),
       stateRoot: toRootHex(block.stateRoot),
       timeliness: isTimely,
+      ptcTimeliness: this.isBlockPtcTimely(block, blockDelaySec),
+      proposerIndex: block.proposerIndex,
 
       justifiedEpoch: stateJustifiedEpoch,
       justifiedRoot: toRootHex(state.currentJustifiedCheckpoint.root),
@@ -1078,11 +1129,20 @@ export class ForkChoice implements IForkChoice {
     while (this.fcStore.currentSlot < currentSlot) {
       const previousSlot = this.fcStore.currentSlot;
       // Note: we are relying upon `onTick` to update `fcStore.time` to ensure we don't get stuck in a loop.
-      this.onTick(previousSlot + 1);
+      const didUpdateCheckpoints = this.onTick(previousSlot + 1);
       this.queuedAttestationsPreviousSlot = 0;
       // Process any attestations that might now be eligible before running FCR for this slot.
       this.processAttestationQueue();
-      this.runFastConfirmation();
+      const didRecomputeHead = this.runFastConfirmation();
+
+      // An epoch-boundary checkpoint pull-up can move the head's dependent root and stale the cached
+      // head before block 0 of the new epoch is imported, making isProposerBoostSameDependentRoot()
+      // wrong for that block. Recompute the head so it reflects the new checkpoint and the queued
+      // votes — unless fast confirmation already did, to avoid a redundant head calculation.
+      if (didUpdateCheckpoints && !didRecomputeHead) {
+        this.updateHead();
+      }
+
       this.validatedAttestationDatas = new Set();
     }
   }
@@ -1593,7 +1653,8 @@ export class ForkChoice implements IForkChoice {
     // Only ever called on a block already in fork choice, so a miss is a broken invariant.
     const node = this.protoArray.getNodeDefaultStatus(blockRoot);
     if (node === undefined) {
-      // this is called for head so we should always have this in forkchoice, otherwise we have a serious error
+      // this is called for head or the boosted block's parent, both of which should always be
+      // in forkchoice, otherwise we have a serious error
       throw new ForkChoiceError({code: ForkChoiceErrorCode.MISSING_PROTO_ARRAY_BLOCK, root: blockRoot});
     }
 
@@ -1613,7 +1674,7 @@ export class ForkChoice implements IForkChoice {
     // always 0. Return before fetching the state and walking the block's committees.
     if (equivocatingIndices.size > 0) {
       const state = this.fcStore.stateGetter({stateRoot: node.stateRoot});
-      // Only ever called on the head, so the state is always cached.
+      // Only ever called on the head or the boosted block's parent, so the state is always cached.
       // A miss is a broken invariant, not a recoverable state.
       if (state === null) {
         throw new ForkChoiceError({
@@ -1676,6 +1737,99 @@ export class ForkChoice implements IForkChoice {
     return this.fcStore.currentSlot === block.slot && isBeforeLateBlockCutoff;
   }
 
+  /**
+   * Return true if the block arrived before the PTC (payload-timeliness committee) deadline,
+   * ie. block_timeliness[PTC_TIMELINESS_INDEX]. should_apply_proposer_boost uses this as the
+   * definition of an "early" proposer equivocation: only a sibling seen by the PTC deadline
+   * proves the proposer equivocated soon enough that honest nodes could have withheld the boost.
+   *
+   * https://github.com/ethereum/consensus-specs/blob/v1.7.0-alpha.14/specs/gloas/fork-choice.md#modified-record_block_timeliness
+   *
+   * Child class can overwrite this for testing purpose.
+   */
+  protected isBlockPtcTimely(block: BeaconBlock, blockDelaySec: number): boolean {
+    const ptcThresholdMs = this.config.getSlotComponentDurationMs(this.config.PAYLOAD_ATTESTATION_DUE_BPS);
+    return this.fcStore.currentSlot === block.slot && blockDelaySec * 1000 < ptcThresholdMs;
+  }
+
+  /**
+   * Determine whether proposer boost should be applied to `proposerBoostRoot`.
+   *
+   * https://github.com/ethereum/consensus-specs/blob/v1.7.0-alpha.14/specs/gloas/fork-choice.md#new-should_apply_proposer_boost
+   *
+   * Pre-gloas blocks always receive the boost (unconditional, backward compatible). For gloas
+   * blocks the boost is withheld when the parent is a weak block from the previous slot and the
+   * proposer of that parent equivocated (published another PTC-timely block at the same slot).
+   */
+  private shouldApplyProposerBoost(): boolean {
+    if (!this.proposerBoostRoot) {
+      return false;
+    }
+
+    const boostedBlock = this.getBlockHexDefaultStatus(this.proposerBoostRoot);
+    // Pre-gloas blocks always get boost
+    if (!boostedBlock || !isGloasBlock(boostedBlock)) {
+      return true;
+    }
+
+    const parentBlock = this.getBlockHexDefaultStatus(boostedBlock.parentRoot);
+    if (!parentBlock) {
+      return true;
+    }
+
+    // Apply proposer boost if parent is not from the previous slot
+    if (parentBlock.slot + 1 < boostedBlock.slot) {
+      return true;
+    }
+
+    // Apply proposer boost if parent is not weak
+    if (!this.isHeadWeak(parentBlock.blockRoot)) {
+      return true;
+    }
+
+    // Parent is weak and from the previous slot: apply boost only if there are no early
+    // equivocations, ie. no other PTC-timely block at the parent's slot from the same proposer.
+    return !this.protoArray.hasEquivocatingBlock(
+      parentBlock.proposerIndex,
+      parentBlock.slot,
+      parentBlock.blockRoot,
+      // Only a sibling seen before the PTC deadline counts. A late released one might not have been
+      // seen by the proposer, so it cannot be expected to reorg it and is not denied the boost for it.
+      true
+    );
+  }
+
+  /**
+   * Return true if another block at the same slot from the same proposer is known to fork choice.
+   *
+   * https://github.com/ethereum/consensus-specs/blob/v1.7.0-alpha.14/specs/phase0/fork-choice.md#is_proposer_equivocation
+   */
+  private isProposerEquivocation(block: ProtoBlock): boolean {
+    // Any known sibling counts, timely or not. Timeliness only matters for withholding the boost from
+    // the next proposer, the reorg itself is safe to attempt whenever the equivocation is visible.
+    return this.protoArray.hasEquivocatingBlock(block.proposerIndex, block.slot, block.blockRoot, false);
+  }
+
+  /**
+   * The proposer boost to apply to `proposerBoostRoot`, propagated up the branch by
+   * applyScoreChanges() together with the deltas.
+   */
+  private getProposerBoost(): {root: RootHex; score: bigint} | null {
+    if (!this.proposerBoostRoot) {
+      return null;
+    }
+
+    const proposerBoostScore =
+      this.justifiedProposerBoostScore ??
+      getCommitteeFraction(this.fcStore.justified.totalBalance, {
+        slotsPerEpoch: SLOTS_PER_EPOCH,
+        committeePercent: this.config.PROPOSER_SCORE_BOOST,
+      });
+    this.justifiedProposerBoostScore = proposerBoostScore;
+
+    return {root: this.proposerBoostRoot, score: proposerBoostScore};
+  }
+
   /**
    * https://github.com/ethereum/consensus-specs/blob/v1.5.0/specs/phase0/fork-choice.md#is_proposing_on_time
    */
@@ -1728,23 +1882,31 @@ export class ForkChoice implements IForkChoice {
    * May need the justified balances of:
    * - unrealizedJustified: Already available in `CheckpointWithBalance`
    * Since this balances are already available the getter is just `() => balances`, without cache interaction
+   *
+   * @returns Whether either checkpoint was updated.
    */
   private updateCheckpoints(
     justifiedCheckpoint: CheckpointWithHex,
     finalizedCheckpoint: CheckpointWithHex,
     getJustifiedBalances: () => JustifiedBalances
-  ): void {
+  ): boolean {
+    let updated = false;
+
     // Update justified checkpoint.
     if (justifiedCheckpoint.epoch > this.fcStore.justified.checkpoint.epoch) {
       this.fcStore.justified = {checkpoint: justifiedCheckpoint, balances: getJustifiedBalances()};
       this.justifiedProposerBoostScore = null;
+      updated = true;
     }
 
     // Update finalized checkpoint.
     if (finalizedCheckpoint.epoch > this.fcStore.finalizedCheckpoint.epoch) {
       this.fcStore.finalizedCheckpoint = finalizedCheckpoint;
       this.justifiedProposerBoostScore = null;
+      updated = true;
     }
+
+    return updated;
   }
 
   /**
@@ -2030,8 +2192,10 @@ export class ForkChoice implements IForkChoice {
    * Equivalent to:
    *
    * https://github.com/ethereum/consensus-specs/blob/v1.1.10/specs/phase0/fork-choice.md#on_tick
+   *
+   * @returns Whether an epoch-boundary checkpoint was updated.
    */
-  private onTick(time: Slot): void {
+  private onTick(time: Slot): boolean {
     const previousSlot = this.fcStore.currentSlot;
 
     if (time > previousSlot + 1) {
@@ -2052,11 +2216,11 @@ export class ForkChoice implements IForkChoice {
 
     // Not a new epoch, return.
     if (computeSlotsSinceEpochStart(time) !== 0) {
-      return;
+      return false;
     }
 
-    // If a new epoch, pull-up justification and finalization from previous epoch
-    this.updateCheckpoints(
+    // If a new epoch, pull-up justification and finalization from previous epoch.
+    return this.updateCheckpoints(
       this.fcStore.unrealizedJustified.checkpoint,
       this.fcStore.unrealizedFinalizedCheckpoint,
       () => this.fcStore.unrealizedJustified.balances
@@ -2115,10 +2279,11 @@ export class ForkChoice implements IForkChoice {
     return {prelimProposerHead};
   }
 
-  private runFastConfirmation(): void {
+  /** Returns whether it recomputed the head, so the caller can avoid a redundant `updateHead()`. */
+  private runFastConfirmation(): boolean {
     const fastConfirmationRule = this.fastConfirmationRule;
     const fastConfirmationContext = this.fastConfirmationContext;
-    if (!fastConfirmationRule || !fastConfirmationContext) return;
+    if (!fastConfirmationRule || !fastConfirmationContext) return false;
 
     if (this.fastConfirmationPaused) {
       // Keep consumers on a safe, available root while the rule is paused
@@ -2129,7 +2294,7 @@ export class ForkChoice implements IForkChoice {
         // Runs outside the timed try/catch below; a throw would escape to the clock listener
         this.logger?.debug("Fast confirmation notify failed", {slot: this.fcStore.currentSlot}, err as Error);
       }
-      return;
+      return false;
     }
 
     withObservedDuration(this.metrics?.fastConfirmation.totalDuration.startTimer(), () => {
@@ -2152,6 +2317,8 @@ export class ForkChoice implements IForkChoice {
         );
       }
     });
+
+    return true;
   }
 
   private createFastConfirmationContext(): FastConfirmationContext {

package/src/protoArray/interface.ts

@@ -1,5 +1,5 @@
 import {DataAvailabilityStatus} from "@lodestar/state-transition";
-import {Epoch, RootHex, Slot, UintNum64} from "@lodestar/types";
+import {Epoch, RootHex, Slot, UintNum64, ValidatorIndex} from "@lodestar/types";
 
 // RootHex is a root as a hex string
 // Used for lightweight and easy comparison
@@ -144,6 +144,13 @@ export type ProtoBlock = BlockExtraMeta & {
   // Indicate whether block arrives in a timely manner ie. before the 4 second mark
   timeliness: boolean;
 
+  // Indicate whether block arrives before the PTC deadline
+  // Spec: gloas/fork-choice.md#modified-record_block_timeliness (block_timeliness[PTC_TIMELINESS_INDEX])
+  ptcTimeliness: boolean;
+
+  // The index of the block proposer. Used by should_apply_proposer_boost to detect proposer equivocations
+  proposerIndex: ValidatorIndex;
+
   /** Payload status for this node (Gloas fork). Always FULL in pre-gloas */
   payloadStatus: PayloadStatus;
 

package/src/protoArray/protoArray.ts

@@ -1,7 +1,7 @@
 import {BitArray} from "@chainsafe/ssz";
 import {EFFECTIVE_BALANCE_INCREMENT, GENESIS_EPOCH, GENESIS_SLOT, PTC_SIZE} from "@lodestar/params";
 import {DataAvailabilityStatus, computeEpochAtSlot, computeStartSlotAtEpoch} from "@lodestar/state-transition";
-import {Epoch, RootHex, Slot} from "@lodestar/types";
+import {Epoch, RootHex, Slot, ValidatorIndex} from "@lodestar/types";
 import {bitCount, toRootHex} from "@lodestar/utils";
 import {ForkChoiceError, ForkChoiceErrorCode} from "../forkChoice/errors.js";
 import {LVHExecError, LVHExecErrorCode, ProtoArrayError, ProtoArrayErrorCode} from "./errors.js";
@@ -2007,6 +2007,41 @@ export class ProtoArray {
     return this.getNodeByIndex(nodeIndex);
   }
 
+  /**
+   * Return true if a block other than `excludeRoot` at `slot` was proposed by `proposerIndex`.
+   * `should_apply_proposer_boost` only counts PTC-timely blocks (`ptcTimelyOnly`), `is_proposer_equivocation`
+   * counts any known block.
+   *
+   * Iterates unique block roots (via the canonical variant) since `slot`, `proposerIndex` and
+   * `ptcTimeliness` are block-level properties identical across payload-status variants.
+   */
+  hasEquivocatingBlock(
+    proposerIndex: ValidatorIndex,
+    slot: Slot,
+    excludeRoot: RootHex,
+    ptcTimelyOnly: boolean
+  ): boolean {
+    for (const root of this.indices.keys()) {
+      if (root === excludeRoot) {
+        continue;
+      }
+      const nodeIndex = this.getDefaultNodeIndex(root);
+      if (nodeIndex === undefined) {
+        continue;
+      }
+      const node = this.nodes[nodeIndex];
+      if (
+        node !== undefined &&
+        node.slot === slot &&
+        node.proposerIndex === proposerIndex &&
+        (node.ptcTimeliness || !ptcTimelyOnly)
+      ) {
+        return true;
+      }
+    }
+    return false;
+  }
+
   /**
    * Return MUTABLE ProtoBlock for blockRoot with explicit payload status
    *