@lodestar/fork-choice 1.44.0-dev.7418ddd9f7 → 1.44.0-dev.762dd5f186

package/src/forkChoice/fastConfirmation/rules.ts

@@ -0,0 +1,151 @@
+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,
+  isResetReason,
+} 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,
+  };
+
+  const reasonTrail: FastConfirmationDecisionReason[] = [];
+  for (const rule of FAST_CONFIRMATION_RULES) {
+    const previousDecision = decision;
+    decision = rule(snapshot, ctx, store, cache, decision, logger);
+    if (decision !== previousDecision && decision.reason !== FastConfirmationDecisionReason.Unchanged) {
+      reasonTrail.push(decision.reason);
+    }
+  }
+  logger?.debug("Fast confirmation rule outcomes", {reasonTrail: reasonTrail.join(",")});
+
+  // 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,
+    // Reset cause: the first reset-classified reason in the trail (only when an actual reset occurred).
+    resetReason: decision.didReset ? reasonTrail.find(isResetReason) : undefined,
+    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: reasonTrail.includes(FastConfirmationDecisionReason.ObservedJustified),
+  };
+}

package/src/forkChoice/fastConfirmation/types.ts

@@ -0,0 +1,137 @@
+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",
+}
+
+/** Reasons where the confirmed root is pulled backward (a reset), as opposed to advanced forward. */
+const RESET_REASONS = new Set<FastConfirmationDecisionReason>([
+  FastConfirmationDecisionReason.ConfirmedNotFound,
+  FastConfirmationDecisionReason.ResetBehind,
+  FastConfirmationDecisionReason.ResetNotAncestor,
+  FastConfirmationDecisionReason.ResetChainUnsafe,
+]);
+
+export function isResetReason(reason: FastConfirmationDecisionReason): boolean {
+  return RESET_REASONS.has(reason);
+}
+
+export type FastConfirmationDecision = {
+  confirmedRoot: RootHex;
+  didReset: boolean;
+  reason: FastConfirmationDecisionReason;
+};
+
+export type FastConfirmationRunResult = FastConfirmationDecision & {
+  /**
+   * Cause of the reset, when one occurred.
+   * The `reason` attribute reports the final disposition and can be different.
+   */
+  resetReason?: FastConfirmationDecisionReason;
+  /** 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;
+}