@lodestar/fork-choice 1.41.0-dev.09945f6589 → 1.41.0-dev.0df187678b

package/src/forkChoice/interface.ts

@@ -12,7 +12,7 @@ import {
   ProtoNode,
 } from "../protoArray/interface.js";
 import {UpdateAndGetHeadOpt} from "./forkChoice.js";
-import {CheckpointWithHex, CheckpointWithPayload} from "./store.js";
+import {CheckpointWithHex, CheckpointWithPayloadStatus} from "./store.js";
 
 export type CheckpointHex = {
   epoch: Epoch;
@@ -25,7 +25,7 @@ export type CheckpointsWithHex = {
 };
 
 export type CheckpointWithPayloadAndBalance = {
-  checkpoint: CheckpointWithPayload;
+  checkpoint: CheckpointWithPayloadStatus;
   balances: EffectiveBalanceIncrements;
 };
 
@@ -124,8 +124,8 @@ export interface IForkChoice {
    * Retrieve all nodes for the debug API.
    */
   getAllNodes(): ProtoNode[];
-  getFinalizedCheckpoint(): CheckpointWithPayload;
-  getJustifiedCheckpoint(): CheckpointWithPayload;
+  getFinalizedCheckpoint(): CheckpointWithPayloadStatus;
+  getJustifiedCheckpoint(): CheckpointWithPayloadStatus;
   /**
    * Add `block` to the fork choice DAG.
    *
@@ -246,7 +246,12 @@ export interface IForkChoice {
    * Always returns `false` if either input roots are unknown.
    * Still returns `true` if `ancestorRoot===descendantRoot` (and the roots are known)
    */
-  isDescendant(ancestorRoot: RootHex, descendantRoot: RootHex): boolean;
+  isDescendant(
+    ancestorRoot: RootHex,
+    ancestorPayloadStatus: PayloadStatus,
+    descendantRoot: RootHex,
+    descendantPayloadStatus: PayloadStatus
+  ): boolean;
   /**
    * Prune items up to a finalized root.
    */
@@ -255,16 +260,20 @@ export interface IForkChoice {
   /**
    * Iterates backwards through ancestor block summaries, starting from a block root
    */
-  iterateAncestorBlocks(blockRoot: RootHex): IterableIterator<ProtoBlock>;
-  getAllAncestorBlocks(blockRoot: RootHex): ProtoBlock[];
+  iterateAncestorBlocks(blockRoot: RootHex, payloadStatus: PayloadStatus): IterableIterator<ProtoBlock>;
+  getAllAncestorBlocks(blockRoot: RootHex, payloadStatus: PayloadStatus): ProtoBlock[];
   /**
    * The same to iterateAncestorBlocks but this gets non-ancestor nodes instead of ancestor nodes.
    */
-  getAllNonAncestorBlocks(blockRoot: RootHex): ProtoBlock[];
+  getAllNonAncestorBlocks(blockRoot: RootHex, payloadStatus: PayloadStatus): ProtoBlock[];
   /**
    * Returns both ancestor and non-ancestor blocks in a single traversal.
    */
-  getAllAncestorAndNonAncestorBlocks(blockRoot: RootHex): {ancestors: ProtoBlock[]; nonAncestors: ProtoBlock[]};
+  getAllAncestorAndNonAncestorBlocks(
+    blockRoot: RootHex,
+    payloadStatus: PayloadStatus
+  ): {ancestors: ProtoBlock[]; nonAncestors: ProtoBlock[]};
+  getCanonicalBlockByRoot(blockRoot: Root): ProtoBlock | null;
   getCanonicalBlockAtSlot(slot: Slot): ProtoBlock | null;
   getCanonicalBlockClosestLteSlot(slot: Slot): ProtoBlock | null;
   /**
@@ -274,7 +283,7 @@ export interface IForkChoice {
   /**
    * Iterates forward descendants of blockRoot. Does not yield blockRoot itself
    */
-  forwardIterateDescendants(blockRoot: RootHex): IterableIterator<ProtoBlock>;
+  forwardIterateDescendants(blockRoot: RootHex, payloadStatus: PayloadStatus): IterableIterator<ProtoBlock>;
   getBlockSummariesByParentRoot(parentRoot: RootHex): ProtoBlock[];
   getBlockSummariesAtSlot(slot: Slot): ProtoBlock[];
   /** Returns the distance of common ancestor of nodes to the max of the newNode and the prevNode. */

package/src/forkChoice/store.ts

@@ -18,7 +18,7 @@ export type CheckpointWithHex = phase0.Checkpoint & {rootHex: RootHex};
  * Pre-Gloas: payloadStatus is always FULL (payload embedded in block)
  * Gloas: determined by state.execution_payload_availability
  */
-export type CheckpointWithPayload = CheckpointWithHex & {payloadStatus: PayloadStatus};
+export type CheckpointWithPayloadStatus = CheckpointWithHex & {payloadStatus: PayloadStatus};
 
 export type JustifiedBalances = EffectiveBalanceIncrements;
 
@@ -29,7 +29,7 @@ export type JustifiedBalances = EffectiveBalanceIncrements;
  * @param blockState state that declares justified checkpoint `checkpoint`
  */
 export type JustifiedBalancesGetter = (
-  checkpoint: CheckpointWithPayload,
+  checkpoint: CheckpointWithPayloadStatus,
   blockState: CachedBeaconStateAllForks
 ) => JustifiedBalances;
 
@@ -50,8 +50,8 @@ export interface IForkChoiceStore {
   get justified(): CheckpointWithPayloadAndTotalBalance;
   set justified(justified: CheckpointWithPayloadAndBalance);
   unrealizedJustified: CheckpointWithPayloadAndBalance;
-  finalizedCheckpoint: CheckpointWithPayload;
-  unrealizedFinalizedCheckpoint: CheckpointWithPayload;
+  finalizedCheckpoint: CheckpointWithPayloadStatus;
+  unrealizedFinalizedCheckpoint: CheckpointWithPayloadStatus;
   justifiedBalancesGetter: JustifiedBalancesGetter;
   equivocatingIndices: Set<ValidatorIndex>;
 }
@@ -62,8 +62,8 @@ export interface IForkChoiceStore {
 export class ForkChoiceStore implements IForkChoiceStore {
   private _justified: CheckpointWithPayloadAndTotalBalance;
   unrealizedJustified: CheckpointWithPayloadAndBalance;
-  private _finalizedCheckpoint: CheckpointWithPayload;
-  unrealizedFinalizedCheckpoint: CheckpointWithPayload;
+  private _finalizedCheckpoint: CheckpointWithPayloadStatus;
+  unrealizedFinalizedCheckpoint: CheckpointWithPayloadStatus;
   equivocatingIndices = new Set<ValidatorIndex>();
   justifiedBalancesGetter: JustifiedBalancesGetter;
   currentSlot: Slot;
@@ -87,8 +87,8 @@ export class ForkChoiceStore implements IForkChoiceStore {
      */
     finalizedPayloadStatus: PayloadStatus,
     private readonly events?: {
-      onJustified: (cp: CheckpointWithPayload) => void;
-      onFinalized: (cp: CheckpointWithPayload) => void;
+      onJustified: (cp: CheckpointWithPayloadStatus) => void;
+      onFinalized: (cp: CheckpointWithPayloadStatus) => void;
     }
   ) {
     this.justifiedBalancesGetter = justifiedBalancesGetter;
@@ -112,10 +112,10 @@ export class ForkChoiceStore implements IForkChoiceStore {
     this.events?.onJustified(justified.checkpoint);
   }
 
-  get finalizedCheckpoint(): CheckpointWithPayload {
+  get finalizedCheckpoint(): CheckpointWithPayloadStatus {
     return this._finalizedCheckpoint;
   }
-  set finalizedCheckpoint(checkpoint: CheckpointWithPayload) {
+  set finalizedCheckpoint(checkpoint: CheckpointWithPayloadStatus) {
     const cp = toCheckpointWithPayload(checkpoint, checkpoint.payloadStatus);
     this._finalizedCheckpoint = cp;
     this.events?.onFinalized(cp);
@@ -136,7 +136,7 @@ export function toCheckpointWithHex(checkpoint: phase0.Checkpoint): CheckpointWi
 export function toCheckpointWithPayload(
   checkpoint: phase0.Checkpoint,
   payloadStatus: PayloadStatus
-): CheckpointWithPayload {
+): CheckpointWithPayloadStatus {
   return {
     ...toCheckpointWithHex(checkpoint),
     payloadStatus,

package/src/index.ts

@@ -24,7 +24,7 @@ export {
 export * from "./forkChoice/safeBlocks.js";
 export {
   type CheckpointWithHex,
-  type CheckpointWithPayload,
+  type CheckpointWithPayloadStatus,
   ForkChoiceStore,
   type IForkChoiceStore,
   type JustifiedBalancesGetter,

package/src/protoArray/protoArray.ts

@@ -1477,11 +1477,8 @@ export class ProtoArray {
    * For Gloas blocks: returns EMPTY/FULL variants (not PENDING) based on parent payload status
    * For pre-Gloas blocks: returns FULL variants
    */
-  *iterateAncestorNodes(blockRoot: RootHex): IterableIterator<ProtoNode> {
-    // Get canonical node: FULL for pre-Gloas, PENDING for Gloas
-    const defaultStatus = this.getDefaultVariant(blockRoot);
-    const startIndex =
-      defaultStatus !== undefined ? this.getNodeIndexByRootAndStatus(blockRoot, defaultStatus) : undefined;
+  *iterateAncestorNodes(blockRoot: RootHex, payloadStatus: PayloadStatus): IterableIterator<ProtoNode> {
+    const startIndex = this.getNodeIndexByRootAndStatus(blockRoot, payloadStatus);
     if (startIndex === undefined) {
       return;
     }
@@ -1520,11 +1517,8 @@ export class ProtoArray {
    * For Gloas blocks: returns EMPTY/FULL variants (not PENDING) based on parent payload status
    * For pre-Gloas blocks: returns FULL variants
    */
-  getAllAncestorNodes(blockRoot: RootHex): ProtoNode[] {
-    // Get canonical node: FULL for pre-Gloas, PENDING for Gloas
-    const defaultStatus = this.getDefaultVariant(blockRoot);
-    const startIndex =
-      defaultStatus !== undefined ? this.getNodeIndexByRootAndStatus(blockRoot, defaultStatus) : undefined;
+  getAllAncestorNodes(blockRoot: RootHex, payloadStatus: PayloadStatus): ProtoNode[] {
+    const startIndex = this.getNodeIndexByRootAndStatus(blockRoot, payloadStatus);
     if (startIndex === undefined) {
       return [];
     }
@@ -1537,12 +1531,10 @@ export class ProtoArray {
       });
     }
 
-    // Include starting node if node is pre-gloas
-    // Reason why we exclude post-gloas is because node is always default variant (PENDING)
-    // which we want to exclude.
+    // Exclude PENDING variant from returned ancestors.
     const nodes: ProtoNode[] = [];
 
-    if (!isGloasBlock(node)) {
+    if (node.payloadStatus !== PayloadStatus.PENDING) {
       nodes.push(node);
     }
 
@@ -1567,13 +1559,8 @@ export class ProtoArray {
    * For Gloas blocks: returns EMPTY/FULL variants (not PENDING) based on parent payload status
    * For pre-Gloas blocks: returns FULL variants
    */
-  getAllNonAncestorNodes(blockRoot: RootHex): ProtoNode[] {
-    // Get canonical node: FULL for pre-Gloas, PENDING for Gloas
-    const defaultStatus = this.getDefaultVariant(blockRoot);
-    if (defaultStatus === undefined) {
-      return [];
-    }
-    const startIndex = this.getNodeIndexByRootAndStatus(blockRoot, defaultStatus);
+  getAllNonAncestorNodes(blockRoot: RootHex, payloadStatus: PayloadStatus): ProtoNode[] {
+    const startIndex = this.getNodeIndexByRootAndStatus(blockRoot, payloadStatus);
     if (startIndex === undefined) {
       return [];
     }
@@ -1613,11 +1600,11 @@ export class ProtoArray {
    * For Gloas blocks: returns EMPTY/FULL variants (not PENDING) based on parent payload status
    * For pre-Gloas blocks: returns FULL variants
    */
-  getAllAncestorAndNonAncestorNodes(blockRoot: RootHex): {ancestors: ProtoNode[]; nonAncestors: ProtoNode[]} {
-    // Get canonical node: FULL for pre-Gloas, PENDING for Gloas
-    const defaultStatus = this.getDefaultVariant(blockRoot);
-    const startIndex =
-      defaultStatus !== undefined ? this.getNodeIndexByRootAndStatus(blockRoot, defaultStatus) : undefined;
+  getAllAncestorAndNonAncestorNodes(
+    blockRoot: RootHex,
+    payloadStatus: PayloadStatus
+  ): {ancestors: ProtoNode[]; nonAncestors: ProtoNode[]} {
+    const startIndex = this.getNodeIndexByRootAndStatus(blockRoot, payloadStatus);
     if (startIndex === undefined) {
       return {ancestors: [], nonAncestors: []};
     }
@@ -1735,26 +1722,28 @@ export class ProtoArray {
   /**
    * Returns `true` if the `descendantRoot` has an ancestor with `ancestorRoot`.
    * Always returns `false` if either input roots are unknown.
-   * Still returns `true` if `ancestorRoot` === `descendantRoot` (and the roots are known)
+   * Still returns `true` if `ancestorRoot` === `descendantRoot` and payload statuses match.
    */
-  isDescendant(ancestorRoot: RootHex, descendantRoot: RootHex): boolean {
-    // We use the default variant (PENDING for Gloas, FULL for pre-Gloas)
-    // We cannot use FULL/EMPTY variants for Gloas because they may not be canonical
-    const defaultStatus = this.getDefaultVariant(ancestorRoot);
-    const ancestorNode = defaultStatus !== undefined ? this.getNode(ancestorRoot, defaultStatus) : undefined;
+  isDescendant(
+    ancestorRoot: RootHex,
+    ancestorPayloadStatus: PayloadStatus,
+    descendantRoot: RootHex,
+    descendantPayloadStatus: PayloadStatus
+  ): boolean {
+    const ancestorNode = this.getNode(ancestorRoot, ancestorPayloadStatus);
     if (!ancestorNode) {
       return false;
     }
 
-    if (ancestorRoot === descendantRoot) {
+    if (ancestorRoot === descendantRoot && ancestorPayloadStatus === descendantPayloadStatus) {
       return true;
     }
 
-    for (const node of this.iterateAncestorNodes(descendantRoot)) {
+    for (const node of this.iterateAncestorNodes(descendantRoot, descendantPayloadStatus)) {
       if (node.slot < ancestorNode.slot) {
         return false;
       }
-      if (node.blockRoot === ancestorNode.blockRoot) {
+      if (node.blockRoot === ancestorNode.blockRoot && node.payloadStatus === ancestorNode.payloadStatus) {
         return true;
       }
     }