@lodestar/fork-choice 1.46.0 → 1.47.0-dev.09607ce6d4

package/src/forkChoice/fastConfirmation/rules.ts

@@ -1,6 +1,6 @@
 import {computeEpochAtSlot, isStartSlotOfEpoch} from "@lodestar/state-transition";
 import {Logger} from "@lodestar/utils";
-import {equalCheckpointWithHex} from "../store.ts";
+import {equalCheckpointWithHex} from "../store.js";
 import {
   FastConfirmationCache,
   FastConfirmationContext,
@@ -11,8 +11,8 @@ import {
   FastConfirmationSnapshot,
   IFastConfirmationStore,
   isResetReason,
-} from "./types.ts";
-import {findLatestConfirmedDescendant, getBlock, isAncestor, isConfirmedChainSafe} from "./utils.ts";
+} from "./types.js";
+import {findLatestConfirmedDescendant, getBlock, isAncestor, isConfirmedChainSafe} from "./utils.js";
 
 export const resetIfConfirmedUnavailable: FastConfirmationRule = (snapshot, ctx, _store, cache, decision) => {
   const confirmedBlock = getBlock(ctx, cache, decision.confirmedRoot);

package/src/forkChoice/fastConfirmation/types.ts

@@ -1,8 +1,8 @@
 import {EffectiveBalanceIncrements, IBeaconStateView} from "@lodestar/state-transition";
 import {Epoch, RootHex, Slot, ValidatorIndex} from "@lodestar/types";
 import {Logger} from "@lodestar/utils";
-import {ProtoBlock} from "../../protoArray/interface.ts";
-import {CheckpointWithHex} from "../store.ts";
+import {ProtoBlock} from "../../protoArray/interface.js";
+import {CheckpointWithHex} from "../store.js";
 
 export type FastConfirmationBalanceSource = {
   state: IBeaconStateView | null;
@@ -15,7 +15,7 @@ export type ForkChoiceStateGetter = (
   opts: {stateRoot: RootHex; checkpoint?: never} | {stateRoot?: never; checkpoint: CheckpointWithHex}
 ) => IBeaconStateView | null;
 
-type IFastConfirmationSpecStore = {
+export type IFastConfirmationSpecStore = {
   confirmedRoot: RootHex;
   previousEpochObservedJustifiedCheckpoint: CheckpointWithHex;
   currentEpochObservedJustifiedCheckpoint: CheckpointWithHex;

package/src/forkChoice/fastConfirmation/utils.ts

@@ -9,8 +9,8 @@ import {
 } from "@lodestar/state-transition";
 import {Epoch, RootHex, Slot, ValidatorIndex} from "@lodestar/types";
 import {Logger, fromHex} from "@lodestar/utils";
-import {ExecutionStatus, ProtoBlock} from "../../protoArray/interface.ts";
-import {CheckpointWithHex, computeTotalBalance, equalCheckpointWithHex} from "../store.ts";
+import {ExecutionStatus, ProtoBlock} from "../../protoArray/interface.js";
+import {CheckpointWithHex, computeTotalBalance, equalCheckpointWithHex} from "../store.js";
 import {
   type BalanceSourceKey,
   FastConfirmationBalanceSource,
@@ -19,7 +19,7 @@ import {
   FastConfirmationSnapshot,
   IFastConfirmationStore,
   type TotalActiveBalanceCacheKey,
-} from "./types.ts";
+} from "./types.js";
 
 // Spec: adjust_committee_weight_estimate_to_ensure_safety
 // https://github.com/ethereum/consensus-specs/blob/master/specs/phase0/fast-confirmation.md#adjust_committee_weight_estimate_to_ensure_safety

package/src/forkChoice/forkChoice.ts

@@ -1,5 +1,5 @@
 import {ChainForkConfig} from "@lodestar/config";
-import {MIN_SEED_LOOKAHEAD, SLOTS_PER_EPOCH, isForkPostGloas} from "@lodestar/params";
+import {MIN_SEED_LOOKAHEAD, SLOTS_PER_EPOCH, isForkPostFulu, isForkPostGloas} from "@lodestar/params";
 import {
   DataAvailabilityStatus,
   EffectiveBalanceIncrements,
@@ -49,7 +49,8 @@ import {
   FastConfirmationRule,
   FastConfirmationSteps,
   type IFastConfirmationRule,
-} from "./fastConfirmation/fastConfirmationRule.ts";
+  type IFastConfirmationSpecStore,
+} from "./fastConfirmation/fastConfirmationRule.js";
 import {
   AncestorResult,
   AncestorStatus,
@@ -228,6 +229,17 @@ export class ForkChoice implements IForkChoice {
     return this.fastConfirmationRule?.getConfirmedRoot() ?? this.fcStore.justified.checkpoint.rootHex;
   }
 
+  getFastConfirmationStore(): IFastConfirmationSpecStore {
+    return {
+      confirmedRoot: this.getConfirmedRoot(),
+      previousEpochObservedJustifiedCheckpoint: this.fcStore.previousEpochObservedJustifiedCheckpoint,
+      currentEpochObservedJustifiedCheckpoint: this.fcStore.currentEpochObservedJustifiedCheckpoint,
+      previousEpochGreatestUnrealizedCheckpoint: this.fcStore.previousEpochGreatestUnrealizedCheckpoint,
+      previousSlotHead: this.fcStore.previousSlotHead,
+      currentSlotHead: this.fcStore.currentSlotHead,
+    };
+  }
+
   getConfirmedBlock(): ProtoBlock | null {
     return this.getBlockHexDefaultStatus(this.getConfirmedRoot());
   }
@@ -614,8 +626,8 @@ export class ForkChoice implements IForkChoice {
     return this.protoArray.nodes.filter((node) => node.slot > windowStart).length;
   }
 
-  getPayloadRevealCounts(fromSlot: Slot, toSlot: Slot): {blocksPresent: number; payloadsRevealed: number} {
-    return this.protoArray.getPayloadRevealCounts(fromSlot, toSlot);
+  getCanonicalPayloadCounts(fromSlot: Slot, toSlot: Slot, head: ProtoBlock): {full: number; empty: number} {
+    return this.protoArray.getCanonicalPayloadCounts(fromSlot, toSlot, head.blockRoot, head.payloadStatus);
   }
 
   /** Very expensive function, iterates the entire ProtoArray. Called only in debug API */
@@ -2074,11 +2086,9 @@ export class ForkChoice implements IForkChoice {
       return {prelimProposerHead, prelimNotReorgedReason: NotReorgedReason.HeadBlockIsTimely};
     }
 
-    // No reorg if we are at an epoch boundary
-    // https://github.com/ethereum/consensus-specs/blob/v1.7.0-alpha.12/specs/phase0/fork-choice.md#is_not_epoch_boundary
-    const isAtEpochBoundary = slot % SLOTS_PER_EPOCH === 0;
-    if (isAtEpochBoundary) {
-      return {prelimProposerHead, prelimNotReorgedReason: NotReorgedReason.AtEpochBoundary};
+    const isShufflingStable = isForkPostFulu(this.config.getForkName(slot)) || slot % SLOTS_PER_EPOCH !== 0;
+    if (!isShufflingStable) {
+      return {prelimProposerHead, prelimNotReorgedReason: NotReorgedReason.NotShufflingStable};
     }
 
     // No reorg if headBlock and parentBlock are not ffg competitive

package/src/forkChoice/interface.ts

@@ -8,6 +8,7 @@ import {
   ProtoBlock,
   ProtoNode,
 } from "../protoArray/interface.js";
+import {IFastConfirmationSpecStore} from "./fastConfirmation/types.js";
 import {UpdateAndGetHeadOpt} from "./forkChoice.js";
 import {CheckpointWithHex} from "./store.js";
 
@@ -53,7 +54,7 @@ export enum NotReorgedReason {
   HeadBlockIsTimely = "headBlockIsTimely",
   ParentBlockNotAvailable = "parentBlockNotAvailable",
   ProposerBoostReorgDisabled = "proposerBoostReorgDisabled",
-  AtEpochBoundary = "atEpochBoundary",
+  NotShufflingStable = "notShufflingStable",
   NotFFGCompetitive = "notFFGCompetitive",
   ChainLongUnfinality = "chainLongUnfinality",
   ParentBlockDistanceMoreThanOneSlot = "parentBlockDistanceMoreThanOneSlot",
@@ -100,6 +101,8 @@ export interface IForkChoice {
   getHead(): ProtoBlock;
   getConfirmedRoot(): RootHex;
   getConfirmedBlock(): ProtoBlock | null;
+  /** Snapshot of the spec `FastConfirmationStore` fields, mirroring `get_fast_confirmation_store` */
+  getFastConfirmationStore(): IFastConfirmationSpecStore;
   /** Resume the fast confirmation rule; restarts from the finalized root on the next slot tick */
   resumeFastConfirmation(): void;
   /** Pause the fast confirmation rule (e.g. while syncing); pins the confirmed root to the finalized root */
@@ -246,11 +249,8 @@ export interface IForkChoice {
   hasPayloadUnsafe(blockRoot: Root): boolean;
   hasPayloadHexUnsafe(blockRoot: RootHex): boolean;
   getSlotsPresent(windowStart: number): number;
-  /**
-   * Count gloas blocks with fromSlot <= slot <= toSlot and how many of them have a revealed
-   * payload (FULL variant exists). Used by the builder circuit breaker.
-   */
-  getPayloadRevealCounts(fromSlot: Slot, toSlot: Slot): {blocksPresent: number; payloadsRevealed: number};
+  /** Count FULL and EMPTY blocks on the supplied head chain in the inclusive slot range. */
+  getCanonicalPayloadCounts(fromSlot: Slot, toSlot: Slot, head: ProtoBlock): {full: number; empty: number};
   getPTCVotes(blockRootHex: RootHex): (boolean | null)[] | null;
   /** Raw PTC vote tallies for the debug fork choice endpoint; `null` for pre-Gloas roots. */
   getPTCVoteCounts(blockRootHex: RootHex): {

package/src/forkChoice/safeBlocks.ts

@@ -1,24 +1,10 @@
-import {GENESIS_SLOT, ZERO_HASH_HEX} from "@lodestar/params";
-import {Root, RootHex} from "@lodestar/types";
-import {LogLevel, Logger, fromHex} from "@lodestar/utils";
-import {HEX_ZERO_HASH, ProtoBlock, isGloasBlock} from "../protoArray/interface.js";
+import {GENESIS_SLOT} from "@lodestar/params";
+import {RootHex} from "@lodestar/types";
+import {LogLevel, Logger} from "@lodestar/utils";
+import {ExecutionStatus, HEX_ZERO_HASH, ProtoBlock, isGloasBlock} from "../protoArray/interface.js";
+import {ForkChoiceError, ForkChoiceErrorCode} from "./errors.js";
 import {IForkChoice} from "./interface.js";
 
-/**
- * Under honest majority and certain network synchronicity assumptions there exists a block
- * that is safe from re-orgs. Normally this block is pretty close to the head of canonical
- * chain which makes it valuable to expose a safe block to users.
- *
- * @deprecated The merged fast-confirmation spec only defines `get_safe_execution_block_hash`.
- */
-export function getSafeBeaconBlockRoot(fc: IForkChoice): Root {
-  const confirmedRoot = fc.getConfirmedRoot();
-  if (confirmedRoot && fc.hasBlockHex(confirmedRoot)) {
-    return fromHex(confirmedRoot);
-  }
-  return fc.getJustifiedCheckpoint().root;
-}
-
 /**
  * Get execution payload hash to report as `safeBlockHash` in `engine_forkchoiceUpdated`.
  *
@@ -29,16 +15,21 @@ export function getSafeBeaconBlockRoot(fc: IForkChoice): Root {
  *
  * https://github.com/ethereum/consensus-specs/blob/v1.7.0-alpha.13/specs/bellatrix/fast-confirmation.md#new-get_safe_execution_block_hash
  */
-export function getSafeExecutionBlockHash(forkChoice: IForkChoice, logger?: Pick<Logger, LogLevel.warn>): RootHex {
+export function getSafeExecutionBlockHash(forkChoice: IForkChoice, logger?: Pick<Logger, LogLevel.debug>): RootHex {
+  const confirmedRoot = forkChoice.getConfirmedRoot();
   const confirmedBlock = forkChoice.getConfirmedBlock();
   if (confirmedBlock === null) {
-    logger?.warn("Confirmed block not found, using zero safe execution block hash", {
-      confirmedRoot: forkChoice.getConfirmedRoot(),
+    throw new ForkChoiceError({code: ForkChoiceErrorCode.MISSING_PROTO_ARRAY_BLOCK, root: confirmedRoot});
+  }
+
+  if (confirmedBlock.blockRoot === forkChoice.getFinalizedBlock().blockRoot) {
+    logger?.debug("Confirmed block is the finalized block", {
+      blockRoot: confirmedBlock.blockRoot,
+      slot: confirmedBlock.slot,
     });
-    return ZERO_HASH_HEX;
   }
 
-  return getExecutionBlockHash(confirmedBlock, logger);
+  return getExecutionBlockHash(confirmedBlock);
 }
 
 /**
@@ -47,11 +38,11 @@ export function getSafeExecutionBlockHash(forkChoice: IForkChoice, logger?: Pick
  *
  * https://github.com/ethereum/consensus-specs/blob/v1.7.0-alpha.13/specs/gloas/fork-choice.md#notify_forkchoice_updated
  */
-export function getFinalizedExecutionBlockHash(forkChoice: IForkChoice, logger?: Pick<Logger, LogLevel.warn>): RootHex {
-  return getExecutionBlockHash(forkChoice.getFinalizedBlock(), logger);
+export function getFinalizedExecutionBlockHash(forkChoice: IForkChoice): RootHex {
+  return getExecutionBlockHash(forkChoice.getFinalizedBlock());
 }
 
-function getExecutionBlockHash(block: ProtoBlock, logger?: Pick<Logger, LogLevel.warn>): RootHex {
+function getExecutionBlockHash(block: ProtoBlock): RootHex {
   if (isGloasBlock(block)) {
     return block.parentBlockHash;
   }
@@ -63,13 +54,14 @@ function getExecutionBlockHash(block: ProtoBlock, logger?: Pick<Logger, LogLevel
     return HEX_ZERO_HASH;
   }
 
-  if (block.executionPayloadBlockHash === null) {
-    logger?.warn("Execution payload block hash not found, using zero hash", {
-      blockRoot: block.blockRoot,
-      slot: block.slot,
+  const {blockRoot, slot} = block;
+  if (block.executionPayloadBlockHash === null && block.executionStatus !== ExecutionStatus.PreMerge) {
+    throw new ForkChoiceError({
+      code: ForkChoiceErrorCode.MISSING_EXECUTION_PAYLOAD_BLOCK_HASH,
+      root: blockRoot,
+      slot,
     });
-    return HEX_ZERO_HASH;
   }
 
-  return block.executionPayloadBlockHash;
+  return block.executionPayloadBlockHash ?? HEX_ZERO_HASH;
 }

package/src/forkChoice/store.ts

@@ -1,7 +1,7 @@
 import {EffectiveBalanceIncrements, IBeaconStateView} from "@lodestar/state-transition";
 import {RootHex, Slot, ValidatorIndex, phase0} from "@lodestar/types";
 import {toRootHex} from "@lodestar/utils";
-import {ForkChoiceStateGetter, IFastConfirmationStore} from "./fastConfirmation/types.ts";
+import {ForkChoiceStateGetter, IFastConfirmationStore} from "./fastConfirmation/types.js";
 import {CheckpointWithBalance, CheckpointWithTotalBalance} from "./interface.js";
 
 /**

package/src/index.ts

@@ -16,7 +16,7 @@ export {
   type IFastConfirmationRule,
   type IFastConfirmationStore,
   getFastConfirmationMetrics,
-} from "./forkChoice/fastConfirmation/fastConfirmationRule.ts";
+} from "./forkChoice/fastConfirmation/fastConfirmationRule.js";
 export {ForkChoice, type ForkChoiceOpts, UpdateHeadOpt, getCommitteeFraction} from "./forkChoice/forkChoice.js";
 export {
   type AncestorResult,

package/src/metrics.ts

@@ -1,5 +1,5 @@
 import {MetricsRegisterExtra} from "@lodestar/utils";
-import {FastConfirmationMetrics, getFastConfirmationMetrics} from "./forkChoice/fastConfirmation/metrics.ts";
+import {FastConfirmationMetrics, getFastConfirmationMetrics} from "./forkChoice/fastConfirmation/metrics.js";
 import {UpdateHeadOpt} from "./forkChoice/forkChoice.js";
 import {NotReorgedReason} from "./forkChoice/interface.js";
 

package/src/protoArray/protoArray.ts

@@ -1,5 +1,5 @@
 import {BitArray} from "@chainsafe/ssz";
-import {GENESIS_EPOCH, PTC_SIZE} from "@lodestar/params";
+import {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 {bitCount, toRootHex} from "@lodestar/utils";
@@ -690,26 +690,42 @@ export class ProtoArray {
     this.maybeUpdateBestChildAndDescendant(pendingIndex, fullIndex, currentSlot, proposerBoostRoot);
   }
 
-  /**
-   * Count gloas blocks with fromSlot <= slot <= toSlot and how many of them have a revealed
-   * payload (FULL variant exists). Used by the builder circuit breaker.
-   */
-  getPayloadRevealCounts(fromSlot: Slot, toSlot: Slot): {blocksPresent: number; payloadsRevealed: number} {
-    let blocksPresent = 0;
-    let payloadsRevealed = 0;
-    // Full scan, nodes are in import order not slot order (an old block can be imported after newer
-    // ones during sync or reorg resolution), so we cannot stop early on an out-of-window slot
-    for (const node of this.nodes) {
-      // Count each gloas block once via its PENDING variant, pre-gloas nodes are FULL only
-      if (node.slot < fromSlot || node.slot > toSlot || node.payloadStatus !== PayloadStatus.PENDING) {
-        continue;
-      }
-      blocksPresent++;
-      if (this.hasPayload(node.blockRoot)) {
-        payloadsRevealed++;
+  /** Count blocks selected as FULL or EMPTY by the supplied head chain in the inclusive slot range. */
+  getCanonicalPayloadCounts(
+    fromSlot: Slot,
+    toSlot: Slot,
+    headRoot: RootHex,
+    headPayloadStatus: PayloadStatus
+  ): {full: number; empty: number} {
+    let full = 0;
+    let empty = 0;
+
+    // Walk the canonical chain newest-first from the head, following ancestors via `getParentNodeIndex`.
+    // Ancestors are strictly slot-descending, so we stop as soon as a node falls below `fromSlot`
+    // instead of materializing the whole chain back to the anchor as `getAllAncestorNodes` does.
+    // This keeps the scan O(window) rather than O(chain-to-anchor), relevant under prolonged non-finality.
+    const headIndex = this.getNodeIndexByRootAndStatus(headRoot, headPayloadStatus);
+    let node = headIndex !== undefined ? this.nodes[headIndex] : undefined;
+
+    while (node !== undefined && node.slot >= fromSlot) {
+      if (
+        node.slot !== GENESIS_SLOT &&
+        node.slot <= toSlot &&
+        isGloasBlock(node) &&
+        node.payloadStatus !== PayloadStatus.PENDING
+      ) {
+        if (node.payloadStatus === PayloadStatus.FULL) {
+          full++;
+        } else {
+          empty++;
+        }
       }
+
+      const parentIndex = this.getParentNodeIndex(node);
+      node = parentIndex === undefined ? undefined : this.nodes[parentIndex];
     }
-    return {blocksPresent, payloadsRevealed};
+
+    return {full, empty};
   }
 
   /**