@lodestar/fork-choice 1.44.0-dev.847e824a6a → 1.44.0-dev.848b01419b

package/src/forkChoice/fastConfirmation/index.ts

@@ -0,0 +1,3 @@
+export * from "./fastConfirmationRule.ts";
+export * from "./metrics.ts";
+export * from "./types.ts";

package/src/forkChoice/fastConfirmation/metrics.ts

@@ -0,0 +1,57 @@
+import {MetricsRegisterExtra} from "@lodestar/utils";
+
+export type FastConfirmationMetrics = ReturnType<typeof getFastConfirmationMetrics>;
+
+export enum FastConfirmationSteps {
+  updateHead = "updateHead",
+  buildCache = "buildCache",
+  buildSnapshot = "buildSnapshot",
+  runRules = "runRules",
+}
+
+export function getFastConfirmationMetrics(register: MetricsRegisterExtra) {
+  return {
+    fastConfirmation: {
+      totalDuration: register.histogram({
+        name: "lodestar_fast_confirmation_duration_seconds",
+        help: "Time to run Fast Confirmation Rule algorithm",
+        buckets: [0.001, 0.005, 0.01, 0.05, 0.1, 0.5, 1, 2],
+      }),
+      stepsDuration: register.histogram<{step: FastConfirmationSteps}>({
+        name: "lodestar_fast_confirmation_steps_duration_seconds",
+        help: "Time to run Fast Confirmation Steps",
+        buckets: [0.001, 0.005, 0.01, 0.05, 0.1, 0.5, 1, 2],
+        labelNames: ["step"],
+      }),
+      confirmedEpoch: register.gauge({
+        name: "lodestar_fast_confirmation_confirmed_epoch",
+        help: "Current confirmed epoch from fast confirmation",
+      }),
+      votesTracked: register.gauge({
+        name: "lodestar_fast_confirmation_votes_tracked",
+        help: "Number of checkpoint votes tracked by fast confirmation",
+      }),
+      resets: register.counter({
+        name: "lodestar_fast_confirmation_resets_total",
+        help: "Total number of fast confirmation resets (any cause)",
+      }),
+      // Standardized Fast Confirmation metrics
+      slot: register.gauge({
+        name: "beacon_fast_confirmation_slot",
+        help: "Slot of the most recent confirmed block",
+      }),
+      reorgs: register.counter({
+        name: "beacon_fast_confirmation_reorgs_total",
+        help: "Total number of confirmed block reorganizations",
+      }),
+      fallbacks: register.counter({
+        name: "beacon_fast_confirmation_fallbacks_total",
+        help: "Total number of fallbacks to finality",
+      }),
+      restarts: register.counter({
+        name: "beacon_fast_confirmation_restarts_total",
+        help: "Total number of restarts from a safe unrealized justified block",
+      }),
+    },
+  };
+}

package/src/forkChoice/fastConfirmation/rules.ts

@@ -0,0 +1,146 @@
+import {computeEpochAtSlot, isStartSlotOfEpoch} from "@lodestar/state-transition";
+import {Logger} from "@lodestar/utils";
+import {equalCheckpointWithHex} from "../store.ts";
+import {
+  FastConfirmationCache,
+  FastConfirmationContext,
+  FastConfirmationDecision,
+  FastConfirmationDecisionReason,
+  FastConfirmationRule,
+  FastConfirmationRunResult,
+  FastConfirmationSnapshot,
+  IFastConfirmationStore,
+} from "./types.ts";
+import {findLatestConfirmedDescendant, getBlock, isAncestor, isConfirmedChainSafe} from "./utils.ts";
+
+export const resetIfConfirmedUnavailable: FastConfirmationRule = (snapshot, ctx, _store, cache, decision) => {
+  const confirmedBlock = getBlock(ctx, cache, decision.confirmedRoot);
+  if (!confirmedBlock) {
+    return {
+      confirmedRoot: snapshot.finalizedRoot,
+      didReset: true,
+      reason: FastConfirmationDecisionReason.ConfirmedNotFound,
+    };
+  }
+  return decision;
+};
+
+export const resetIfBehindOrNotAncestorOrUnsafe: FastConfirmationRule = (
+  snapshot,
+  ctx,
+  store,
+  cache,
+  decision,
+  logger
+) => {
+  const confirmedBlock = getBlock(ctx, cache, decision.confirmedRoot);
+  if (!confirmedBlock) return decision;
+  const confirmedEpoch = computeEpochAtSlot(confirmedBlock.slot);
+
+  const confirmedEpochBehindHead = confirmedEpoch + 1 < snapshot.currentEpoch;
+  const notAncestorOfHead = !isAncestor(ctx, cache, snapshot.headRoot, decision.confirmedRoot);
+  const allChildrenNotConfirmed =
+    isStartSlotOfEpoch(snapshot.currentSlot) &&
+    !isConfirmedChainSafe(ctx, store, cache, decision.confirmedRoot, logger);
+
+  if (confirmedEpochBehindHead || notAncestorOfHead || allChildrenNotConfirmed) {
+    const didReset = decision.didReset || decision.confirmedRoot !== snapshot.finalizedRoot;
+    const reason = confirmedEpochBehindHead
+      ? FastConfirmationDecisionReason.ResetBehind
+      : notAncestorOfHead
+        ? FastConfirmationDecisionReason.ResetNotAncestor
+        : FastConfirmationDecisionReason.ResetChainUnsafe;
+    return {confirmedRoot: snapshot.finalizedRoot, didReset, reason};
+  }
+  return decision;
+};
+
+export const advanceIfObservedJustified: FastConfirmationRule = (snapshot, ctx, store, cache, decision) => {
+  if (!isStartSlotOfEpoch(snapshot.currentSlot)) return decision;
+  if (store.currentEpochObservedJustifiedCheckpoint.epoch + 1 !== snapshot.currentEpoch) return decision;
+  if (!snapshot.headUnrealized) return decision;
+  if (!equalCheckpointWithHex(store.currentEpochObservedJustifiedCheckpoint, snapshot.headUnrealized)) return decision;
+  const observedBlock = getBlock(ctx, cache, store.currentEpochObservedJustifiedCheckpoint.rootHex);
+  if (!observedBlock || computeEpochAtSlot(observedBlock.slot) + 1 < snapshot.currentEpoch) return decision;
+
+  const confirmedSlot = getBlock(ctx, cache, decision.confirmedRoot)?.slot ?? null;
+  const observedSlot = observedBlock.slot;
+  if (confirmedSlot !== null && observedSlot !== null && confirmedSlot < observedSlot) {
+    return {
+      ...decision,
+      confirmedRoot: store.currentEpochObservedJustifiedCheckpoint.rootHex,
+      reason: FastConfirmationDecisionReason.ObservedJustified,
+    };
+  }
+  return decision;
+};
+
+export const advanceToLatestConfirmedDescendant: FastConfirmationRule = (
+  snapshot,
+  ctx,
+  store,
+  cache,
+  decision,
+  logger
+) => {
+  const confirmedBlock = getBlock(ctx, cache, decision.confirmedRoot);
+  const confirmedEpoch = confirmedBlock ? computeEpochAtSlot(confirmedBlock.slot) : null;
+  if (confirmedEpoch !== null && confirmedEpoch + 1 >= snapshot.currentEpoch) {
+    const newConfirmed = findLatestConfirmedDescendant(snapshot, ctx, store, cache, decision.confirmedRoot, logger);
+    return {
+      ...decision,
+      confirmedRoot: newConfirmed,
+      reason: FastConfirmationDecisionReason.ConfirmedDescendant,
+    };
+  }
+  return decision;
+};
+
+export const FAST_CONFIRMATION_RULES: FastConfirmationRule[] = [
+  resetIfConfirmedUnavailable,
+  resetIfBehindOrNotAncestorOrUnsafe,
+  advanceIfObservedJustified,
+  advanceToLatestConfirmedDescendant,
+];
+
+// Spec mapping: this rule runner implements the `get_latest_confirmed` decision flow
+// over Lodestar's snapshot/store/cache abstractions.
+export function runFastConfirmationRules(
+  snapshot: FastConfirmationSnapshot,
+  ctx: FastConfirmationContext,
+  store: IFastConfirmationStore,
+  cache: FastConfirmationCache,
+  logger?: Logger
+): FastConfirmationRunResult {
+  let decision: FastConfirmationDecision = {
+    confirmedRoot: snapshot.confirmedRoot,
+    didReset: false,
+    reason: FastConfirmationDecisionReason.Unchanged,
+  };
+
+  // Track every reason a rule decided on, the final `decision.reason` is overwritten by
+  // later rules (eg. a restart is followed by advancing to the latest confirmed descendant)
+  const reasons = new Set<FastConfirmationDecisionReason>();
+  for (const rule of FAST_CONFIRMATION_RULES) {
+    decision = rule(snapshot, ctx, store, cache, decision, logger);
+    reasons.add(decision.reason);
+  }
+
+  // Detect a reorg directly from ancestry instead of the reset reason: when the confirmed block is
+  // both epoch-behind and not an ancestor of head, `resetIfBehindOrNotAncestorOrUnsafe` records
+  // `ResetBehind` (it takes precedence), so keying off `ResetNotAncestor` alone would miss reorgs
+  // that cross an epoch boundary.
+  const initialConfirmedBlock = getBlock(ctx, cache, snapshot.confirmedRoot);
+  const didReorg = initialConfirmedBlock !== null && !isAncestor(ctx, cache, snapshot.headRoot, snapshot.confirmedRoot);
+
+  return {
+    confirmedRoot: decision.confirmedRoot,
+    didReset: decision.didReset,
+    reason: decision.reason,
+    didReorg,
+    // A fallback is a revert to finality: a reset whose final confirmed root is the finalized
+    // checkpoint. A later rule may advance the confirmed root forward, which is not a fallback.
+    didFallback: decision.didReset && decision.confirmedRoot === snapshot.finalizedRoot,
+    didRestart: reasons.has(FastConfirmationDecisionReason.ObservedJustified),
+  };
+}

package/src/forkChoice/fastConfirmation/types.ts

@@ -0,0 +1,120 @@
+import {EffectiveBalanceIncrements, IBeaconStateView} from "@lodestar/state-transition";
+import {Epoch, RootHex, Slot, ValidatorIndex} from "@lodestar/types";
+import {Logger} from "@lodestar/utils";
+import {ProtoBlock} from "../../protoArray/interface.ts";
+import {CheckpointWithHex} from "../store.ts";
+
+export type FastConfirmationBalanceSource = {
+  state: IBeaconStateView | null;
+  balances: EffectiveBalanceIncrements;
+};
+
+export type ForkChoiceStateGetter = (
+  opts: {stateRoot: RootHex; checkpoint?: never} | {stateRoot?: never; checkpoint: CheckpointWithHex}
+) => IBeaconStateView | null;
+
+type IFastConfirmationSpecStore = {
+  confirmedRoot: RootHex;
+  previousEpochObservedJustifiedCheckpoint: CheckpointWithHex;
+  currentEpochObservedJustifiedCheckpoint: CheckpointWithHex;
+  previousEpochGreatestUnrealizedCheckpoint: CheckpointWithHex;
+  previousSlotHead: RootHex;
+  currentSlotHead: RootHex;
+};
+
+type IFastConfirmationAuxStore = {
+  previousEpochObservedJustifiedBalances: EffectiveBalanceIncrements;
+  currentEpochObservedJustifiedBalances: EffectiveBalanceIncrements;
+  previousEpochGreatestUnrealizedBalances: EffectiveBalanceIncrements;
+  stateGetter: ForkChoiceStateGetter;
+};
+
+export type IFastConfirmationStore = IFastConfirmationSpecStore & IFastConfirmationAuxStore;
+
+export type FastConfirmationResult = {
+  confirmedRoot: RootHex;
+  didReset?: boolean;
+};
+
+export type FastConfirmationSnapshot = {
+  currentSlot: Slot;
+  currentEpoch: Epoch;
+  headRoot: RootHex;
+  confirmedRoot: RootHex;
+  confirmedEpoch: Epoch | null;
+  confirmedSlot: Slot | null;
+  observedJustified: CheckpointWithHex;
+  headUnrealized: CheckpointWithHex | null;
+  finalizedRoot: RootHex;
+};
+
+export enum FastConfirmationDecisionReason {
+  Unchanged = "unchanged",
+  ConfirmedNotFound = "confirmed_not_found",
+  ResetBehind = "reset_behind",
+  ResetNotAncestor = "reset_not_ancestor",
+  ResetChainUnsafe = "reset_chain_unsafe",
+  ObservedJustified = "observed_justified",
+  ConfirmedDescendant = "confirmed_descendant",
+}
+
+export type FastConfirmationDecision = {
+  confirmedRoot: RootHex;
+  didReset: boolean;
+  reason: FastConfirmationDecisionReason;
+};
+
+export type FastConfirmationRunResult = FastConfirmationDecision & {
+  /** Confirmed block became non-canonical (no longer an ancestor of head) */
+  didReorg: boolean;
+  /** Confirmed block reverted to the finalized checkpoint */
+  didFallback: boolean;
+  /** Restarted confirmation from the observed unrealized justified checkpoint */
+  didRestart: boolean;
+};
+
+export type FastConfirmationRule = (
+  snapshot: FastConfirmationSnapshot,
+  ctx: FastConfirmationContext,
+  store: IFastConfirmationStore,
+  cache: FastConfirmationCache,
+  decision: FastConfirmationDecision,
+  logger?: Logger
+) => FastConfirmationDecision;
+
+export type BalanceSourceKey = "current" | "previous";
+
+// This cache is created once per slot
+export type FastConfirmationCache = {
+  blockByRoot: Map<RootHex, ProtoBlock | null>;
+  ancestorRoots: Map<string, RootHex[] | null>;
+  committeeBySlot: Map<Slot, Set<ValidatorIndex>>;
+  isDescendantByRootPair: Map<string, boolean>;
+  /** voteRoot -> totalWeight, keyed by sourceKey */
+  voteWeightBySource: Map<BalanceSourceKey, Map<RootHex, number>>;
+  headState?: IBeaconStateView;
+  pulledUpHeadState?: IBeaconStateView;
+  checkpointStateByKey: Map<string, IBeaconStateView | null>;
+};
+
+export type FastConfirmationContext = {
+  config: {
+    CONFIRMATION_BYZANTINE_THRESHOLD: number;
+    PROPOSER_SCORE_BOOST: number;
+  };
+  getCurrentSlot(): Slot;
+  getHead(): ProtoBlock;
+  getBlock(root: RootHex): ProtoBlock | null;
+  getAncestor(root: RootHex, slot: Slot): RootHex;
+  isDescendant(ancestor: RootHex, descendant: RootHex): boolean;
+  getLatestMessage(validatorIndex: ValidatorIndex): {root: RootHex; epoch: Epoch} | null;
+  getUnrealizedJustified(): {checkpoint: CheckpointWithHex; balances: EffectiveBalanceIncrements};
+  getFinalizedCheckpoint(): CheckpointWithHex;
+  getEquivocatingIndices(): Set<ValidatorIndex>;
+  getTrackedVotesCount(): number;
+};
+
+export interface IFastConfirmationRule {
+  getConfirmedRoot(): RootHex;
+  onSlotStartAfterPastAttestationsApplied(ctx: FastConfirmationContext): FastConfirmationResult;
+}