@lodestar/fork-choice 1.41.0-dev.f2caa915ab → 1.41.0-dev.f7a5f4ddda

package/src/forkChoice/interface.ts

@@ -4,9 +4,15 @@ import {
   EffectiveBalanceIncrements,
 } from "@lodestar/state-transition";
 import {AttesterSlashing, BeaconBlock, Epoch, IndexedAttestation, Root, RootHex, Slot} from "@lodestar/types";
-import {LVHExecResponse, MaybeValidExecutionStatus, ProtoBlock, ProtoNode} from "../protoArray/interface.js";
+import {
+  LVHExecResponse,
+  MaybeValidExecutionStatus,
+  PayloadStatus,
+  ProtoBlock,
+  ProtoNode,
+} from "../protoArray/interface.js";
 import {UpdateAndGetHeadOpt} from "./forkChoice.js";
-import {CheckpointWithHex} from "./store.js";
+import {CheckpointWithHex, CheckpointWithPayloadStatus} from "./store.js";
 
 export type CheckpointHex = {
   epoch: Epoch;
@@ -18,12 +24,12 @@ export type CheckpointsWithHex = {
   finalizedCheckpoint: CheckpointWithHex;
 };
 
-export type CheckpointHexWithBalance = {
-  checkpoint: CheckpointWithHex;
+export type CheckpointWithPayloadAndBalance = {
+  checkpoint: CheckpointWithPayloadStatus;
   balances: EffectiveBalanceIncrements;
 };
 
-export type CheckpointHexWithTotalBalance = CheckpointHexWithBalance & {
+export type CheckpointWithPayloadAndTotalBalance = CheckpointWithPayloadAndBalance & {
   totalBalance: number;
 };
 
@@ -72,16 +78,18 @@ export interface IForkChoice {
   irrecoverableError?: Error;
 
   /**
-   * Returns the block root of an ancestor of `block_root` at the given `slot`. (Note: `slot` refers
+   * Returns the ancestor node of `block_root` at the given `slot`. (Note: `slot` refers
    * to the block that is *returned*, not the one that is supplied.)
    *
    * ## Specification
    *
-   * Equivalent to:
+   * Modified for Gloas to return ProtoNode instead of just root:
+   * https://github.com/ethereum/consensus-specs/blob/v1.7.0-alpha.1/specs/gloas/fork-choice.md#modified-get_ancestor
    *
-   * https://github.com/ethereum/consensus-specs/blob/v1.1.10/specs/phase0/fork-choice.md#get_ancestor
+   * Pre-Gloas: Returns (root, PAYLOAD_STATUS_FULL)
+   * Gloas: Returns (root, payloadStatus) based on actual node state
    */
-  getAncestor(blockRoot: RootHex, ancestorSlot: Slot): RootHex;
+  getAncestor(blockRoot: RootHex, ancestorSlot: Slot): ProtoNode;
   /**
    * Run the fork choice rule to determine the head.
    *
@@ -104,7 +112,7 @@ export interface IForkChoice {
    * called by `predictProposerHead()` during `prepareNextSlot()`.
    */
   shouldOverrideForkChoiceUpdate(
-    blockRoot: RootHex,
+    headBlock: ProtoBlock,
     secFromSlot: number,
     currentSlot: Slot
   ): ShouldOverrideForkChoiceUpdateResult;
@@ -116,8 +124,8 @@ export interface IForkChoice {
    * Retrieve all nodes for the debug API.
    */
   getAllNodes(): ProtoNode[];
-  getFinalizedCheckpoint(): CheckpointWithHex;
-  getJustifiedCheckpoint(): CheckpointWithHex;
+  getFinalizedCheckpoint(): CheckpointWithPayloadStatus;
+  getJustifiedCheckpoint(): CheckpointWithPayloadStatus;
   /**
    * Add `block` to the fork choice DAG.
    *
@@ -169,6 +177,38 @@ export interface IForkChoice {
    * https://github.com/ethereum/consensus-specs/blob/v1.2.0-rc.3/specs/phase0/fork-choice.md#on_attester_slashing
    */
   onAttesterSlashing(slashing: AttesterSlashing): void;
+  /**
+   * Process PTC (Payload Timeliness Committee) messages from a block
+   * Updates the PTC votes for the attested beacon block
+   *
+   * ## Specification
+   *
+   * https://github.com/ethereum/consensus-specs/blob/v1.7.0-alpha.0/specs/gloas/fork-choice.md#new-notify_ptc_messages
+   *
+   * @param blockRoot - The beacon block root being attested
+   * @param ptcIndices - Array of PTC committee indices that voted
+   * @param payloadPresent - Whether validators attest the payload is present
+   */
+  notifyPtcMessages(blockRoot: RootHex, ptcIndices: number[], payloadPresent: boolean): void;
+  /**
+   * Notify fork choice that an execution payload has arrived (Gloas fork)
+   * Creates the FULL variant of a Gloas block when the payload becomes available
+   *
+   * ## Specification
+   *
+   * https://github.com/ethereum/consensus-specs/blob/v1.7.0-alpha.1/specs/gloas/fork-choice.md#new-on_execution_payload
+   *
+   * @param blockRoot - The beacon block root for which the payload arrived
+   * @param executionPayloadBlockHash - The block hash of the execution payload
+   * @param executionPayloadNumber - The block number of the execution payload
+   * @param executionPayloadStateRoot - The execution payload state root ie. the root of post-state after processExecutionPayloadEnvelope()
+   */
+  onExecutionPayload(
+    blockRoot: RootHex,
+    executionPayloadBlockHash: RootHex,
+    executionPayloadNumber: number,
+    executionPayloadStateRoot: RootHex
+  ): void;
   /**
    * Call `onTick` for all slots between `fcStore.getCurrentSlot()` and the provided `currentSlot`.
    */
@@ -192,8 +232,11 @@ export interface IForkChoice {
   /**
    * Returns a `ProtoBlock` if the block is known **and** a descendant of the finalized root.
    */
-  getBlock(blockRoot: Root): ProtoBlock | null;
-  getBlockHex(blockRoot: RootHex): ProtoBlock | null;
+  getBlock(blockRoot: Root, payloadStatus: PayloadStatus): ProtoBlock | null;
+  getBlockHex(blockRoot: RootHex, payloadStatus: PayloadStatus): ProtoBlock | null;
+  getBlockDefaultStatus(blockRoot: Root): ProtoBlock | null;
+  getBlockHexDefaultStatus(blockRoot: RootHex): ProtoBlock | null;
+  getBlockHexAndBlockHash(blockRoot: RootHex, blockHash: RootHex): ProtoBlock | null;
   getFinalizedBlock(): ProtoBlock;
   getJustifiedBlock(): ProtoBlock;
   getFinalizedCheckpointSlot(): Slot;
@@ -203,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.
    */
@@ -212,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;
   /**
@@ -231,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

@@ -1,7 +1,8 @@
 import {CachedBeaconStateAllForks, EffectiveBalanceIncrements} from "@lodestar/state-transition";
 import {RootHex, Slot, ValidatorIndex, phase0} from "@lodestar/types";
 import {toRootHex} from "@lodestar/utils";
-import {CheckpointHexWithBalance, CheckpointHexWithTotalBalance} from "./interface.js";
+import {PayloadStatus} from "../protoArray/interface.js";
+import {CheckpointWithPayloadAndBalance, CheckpointWithPayloadAndTotalBalance} from "./interface.js";
 
 /**
  * Stores checkpoints in a hybrid format:
@@ -10,6 +11,15 @@ import {CheckpointHexWithBalance, CheckpointHexWithTotalBalance} from "./interfa
  */
 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;
 
 /**
@@ -19,7 +29,7 @@ export type JustifiedBalances = EffectiveBalanceIncrements;
  * @param blockState state that declares justified checkpoint `checkpoint`
  */
 export type JustifiedBalancesGetter = (
-  checkpoint: CheckpointWithHex,
+  checkpoint: CheckpointWithPayloadStatus,
   blockState: CachedBeaconStateAllForks
 ) => JustifiedBalances;
 
@@ -37,11 +47,11 @@ export type JustifiedBalancesGetter = (
  */
 export interface IForkChoiceStore {
   currentSlot: Slot;
-  get justified(): CheckpointHexWithTotalBalance;
-  set justified(justified: CheckpointHexWithBalance);
-  unrealizedJustified: CheckpointHexWithBalance;
-  finalizedCheckpoint: CheckpointWithHex;
-  unrealizedFinalizedCheckpoint: CheckpointWithHex;
+  get justified(): CheckpointWithPayloadAndTotalBalance;
+  set justified(justified: CheckpointWithPayloadAndBalance);
+  unrealizedJustified: CheckpointWithPayloadAndBalance;
+  finalizedCheckpoint: CheckpointWithPayloadStatus;
+  unrealizedFinalizedCheckpoint: CheckpointWithPayloadStatus;
   justifiedBalancesGetter: JustifiedBalancesGetter;
   equivocatingIndices: Set<ValidatorIndex>;
 }
@@ -50,10 +60,10 @@ export interface IForkChoiceStore {
  * IForkChoiceStore implementer which emits forkChoice events on updated justified and finalized checkpoints.
  */
 export class ForkChoiceStore implements IForkChoiceStore {
-  private _justified: CheckpointHexWithTotalBalance;
-  unrealizedJustified: CheckpointHexWithBalance;
-  private _finalizedCheckpoint: CheckpointWithHex;
-  unrealizedFinalizedCheckpoint: CheckpointWithHex;
+  private _justified: CheckpointWithPayloadAndTotalBalance;
+  unrealizedJustified: CheckpointWithPayloadAndBalance;
+  private _finalizedCheckpoint: CheckpointWithPayloadStatus;
+  unrealizedFinalizedCheckpoint: CheckpointWithPayloadStatus;
   equivocatingIndices = new Set<ValidatorIndex>();
   justifiedBalancesGetter: JustifiedBalancesGetter;
   currentSlot: Slot;
@@ -64,37 +74,49 @@ 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: CheckpointWithHex) => void;
-      onFinalized: (cp: CheckpointWithHex) => void;
+      onJustified: (cp: CheckpointWithPayloadStatus) => void;
+      onFinalized: (cp: CheckpointWithPayloadStatus) => void;
     }
   ) {
     this.justifiedBalancesGetter = justifiedBalancesGetter;
     this.currentSlot = currentSlot;
     const justified = {
-      checkpoint: toCheckpointWithHex(justifiedCheckpoint),
+      checkpoint: toCheckpointWithPayload(justifiedCheckpoint, justifiedPayloadStatus),
       balances: justifiedBalances,
       totalBalance: computeTotalBalance(justifiedBalances),
     };
     this._justified = justified;
     this.unrealizedJustified = justified;
-    this._finalizedCheckpoint = toCheckpointWithHex(finalizedCheckpoint);
+    this._finalizedCheckpoint = toCheckpointWithPayload(finalizedCheckpoint, finalizedPayloadStatus);
     this.unrealizedFinalizedCheckpoint = this._finalizedCheckpoint;
   }
 
-  get justified(): CheckpointHexWithTotalBalance {
+  get justified(): CheckpointWithPayloadAndTotalBalance {
     return this._justified;
   }
-  set justified(justified: CheckpointHexWithBalance) {
+  set justified(justified: CheckpointWithPayloadAndBalance) {
     this._justified = {...justified, totalBalance: computeTotalBalance(justified.balances)};
     this.events?.onJustified(justified.checkpoint);
   }
 
-  get finalizedCheckpoint(): CheckpointWithHex {
+  get finalizedCheckpoint(): CheckpointWithPayloadStatus {
     return this._finalizedCheckpoint;
   }
-  set finalizedCheckpoint(checkpoint: CheckpointWithHex) {
-    const cp = toCheckpointWithHex(checkpoint);
+  set finalizedCheckpoint(checkpoint: CheckpointWithPayloadStatus) {
+    const cp = toCheckpointWithPayload(checkpoint, checkpoint.payloadStatus);
     this._finalizedCheckpoint = cp;
     this.events?.onFinalized(cp);
   }
@@ -111,6 +133,16 @@ 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,10 +6,17 @@ export {
   type InvalidBlock,
   InvalidBlockCode,
 } from "./forkChoice/errors.js";
-export {ForkChoice, type ForkChoiceOpts, UpdateHeadOpt} from "./forkChoice/forkChoice.js";
+export {
+  ForkChoice,
+  type ForkChoiceOpts,
+  UpdateHeadOpt,
+  getCheckpointPayloadStatus,
+} from "./forkChoice/forkChoice.js";
 export {
   type AncestorResult,
   AncestorStatus,
+  type CheckpointWithPayloadAndBalance,
+  type CheckpointWithPayloadAndTotalBalance,
   EpochDifference,
   type IForkChoice,
   NotReorgedReason,
@@ -17,6 +24,7 @@ export {
 export * from "./forkChoice/safeBlocks.js";
 export {
   type CheckpointWithHex,
+  type CheckpointWithPayloadStatus,
   ForkChoiceStore,
   type IForkChoiceStore,
   type JustifiedBalancesGetter,
@@ -30,5 +38,5 @@ export type {
   ProtoBlock,
   ProtoNode,
 } from "./protoArray/interface.js";
-export {ExecutionStatus} from "./protoArray/interface.js";
+export {ExecutionStatus, PayloadStatus} from "./protoArray/interface.js";
 export {ProtoArray} from "./protoArray/protoArray.js";

package/src/protoArray/computeDeltas.ts

@@ -66,6 +66,7 @@ export function computeDeltas(
   for (let vIndex = 0; vIndex < voteNextIndices.length; vIndex++) {
     currentIndex = voteCurrentIndices[vIndex];
     nextIndex = voteNextIndices[vIndex];
+
     // There is no need to create a score change if the validator has never voted or both of their
     // votes are for the zero hash (genesis block)
     if (currentIndex === NULL_VOTE_INDEX && nextIndex === NULL_VOTE_INDEX) {
@@ -106,6 +107,9 @@ export function computeDeltas(
       continue;
     }
 
+    // Deduct old balance from current index, add new balance to next index
+    // currentIndex and nextIndex already point to the correct node variants
+    // Note: If a validator changes from EMPTY to FULL variant of the same block, indexChanged will be true
     if (currentIndex !== nextIndex || oldBalance !== newBalance) {
       // We ignore the vote if it is not known in `indices .
       // We assume that it is outside of our tree (ie: pre-finalization) and therefore not interesting
@@ -116,6 +120,7 @@ export function computeDeltas(
             index: currentIndex,
           });
         }
+
         deltas[currentIndex] -= oldBalance;
       }
 
@@ -128,6 +133,7 @@ export function computeDeltas(
             index: nextIndex,
           });
         }
+
         deltas[nextIndex] += newBalance;
       }
       voteCurrentIndices[vIndex] = nextIndex;

package/src/protoArray/errors.ts

@@ -12,6 +12,8 @@ export type LVHExecError = {lvhCode: LVHExecErrorCode; blockRoot: RootHex; execH
 export enum ProtoArrayErrorCode {
   FINALIZED_NODE_UNKNOWN = "PROTO_ARRAY_ERROR_FINALIZED_NODE_UNKNOWN",
   JUSTIFIED_NODE_UNKNOWN = "PROTO_ARRAY_ERROR_JUSTIFIED_NODE_UNKNOWN",
+  UNKNOWN_BLOCK = "PROTO_ARRAY_ERROR_UNKNOWN_BLOCK",
+  UNKNOWN_PARENT_BLOCK = "PROTO_ARRAY_ERROR_UNKNOWN_PARENT_BLOCK",
   INVALID_FINALIZED_ROOT_CHANGE = "PROTO_ARRAY_ERROR_INVALID_FINALIZED_ROOT_CHANGE",
   INVALID_NODE_INDEX = "PROTO_ARRAY_ERROR_INVALID_NODE_INDEX",
   INVALID_PARENT_INDEX = "PROTO_ARRAY_ERROR_INVALID_PARENT_INDEX",
@@ -27,11 +29,14 @@ export enum ProtoArrayErrorCode {
   INVALID_BLOCK_EXECUTION_STATUS = "PROTO_ARRAY_INVALID_BLOCK_EXECUTION_STATUS",
   INVALID_JUSTIFIED_EXECUTION_STATUS = "PROTO_ARRAY_INVALID_JUSTIFIED_EXECUTION_STATUS",
   INVALID_LVH_EXECUTION_RESPONSE = "PROTO_ARRAY_INVALID_LVH_EXECUTION_RESPONSE",
+  PRE_GLOAS_BLOCK = "PROTO_ARRAY_ERROR_PRE_GLOAS_BLOCK",
 }
 
 export type ProtoArrayErrorType =
   | {code: ProtoArrayErrorCode.FINALIZED_NODE_UNKNOWN; root: RootHex}
   | {code: ProtoArrayErrorCode.JUSTIFIED_NODE_UNKNOWN; root: RootHex}
+  | {code: ProtoArrayErrorCode.UNKNOWN_BLOCK; root: RootHex}
+  | {code: ProtoArrayErrorCode.UNKNOWN_PARENT_BLOCK; parentRoot: RootHex; parentHash: RootHex | null}
   | {code: ProtoArrayErrorCode.INVALID_FINALIZED_ROOT_CHANGE}
   | {code: ProtoArrayErrorCode.INVALID_NODE_INDEX; index: number}
   | {code: ProtoArrayErrorCode.INVALID_PARENT_INDEX; index: number}
@@ -54,6 +59,7 @@ export type ProtoArrayErrorType =
     }
   | {code: ProtoArrayErrorCode.INVALID_BLOCK_EXECUTION_STATUS; root: RootHex}
   | {code: ProtoArrayErrorCode.INVALID_JUSTIFIED_EXECUTION_STATUS; root: RootHex}
-  | ({code: ProtoArrayErrorCode.INVALID_LVH_EXECUTION_RESPONSE} & LVHExecError);
+  | ({code: ProtoArrayErrorCode.INVALID_LVH_EXECUTION_RESPONSE} & LVHExecError)
+  | {code: ProtoArrayErrorCode.PRE_GLOAS_BLOCK; root: RootHex};
 
 export class ProtoArrayError extends LodestarError<ProtoArrayErrorType> {}

package/src/protoArray/interface.ts

@@ -36,6 +36,23 @@ export enum ExecutionStatus {
   PayloadSeparated = "PayloadSeparated",
 }
 
+/**
+ * Payload status for ePBS (Gloas fork)
+ * Spec: gloas/fork-choice.md#constants
+ */
+export enum PayloadStatus {
+  PENDING = 0,
+  EMPTY = 1,
+  FULL = 2,
+}
+
+/**
+ * Check if a block is in the Gloas fork (ePBS enabled)
+ */
+export function isGloasBlock(block: ProtoBlock): boolean {
+  return block.parentBlockHash !== null;
+}
+
 export type LVHValidResponse = {
   executionStatus: ExecutionStatus.Valid;
   latestValidExecHash: RootHex;
@@ -51,6 +68,11 @@ export type MaybeValidExecutionStatus = Exclude<ExecutionStatus, ExecutionStatus
 
 export type BlockExtraMeta =
   | {
+      // Pre-gloas:
+      //   - block hash of payload of the block
+      // Post-gloas:
+      //   - this is parentBlockHash of block bid because payload is only received later
+      //   - payload block hash for FULL variant
       executionPayloadBlockHash: RootHex;
       executionPayloadNumber: UintNum64;
       executionStatus: Exclude<ExecutionStatus, ExecutionStatus.PreMerge>;
@@ -102,14 +124,25 @@ export type ProtoBlock = BlockExtraMeta & {
   // Indicate whether block arrives in a timely manner ie. before the 4 second mark
   timeliness: boolean;
 
-  // GLOAS: The followings are from bids. Used for execution payload gossip validation
-  builderIndex?: number;
-  blockHashHex?: RootHex;
+  /** Payload status for this node (Gloas fork). Always FULL in pre-gloas */
+  payloadStatus: PayloadStatus;
+
+  // GLOAS: The followings are from bids. They are null in pre-gloas
+  // Used for execution payload gossip validation
+  builderIndex: number | null;
+  // Used for execution payload gossip validation. Not to be confused with executionPayloadBlockHash
+  blockHashFromBid: RootHex | null;
+
+  // Used to determine if this block extends EMPTY or FULL parent variant
+  // Spec: gloas/fork-choice.md#new-get_parent_payload_status
+  parentBlockHash: RootHex | null;
 };
 
 /**
  * A block root with additional metadata required to form a DAG
  * with vote weights and best blocks stored as metadata
+ *
+ * It is also used as ForkChoiceNode in fork choice spec
  */
 export type ProtoNode = ProtoBlock & {
   parent?: number;