plamentsv/fork-choice-audit

Injectable Skill: Fork Choice Audit

L1 trigger: L1_PATTERN=true AND (fork_choice/ OR ghost/ OR lmd/ OR consensus/tendermint/ OR fork.rs OR choice.rs detected in recon subsystem map) Inject Into: depth-consensus-invariant Language: Go and Rust Finding prefix: [FC-N] Status: v0.1 draft, Round 4 exemplars pending

Orchestrator Decomposition Guide

• Section 1, 2: depth-consensus-invariant (rule correctness)
• Section 3: depth-edge-case (equivocation + duplicate handling)
• Section 4: depth-state-trace (reorg state consistency)

When This Skill Activates

Recon identifies a fork-choice module. This skill applies whether the protocol uses LMD-GHOST (Ethereum beacon chain), longest-chain (Bitcoin, pre-merge Ethereum), Tendermint locking (Cosmos), or a custom fork-choice rule.

1. Identify the Rule

Before auditing, determine which rule is implemented. Extract from spec docs and code:

| Rule | Signature | Key invariants | |---|---|---| | LMD-GHOST | "latest message driven — greedy heaviest observed subtree" | Each validator's latest attestation contributes to a subtree weight; choose heaviest | | Casper FFG + LMD-GHOST (Ethereum) | LMD-GHOST bounded by finalized checkpoints | Never revert past justified/finalized checkpoint | | Tendermint BFT | Round-based, locking on 2/3+ prevotes | Locked validator cannot vote for conflicting proposal in same round | | Nakamoto longest-chain | Heaviest accumulated work | Chain with most work wins; stale blocks discarded | | HotStuff / Aptos / Sui | 3-phase: prepare, precommit, commit | No two conflicting QCs at the same view |

Write the identified rule into the finding header so reviewers know which invariants apply.

2. Rule-Specific Invariants

2a. LMD-GHOST

• Heaviest subtree monotonicity: adding an attestation can only increase (never decrease) the subtree weight
• Latest-message tie-break: if two children have equal weight, tie-break is deterministic (typically lower root hash)
• Boundary with finality: fork choice never selects a block that would require reverting a finalized block
• Slot vs block: a slot can have zero, one, or multiple proposed blocks; fork choice must handle the missing-block case

Check: Enumerate every call site of find_head() / get_head(). For each, verify the return value is bounded by the latest finalized checkpoint.

2b. Tendermint BFT locking

• Lock only on 2/3+ prevotes: validator cannot lock without proof of 2/3 prevotes
• Lock carries across rounds: once locked in round R, validator votes locked block in rounds R+1, R+2, ... unless unlocked by a newer 2/3+ prevote
• Unlock on newer PoLC (Proof-of-Lock-Change): only unlock if a strictly newer round's 2/3+ prevotes are seen
• No equivocation across rounds: locked validator cannot vote for conflicting block in later round of same height

Check: Follow the lock_value, lock_round, valid_value, valid_round state variables. Verify every set_lock call is guarded by the 2/3 check.

2c. Nakamoto longest-chain

• Cumulative difficulty, not length: chain selection uses total work, not block count
• Stale block eviction: blocks building on non-canonical ancestors are discarded cleanly
• Reorg depth bound: some clients impose a max reorg depth (e.g., 64 blocks); verify the bound is documented and enforced

3. Equivocation and Duplicate Block Handling

Equivocation = a validator signing two conflicting attestations. Fork choice must:

1. Detect equivocation via slashing conditions (double vote, surround vote, double proposal)
2. Preserve both conflicting signatures as evidence
3. Not crash or hang when two conflicting messages arrive in close proximity
4. Not double-count the equivocator's weight — their vote should NOT contribute to fork-choice weight after equivocation is detected

Check:

• Ast-grep for "equivocation" / "double_vote" / "slashing" in fork-choice code
• Trace the weight computation: does it exclude equivocators' contributions?
• Duplicate block handling: if two blocks for the same slot arrive, does the fork-choice data structure gracefully hold both, or does the second overwrite the first? Overwrites are bug-prone.

Known exemplar class: Cosmos / Tendermint "Denial of Validators" attacks — multiple historical bugs where equivocation detection could itself be exploited to halt the chain.

Tag: [EQUIVOC:{loc}:{handling}]

4. Reorg State Consistency

When fork choice selects a new head, the node must reorg: revert state from the old head back to the common ancestor, then apply blocks from the common ancestor to the new head.

Check:

1. Enumerate all state that must be rolled back on reorg: account balances, nonces, receipts, logs, fork-choice's own caches
2. For each state category, verify the reorg path touches it
3. Look for side-channel state that does NOT roll back: metrics, logs flushed to disk, cached RPC responses, indexer state
4. On reorg, is any background task (indexer, RPC subscription, metrics) left in an inconsistent state?

Tag: [REORG-GAP:{state-category}]

4a. Fork block ordering / replay order

For every helper that returns blocks to apply during a reorg (get_fork_blocks, fork_blocks, blocks_to_apply, ancestor_path, rollback_path):

1. Determine the expected order: ancestor → child → ... → new head for forward application, or old head → ... → ancestor for rollback.
2. Inspect whether the implementation collects by walking parent pointers from head to ancestor and forgets to reverse the list.
3. Check all consumers: if a function expects forward order but receives reverse-chronological order, state replay can apply children before parents.
4. Emit a finding for any ambiguous helper that does not document and enforce its order contract.

Tag: [REORG-ORDER:{function}:{expected}->{actual}]

Known exemplar class: Solana Sept 2022 stuck validator bug — fork choice could not revert to heaviest bank when its slot matched the last voted slot.

5. Slot vs Block Reasoning

A subtle class of bugs comes from conflating slot (time unit) with block (proposed content). Rules of thumb:

• Every slot has zero or one canonical block but the fork-choice data structure must handle both cases
• Slot N can be skipped (empty slot) and slot N+1's block parent points to slot N-1's block
• Validators vote on slots, not blocks — if slot N is empty, validators vote "empty" for N and contribute to the subtree rooted at N-1

Check: Ast-grep for "slot" in fork-choice code. For each, ask: does the code distinguish "no block at this slot" (valid) from "block not yet arrived" (network delay)?

6. Boundary Conditions

Apply the sweep specific to fork choice:

| State | Test | Expected | Observed | |---|---|---|---| | Genesis | fork choice on only genesis block | returns genesis | | | Single child | one block building on head | returns the child | | | Tie | two children with equal weight | deterministic tie-break | | | Deep reorg | new head requires reverting 50+ blocks | completes without state corruption | | | Finality boundary | new head would revert finalized block | rejected | | | Equivocator weight | equivocator's vote equals non-equivocator's vote | equivocator excluded, non-equivocator wins | | | All votes missing | no attestations in latest epoch | returns last-known head | |

Tag: [BOUNDARY:fork-choice:{test} → {result}]

7. Output schema

• Layer: consensus
• Bug class: fork-choice-rule / equivocation-handling / reorg-consistency / slot-block-conflation / boundary
• Preferred evidence tags: [CONFORMANCE-PASS] (spec test against reference) > [NON-DET-PASS] > [DIFF-PASS] > [LSP-TRACE]

8. Known bug exemplars (v0.2 — Round 4 verified)

1. Solana duplicate-block fork-choice stuck-validator (September 30, 2022) — a validator's hot-spare malfunctioned and generated duplicate blocks for the same slot. Fork choice had no rule for same_leader + same_slot + different_payload. Consensus stalled until coordinated restart. Helius outage history. Skill catch point: Section 3 — enumerate leader-duplicate scenarios (same slot/different parent, same slot/same parent/different content, same slot/two leaders); assert fork choice resolves each without liveness loss.

2. Prysm Fusaka outdated-attestation state replay DoS (December 4, 2025) — Prysm v7.0.0 unnecessarily generated old beacon states while processing outdated attestations. Out-of-sync attestations referencing historical block roots triggered thousands of costly state replays, dropping validator participation to 75% and costing 382 ETH in missed rewards. Rated High not Critical because 9 other clients continued validating. Crypto.news analysis; postmortem. Skill catch point: new methodology step — identify every path that triggers historical state replay, assert the trigger is bounded by a recent-slot check. Stale attestations must be rejected before any state replay.

3. Lighthouse fork-choice timing bug (v2.5.0, fixed in v2.5.1 "Slippy") — two separate bugs introduced in v2.4.0 and v2.5.0 causing intermittent fork-choice errors. Self-resolved within seconds but noise in logs indicated deeper race conditions. Release v2.5.1 "Slippy". Skill catch point: Section 2a — for each tick-driven fork-choice update, verify ordering of: new block arrival, attestation arrival, slot tick, head update. Fuzz all permutations.

4. Tendermint lite-client bisection safety gap (issue #3244) — bisection binary-searched for blocks where validator set voting power changes by <1/3. With sufficient validator-set flux, an attacker could fool a lite client into accepting an invalid header at zero cost. tendermint #3244; attack spec. Skill catch point: for any skip/jump verification, assert the security argument depends on slashing-accountability of faulty validators between trusted and target heights, NOT on honest-majority assumption at target alone.

Methodology nuance from Round 4 (stale-state triggers are DoS vectors)

Add to Section 2a: The Prysm Fusaka lesson generalizes — any fork-choice handler that replays historical state on attacker-controlled input is a DoS vector. Specific check:

• For every attestation / message handler, trace the path: "does this trigger state reconstruction?"
• For every state reconstruction call, assert it is bounded by a recent-slot check
• Reject-before-replay, not reject-after-replay

Tag: [FC-STALE-DOS:{handler}:{replay-trigger}]

9. Fallback if primitives unavailable

• Identify fork-choice module by directory name
• Read the function that returns "current head" / "canonical chain"
• Grep for weight/score accumulation loops
• Check recent fork-choice fixes in git log

Cross-references

• Related skills: consensus-safety-invariants, bls-aggregation-audit (for attestation signature check), state-sync-pruning (reorg clears sync state)
• Consumed by: depth-consensus-invariant
• Severity guide: docs/l1-mode/severity-matrix.md