@lodestar/fork-choice 1.44.0-dev.6ef8199cfa → 1.44.0-dev.762dd5f186

package/src/forkChoice/forkChoice.ts

@@ -25,7 +25,7 @@ import {
   phase0,
   ssz,
 } from "@lodestar/types";
-import {Logger, MapDef, fromHex, toRootHex} from "@lodestar/utils";
+import {Logger, MapDef, fromHex, toRootHex, withObservedDuration} from "@lodestar/utils";
 import {ForkChoiceMetrics} from "../metrics.js";
 import {computeDeltas} from "../protoArray/computeDeltas.js";
 import {ProtoArrayError, ProtoArrayErrorCode} from "../protoArray/errors.js";
@@ -44,6 +44,12 @@ import {
 } from "../protoArray/interface.js";
 import {ProtoArray} from "../protoArray/protoArray.js";
 import {ForkChoiceError, ForkChoiceErrorCode, InvalidAttestationCode, InvalidBlockCode} from "./errors.js";
+import {
+  type FastConfirmationContext,
+  FastConfirmationRule,
+  FastConfirmationSteps,
+  type IFastConfirmationRule,
+} from "./fastConfirmation/fastConfirmationRule.ts";
 import {
   AncestorResult,
   AncestorStatus,
@@ -58,6 +64,7 @@ export type ForkChoiceOpts = {
   proposerBoost?: boolean;
   proposerBoostReorg?: boolean;
   computeUnrealized?: boolean;
+  fastConfirmation?: boolean;
 };
 
 export enum UpdateHeadOpt {
@@ -142,6 +149,9 @@ export class ForkChoice implements IForkChoice {
   private justifiedProposerBoostScore: number | null = null;
   /** The current effective balances */
   private balances: EffectiveBalanceIncrements;
+  /** Optional fast confirmation rule implementation */
+  private readonly fastConfirmationRule?: IFastConfirmationRule;
+  private readonly fastConfirmationContext?: FastConfirmationContext;
   /**
    * Instantiates a Fork Choice from some existing components
    *
@@ -167,6 +177,11 @@ export class ForkChoice implements IForkChoice {
     this.head = this.updateHead();
     this.balances = this.fcStore.justified.balances;
 
+    if (this.opts?.fastConfirmation) {
+      this.fastConfirmationRule = new FastConfirmationRule(this.fcStore, metrics, this.logger);
+      this.fastConfirmationContext = this.createFastConfirmationContext();
+    }
+
     metrics?.forkChoice.votes.addCollect(() => {
       metrics.forkChoice.votes.set(this.voteNextSlots.length);
       metrics.forkChoice.queuedAttestations.set(this.queuedAttestationsPreviousSlot);
@@ -207,6 +222,14 @@ export class ForkChoice implements IForkChoice {
     return this.head;
   }
 
+  getConfirmedRoot(): RootHex {
+    return this.fastConfirmationRule?.getConfirmedRoot() ?? this.fcStore.justified.checkpoint.rootHex;
+  }
+
+  getConfirmedBlock(): ProtoBlock | null {
+    return this.getBlockHexDefaultStatus(this.getConfirmedRoot());
+  }
+
   /**
    *
    * A multiplexer to wrap around the traditional `updateHead()` according to the scenario
@@ -310,6 +333,10 @@ export class ForkChoice implements IForkChoice {
     return this.proposerBoostRoot ?? HEX_ZERO_HASH;
   }
 
+  getPreviousProposerBoostRoot(): RootHex {
+    return this.protoArray.getPreviousProposerBoostRoot();
+  }
+
   /**
    * Decides whether to extend an available payload from the previous slot,
    * corresponding to the beacon block `blockRoot`.
@@ -318,6 +345,11 @@ export class ForkChoice implements IForkChoice {
     return this.protoArray.shouldExtendPayload(blockRoot, this.proposerBoostRoot);
   }
 
+  /** Spec: should_build_on_full(store, head) */
+  shouldBuildOnFull(head: ProtoBlock, slot: Slot): boolean {
+    return this.protoArray.shouldBuildOnFull(head, slot);
+  }
+
   /**
    * To predict the proposer head of the next slot. That is, to predict if proposer-boost-reorg could happen.
    * Reason why we can't be certain is because information of the head block is not fully available yet
@@ -596,7 +628,11 @@ export class ForkChoice implements IForkChoice {
     blockDelaySec: number,
     currentSlot: Slot,
     executionStatus: BlockExecutionStatus,
-    dataAvailabilityStatus: DataAvailabilityStatus
+    dataAvailabilityStatus: DataAvailabilityStatus,
+    // The expected proposer index on the canonical chain we are following.
+    // Calculated by our head state. We use it as part of the proposer
+    // boost decision making. No boost will be set if this is null.
+    expectedProposerIndex: ValidatorIndex | null
   ): ProtoBlock {
     const {parentRoot, slot} = block;
     const parentRootHex = toRootHex(parentRoot);
@@ -669,7 +705,9 @@ export class ForkChoice implements IForkChoice {
       this.opts?.proposerBoost &&
       isTimely &&
       // only boost the first block we see
-      this.proposerBoostRoot === null
+      this.proposerBoostRoot === null &&
+      expectedProposerIndex !== null &&
+      block.proposerIndex === expectedProposerIndex
     ) {
       this.proposerBoostRoot = blockRootHex;
     }
@@ -764,33 +802,32 @@ export class ForkChoice implements IForkChoice {
       unrealizedFinalizedRoot: unrealizedFinalizedCheckpoint.rootHex,
 
       ...(isGloasBeaconBlock(block)
-        ? {
-            executionPayloadBlockHash: toRootHex(block.body.signedExecutionPayloadBid.message.parentBlockHash), // post-gloas, we don't know payload hash until we import execution payload. Set to parent payload hash for now
-            executionPayloadNumber: (() => {
-              // Determine parent's execution payload number based on which variant the block extends
-              const parentBlockHashFromBid = toRootHex(block.body.signedExecutionPayloadBid.message.parentBlockHash);
-
-              // If parent is pre-merge, return 0
-              if (parentBlock.executionPayloadBlockHash === null) {
-                return 0;
-              }
-
-              // If parent is pre-Gloas, it only has FULL variant
-              if (parentBlock.parentBlockHash === null) {
-                return parentBlock.executionPayloadNumber;
-              }
-
-              // Parent is Gloas: get the variant that matches the parentBlockHash from bid
-              const parentVariant = this.getBlockHexAndBlockHash(parentRootHex, parentBlockHashFromBid);
-              if (parentVariant && parentVariant.executionPayloadBlockHash !== null) {
-                return parentVariant.executionPayloadNumber;
-              }
-              // Fallback to parent block's number (we know it's post-merge from check above)
-              return parentBlock.executionPayloadNumber;
-            })(),
-            executionStatus: this.getPostMergeExecStatus(executionStatus),
-            dataAvailabilityStatus,
-          }
+        ? (() => {
+            // post-gloas, we don't know payload hash until we import execution payload. Set to
+            // parent payload hash for now, along with the gas limit/number of that parent payload
+            // (which is what bids built on top of this block will reference until a payload arrives).
+            // we also use parent hash to pass to EL via fcu
+            // see https://github.com/ethereum/consensus-specs/pull/5197
+            const parentBlockHashFromBid = toRootHex(block.body.signedExecutionPayloadBid.message.parentBlockHash);
+
+            // Inherit parent payload's (number, gasLimit) for the PENDING/EMPTY variants.
+            // `parentBlock` is already the variant matching `parentBlockHashFromBid` —
+            // `getParent` (called above) resolves Gloas parents via
+            // `getBlockHexAndBlockHash(parentRoot, parentBlockHash)`, and pre-Gloas parents
+            // have a single variant. Pre-merge parents have null payload hash and zero values.
+            const parentMeta: {number: number; gasLimit: number} =
+              parentBlock.executionPayloadBlockHash === null
+                ? {number: 0, gasLimit: 0}
+                : {number: parentBlock.executionPayloadNumber, gasLimit: parentBlock.executionPayloadGasLimit};
+
+            return {
+              executionPayloadBlockHash: parentBlockHashFromBid,
+              executionPayloadNumber: parentMeta.number,
+              executionPayloadGasLimit: parentMeta.gasLimit,
+              executionStatus: this.getPostMergeExecStatus(executionStatus),
+              dataAvailabilityStatus,
+            };
+          })()
         : isExecutionBlockBodyType(block.body) &&
             isStatePostBellatrix(state) &&
             state.isExecutionStateType &&
@@ -798,6 +835,7 @@ export class ForkChoice implements IForkChoice {
           ? {
               executionPayloadBlockHash: toRootHex(block.body.executionPayload.blockHash),
               executionPayloadNumber: block.body.executionPayload.blockNumber,
+              executionPayloadGasLimit: block.body.executionPayload.gasLimit,
               executionStatus: this.getPostMergeExecStatus(executionStatus),
               dataAvailabilityStatus,
             }
@@ -934,8 +972,14 @@ export class ForkChoice implements IForkChoice {
    * Updates the PTC votes for multiple validators attesting to a block
    * Spec: gloas/fork-choice.md#new-on_payload_attestation_message
    */
-  notifyPtcMessages(blockRoot: RootHex, ptcIndices: number[], payloadPresent: boolean): void {
-    this.protoArray.notifyPtcMessages(blockRoot, ptcIndices, payloadPresent);
+  notifyPtcMessages(
+    blockRoot: RootHex,
+    slot: Slot,
+    ptcIndices: number[],
+    payloadPresent: boolean,
+    blobDataAvailable: boolean
+  ): void {
+    this.protoArray.notifyPtcMessages(blockRoot, slot, ptcIndices, payloadPresent, blobDataAvailable);
   }
 
   /**
@@ -947,6 +991,7 @@ export class ForkChoice implements IForkChoice {
     blockRoot: RootHex,
     executionPayloadBlockHash: RootHex,
     executionPayloadNumber: number,
+    executionPayloadGasLimit: number,
     executionStatus: PayloadExecutionStatus,
     dataAvailabilityStatus: DataAvailabilityStatus
   ): void {
@@ -955,6 +1000,7 @@ export class ForkChoice implements IForkChoice {
       this.fcStore.currentSlot,
       executionPayloadBlockHash,
       executionPayloadNumber,
+      executionPayloadGasLimit,
       this.proposerBoostRoot,
       executionStatus,
       dataAvailabilityStatus
@@ -975,12 +1021,12 @@ export class ForkChoice implements IForkChoice {
       const previousSlot = this.fcStore.currentSlot;
       // Note: we are relying upon `onTick` to update `fcStore.time` to ensure we don't get stuck in a loop.
       this.onTick(previousSlot + 1);
+      this.queuedAttestationsPreviousSlot = 0;
+      // Process any attestations that might now be eligible before running FCR for this slot.
+      this.processAttestationQueue();
+      this.runFastConfirmation();
+      this.validatedAttestationDatas = new Set();
     }
-
-    this.queuedAttestationsPreviousSlot = 0;
-    // Process any attestations that might now be eligible.
-    this.processAttestationQueue();
-    this.validatedAttestationDatas = new Set();
   }
 
   getTime(): Slot {
@@ -1049,6 +1095,30 @@ export class ForkChoice implements IForkChoice {
     return votes.toBoolArray().map((v) => v ?? null);
   }
 
+  getPTCVoteCounts(blockRootHex: RootHex): {
+    attesterCount: number;
+    payloadPresentCount: number;
+    dataAvailableCount: number;
+  } | null {
+    return this.protoArray.getPTCVoteCounts(blockRootHex);
+  }
+
+  getPayloadTimelinessVotes(blockRootHex: RootHex): (boolean | null)[] | null {
+    return this.protoArray.getPayloadTimelinessVotes(blockRootHex);
+  }
+
+  getPayloadDataAvailabilityVotes(blockRootHex: RootHex): (boolean | null)[] | null {
+    return this.protoArray.getPayloadDataAvailabilityVotes(blockRootHex);
+  }
+
+  getUnrealizedJustifiedCheckpoint(): CheckpointWithHex {
+    return this.fcStore.unrealizedJustified.checkpoint;
+  }
+
+  getUnrealizedFinalizedCheckpoint(): CheckpointWithHex {
+    return this.fcStore.unrealizedFinalizedCheckpoint;
+  }
+
   /**
    * Returns a MUTABLE `ProtoBlock` if the block is known **and** a descendant of the finalized root.
    */
@@ -1874,6 +1944,88 @@ export class ForkChoice implements IForkChoice {
 
     return {prelimProposerHead};
   }
+
+  private runFastConfirmation(): void {
+    withObservedDuration(this.metrics?.fastConfirmation.totalDuration.startTimer(), () => {
+      if (!this.fastConfirmationRule || !this.fastConfirmationContext) return;
+
+      try {
+        withObservedDuration(
+          this.metrics?.fastConfirmation.stepsDuration.startTimer({
+            step: FastConfirmationSteps.updateHead,
+          }),
+          () => this.updateHead()
+        );
+
+        const result = this.fastConfirmationRule.onSlotStartAfterPastAttestationsApplied(this.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,
+        });
+      } catch (err) {
+        this.logger?.debug(
+          "Fast confirmation failed",
+          {slot: this.fcStore.currentSlot, head: this.head.blockRoot, confirmedRoot: this.fcStore.confirmedRoot},
+          err as Error
+        );
+      }
+    });
+  }
+
+  private createFastConfirmationContext(): FastConfirmationContext {
+    const confirmationByzantineThreshold = this.config.CONFIRMATION_BYZANTINE_THRESHOLD;
+    if (!confirmationByzantineThreshold) {
+      throw new Error("CONFIRMATION_BYZANTINE_THRESHOLD must be set to use fast confirmation");
+    }
+
+    return {
+      config: {
+        CONFIRMATION_BYZANTINE_THRESHOLD: confirmationByzantineThreshold,
+        PROPOSER_SCORE_BOOST: this.config.PROPOSER_SCORE_BOOST,
+      },
+      getCurrentSlot: () => this.fcStore.currentSlot,
+      getHead: () => this.head,
+      getBlock: (root: RootHex) => this.getBlockHexDefaultStatus(root),
+      getAncestor: (root: RootHex, slot: Slot) => this.getAncestor(root, slot).blockRoot,
+      isDescendant: (ancestor: RootHex, descendant: RootHex) => {
+        const ancestorStatus = this.protoArray.getDefaultVariant(ancestor);
+        const descendantStatus = this.protoArray.getDefaultVariant(descendant);
+        if (ancestorStatus === undefined || descendantStatus === undefined) return false;
+        return this.isDescendant(ancestor, ancestorStatus, descendant, descendantStatus);
+      },
+      getLatestMessage: (validatorIndex: ValidatorIndex) => {
+        const nextIndex = this.voteNextIndices[validatorIndex];
+        if (nextIndex === undefined || nextIndex === NULL_VOTE_INDEX) {
+          return null;
+        }
+        const node = this.protoArray.nodes[nextIndex];
+        if (!node) return null;
+        return {root: node.blockRoot, epoch: computeEpochAtSlot(this.voteNextSlots[validatorIndex])};
+      },
+      getUnrealizedJustified: () => ({
+        checkpoint: this.fcStore.unrealizedJustified.checkpoint,
+        balances: this.fcStore.unrealizedJustified.balances,
+      }),
+      getFinalizedCheckpoint: () => this.fcStore.finalizedCheckpoint,
+      getEquivocatingIndices: () => this.fcStore.equivocatingIndices,
+      getTrackedVotesCount: () => {
+        let count = 0;
+        for (let i = 0; i < this.voteNextIndices.length; i++) {
+          if (this.voteNextIndices[i] !== NULL_VOTE_INDEX) {
+            count++;
+          }
+        }
+        return count;
+      },
+    };
+  }
 }
 
 // Approximate https://github.com/ethereum/consensus-specs/blob/v1.6.1/specs/phase0/fork-choice.md#calculate_committee_fraction

package/src/forkChoice/interface.ts

@@ -1,5 +1,14 @@
 import {DataAvailabilityStatus, EffectiveBalanceIncrements, IBeaconStateView} from "@lodestar/state-transition";
-import {AttesterSlashing, BeaconBlock, Epoch, IndexedAttestation, Root, RootHex, Slot} from "@lodestar/types";
+import {
+  AttesterSlashing,
+  BeaconBlock,
+  Epoch,
+  IndexedAttestation,
+  Root,
+  RootHex,
+  Slot,
+  ValidatorIndex,
+} from "@lodestar/types";
 import {
   BlockExecutionStatus,
   LVHExecResponse,
@@ -98,6 +107,8 @@ export interface IForkChoice {
    */
   getHeadRoot(): RootHex;
   getHead(): ProtoBlock;
+  getConfirmedRoot(): RootHex;
+  getConfirmedBlock(): ProtoBlock | null;
   updateAndGetHead(mode: UpdateAndGetHeadOpt): {
     head: ProtoBlock;
     isHeadTimely?: boolean;
@@ -123,6 +134,10 @@ export interface IForkChoice {
   getAllNodes(): ProtoNode[];
   getFinalizedCheckpoint(): CheckpointWithHex;
   getJustifiedCheckpoint(): CheckpointWithHex;
+  getUnrealizedJustifiedCheckpoint(): CheckpointWithHex;
+  getUnrealizedFinalizedCheckpoint(): CheckpointWithHex;
+  getProposerBoostRoot(): RootHex;
+  getPreviousProposerBoostRoot(): RootHex;
   /**
    * Add `block` to the fork choice DAG.
    *
@@ -145,7 +160,8 @@ export interface IForkChoice {
     blockDelaySec: number,
     currentSlot: Slot,
     executionStatus: BlockExecutionStatus,
-    dataAvailabilityStatus: DataAvailabilityStatus
+    dataAvailabilityStatus: DataAvailabilityStatus,
+    expectedProposerIndex: ValidatorIndex | null
   ): ProtoBlock;
   /**
    * Register `attestation` with the fork choice DAG so that it may influence future calls to `getHead`.
@@ -181,12 +197,14 @@ export interface IForkChoice {
    * ## Specification
    *
    * https://github.com/ethereum/consensus-specs/blob/v1.7.0-alpha.0/specs/gloas/fork-choice.md#new-notify_ptc_messages
-   *
-   * @param blockRoot - The beacon block root being attested
-   * @param ptcIndices - Array of PTC committee indices that voted
-   * @param payloadPresent - Whether validators attest the payload is present
    */
-  notifyPtcMessages(blockRoot: RootHex, ptcIndices: number[], payloadPresent: boolean): void;
+  notifyPtcMessages(
+    blockRoot: RootHex,
+    slot: Slot,
+    ptcIndices: number[],
+    payloadPresent: boolean,
+    blobDataAvailable: boolean
+  ): void;
   /**
    * Notify fork choice that an execution payload has arrived (Gloas fork)
    * Creates the FULL variant of a Gloas block when the payload becomes available
@@ -198,11 +216,13 @@ export interface IForkChoice {
    * @param blockRoot - The beacon block root for which the payload arrived
    * @param executionPayloadBlockHash - The block hash of the execution payload
    * @param executionPayloadNumber - The block number of the execution payload
+   * @param executionPayloadGasLimit - The gas limit of the execution payload
    */
   onExecutionPayload(
     blockRoot: RootHex,
     executionPayloadBlockHash: RootHex,
     executionPayloadNumber: number,
+    executionPayloadGasLimit: number,
     executionStatus: PayloadExecutionStatus,
     dataAvailabilityStatus: DataAvailabilityStatus
   ): void;
@@ -233,6 +253,15 @@ export interface IForkChoice {
   hasPayloadHexUnsafe(blockRoot: RootHex): boolean;
   getSlotsPresent(windowStart: number): 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): {
+    attesterCount: number;
+    payloadPresentCount: number;
+    dataAvailableCount: number;
+  } | null;
+  getPayloadTimelinessVotes(blockRootHex: RootHex): (boolean | null)[] | null;
+  getPayloadDataAvailabilityVotes(blockRootHex: RootHex): (boolean | null)[] | null;
+
   /**
    * Returns a `ProtoBlock` if the block is known **and** a descendant of the finalized root.
    */
@@ -242,6 +271,8 @@ export interface IForkChoice {
   getBlockHexDefaultStatus(blockRoot: RootHex): ProtoBlock | null;
   getBlockHexAndBlockHash(blockRoot: RootHex, blockHash: RootHex): ProtoBlock | null;
   shouldExtendPayload(blockRoot: RootHex): boolean;
+  /** Spec: should_build_on_full(store, head) */
+  shouldBuildOnFull(head: ProtoBlock, slot: Slot): boolean;
   getFinalizedBlock(): ProtoBlock;
   getJustifiedBlock(): ProtoBlock;
   getFinalizedCheckpointSlot(): Slot;

package/src/forkChoice/safeBlocks.ts

@@ -1,5 +1,6 @@
 import {ZERO_HASH_HEX} from "@lodestar/params";
 import {Root, RootHex} from "@lodestar/types";
+import {fromHex} from "@lodestar/utils";
 import {IForkChoice} from "./interface.js";
 
 /**
@@ -7,21 +8,28 @@ import {IForkChoice} from "./interface.js";
  * that is safe from re-orgs. Normally this block is pretty close to the head of canonical
  * chain which makes it valuable to expose a safe block to users.
  *
- * https://github.com/ethereum/consensus-specs/blob/v1.6.0/fork_choice/safe-block.md#get_safe_beacon_block_root
+ * @deprecated The merged fast-confirmation spec only defines `get_safe_execution_block_hash`.
  */
 export function getSafeBeaconBlockRoot(fc: IForkChoice): Root {
+  const confirmedRoot = fc.getConfirmedRoot();
+  if (confirmedRoot && fc.hasBlockHex(confirmedRoot)) {
+    return fromHex(confirmedRoot);
+  }
   return fc.getJustifiedCheckpoint().root;
 }
 
 /**
  * Get execution payload hash for the safe block
- * This function assumes that safe block is post Bellatrix and function should not be called otherwise.
  *
- * As our existing usage is aligned with above condition so not adding fork-check inside this function
- *
- *
- * https://github.com/ethereum/consensus-specs/blob/v1.6.0/fork_choice/safe-block.md#get_safe_execution_block_hash
+ * https://github.com/ethereum/consensus-specs/blob/master/fork_choice/safe-block.md#get_safe_execution_block_hash
  */
 export function getSafeExecutionBlockHash(forkChoice: IForkChoice): RootHex {
-  return forkChoice.getJustifiedBlock().executionPayloadBlockHash ?? ZERO_HASH_HEX;
+  const confirmedRoot = forkChoice.getConfirmedRoot();
+  if (confirmedRoot) {
+    const confirmedBlock = forkChoice.getBlockHexDefaultStatus(confirmedRoot);
+    if (confirmedBlock?.executionPayloadBlockHash) {
+      return confirmedBlock.executionPayloadBlockHash;
+    }
+  }
+  return ZERO_HASH_HEX;
 }

package/src/forkChoice/store.ts

@@ -1,6 +1,7 @@
 import {EffectiveBalanceIncrements, IBeaconStateView} from "@lodestar/state-transition";
 import {RootHex, Slot, ValidatorIndex, phase0} from "@lodestar/types";
 import {toRootHex} from "@lodestar/utils";
+import {ForkChoiceStateGetter, IFastConfirmationStore} from "./fastConfirmation/types.ts";
 import {CheckpointWithBalance, CheckpointWithTotalBalance} from "./interface.js";
 
 /**
@@ -35,7 +36,7 @@ export type JustifiedBalancesGetter = (
  * - The actual block DAG in `ProtoArray`.
  * - `time` is represented using `Slot` instead of UNIX epoch `u64`.
  */
-export interface IForkChoiceStore {
+export interface IForkChoiceStore extends IFastConfirmationStore {
   currentSlot: Slot;
   get justified(): CheckpointWithTotalBalance;
   set justified(justified: CheckpointWithBalance);
@@ -44,6 +45,7 @@ export interface IForkChoiceStore {
   unrealizedFinalizedCheckpoint: CheckpointWithHex;
   justifiedBalancesGetter: JustifiedBalancesGetter;
   equivocatingIndices: Set<ValidatorIndex>;
+  notifyFastConfirmation?(data: {block: RootHex; slot: Slot; currentSlot: Slot}): void;
 }
 
 /**
@@ -58,19 +60,36 @@ export class ForkChoiceStore implements IForkChoiceStore {
   justifiedBalancesGetter: JustifiedBalancesGetter;
   currentSlot: Slot;
 
+  // Fast Confirmation Rule spec fields
+  confirmedRoot: RootHex;
+  previousEpochObservedJustifiedCheckpoint: CheckpointWithHex;
+  currentEpochObservedJustifiedCheckpoint: CheckpointWithHex;
+  previousEpochGreatestUnrealizedCheckpoint: CheckpointWithHex;
+  previousSlotHead: RootHex;
+  currentSlotHead: RootHex;
+
+  // Fast Confirmation Rule internal fields
+  previousEpochObservedJustifiedBalances: JustifiedBalances;
+  currentEpochObservedJustifiedBalances: JustifiedBalances;
+  previousEpochGreatestUnrealizedBalances: JustifiedBalances;
+  stateGetter: ForkChoiceStateGetter;
+
   constructor(
     currentSlot: Slot,
     justifiedCheckpoint: phase0.Checkpoint,
     finalizedCheckpoint: phase0.Checkpoint,
     justifiedBalances: EffectiveBalanceIncrements,
     justifiedBalancesGetter: JustifiedBalancesGetter,
+    stateGetter: ForkChoiceStateGetter,
     private readonly events?: {
       onJustified: (cp: CheckpointWithHex) => void;
       onFinalized: (cp: CheckpointWithHex) => void;
+      onFastConfirmation?: (data: {block: RootHex; slot: Slot; currentSlot: Slot}) => void;
     }
   ) {
     this.justifiedBalancesGetter = justifiedBalancesGetter;
     this.currentSlot = currentSlot;
+    this.stateGetter = stateGetter;
     const justified = {
       checkpoint: toCheckpointWithHex(justifiedCheckpoint),
       balances: justifiedBalances,
@@ -80,6 +99,22 @@ export class ForkChoiceStore implements IForkChoiceStore {
     this.unrealizedJustified = justified;
     this._finalizedCheckpoint = toCheckpointWithHex(finalizedCheckpoint);
     this.unrealizedFinalizedCheckpoint = this._finalizedCheckpoint;
+
+    // Initialize Fast Confirmation fields conservatively from finalized, matching
+    // the spec's get_fast_confirmation_store() behavior.
+    const finalizedCheckpointWithHex = toCheckpointWithHex(finalizedCheckpoint);
+    const finalizedState = stateGetter({checkpoint: finalizedCheckpointWithHex});
+    const finalizedBalances = finalizedState?.effectiveBalanceIncrements ?? justifiedBalances;
+    const anchorRoot = finalizedCheckpointWithHex.rootHex;
+    this.previousEpochObservedJustifiedCheckpoint = finalizedCheckpointWithHex;
+    this.currentEpochObservedJustifiedCheckpoint = finalizedCheckpointWithHex;
+    this.previousEpochGreatestUnrealizedCheckpoint = finalizedCheckpointWithHex;
+    this.confirmedRoot = anchorRoot;
+    this.previousEpochObservedJustifiedBalances = finalizedBalances;
+    this.currentEpochObservedJustifiedBalances = finalizedBalances;
+    this.previousEpochGreatestUnrealizedBalances = finalizedBalances;
+    this.previousSlotHead = anchorRoot;
+    this.currentSlotHead = anchorRoot;
   }
 
   get justified(): CheckpointWithTotalBalance {
@@ -98,6 +133,15 @@ export class ForkChoiceStore implements IForkChoiceStore {
     this._finalizedCheckpoint = cp;
     this.events?.onFinalized(cp);
   }
+
+  /**
+   * Notify subscribers that the Fast Confirmation Rule executed and produced
+   * `data.block` at `data.slot`. Fires once per FCR execution, even when
+   * `confirmedRoot` did not change from the prior slot.
+   */
+  notifyFastConfirmation(data: {block: RootHex; slot: Slot; currentSlot: Slot}): void {
+    this.events?.onFastConfirmation?.(data);
+  }
 }
 
 export function toCheckpointWithHex(checkpoint: phase0.Checkpoint): CheckpointWithHex {

package/src/index.ts

@@ -6,6 +6,17 @@ export {
   type InvalidBlock,
   InvalidBlockCode,
 } from "./forkChoice/errors.js";
+export {
+  type FastConfirmationBalanceSource,
+  type FastConfirmationContext,
+  type FastConfirmationMetrics,
+  type FastConfirmationResult,
+  FastConfirmationRule,
+  type ForkChoiceStateGetter,
+  type IFastConfirmationRule,
+  type IFastConfirmationStore,
+  getFastConfirmationMetrics,
+} from "./forkChoice/fastConfirmation/fastConfirmationRule.ts";
 export {ForkChoice, type ForkChoiceOpts, UpdateHeadOpt} from "./forkChoice/forkChoice.js";
 export {
   type AncestorResult,

package/src/metrics.ts

@@ -1,11 +1,13 @@
 import {MetricsRegisterExtra} from "@lodestar/utils";
+import {FastConfirmationMetrics, getFastConfirmationMetrics} from "./forkChoice/fastConfirmation/metrics.ts";
 import {UpdateHeadOpt} from "./forkChoice/forkChoice.js";
 import {NotReorgedReason} from "./forkChoice/interface.js";
 
-export type ForkChoiceMetrics = ReturnType<typeof getForkChoiceMetrics>;
+export type ForkChoiceMetrics = ReturnType<typeof getForkChoiceMetrics> & FastConfirmationMetrics;
 
 export function getForkChoiceMetrics(register: MetricsRegisterExtra) {
   return {
+    ...getFastConfirmationMetrics(register),
     forkChoice: {
       findHead: register.histogram<{caller: string}>({
         name: "beacon_fork_choice_find_head_seconds",

package/src/protoArray/interface.ts

@@ -87,6 +87,14 @@ export type BlockExtraMeta =
       //   - payload block hash for FULL variant
       executionPayloadBlockHash: RootHex;
       executionPayloadNumber: UintNum64;
+      // Gas limit of the executed payload identified by executionPayloadBlockHash. Set on
+      // pre-Gloas blocks (from block.body.executionPayload.gasLimit) and on Gloas variants:
+      //   - PENDING/EMPTY: inherited from the parent payload that the bid commits to extend
+      //     (matches executionPayloadBlockHash, which also points to that parent payload)
+      //   - FULL: the actual delivered payload's gasLimit (set in onExecutionPayload)
+      // Consumers (e.g. Gloas bid gas-limit validation) can read this without re-deriving from
+      // state.
+      executionPayloadGasLimit: UintNum64;
       executionStatus: Exclude<ExecutionStatus, ExecutionStatus.PreMerge>;
       dataAvailabilityStatus: DataAvailabilityStatus;
     }