Limit VDF Run-Ahead via Seed-Confirmation Gate — Design Plan

Mode: Bug
Clarity Score: 0.96 (Goal: 0.97, Constraints: 0.95, Scope: 0.97)
Date: 2026-06-15
Issue: #1447 — "Limit VDF run ahead to avoid seed poisoning"
Scope: Prevention only. Recovery / self-heal is explicitly out of scope.

Root Cause

The VDF mining loop (crates/vdf/src/vdf.rs run_vdf) samples the reset seed for an
upcoming reset boundary from the canonical chain tip's next_seed field
(vdf.rs:157-158) and applies it when the local step crosses that boundary
(process_reset, vdf.rs:248-274). A gate (vdf.rs:172-173) is meant to keep the
node from crossing a boundary before the seed is pinned:

let is_too_far_ahead = (global_step_number + 1).is_multiple_of(vdf_reset_frequency)
    && global_step_number + 1 > canonical_global_step_number + vdf_reset_frequency;

This opens the gate the instant the canonical tip reaches B − reset_frequency — that
is, the instant the rotation block that pins boundary B's seed becomes the tip, at
zero confirmations. A node whose VDF runs a full window ahead therefore consumes
the seed from a brand-new block. If that block then loses a fork (as happened to
testnet peer-4: a same-height, ~1-second fork where the loser had rotated and the
winner had not), the node mixes a non-canonical reset seed into every subsequent step.
The VDF state has no reorg reconciliation, so the divergent steps persist and the node
wedges (recall-range validation, which replays the local VDF buffer, then rejects the
genuinely-valid canonical block).

The seed-pinning design is intended to be fork-safe by pinning one window early, but
the safety margin is reset_frequency − vdf_lead. A node hugging the run-ahead cap has
a margin of ~0: the same event opens the gate and supplies the seed. See the issue and
the conversation log for the full verified chain of evidence.

Fix Approach

Replace the zero-confirmation boundary condition with a confirmation-depth gate: a
node may cross reset boundary B only once the rotation block that pinned B's seed is
at least block_migration_depth blocks deep on the canonical chain (i.e. confirmed /
migrated — note this is the codebase's "confirmed" marker, weaker than "finalized",
which is the deeper prune/block_tree_depth boundary; see forkchoice_markers.rs:38-41).
The depth is measured in blocks, not VDF steps, so it is immune to a
stall followed by a single large catch-up block (a step-denominated margin can be
satisfied by one block and degrade to a single confirmation).

Mechanism — the reset seed changes only at rotation blocks, and run_vdf reads the tip
every iteration, so the loop can track confirmation depth in O(1):

1. Extend BlockProvider to return the canonical tip's block height alongside its
   VDFLimiterInfo, taken from the same tip snapshot (so seed and height are
   consistent).
2. In run_vdf, track (last_next_seed, seed_pin_height): whenever the observed
   next_seed changes value, record seed_pin_height = current tip height. The
   confirmation depth of the active seed is tip_height − seed_pin_height.
3. Gate: extend the existing boundary condition with the confirmation check — keep
   the readiness check, do not replace it:
   is_too_far_ahead = is_boundary && ( next_step > canonical_gsn + reset_frequency || seed_confirmations < K ),
   where K = block_migration_depth. The first disjunct is the retained readiness
   guard: next_seed is carried forward unchanged between rotation blocks
   (block.rs:150-169 calculate_seeds), so a node more than one window ahead would
   otherwise re-apply the previous period's seed — confirmation depth alone cannot
   replace readiness. The second disjunct is the new confirmation guard: the pinned
   seed's rotation block must be K blocks deep.
4. Startup: do not assume the startup seed is already confirmed. initial_reset_seed
   is the live tip's next_seed (chain.rs:2161), not a verified-deep historical seed, so
   exempting it could let a restarted node consume a fresh seed. Track
   last_observed_seed: Option<H256> (initially None) and seed_pin_height: u64. On the
   first provider read — and every later next_seed transition — set
   seed_pin_height = current tip height, treating the seed as freshly pinned. This
   conservatively ages the startup seed by K blocks (a node restarting within one window
   of a boundary may park ≤ K blocks at that first boundary — safe, minor). No
   initial-tip-height parameter is needed and a live tip is never assumed pre-confirmed.

K is sourced from the existing ConsensusConfig::block_migration_depth (value 6 on
all networks) — no new tunable config field is introduced. It is threaded into
run_vdf as a parameter from the single call site, which has the full Config.

The gate predicate is extracted into a pure function so it can be proptested in
isolation, mirroring the existing process_reset + process_reset_props pattern.

Effect (verified)

• Seed safety: at any boundary the rotation block is ≥ block_migration_depth deep
  → the entire ≤6-block fork class is closed, including peer-4's 1-block fork (6×
  margin).
• Run-ahead / liveness: max boundary run-ahead drops from reset_frequency to
  reset_frequency − K × steps_per_block. Mainnet: 600 → ~528 steps (~9 min). Testnet:
  1200 → ~1140 steps (~19 min). Ample headroom remains for low-hashpower bring-up.
• Determinism: the gate changes only when a step is computed, never a step's
  value. VDF output is unchanged, so there is no consensus-value divergence risk.

Residual (out of scope)

A seed becomes truly irreversible only at finalization (the prune boundary,
block_tree_depth behind the head); the block_migration_depth marker this gate uses is
the weaker confirmed marker (forkchoice_markers.rs:38-41). So a confirmed but not
yet finalized seed source — a rotation block between block_migration_depth and
block_tree_depth deep — can still be reversed by a partition-recovery reorg:
block_status_provider.rs:124-131 classifies such a competing indexed-height block as
still processable, and the recovery is driven through the block-tree service and exercised
end-to-end by crates/chain-tests/src/multi_node/partition_recovery.rs. On mainnet this
tail is structurally unavoidable within one window (window 50 blocks < finalization depth
block_tree_depth 100 — verified). The startup seed is conservatively aged (not exempted),
so it is held to the same K-block standard. Closing this tail requires recovery
(reorg-triggered VDF buffer reconciliation), which is explicitly out of scope for this fix.

Amended (Codex design review): corrected the "finalized" vs "confirmed" terminology
(migration_depth is confirmed, block_tree_depth/prune is finalized), and pointed
the deep-reorg residual at the block-tree partition-recovery path rather than at
BlockStatusProvider (which only classifies). The startup-init step was also reworked to
exempt only the persisted disk seed via a None sentinel — never assuming a live tip is
pre-confirmed — and to avoid needing an initial-tip-height parameter.

Files Affected

• crates/types/src/block_provider.rs — extend the BlockProvider trait: change
  latest_canonical_vdf_info to return a small struct carrying both the
  VDFLimiterInfo and the tip block height (new CanonicalVdfSnapshot).
• crates/p2p/src/block_status_provider.rs:488-495 — update the impl to return
  block.height alongside vdf_limiter_info from the same canonical-tip read.
• crates/vdf/src/vdf.rs — update the two provider call sites (~109, ~157); add
  seed-confirmation tracking + startup init; replace the gate's second condition
  (172-173) with the confirmation-depth check; extract a pure gate predicate; thread
  K into run_vdf; update MockBlockProvider and make it configurable for tests.
• crates/chain/src/chain.rs:2217-2230 — pass config.consensus.block_migration_depth
  into run_vdf.
• crates/vdf/src/vdf.rs (tests) — proptest the pure gate predicate; add a peer-4
  regression test (fresh seed at a boundary parks the loop until the source is K-deep);
  update existing loop tests for the new mock signature.
• crates/chain-tests/src/multi_node/ (tests) — add an end-to-end regression using the
  existing fork/partition-recovery harnesses (fork_recovery.rs, partition_recovery.rs,
  partition_recovery_epoch_boundary.rs, vdf_validation_progress.rs): force competing
  forks around a reset boundary, reorg to the winner, and assert the node that observed the
  loser does not wedge — it keeps validating and applying later canonical blocks (no
  recall-range poisoning). This covers the real failure path, which VDF-unit tests cannot.

Amended (Codex design review): added the chain-tests end-to-end regression. The bug
manifests through block validation replaying local VDF history across a fork, so pure
irys-vdf tests prove the gate predicate but not that the node survives the real reorg
path; the repo already has the multi-node harnesses to exercise it.

Risk Assessment

• Consensus-critical hot path. The change is in the VDF stepping loop. Mitigation:
  it only gates timing, not step values; determinism is preserved. The run-ahead
  reduction is small and quantified.
• Startup parking. A bad startup initialisation could stall the first boundary
  crossing for up to a window. Mitigation: startup seed treated as K-confirmed
  (justified — startup tip is canonical).
• Provider return-type change. Touches five sites (trait, two run_vdf calls, mock,
  real impl). All updated in the same change; the compiler enforces completeness.
• Bring-up liveness. Reduced run-ahead could in principle slow low-hashpower
  bring-up. Mitigation: headroom remains 9–19 min; the reduction is ~6 blocks.
• Rollback: revert the gate to the previous single condition and revert the provider
  signature — a clean single-commit revert. No state migration, no persisted format
  change.

Verification

Acceptance criteria:

1. Pure predicate (proptest): the gate reports "too far ahead" iff the next step is a
   reset boundary and seed_confirmations < block_migration_depth; never panics.
2. Regression (peer-4): with a provider reporting a freshly-pinned seed (depth 0) at a
   reset boundary, the VDF loop does not advance past the boundary; after the provider's
   tip height advances by K (same seed), the loop crosses.
3. No spurious startup park: a loop started against a settled tip crosses its first
   boundary without waiting K blocks.
4. Existing VDF tests pass with the updated mock (including
   test_vdf_does_not_get_too_far_ahead, adjusted for the new semantics).
5. End-to-end reorg regression (chain-tests): a multi-node test creates competing
   forks around a reset boundary; after the network reorgs to the winner, the node that
   observed the loser does not wedge — it continues to validate and apply subsequent
   canonical blocks (no recall-range poisoning). Exercises the real failure path.
6. cargo fmt --all, cargo clippy --workspace --tests --all-targets,
   cargo nextest run -p irys-vdf and the new chain-tests regression all clean.

External Review (Codex — Design)

Date: 2026-06-15
Findings: 3 (1 High, 2 Medium)
Accepted: 3
Rejected: 0

Codex validated the core shape: run_vdf is the right place for the gate, BlockProvider
is the right abstraction boundary, and reusing ConsensusConfig::block_migration_depth
matches existing configuration patterns.

Amendments Made

• Fix Approach, startup (High): reworked the startup initialisation. The original
  "treat the live tip seed as confirmed" shortcut was unsound — a migrated block can be
  rolled back by partition recovery, and run_vdf has no initial tip height. Now only the
  persisted initial_reset_seed is exempt (via a None sentinel); the first live seed
  transition begins K-block ageing. Verified: vdf.rs:56 has no tip-height param;
  block_status_provider.rs:124-131 confirms migrated blocks remain reorg-able.
• Residual (Medium): corrected "finalized" → "confirmed" for block_migration_depth
  and pointed the deep-reorg residual at the block-tree partition-recovery path. Verified:
  forkchoice_markers.rs:38-41 (migration_block = confirmed, prune_block = finalized).
• Files Affected / Verification (Medium): added an end-to-end chain-tests reorg
  regression. Verified the harnesses exist: crates/chain-tests/src/multi_node/fork_recovery.rs
  (1899 lines), partition_recovery.rs, partition_recovery_epoch_boundary.rs,
  vdf_validation_progress.rs.

Rejected Findings

• None.

External Review (Codex — Implementation, design-level corrections)

The Phase-7 implementation-plan review surfaced two issues that also corrected this design
(full details in the implementation plan's review section):

• Gate logic (Critical): the "Fix Approach" originally replaced the readiness check
  with confirmation depth. Corrected to keep readiness and add confirmation — next_seed
  is carried forward unchanged between rotations (block.rs:150-169), so a node >1 window
  ahead would otherwise re-apply a stale seed. (Fix Approach step 3 amended.)
• Startup (High): the startup exemption assumed initial_reset_seed was a deep
  historical seed, but it is the live tip's next_seed (chain.rs:2161). Corrected to
  conservatively age the startup seed rather than exempt it. (Fix Approach step 4 amended.)

sequenceDiagram
  rect rgba(100, 180, 255, 0.5)
    Note over run_vdf,BlockTree: Snapshot refresh on each VDF step
  end
  participant run_vdf
  participant BlockStatusProvider
  participant BlockTree

  run_vdf->>BlockStatusProvider: latest_canonical_vdf_info()
  BlockStatusProvider->>BlockTree: get latest canonical entry header → vdf_limiter_info
  BlockStatusProvider->>BlockTree: confirmed_canonical_step(block_migration_depth)
  BlockTree-->>BlockStatusProvider: confirmed_global_step_number (skips non-Onchain tail)
  BlockStatusProvider-->>run_vdf: CanonicalVdfSnapshot { vdf_info, confirmed_global_step_number }
  run_vdf->>run_vdf: compute confirmation_lag = canonical_gsn - confirmed_gsn
  run_vdf->>run_vdf: select gate_step (canonical or confirmed)

  rect rgba(255, 160, 80, 0.5)
    Note over run_vdf,is_reset_boundary_blocked: At each candidate reset boundary
  end
  run_vdf->>is_reset_boundary_blocked: (next_global_step, reset_frequency, confirmed_gsn)
  alt blocked = true
    is_reset_boundary_blocked-->>run_vdf: park / sleep
  else blocked = false
    is_reset_boundary_blocked-->>run_vdf: advance past boundary
  end

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

Benchmark results: https://irys-xyz.github.io/irys/dev/bench/jason%2Fvdf_run_ahead/index.html

@CodeRabbit full review

@CodeRabbit full review