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

package/lib/protoArray/protoArray.js

@@ -1,9 +1,14 @@
-import { GENESIS_EPOCH } from "@lodestar/params";
+import { GENESIS_EPOCH, PTC_SIZE } from "@lodestar/params";
 import { computeEpochAtSlot, computeStartSlotAtEpoch } from "@lodestar/state-transition";
 import { toRootHex } from "@lodestar/utils";
 import { ForkChoiceError, ForkChoiceErrorCode } from "../forkChoice/errors.js";
 import { LVHExecErrorCode, ProtoArrayError, ProtoArrayErrorCode } from "./errors.js";
-import { ExecutionStatus, HEX_ZERO_HASH } from "./interface.js";
+import { ExecutionStatus, HEX_ZERO_HASH, PayloadStatus, isGloasBlock, } from "./interface.js";
+/**
+ * Threshold for payload timeliness (>50% of PTC must vote)
+ * Spec: gloas/fork-choice.md (PAYLOAD_TIMELY_THRESHOLD = PTC_SIZE // 2)
+ */
+const PAYLOAD_TIMELY_THRESHOLD = Math.floor(PTC_SIZE / 2);
 export const DEFAULT_PRUNE_THRESHOLD = 0;
 const ZERO_HASH_HEX = toRootHex(Buffer.alloc(32, 0));
 export class ProtoArray {
@@ -15,9 +20,28 @@ export class ProtoArray {
     finalizedEpoch;
     finalizedRoot;
     nodes = [];
+    /**
+     * Maps block root to array of node indices for each payload status variant
+     *
+     * Array structure: [PENDING, EMPTY, FULL] where indices correspond to PayloadStatus enum values
+     * - number[0] = PENDING variant index (PayloadStatus.PENDING = 0)
+     * - number[1] = EMPTY variant index (PayloadStatus.EMPTY = 1)
+     * - number[2] = FULL variant index (PayloadStatus.FULL = 2)
+     *
+     * Note: undefined array elements indicate that variant doesn't exist for this block
+     */
     indices = new Map();
     lvhError;
     previousProposerBoost = null;
+    /**
+     * PTC (Payload Timeliness Committee) votes per block
+     * Maps block root to boolean array of size PTC_SIZE (from params: 512 mainnet, 2 minimal)
+     * Spec: gloas/fork-choice.md#modified-store (line 148)
+     *
+     * ptcVotes[blockRoot][i] = true if PTC member i voted payload_present=true
+     * Used by is_payload_timely() to determine if payload is timely
+     */
+    ptcVotes = new Map();
     constructor({ pruneThreshold, justifiedEpoch, justifiedRoot, finalizedEpoch, finalizedRoot, }) {
         this.pruneThreshold = pruneThreshold;
         this.justifiedEpoch = justifiedEpoch;
@@ -37,9 +61,146 @@ export class ProtoArray {
             ...block,
             // We are using the blockROot as the targetRoot, since it always lies on an epoch boundary
             targetRoot: block.blockRoot,
-        }, currentSlot);
+        }, currentSlot, null);
         return protoArray;
     }
+    /**
+     * Get node index for a block root and payload status
+     *
+     * @param root - The block root to look up
+     * @param payloadStatus - The specific payload status variant (PENDING/EMPTY/FULL)
+     * @returns The node index for the specified variant, or undefined if not found
+     *
+     * Behavior:
+     * - Pre-Gloas blocks: only FULL is valid, PENDING/EMPTY throw error
+     * - Gloas blocks: returns the specified variant index, or undefined if that variant doesn't exist
+     *
+     * Note: payloadStatus is required. Use getDefaultVariant() to get the canonical variant.
+     */
+    getNodeIndexByRootAndStatus(root, payloadStatus) {
+        const variantOrArr = this.indices.get(root);
+        if (variantOrArr == null) {
+            return undefined;
+        }
+        // Pre-Gloas: only FULL variant exists
+        if (!Array.isArray(variantOrArr)) {
+            // Return FULL variant if no status specified or FULL explicitly requested
+            if (payloadStatus === PayloadStatus.FULL) {
+                return variantOrArr;
+            }
+            // PENDING and EMPTY are invalid for pre-Gloas blocks
+            throw new ProtoArrayError({
+                code: ProtoArrayErrorCode.INVALID_NODE_INDEX,
+                index: payloadStatus,
+            });
+        }
+        // Gloas: return the specified variant, or PENDING if not specified
+        return variantOrArr[payloadStatus];
+    }
+    /**
+     * Get the default/canonical payload status for a block root
+     * - Pre-Gloas blocks: Returns FULL (payload embedded in block)
+     * - Gloas blocks: Returns PENDING (canonical variant)
+     *
+     * @param blockRoot - The block root to check
+     * @returns PayloadStatus.FULL for pre-Gloas, PayloadStatus.PENDING for Gloas, undefined if block not found
+     */
+    getDefaultVariant(blockRoot) {
+        const variantOrArr = this.indices.get(blockRoot);
+        if (variantOrArr == null) {
+            return undefined;
+        }
+        // Pre-Gloas: only FULL variant exists
+        if (!Array.isArray(variantOrArr)) {
+            return PayloadStatus.FULL;
+        }
+        // Gloas: multiple variants exist, PENDING is canonical
+        return PayloadStatus.PENDING;
+    }
+    /**
+     * Determine which parent payload status a block extends
+     * Spec: gloas/fork-choice.md#new-get_parent_payload_status
+     *   def get_parent_payload_status(store: Store, block: BeaconBlock) -> PayloadStatus:
+     *     parent = store.blocks[block.parent_root]
+     *     parent_block_hash = block.body.signed_execution_payload_bid.message.parent_block_hash
+     *     message_block_hash = parent.body.signed_execution_payload_bid.message.block_hash
+     *     return PAYLOAD_STATUS_FULL if parent_block_hash == message_block_hash else PAYLOAD_STATUS_EMPTY
+     *
+     * In lodestar forkchoice, we don't store the full bid, so we compares parent_block_hash in child's bid with executionPayloadBlockHash in parent:
+     * - If it matches EMPTY variant, return EMPTY
+     * - If it matches FULL variant, return FULL
+     * - If no match, throw UNKNOWN_PARENT_BLOCK error
+     *
+     * For pre-Gloas blocks: always returns FULL
+     */
+    getParentPayloadStatus(block) {
+        // Pre-Gloas blocks have payloads embedded, so parents are always FULL
+        const { parentBlockHash } = block;
+        if (parentBlockHash === null) {
+            return PayloadStatus.FULL;
+        }
+        const parentBlock = this.getBlockHexAndBlockHash(block.parentRoot, parentBlockHash);
+        if (parentBlock == null) {
+            throw new ProtoArrayError({
+                code: ProtoArrayErrorCode.UNKNOWN_PARENT_BLOCK,
+                parentRoot: block.parentRoot,
+                parentHash: parentBlockHash,
+            });
+        }
+        return parentBlock.payloadStatus;
+    }
+    /**
+     * Return the parent `ProtoBlock` given its root and block hash.
+     */
+    getParent(parentRoot, parentBlockHash) {
+        // pre-gloas
+        if (parentBlockHash === null) {
+            const parentIndex = this.indices.get(parentRoot);
+            if (parentIndex === undefined) {
+                return null;
+            }
+            if (Array.isArray(parentIndex)) {
+                // Gloas block found when pre-gloas expected
+                throw new ProtoArrayError({
+                    code: ProtoArrayErrorCode.UNKNOWN_PARENT_BLOCK,
+                    parentRoot,
+                    parentHash: parentBlockHash,
+                });
+            }
+            return this.nodes[parentIndex] ?? null;
+        }
+        // post-gloas
+        return this.getBlockHexAndBlockHash(parentRoot, parentBlockHash);
+    }
+    /**
+     * Returns an EMPTY or FULL `ProtoBlock` that has matching block root and block hash
+     */
+    getBlockHexAndBlockHash(blockRoot, blockHash) {
+        const variantIndices = this.indices.get(blockRoot);
+        if (variantIndices === undefined) {
+            return null;
+        }
+        // Pre-Gloas
+        if (!Array.isArray(variantIndices)) {
+            const node = this.nodes[variantIndices];
+            return node.executionPayloadBlockHash === blockHash ? node : null;
+        }
+        // Post-Gloas, check empty and full variants
+        const fullNodeIndex = variantIndices[PayloadStatus.FULL];
+        if (fullNodeIndex !== undefined) {
+            const fullNode = this.nodes[fullNodeIndex];
+            if (fullNode && fullNode.executionPayloadBlockHash === blockHash) {
+                return fullNode;
+            }
+        }
+        const emptyNode = this.nodes[variantIndices[PayloadStatus.EMPTY]];
+        if (emptyNode && emptyNode.executionPayloadBlockHash === blockHash) {
+            return emptyNode;
+        }
+        // PENDING is the same to EMPTY so not likely we can return it
+        // also it's only specific for fork-choice
+        return null;
+    }
     /**
      * Iterate backwards through the array, touching all nodes and their parents and potentially
      * the best-child of each parent.
@@ -56,11 +217,11 @@ export class ProtoArray {
      * - If required, update the parents best-descendant with the current node or its best-descendant.
      */
     applyScoreChanges({ deltas, proposerBoost, justifiedEpoch, justifiedRoot, finalizedEpoch, finalizedRoot, currentSlot, }) {
-        if (deltas.length !== this.indices.size) {
+        if (deltas.length !== this.nodes.length) {
             throw new ProtoArrayError({
                 code: ProtoArrayErrorCode.INVALID_DELTA_LEN,
                 deltas: deltas.length,
-                indices: this.indices.size,
+                indices: this.nodes.length,
             });
         }
         if (justifiedEpoch !== this.justifiedEpoch ||
@@ -129,7 +290,7 @@ export class ProtoArray {
             // If the node has a parent, try to update its best-child and best-descendant.
             const parentIndex = node.parent;
             if (parentIndex !== undefined) {
-                this.maybeUpdateBestChildAndDescendant(parentIndex, nodeIndex, currentSlot);
+                this.maybeUpdateBestChildAndDescendant(parentIndex, nodeIndex, currentSlot, proposerBoost?.root ?? null);
             }
         }
         // Update the previous proposer boost
@@ -140,9 +301,9 @@ export class ProtoArray {
      *
      * It is only sane to supply an undefined parent for the genesis block
      */
-    onBlock(block, currentSlot) {
+    onBlock(block, currentSlot, proposerBoostRoot) {
         // If the block is already known, simply ignore it
-        if (this.indices.has(block.blockRoot)) {
+        if (this.hasBlock(block.blockRoot)) {
             return;
         }
         if (block.executionStatus === ExecutionStatus.Invalid) {
@@ -151,30 +312,258 @@ export class ProtoArray {
                 root: block.blockRoot,
             });
         }
-        const node = {
-            ...block,
-            parent: this.indices.get(block.parentRoot),
+        if (isGloasBlock(block)) {
+            // Gloas: Create PENDING + EMPTY nodes with correct parent relationships
+            // Parent of new PENDING node = parent block's EMPTY or FULL (inter-block edge)
+            // Parent of new EMPTY node = own PENDING node (intra-block edge)
+            // For fork transition: if parent is pre-Gloas, point to parent's FULL
+            // Otherwise, determine which parent payload status this block extends
+            let parentIndex;
+            // Check if parent exists by getting variants array
+            const parentVariants = this.indices.get(block.parentRoot);
+            if (parentVariants != null) {
+                const anyParentIndex = Array.isArray(parentVariants) ? parentVariants[0] : parentVariants;
+                const anyParentNode = this.nodes[anyParentIndex];
+                if (!isGloasBlock(anyParentNode)) {
+                    // Fork transition: parent is pre-Gloas, so it only has FULL variant at variants[0]
+                    parentIndex = anyParentIndex;
+                }
+                else {
+                    // Both blocks are Gloas: determine which parent payload status to extend
+                    const parentPayloadStatus = this.getParentPayloadStatus(block);
+                    parentIndex = this.getNodeIndexByRootAndStatus(block.parentRoot, parentPayloadStatus);
+                }
+            }
+            // else: parent doesn't exist, parentIndex remains undefined (orphan block)
+            // Create PENDING node
+            const pendingNode = {
+                ...block,
+                parent: parentIndex, // Points to parent's EMPTY/FULL or FULL (for transition)
+                payloadStatus: PayloadStatus.PENDING,
+                weight: 0,
+                bestChild: undefined,
+                bestDescendant: undefined,
+            };
+            const pendingIndex = this.nodes.length;
+            this.nodes.push(pendingNode);
+            // Create EMPTY variant as a child of PENDING
+            const emptyNode = {
+                ...block,
+                parent: pendingIndex, // Points to own PENDING
+                payloadStatus: PayloadStatus.EMPTY,
+                weight: 0,
+                bestChild: undefined,
+                bestDescendant: undefined,
+            };
+            const emptyIndex = this.nodes.length;
+            this.nodes.push(emptyNode);
+            // Store both variants in the indices array
+            // [PENDING, EMPTY, undefined] - FULL will be added later if payload arrives
+            this.indices.set(block.blockRoot, [pendingIndex, emptyIndex]);
+            // Update bestChild pointers
+            if (parentIndex !== undefined) {
+                this.maybeUpdateBestChildAndDescendant(parentIndex, pendingIndex, currentSlot, proposerBoostRoot);
+                if (pendingNode.executionStatus === ExecutionStatus.Valid) {
+                    this.propagateValidExecutionStatusByIndex(parentIndex);
+                }
+            }
+            // Update bestChild for PENDING → EMPTY edge
+            this.maybeUpdateBestChildAndDescendant(pendingIndex, emptyIndex, currentSlot, proposerBoostRoot);
+            // Initialize PTC votes for this block (all false initially)
+            // Spec: gloas/fork-choice.md#modified-on_block (line 645)
+            this.ptcVotes.set(block.blockRoot, new Array(PTC_SIZE).fill(false));
+        }
+        else {
+            // Pre-Gloas: Only create FULL node (payload embedded in block)
+            const node = {
+                ...block,
+                parent: this.getNodeIndexByRootAndStatus(block.parentRoot, PayloadStatus.FULL),
+                payloadStatus: PayloadStatus.FULL,
+                weight: 0,
+                bestChild: undefined,
+                bestDescendant: undefined,
+            };
+            const nodeIndex = this.nodes.length;
+            this.nodes.push(node);
+            // Pre-Gloas: store FULL index instead of array
+            this.indices.set(block.blockRoot, nodeIndex);
+            // If this node is valid, lets propagate the valid status up the chain
+            // and throw error if we counter invalid, as this breaks consensus
+            if (node.parent !== undefined) {
+                this.maybeUpdateBestChildAndDescendant(node.parent, nodeIndex, currentSlot, proposerBoostRoot);
+                if (node.executionStatus === ExecutionStatus.Valid) {
+                    this.propagateValidExecutionStatusByIndex(node.parent);
+                }
+            }
+        }
+    }
+    /**
+     * Called when an execution payload is received for a block (Gloas only)
+     * Creates a FULL variant node as a sibling to the existing EMPTY variant
+     * Both EMPTY and FULL have parent = own PENDING node
+     *
+     * Spec: gloas/fork-choice.md (on_execution_payload event)
+     */
+    onExecutionPayload(blockRoot, currentSlot, executionPayloadBlockHash, executionPayloadNumber, executionPayloadStateRoot, proposerBoostRoot) {
+        // First check if block exists
+        const variants = this.indices.get(blockRoot);
+        if (variants == null) {
+            // Equivalent to `assert envelope.beacon_block_root in store.block_states`
+            throw new ProtoArrayError({
+                code: ProtoArrayErrorCode.UNKNOWN_BLOCK,
+                root: blockRoot,
+            });
+        }
+        if (!Array.isArray(variants)) {
+            // Pre-gloas block should not be calling this method
+            throw new ProtoArrayError({
+                code: ProtoArrayErrorCode.PRE_GLOAS_BLOCK,
+                root: blockRoot,
+            });
+        }
+        // Check if FULL already exists for Gloas blocks
+        if (variants[PayloadStatus.FULL] !== undefined) {
+            return;
+        }
+        // Get PENDING node for Gloas blocks
+        const pendingIndex = variants[PayloadStatus.PENDING];
+        if (pendingIndex === undefined) {
+            throw new ProtoArrayError({
+                code: ProtoArrayErrorCode.UNKNOWN_BLOCK,
+                root: blockRoot,
+            });
+        }
+        const pendingNode = this.nodes[pendingIndex];
+        if (!pendingNode) {
+            throw new ProtoArrayError({
+                code: ProtoArrayErrorCode.INVALID_NODE_INDEX,
+                index: pendingIndex,
+            });
+        }
+        // Create FULL variant as a child of PENDING (sibling to EMPTY)
+        const fullNode = {
+            ...pendingNode,
+            parent: pendingIndex, // Points to own PENDING (same as EMPTY)
+            payloadStatus: PayloadStatus.FULL,
             weight: 0,
             bestChild: undefined,
             bestDescendant: undefined,
+            executionStatus: ExecutionStatus.Valid,
+            executionPayloadBlockHash,
+            executionPayloadNumber,
+            stateRoot: executionPayloadStateRoot,
         };
-        const nodeIndex = this.nodes.length;
-        this.indices.set(node.blockRoot, nodeIndex);
-        this.nodes.push(node);
-        // If this node is valid, lets propagate the valid status up the chain
-        // and throw error if we counter invalid, as this breaks consensus
-        if (node.parent !== undefined) {
-            this.maybeUpdateBestChildAndDescendant(node.parent, nodeIndex, currentSlot);
-            if (node.executionStatus === ExecutionStatus.Valid) {
-                this.propagateValidExecutionStatusByIndex(node.parent);
+        const fullIndex = this.nodes.length;
+        this.nodes.push(fullNode);
+        // Add FULL variant to the indices array
+        variants[PayloadStatus.FULL] = fullIndex;
+        // Update bestChild for PENDING node (may now prefer FULL over EMPTY)
+        this.maybeUpdateBestChildAndDescendant(pendingIndex, fullIndex, currentSlot, proposerBoostRoot);
+    }
+    /**
+     * Update PTC votes for multiple validators attesting to a block
+     * Spec: gloas/fork-choice.md#new-on_payload_attestation_message
+     *
+     * @param blockRoot - The beacon block root being attested
+     * @param ptcIndices - Array of PTC committee indices that voted (0..PTC_SIZE-1)
+     * @param payloadPresent - Whether the validators attest the payload is present
+     */
+    notifyPtcMessages(blockRoot, ptcIndices, payloadPresent) {
+        const votes = this.ptcVotes.get(blockRoot);
+        if (votes === undefined) {
+            // Block not found or not a Gloas block, ignore
+            return;
+        }
+        for (const ptcIndex of ptcIndices) {
+            if (ptcIndex < 0 || ptcIndex >= PTC_SIZE) {
+                throw new Error(`Invalid PTC index: ${ptcIndex}, must be 0..${PTC_SIZE - 1}`);
             }
+            // Update the vote
+            votes[ptcIndex] = payloadPresent;
+        }
+    }
+    /**
+     * Check if execution payload for a block is timely
+     * Spec: gloas/fork-choice.md#new-is_payload_timely
+     *
+     * Returns true if:
+     * 1. Block has PTC votes tracked
+     * 2. Payload is locally available (FULL variant exists in proto array)
+     * 3. More than PAYLOAD_TIMELY_THRESHOLD (>50% of PTC) members voted payload_present=true
+     *
+     * @param blockRoot - The beacon block root to check
+     */
+    isPayloadTimely(blockRoot) {
+        const votes = this.ptcVotes.get(blockRoot);
+        if (votes === undefined) {
+            // Block not found or not a Gloas block
+            return false;
+        }
+        // If payload is not locally available, it's not timely
+        // In our implementation, payload is locally available if proto array has FULL variant of the block
+        const fullNodeIndex = this.getNodeIndexByRootAndStatus(blockRoot, PayloadStatus.FULL);
+        if (fullNodeIndex === undefined) {
+            return false;
+        }
+        // Count votes for payload_present=true
+        const yesVotes = votes.filter((v) => v).length;
+        return yesVotes > PAYLOAD_TIMELY_THRESHOLD;
+    }
+    /**
+     * Check if parent node is FULL
+     * Spec: gloas/fork-choice.md#new-is_parent_node_full
+     *
+     * Returns true if the parent payload status (determined by block.parentBlockHash) is FULL
+     */
+    isParentNodeFull(block) {
+        return this.getParentPayloadStatus(block) === PayloadStatus.FULL;
+    }
+    /**
+     * Determine if we should extend the payload (prefer FULL over EMPTY)
+     * Spec: gloas/fork-choice.md#new-should_extend_payload
+     *
+     * Returns true if:
+     * 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
+     * 4. Proposer boost root extends FULL parent
+     *
+     * @param blockRoot - The block root to check
+     * @param proposerBoostRoot - Current proposer boost root (from ForkChoice)
+     */
+    shouldExtendPayload(blockRoot, proposerBoostRoot) {
+        // Condition 1: Payload is timely
+        if (this.isPayloadTimely(blockRoot)) {
+            return true;
+        }
+        // Condition 2: No proposer boost root
+        if (proposerBoostRoot === null || proposerBoostRoot === HEX_ZERO_HASH) {
+            return true;
+        }
+        // Get proposer boost block
+        // We don't care about variant here, just need proposer boost block info
+        const defaultStatus = this.getDefaultVariant(proposerBoostRoot);
+        const proposerBoostBlock = defaultStatus !== undefined ? this.getNode(proposerBoostRoot, defaultStatus) : undefined;
+        if (!proposerBoostBlock) {
+            // Proposer boost block not found, default to extending payload
+            return true;
+        }
+        // Condition 3: Proposer boost root's parent is not this block
+        if (proposerBoostBlock.parentRoot !== blockRoot) {
+            return true;
+        }
+        // Condition 4: Proposer boost root extends FULL parent
+        if (this.isParentNodeFull(proposerBoostBlock)) {
+            return true;
         }
+        return false;
     }
     /**
      * Optimistic sync validate till validated latest hash, invalidate any descendant branch
      * if invalidate till hash provided. If consensus fails, this will invalidate entire
      * forkChoice which will throw on any call to findHead
      */
+    // TODO GLOAS: Review usage of this post-gloas
     validateLatestHash(execResponse, currentSlot) {
         // Look reverse because its highly likely node with latestValidExecHash is towards the
         // the leaves of the forkchoice
@@ -216,7 +605,11 @@ export class ProtoArray {
             // if its in fcU.
             //
             const { invalidateFromParentBlockRoot, latestValidExecHash } = execResponse;
-            const invalidateFromParentIndex = this.indices.get(invalidateFromParentBlockRoot);
+            // TODO GLOAS: verify if getting default variant is correct here
+            const defaultStatus = this.getDefaultVariant(invalidateFromParentBlockRoot);
+            const invalidateFromParentIndex = defaultStatus !== undefined
+                ? this.getNodeIndexByRootAndStatus(invalidateFromParentBlockRoot, defaultStatus)
+                : undefined;
             if (invalidateFromParentIndex === undefined) {
                 throw Error(`Unable to find invalidateFromParentBlockRoot=${invalidateFromParentBlockRoot} in forkChoice`);
             }
@@ -356,8 +749,41 @@ export class ProtoArray {
         }
         return validNode;
     }
+    /**
+     * Get payload status tiebreaker for fork choice comparison
+     * Spec: gloas/fork-choice.md#new-get_payload_status_tiebreaker
+     *
+     * For PENDING nodes: always returns 0
+     * For EMPTY/FULL variants from slot n-1: implements tiebreaker logic based on should_extend_payload
+     * For older blocks: returns node.payloadStatus
+     *
+     * Note: pre-gloas logic won't reach here. Pre-Gloas blocks have different roots, so they are always resolved by the weight and root tiebreaker before reaching here.
+     */
+    getPayloadStatusTiebreaker(node, currentSlot, proposerBoostRoot) {
+        // PENDING nodes always return PENDING (no tiebreaker needed)
+        // PENDING=0, EMPTY=1, FULL=2
+        if (node.payloadStatus === PayloadStatus.PENDING) {
+            return node.payloadStatus;
+        }
+        // For Gloas: check if from previous slot
+        if (node.slot + 1 !== currentSlot) {
+            return node.payloadStatus;
+        }
+        // For previous slot blocks in Gloas, decide between FULL and EMPTY
+        // based on should_extend_payload
+        if (node.payloadStatus === PayloadStatus.EMPTY) {
+            return PayloadStatus.EMPTY;
+        }
+        // FULL - check should_extend_payload
+        const shouldExtend = this.shouldExtendPayload(node.blockRoot, proposerBoostRoot);
+        return shouldExtend ? PayloadStatus.FULL : PayloadStatus.PENDING;
+    }
     /**
      * Follows the best-descendant links to find the best-block (i.e., head-block).
+     *
+     * Returns the ProtoNode representing the head.
+     * For pre-Gloas forks, only FULL variants exist (payload embedded).
+     * For Gloas, may return PENDING/EMPTY/FULL variants.
      */
     findHead(justifiedRoot, currentSlot) {
         if (this.lvhError) {
@@ -366,7 +792,9 @@ export class ProtoArray {
                 ...this.lvhError,
             });
         }
-        const justifiedIndex = this.indices.get(justifiedRoot);
+        // Get canonical node: FULL for pre-Gloas, PENDING for Gloas
+        const defaultStatus = this.getDefaultVariant(justifiedRoot);
+        const justifiedIndex = defaultStatus !== undefined ? this.getNodeIndexByRootAndStatus(justifiedRoot, defaultStatus) : undefined;
         if (justifiedIndex === undefined) {
             throw new ProtoArrayError({
                 code: ProtoArrayErrorCode.JUSTIFIED_NODE_UNKNOWN,
@@ -412,7 +840,7 @@ export class ProtoArray {
                 headFinalizedEpoch: justifiedNode.finalizedEpoch,
             });
         }
-        return bestNode.blockRoot;
+        return bestNode;
     }
     /**
      * Update the tree with new finalization information. The tree is only actually pruned if both
@@ -430,38 +858,68 @@ export class ProtoArray {
      * - There is some internal error relating to invalid indices inside `this`.
      */
     maybePrune(finalizedRoot) {
-        const finalizedIndex = this.indices.get(finalizedRoot);
-        if (finalizedIndex === undefined) {
+        const variants = this.indices.get(finalizedRoot);
+        if (variants == null) {
             throw new ProtoArrayError({
                 code: ProtoArrayErrorCode.FINALIZED_NODE_UNKNOWN,
                 root: finalizedRoot,
             });
         }
+        // Find the minimum index among all variants to ensure we don't prune too much
+        const finalizedIndex = Array.isArray(variants)
+            ? Math.min(...variants.filter((idx) => idx !== undefined))
+            : variants;
         if (finalizedIndex < this.pruneThreshold) {
             // Pruning at small numbers incurs more cost than benefit
             return [];
         }
-        // Remove the this.indices key/values for all the to-be-deleted nodes
-        for (let nodeIndex = 0; nodeIndex < finalizedIndex; nodeIndex++) {
-            const node = this.nodes[nodeIndex];
+        // Collect all block roots that will be pruned
+        const prunedRoots = new Set();
+        for (let i = 0; i < finalizedIndex; i++) {
+            const node = this.nodes[i];
             if (node === undefined) {
-                throw new ProtoArrayError({ code: ProtoArrayErrorCode.INVALID_NODE_INDEX, index: nodeIndex });
+                throw new ProtoArrayError({ code: ProtoArrayErrorCode.INVALID_NODE_INDEX, index: i });
             }
-            this.indices.delete(node.blockRoot);
+            prunedRoots.add(node.blockRoot);
+        }
+        // Remove indices for pruned blocks and PTC votes
+        for (const root of prunedRoots) {
+            this.indices.delete(root);
+            // Prune PTC votes for this block to prevent memory leak
+            // Spec: gloas/fork-choice.md (implicit - finalized blocks don't need PTC votes)
+            this.ptcVotes.delete(root);
         }
         // Store nodes prior to finalization
         const removed = this.nodes.slice(0, finalizedIndex);
         // Drop all the nodes prior to finalization
         this.nodes = this.nodes.slice(finalizedIndex);
-        // Adjust the indices map
-        for (const [key, value] of this.indices.entries()) {
-            if (value < finalizedIndex) {
-                throw new ProtoArrayError({
-                    code: ProtoArrayErrorCode.INDEX_OVERFLOW,
-                    value: "indices",
-                });
+        // Adjust the indices map - subtract finalizedIndex from all node indices
+        for (const [root, variantIndices] of this.indices.entries()) {
+            // Pre-Gloas: single index
+            if (!Array.isArray(variantIndices)) {
+                if (variantIndices < finalizedIndex) {
+                    throw new ProtoArrayError({
+                        code: ProtoArrayErrorCode.INDEX_OVERFLOW,
+                        value: "indices",
+                    });
+                }
+                this.indices.set(root, variantIndices - finalizedIndex);
+                continue;
             }
-            this.indices.set(key, value - finalizedIndex);
+            // Post-Gloas: array of variant indices
+            const adjustedVariants = variantIndices.map((variantIndex) => {
+                if (variantIndex === undefined) {
+                    return undefined;
+                }
+                if (variantIndex < finalizedIndex) {
+                    throw new ProtoArrayError({
+                        code: ProtoArrayErrorCode.INDEX_OVERFLOW,
+                        value: "indices",
+                    });
+                }
+                return variantIndex - finalizedIndex;
+            });
+            this.indices.set(root, adjustedVariants);
         }
         // Iterate through all the existing nodes and adjust their indices to match the new layout of this.nodes
         for (let i = 0, len = this.nodes.length; i < len; i++) {
@@ -508,7 +966,7 @@ export class ProtoArray {
      * - The child is not the best child but becomes the best child.
      * - The child is not the best child and does not become the best child.
      */
-    maybeUpdateBestChildAndDescendant(parentIndex, childIndex, currentSlot) {
+    maybeUpdateBestChildAndDescendant(parentIndex, childIndex, currentSlot, proposerBoostRoot) {
         const childNode = this.nodes[childIndex];
         if (childNode === undefined) {
             throw new ProtoArrayError({
@@ -529,61 +987,87 @@ export class ProtoArray {
         const noChange = [parentNode.bestChild, parentNode.bestDescendant];
         let newChildAndDescendant;
         const bestChildIndex = parentNode.bestChild;
-        if (bestChildIndex !== undefined) {
-            if (bestChildIndex === childIndex && !childLeadsToViableHead) {
-                // the child is already the best-child of the parent but its not viable for the head
-                // so remove it
-                newChildAndDescendant = changeToNull;
-            }
-            else if (bestChildIndex === childIndex) {
-                // the child is the best-child already
-                // set it again to ensure that the best-descendent of the parent is updated
-                newChildAndDescendant = changeToChild;
-            }
-            else {
-                const bestChildNode = this.nodes[bestChildIndex];
-                if (bestChildNode === undefined) {
-                    throw new ProtoArrayError({
-                        code: ProtoArrayErrorCode.INVALID_BEST_CHILD_INDEX,
-                        index: bestChildIndex,
-                    });
+        // biome-ignore lint/suspicious/noConfusingLabels: labeled block used for early exit from complex decision tree
+        outer: {
+            if (bestChildIndex !== undefined) {
+                if (bestChildIndex === childIndex && !childLeadsToViableHead) {
+                    // the child is already the best-child of the parent but its not viable for the head
+                    // so remove it
+                    newChildAndDescendant = changeToNull;
                 }
-                const bestChildLeadsToViableHead = this.nodeLeadsToViableHead(bestChildNode, currentSlot);
-                if (childLeadsToViableHead && !bestChildLeadsToViableHead) {
-                    // the child leads to a viable head, but the current best-child doesn't
+                else if (bestChildIndex === childIndex) {
+                    // the child is the best-child already
+                    // set it again to ensure that the best-descendent of the parent is updated
                     newChildAndDescendant = changeToChild;
                 }
-                else if (!childLeadsToViableHead && bestChildLeadsToViableHead) {
-                    // the best child leads to a viable head but the child doesn't
-                    newChildAndDescendant = noChange;
-                }
-                else if (childNode.weight === bestChildNode.weight) {
-                    // tie-breaker of equal weights by root
-                    if (childNode.blockRoot >= bestChildNode.blockRoot) {
+                else {
+                    const bestChildNode = this.nodes[bestChildIndex];
+                    if (bestChildNode === undefined) {
+                        throw new ProtoArrayError({
+                            code: ProtoArrayErrorCode.INVALID_BEST_CHILD_INDEX,
+                            index: bestChildIndex,
+                        });
+                    }
+                    const bestChildLeadsToViableHead = this.nodeLeadsToViableHead(bestChildNode, currentSlot);
+                    if (childLeadsToViableHead && !bestChildLeadsToViableHead) {
+                        // the child leads to a viable head, but the current best-child doesn't
                         newChildAndDescendant = changeToChild;
+                        break outer;
                     }
-                    else {
+                    if (!childLeadsToViableHead && bestChildLeadsToViableHead) {
+                        // the best child leads to a viable head but the child doesn't
                         newChildAndDescendant = noChange;
+                        break outer;
                     }
-                }
-                else {
-                    // choose the winner by weight
-                    if (childNode.weight >= bestChildNode.weight) {
+                    // Both nodes lead to viable heads (or both don't), need to pick winner
+                    // Pre-fulu we pick whichever has higher weight, tie-breaker by root
+                    // Post-fulu we pick whichever has higher weight, then tie-breaker by root, then tie-breaker by `getPayloadStatusTiebreaker`
+                    // Gloas: nodes from previous slot (n-1) with EMPTY/FULL variant have weight hardcoded to 0.
+                    // https://github.com/ethereum/consensus-specs/blob/69a2582d5d62c914b24894bdb65f4bd5d4e49ae4/specs/gloas/fork-choice.md?plain=1#L442
+                    const childEffectiveWeight = !isGloasBlock(childNode) ||
+                        childNode.payloadStatus === PayloadStatus.PENDING ||
+                        childNode.slot + 1 !== currentSlot
+                        ? childNode.weight
+                        : 0;
+                    const bestChildEffectiveWeight = !isGloasBlock(bestChildNode) ||
+                        bestChildNode.payloadStatus === PayloadStatus.PENDING ||
+                        bestChildNode.slot + 1 !== currentSlot
+                        ? bestChildNode.weight
+                        : 0;
+                    if (childEffectiveWeight !== bestChildEffectiveWeight) {
+                        // Different effective weights, choose the winner by weight
+                        newChildAndDescendant = childEffectiveWeight >= bestChildEffectiveWeight ? changeToChild : noChange;
+                        break outer;
+                    }
+                    if (childNode.blockRoot !== bestChildNode.blockRoot) {
+                        // Different blocks, tie-breaker by root
+                        newChildAndDescendant = childNode.blockRoot >= bestChildNode.blockRoot ? changeToChild : noChange;
+                        break outer;
+                    }
+                    // Same effective weight and same root — Gloas EMPTY vs FULL from n-1, tie-breaker by payload status
+                    // Note: pre-Gloas, each child node of a block has a unique root, so this point should not be reached
+                    const childTiebreaker = this.getPayloadStatusTiebreaker(childNode, currentSlot, proposerBoostRoot);
+                    const bestChildTiebreaker = this.getPayloadStatusTiebreaker(bestChildNode, currentSlot, proposerBoostRoot);
+                    if (childTiebreaker > bestChildTiebreaker) {
                         newChildAndDescendant = changeToChild;
                     }
+                    else if (childTiebreaker < bestChildTiebreaker) {
+                        newChildAndDescendant = noChange;
+                    }
                     else {
+                        // Equal in all aspects, noChange
                         newChildAndDescendant = noChange;
                     }
                 }
             }
-        }
-        else if (childLeadsToViableHead) {
-            // There is no current best-child and the child is viable.
-            newChildAndDescendant = changeToChild;
-        }
-        else {
-            // There is no current best-child but the child is not viable.
-            newChildAndDescendant = noChange;
+            else if (childLeadsToViableHead) {
+                // There is no current best-child and the child is viable.
+                newChildAndDescendant = changeToChild;
+            }
+            else {
+                // There is no current best-child but the child is not viable.
+                newChildAndDescendant = noChange;
+            }
         }
         parentNode.bestChild = newChildAndDescendant[0];
         parentNode.bestDescendant = newChildAndDescendant[1];
@@ -652,7 +1136,8 @@ export class ProtoArray {
             return true;
         }
         const finalizedSlot = computeStartSlotAtEpoch(this.finalizedEpoch);
-        return this.finalizedEpoch === 0 || this.finalizedRoot === this.getAncestorOrNull(node.blockRoot, finalizedSlot);
+        const ancestorNode = this.getAncestorOrNull(node.blockRoot, finalizedSlot);
+        return this.finalizedEpoch === 0 || (ancestorNode !== null && this.finalizedRoot === ancestorNode.blockRoot);
     }
     /**
      * Same to getAncestor but it may return null instead of throwing error
@@ -666,47 +1151,103 @@ export class ProtoArray {
         }
     }
     /**
-     * Returns the block root of an ancestor of `blockRoot` at the given `slot`.
+     * Returns the node identifier of an ancestor of `blockRoot` at the given `slot`.
      * (Note: `slot` refers to the block that is *returned*, not the one that is supplied.)
      *
      * NOTE: May be expensive: potentially walks through the entire fork of head to finalized block
      *
      * ### Specification
      *
-     * Equivalent to:
+     * Modified for Gloas to return node identifier 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, ancestorSlot) {
-        const block = this.getBlock(blockRoot);
-        if (!block) {
+        // Get any variant to check the block (use variants[0])
+        const variantOrArr = this.indices.get(blockRoot);
+        if (variantOrArr == null) {
             throw new ForkChoiceError({
                 code: ForkChoiceErrorCode.MISSING_PROTO_ARRAY_BLOCK,
                 root: blockRoot,
             });
         }
-        if (block.slot > ancestorSlot) {
-            // Search for a slot that is lte the target slot.
-            // We check for lower slots to account for skip slots.
-            for (const node of this.iterateAncestorNodes(blockRoot)) {
-                if (node.slot <= ancestorSlot) {
-                    return node.blockRoot;
-                }
+        const blockIndex = Array.isArray(variantOrArr) ? variantOrArr[0] : variantOrArr;
+        const block = this.nodes[blockIndex];
+        // If block is at or before queried slot, return PENDING variant (or FULL for pre-Gloas)
+        if (block.slot <= ancestorSlot) {
+            // For pre-Gloas: only FULL exists at variants[0]
+            // For Gloas: PENDING is at variants[0]
+            return block;
+        }
+        // Walk backwards through beacon blocks to find ancestor
+        // Start with the parent of the current block
+        let currentBlock = block;
+        const parentVariants = this.indices.get(currentBlock.parentRoot);
+        if (parentVariants == null) {
+            throw new ForkChoiceError({
+                code: ForkChoiceErrorCode.UNKNOWN_ANCESTOR,
+                descendantRoot: blockRoot,
+                ancestorSlot,
+            });
+        }
+        let parentIndex = Array.isArray(parentVariants) ? parentVariants[0] : parentVariants;
+        let parentBlock = this.nodes[parentIndex];
+        // Walk backwards while parent.slot > ancestorSlot
+        while (parentBlock.slot > ancestorSlot) {
+            currentBlock = parentBlock;
+            const nextParentVariants = this.indices.get(currentBlock.parentRoot);
+            if (nextParentVariants == null) {
+                throw new ForkChoiceError({
+                    code: ForkChoiceErrorCode.UNKNOWN_ANCESTOR,
+                    descendantRoot: blockRoot,
+                    ancestorSlot,
+                });
             }
+            parentIndex = Array.isArray(nextParentVariants) ? nextParentVariants[0] : nextParentVariants;
+            parentBlock = this.nodes[parentIndex];
+        }
+        // Now parentBlock.slot <= ancestorSlot
+        // Return the parent with the correct payload status based on currentBlock
+        if (!isGloasBlock(currentBlock)) {
+            // Pre-Gloas: return FULL variant (only one that exists)
+            return parentBlock;
+        }
+        // Gloas: determine which parent variant (EMPTY or FULL) based on parent_block_hash
+        const parentPayloadStatus = this.getParentPayloadStatus(currentBlock);
+        const parentVariantIndex = this.getNodeIndexByRootAndStatus(currentBlock.parentRoot, parentPayloadStatus);
+        if (parentVariantIndex === undefined) {
             throw new ForkChoiceError({
                 code: ForkChoiceErrorCode.UNKNOWN_ANCESTOR,
                 descendantRoot: blockRoot,
                 ancestorSlot,
             });
         }
-        // Root is older or equal than queried slot, thus a skip slot. Return most recent root prior to slot.
-        return blockRoot;
+        return this.nodes[parentVariantIndex];
+    }
+    /**
+     * Get the parent node index for traversal
+     * For Gloas blocks: returns the correct EMPTY/FULL variant based on parent payload status
+     * For pre-Gloas blocks: returns the simple parent index
+     * Returns undefined if parent doesn't exist or can't be found
+     */
+    getParentNodeIndex(node) {
+        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);
+        }
+        // Simple parent traversal for pre-Gloas blocks (includes fork transition)
+        return node.parent;
     }
     /**
      * Iterate from a block root backwards over nodes
+     * For Gloas blocks: returns EMPTY/FULL variants (not PENDING) based on parent payload status
+     * For pre-Gloas blocks: returns FULL variants
      */
-    *iterateAncestorNodes(blockRoot) {
-        const startIndex = this.indices.get(blockRoot);
+    *iterateAncestorNodes(blockRoot, payloadStatus) {
+        const startIndex = this.getNodeIndexByRootAndStatus(blockRoot, payloadStatus);
         if (startIndex === undefined) {
             return;
         }
@@ -720,19 +1261,28 @@ export class ProtoArray {
         yield* this.iterateAncestorNodesFromNode(node);
     }
     /**
-     * Iterate from a block root backwards over nodes
+     * Iterate from a node backwards over ancestor nodes
+     * For Gloas blocks: returns EMPTY/FULL variants (not PENDING) based on parent payload status
+     * For pre-Gloas blocks: returns FULL variants
+     * Handles fork transition from Gloas to pre-Gloas blocks
      */
     *iterateAncestorNodesFromNode(node) {
         while (node.parent !== undefined) {
-            node = this.getNodeFromIndex(node.parent);
+            const parentIndex = this.getParentNodeIndex(node);
+            if (parentIndex === undefined) {
+                break;
+            }
+            node = this.nodes[parentIndex];
             yield node;
         }
     }
     /**
      * Get all nodes from a block root backwards
+     * For Gloas blocks: returns EMPTY/FULL variants (not PENDING) based on parent payload status
+     * For pre-Gloas blocks: returns FULL variants
      */
-    getAllAncestorNodes(blockRoot) {
-        const startIndex = this.indices.get(blockRoot);
+    getAllAncestorNodes(blockRoot, payloadStatus) {
+        const startIndex = this.getNodeIndexByRootAndStatus(blockRoot, payloadStatus);
         if (startIndex === undefined) {
             return [];
         }
@@ -743,9 +1293,17 @@ export class ProtoArray {
                 index: startIndex,
             });
         }
-        const nodes = [node];
+        // Exclude PENDING variant from returned ancestors.
+        const nodes = [];
+        if (node.payloadStatus !== PayloadStatus.PENDING) {
+            nodes.push(node);
+        }
         while (node.parent !== undefined) {
-            node = this.getNodeFromIndex(node.parent);
+            const parentIndex = this.getParentNodeIndex(node);
+            if (parentIndex === undefined) {
+                break;
+            }
+            node = this.nodes[parentIndex];
             nodes.push(node);
         }
         return nodes;
@@ -754,9 +1312,12 @@ export class ProtoArray {
      * The opposite of iterateNodes.
      * iterateNodes is to find ancestor nodes of a blockRoot.
      * this is to find non-ancestor nodes of a blockRoot.
+     *
+     * For Gloas blocks: returns EMPTY/FULL variants (not PENDING) based on parent payload status
+     * For pre-Gloas blocks: returns FULL variants
      */
-    getAllNonAncestorNodes(blockRoot) {
-        const startIndex = this.indices.get(blockRoot);
+    getAllNonAncestorNodes(blockRoot, payloadStatus) {
+        const startIndex = this.getNodeIndexByRootAndStatus(blockRoot, payloadStatus);
         if (startIndex === undefined) {
             return [];
         }
@@ -767,23 +1328,31 @@ export class ProtoArray {
                 index: startIndex,
             });
         }
+        // For both Gloas and pre-Gloas blocks
         const result = [];
         let nodeIndex = startIndex;
         while (node.parent !== undefined) {
-            const parentIndex = node.parent;
-            node = this.getNodeFromIndex(parentIndex);
-            // nodes between nodeIndex and parentIndex means non-ancestor nodes
-            result.push(...this.getNodesBetween(nodeIndex, parentIndex));
+            const parentIndex = this.getParentNodeIndex(node);
+            if (parentIndex === undefined) {
+                break;
+            }
+            node = this.nodes[parentIndex];
+            // Collect non-ancestor nodes between current and parent
+            // Filter to exclude PENDING nodes (FULL variant pre-gloas, EMPTY or FULL variant post-gloas)
+            result.push(...this.getNodesBetween(nodeIndex, parentIndex).filter((n) => n.payloadStatus !== PayloadStatus.PENDING));
             nodeIndex = parentIndex;
         }
-        result.push(...this.getNodesBetween(nodeIndex, 0));
+        // Collect remaining nodes from nodeIndex to beginning
+        result.push(...this.getNodesBetween(nodeIndex, 0).filter((n) => n.payloadStatus !== PayloadStatus.PENDING));
         return result;
     }
     /**
      * Returns both ancestor and non-ancestor nodes in a single traversal.
+     * For Gloas blocks: returns EMPTY/FULL variants (not PENDING) based on parent payload status
+     * For pre-Gloas blocks: returns FULL variants
      */
-    getAllAncestorAndNonAncestorNodes(blockRoot) {
-        const startIndex = this.indices.get(blockRoot);
+    getAllAncestorAndNonAncestorNodes(blockRoot, payloadStatus) {
+        const startIndex = this.getNodeIndexByRootAndStatus(blockRoot, payloadStatus);
         if (startIndex === undefined) {
             return { ancestors: [], nonAncestors: [] };
         }
@@ -796,32 +1365,68 @@ export class ProtoArray {
         }
         const ancestors = [];
         const nonAncestors = [];
+        // 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);
+        }
         let nodeIndex = startIndex;
         while (node.parent !== undefined) {
+            const parentIndex = this.getParentNodeIndex(node);
+            if (parentIndex === undefined) {
+                break;
+            }
+            node = this.nodes[parentIndex];
             ancestors.push(node);
-            const parentIndex = node.parent;
-            node = this.getNodeFromIndex(parentIndex);
-            // Nodes between nodeIndex and parentIndex are non-ancestor nodes
-            nonAncestors.push(...this.getNodesBetween(nodeIndex, parentIndex));
+            // Collect non-ancestor nodes between current and parent
+            // Filter to exclude PENDING nodes (include all FULL/EMPTY for both pre-Gloas and Gloas)
+            nonAncestors.push(...this.getNodesBetween(nodeIndex, parentIndex).filter((n) => n.payloadStatus !== PayloadStatus.PENDING));
             nodeIndex = parentIndex;
         }
-        ancestors.push(node);
-        nonAncestors.push(...this.getNodesBetween(nodeIndex, 0));
+        // Collect remaining non-ancestor nodes from nodeIndex to beginning
+        nonAncestors.push(...this.getNodesBetween(nodeIndex, 0).filter((n) => n.payloadStatus !== PayloadStatus.PENDING));
         return { ancestors, nonAncestors };
     }
+    /**
+     * Check if a block exists in the proto array
+     * Uses default variant (PENDING for Gloas, FULL for pre-Gloas)
+     */
     hasBlock(blockRoot) {
-        return this.indices.has(blockRoot);
+        const defaultVariant = this.getDefaultVariant(blockRoot);
+        if (defaultVariant === undefined) {
+            return false;
+        }
+        const index = this.getNodeIndexByRootAndStatus(blockRoot, defaultVariant);
+        return index !== undefined;
     }
-    getNode(blockRoot) {
-        const blockIndex = this.indices.get(blockRoot);
+    /**
+     * Return ProtoNode for blockRoot with explicit payload status
+     *
+     * @param blockRoot - The block root to look up
+     * @param payloadStatus - The specific payload status variant (PENDING/EMPTY/FULL)
+     * @returns The ProtoNode for the specified variant, or undefined if not found
+     *
+     * Note: Callers must explicitly specify which variant they need.
+     * Use getDefaultVariant() to get the canonical variant for a block.
+     */
+    getNode(blockRoot, payloadStatus) {
+        const blockIndex = this.getNodeIndexByRootAndStatus(blockRoot, payloadStatus);
         if (blockIndex === undefined) {
             return undefined;
         }
         return this.getNodeByIndex(blockIndex);
     }
-    /** Return MUTABLE ProtoBlock for blockRoot (spreads properties) */
-    getBlock(blockRoot) {
-        const node = this.getNode(blockRoot);
+    /**
+     * Return MUTABLE ProtoBlock for blockRoot with explicit payload status
+     *
+     * @param blockRoot - The block root to look up
+     * @param payloadStatus - The specific payload status variant (PENDING/EMPTY/FULL)
+     * @returns The ProtoBlock for the specified variant (spreads properties), or undefined if not found
+     *
+     * Note: Callers must explicitly specify which variant they need.
+     * Use getDefaultVariant() to get the canonical variant for a block.
+     */
+    getBlock(blockRoot, payloadStatus) {
+        const node = this.getNode(blockRoot, payloadStatus);
         if (!node) {
             return undefined;
         }
@@ -829,9 +1434,19 @@ export class ProtoArray {
             ...node,
         };
     }
-    /** Return NON-MUTABLE ProtoBlock for blockRoot (does not spread properties) */
-    getBlockReadonly(blockRoot) {
-        const node = this.getNode(blockRoot);
+    /**
+     * Return NON-MUTABLE ProtoBlock for blockRoot with explicit payload status
+     *
+     * @param blockRoot - The block root to look up
+     * @param payloadStatus - The specific payload status variant (PENDING/EMPTY/FULL)
+     * @returns The ProtoBlock for the specified variant (does not spread properties)
+     * @throws Error if block not found
+     *
+     * Note: Callers must explicitly specify which variant they need.
+     * Use getDefaultVariant() to get the canonical variant for a block.
+     */
+    getBlockReadonly(blockRoot, payloadStatus) {
+        const node = this.getNode(blockRoot, payloadStatus);
         if (!node) {
             throw Error(`No block for root ${blockRoot}`);
         }
@@ -840,21 +1455,21 @@ 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, descendantRoot) {
-        const ancestorNode = this.getNode(ancestorRoot);
+    isDescendant(ancestorRoot, ancestorPayloadStatus, descendantRoot, descendantPayloadStatus) {
+        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;
             }
         }