@lodestar/fork-choice 1.50.0-dev.586c4d5d51 → 1.50.0-dev.5a1db4e01c

package/src/forkChoice/interface.ts

@@ -7,6 +7,7 @@ import {
   PayloadStatus,
   ProtoBlock,
   ProtoNode,
+  PtcQuorum,
 } from "../protoArray/interface.js";
 import {IFastConfirmationSpecStore} from "./fastConfirmation/types.js";
 import {UpdateAndGetHeadOpt} from "./forkChoice.js";
@@ -31,6 +32,9 @@ export type CheckpointWithTotalBalance = CheckpointWithBalance & {
   totalBalance: number;
 };
 
+/** Emitted when the PTC verdict on a block is decided or flips, see getPtcVerdict */
+export type PtcQuorumEvent = PtcQuorum & {blockRoot: RootHex; slot: Slot; verdict: boolean};
+
 export enum EpochDifference {
   current = 0,
   previous = 1,
@@ -259,6 +263,8 @@ export interface IForkChoice {
     payloadPresentCount: number;
     dataAvailableCount: number;
   } | null;
+  /** Current PTC majority per vote field; `null` for pre-Gloas roots */
+  getPtcQuorum(blockRootHex: RootHex): PtcQuorum | null;
   getPayloadTimelinessVotes(blockRootHex: RootHex): (boolean | null)[] | null;
   getPayloadDataAvailabilityVotes(blockRootHex: RootHex): (boolean | null)[] | null;
 

package/src/forkChoice/store.ts

@@ -2,7 +2,7 @@ import {EffectiveBalanceIncrements, IBeaconStateView} from "@lodestar/state-tran
 import {RootHex, Slot, ValidatorIndex, phase0} from "@lodestar/types";
 import {toRootHex} from "@lodestar/utils";
 import {ForkChoiceStateGetter, IFastConfirmationStore} from "./fastConfirmation/types.js";
-import {CheckpointWithBalance, CheckpointWithTotalBalance} from "./interface.js";
+import {CheckpointWithBalance, CheckpointWithTotalBalance, PtcQuorumEvent} from "./interface.js";
 
 /**
  * Stores checkpoints in a hybrid format:
@@ -46,6 +46,7 @@ export interface IForkChoiceStore extends IFastConfirmationStore {
   justifiedBalancesGetter: JustifiedBalancesGetter;
   equivocatingIndices: Set<ValidatorIndex>;
   notifyFastConfirmation?(data: {block: RootHex; slot: Slot; currentSlot: Slot}): void;
+  notifyPtcQuorum?(data: PtcQuorumEvent): void;
 }
 
 /**
@@ -85,6 +86,7 @@ export class ForkChoiceStore implements IForkChoiceStore {
       onJustified: (cp: CheckpointWithHex) => void;
       onFinalized: (cp: CheckpointWithHex) => void;
       onFastConfirmation?: (data: {block: RootHex; slot: Slot; currentSlot: Slot}) => void;
+      onPtcQuorum?: (data: PtcQuorumEvent) => void;
     }
   ) {
     this.justifiedBalancesGetter = justifiedBalancesGetter;
@@ -142,6 +144,10 @@ export class ForkChoiceStore implements IForkChoiceStore {
   notifyFastConfirmation(data: {block: RootHex; slot: Slot; currentSlot: Slot}): void {
     this.events?.onFastConfirmation?.(data);
   }
+
+  notifyPtcQuorum(data: PtcQuorumEvent): void {
+    this.events?.onPtcQuorum?.(data);
+  }
 }
 
 export function toCheckpointWithHex(checkpoint: phase0.Checkpoint): CheckpointWithHex {

package/src/index.ts

@@ -26,6 +26,7 @@ export {
   EpochDifference,
   type IForkChoice,
   NotReorgedReason,
+  type PtcQuorumEvent,
 } from "./forkChoice/interface.js";
 export * from "./forkChoice/safeBlocks.js";
 export {
@@ -43,6 +44,7 @@ export type {
   PayloadExecutionStatus,
   ProtoBlock,
   ProtoNode,
+  PtcQuorum,
 } from "./protoArray/interface.js";
-export {ExecutionStatus, PayloadStatus, isGloasBlock} from "./protoArray/interface.js";
+export {ExecutionStatus, PayloadStatus, getPtcVerdict, isGloasBlock} from "./protoArray/interface.js";
 export {ProtoArray} from "./protoArray/protoArray.js";

package/src/metrics.ts

@@ -68,6 +68,11 @@ export function getForkChoiceMetrics(register: MetricsRegisterExtra) {
         help: "Reason why the current head is not re-orged out",
         labelNames: ["reason"],
       }),
+      ptcQuorum: register.counter<{verdict: "true" | "false"}>({
+        name: "beacon_fork_choice_ptc_quorum_total",
+        help: "Count of decided PTC verdicts, true once majorities voted present and available, false once a majority voted either against",
+        labelNames: ["verdict"],
+      }),
       computeDeltas: {
         duration: register.histogram({
           name: "beacon_fork_choice_compute_deltas_seconds",

package/src/protoArray/interface.ts

@@ -180,3 +180,24 @@ export type ProtoNode = ProtoBlock & {
   bestChild?: number;
   bestDescendant?: number;
 };
+
+/**
+ * PTC majority per PayloadAttestationData field: `true` or `false` once more than PTC_SIZE // 2
+ * members voted that way, `null` while neither outcome has a majority.
+ */
+export type PtcQuorum = {
+  payloadPresent: boolean | null;
+  blobDataAvailable: boolean | null;
+};
+
+/**
+ * The PTC verdict fork choice acts on: `false` once either field has a majority against the
+ * payload, `true` once both have a majority for it, `null` while undecided. A single majority
+ * against is final on its own because should_extend_payload needs both in favour and
+ * should_build_on_full moves the proposer onto EMPTY on either.
+ */
+export function getPtcVerdict({payloadPresent, blobDataAvailable}: PtcQuorum): boolean | null {
+  if (payloadPresent === false || blobDataAvailable === false) return false;
+  if (payloadPresent === true && blobDataAvailable === true) return true;
+  return null;
+}

package/src/protoArray/protoArray.ts

@@ -13,6 +13,7 @@ import {
   PayloadStatus,
   ProtoBlock,
   ProtoNode,
+  PtcQuorum,
   isGloasBlock,
 } from "./interface.js";
 
@@ -52,6 +53,12 @@ export function countNoVotes(attended: BitArray, yes: BitArray): number {
   return count;
 }
 
+function majorityVote(attended: BitArray, yes: BitArray, threshold: number): boolean | null {
+  if (bitCount(yes.uint8Array) > threshold) return true;
+  if (countNoVotes(attended, yes) > threshold) return false;
+  return null;
+}
+
 export const DEFAULT_PRUNE_THRESHOLD = 0;
 type ProposerBoost = {root: RootHex; score: bigint};
 
@@ -90,6 +97,8 @@ export class ProtoArray {
   lvhError?: LVHExecError;
 
   private previousProposerBoost: ProposerBoost | null = null;
+  /** Root read by shouldExtendPayload(), set even while the boost weight is withheld */
+  private proposerBoostRoot: RootHex | null = null;
 
   /**
    * PTC (Payload Timeliness Committee) votes per block as bitvectors
@@ -357,6 +366,7 @@ export class ProtoArray {
   applyScoreChanges({
     attestationDeltas,
     proposerBoost,
+    proposerBoostRoot,
     justifiedEpoch,
     justifiedRoot,
     finalizedEpoch,
@@ -365,6 +375,8 @@ export class ProtoArray {
   }: {
     attestationDeltas: number[];
     proposerBoost: ProposerBoost | null;
+    /** Defaults to the boosted root. Pass it explicitly when the boost weight is withheld */
+    proposerBoostRoot?: RootHex | null;
     justifiedEpoch: Epoch;
     justifiedRoot: RootHex;
     finalizedEpoch: Epoch;
@@ -463,7 +475,9 @@ export class ProtoArray {
     // We _must_ perform these functions separate from the weight-updating loop above to ensure
     // that we have a fully coherent set of weights before updating parent
     // best-child/descendant.
-    const proposerBoostRoot = proposerBoost?.root ?? null;
+    // should_extend_payload reads store.proposer_boost_root even when should_apply_proposer_boost
+    // withholds the boost weight, so the tiebreak root is tracked apart from the applied boost
+    this.proposerBoostRoot = proposerBoostRoot ?? proposerBoost?.root ?? null;
     for (let nodeIndex = this.nodes.length - 1; nodeIndex >= 0; nodeIndex--) {
       const node = this.nodes[nodeIndex];
       if (node === undefined) {
@@ -476,7 +490,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, proposerBoostRoot);
+        this.maybeUpdateBestChildAndDescendant(parentIndex, nodeIndex, currentSlot, this.proposerBoostRoot);
       }
     }
     // Update the previous proposer boost
@@ -801,6 +815,23 @@ export class ProtoArray {
     };
   }
 
+  /**
+   * PTC majority per vote field from the raw tallies, regardless of whether the payload is locally
+   * available. Returns `null` for pre-Gloas (or pruned) roots, which have no vote maps.
+   */
+  getPtcQuorum(blockRoot: RootHex): PtcQuorum | null {
+    const attended = this.ptcAttested.get(blockRoot);
+    const timelinessVotes = this.payloadTimelinessVotes.get(blockRoot);
+    const daVotes = this.payloadDataAvailabilityVotes.get(blockRoot);
+    if (attended === undefined || timelinessVotes === undefined || daVotes === undefined) {
+      return null;
+    }
+    return {
+      payloadPresent: majorityVote(attended, timelinessVotes, PAYLOAD_TIMELY_THRESHOLD),
+      blobDataAvailable: majorityVote(attended, daVotes, DATA_AVAILABILITY_TIMELY_THRESHOLD),
+    };
+  }
+
   getPreviousProposerBoostRoot(): RootHex {
     return this.previousProposerBoost?.root ?? HEX_ZERO_HASH;
   }
@@ -1043,6 +1074,8 @@ export class ProtoArray {
 
   private propagateValidExecutionStatusByIndex(validNodeIndex: number): void {
     let nodeIndex: number | undefined = validNodeIndex;
+    // Payloads that transitioned to VALID, their gloas dependents are validated below
+    const validatedPayloadHashes = new Set<RootHex>();
     // propagate till we keep encountering syncing status
     while (nodeIndex !== undefined) {
       const node = this.getNodeFromIndex(nodeIndex);
@@ -1050,8 +1083,36 @@ export class ProtoArray {
         break;
       }
       this.validateNodeByIndex(nodeIndex);
+      if (node.payloadStatus === PayloadStatus.FULL && node.executionPayloadBlockHash !== null) {
+        validatedPayloadHashes.add(node.executionPayloadBlockHash);
+      }
       nodeIndex = node.parent;
     }
+
+    if (validatedPayloadHashes.size > 0) {
+      this.validatePayloadDependents(validatedPayloadHashes);
+    }
+  }
+
+  /**
+   * Gloas PENDING and EMPTY variants have no payload of their own, they inherit the execution status of
+   * the payload they build on, which is their `executionPayloadBlockHash`. Once that payload is VALID, all
+   * of them are, not only the ones on the chain the validation walked up (e.g. siblings, or blocks
+   * building on a sibling's EMPTY variant).
+   */
+  private validatePayloadDependents(payloadHashes: Set<RootHex>): void {
+    for (let nodeIndex = 0; nodeIndex < this.nodes.length; nodeIndex++) {
+      const node = this.nodes[nodeIndex];
+      if (
+        node.payloadStatus === PayloadStatus.PENDING &&
+        node.executionStatus === ExecutionStatus.Syncing &&
+        node.executionPayloadBlockHash !== null &&
+        payloadHashes.has(node.executionPayloadBlockHash)
+      ) {
+        // Also flips the sibling EMPTY variant
+        this.validateNodeByIndex(nodeIndex);
+      }
+    }
   }
 
   /**
@@ -1092,6 +1153,7 @@ export class ProtoArray {
     this.applyScoreChanges({
       attestationDeltas: Array.from({length: this.nodes.length}, () => 0),
       proposerBoost: this.previousProposerBoost,
+      proposerBoostRoot: this.proposerBoostRoot,
       justifiedEpoch: this.justifiedEpoch,
       justifiedRoot: this.justifiedRoot,
       finalizedEpoch: this.finalizedEpoch,