@lodestar/fork-choice 1.42.0 → 1.43.0-dev.07452fe3b7

package/src/forkChoice/store.ts

@@ -1,8 +1,7 @@
 import {EffectiveBalanceIncrements, IBeaconStateView} from "@lodestar/state-transition";
 import {RootHex, Slot, ValidatorIndex, phase0} from "@lodestar/types";
 import {toRootHex} from "@lodestar/utils";
-import {PayloadStatus} from "../protoArray/interface.js";
-import {CheckpointWithPayloadAndBalance, CheckpointWithPayloadAndTotalBalance} from "./interface.js";
+import {CheckpointWithBalance, CheckpointWithTotalBalance} from "./interface.js";
 
 /**
  * Stores checkpoints in a hybrid format:
@@ -11,15 +10,6 @@ import {CheckpointWithPayloadAndBalance, CheckpointWithPayloadAndTotalBalance} f
  */
 export type CheckpointWithHex = phase0.Checkpoint & {rootHex: RootHex};
 
-/**
- * Checkpoint with payload status for Gloas fork choice.
- * Used to track which variant (EMPTY or FULL) of the finalized/justified block to use.
- *
- * Pre-Gloas: payloadStatus is always FULL (payload embedded in block)
- * Gloas: determined by state.execution_payload_availability
- */
-export type CheckpointWithPayloadStatus = CheckpointWithHex & {payloadStatus: PayloadStatus};
-
 export type JustifiedBalances = EffectiveBalanceIncrements;
 
 /**
@@ -29,7 +19,7 @@ export type JustifiedBalances = EffectiveBalanceIncrements;
  * @param blockState state that declares justified checkpoint `checkpoint`
  */
 export type JustifiedBalancesGetter = (
-  checkpoint: CheckpointWithPayloadStatus,
+  checkpoint: CheckpointWithHex,
   blockState: IBeaconStateView
 ) => JustifiedBalances;
 
@@ -47,11 +37,11 @@ export type JustifiedBalancesGetter = (
  */
 export interface IForkChoiceStore {
   currentSlot: Slot;
-  get justified(): CheckpointWithPayloadAndTotalBalance;
-  set justified(justified: CheckpointWithPayloadAndBalance);
-  unrealizedJustified: CheckpointWithPayloadAndBalance;
-  finalizedCheckpoint: CheckpointWithPayloadStatus;
-  unrealizedFinalizedCheckpoint: CheckpointWithPayloadStatus;
+  get justified(): CheckpointWithTotalBalance;
+  set justified(justified: CheckpointWithBalance);
+  unrealizedJustified: CheckpointWithBalance;
+  finalizedCheckpoint: CheckpointWithHex;
+  unrealizedFinalizedCheckpoint: CheckpointWithHex;
   justifiedBalancesGetter: JustifiedBalancesGetter;
   equivocatingIndices: Set<ValidatorIndex>;
 }
@@ -60,10 +50,10 @@ export interface IForkChoiceStore {
  * IForkChoiceStore implementer which emits forkChoice events on updated justified and finalized checkpoints.
  */
 export class ForkChoiceStore implements IForkChoiceStore {
-  private _justified: CheckpointWithPayloadAndTotalBalance;
-  unrealizedJustified: CheckpointWithPayloadAndBalance;
-  private _finalizedCheckpoint: CheckpointWithPayloadStatus;
-  unrealizedFinalizedCheckpoint: CheckpointWithPayloadStatus;
+  private _justified: CheckpointWithTotalBalance;
+  unrealizedJustified: CheckpointWithBalance;
+  private _finalizedCheckpoint: CheckpointWithHex;
+  unrealizedFinalizedCheckpoint: CheckpointWithHex;
   equivocatingIndices = new Set<ValidatorIndex>();
   justifiedBalancesGetter: JustifiedBalancesGetter;
   currentSlot: Slot;
@@ -74,49 +64,37 @@ export class ForkChoiceStore implements IForkChoiceStore {
     finalizedCheckpoint: phase0.Checkpoint,
     justifiedBalances: EffectiveBalanceIncrements,
     justifiedBalancesGetter: JustifiedBalancesGetter,
-    /**
-     * Payload status for justified checkpoint.
-     * Pre-Gloas: always FULL
-     * Gloas: determined by state.execution_payload_availability
-     */
-    justifiedPayloadStatus: PayloadStatus,
-    /**
-     * Payload status for finalized checkpoint.
-     * Pre-Gloas: always FULL
-     * Gloas: determined by state.execution_payload_availability
-     */
-    finalizedPayloadStatus: PayloadStatus,
     private readonly events?: {
-      onJustified: (cp: CheckpointWithPayloadStatus) => void;
-      onFinalized: (cp: CheckpointWithPayloadStatus) => void;
+      onJustified: (cp: CheckpointWithHex) => void;
+      onFinalized: (cp: CheckpointWithHex) => void;
     }
   ) {
     this.justifiedBalancesGetter = justifiedBalancesGetter;
     this.currentSlot = currentSlot;
     const justified = {
-      checkpoint: toCheckpointWithPayload(justifiedCheckpoint, justifiedPayloadStatus),
+      checkpoint: toCheckpointWithHex(justifiedCheckpoint),
       balances: justifiedBalances,
       totalBalance: computeTotalBalance(justifiedBalances),
     };
     this._justified = justified;
     this.unrealizedJustified = justified;
-    this._finalizedCheckpoint = toCheckpointWithPayload(finalizedCheckpoint, finalizedPayloadStatus);
+    this._finalizedCheckpoint = toCheckpointWithHex(finalizedCheckpoint);
     this.unrealizedFinalizedCheckpoint = this._finalizedCheckpoint;
   }
 
-  get justified(): CheckpointWithPayloadAndTotalBalance {
+  get justified(): CheckpointWithTotalBalance {
     return this._justified;
   }
-  set justified(justified: CheckpointWithPayloadAndBalance) {
+  set justified(justified: CheckpointWithBalance) {
     this._justified = {...justified, totalBalance: computeTotalBalance(justified.balances)};
     this.events?.onJustified(justified.checkpoint);
   }
 
-  get finalizedCheckpoint(): CheckpointWithPayloadStatus {
+  get finalizedCheckpoint(): CheckpointWithHex {
     return this._finalizedCheckpoint;
   }
-  set finalizedCheckpoint(checkpoint: CheckpointWithPayloadStatus) {
-    const cp = toCheckpointWithPayload(checkpoint, checkpoint.payloadStatus);
+  set finalizedCheckpoint(checkpoint: CheckpointWithHex) {
+    const cp = toCheckpointWithHex(checkpoint);
     this._finalizedCheckpoint = cp;
     this.events?.onFinalized(cp);
   }
@@ -133,16 +111,6 @@ export function toCheckpointWithHex(checkpoint: phase0.Checkpoint): CheckpointWi
   };
 }
 
-export function toCheckpointWithPayload(
-  checkpoint: phase0.Checkpoint,
-  payloadStatus: PayloadStatus
-): CheckpointWithPayloadStatus {
-  return {
-    ...toCheckpointWithHex(checkpoint),
-    payloadStatus,
-  };
-}
-
 export function equalCheckpointWithHex(a: CheckpointWithHex, b: CheckpointWithHex): boolean {
   return a.epoch === b.epoch && a.rootHex === b.rootHex;
 }

package/src/index.ts

@@ -6,17 +6,12 @@ export {
   type InvalidBlock,
   InvalidBlockCode,
 } from "./forkChoice/errors.js";
-export {
-  ForkChoice,
-  type ForkChoiceOpts,
-  UpdateHeadOpt,
-  getCheckpointPayloadStatus,
-} from "./forkChoice/forkChoice.js";
+export {ForkChoice, type ForkChoiceOpts, UpdateHeadOpt} from "./forkChoice/forkChoice.js";
 export {
   type AncestorResult,
   AncestorStatus,
-  type CheckpointWithPayloadAndBalance,
-  type CheckpointWithPayloadAndTotalBalance,
+  type CheckpointWithBalance,
+  type CheckpointWithTotalBalance,
   EpochDifference,
   type IForkChoice,
   NotReorgedReason,
@@ -24,7 +19,6 @@ export {
 export * from "./forkChoice/safeBlocks.js";
 export {
   type CheckpointWithHex,
-  type CheckpointWithPayloadStatus,
   ForkChoiceStore,
   type IForkChoiceStore,
   type JustifiedBalancesGetter,

package/src/protoArray/interface.ts

@@ -24,16 +24,15 @@ export type VoteIndex = number;
  * - Syncing: EL is syncing, payload validity unknown (optimistic sync)
  * - PreMerge: Block is from before The Merge, no execution payload exists
  * - Invalid: Execution payload was invalidated by the EL (post-import status)
- * - PayloadSeparated: Gloas beacon block without embedded execution payload.
- *         The execution payload arrives separately via SignedExecutionPayloadEnvelope.
- *         Gloas blocks WITH execution payload (FULL variant) use Valid/Invalid/Syncing.
+ *
+ * For gloas blocks the PENDING/EMPTY variants inherit `executionStatus` from the parent's chain
+ * (Valid/Syncing/PreMerge); the FULL variant carries the EL response for this block's own payload.
  */
 export enum ExecutionStatus {
   Valid = "Valid",
   Syncing = "Syncing",
   PreMerge = "PreMerge",
   Invalid = "Invalid",
-  PayloadSeparated = "PayloadSeparated",
 }
 
 /**
@@ -61,19 +60,21 @@ export type LVHInvalidResponse = {
   executionStatus: ExecutionStatus.Invalid;
   latestValidExecHash: RootHex | null;
   invalidateFromParentBlockRoot: RootHex;
+  // EL block hash from invalid block's bid (gloas) or payload's parentHash (pre-gloas).
+  // Disambiguates which variant of the parent (FULL vs EMPTY) to invalidate from.
+  invalidateFromParentBlockHash: RootHex;
 };
 export type LVHExecResponse = LVHValidResponse | LVHInvalidResponse;
 
 /**
  * Any execution status that is not definitively invalid.
- * Pre-Gloas: Valid | Syncing | PreMerge
- * Post-Gloas: execution status must be PayloadSeparated (beacon block imported before its payload arrives via SignedExecutionPayloadEnvelope)
+ * Valid | Syncing | PreMerge
  */
 export type BlockExecutionStatus = Exclude<ExecutionStatus, ExecutionStatus.Invalid>;
 
 /**
  * Execution status for a block whose execution payload is present and has been submitted to the EL.
- * Used post-Gloas when transitioning a PayloadSeparated block to FULL via onExecutionPayload().
+ * Used post-Gloas when transitioning a PENDING block to FULL via onExecutionPayload().
  */
 export type PayloadExecutionStatus = ExecutionStatus.Valid | ExecutionStatus.Syncing;
 

package/src/protoArray/protoArray.ts

@@ -1,6 +1,6 @@
 import {BitArray} from "@chainsafe/ssz";
 import {GENESIS_EPOCH, PTC_SIZE} from "@lodestar/params";
-import {computeEpochAtSlot, computeStartSlotAtEpoch} from "@lodestar/state-transition";
+import {DataAvailabilityStatus, computeEpochAtSlot, computeStartSlotAtEpoch} from "@lodestar/state-transition";
 import {Epoch, RootHex, Slot} from "@lodestar/types";
 import {bitCount, toRootHex} from "@lodestar/utils";
 import {ForkChoiceError, ForkChoiceErrorCode} from "../forkChoice/errors.js";
@@ -108,6 +108,7 @@ export class ProtoArray {
       currentSlot,
       null
     );
+
     return protoArray;
   }
 
@@ -251,38 +252,43 @@ export class ProtoArray {
   }
 
   /**
-   * Returns an EMPTY or FULL `ProtoBlock` that has matching block root and block hash
+   * Returns the node index of an EMPTY or FULL variant matching block root and block hash.
+   * Pre-gloas: checks the single variant. Post-gloas: prefers FULL, falls back to EMPTY.
    */
-  getBlockHexAndBlockHash(blockRoot: RootHex, blockHash: RootHex): ProtoBlock | null {
+  getNodeIndexByRootAndBlockHash(blockRoot: RootHex, blockHash: RootHex): number | undefined {
     const variantIndices = this.indices.get(blockRoot);
     if (variantIndices === undefined) {
-      return null;
+      return undefined;
     }
 
     // Pre-Gloas
     if (!Array.isArray(variantIndices)) {
-      const node = this.nodes[variantIndices];
-      return node.executionPayloadBlockHash === blockHash ? node : null;
+      return this.nodes[variantIndices].executionPayloadBlockHash === blockHash ? variantIndices : undefined;
     }
 
-    // Post-Gloas, check empty and full variants
+    // Post-Gloas, prefer FULL then EMPTY
     const fullNodeIndex = variantIndices[PayloadStatus.FULL];
-    if (fullNodeIndex !== undefined) {
-      const fullNode = this.nodes[fullNodeIndex];
-      if (fullNode && fullNode.executionPayloadBlockHash === blockHash) {
-        return fullNode;
-      }
+    if (fullNodeIndex !== undefined && this.nodes[fullNodeIndex].executionPayloadBlockHash === blockHash) {
+      return fullNodeIndex;
     }
 
-    const emptyNode = this.nodes[variantIndices[PayloadStatus.EMPTY]];
-    if (emptyNode && emptyNode.executionPayloadBlockHash === blockHash) {
-      return emptyNode;
+    const emptyNodeIndex = variantIndices[PayloadStatus.EMPTY];
+    if (this.nodes[emptyNodeIndex].executionPayloadBlockHash === blockHash) {
+      return emptyNodeIndex;
     }
 
     // PENDING is the same to EMPTY so not likely we can return it
     // also it's only specific for fork-choice
 
-    return null;
+    return undefined;
+  }
+
+  /**
+   * Returns an EMPTY or FULL `ProtoBlock` that has matching block root and block hash
+   */
+  getBlockHexAndBlockHash(blockRoot: RootHex, blockHash: RootHex): ProtoBlock | null {
+    const idx = this.getNodeIndexByRootAndBlockHash(blockRoot, blockHash);
+    return idx !== undefined ? this.nodes[idx] : null;
   }
 
   /**
@@ -354,9 +360,15 @@ export class ProtoArray {
         continue;
       }
 
-      const currentBoost = proposerBoost && proposerBoost.root === node.blockRoot ? proposerBoost.score : 0;
+      // For Gloas blocks, PENDING/EMPTY/FULL all share the same blockRoot.
+      // Only apply proposer boost to PENDING (for Gloas) or FULL (for pre-Gloas) — to avoid
+      // double-counting the boost across variants during delta back-propagation, and to keep
+      // the boost neutral with respect to EMPTY vs FULL selection.
+      const isBoostVariant = isGloasBlock(node) ? node.payloadStatus === PayloadStatus.PENDING : true; // pre-Gloas has only FULL, always boost
+      const currentBoost =
+        proposerBoost && proposerBoost.root === node.blockRoot && isBoostVariant ? proposerBoost.score : 0;
       const previousBoost =
-        this.previousProposerBoost && this.previousProposerBoost.root === node.blockRoot
+        this.previousProposerBoost && this.previousProposerBoost.root === node.blockRoot && isBoostVariant
           ? this.previousProposerBoost.score
           : 0;
 
@@ -541,9 +553,9 @@ export class ProtoArray {
     currentSlot: Slot,
     executionPayloadBlockHash: RootHex,
     executionPayloadNumber: number,
-    executionPayloadStateRoot: RootHex,
     proposerBoostRoot: RootHex | null,
-    executionStatus: PayloadExecutionStatus
+    executionStatus: PayloadExecutionStatus,
+    dataAvailabilityStatus: DataAvailabilityStatus
   ): void {
     // First check if block exists
     const variants = this.indices.get(blockRoot);
@@ -585,7 +597,7 @@ export class ProtoArray {
       });
     }
 
-    // Create FULL variant as a child of PENDING (sibling to EMPTY)
+    // Create FULL variant as a child of PENDING (sibling to EMPTY).
     const fullNode: ProtoNode = {
       ...pendingNode,
       parent: pendingIndex, // Points to own PENDING (same as EMPTY)
@@ -593,11 +605,10 @@ export class ProtoArray {
       weight: 0,
       bestChild: undefined,
       bestDescendant: undefined,
-      // TODO GLOAS: handle optimistic sync
       executionStatus,
       executionPayloadBlockHash,
       executionPayloadNumber,
-      stateRoot: executionPayloadStateRoot,
+      dataAvailabilityStatus,
     };
 
     const fullIndex = this.nodes.length;
@@ -606,6 +617,12 @@ export class ProtoArray {
     // Add FULL variant to the indices array
     variants[PayloadStatus.FULL] = fullIndex;
 
+    if (executionStatus === ExecutionStatus.Valid) {
+      // Walk up from FULL's parent (its own PENDING). FULL is already Valid; the loop breaks
+      // immediately if we start at FULL. Same pattern as pre-gloas onBlock at line ~533.
+      this.propagateValidExecutionStatusByIndex(pendingIndex);
+    }
+
     // Update bestChild for PENDING node (may now prefer FULL over EMPTY)
     this.maybeUpdateBestChildAndDescendant(pendingIndex, fullIndex, currentSlot, proposerBoostRoot);
   }
@@ -634,6 +651,16 @@ export class ProtoArray {
     }
   }
 
+  getPTCVotes(blockRootHex: RootHex): BitArray | null {
+    const votes = this.ptcVotes.get(blockRootHex);
+    if (votes === undefined) {
+      // Block not found or not a Gloas block
+      return null;
+    }
+
+    return votes;
+  }
+
   /**
    * Check if execution payload for a block is timely
    * Spec: gloas/fork-choice.md#new-is_payload_timely
@@ -676,7 +703,7 @@ export class ProtoArray {
    * Determine if we should extend the payload (prefer FULL over EMPTY)
    * Spec: gloas/fork-choice.md#new-should_extend_payload
    *
-   * Returns true if:
+   * Returns true if payload is verified (FULL variant exists) AND:
    * 1. Payload is timely, OR
    * 2. No proposer boost root (empty/zero hash), OR
    * 3. Proposer boost root's parent is not this block, OR
@@ -686,6 +713,10 @@ export class ProtoArray {
    * @param proposerBoostRoot - Current proposer boost root (from ForkChoice)
    */
   shouldExtendPayload(blockRoot: RootHex, proposerBoostRoot: RootHex | null): boolean {
+    if (!this.hasPayload(blockRoot)) {
+      return false;
+    }
+
     // Condition 1: Payload is timely
     if (this.isPayloadTimely(blockRoot)) {
       return true;
@@ -766,11 +797,15 @@ export class ProtoArray {
       // Mark chain ii) as Invalid if LVH is found and non null, else only invalidate invalid_payload
       // if its in fcU.
       //
-      const {invalidateFromParentBlockRoot, latestValidExecHash} = execResponse;
-      // TODO GLOAS: verify if getting the default/canonical node index is correct here
-      const invalidateFromParentIndex = this.getDefaultNodeIndex(invalidateFromParentBlockRoot);
+      const {invalidateFromParentBlockRoot, invalidateFromParentBlockHash, latestValidExecHash} = execResponse;
+      const invalidateFromParentIndex = this.getNodeIndexByRootAndBlockHash(
+        invalidateFromParentBlockRoot,
+        invalidateFromParentBlockHash
+      );
       if (invalidateFromParentIndex === undefined) {
-        throw Error(`Unable to find invalidateFromParentBlockRoot=${invalidateFromParentBlockRoot} in forkChoice`);
+        throw Error(
+          `Unable to find invalidateFromParentBlockRoot=${invalidateFromParentBlockRoot} invalidateFromParentBlockHash=${invalidateFromParentBlockHash} in forkChoice`
+        );
       }
       const latestValidHashIndex =
         latestValidExecHash !== null ? this.getNodeIndexFromLVH(latestValidExecHash, invalidateFromParentIndex) : null;
@@ -806,12 +841,6 @@ export class ProtoArray {
       if (node.executionStatus === ExecutionStatus.PreMerge || node.executionStatus === ExecutionStatus.Valid) {
         break;
       }
-      // If PayloadSeparated, that means the node is either PENDING or EMPTY, there could be
-      // some ancestor still has syncing status.
-      if (node.executionStatus === ExecutionStatus.PayloadSeparated) {
-        nodeIndex = node.parent;
-        continue;
-      }
       this.validateNodeByIndex(nodeIndex);
       nodeIndex = node.parent;
     }
@@ -909,6 +938,13 @@ export class ProtoArray {
     invalidNode.executionStatus = ExecutionStatus.Invalid;
     invalidNode.bestChild = undefined;
     invalidNode.bestDescendant = undefined;
+    // Gloas: PENDING and sibling EMPTY share chain status, flip together
+    if (invalidNode.payloadStatus === PayloadStatus.PENDING) {
+      const variants = this.indices.get(invalidNode.blockRoot);
+      if (Array.isArray(variants)) {
+        this.invalidateNodeByIndex(variants[PayloadStatus.EMPTY]);
+      }
+    }
 
     return invalidNode;
   }
@@ -930,6 +966,13 @@ export class ProtoArray {
     if (validNode.executionStatus === ExecutionStatus.Syncing) {
       validNode.executionStatus = ExecutionStatus.Valid;
     }
+    // Gloas: PENDING and sibling EMPTY share chain status, flip together
+    if (validNode.payloadStatus === PayloadStatus.PENDING) {
+      const variants = this.indices.get(validNode.blockRoot);
+      if (Array.isArray(variants)) {
+        this.validateNodeByIndex(variants[PayloadStatus.EMPTY]);
+      }
+    }
     return validNode;
   }
 
@@ -1478,9 +1521,16 @@ export class ProtoArray {
    */
   private getParentNodeIndex(node: ProtoNode): number | undefined {
     if (isGloasBlock(node)) {
-      // Use getParentPayloadStatus for Gloas blocks to get correct EMPTY/FULL variant
-      const parentPayloadStatus = this.getParentPayloadStatus(node);
-      return this.getNodeIndexByRootAndStatus(node.parentRoot, parentPayloadStatus);
+      // Traversal may reach the finalized ProtoBlock, should not throw error in that case
+      try {
+        const parentPayloadStatus = this.getParentPayloadStatus(node);
+        return this.getNodeIndexByRootAndStatus(node.parentRoot, parentPayloadStatus);
+      } catch (e) {
+        if (e instanceof ProtoArrayError && e.type.code === ProtoArrayErrorCode.UNKNOWN_PARENT_BLOCK) {
+          return undefined;
+        }
+        throw e;
+      }
     }
     // Simple parent traversal for pre-Gloas blocks (includes fork transition)
     return node.parent;
@@ -1634,10 +1684,9 @@ export class ProtoArray {
     const ancestors: ProtoNode[] = [];
     const nonAncestors: ProtoNode[] = [];
 
-    // Include starting node if it's not PENDING (i.e., pre-Gloas or EMPTY/FULL variant post-Gloas)
-    if (node.payloadStatus !== PayloadStatus.PENDING) {
-      ancestors.push(node);
-    }
+    // caller of this method may pass default status
+    // this is the only node that we accept PENDING
+    ancestors.push(node);
 
     let nodeIndex = startIndex;
     while (node.parent !== undefined) {