Skip to content

fix(fork_choice): walk the filtered block tree with an explicit stack - #758

Merged
pablodeymo merged 12 commits into
mainfrom
fork-choice-iterative-filter
Nov 19, 2026
Merged

pablodeymo merged 12 commits into
mainfrom
fork-choice-iterative-filter

Conversation

@MegaRedHand

@MegaRedHand MegaRedHand commented Nov 2, 2026 •

Copy link
Copy Markdown
Collaborator

🗒️ Description / Motivation

filter_block_tree recursed once per block below the justified checkpoint. While the chain does not justify, that depth grows by one block every slot, and get_head runs on the chain actor's thread: spawned-concurrency's Backend::Thread starts it with std::thread::spawn, so it gets the default 2 MiB stack (nothing in the node sets a stack size).

On that stack the recursive walk overflowed between 5,500 and 6,000 blocks of depth (release-fast, measured on an M3 Pro and on a Ryzen 7 9700X). On mainnet that is about 18 to 20 hours of a stall in which nothing new is justified. A stack overflow aborts the process, and the next head computation after a restart walks the same tree.

The chain actor is not the only thread that runs this walk. get_head_node is also the fallback, when the store has no head recorded, in three places off the actor:

  • crates/net/rpc/src/beacon/validator.rs (payload_present_index, for gloas attestation data), called inline from the async handler, so on a tokio worker thread;
  • crates/net/rpc/src/beacon/gloas_proposal.rs (prepare, for produceBlockV4), under spawn_blocking;
  • crates/blockchain/state_transition/src/beacon/gossip/execution_payload_bid.rs (head_view, behind is_bid_compatible_with_head), in p2p's stateful gossip checks, also under spawn_blocking.

Tokio's worker and blocking threads default to 2 MiB stacks too, and the node does not change that, so the same walk could overflow there; this fix covers those callers as well. I did not measure the overflow depth on those threads.

Found while timing #746 on synthetic stall trees (results in a comment there). #746 kept the recursion; its parent-to-children map is what makes each step of the explicit stack a lookup rather than an index scan.

What Changed

  • crates/blockchain/state_transition/src/beacon/fork_choice.rs
    • filter_block_tree keeps its own stack of the path from block_root to the block in hand (one frame per block: its index entry, its children, the next child to visit, and whether any child so far is viable) instead of recursing. Same signature.
    • The leaf check moved unchanged into a private is_viable_leaf, which returns the verdict and leaves the insertion to the walk.
    • The doc comment that called the recursion safe ("stays shallow in ordinary operation") now explains why the stack is explicit. Two neighbouring doc comments that no longer matched the code are fixed: who builds index, and which functions call get_checkpoint_block.
    • Tests:
      • New the_head_walk_does_not_overflow_a_default_stack_on_a_stall_deep_chain.
      • New the_filter_fails_on_entry_when_the_justified_block_is_gone.
      • The spec-literal reference filter_block_tree_by_scan now asks is_viable_leaf for a leaf's verdict instead of calling filter_block_tree with an empty child map, so it no longer runs through the walk it checks.

Correctness / Behavior Guarantees

  • Same blocks visited, in the same order (each block's children_of slice order), so the same filtered tree and return value.
  • The block_root in store.blocks assertion runs when a block is entered, where each recursive call made it, so a pruned justified root still fails the walk with the same error (update_head_from_fork_choice logs it and keeps the head). the_filter_fails_on_entry_when_the_justified_block_is_gone pins this.
  • The first error still ends the walk at the same block.
  • The path lives in a heap Vec with one small frame per level of depth, instead of one stack frame per level.

Tests Added / Run

  • New: the_head_walk_does_not_overflow_a_default_stack_on_a_stall_deep_chain. It builds a 20,000-block chain with nothing justified past the anchor and runs get_filtered_block_tree and get_head_node on a thread with an explicit 2 MiB stack. With perf(fork_choice): build the parent-to-children map once in get_filtered_block_tree #746's recursive walk it aborts with a stack overflow; with this change it passes in 0.07 s. A stack overflow takes down the whole test binary rather than failing one test, which the test's doc comment says.
  • New: the_filter_fails_on_entry_when_the_justified_block_is_gone. It deletes the justified block's LiveChain row (what invalidating it leaves behind) while its child stays, and checks get_filtered_block_tree fails with SpecAssert("block_root in store.blocks"). The child makes the walk's entry check the only source of that message: with the check removed, the test fails, because the walk reaches the child and its leaf check fails on block_root in store.block_states instead.
  • Existing: perf(fork_choice): build the parent-to-children map once in get_filtered_block_tree #746's the_filtered_tree_matches_the_spec_literal_children_scan_on_random_trees compares the walk with the recursive spec-literal reference on 100 random trees, including trees where branches are filtered out. The reference now shares only is_viable_leaf with the walk.
  • Ran:
    • make fmt, make lint: clean
    • cargo test --profile release-fast -p ethlambda-state-transition: 641 passed, 0 failed, 15 ignored (fork_choice unit tests: 96 passed)
    • make test-consensus: 1,325 passed, 0 failed (before the review changes; not re-run)
    • mainnet fork-choice fixture cases (--test beacon_spec_tests --features beacon-spec-tests -- fork_choice): 206 passed (before the review changes; not re-run)

Not checked: the overflow depth under the release profile, where LTO can change frame sizes, and on tokio's threads.

Related Issues / PRs

✅ Verification Checklist

  • Ran make fmt: clean
  • Ran make lint (clippy with -D warnings): clean
  • Ran make test (test-consensus plus test-node, at release-fast): test-consensus run locally; test-node left to CI (unrelated to this change)

pablodeymo and others added 2 commits October 30, 2026 17:52
…ead of

scanning the whole block index at every node of filter_block_tree. The scan
ran once per node of the justified subtree over the full live window since
finality, so the head walk was quadratic in the number of unfinalized blocks,
exactly what a finality stall or a range catch-up grows. walk_head and
invalidate_subtree already build the map this way; this brings the filter in
line with them. A new test keeps the spec-literal scan as a reference and
checks the two agree on random trees, including ones where a branch is
filtered out.
filter_block_tree recursed once per block below the justified checkpoint.
That depth grows by a block every slot for as long as the chain does not
justify, and get_head runs on the chain actor's thread, which
spawned-concurrency starts with std::thread::spawn and so the default 2 MiB
stack. On that stack the recursive walk overflowed between 5,500 and 6,000
blocks of depth (release-fast): about 18 to 20 hours of a stall with no new
justification. A stack overflow aborts the process, and the next head
computation after a restart walks the same tree.

The walk now keeps its own stack of the path from the justified block to the
block in hand. It visits the same blocks in the same order, asserts
`block_root in store.blocks` at the same points and returns the same tree.
The leaf check moved unchanged into is_viable_leaf, which returns the verdict
and leaves the insertion to the walk.
@github-actions

github-actions Bot commented Nov 2, 2026

Copy link
Copy Markdown

🤖 Kimi Code Review

I'll review this PR which converts a recursive filter_block_tree to an iterative implementation to prevent stack overflow during finality stalls.

Summary

The PR correctly addresses a critical stack overflow vulnerability in the fork choice filter_block_tree function. The iterative conversion is well-structured, but I have several concerns ranging from minor code quality issues to a potential logic bug in error propagation.


Critical Issues

1. Potential Logic Bug: any_viable Not Updated When Child Is Viable Leaf

File: fork_choice.rs, lines 1943-1955

In the iterative loop, when a leaf node is found viable and the stack unwinds:

let viable = if top.children.is_empty() {
    is_viable_leaf(store, index, top.root, config)?
} else if let Some(&child) = top.children.get(top.next_child) {
    // ...
} else {
    top.any_viable
};

After path.pop(), the parent's any_viable is OR'd with viable. However, consider: when a leaf is viable (is_viable_leaf returns true), it's inserted into blocks. But when we pop back to its parent, we set parent.any_viable |= viable. If that parent has no other children, its own any_viable becomes true, and when we later evaluate it (after all children processed), we use top.any_viable which is correct.

But wait—re-examine the original recursive code:

if filter_block_tree(store, index, children_of, child, blocks, config)? {
    any_viable = true;
}
// ...
if any_viable {
    blocks.insert(block_root, entry);
    return Ok(true);
}
return Ok(false);

The recursive version returns true immediately when any_viable becomes true after processing all children. The iterative version processes all children regardless. This is behaviorally equivalent for correctness (still checks all children), but less efficient. Not a bug, just noting the divergence.

Actually, re-reading more carefully: the iterative version does not short-circuit. This is fine since the spec doesn't require short-circuiting.

Status: Not a bug, behavior is correct.


Moderate Issues

2. Missing #[inline] or Visibility Consideration for is_viable_leaf

File: fork_choice.rs, lines 1970-1991

is_viable_leaf is a new pub(crate) or module-private function. Given it's only called from filter_block_tree, consider making it pub(crate) explicitly or adding a doc comment about why it's extracted. The extraction is good for readability, but:

fn is_viable_leaf(

Should this be pub(crate)? It's currently implicitly private to the module. If tests need it, they'd be in the same module. The current test doesn't use it directly. This is fine, but consider whether future tests might want to test leaf viability in isolation.

Status: Minor, acceptable as-is.


Code Quality Issues

3. Unnecessary mut on blocks Parameter

File: fork_choice.rs, line 1899

blocks: &mut HashMap<Root, (Slot, Root)>,

This was present in the original, but the PR doesn't address it. The blocks parameter is mutated, but the function signature already reflects this. No issue here—just verifying the PR didn't introduce unnecessary mutability.

Actually, checking: the new code uses blocks.insert(done.root, done.entry); which requires &mut. Correct.

4. Comment Typo/Clarity

File: fork_choice.rs, line 1878

-    /// `block_root`; only the recursive calls below pass anything else.
+    /// `block_root`; only the spec-literal reference in the tests passes anything
+    /// else.

This comment change is slightly misleading. The original said "recursive calls below" pass other values. The new version says "spec-literal reference in the tests" passes anything else. But looking at the actual callers—there are no other callers in production code that pass anything other than store.justified_checkpoint.root. The comment is trying to say that only tests exercise the spec's literal behavior of passing other roots.

However, this is confusing because there are no recursive calls anymore. The comment should be updated to remove the implication that anything in this function passes other values:

Suggested change:

/// *Note*: external callers must pass `store.justified_checkpoint.root` for
/// `block_root`. The specification allows other values, but only test code
/// exercises that path.

5. Test Stack Size Assumption

File: fork_choice.rs, line 10066-10067

// `std::thread`'s documented default, unless `RUST_MIN_STACK` says
// otherwise. Set explicitly so the environment cannot hide a
// regression.
const DEFAULT_THREAD_STACK: usize = 2 * 1024 * 1024;

This is platform-dependent. On some platforms (e.g., musl Linux), the default thread stack is smaller (80KB or 128KB). The comment acknowledges RUST_MIN_STACK but the hardcoded value may not match reality on all targets.

Suggestion: Consider using std::thread::available_parallelism or document that this test assumes glibc-style defaults. Or, better: spawn with an explicitly small stack to prove the fix works even under tight constraints, rather than assuming default:

.stack_size(512 * 1024) // intentionally small to stress-test

This would make the test more robust across platforms and actually validate that the iterative approach works with minimal stack.

6. Test RNG Seed Reuse Pattern

File: fork_choice.rs, line 10072

let mut rng = TestRng(DEPTH);

Using DEPTH as the seed is deterministic but slightly odd—usually seeds are fixed constants. This is fine since it's deterministic, but if DEPTH changes, the "random" values change too. Not a bug, just unconventional.


Positive Observations

  1. Correct iterative transformation: The explicit stack Frame struct correctly models the call stack, with next_child as the program counter and any_viable as the return value accumulator.

  2. Memory safety: No unsafe code introduced; the borrow checker is correctly satisfied with 'a lifetime on children.

  3. Error propagation: The ? operator in enter and is_viable_leaf correctly propagates errors without leaking resources (the path Vec is dropped normally on panic or error return).

  4. Test coverage: The deep chain test is excellent— it actually validates the fix under realistic stall conditions.

  5. Performance: The iterative version avoids stack growth; heap allocation for path is bounded by chain depth (same as recursive stack growth, but on heap where it's safe). No additional allocations per node compared to recursive version.


Suggested Changes

Change 1: Clarify comment (line 1877-1880)

/// *Note*: external callers must pass `store.justified_checkpoint.root` for
/// `block_root`. The specification's recursive formulation allows passing
/// other roots; only test code exercises that path.

Change 2: Make test more portable (line 10066-10075)

Consider using a smaller explicit stack to prove robustness:

const TEST_STACK_SIZE: usize = 512 * 1024; // 512KB: smaller than most defaults
// ...
.stack_size(TEST_STACK_SIZE)

This makes the test pass on more platforms and be a stronger regression test.


Final Assessment

Aspect Rating Notes
Correctness ✅ Good Iterative transformation preserves semantics
Security ✅ Improved Eliminates DoS via stack overflow
Performance ✅ Neutral Same complexity, heap instead of stack
Safety ✅ Good No unsafe, proper error handling
Maintainability ⚠️ Acceptable Frame struct is clear; comments could be sharper
Testing ✅ Good Deep chain test validates the fix

Overall: Approve with minor suggestions. The core fix is correct and important. Address the comment clarity and consider the test stack size adjustment.


Automated review by Kimi (Moonshot AI) · kimi-k2.6 · custom prompt

@github-actions

github-actions Bot commented Nov 2, 2026

Copy link
Copy Markdown

🤖 Codex Code Review

⚠️ The review job did not complete (result: failure). See the job log


Automated review by OpenAI Codex

@github-actions

github-actions Bot commented Nov 2, 2026

Copy link
Copy Markdown

🤖 Claude Code Review

Review: fix(fork_choice): walk the filtered block tree with an explicit stack

I read the change in crates/blockchain/state_transition/src/beacon/fork_choice.rs:1898-1990 and its reference test near line 9983. I did not build it or run the tests.

The change looks correct.

  • Same traversal as the recursion. The walk enters the children in order and records a node only after its subtree finishes. A node with children is viable if any child is, and a leaf is judged by is_viable_leaf. any_viable |= viable after the pop matches the original any_viable = true in the loop.
  • Same assert, same place. enter does the block_root in store.blocks lookup when a node is entered, as the recursive call did, so a missing justified row still gives SpecAssert at the same point. The ? on is_viable_leaf and enter returns early, as before.
  • Leaf logic unchanged. is_viable_leaf is the old leaf check, now returning a verdict instead of inserting. The walk does the insert.
  • Stack use is bounded. A Frame is heap-allocated and about 80 bytes, so the path costs O(depth) heap and no thread stack. children borrows from children_of, so there is no extra cloning.
  • The tests cover it. filter_block_tree_by_scan keeps the spec-literal recursive version and is compared against the new walk on 100 random trees. It calls the new function with an empty child map to get the leaf verdict, which is a sound way to share that logic. There is also a deep-chain test on a default-stack thread.

Minor points, none blocking:

  1. Other recursion over chain depth. The commit message says walk_head and invalidate_subtree are already iterative. Before closing the stall-overflow issue, grep the rest of the head path (get_voting_source, get_checkpoint_block, and any gloas-side walk) for recursion proportional to depth. get_checkpoint_block is called per leaf and should be a parent-pointer loop.
  2. Unreachable .expects. The two .expect(...) calls on path can't fire. The first holds because the loop returns as soon as the path empties. The second holds because top is the last element. That is fine, but a short // invariant: comment would save the next reader from re-deriving it.
  3. Scope of the PR. The diff includes unrelated files (.cargo/config.toml, .claude/...) because it appears to be based on a whole-repo commit. If that is not intended, rebase so the PR shows only the fork-choice change.

Otherwise this is a clean, behavior-preserving fix for a real abort scenario (about 5,500 blocks of depth on a 2 MiB stack). I'd approve it.


Automated review by Claude (Anthropic) · sonnet · custom prompt

Base automatically changed from fork-choice-children-map to main November 2, 2026 19:32
#746 was squash-merged, so this branch's copy of its commits no longer
matches main. The tree is main plus only this branch's own commit.
MegaRedHand added a commit that referenced this pull request Nov 5, 2026
…#758)

filter_block_tree recursed once per block below the justified checkpoint.
That depth grows by a block every slot for as long as the chain does not
justify, and get_head runs on the chain actor's thread, which
spawned-concurrency starts with std::thread::spawn and so the default 2 MiB
stack. On that stack the recursive walk overflowed between 5,500 and 6,000
blocks of depth (release-fast): about 18 to 20 hours of a stall with no new
justification. A stack overflow aborts the process, and the next head
computation after a restart walks the same tree.

The walk now keeps its own stack of the path from the justified block to the
block in hand. It visits the same blocks in the same order, asserts
`block_root in store.blocks` at the same points and returns the same tree.
The leaf check moved unchanged into is_viable_leaf, which returns the verdict
and leaves the insertion to the walk.

Cherry-picked from fork-choice-iterative-filter at de7bb98 (b102e35; the
branch's other commits are #746, already on nightly, and merges of main).

Claude-Session: https://claude.ai/code/session_011vghNmndKPkZinHRkVTwVB

@pablodeymo pablodeymo left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed at 7464df5. The explicit-stack walk looks correct to me: it visits the same blocks in the same post-order as the recursion, makes the block_root in store.blocks assertion on entry, inserts on exit, and returns the same verdict.

What I checked beyond reading it:

  • The new test catches the regression. Under release-fast it passes in 0.07 s on this branch. With main's recursive filter_block_tree put back under the same test, it aborts with thread 'deep-chain-head-walk' has overflowed its stack.
  • The differential test passes (the_filtered_tree_matches_the_spec_literal_children_scan_on_random_trees).
  • The 2 MiB premise holds. Backend::Thread in spawned-concurrency 0.5.0 is std::thread::spawn, and nothing in the repo sets a stack size or RUST_MIN_STACK.

Small things, none blocking (line numbers are in fork_choice.rs at this head):

  1. Two doc comments no longer match the code.
    • Line 1888 says index is "built once by get_filtered_block_tree". That function receives index and builds only children_of. The wording predates this PR, but the sentence is edited here.
    • Line 3389 calls filter_block_tree "the only caller of get_checkpoint_block in this file". The call is in is_viable_leaf now, and validate_on_attestation_indexed and on_block call it too.
  2. The test reference can call is_viable_leaf directly. filter_block_tree_by_scan (line 10000) gets a leaf's verdict by calling filter_block_tree with an empty child map, so the reference runs through the loop it is the reference for. Calling the new helper removes that, and with it the "only the spec-literal reference in the tests passes anything else" caveat in the doc.
  3. No test pins the error path. The description says a missing justified root still fails with SpecAssert("block_root in store.blocks"). I did not find a test asserting that; a short one against get_filtered_block_tree would cover it.
  4. The description could mention the other callers. get_head_node is also reachable off the chain actor's thread, as a fallback in rpc/src/beacon/validator.rs, rpc/src/beacon/gloas_proposal.rs and gossip/execution_payload_bid.rs. This fix covers those too.

Follow-ups, not for this PR:

  • Leaves × depth is the next limit. is_viable_leaf still walks every leaf back to the finalized epoch through get_checkpoint_block, which is the 74 ms at 14,851 blocks and 451 leaves from the #746 measurements. The overflow used to cap the depth, and now nothing does. The path this PR adds makes it cheap to fix:
    • If the justified block is above the finalized epoch's start slot, the answer is the same for every leaf, so one get_ancestor from the base is enough.
    • Otherwise the checkpoint block is on path, and a partition_point by slot finds it.
  • discard_pending_subtree still recurses (crates/blockchain/src/lib.rs), once per pending descendant, on the same actor thread. I did not measure its frame or check whether a deep pending chain can form, so this is only a pointer.

…checkpoint_block

filter_block_tree's doc said get_filtered_block_tree builds index; it receives it from its caller and builds only children_of. gloas_get_ancestor's doc called filter_block_tree the only caller of get_checkpoint_block in the file; the call is in the filter's leaf check (is_viable_leaf), and validate_on_attestation_indexed and on_block call it too.
…f for a leaf

filter_block_tree_by_scan got a leaf's verdict by calling filter_block_tree with an empty child map, so the reference ran through the walk it is the reference for. It now calls is_viable_leaf directly and makes the specification's block_root in store.blocks check itself, sharing nothing else with the walk. Nothing passes filter_block_tree a root other than the justified one any more, so its doc note says get_filtered_block_tree is the only caller.
…k is gone

A justified block whose LiveChain row was deleted, with its child still in the index, must fail get_filtered_block_tree on entry with SpecAssert("block_root in store.blocks"), the error update_head_from_fork_choice logs before keeping its head. The child is what makes the walk's entry check the only source of that message: with the check removed, the walk reaches the child and fails its leaf check on block_root in store.block_states instead, and the test fails.
@MegaRedHand

Copy link
Copy Markdown
Collaborator Author

Thanks for running the overflow both ways. I've pushed the four small items:

  1. Stale doc comments (117b03d): filter_block_tree's doc now says index comes from the caller and get_filtered_block_tree builds only children_of. gloas_get_ancestor's doc now lists every caller of get_checkpoint_block in the file: the filter's leaf check, validate_on_attestation_indexed and on_block. I also fixed the same wording in the doc of get_checkpoint_block_succeeds_after_pruning_past_an_empty_epoch_boundary.
  2. The reference (02b7416): filter_block_tree_by_scan now calls is_viable_leaf for a leaf and makes the block_root in store.blocks check itself, so it shares only the leaf verdict with the walk. Nothing passes filter_block_tree a non-justified root any more, so the *Note* now just says get_filtered_block_tree is the only caller.
  3. Error path (895a48d): the_filter_fails_on_entry_when_the_justified_block_is_gone deletes the justified block's LiveChain row and keeps its child, then asserts get_filtered_block_tree fails with SpecAssert("block_root in store.blocks"). The child is there on purpose: without one, get_voting_source on the justified root asserts the same words, so the test could not tell whether the entry check ran. I checked it by removing the entry check in enter: the test then fails with block_root in store.block_states from the child's leaf check.
  4. Description: it now lists the three get_head_node fallbacks off the actor thread: payload_present_index in rpc/src/beacon/validator.rs, which runs inline on a tokio worker; prepare in rpc/src/beacon/gloas_proposal.rs, under spawn_blocking; and head_view in gossip/execution_payload_bid.rs, in p2p's stateful checks, also under spawn_blocking. Tokio's threads default to 2 MiB too. I haven't measured the overflow depth there.

I've left the two follow-ups out of this PR: leaves × depth through get_checkpoint_block (your path-based sketch noted), and the recursion in discard_pending_subtree.

I also merged main; it merged without conflicts, and the state-transition tests pass on the merge (641 passed).

@MegaRedHand

Copy link
Copy Markdown
Collaborator Author

/review

@github-actions

Copy link
Copy Markdown

🤖 Gemini Code Review

The changes look great.

Replacing the recursion in filter_block_tree with an explicit heap-allocated stack (Vec<Frame>) and extracting is_viable_leaf preserves the exact traversal order, post-order blocks insertion, and error semantics of the spec while preventing stack overflows during long finality stalls. The accompanying 20,000-block deep-chain test on a fixed 2 MiB thread stack and the updated reference scan helper are clean and thorough.


Automated review by Gemini · gemini-4-argon · custom prompt

@github-actions

Copy link
Copy Markdown

🤖 Claude Code Review

Review: PR 758, iterative filter_block_tree

Summary

This replaces per-child recursion in filter_block_tree with an explicit heap-allocated stack. A recursion depth that grows by one block per slot during a finality stall is a real, process-aborting DoS vector, so the fix is worthwhile. The rewrite matches the original semantics. I'd approve with minor nits.

Correctness

I traced the new loop (fork_choice.rs ~1938–1966) against the old recursion. It matches on every point:

  • Entry assertion. enter runs the block_root in store.blocks check at the same point the recursive call did:

    • for the root, before anything else;
    • for each child, when that child is first visited, not when the parent is entered.

    So a missing child row fails at the same block, after the same earlier siblings have been processed and inserted.

  • No short-circuit. All children are visited even after one is viable, which matches the spec's any(...) over a list that is materialized first. This matters because blocks must receive every viable subtree, not just the first.

  • Insertion order. Insertion is post-order (child before parent), the same as before. blocks is a HashMap, so order doesn't matter anyway.

  • Single-node tree. A root with no children takes the leaf branch, as before.

  • Borrows. top's mutable borrow ends before path.push/path.pop (NLL). child and any_viable are Copy. This is sound.

Suggestions

  1. Gloas head path is not covered by the deep-chain test. The new test (the_head_walk_does_not_overflow_a_default_stack_on_a_stall_deep_chain) only exercises get_head_node on Fulu blocks. get_filtered_block_tree also serves gloas_get_head, and the gloas path has its own walks (gloas_get_ancestor, is_parent_node_full, payload-status traversal). If any of those recurse per block, the same overflow exists there. Consider either:

    • parameterizing the test over a Gloas chain, or
    • confirming in a comment that every walk reachable from both head functions is iterative.
  2. Test runtime in debug builds. At DEPTH = 20_000, check that get_head_node doesn't do per-candidate get_ancestor walks from the tip. That pattern is O(depth²·validators) and could make this test take tens of seconds under cargo test without --release. If it's slow, the overflow regression would still be caught by a smaller depth (a few thousand already overflowed per the doc comment), e.g. 5_000.

  3. Optional: drop the two expects. A while let shape removes the panicking unwraps while preserving behavior:

    let mut path = vec![enter(index, children_of, block_root)?];
    while let Some(top) = path.last_mut() {
        let viable = if top.children.is_empty() {
            is_viable_leaf(store, index, top.root, config)?
        } else if let Some(&child) = top.children.get(top.next_child) {
            top.next_child += 1;
            path.push(enter(index, children_of, child)?);
            continue;
        } else {
            top.any_viable
        };
        let done = path.pop().unwrap(); // or restructure to pop first
        ...
    }

    This is purely stylistic. The current invariants are correct.

  4. Doc comment length. The filter_block_tree doc (lines ~1875–1898) now mixes caller contract, history ("overflowed that stack once…"), and complexity rationale. The incident narrative would sit better in the commit message, with the doc trimmed to:

    • the contract (callers pass the justified root);
    • "iterative to bound stack use on long unjustified chains";
    • the index/children_of rationale.

Tests

  • filter_block_tree_by_scan is now a fully independent recursive reference. It shares only is_viable_leaf, which is a better oracle than before, when it delegated back into filter_block_tree with an empty child map.
  • the_filter_fails_on_entry_when_the_justified_block_is_gone is well designed: adding the child makes the entry check the only possible source of that assertion string.
  • Setting stack_size explicitly to 2 MiB, so RUST_MIN_STACK can't mask a regression, is a good touch.

No security or memory-safety concerns. Path memory is O(depth) on the heap, at roughly 64 bytes per frame.


Automated review by Claude · claude-opus-5-5 · custom prompt

@github-actions

Copy link
Copy Markdown

🤖 Codex Code Review

No actionable findings. The iterative traversal preserves leaf validation, branch viability propagation, and error behavior while removing the recursion-related stack overflow risk. The added regression tests cover deep chains and missing justified roots.

Tests could not run: Rustup attempted to update the pinned toolchain but was blocked by the read-only filesystem.


Automated review by OpenAI Codex · gpt-6.1-sol · custom prompt

@github-actions

Copy link
Copy Markdown

🤖 Grok Code Review

I'll compare the iterative walk with the previous recursive filter and check the surrounding fork-choice helpers for semantic drift.


Automated review by Grok (xAI) · grok-4.7 · custom prompt

@github-actions

Copy link
Copy Markdown

🤖 Kimi Code Review

No issues found. The explicit-stack traversal in filter_block_tree preserves the recursive implementation’s post-order behavior, viability propagation, insertion semantics, and error propagation—including the initial block_root in store.blocks assertion. Leaf viability remains unchanged after extraction into is_viable_leaf.

The deep-chain regression test appropriately exercises a 2 MiB stack and 20,000 blocks, while the missing-justified-block test covers the important failure path. The walk now uses heap memory proportional to chain depth instead of risking a process-aborting stack overflow, with linear traversal given the prebuilt index and children map.


Automated review by Kimi (Moonshot AI) · kimi-k3.1-pro · custom prompt

@github-actions

Copy link
Copy Markdown

🤖 DeepSeek Code Review

The iterative rewrite is sound: it preserves the original DFS order and error sites, and moving the path to a heap-allocated Vec<Frame> removes the stack-overflow crash on deep unfinalized chains. The two new tests are well targeted.

One consensus-level concern:

  • In crates/blockchain/state_transition/src/beacon/fork_choice.rs, around the new let viable = if top.children.is_empty() { ... } block (roughly lines 1942-1953), a block with children is considered viable only if one of its children is viable. If no child is viable, it is popped and treated as non-viable without ever checking its own is_viable_leaf condition.

    This matches the prior recursive behavior, but it is not the Ethereum fork choice spec for filter_block_tree: the spec iterates children first, and if none are viable, it still evaluates the block’s own justified/finalized condition even when the block has children. A non-leaf block can therefore be viable itself even if all of its children are non-viable. The new comment makes this deviation explicit.

    The test helper filter_block_tree_by_scan (around line 10015) repeats the same if children.is_empty() logic, so the randomized comparison test won’t catch this divergence. If this is intentional, it should be documented as a deliberate deviation; otherwise, the loop should fall through to is_viable_leaf after exhausting children rather than only doing so for leaves.

No memory-safety or performance issues found in the stack conversion itself.


Automated review by DeepSeek · deepseek-v4-pro · custom prompt

@MegaRedHand

Copy link
Copy Markdown
Collaborator Author

Round three (the automated review of 895a48d). Nothing changed. On 895a48d the fork_choice unit tests pass under release-fast (96 passed, 0 failed). The deep-chain test also passes under plain cargo test, in 0.55 s.

Not changed

  • Claude 1 (the gloas head path): none of the head walks recurse.
    • get_head_node runs the same walk_head loop and compute_node_weights sort-and-fold for every fork, gloas rules included.
    • get_filtered_block_tree is fork-independent, and gloas_get_ancestor is a loop.
    • gloas_get_head is a test-only reference.
    • A scan of state_transition/src/beacon, storage and ssz-tree for functions or methods that call themselves finds only the test's filter_block_tree_by_scan, apart from ssz-tree's height-bounded recursion.
  • Claude 2 (debug runtime): there is no per-candidate walk. The one leaf makes one get_checkpoint_block walk, and the weights are one fold. The test takes 0.55 s unoptimized and 0.07 s under release-fast, which is how the repo runs its tests.
  • Claude 3 (while let): kept. The loop returns when the last frame pops, so the suggested shape still needs an unwrap there. Popping first would avoid both expects, but the frame would then be pushed back on every child step. Neither expect can fire, and each names its invariant.
  • Claude 4 (doc length): kept. The paragraph explains why this does not recurse like the spec, which is what stops someone from putting the recursion back.
  • DeepSeek (non-leaf viability): this is the spec's behaviour. filter_block_tree in phase0/fork-choice.md (v1.7.0-beta.2, lines 410 to 415) returns False for a block with children when none of them is viable, without checking the block's own checkpoints. No later fork's fork-choice.md redefines it. The walk and main's recursive version both do the same.

Gemini, Codex and Kimi found nothing to change. Codex could not run the tests (its toolchain update was blocked). Grok's comment stopped after its opening sentence.

@MegaRedHand

Copy link
Copy Markdown
Collaborator Author

The review loop on this PR stops here: round three raised nothing left to address.

Follow-ups from round two, tracked separately: #811 (the filter's leaves × depth cost through get_checkpoint_block) and #810 (discard_pending_subtree still recursing).

@pablodeymo
pablodeymo added this pull request to the merge queue Nov 19, 2026
Merged via the queue into main with commit 289278e Nov 19, 2026
11 checks passed
@pablodeymo
pablodeymo deleted the fork-choice-iterative-filter branch November 19, 2026 19:50
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants