@lodestar/fork-choice 1.41.0-dev.c8abf8f187 → 1.41.0-dev.cfc5790a15

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (48) hide show
  1. package/lib/forkChoice/errors.d.ts +9 -1
  2. package/lib/forkChoice/errors.d.ts.map +1 -1
  3. package/lib/forkChoice/errors.js +10 -3
  4. package/lib/forkChoice/errors.js.map +1 -1
  5. package/lib/forkChoice/forkChoice.d.ts +76 -20
  6. package/lib/forkChoice/forkChoice.d.ts.map +1 -1
  7. package/lib/forkChoice/forkChoice.js +304 -118
  8. package/lib/forkChoice/forkChoice.js.map +1 -1
  9. package/lib/forkChoice/interface.d.ts +54 -21
  10. package/lib/forkChoice/interface.d.ts.map +1 -1
  11. package/lib/forkChoice/interface.js +6 -3
  12. package/lib/forkChoice/interface.js.map +1 -1
  13. package/lib/forkChoice/safeBlocks.js.map +1 -1
  14. package/lib/forkChoice/store.d.ts +40 -16
  15. package/lib/forkChoice/store.d.ts.map +1 -1
  16. package/lib/forkChoice/store.js +22 -4
  17. package/lib/forkChoice/store.js.map +1 -1
  18. package/lib/index.d.ts +4 -4
  19. package/lib/index.d.ts.map +1 -1
  20. package/lib/index.js +2 -2
  21. package/lib/index.js.map +1 -1
  22. package/lib/metrics.d.ts.map +1 -1
  23. package/lib/metrics.js.map +1 -1
  24. package/lib/protoArray/computeDeltas.d.ts.map +1 -1
  25. package/lib/protoArray/computeDeltas.js +3 -0
  26. package/lib/protoArray/computeDeltas.js.map +1 -1
  27. package/lib/protoArray/errors.d.ts +15 -2
  28. package/lib/protoArray/errors.d.ts.map +1 -1
  29. package/lib/protoArray/errors.js +7 -2
  30. package/lib/protoArray/errors.js.map +1 -1
  31. package/lib/protoArray/interface.d.ts +33 -3
  32. package/lib/protoArray/interface.d.ts.map +1 -1
  33. package/lib/protoArray/interface.js +31 -1
  34. package/lib/protoArray/interface.js.map +1 -1
  35. package/lib/protoArray/protoArray.d.ts +219 -24
  36. package/lib/protoArray/protoArray.d.ts.map +1 -1
  37. package/lib/protoArray/protoArray.js +755 -134
  38. package/lib/protoArray/protoArray.js.map +1 -1
  39. package/package.json +9 -9
  40. package/src/forkChoice/errors.ts +7 -2
  41. package/src/forkChoice/forkChoice.ts +387 -127
  42. package/src/forkChoice/interface.ts +72 -20
  43. package/src/forkChoice/store.ts +52 -20
  44. package/src/index.ts +10 -2
  45. package/src/protoArray/computeDeltas.ts +6 -0
  46. package/src/protoArray/errors.ts +7 -1
  47. package/src/protoArray/interface.ts +48 -3
  48. package/src/protoArray/protoArray.ts +887 -135
@@ -1,16 +1,41 @@
1
- import {GENESIS_EPOCH} from "@lodestar/params";
1
+ import {BitArray} from "@chainsafe/ssz";
2
+ import {GENESIS_EPOCH, PTC_SIZE} from "@lodestar/params";
2
3
  import {computeEpochAtSlot, computeStartSlotAtEpoch} from "@lodestar/state-transition";
3
4
  import {Epoch, RootHex, Slot} from "@lodestar/types";
4
- import {toRootHex} from "@lodestar/utils";
5
+ import {bitCount, toRootHex} from "@lodestar/utils";
5
6
  import {ForkChoiceError, ForkChoiceErrorCode} from "../forkChoice/errors.js";
6
7
  import {LVHExecError, LVHExecErrorCode, ProtoArrayError, ProtoArrayErrorCode} from "./errors.js";
7
- import {ExecutionStatus, HEX_ZERO_HASH, LVHExecResponse, ProtoBlock, ProtoNode} from "./interface.js";
8
+ import {
9
+ ExecutionStatus,
10
+ HEX_ZERO_HASH,
11
+ LVHExecResponse,
12
+ PayloadStatus,
13
+ ProtoBlock,
14
+ ProtoNode,
15
+ isGloasBlock,
16
+ } from "./interface.js";
17
+
18
+ /**
19
+ * Threshold for payload timeliness (>50% of PTC must vote)
20
+ * Spec: gloas/fork-choice.md (PAYLOAD_TIMELY_THRESHOLD = PTC_SIZE // 2)
21
+ */
22
+ const PAYLOAD_TIMELY_THRESHOLD = Math.floor(PTC_SIZE / 2);
8
23
 
9
24
  export const DEFAULT_PRUNE_THRESHOLD = 0;
10
25
  type ProposerBoost = {root: RootHex; score: number};
11
26
 
12
27
  const ZERO_HASH_HEX = toRootHex(Buffer.alloc(32, 0));
13
28
 
29
+ /** Pre-Gloas: single element, FULL index (for backward compatibility) */
30
+ type PreGloasVariantIndex = number;
31
+ /**
32
+ * Post-Gloas: array length is 2 or 3
33
+ * - Length 2: [PENDING_INDEX, EMPTY_INDEX] when payload hasn't arrived yet
34
+ * - Length 3: [PENDING_INDEX, EMPTY_INDEX, FULL_INDEX] when payload has arrived
35
+ */
36
+ type GloasVariantIndices = [number, number] | [number, number, number];
37
+ type VariantIndices = PreGloasVariantIndex | GloasVariantIndices;
38
+
14
39
  export class ProtoArray {
15
40
  // Do not attempt to prune the tree unless it has at least this many nodes.
16
41
  // Small prunes simply waste time
@@ -20,11 +45,31 @@ export class ProtoArray {
20
45
  finalizedEpoch: Epoch;
21
46
  finalizedRoot: RootHex;
22
47
  nodes: ProtoNode[] = [];
23
- indices = new Map<RootHex, number>();
48
+ /**
49
+ * Maps block root to array of node indices for each payload status variant
50
+ *
51
+ * Array structure: [PENDING, EMPTY, FULL] where indices correspond to PayloadStatus enum values
52
+ * - number[0] = PENDING variant index (PayloadStatus.PENDING = 0)
53
+ * - number[1] = EMPTY variant index (PayloadStatus.EMPTY = 1)
54
+ * - number[2] = FULL variant index (PayloadStatus.FULL = 2)
55
+ *
56
+ * Note: undefined array elements indicate that variant doesn't exist for this block
57
+ */
58
+ indices = new Map<RootHex, VariantIndices>();
24
59
  lvhError?: LVHExecError;
25
60
 
26
61
  private previousProposerBoost: ProposerBoost | null = null;
27
62
 
63
+ /**
64
+ * PTC (Payload Timeliness Committee) votes per block as bitvectors
65
+ * Maps block root to BitArray of PTC_SIZE bits (512 mainnet, 2 minimal)
66
+ * Spec: gloas/fork-choice.md#modified-store (line 148)
67
+ *
68
+ * Bit i is set if PTC member i voted payload_present=true
69
+ * Used by is_payload_timely() to determine if payload is timely
70
+ */
71
+ private ptcVotes = new Map<RootHex, BitArray>();
72
+
28
73
  constructor({
29
74
  pruneThreshold,
30
75
  justifiedEpoch,
@@ -59,11 +104,166 @@ export class ProtoArray {
59
104
  // We are using the blockROot as the targetRoot, since it always lies on an epoch boundary
60
105
  targetRoot: block.blockRoot,
61
106
  } as ProtoBlock,
62
- currentSlot
107
+ currentSlot,
108
+ null
63
109
  );
64
110
  return protoArray;
65
111
  }
66
112
 
113
+ /**
114
+ * Get node index for a block root and payload status
115
+ *
116
+ * @param root - The block root to look up
117
+ * @param payloadStatus - The specific payload status variant (PENDING/EMPTY/FULL)
118
+ * @returns The node index for the specified variant, or undefined if not found
119
+ *
120
+ * Behavior:
121
+ * - Pre-Gloas blocks: only FULL is valid, PENDING/EMPTY throw error
122
+ * - Gloas blocks: returns the specified variant index, or undefined if that variant doesn't exist
123
+ *
124
+ * Note: payloadStatus is required. Use getDefaultVariant() to get the canonical variant.
125
+ */
126
+ getNodeIndexByRootAndStatus(root: RootHex, payloadStatus: PayloadStatus): number | undefined {
127
+ const variantOrArr = this.indices.get(root);
128
+ if (variantOrArr == null) {
129
+ return undefined;
130
+ }
131
+
132
+ // Pre-Gloas: only FULL variant exists
133
+ if (!Array.isArray(variantOrArr)) {
134
+ // Return FULL variant if no status specified or FULL explicitly requested
135
+ if (payloadStatus === PayloadStatus.FULL) {
136
+ return variantOrArr;
137
+ }
138
+ // PENDING and EMPTY are invalid for pre-Gloas blocks
139
+ throw new ProtoArrayError({
140
+ code: ProtoArrayErrorCode.INVALID_NODE_INDEX,
141
+ index: payloadStatus,
142
+ });
143
+ }
144
+
145
+ // Gloas: return the specified variant, or PENDING if not specified
146
+ return variantOrArr[payloadStatus];
147
+ }
148
+
149
+ /**
150
+ * Get the default/canonical payload status for a block root
151
+ * - Pre-Gloas blocks: Returns FULL (payload embedded in block)
152
+ * - Gloas blocks: Returns PENDING (canonical variant)
153
+ *
154
+ * @param blockRoot - The block root to check
155
+ * @returns PayloadStatus.FULL for pre-Gloas, PayloadStatus.PENDING for Gloas, undefined if block not found
156
+ */
157
+ getDefaultVariant(blockRoot: RootHex): PayloadStatus | undefined {
158
+ const variantOrArr = this.indices.get(blockRoot);
159
+ if (variantOrArr == null) {
160
+ return undefined;
161
+ }
162
+
163
+ // Pre-Gloas: only FULL variant exists
164
+ if (!Array.isArray(variantOrArr)) {
165
+ return PayloadStatus.FULL;
166
+ }
167
+
168
+ // Gloas: multiple variants exist, PENDING is canonical
169
+ return PayloadStatus.PENDING;
170
+ }
171
+
172
+ /**
173
+ * Determine which parent payload status a block extends
174
+ * Spec: gloas/fork-choice.md#new-get_parent_payload_status
175
+ * def get_parent_payload_status(store: Store, block: BeaconBlock) -> PayloadStatus:
176
+ * parent = store.blocks[block.parent_root]
177
+ * parent_block_hash = block.body.signed_execution_payload_bid.message.parent_block_hash
178
+ * message_block_hash = parent.body.signed_execution_payload_bid.message.block_hash
179
+ * return PAYLOAD_STATUS_FULL if parent_block_hash == message_block_hash else PAYLOAD_STATUS_EMPTY
180
+ *
181
+ * In lodestar forkchoice, we don't store the full bid, so we compares parent_block_hash in child's bid with executionPayloadBlockHash in parent:
182
+ * - If it matches EMPTY variant, return EMPTY
183
+ * - If it matches FULL variant, return FULL
184
+ * - If no match, throw UNKNOWN_PARENT_BLOCK error
185
+ *
186
+ * For pre-Gloas blocks: always returns FULL
187
+ */
188
+ getParentPayloadStatus(block: ProtoBlock): PayloadStatus {
189
+ // Pre-Gloas blocks have payloads embedded, so parents are always FULL
190
+ const {parentBlockHash} = block;
191
+ if (parentBlockHash === null) {
192
+ return PayloadStatus.FULL;
193
+ }
194
+
195
+ const parentBlock = this.getBlockHexAndBlockHash(block.parentRoot, parentBlockHash);
196
+ if (parentBlock == null) {
197
+ throw new ProtoArrayError({
198
+ code: ProtoArrayErrorCode.UNKNOWN_PARENT_BLOCK,
199
+ parentRoot: block.parentRoot,
200
+ parentHash: parentBlockHash,
201
+ });
202
+ }
203
+
204
+ return parentBlock.payloadStatus;
205
+ }
206
+
207
+ /**
208
+ * Return the parent `ProtoBlock` given its root and block hash.
209
+ */
210
+ getParent(parentRoot: RootHex, parentBlockHash: RootHex | null): ProtoBlock | null {
211
+ // pre-gloas
212
+ if (parentBlockHash === null) {
213
+ const parentIndex = this.indices.get(parentRoot);
214
+ if (parentIndex === undefined) {
215
+ return null;
216
+ }
217
+ if (Array.isArray(parentIndex)) {
218
+ // Gloas block found when pre-gloas expected
219
+ throw new ProtoArrayError({
220
+ code: ProtoArrayErrorCode.UNKNOWN_PARENT_BLOCK,
221
+ parentRoot,
222
+ parentHash: parentBlockHash,
223
+ });
224
+ }
225
+ return this.nodes[parentIndex] ?? null;
226
+ }
227
+
228
+ // post-gloas
229
+ return this.getBlockHexAndBlockHash(parentRoot, parentBlockHash);
230
+ }
231
+
232
+ /**
233
+ * Returns an EMPTY or FULL `ProtoBlock` that has matching block root and block hash
234
+ */
235
+ getBlockHexAndBlockHash(blockRoot: RootHex, blockHash: RootHex): ProtoBlock | null {
236
+ const variantIndices = this.indices.get(blockRoot);
237
+ if (variantIndices === undefined) {
238
+ return null;
239
+ }
240
+
241
+ // Pre-Gloas
242
+ if (!Array.isArray(variantIndices)) {
243
+ const node = this.nodes[variantIndices];
244
+ return node.executionPayloadBlockHash === blockHash ? node : null;
245
+ }
246
+
247
+ // Post-Gloas, check empty and full variants
248
+ const fullNodeIndex = variantIndices[PayloadStatus.FULL];
249
+ if (fullNodeIndex !== undefined) {
250
+ const fullNode = this.nodes[fullNodeIndex];
251
+ if (fullNode && fullNode.executionPayloadBlockHash === blockHash) {
252
+ return fullNode;
253
+ }
254
+ }
255
+
256
+ const emptyNode = this.nodes[variantIndices[PayloadStatus.EMPTY]];
257
+ if (emptyNode && emptyNode.executionPayloadBlockHash === blockHash) {
258
+ return emptyNode;
259
+ }
260
+
261
+ // PENDING is the same to EMPTY so not likely we can return it
262
+ // also it's only specific for fork-choice
263
+
264
+ return null;
265
+ }
266
+
67
267
  /**
68
268
  * Iterate backwards through the array, touching all nodes and their parents and potentially
69
269
  * the best-child of each parent.
@@ -96,11 +296,11 @@ export class ProtoArray {
96
296
  finalizedRoot: RootHex;
97
297
  currentSlot: Slot;
98
298
  }): void {
99
- if (deltas.length !== this.indices.size) {
299
+ if (deltas.length !== this.nodes.length) {
100
300
  throw new ProtoArrayError({
101
301
  code: ProtoArrayErrorCode.INVALID_DELTA_LEN,
102
302
  deltas: deltas.length,
103
- indices: this.indices.size,
303
+ indices: this.nodes.length,
104
304
  });
105
305
  }
106
306
 
@@ -183,7 +383,7 @@ export class ProtoArray {
183
383
  // If the node has a parent, try to update its best-child and best-descendant.
184
384
  const parentIndex = node.parent;
185
385
  if (parentIndex !== undefined) {
186
- this.maybeUpdateBestChildAndDescendant(parentIndex, nodeIndex, currentSlot);
386
+ this.maybeUpdateBestChildAndDescendant(parentIndex, nodeIndex, currentSlot, proposerBoost?.root ?? null);
187
387
  }
188
388
  }
189
389
  // Update the previous proposer boost
@@ -195,9 +395,9 @@ export class ProtoArray {
195
395
  *
196
396
  * It is only sane to supply an undefined parent for the genesis block
197
397
  */
198
- onBlock(block: ProtoBlock, currentSlot: Slot): void {
398
+ onBlock(block: ProtoBlock, currentSlot: Slot, proposerBoostRoot: RootHex | null): void {
199
399
  // If the block is already known, simply ignore it
200
- if (this.indices.has(block.blockRoot)) {
400
+ if (this.hasBlock(block.blockRoot)) {
201
401
  return;
202
402
  }
203
403
  if (block.executionStatus === ExecutionStatus.Invalid) {
@@ -207,28 +407,293 @@ export class ProtoArray {
207
407
  });
208
408
  }
209
409
 
210
- const node: ProtoNode = {
211
- ...block,
212
- parent: this.indices.get(block.parentRoot),
410
+ if (isGloasBlock(block)) {
411
+ // Gloas: Create PENDING + EMPTY nodes with correct parent relationships
412
+ // Parent of new PENDING node = parent block's EMPTY or FULL (inter-block edge)
413
+ // Parent of new EMPTY node = own PENDING node (intra-block edge)
414
+
415
+ // For fork transition: if parent is pre-Gloas, point to parent's FULL
416
+ // Otherwise, determine which parent payload status this block extends
417
+ let parentIndex: number | undefined;
418
+
419
+ // Check if parent exists by getting variants array
420
+ const parentVariants = this.indices.get(block.parentRoot);
421
+ if (parentVariants != null) {
422
+ const anyParentIndex = Array.isArray(parentVariants) ? parentVariants[0] : parentVariants;
423
+ const anyParentNode = this.nodes[anyParentIndex];
424
+
425
+ if (!isGloasBlock(anyParentNode)) {
426
+ // Fork transition: parent is pre-Gloas, so it only has FULL variant at variants[0]
427
+ parentIndex = anyParentIndex;
428
+ } else {
429
+ // Both blocks are Gloas: determine which parent payload status to extend
430
+ const parentPayloadStatus = this.getParentPayloadStatus(block);
431
+ parentIndex = this.getNodeIndexByRootAndStatus(block.parentRoot, parentPayloadStatus);
432
+ }
433
+ }
434
+ // else: parent doesn't exist, parentIndex remains undefined (orphan block)
435
+
436
+ // Create PENDING node
437
+ const pendingNode: ProtoNode = {
438
+ ...block,
439
+ parent: parentIndex, // Points to parent's EMPTY/FULL or FULL (for transition)
440
+ payloadStatus: PayloadStatus.PENDING,
441
+ weight: 0,
442
+ bestChild: undefined,
443
+ bestDescendant: undefined,
444
+ };
445
+
446
+ const pendingIndex = this.nodes.length;
447
+ this.nodes.push(pendingNode);
448
+
449
+ // Create EMPTY variant as a child of PENDING
450
+ const emptyNode: ProtoNode = {
451
+ ...block,
452
+ parent: pendingIndex, // Points to own PENDING
453
+ payloadStatus: PayloadStatus.EMPTY,
454
+ weight: 0,
455
+ bestChild: undefined,
456
+ bestDescendant: undefined,
457
+ };
458
+
459
+ const emptyIndex = this.nodes.length;
460
+ this.nodes.push(emptyNode);
461
+
462
+ // Store both variants in the indices array
463
+ // [PENDING, EMPTY, undefined] - FULL will be added later if payload arrives
464
+ this.indices.set(block.blockRoot, [pendingIndex, emptyIndex]);
465
+
466
+ // Update bestChild pointers
467
+ if (parentIndex !== undefined) {
468
+ this.maybeUpdateBestChildAndDescendant(parentIndex, pendingIndex, currentSlot, proposerBoostRoot);
469
+
470
+ if (pendingNode.executionStatus === ExecutionStatus.Valid) {
471
+ this.propagateValidExecutionStatusByIndex(parentIndex);
472
+ }
473
+ }
474
+
475
+ // Update bestChild for PENDING → EMPTY edge
476
+ this.maybeUpdateBestChildAndDescendant(pendingIndex, emptyIndex, currentSlot, proposerBoostRoot);
477
+
478
+ // Initialize PTC votes for this block (all false initially)
479
+ // Spec: gloas/fork-choice.md#modified-on_block (line 645)
480
+ this.ptcVotes.set(block.blockRoot, BitArray.fromBitLen(PTC_SIZE));
481
+ } else {
482
+ // Pre-Gloas: Only create FULL node (payload embedded in block)
483
+ const node: ProtoNode = {
484
+ ...block,
485
+ parent: this.getNodeIndexByRootAndStatus(block.parentRoot, PayloadStatus.FULL),
486
+ payloadStatus: PayloadStatus.FULL,
487
+ weight: 0,
488
+ bestChild: undefined,
489
+ bestDescendant: undefined,
490
+ };
491
+
492
+ const nodeIndex = this.nodes.length;
493
+ this.nodes.push(node);
494
+
495
+ // Pre-Gloas: store FULL index instead of array
496
+ this.indices.set(block.blockRoot, nodeIndex);
497
+
498
+ // If this node is valid, lets propagate the valid status up the chain
499
+ // and throw error if we counter invalid, as this breaks consensus
500
+ if (node.parent !== undefined) {
501
+ this.maybeUpdateBestChildAndDescendant(node.parent, nodeIndex, currentSlot, proposerBoostRoot);
502
+
503
+ if (node.executionStatus === ExecutionStatus.Valid) {
504
+ this.propagateValidExecutionStatusByIndex(node.parent);
505
+ }
506
+ }
507
+ }
508
+ }
509
+
510
+ /**
511
+ * Called when an execution payload is received for a block (Gloas only)
512
+ * Creates a FULL variant node as a sibling to the existing EMPTY variant
513
+ * Both EMPTY and FULL have parent = own PENDING node
514
+ *
515
+ * Spec: gloas/fork-choice.md (on_execution_payload event)
516
+ */
517
+ onExecutionPayload(
518
+ blockRoot: RootHex,
519
+ currentSlot: Slot,
520
+ executionPayloadBlockHash: RootHex,
521
+ executionPayloadNumber: number,
522
+ executionPayloadStateRoot: RootHex,
523
+ proposerBoostRoot: RootHex | null
524
+ ): void {
525
+ // First check if block exists
526
+ const variants = this.indices.get(blockRoot);
527
+ if (variants == null) {
528
+ // Equivalent to `assert envelope.beacon_block_root in store.block_states`
529
+ throw new ProtoArrayError({
530
+ code: ProtoArrayErrorCode.UNKNOWN_BLOCK,
531
+ root: blockRoot,
532
+ });
533
+ }
534
+
535
+ if (!Array.isArray(variants)) {
536
+ // Pre-gloas block should not be calling this method
537
+ throw new ProtoArrayError({
538
+ code: ProtoArrayErrorCode.PRE_GLOAS_BLOCK,
539
+ root: blockRoot,
540
+ });
541
+ }
542
+
543
+ // Check if FULL already exists for Gloas blocks
544
+ if (variants[PayloadStatus.FULL] !== undefined) {
545
+ return;
546
+ }
547
+
548
+ // Get PENDING node for Gloas blocks
549
+ const pendingIndex = variants[PayloadStatus.PENDING];
550
+ if (pendingIndex === undefined) {
551
+ throw new ProtoArrayError({
552
+ code: ProtoArrayErrorCode.UNKNOWN_BLOCK,
553
+ root: blockRoot,
554
+ });
555
+ }
556
+
557
+ const pendingNode = this.nodes[pendingIndex];
558
+ if (!pendingNode) {
559
+ throw new ProtoArrayError({
560
+ code: ProtoArrayErrorCode.INVALID_NODE_INDEX,
561
+ index: pendingIndex,
562
+ });
563
+ }
564
+
565
+ // Create FULL variant as a child of PENDING (sibling to EMPTY)
566
+ const fullNode: ProtoNode = {
567
+ ...pendingNode,
568
+ parent: pendingIndex, // Points to own PENDING (same as EMPTY)
569
+ payloadStatus: PayloadStatus.FULL,
213
570
  weight: 0,
214
571
  bestChild: undefined,
215
572
  bestDescendant: undefined,
573
+ executionStatus: ExecutionStatus.Valid,
574
+ executionPayloadBlockHash,
575
+ executionPayloadNumber,
576
+ stateRoot: executionPayloadStateRoot,
216
577
  };
217
578
 
218
- const nodeIndex = this.nodes.length;
579
+ const fullIndex = this.nodes.length;
580
+ this.nodes.push(fullNode);
581
+
582
+ // Add FULL variant to the indices array
583
+ variants[PayloadStatus.FULL] = fullIndex;
219
584
 
220
- this.indices.set(node.blockRoot, nodeIndex);
221
- this.nodes.push(node);
585
+ // Update bestChild for PENDING node (may now prefer FULL over EMPTY)
586
+ this.maybeUpdateBestChildAndDescendant(pendingIndex, fullIndex, currentSlot, proposerBoostRoot);
587
+ }
222
588
 
223
- // If this node is valid, lets propagate the valid status up the chain
224
- // and throw error if we counter invalid, as this breaks consensus
225
- if (node.parent !== undefined) {
226
- this.maybeUpdateBestChildAndDescendant(node.parent, nodeIndex, currentSlot);
589
+ /**
590
+ * Update PTC votes for multiple validators attesting to a block
591
+ * Spec: gloas/fork-choice.md#new-on_payload_attestation_message
592
+ *
593
+ * @param blockRoot - The beacon block root being attested
594
+ * @param ptcIndices - Array of PTC committee indices that voted (0..PTC_SIZE-1)
595
+ * @param payloadPresent - Whether the validators attest the payload is present
596
+ */
597
+ notifyPtcMessages(blockRoot: RootHex, ptcIndices: number[], payloadPresent: boolean): void {
598
+ const votes = this.ptcVotes.get(blockRoot);
599
+ if (votes === undefined) {
600
+ // Block not found or not a Gloas block, ignore
601
+ return;
602
+ }
227
603
 
228
- if (node.executionStatus === ExecutionStatus.Valid) {
229
- this.propagateValidExecutionStatusByIndex(node.parent);
604
+ for (const ptcIndex of ptcIndices) {
605
+ if (ptcIndex < 0 || ptcIndex >= PTC_SIZE) {
606
+ throw new Error(`Invalid PTC index: ${ptcIndex}, must be 0..${PTC_SIZE - 1}`);
230
607
  }
608
+
609
+ votes.set(ptcIndex, payloadPresent);
610
+ }
611
+ }
612
+
613
+ /**
614
+ * Check if execution payload for a block is timely
615
+ * Spec: gloas/fork-choice.md#new-is_payload_timely
616
+ *
617
+ * Returns true if:
618
+ * 1. Block has PTC votes tracked
619
+ * 2. Payload is locally available (FULL variant exists in proto array)
620
+ * 3. More than PAYLOAD_TIMELY_THRESHOLD (>50% of PTC) members voted payload_present=true
621
+ *
622
+ * @param blockRoot - The beacon block root to check
623
+ */
624
+ isPayloadTimely(blockRoot: RootHex): boolean {
625
+ const votes = this.ptcVotes.get(blockRoot);
626
+ if (votes === undefined) {
627
+ // Block not found or not a Gloas block
628
+ return false;
629
+ }
630
+
631
+ // If payload is not locally available, it's not timely
632
+ // In our implementation, payload is locally available if proto array has FULL variant of the block
633
+ const fullNodeIndex = this.getNodeIndexByRootAndStatus(blockRoot, PayloadStatus.FULL);
634
+ if (fullNodeIndex === undefined) {
635
+ return false;
636
+ }
637
+
638
+ // Count votes for payload_present=true
639
+ const yesVotes = bitCount(votes.uint8Array);
640
+ return yesVotes > PAYLOAD_TIMELY_THRESHOLD;
641
+ }
642
+
643
+ /**
644
+ * Check if parent node is FULL
645
+ * Spec: gloas/fork-choice.md#new-is_parent_node_full
646
+ *
647
+ * Returns true if the parent payload status (determined by block.parentBlockHash) is FULL
648
+ */
649
+ isParentNodeFull(block: ProtoBlock): boolean {
650
+ return this.getParentPayloadStatus(block) === PayloadStatus.FULL;
651
+ }
652
+
653
+ /**
654
+ * Determine if we should extend the payload (prefer FULL over EMPTY)
655
+ * Spec: gloas/fork-choice.md#new-should_extend_payload
656
+ *
657
+ * Returns true if:
658
+ * 1. Payload is timely, OR
659
+ * 2. No proposer boost root (empty/zero hash), OR
660
+ * 3. Proposer boost root's parent is not this block, OR
661
+ * 4. Proposer boost root extends FULL parent
662
+ *
663
+ * @param blockRoot - The block root to check
664
+ * @param proposerBoostRoot - Current proposer boost root (from ForkChoice)
665
+ */
666
+ shouldExtendPayload(blockRoot: RootHex, proposerBoostRoot: RootHex | null): boolean {
667
+ // Condition 1: Payload is timely
668
+ if (this.isPayloadTimely(blockRoot)) {
669
+ return true;
670
+ }
671
+
672
+ // Condition 2: No proposer boost root
673
+ if (proposerBoostRoot === null || proposerBoostRoot === HEX_ZERO_HASH) {
674
+ return true;
675
+ }
676
+
677
+ // Get proposer boost block
678
+ // We don't care about variant here, just need proposer boost block info
679
+ const defaultStatus = this.getDefaultVariant(proposerBoostRoot);
680
+ const proposerBoostBlock = defaultStatus !== undefined ? this.getNode(proposerBoostRoot, defaultStatus) : undefined;
681
+ if (!proposerBoostBlock) {
682
+ // Proposer boost block not found, default to extending payload
683
+ return true;
684
+ }
685
+
686
+ // Condition 3: Proposer boost root's parent is not this block
687
+ if (proposerBoostBlock.parentRoot !== blockRoot) {
688
+ return true;
231
689
  }
690
+
691
+ // Condition 4: Proposer boost root extends FULL parent
692
+ if (this.isParentNodeFull(proposerBoostBlock)) {
693
+ return true;
694
+ }
695
+
696
+ return false;
232
697
  }
233
698
 
234
699
  /**
@@ -236,6 +701,7 @@ export class ProtoArray {
236
701
  * if invalidate till hash provided. If consensus fails, this will invalidate entire
237
702
  * forkChoice which will throw on any call to findHead
238
703
  */
704
+ // TODO GLOAS: Review usage of this post-gloas
239
705
  validateLatestHash(execResponse: LVHExecResponse, currentSlot: Slot): void {
240
706
  // Look reverse because its highly likely node with latestValidExecHash is towards the
241
707
  // the leaves of the forkchoice
@@ -279,7 +745,12 @@ export class ProtoArray {
279
745
  // if its in fcU.
280
746
  //
281
747
  const {invalidateFromParentBlockRoot, latestValidExecHash} = execResponse;
282
- const invalidateFromParentIndex = this.indices.get(invalidateFromParentBlockRoot);
748
+ // TODO GLOAS: verify if getting default variant is correct here
749
+ const defaultStatus = this.getDefaultVariant(invalidateFromParentBlockRoot);
750
+ const invalidateFromParentIndex =
751
+ defaultStatus !== undefined
752
+ ? this.getNodeIndexByRootAndStatus(invalidateFromParentBlockRoot, defaultStatus)
753
+ : undefined;
283
754
  if (invalidateFromParentIndex === undefined) {
284
755
  throw Error(`Unable to find invalidateFromParentBlockRoot=${invalidateFromParentBlockRoot} in forkChoice`);
285
756
  }
@@ -317,6 +788,12 @@ export class ProtoArray {
317
788
  if (node.executionStatus === ExecutionStatus.PreMerge || node.executionStatus === ExecutionStatus.Valid) {
318
789
  break;
319
790
  }
791
+ // If PayloadSeparated, that means the node is either PENDING or EMPTY, there could be
792
+ // some ancestor still has syncing status.
793
+ if (node.executionStatus === ExecutionStatus.PayloadSeparated) {
794
+ nodeIndex = node.parent;
795
+ continue;
796
+ }
320
797
  this.validateNodeByIndex(nodeIndex);
321
798
  nodeIndex = node.parent;
322
799
  }
@@ -438,10 +915,46 @@ export class ProtoArray {
438
915
  return validNode;
439
916
  }
440
917
 
918
+ /**
919
+ * Get payload status tiebreaker for fork choice comparison
920
+ * Spec: gloas/fork-choice.md#new-get_payload_status_tiebreaker
921
+ *
922
+ * For PENDING nodes: always returns 0
923
+ * For EMPTY/FULL variants from slot n-1: implements tiebreaker logic based on should_extend_payload
924
+ * For older blocks: returns node.payloadStatus
925
+ *
926
+ * 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.
927
+ */
928
+ private getPayloadStatusTiebreaker(node: ProtoNode, currentSlot: Slot, proposerBoostRoot: RootHex | null): number {
929
+ // PENDING nodes always return PENDING (no tiebreaker needed)
930
+ // PENDING=0, EMPTY=1, FULL=2
931
+ if (node.payloadStatus === PayloadStatus.PENDING) {
932
+ return node.payloadStatus;
933
+ }
934
+
935
+ // For Gloas: check if from previous slot
936
+ if (node.slot + 1 !== currentSlot) {
937
+ return node.payloadStatus;
938
+ }
939
+
940
+ // For previous slot blocks in Gloas, decide between FULL and EMPTY
941
+ // based on should_extend_payload
942
+ if (node.payloadStatus === PayloadStatus.EMPTY) {
943
+ return PayloadStatus.EMPTY;
944
+ }
945
+ // FULL - check should_extend_payload
946
+ const shouldExtend = this.shouldExtendPayload(node.blockRoot, proposerBoostRoot);
947
+ return shouldExtend ? PayloadStatus.FULL : PayloadStatus.PENDING;
948
+ }
949
+
441
950
  /**
442
951
  * Follows the best-descendant links to find the best-block (i.e., head-block).
952
+ *
953
+ * Returns the ProtoNode representing the head.
954
+ * For pre-Gloas forks, only FULL variants exist (payload embedded).
955
+ * For Gloas, may return PENDING/EMPTY/FULL variants.
443
956
  */
444
- findHead(justifiedRoot: RootHex, currentSlot: Slot): RootHex {
957
+ findHead(justifiedRoot: RootHex, currentSlot: Slot): ProtoNode {
445
958
  if (this.lvhError) {
446
959
  throw new ProtoArrayError({
447
960
  code: ProtoArrayErrorCode.INVALID_LVH_EXECUTION_RESPONSE,
@@ -449,7 +962,10 @@ export class ProtoArray {
449
962
  });
450
963
  }
451
964
 
452
- const justifiedIndex = this.indices.get(justifiedRoot);
965
+ // Get canonical node: FULL for pre-Gloas, PENDING for Gloas
966
+ const defaultStatus = this.getDefaultVariant(justifiedRoot);
967
+ const justifiedIndex =
968
+ defaultStatus !== undefined ? this.getNodeIndexByRootAndStatus(justifiedRoot, defaultStatus) : undefined;
453
969
  if (justifiedIndex === undefined) {
454
970
  throw new ProtoArrayError({
455
971
  code: ProtoArrayErrorCode.JUSTIFIED_NODE_UNKNOWN,
@@ -501,7 +1017,7 @@ export class ProtoArray {
501
1017
  });
502
1018
  }
503
1019
 
504
- return bestNode.blockRoot;
1020
+ return bestNode;
505
1021
  }
506
1022
 
507
1023
  /**
@@ -520,26 +1036,40 @@ export class ProtoArray {
520
1036
  * - There is some internal error relating to invalid indices inside `this`.
521
1037
  */
522
1038
  maybePrune(finalizedRoot: RootHex): ProtoBlock[] {
523
- const finalizedIndex = this.indices.get(finalizedRoot);
524
- if (finalizedIndex === undefined) {
1039
+ const variants = this.indices.get(finalizedRoot);
1040
+ if (variants == null) {
525
1041
  throw new ProtoArrayError({
526
1042
  code: ProtoArrayErrorCode.FINALIZED_NODE_UNKNOWN,
527
1043
  root: finalizedRoot,
528
1044
  });
529
1045
  }
530
1046
 
1047
+ // Find the minimum index among all variants to ensure we don't prune too much
1048
+ const finalizedIndex = Array.isArray(variants)
1049
+ ? Math.min(...variants.filter((idx) => idx !== undefined))
1050
+ : variants;
1051
+
531
1052
  if (finalizedIndex < this.pruneThreshold) {
532
1053
  // Pruning at small numbers incurs more cost than benefit
533
1054
  return [];
534
1055
  }
535
1056
 
536
- // Remove the this.indices key/values for all the to-be-deleted nodes
537
- for (let nodeIndex = 0; nodeIndex < finalizedIndex; nodeIndex++) {
538
- const node = this.nodes[nodeIndex];
1057
+ // Collect all block roots that will be pruned
1058
+ const prunedRoots = new Set<RootHex>();
1059
+ for (let i = 0; i < finalizedIndex; i++) {
1060
+ const node = this.nodes[i];
539
1061
  if (node === undefined) {
540
- throw new ProtoArrayError({code: ProtoArrayErrorCode.INVALID_NODE_INDEX, index: nodeIndex});
1062
+ throw new ProtoArrayError({code: ProtoArrayErrorCode.INVALID_NODE_INDEX, index: i});
541
1063
  }
542
- this.indices.delete(node.blockRoot);
1064
+ prunedRoots.add(node.blockRoot);
1065
+ }
1066
+
1067
+ // Remove indices for pruned blocks and PTC votes
1068
+ for (const root of prunedRoots) {
1069
+ this.indices.delete(root);
1070
+ // Prune PTC votes for this block to prevent memory leak
1071
+ // Spec: gloas/fork-choice.md (implicit - finalized blocks don't need PTC votes)
1072
+ this.ptcVotes.delete(root);
543
1073
  }
544
1074
 
545
1075
  // Store nodes prior to finalization
@@ -547,15 +1077,35 @@ export class ProtoArray {
547
1077
  // Drop all the nodes prior to finalization
548
1078
  this.nodes = this.nodes.slice(finalizedIndex);
549
1079
 
550
- // Adjust the indices map
551
- for (const [key, value] of this.indices.entries()) {
552
- if (value < finalizedIndex) {
553
- throw new ProtoArrayError({
554
- code: ProtoArrayErrorCode.INDEX_OVERFLOW,
555
- value: "indices",
556
- });
1080
+ // Adjust the indices map - subtract finalizedIndex from all node indices
1081
+ for (const [root, variantIndices] of this.indices.entries()) {
1082
+ // Pre-Gloas: single index
1083
+ if (!Array.isArray(variantIndices)) {
1084
+ if (variantIndices < finalizedIndex) {
1085
+ throw new ProtoArrayError({
1086
+ code: ProtoArrayErrorCode.INDEX_OVERFLOW,
1087
+ value: "indices",
1088
+ });
1089
+ }
1090
+ this.indices.set(root, variantIndices - finalizedIndex);
1091
+ continue;
557
1092
  }
558
- this.indices.set(key, value - finalizedIndex);
1093
+
1094
+ // Post-Gloas: array of variant indices
1095
+ const adjustedVariants = variantIndices.map((variantIndex) => {
1096
+ if (variantIndex === undefined) {
1097
+ return undefined;
1098
+ }
1099
+
1100
+ if (variantIndex < finalizedIndex) {
1101
+ throw new ProtoArrayError({
1102
+ code: ProtoArrayErrorCode.INDEX_OVERFLOW,
1103
+ value: "indices",
1104
+ });
1105
+ }
1106
+ return variantIndex - finalizedIndex;
1107
+ });
1108
+ this.indices.set(root, adjustedVariants as GloasVariantIndices);
559
1109
  }
560
1110
 
561
1111
  // Iterate through all the existing nodes and adjust their indices to match the new layout of this.nodes
@@ -604,7 +1154,13 @@ export class ProtoArray {
604
1154
  * - The child is not the best child but becomes the best child.
605
1155
  * - The child is not the best child and does not become the best child.
606
1156
  */
607
- maybeUpdateBestChildAndDescendant(parentIndex: number, childIndex: number, currentSlot: Slot): void {
1157
+
1158
+ maybeUpdateBestChildAndDescendant(
1159
+ parentIndex: number,
1160
+ childIndex: number,
1161
+ currentSlot: Slot,
1162
+ proposerBoostRoot: RootHex | null
1163
+ ): void {
608
1164
  const childNode = this.nodes[childIndex];
609
1165
  if (childNode === undefined) {
610
1166
  throw new ProtoArrayError({
@@ -634,54 +1190,90 @@ export class ProtoArray {
634
1190
 
635
1191
  let newChildAndDescendant: ChildAndDescendant;
636
1192
  const bestChildIndex = parentNode.bestChild;
637
- if (bestChildIndex !== undefined) {
638
- if (bestChildIndex === childIndex && !childLeadsToViableHead) {
639
- // the child is already the best-child of the parent but its not viable for the head
640
- // so remove it
641
- newChildAndDescendant = changeToNull;
642
- } else if (bestChildIndex === childIndex) {
643
- // the child is the best-child already
644
- // set it again to ensure that the best-descendent of the parent is updated
645
- newChildAndDescendant = changeToChild;
646
- } else {
647
- const bestChildNode = this.nodes[bestChildIndex];
648
- if (bestChildNode === undefined) {
649
- throw new ProtoArrayError({
650
- code: ProtoArrayErrorCode.INVALID_BEST_CHILD_INDEX,
651
- index: bestChildIndex,
652
- });
653
- }
1193
+ // biome-ignore lint/suspicious/noConfusingLabels: labeled block used for early exit from complex decision tree
1194
+ outer: {
1195
+ if (bestChildIndex !== undefined) {
1196
+ if (bestChildIndex === childIndex && !childLeadsToViableHead) {
1197
+ // the child is already the best-child of the parent but its not viable for the head
1198
+ // so remove it
1199
+ newChildAndDescendant = changeToNull;
1200
+ } else if (bestChildIndex === childIndex) {
1201
+ // the child is the best-child already
1202
+ // set it again to ensure that the best-descendent of the parent is updated
1203
+ newChildAndDescendant = changeToChild;
1204
+ } else {
1205
+ const bestChildNode = this.nodes[bestChildIndex];
1206
+ if (bestChildNode === undefined) {
1207
+ throw new ProtoArrayError({
1208
+ code: ProtoArrayErrorCode.INVALID_BEST_CHILD_INDEX,
1209
+ index: bestChildIndex,
1210
+ });
1211
+ }
654
1212
 
655
- const bestChildLeadsToViableHead = this.nodeLeadsToViableHead(bestChildNode, currentSlot);
1213
+ const bestChildLeadsToViableHead = this.nodeLeadsToViableHead(bestChildNode, currentSlot);
656
1214
 
657
- if (childLeadsToViableHead && !bestChildLeadsToViableHead) {
658
- // the child leads to a viable head, but the current best-child doesn't
659
- newChildAndDescendant = changeToChild;
660
- } else if (!childLeadsToViableHead && bestChildLeadsToViableHead) {
661
- // the best child leads to a viable head but the child doesn't
662
- newChildAndDescendant = noChange;
663
- } else if (childNode.weight === bestChildNode.weight) {
664
- // tie-breaker of equal weights by root
665
- if (childNode.blockRoot >= bestChildNode.blockRoot) {
1215
+ if (childLeadsToViableHead && !bestChildLeadsToViableHead) {
1216
+ // the child leads to a viable head, but the current best-child doesn't
666
1217
  newChildAndDescendant = changeToChild;
667
- } else {
1218
+ break outer;
1219
+ }
1220
+ if (!childLeadsToViableHead && bestChildLeadsToViableHead) {
1221
+ // the best child leads to a viable head but the child doesn't
668
1222
  newChildAndDescendant = noChange;
1223
+ break outer;
669
1224
  }
670
- } else {
671
- // choose the winner by weight
672
- if (childNode.weight >= bestChildNode.weight) {
1225
+ // Both nodes lead to viable heads (or both don't), need to pick winner
1226
+
1227
+ // Pre-fulu we pick whichever has higher weight, tie-breaker by root
1228
+ // Post-fulu we pick whichever has higher weight, then tie-breaker by root, then tie-breaker by `getPayloadStatusTiebreaker`
1229
+ // Gloas: nodes from previous slot (n-1) with EMPTY/FULL variant have weight hardcoded to 0.
1230
+ // https://github.com/ethereum/consensus-specs/blob/69a2582d5d62c914b24894bdb65f4bd5d4e49ae4/specs/gloas/fork-choice.md?plain=1#L442
1231
+ const childEffectiveWeight =
1232
+ !isGloasBlock(childNode) ||
1233
+ childNode.payloadStatus === PayloadStatus.PENDING ||
1234
+ childNode.slot + 1 !== currentSlot
1235
+ ? childNode.weight
1236
+ : 0;
1237
+ const bestChildEffectiveWeight =
1238
+ !isGloasBlock(bestChildNode) ||
1239
+ bestChildNode.payloadStatus === PayloadStatus.PENDING ||
1240
+ bestChildNode.slot + 1 !== currentSlot
1241
+ ? bestChildNode.weight
1242
+ : 0;
1243
+
1244
+ if (childEffectiveWeight !== bestChildEffectiveWeight) {
1245
+ // Different effective weights, choose the winner by weight
1246
+ newChildAndDescendant = childEffectiveWeight >= bestChildEffectiveWeight ? changeToChild : noChange;
1247
+ break outer;
1248
+ }
1249
+
1250
+ if (childNode.blockRoot !== bestChildNode.blockRoot) {
1251
+ // Different blocks, tie-breaker by root
1252
+ newChildAndDescendant = childNode.blockRoot >= bestChildNode.blockRoot ? changeToChild : noChange;
1253
+ break outer;
1254
+ }
1255
+
1256
+ // Same effective weight and same root — Gloas EMPTY vs FULL from n-1, tie-breaker by payload status
1257
+ // Note: pre-Gloas, each child node of a block has a unique root, so this point should not be reached
1258
+ const childTiebreaker = this.getPayloadStatusTiebreaker(childNode, currentSlot, proposerBoostRoot);
1259
+ const bestChildTiebreaker = this.getPayloadStatusTiebreaker(bestChildNode, currentSlot, proposerBoostRoot);
1260
+
1261
+ if (childTiebreaker > bestChildTiebreaker) {
673
1262
  newChildAndDescendant = changeToChild;
1263
+ } else if (childTiebreaker < bestChildTiebreaker) {
1264
+ newChildAndDescendant = noChange;
674
1265
  } else {
1266
+ // Equal in all aspects, noChange
675
1267
  newChildAndDescendant = noChange;
676
1268
  }
677
1269
  }
1270
+ } else if (childLeadsToViableHead) {
1271
+ // There is no current best-child and the child is viable.
1272
+ newChildAndDescendant = changeToChild;
1273
+ } else {
1274
+ // There is no current best-child but the child is not viable.
1275
+ newChildAndDescendant = noChange;
678
1276
  }
679
- } else if (childLeadsToViableHead) {
680
- // There is no current best-child and the child is viable.
681
- newChildAndDescendant = changeToChild;
682
- } else {
683
- // There is no current best-child but the child is not viable.
684
- newChildAndDescendant = noChange;
685
1277
  }
686
1278
 
687
1279
  parentNode.bestChild = newChildAndDescendant[0];
@@ -761,13 +1353,14 @@ export class ProtoArray {
761
1353
  }
762
1354
 
763
1355
  const finalizedSlot = computeStartSlotAtEpoch(this.finalizedEpoch);
764
- return this.finalizedEpoch === 0 || this.finalizedRoot === this.getAncestorOrNull(node.blockRoot, finalizedSlot);
1356
+ const ancestorNode = this.getAncestorOrNull(node.blockRoot, finalizedSlot);
1357
+ return this.finalizedEpoch === 0 || (ancestorNode !== null && this.finalizedRoot === ancestorNode.blockRoot);
765
1358
  }
766
1359
 
767
1360
  /**
768
1361
  * Same to getAncestor but it may return null instead of throwing error
769
1362
  */
770
- getAncestorOrNull(blockRoot: RootHex, ancestorSlot: Slot): RootHex | null {
1363
+ getAncestorOrNull(blockRoot: RootHex, ancestorSlot: Slot): ProtoNode | null {
771
1364
  try {
772
1365
  return this.getAncestor(blockRoot, ancestorSlot);
773
1366
  } catch (_) {
@@ -776,49 +1369,116 @@ export class ProtoArray {
776
1369
  }
777
1370
 
778
1371
  /**
779
- * Returns the block root of an ancestor of `blockRoot` at the given `slot`.
1372
+ * Returns the node identifier of an ancestor of `blockRoot` at the given `slot`.
780
1373
  * (Note: `slot` refers to the block that is *returned*, not the one that is supplied.)
781
1374
  *
782
1375
  * NOTE: May be expensive: potentially walks through the entire fork of head to finalized block
783
1376
  *
784
1377
  * ### Specification
785
1378
  *
786
- * Equivalent to:
1379
+ * Modified for Gloas to return node identifier instead of just root:
1380
+ * https://github.com/ethereum/consensus-specs/blob/v1.7.0-alpha.1/specs/gloas/fork-choice.md#modified-get_ancestor
787
1381
  *
788
- * https://github.com/ethereum/consensus-specs/blob/v1.1.10/specs/phase0/fork-choice.md#get_ancestor
1382
+ * Pre-Gloas: Returns (root, PAYLOAD_STATUS_FULL)
1383
+ * Gloas: Returns (root, payloadStatus) based on actual node state
789
1384
  */
790
- getAncestor(blockRoot: RootHex, ancestorSlot: Slot): RootHex {
791
- const block = this.getBlock(blockRoot);
792
- if (!block) {
1385
+ getAncestor(blockRoot: RootHex, ancestorSlot: Slot): ProtoNode {
1386
+ // Get any variant to check the block (use variants[0])
1387
+ const variantOrArr = this.indices.get(blockRoot);
1388
+ if (variantOrArr == null) {
793
1389
  throw new ForkChoiceError({
794
1390
  code: ForkChoiceErrorCode.MISSING_PROTO_ARRAY_BLOCK,
795
1391
  root: blockRoot,
796
1392
  });
797
1393
  }
798
1394
 
799
- if (block.slot > ancestorSlot) {
800
- // Search for a slot that is lte the target slot.
801
- // We check for lower slots to account for skip slots.
802
- for (const node of this.iterateAncestorNodes(blockRoot)) {
803
- if (node.slot <= ancestorSlot) {
804
- return node.blockRoot;
805
- }
1395
+ const blockIndex = Array.isArray(variantOrArr) ? variantOrArr[0] : variantOrArr;
1396
+ const block = this.nodes[blockIndex];
1397
+
1398
+ // If block is at or before queried slot, return PENDING variant (or FULL for pre-Gloas)
1399
+ if (block.slot <= ancestorSlot) {
1400
+ // For pre-Gloas: only FULL exists at variants[0]
1401
+ // For Gloas: PENDING is at variants[0]
1402
+ return block;
1403
+ }
1404
+
1405
+ // Walk backwards through beacon blocks to find ancestor
1406
+ // Start with the parent of the current block
1407
+ let currentBlock = block;
1408
+ const parentVariants = this.indices.get(currentBlock.parentRoot);
1409
+ if (parentVariants == null) {
1410
+ throw new ForkChoiceError({
1411
+ code: ForkChoiceErrorCode.UNKNOWN_ANCESTOR,
1412
+ descendantRoot: blockRoot,
1413
+ ancestorSlot,
1414
+ });
1415
+ }
1416
+
1417
+ let parentIndex = Array.isArray(parentVariants) ? parentVariants[0] : parentVariants;
1418
+ let parentBlock = this.nodes[parentIndex];
1419
+
1420
+ // Walk backwards while parent.slot > ancestorSlot
1421
+ while (parentBlock.slot > ancestorSlot) {
1422
+ currentBlock = parentBlock;
1423
+
1424
+ const nextParentVariants = this.indices.get(currentBlock.parentRoot);
1425
+ if (nextParentVariants == null) {
1426
+ throw new ForkChoiceError({
1427
+ code: ForkChoiceErrorCode.UNKNOWN_ANCESTOR,
1428
+ descendantRoot: blockRoot,
1429
+ ancestorSlot,
1430
+ });
806
1431
  }
1432
+
1433
+ parentIndex = Array.isArray(nextParentVariants) ? nextParentVariants[0] : nextParentVariants;
1434
+ parentBlock = this.nodes[parentIndex];
1435
+ }
1436
+
1437
+ // Now parentBlock.slot <= ancestorSlot
1438
+ // Return the parent with the correct payload status based on currentBlock
1439
+ if (!isGloasBlock(currentBlock)) {
1440
+ // Pre-Gloas: return FULL variant (only one that exists)
1441
+ return parentBlock;
1442
+ }
1443
+
1444
+ // Gloas: determine which parent variant (EMPTY or FULL) based on parent_block_hash
1445
+ const parentPayloadStatus = this.getParentPayloadStatus(currentBlock);
1446
+ const parentVariantIndex = this.getNodeIndexByRootAndStatus(currentBlock.parentRoot, parentPayloadStatus);
1447
+
1448
+ if (parentVariantIndex === undefined) {
807
1449
  throw new ForkChoiceError({
808
1450
  code: ForkChoiceErrorCode.UNKNOWN_ANCESTOR,
809
1451
  descendantRoot: blockRoot,
810
1452
  ancestorSlot,
811
1453
  });
812
1454
  }
813
- // Root is older or equal than queried slot, thus a skip slot. Return most recent root prior to slot.
814
- return blockRoot;
1455
+
1456
+ return this.nodes[parentVariantIndex];
1457
+ }
1458
+
1459
+ /**
1460
+ * Get the parent node index for traversal
1461
+ * For Gloas blocks: returns the correct EMPTY/FULL variant based on parent payload status
1462
+ * For pre-Gloas blocks: returns the simple parent index
1463
+ * Returns undefined if parent doesn't exist or can't be found
1464
+ */
1465
+ private getParentNodeIndex(node: ProtoNode): number | undefined {
1466
+ if (isGloasBlock(node)) {
1467
+ // Use getParentPayloadStatus for Gloas blocks to get correct EMPTY/FULL variant
1468
+ const parentPayloadStatus = this.getParentPayloadStatus(node);
1469
+ return this.getNodeIndexByRootAndStatus(node.parentRoot, parentPayloadStatus);
1470
+ }
1471
+ // Simple parent traversal for pre-Gloas blocks (includes fork transition)
1472
+ return node.parent;
815
1473
  }
816
1474
 
817
1475
  /**
818
1476
  * Iterate from a block root backwards over nodes
1477
+ * For Gloas blocks: returns EMPTY/FULL variants (not PENDING) based on parent payload status
1478
+ * For pre-Gloas blocks: returns FULL variants
819
1479
  */
820
- *iterateAncestorNodes(blockRoot: RootHex): IterableIterator<ProtoNode> {
821
- const startIndex = this.indices.get(blockRoot);
1480
+ *iterateAncestorNodes(blockRoot: RootHex, payloadStatus: PayloadStatus): IterableIterator<ProtoNode> {
1481
+ const startIndex = this.getNodeIndexByRootAndStatus(blockRoot, payloadStatus);
822
1482
  if (startIndex === undefined) {
823
1483
  return;
824
1484
  }
@@ -835,20 +1495,30 @@ export class ProtoArray {
835
1495
  }
836
1496
 
837
1497
  /**
838
- * Iterate from a block root backwards over nodes
1498
+ * Iterate from a node backwards over ancestor nodes
1499
+ * For Gloas blocks: returns EMPTY/FULL variants (not PENDING) based on parent payload status
1500
+ * For pre-Gloas blocks: returns FULL variants
1501
+ * Handles fork transition from Gloas to pre-Gloas blocks
839
1502
  */
840
1503
  *iterateAncestorNodesFromNode(node: ProtoNode): IterableIterator<ProtoNode> {
841
1504
  while (node.parent !== undefined) {
842
- node = this.getNodeFromIndex(node.parent);
1505
+ const parentIndex = this.getParentNodeIndex(node);
1506
+ if (parentIndex === undefined) {
1507
+ break;
1508
+ }
1509
+
1510
+ node = this.nodes[parentIndex];
843
1511
  yield node;
844
1512
  }
845
1513
  }
846
1514
 
847
1515
  /**
848
1516
  * Get all nodes from a block root backwards
1517
+ * For Gloas blocks: returns EMPTY/FULL variants (not PENDING) based on parent payload status
1518
+ * For pre-Gloas blocks: returns FULL variants
849
1519
  */
850
- getAllAncestorNodes(blockRoot: RootHex): ProtoNode[] {
851
- const startIndex = this.indices.get(blockRoot);
1520
+ getAllAncestorNodes(blockRoot: RootHex, payloadStatus: PayloadStatus): ProtoNode[] {
1521
+ const startIndex = this.getNodeIndexByRootAndStatus(blockRoot, payloadStatus);
852
1522
  if (startIndex === undefined) {
853
1523
  return [];
854
1524
  }
@@ -861,10 +1531,20 @@ export class ProtoArray {
861
1531
  });
862
1532
  }
863
1533
 
864
- const nodes = [node];
1534
+ // Exclude PENDING variant from returned ancestors.
1535
+ const nodes: ProtoNode[] = [];
1536
+
1537
+ if (node.payloadStatus !== PayloadStatus.PENDING) {
1538
+ nodes.push(node);
1539
+ }
865
1540
 
866
1541
  while (node.parent !== undefined) {
867
- node = this.getNodeFromIndex(node.parent);
1542
+ const parentIndex = this.getParentNodeIndex(node);
1543
+ if (parentIndex === undefined) {
1544
+ break;
1545
+ }
1546
+
1547
+ node = this.nodes[parentIndex];
868
1548
  nodes.push(node);
869
1549
  }
870
1550
 
@@ -875,9 +1555,12 @@ export class ProtoArray {
875
1555
  * The opposite of iterateNodes.
876
1556
  * iterateNodes is to find ancestor nodes of a blockRoot.
877
1557
  * this is to find non-ancestor nodes of a blockRoot.
1558
+ *
1559
+ * For Gloas blocks: returns EMPTY/FULL variants (not PENDING) based on parent payload status
1560
+ * For pre-Gloas blocks: returns FULL variants
878
1561
  */
879
- getAllNonAncestorNodes(blockRoot: RootHex): ProtoNode[] {
880
- const startIndex = this.indices.get(blockRoot);
1562
+ getAllNonAncestorNodes(blockRoot: RootHex, payloadStatus: PayloadStatus): ProtoNode[] {
1563
+ const startIndex = this.getNodeIndexByRootAndStatus(blockRoot, payloadStatus);
881
1564
  if (startIndex === undefined) {
882
1565
  return [];
883
1566
  }
@@ -889,24 +1572,39 @@ export class ProtoArray {
889
1572
  index: startIndex,
890
1573
  });
891
1574
  }
1575
+
1576
+ // For both Gloas and pre-Gloas blocks
892
1577
  const result: ProtoNode[] = [];
893
1578
  let nodeIndex = startIndex;
894
1579
  while (node.parent !== undefined) {
895
- const parentIndex = node.parent;
896
- node = this.getNodeFromIndex(parentIndex);
897
- // nodes between nodeIndex and parentIndex means non-ancestor nodes
898
- result.push(...this.getNodesBetween(nodeIndex, parentIndex));
1580
+ const parentIndex = this.getParentNodeIndex(node);
1581
+ if (parentIndex === undefined) {
1582
+ break;
1583
+ }
1584
+
1585
+ node = this.nodes[parentIndex];
1586
+ // Collect non-ancestor nodes between current and parent
1587
+ // Filter to exclude PENDING nodes (FULL variant pre-gloas, EMPTY or FULL variant post-gloas)
1588
+ result.push(
1589
+ ...this.getNodesBetween(nodeIndex, parentIndex).filter((n) => n.payloadStatus !== PayloadStatus.PENDING)
1590
+ );
899
1591
  nodeIndex = parentIndex;
900
1592
  }
901
- result.push(...this.getNodesBetween(nodeIndex, 0));
1593
+ // Collect remaining nodes from nodeIndex to beginning
1594
+ result.push(...this.getNodesBetween(nodeIndex, 0).filter((n) => n.payloadStatus !== PayloadStatus.PENDING));
902
1595
  return result;
903
1596
  }
904
1597
 
905
1598
  /**
906
1599
  * Returns both ancestor and non-ancestor nodes in a single traversal.
1600
+ * For Gloas blocks: returns EMPTY/FULL variants (not PENDING) based on parent payload status
1601
+ * For pre-Gloas blocks: returns FULL variants
907
1602
  */
908
- getAllAncestorAndNonAncestorNodes(blockRoot: RootHex): {ancestors: ProtoNode[]; nonAncestors: ProtoNode[]} {
909
- const startIndex = this.indices.get(blockRoot);
1603
+ getAllAncestorAndNonAncestorNodes(
1604
+ blockRoot: RootHex,
1605
+ payloadStatus: PayloadStatus
1606
+ ): {ancestors: ProtoNode[]; nonAncestors: ProtoNode[]} {
1607
+ const startIndex = this.getNodeIndexByRootAndStatus(blockRoot, payloadStatus);
910
1608
  if (startIndex === undefined) {
911
1609
  return {ancestors: [], nonAncestors: []};
912
1610
  }
@@ -922,39 +1620,78 @@ export class ProtoArray {
922
1620
  const ancestors: ProtoNode[] = [];
923
1621
  const nonAncestors: ProtoNode[] = [];
924
1622
 
1623
+ // Include starting node if it's not PENDING (i.e., pre-Gloas or EMPTY/FULL variant post-Gloas)
1624
+ if (node.payloadStatus !== PayloadStatus.PENDING) {
1625
+ ancestors.push(node);
1626
+ }
1627
+
925
1628
  let nodeIndex = startIndex;
926
1629
  while (node.parent !== undefined) {
927
- ancestors.push(node);
1630
+ const parentIndex = this.getParentNodeIndex(node);
1631
+ if (parentIndex === undefined) {
1632
+ break;
1633
+ }
928
1634
 
929
- const parentIndex = node.parent;
930
- node = this.getNodeFromIndex(parentIndex);
1635
+ node = this.nodes[parentIndex];
1636
+ ancestors.push(node);
931
1637
 
932
- // Nodes between nodeIndex and parentIndex are non-ancestor nodes
933
- nonAncestors.push(...this.getNodesBetween(nodeIndex, parentIndex));
1638
+ // Collect non-ancestor nodes between current and parent
1639
+ // Filter to exclude PENDING nodes (include all FULL/EMPTY for both pre-Gloas and Gloas)
1640
+ nonAncestors.push(
1641
+ ...this.getNodesBetween(nodeIndex, parentIndex).filter((n) => n.payloadStatus !== PayloadStatus.PENDING)
1642
+ );
934
1643
  nodeIndex = parentIndex;
935
1644
  }
936
1645
 
937
- ancestors.push(node);
938
- nonAncestors.push(...this.getNodesBetween(nodeIndex, 0));
1646
+ // Collect remaining non-ancestor nodes from nodeIndex to beginning
1647
+ nonAncestors.push(...this.getNodesBetween(nodeIndex, 0).filter((n) => n.payloadStatus !== PayloadStatus.PENDING));
939
1648
 
940
1649
  return {ancestors, nonAncestors};
941
1650
  }
942
1651
 
1652
+ /**
1653
+ * Check if a block exists in the proto array
1654
+ * Uses default variant (PENDING for Gloas, FULL for pre-Gloas)
1655
+ */
943
1656
  hasBlock(blockRoot: RootHex): boolean {
944
- return this.indices.has(blockRoot);
1657
+ const defaultVariant = this.getDefaultVariant(blockRoot);
1658
+ if (defaultVariant === undefined) {
1659
+ return false;
1660
+ }
1661
+ const index = this.getNodeIndexByRootAndStatus(blockRoot, defaultVariant);
1662
+ return index !== undefined;
945
1663
  }
946
1664
 
947
- getNode(blockRoot: RootHex): ProtoNode | undefined {
948
- const blockIndex = this.indices.get(blockRoot);
1665
+ /**
1666
+ * Return ProtoNode for blockRoot with explicit payload status
1667
+ *
1668
+ * @param blockRoot - The block root to look up
1669
+ * @param payloadStatus - The specific payload status variant (PENDING/EMPTY/FULL)
1670
+ * @returns The ProtoNode for the specified variant, or undefined if not found
1671
+ *
1672
+ * Note: Callers must explicitly specify which variant they need.
1673
+ * Use getDefaultVariant() to get the canonical variant for a block.
1674
+ */
1675
+ getNode(blockRoot: RootHex, payloadStatus: PayloadStatus): ProtoNode | undefined {
1676
+ const blockIndex = this.getNodeIndexByRootAndStatus(blockRoot, payloadStatus);
949
1677
  if (blockIndex === undefined) {
950
1678
  return undefined;
951
1679
  }
952
1680
  return this.getNodeByIndex(blockIndex);
953
1681
  }
954
1682
 
955
- /** Return MUTABLE ProtoBlock for blockRoot (spreads properties) */
956
- getBlock(blockRoot: RootHex): ProtoBlock | undefined {
957
- const node = this.getNode(blockRoot);
1683
+ /**
1684
+ * Return MUTABLE ProtoBlock for blockRoot with explicit payload status
1685
+ *
1686
+ * @param blockRoot - The block root to look up
1687
+ * @param payloadStatus - The specific payload status variant (PENDING/EMPTY/FULL)
1688
+ * @returns The ProtoBlock for the specified variant (spreads properties), or undefined if not found
1689
+ *
1690
+ * Note: Callers must explicitly specify which variant they need.
1691
+ * Use getDefaultVariant() to get the canonical variant for a block.
1692
+ */
1693
+ getBlock(blockRoot: RootHex, payloadStatus: PayloadStatus): ProtoBlock | undefined {
1694
+ const node = this.getNode(blockRoot, payloadStatus);
958
1695
  if (!node) {
959
1696
  return undefined;
960
1697
  }
@@ -963,9 +1700,19 @@ export class ProtoArray {
963
1700
  };
964
1701
  }
965
1702
 
966
- /** Return NON-MUTABLE ProtoBlock for blockRoot (does not spread properties) */
967
- getBlockReadonly(blockRoot: RootHex): ProtoBlock {
968
- const node = this.getNode(blockRoot);
1703
+ /**
1704
+ * Return NON-MUTABLE ProtoBlock for blockRoot with explicit payload status
1705
+ *
1706
+ * @param blockRoot - The block root to look up
1707
+ * @param payloadStatus - The specific payload status variant (PENDING/EMPTY/FULL)
1708
+ * @returns The ProtoBlock for the specified variant (does not spread properties)
1709
+ * @throws Error if block not found
1710
+ *
1711
+ * Note: Callers must explicitly specify which variant they need.
1712
+ * Use getDefaultVariant() to get the canonical variant for a block.
1713
+ */
1714
+ getBlockReadonly(blockRoot: RootHex, payloadStatus: PayloadStatus): ProtoBlock {
1715
+ const node = this.getNode(blockRoot, payloadStatus);
969
1716
  if (!node) {
970
1717
  throw Error(`No block for root ${blockRoot}`);
971
1718
  }
@@ -975,23 +1722,28 @@ export class ProtoArray {
975
1722
  /**
976
1723
  * Returns `true` if the `descendantRoot` has an ancestor with `ancestorRoot`.
977
1724
  * Always returns `false` if either input roots are unknown.
978
- * Still returns `true` if `ancestorRoot` === `descendantRoot` (and the roots are known)
1725
+ * Still returns `true` if `ancestorRoot` === `descendantRoot` and payload statuses match.
979
1726
  */
980
- isDescendant(ancestorRoot: RootHex, descendantRoot: RootHex): boolean {
981
- const ancestorNode = this.getNode(ancestorRoot);
1727
+ isDescendant(
1728
+ ancestorRoot: RootHex,
1729
+ ancestorPayloadStatus: PayloadStatus,
1730
+ descendantRoot: RootHex,
1731
+ descendantPayloadStatus: PayloadStatus
1732
+ ): boolean {
1733
+ const ancestorNode = this.getNode(ancestorRoot, ancestorPayloadStatus);
982
1734
  if (!ancestorNode) {
983
1735
  return false;
984
1736
  }
985
1737
 
986
- if (ancestorRoot === descendantRoot) {
1738
+ if (ancestorRoot === descendantRoot && ancestorPayloadStatus === descendantPayloadStatus) {
987
1739
  return true;
988
1740
  }
989
1741
 
990
- for (const node of this.iterateAncestorNodes(descendantRoot)) {
1742
+ for (const node of this.iterateAncestorNodes(descendantRoot, descendantPayloadStatus)) {
991
1743
  if (node.slot < ancestorNode.slot) {
992
1744
  return false;
993
1745
  }
994
- if (node.blockRoot === ancestorNode.blockRoot) {
1746
+ if (node.blockRoot === ancestorNode.blockRoot && node.payloadStatus === ancestorNode.payloadStatus) {
995
1747
  return true;
996
1748
  }
997
1749
  }