@lodestar/fork-choice 1.45.0-dev.77f7452c30 → 1.45.0-dev.7a06691aa8

package/src/forkChoice/forkChoice.ts

@@ -1,5 +1,5 @@
 import {ChainForkConfig} from "@lodestar/config";
-import {MIN_SEED_LOOKAHEAD, SLOTS_PER_EPOCH} from "@lodestar/params";
+import {MIN_SEED_LOOKAHEAD, SLOTS_PER_EPOCH, isForkPostGloas} from "@lodestar/params";
 import {
   DataAvailabilityStatus,
   EffectiveBalanceIncrements,
@@ -152,6 +152,7 @@ export class ForkChoice implements IForkChoice {
   /** Optional fast confirmation rule implementation */
   private readonly fastConfirmationRule?: IFastConfirmationRule;
   private readonly fastConfirmationContext?: FastConfirmationContext;
+  private fastConfirmationPaused = false;
   /**
    * Instantiates a Fork Choice from some existing components
    *
@@ -180,6 +181,7 @@ export class ForkChoice implements IForkChoice {
     if (this.opts?.fastConfirmation) {
       this.fastConfirmationRule = new FastConfirmationRule(this.fcStore, metrics, this.logger);
       this.fastConfirmationContext = this.createFastConfirmationContext();
+      metrics?.fastConfirmation.paused.set(0);
     }
 
     metrics?.forkChoice.votes.addCollect(() => {
@@ -230,6 +232,47 @@ export class ForkChoice implements IForkChoice {
     return this.getBlockHexDefaultStatus(this.getConfirmedRoot());
   }
 
+  resumeFastConfirmation(): void {
+    this.toggleFastConfirmation(false);
+  }
+
+  pauseFastConfirmation(): void {
+    this.toggleFastConfirmation(true);
+  }
+
+  private toggleFastConfirmation(paused: boolean): void {
+    if (!this.fastConfirmationRule) return;
+    if (paused === this.fastConfirmationPaused) return;
+    this.fastConfirmationPaused = paused;
+    if (paused) {
+      // Pin immediately: block imports report the safe block hash to the EL before the next slot tick
+      this.fcStore.confirmedRoot = this.fcStore.finalizedCheckpoint.rootHex;
+      try {
+        this.notifyConfirmedRoot();
+      } catch (err) {
+        // Callers run in clock/network handler context with no catch above
+        this.logger?.debug("Fast confirmation notify failed", {slot: this.fcStore.currentSlot}, err as Error);
+      }
+    }
+    this.metrics?.fastConfirmation.paused.set(paused ? 1 : 0);
+    this.logger?.info(paused ? "Paused fast confirmation" : "Resumed fast confirmation", {
+      slot: this.fcStore.currentSlot,
+    });
+  }
+
+  private notifyConfirmedRoot(): void {
+    const confirmedRoot = this.fcStore.confirmedRoot;
+    const confirmedBlock = this.getBlockHexDefaultStatus(confirmedRoot);
+    if (confirmedBlock === null) {
+      throw new Error(`Fast confirmation produced root not in protoArray: ${confirmedRoot}`);
+    }
+    this.fcStore.notifyFastConfirmation?.({
+      block: confirmedRoot,
+      slot: confirmedBlock.slot,
+      currentSlot: this.fcStore.currentSlot,
+    });
+  }
+
   /**
    *
    * A multiplexer to wrap around the traditional `updateHead()` according to the scenario
@@ -455,30 +498,12 @@ export class ForkChoice implements IForkChoice {
     }
 
     // No reorg if headBlock is "not weak" ie. headBlock's weight exceeds (REORG_HEAD_WEIGHT_THRESHOLD = 20)% of total attester weight
-    // https://github.com/ethereum/consensus-specs/blob/v1.4.0-beta.4/specs/phase0/fork-choice.md#is_head_weak
-    const reorgThreshold = getCommitteeFraction(this.fcStore.justified.totalBalance, {
-      slotsPerEpoch: SLOTS_PER_EPOCH,
-      committeePercent: this.config.REORG_HEAD_WEIGHT_THRESHOLD,
-    });
-    const headNode = this.protoArray.getNode(headBlock.blockRoot, headBlock.payloadStatus);
-    // If headNode is unavailable, give up reorg
-    if (headNode === undefined || headNode.weight >= reorgThreshold) {
+    if (!this.isHeadWeak(headBlock.blockRoot)) {
       return {proposerHead, isHeadTimely, notReorgedReason: NotReorgedReason.HeadBlockNotWeak};
     }
 
     // No reorg if parentBlock is "not strong" ie. parentBlock's weight is less than or equal to (REORG_PARENT_WEIGHT_THRESHOLD = 160)% of total attester weight
-    // https://github.com/ethereum/consensus-specs/blob/v1.7.0-alpha.11/specs/phase0/fork-choice.md#is_parent_strong
-    // For Gloas: measure support for the parent beacon block root regardless of its payload status by
-    // looking up the PENDING variant.
-    // https://github.com/ethereum/consensus-specs/blob/v1.7.0-alpha.11/specs/gloas/fork-choice.md#modified-is_parent_strong
-    const parentThreshold = getCommitteeFraction(this.fcStore.justified.totalBalance, {
-      slotsPerEpoch: SLOTS_PER_EPOCH,
-      committeePercent: this.config.REORG_PARENT_WEIGHT_THRESHOLD,
-    });
-    const parentStrongVariant = isGloasBlock(parentBlock) ? PayloadStatus.PENDING : PayloadStatus.FULL;
-    const parentNode = this.protoArray.getNode(parentBlock.blockRoot, parentStrongVariant);
-    // If parentNode is unavailable, give up reorg
-    if (parentNode === undefined || parentNode.weight <= parentThreshold) {
+    if (!this.isParentStrong(parentBlock.blockRoot)) {
       return {proposerHead, isHeadTimely, notReorgedReason: NotReorgedReason.ParentBlockNotStrong};
     }
 
@@ -521,7 +546,7 @@ export class ForkChoice implements IForkChoice {
 
     const timer = computeDeltasMetrics?.duration.startTimer();
     const {
-      deltas,
+      attestationDeltas,
       equivocatingValidators,
       oldInactiveValidators,
       newInactiveValidators,
@@ -537,8 +562,8 @@ export class ForkChoice implements IForkChoice {
     );
     timer?.();
 
-    computeDeltasMetrics?.deltasCount.set(deltas.length);
-    computeDeltasMetrics?.zeroDeltasCount.set(deltas.filter((d) => d === 0).length);
+    computeDeltasMetrics?.deltasCount.set(attestationDeltas.length);
+    computeDeltasMetrics?.zeroDeltasCount.set(attestationDeltas.filter((d) => d === 0).length);
     computeDeltasMetrics?.equivocatingValidators.set(equivocatingValidators);
     computeDeltasMetrics?.oldInactiveValidators.set(oldInactiveValidators);
     computeDeltasMetrics?.newInactiveValidators.set(newInactiveValidators);
@@ -564,7 +589,7 @@ export class ForkChoice implements IForkChoice {
 
     const currentSlot = this.fcStore.currentSlot;
     this.protoArray.applyScoreChanges({
-      deltas,
+      attestationDeltas,
       proposerBoost,
       justifiedEpoch: this.fcStore.justified.checkpoint.epoch,
       justifiedRoot: this.fcStore.justified.checkpoint.rootHex,
@@ -589,11 +614,31 @@ export class ForkChoice implements IForkChoice {
     return this.protoArray.nodes.filter((node) => node.slot > windowStart).length;
   }
 
+  getPayloadRevealCounts(fromSlot: Slot, toSlot: Slot): {blocksPresent: number; payloadsRevealed: number} {
+    return this.protoArray.getPayloadRevealCounts(fromSlot, toSlot);
+  }
+
   /** Very expensive function, iterates the entire ProtoArray. Called only in debug API */
   getHeads(): ProtoBlock[] {
     return this.protoArray.nodes.filter((node) => node.bestChild === undefined);
   }
 
+  /**
+   * weight is in EFFECTIVE_BALANCE_INCREMENTS not gwei.
+   * For compliance test use only
+   */
+  getViableHeads(): {root: RootHex; payloadStatus: PayloadStatus; weight: number}[] {
+    return this.protoArray.getViableHeads(this.fcStore.currentSlot);
+  }
+
+  /**
+   * The cached justified total active balance, in EFFECTIVE_BALANCE_INCREMENT units.
+   * For compliance test use only
+   */
+  getJustifiedTotalActiveBalanceByIncrement(): number {
+    return this.fcStore.justified.totalBalance;
+  }
+
   /** This is for the debug API only */
   getAllNodes(): ProtoNode[] {
     return this.protoArray.nodes;
@@ -1526,6 +1571,93 @@ export class ForkChoice implements IForkChoice {
     return headDependentRoot === blockDependentRoot;
   }
 
+  /**
+   * Return true if the block is "weak" ie. its weight is below REORG_HEAD_WEIGHT_THRESHOLD of the
+   * total attester weight per slot.
+   *
+   * https://github.com/ethereum/consensus-specs/blob/v1.7.0-alpha.11/specs/phase0/fork-choice.md#is_head_weak
+   * https://github.com/ethereum/consensus-specs/blob/v1.7.0-alpha.11/specs/gloas/fork-choice.md#modified-is_head_weak
+   */
+  private isHeadWeak(blockRoot: RootHex): boolean {
+    // The default variant is PENDING for gloas, FULL pre-gloas. PENDING is the variant gloas measures
+    // support on, ie. support for the beacon block root regardless of its payload status.
+    // Only ever called on a block already in fork choice, so a miss is a broken invariant.
+    const node = this.protoArray.getNodeDefaultStatus(blockRoot);
+    if (node === undefined) {
+      // this is called for head so we should always have this in forkchoice, otherwise we have a serious error
+      throw new ForkChoiceError({code: ForkChoiceErrorCode.MISSING_PROTO_ARRAY_BLOCK, root: blockRoot});
+    }
+
+    const reorgThreshold = getCommitteeFraction(this.fcStore.justified.totalBalance, {
+      slotsPerEpoch: SLOTS_PER_EPOCH,
+      committeePercent: this.config.REORG_HEAD_WEIGHT_THRESHOLD,
+    });
+
+    if (!isForkPostGloas(this.config.getForkName(node.slot))) {
+      return node.weight < reorgThreshold;
+    }
+
+    let headWeight = node.attestationScore;
+
+    const {equivocatingIndices} = this.fcStore;
+    // Equivocators are extremely rare (none in normal operation), and with none the added weight is
+    // always 0. Return before fetching the state and walking the block's committees.
+    if (equivocatingIndices.size > 0) {
+      const state = this.fcStore.stateGetter({stateRoot: node.stateRoot});
+      // Only ever called on the head, so the state is always cached.
+      // A miss is a broken invariant, not a recoverable state.
+      if (state === null) {
+        throw new ForkChoiceError({
+          code: ForkChoiceErrorCode.BEACON_STATE_ERROR,
+          error: new Error(`Missing state for isHeadWeak, blockRoot=${blockRoot} stateRoot=${node.stateRoot}`),
+        });
+      }
+
+      const epoch = computeEpochAtSlot(node.slot);
+      for (let index = 0; index < state.getBeaconCommitteeCountPerSlot(epoch); index++) {
+        for (const validatorIndex of state.getBeaconCommittee(node.slot, index)) {
+          if (equivocatingIndices.has(validatorIndex)) {
+            // the spec specifies to use effective_balance of the justified state
+            let balance = this.fcStore.justified.balances[validatorIndex];
+            if (!balance) {
+              // 0 (zeroed by getEffectiveBalanceIncrementsZeroInactive) or undefined (validator not in
+              // the justified state) - fall back to the head state's effective balance
+              balance = state.effectiveBalanceIncrements[validatorIndex];
+            }
+            headWeight += balance;
+          }
+        }
+      }
+    }
+
+    return headWeight < reorgThreshold;
+  }
+
+  /**
+   * Return true if the parent block is "strong" ie. its weight exceeds REORG_PARENT_WEIGHT_THRESHOLD
+   * of the total attester weight per slot.
+   *
+   * https://github.com/ethereum/consensus-specs/blob/v1.7.0-alpha.12/specs/phase0/fork-choice.md#is_parent_strong
+   * https://github.com/ethereum/consensus-specs/blob/v1.7.0-alpha.12/specs/gloas/fork-choice.md#modified-is_parent_strong
+   */
+  private isParentStrong(parentRoot: RootHex): boolean {
+    const node = this.protoArray.getNodeDefaultStatus(parentRoot);
+    // If parentNode is unavailable, give up reorg
+    if (node === undefined) {
+      return false;
+    }
+
+    const parentThreshold = getCommitteeFraction(this.fcStore.justified.totalBalance, {
+      slotsPerEpoch: SLOTS_PER_EPOCH,
+      committeePercent: this.config.REORG_PARENT_WEIGHT_THRESHOLD,
+    });
+
+    // pre-gloas uses get_weight() (boost-inclusive), gloas uses get_attestation_score() (boost-excluded)
+    const parentWeight = isForkPostGloas(this.config.getForkName(node.slot)) ? node.attestationScore : node.weight;
+
+    return parentWeight > parentThreshold;
+  }
+
   /**
    * Return true if the block is timely for the current slot.
    * Child class can overwrite this for testing purpose.
@@ -1978,9 +2110,23 @@ export class ForkChoice implements IForkChoice {
   }
 
   private runFastConfirmation(): void {
-    withObservedDuration(this.metrics?.fastConfirmation.totalDuration.startTimer(), () => {
-      if (!this.fastConfirmationRule || !this.fastConfirmationContext) return;
+    const fastConfirmationRule = this.fastConfirmationRule;
+    const fastConfirmationContext = this.fastConfirmationContext;
+    if (!fastConfirmationRule || !fastConfirmationContext) return;
 
+    if (this.fastConfirmationPaused) {
+      // Keep consumers on a safe, available root while the rule is paused
+      this.fcStore.confirmedRoot = this.fcStore.finalizedCheckpoint.rootHex;
+      try {
+        this.notifyConfirmedRoot();
+      } catch (err) {
+        // Runs outside the timed try/catch below; a throw would escape to the clock listener
+        this.logger?.debug("Fast confirmation notify failed", {slot: this.fcStore.currentSlot}, err as Error);
+      }
+      return;
+    }
+
+    withObservedDuration(this.metrics?.fastConfirmation.totalDuration.startTimer(), () => {
       try {
         withObservedDuration(
           this.metrics?.fastConfirmation.stepsDuration.startTimer({
@@ -1989,18 +2135,9 @@ export class ForkChoice implements IForkChoice {
           () => this.updateHead()
         );
 
-        const result = this.fastConfirmationRule.onSlotStartAfterPastAttestationsApplied(this.fastConfirmationContext);
+        const result = fastConfirmationRule.onSlotStartAfterPastAttestationsApplied(fastConfirmationContext);
         this.fcStore.confirmedRoot = result.confirmedRoot;
-
-        const confirmedBlock = this.getBlockHexDefaultStatus(result.confirmedRoot);
-        if (confirmedBlock === null) {
-          throw new Error(`Fast confirmation produced root not in protoArray: ${result.confirmedRoot}`);
-        }
-        this.fcStore.notifyFastConfirmation?.({
-          block: result.confirmedRoot,
-          slot: confirmedBlock.slot,
-          currentSlot: this.fcStore.currentSlot,
-        });
+        this.notifyConfirmedRoot();
       } catch (err) {
         this.logger?.debug(
           "Fast confirmation failed",

package/src/forkChoice/interface.ts

@@ -100,6 +100,10 @@ export interface IForkChoice {
   getHead(): ProtoBlock;
   getConfirmedRoot(): RootHex;
   getConfirmedBlock(): ProtoBlock | null;
+  /** Resume the fast confirmation rule; restarts from the finalized root on the next slot tick */
+  resumeFastConfirmation(): void;
+  /** Pause the fast confirmation rule (e.g. while syncing); pins the confirmed root to the finalized root */
+  pauseFastConfirmation(): void;
   updateAndGetHead(mode: UpdateAndGetHeadOpt): {
     head: ProtoBlock;
     isHeadTimely?: boolean;
@@ -242,6 +246,11 @@ export interface IForkChoice {
   hasPayloadUnsafe(blockRoot: Root): boolean;
   hasPayloadHexUnsafe(blockRoot: RootHex): boolean;
   getSlotsPresent(windowStart: number): number;
+  /**
+   * Count gloas blocks with fromSlot <= slot <= toSlot and how many of them have a revealed
+   * payload (FULL variant exists). Used by the builder circuit breaker.
+   */
+  getPayloadRevealCounts(fromSlot: Slot, toSlot: Slot): {blocksPresent: number; payloadsRevealed: number};
   getPTCVotes(blockRootHex: RootHex): (boolean | null)[] | null;
   /** Raw PTC vote tallies for the debug fork choice endpoint; `null` for pre-Gloas roots. */
   getPTCVoteCounts(blockRootHex: RootHex): {

package/src/index.ts

@@ -17,7 +17,7 @@ export {
   type IFastConfirmationStore,
   getFastConfirmationMetrics,
 } from "./forkChoice/fastConfirmation/fastConfirmationRule.ts";
-export {ForkChoice, type ForkChoiceOpts, UpdateHeadOpt} from "./forkChoice/forkChoice.js";
+export {ForkChoice, type ForkChoiceOpts, UpdateHeadOpt, getCommitteeFraction} from "./forkChoice/forkChoice.js";
 export {
   type AncestorResult,
   AncestorStatus,

package/src/protoArray/computeDeltas.ts

@@ -4,10 +4,10 @@ import {ProtoArrayError, ProtoArrayErrorCode} from "./errors.js";
 import {NULL_VOTE_INDEX, VoteIndex} from "./interface.js";
 
 // reuse arrays to avoid memory reallocation and gc
-const deltas = new Array<number>();
+const attestationDeltas = new Array<number>();
 
 export type DeltasResult = {
-  deltas: number[];
+  attestationDeltas: number[];
   equivocatingValidators: number;
   // inactive validators before beacon node started
   oldInactiveValidators: number;
@@ -19,9 +19,9 @@ export type DeltasResult = {
 };
 
 /**
- * Returns a list of `deltas`, where there is one delta for each of the indices in `indices`
+ * Returns a list of `attestationDeltas`, where there is one delta for each of the indices in `indices`
  *
- * The deltas are formed by a change between `oldBalances` and `newBalances`, and/or a change of vote in `votes`.
+ * The attestationDeltas are formed by a change between `oldBalances` and `newBalances`, and/or a change of vote in `votes`.
  *
  * ## Errors
  *
@@ -46,8 +46,8 @@ export function computeDeltas(
     throw new Error(`numProtoNodes must be less than NULL_VOTE_INDEX: ${numProtoNodes} >= ${NULL_VOTE_INDEX}`);
   }
 
-  deltas.length = numProtoNodes;
-  deltas.fill(0);
+  attestationDeltas.length = numProtoNodes;
+  attestationDeltas.fill(0);
 
   // avoid creating new variables in the loop to potentially reduce GC pressure
   let oldBalance: number, newBalance: number;
@@ -80,7 +80,7 @@ export function computeDeltas(
           });
         }
         oldBalance = oldBalances[vIndex] ?? 0;
-        deltas[currentIndex] -= oldBalance;
+        attestationDeltas[currentIndex] -= oldBalance;
       }
       voteCurrentIndices[vIndex] = NULL_VOTE_INDEX;
       equivocatingIndex++;
@@ -125,7 +125,7 @@ export function computeDeltas(
           });
         }
 
-        deltas[currentIndex] -= oldBalance;
+        attestationDeltas[currentIndex] -= oldBalance;
       }
 
       // We ignore the vote if it is not known in `indices .
@@ -138,7 +138,7 @@ export function computeDeltas(
           });
         }
 
-        deltas[nextIndex] += newBalance;
+        attestationDeltas[nextIndex] += newBalance;
       }
       voteCurrentIndices[vIndex] = nextIndex;
       newVoteValidators++;
@@ -147,13 +147,13 @@ export function computeDeltas(
     }
   } // end validator loop
 
-  if (deltas.length !== numProtoNodes) {
-    // deltas array could be growed in the loop, especially if we mistakenly set the [NULL_VOTE_INDEX] to it , just to be safe
-    throw new Error(`deltas length mismatch: expected ${numProtoNodes}, got ${deltas.length}`);
+  if (attestationDeltas.length !== numProtoNodes) {
+    // attestationDeltas array could be growed in the loop, especially if we mistakenly set the [NULL_VOTE_INDEX] to it , just to be safe
+    throw new Error(`attestationDeltas length mismatch: expected ${numProtoNodes}, got ${attestationDeltas.length}`);
   }
 
   return {
-    deltas,
+    attestationDeltas,
     equivocatingValidators,
     oldInactiveValidators,
     newInactiveValidators,

package/src/protoArray/interface.ts

@@ -160,7 +160,13 @@ export type ProtoBlock = BlockExtraMeta & {
  */
 export type ProtoNode = ProtoBlock & {
   parent?: number;
+  /** Total weight, ie. attestationScore plus the proposer boost credited to this node */
   weight: number;
+  /**
+   * Weight from attester votes only, excluding proposer boost.
+   * Spec: get_attestation_score
+   */
+  attestationScore: number;
   bestChild?: number;
   bestDescendant?: number;
 };

package/src/protoArray/protoArray.ts

@@ -27,6 +27,12 @@ const PAYLOAD_TIMELY_THRESHOLD = Math.floor(PTC_SIZE / 2);
  */
 const DATA_AVAILABILITY_TIMELY_THRESHOLD = Math.floor(PTC_SIZE / 2);
 
+/**
+ * Proposer boost deltas, back-propagated to the boosted node's ancestors in applyScoreChanges().
+ * Reuse the array to avoid memory reallocation and gc, as computeDeltas does for attestation deltas.
+ */
+const boostDeltas = new Array<number>();
+
 /**
  * popcount(attended AND NOT yes) — explicit False-vote count.
  * Excludes PTC members who didn't attest (the None state).
@@ -348,7 +354,7 @@ export class ProtoArray {
    * - If required, update the parents best-descendant with the current node or its best-descendant.
    */
   applyScoreChanges({
-    deltas,
+    attestationDeltas,
     proposerBoost,
     justifiedEpoch,
     justifiedRoot,
@@ -356,7 +362,7 @@ export class ProtoArray {
     finalizedRoot,
     currentSlot,
   }: {
-    deltas: number[];
+    attestationDeltas: number[];
     proposerBoost: ProposerBoost | null;
     justifiedEpoch: Epoch;
     justifiedRoot: RootHex;
@@ -364,14 +370,17 @@ export class ProtoArray {
     finalizedRoot: RootHex;
     currentSlot: Slot;
   }): void {
-    if (deltas.length !== this.nodes.length) {
+    if (attestationDeltas.length !== this.nodes.length) {
       throw new ProtoArrayError({
         code: ProtoArrayErrorCode.INVALID_DELTA_LEN,
-        deltas: deltas.length,
+        deltas: attestationDeltas.length,
         indices: this.nodes.length,
       });
     }
 
+    boostDeltas.length = this.nodes.length;
+    boostDeltas.fill(0);
+
     if (
       justifiedEpoch !== this.justifiedEpoch ||
       finalizedEpoch !== this.finalizedEpoch ||
@@ -416,18 +425,22 @@ export class ProtoArray {
       // If this node's execution status has been marked invalid, then the weight of the node
       // needs to be taken out of consideration after which the node weight will become 0
       // for subsequent iterations of applyScoreChanges
-      const nodeDelta =
-        node.executionStatus === ExecutionStatus.Invalid
-          ? -node.weight
-          : deltas[nodeIndex] + currentBoost - previousBoost;
-
-      // Apply the delta to the node
-      node.weight += nodeDelta;
-
-      // Update the parent delta (if any)
+      const isInvalid = node.executionStatus === ExecutionStatus.Invalid;
+      const attestationDelta = isInvalid ? -node.attestationScore : attestationDeltas[nodeIndex];
+      const boostDelta = isInvalid
+        ? // old boost = weight - attestationScore
+          -(node.weight - node.attestationScore)
+        : boostDeltas[nodeIndex] + currentBoost - previousBoost;
+
+      // Apply the deltas to the node. Their sum is the node's total delta, so weight is unaffected
+      // by tracking the two scores apart.
+      node.attestationScore += attestationDelta;
+      node.weight += attestationDelta + boostDelta;
+
+      // Update the parent deltas (if any)
       const parentIndex = node.parent;
       if (parentIndex !== undefined) {
-        const parentDelta = deltas[parentIndex];
+        const parentDelta = attestationDeltas[parentIndex];
         if (parentDelta === undefined) {
           throw new ProtoArrayError({
             code: ProtoArrayErrorCode.INVALID_PARENT_DELTA,
@@ -435,8 +448,9 @@ export class ProtoArray {
           });
         }
 
-        // back-propagate the nodes delta to its parent
-        deltas[parentIndex] += nodeDelta;
+        // back-propagate the nodes deltas to its parent
+        attestationDeltas[parentIndex] += attestationDelta;
+        boostDeltas[parentIndex] += boostDelta;
       }
     }
 
@@ -514,6 +528,7 @@ export class ProtoArray {
         parent: parentIndex, // Points to parent's EMPTY/FULL or FULL (for transition)
         payloadStatus: PayloadStatus.PENDING,
         weight: 0,
+        attestationScore: 0,
         bestChild: undefined,
         bestDescendant: undefined,
       };
@@ -527,6 +542,7 @@ export class ProtoArray {
         parent: pendingIndex, // Points to own PENDING
         payloadStatus: PayloadStatus.EMPTY,
         weight: 0,
+        attestationScore: 0,
         bestChild: undefined,
         bestDescendant: undefined,
       };
@@ -562,6 +578,7 @@ export class ProtoArray {
         parent: this.getNodeIndexByRootAndStatus(block.parentRoot, PayloadStatus.FULL),
         payloadStatus: PayloadStatus.FULL,
         weight: 0,
+        attestationScore: 0,
         bestChild: undefined,
         bestDescendant: undefined,
       };
@@ -647,6 +664,7 @@ export class ProtoArray {
       parent: pendingIndex, // Points to own PENDING (same as EMPTY)
       payloadStatus: PayloadStatus.FULL,
       weight: 0,
+      attestationScore: 0,
       bestChild: undefined,
       bestDescendant: undefined,
       executionStatus,
@@ -672,6 +690,28 @@ export class ProtoArray {
     this.maybeUpdateBestChildAndDescendant(pendingIndex, fullIndex, currentSlot, proposerBoostRoot);
   }
 
+  /**
+   * Count gloas blocks with fromSlot <= slot <= toSlot and how many of them have a revealed
+   * payload (FULL variant exists). Used by the builder circuit breaker.
+   */
+  getPayloadRevealCounts(fromSlot: Slot, toSlot: Slot): {blocksPresent: number; payloadsRevealed: number} {
+    let blocksPresent = 0;
+    let payloadsRevealed = 0;
+    // Full scan, nodes are in import order not slot order (an old block can be imported after newer
+    // ones during sync or reorg resolution), so we cannot stop early on an out-of-window slot
+    for (const node of this.nodes) {
+      // Count each gloas block once via its PENDING variant, pre-gloas nodes are FULL only
+      if (node.slot < fromSlot || node.slot > toSlot || node.payloadStatus !== PayloadStatus.PENDING) {
+        continue;
+      }
+      blocksPresent++;
+      if (this.hasPayload(node.blockRoot)) {
+        payloadsRevealed++;
+      }
+    }
+    return {blocksPresent, payloadsRevealed};
+  }
+
   /**
    * Update PTC votes for multiple validators attesting to a block
    * Spec: gloas/fork-choice.md#new-notify_ptc_messages
@@ -1030,7 +1070,7 @@ export class ProtoArray {
 
     // update the forkchoice as the invalidation can change the entire forkchoice DAG
     this.applyScoreChanges({
-      deltas: Array.from({length: this.nodes.length}, () => 0),
+      attestationDeltas: Array.from({length: this.nodes.length}, () => 0),
       proposerBoost: this.previousProposerBoost,
       justifiedEpoch: this.justifiedEpoch,
       justifiedRoot: this.justifiedRoot,
@@ -1541,6 +1581,38 @@ export class ProtoArray {
     return correctJustified && correctFinalized;
   }
 
+  /** Weights are in EFFECTIVE_BALANCE_INCREMENT units (NOT Gwei); callers scale as needed. */
+  getViableHeads(currentSlot: Slot): {root: RootHex; payloadStatus: PayloadStatus; weight: number}[] {
+    // Mirror the spec's `get_filtered_block_tree`, which is rooted at the store's justified
+    // checkpoint: a viable head is a leaf (no viable descendant, i.e. `bestChild === undefined`)
+    // that descends from the justified checkpoint block AND is itself viable for head. Iterating
+    // all nodes without the justified-descendant filter would wrongly include FFG-viable leaves
+    // that hang off the finalized checkpoint on a branch not under the current justified checkpoint.
+    const justifiedVariant = this.getDefaultVariant(this.justifiedRoot);
+    // Gloas payload-status variants of one blockRoot are distinct nodes in the spec's filtered
+    // tree, identified by (root, payload_status, weight) — emit one entry per variant.
+    const heads: {root: RootHex; payloadStatus: PayloadStatus; weight: number}[] = [];
+    for (const node of this.nodes) {
+      if (node.bestChild !== undefined || !this.nodeIsViableForHead(node, currentSlot)) {
+        continue;
+      }
+      if (this.justifiedEpoch !== GENESIS_EPOCH) {
+        // Same-root short-circuit: every payload-status variant of the justified block itself is
+        // in the filtered tree, but `isDescendant` from the default (PENDING) variant does not
+        // reach the sibling EMPTY/FULL variants of the same root.
+        const descendsFromJustified =
+          node.blockRoot === this.justifiedRoot ||
+          (justifiedVariant !== undefined &&
+            this.isDescendant(this.justifiedRoot, justifiedVariant, node.blockRoot, node.payloadStatus));
+        if (!descendsFromJustified) {
+          continue;
+        }
+      }
+      heads.push({root: node.blockRoot, payloadStatus: node.payloadStatus, weight: node.weight});
+    }
+    return heads;
+  }
+
   /**
    * Return `true` if `node` is equal to or a descendant of the finalized node.
    * This function helps improve performance of nodeIsViableForHead a lot by avoiding
@@ -1898,6 +1970,19 @@ export class ProtoArray {
     return this.getNodeByIndex(blockIndex);
   }
 
+  /**
+   * Return ProtoNode for the default/canonical variant in a single hash lookup
+   * - Pre-Gloas blocks: the FULL variant
+   * - Gloas blocks: the PENDING variant
+   */
+  getNodeDefaultStatus(blockRoot: RootHex): ProtoNode | undefined {
+    const nodeIndex = this.getDefaultNodeIndex(blockRoot);
+    if (nodeIndex === undefined) {
+      return undefined;
+    }
+    return this.getNodeByIndex(nodeIndex);
+  }
+
   /**
    * Return MUTABLE ProtoBlock for blockRoot with explicit payload status
    *