Skip to content

perf(beacon): back the participation lists and pending deposits with persistent trees - #762

Merged
MegaRedHand merged 18 commits into
mainfrom
perf/tree-backed-participation
Nov 20, 2026
Merged

MegaRedHand merged 18 commits into
mainfrom
perf/tree-backed-participation

Conversation

@MegaRedHand

@MegaRedHand MegaRedHand commented Nov 2, 2026 •

Copy link
Copy Markdown
Collaborator

🗒️ Description / Motivation

The post-block state root check cost ~27 ms per block on the mainnet follower. Perf put 87% of BeaconState::hash_tree_root in plain SszList fields re-merkleized from scratch on every call: the two participation lists (2.4 MB each) and PendingDeposits; only 13% was in the tree-backed ethlambda_ssz_tree lists. Lighthouse keeps every state list in milhouse persistent trees with cached node hashes.

What Changed

  • EpochParticipation (altair through fulu) is ethlambda_ssz_tree::List<u8, LIMIT> with the dense VecMap write buffer; PendingDeposits (electra, fulu) is List<PendingDeposit, LIMIT, BTreeMap>; gloas's are ethlambda_ssz_tree::ProgressiveList. All in tree_fields!, so apply_pending_mutations flushes them, and BeaconState::rebase_on shares them with a resident relative.
  • Accessors: altair_validator_lists() returns ParticipationRefs, epoch_participation_mut() a ParticipationMut.
  • helpers/participation.rs::scan walks both participation iterators in lockstep with iter_validators() instead of an indexed read per validator.
  • Small edits in the process_attestation variants, epoch rotation, fork upgrades and process_pending_deposits; docs/beacon_stf.md and CLAUDE.md updated.

Correctness / Behavior Guarantees

  • SSZ encoding and hash roots are byte-identical, so no DB_VERSION bump: new tests compare the old and new representations at lengths 0, 1, 31, 32, 33, 1000, 65541 and 300001 (bounded and progressive participation, pending deposits), plus writes and a push after a warm hash.
  • Buffer choice: a BTreeMap buffer was a clear loss for participation (75k scattered writes: 29-32 ms vs 13 ms flat); the dense VecMap buffer gives ~5 ms for the two lists.

Benchmarks

Offline ethlambda benchmark import replay on ethlambda-5 (Ryzen 9700X), three mainnet corpora, 2 rounds, steady state n=164, paired per block against main 012dc4f49:

main this PR change 95% CI
STF per block 158.1 ms 135.3 ms -22.9 ms (-14.5%) [-23.4, -22.4]
wall (import + fork choice) 179.7 ms 156.2 ms -23.4 ms (-13.0%)

Per round -15.3% / -13.6%. Epoch-boundary blocks (n=2) -4.9%.

Follow-up commits: regressions this PR introduced

Measured on nightly with all four Lighthouse ports, this PR's first commit cost attestations +1.5 ms per block (a tree descent per attester to read its flags, and another per get_mut write) and process_epoch +9.1 ms at epoch boundaries. The last five commits address that:

  • ethlambda_ssz_tree: List::set / ProgressiveList::set (a blind buffered write), sorted_reader() (reads non-decreasing indices, descending only when an index leaves the leaf last read), and repeat(value, len) (one full leaf and one full inner node per level, shared, each hashing once).
  • process_attestation: the read phase uses the sorted reader (attesting indices are sorted) and records current | new; the write phase stores it with set. That is exact because an attestation's indices are distinct and nothing writes the list between the two phases.
  • The epoch rotation and the altair upgrade build the zero list with repeat.

Micro-benchmarks (2.4M validators, ~74k ascending attesters): read 0.56-0.70 -> 0.10 ms, write 1.6-2.2 -> ~1.0 ms; rotation plus the next hash 3-6 ms -> 0.1-0.2 ms.

On nightly, together with #761's follow-up, offline replay on ethlambda-5, paired, steady state n=164:

before after change 95% CI
STF per block 20.7 ms 19.1 ms -1.5 ms (-7.3%) [-1.6, -1.4]
attestations (ordinary blocks) 5.8 ms 4.3 ms -1.5 ms
process_epoch (epoch boundaries) 106.2 ms 104.8 ms -1.5 ms

Still above nightly before the ports (2.9 ms and 97.2 ms): attestations +1.4 ms (shared with #761) and process_epoch +7.6 ms per epoch boundary; being profiled.

PendingDeposits is left as it is: dropping a processed prefix that is not a multiple of a leaf's element count shifts every later element into another leaf, so the cached hashes cannot be kept without a re-chunking operation. Its per-epoch cost is about 1 ms plus 3 ms of hashing for 20k deposits, against a hash that used to be paid on every block.

Tests Added / Run

  • Representation-equivalence tests above; ignored micro-benchmark participation_root_after_a_block_of_writes_bench (cargo test --profile release-fast -p ethlambda-types --lib -- --ignored --nocapture participation_root).
  • Follow-ups: set, the sorted reader and repeat checked against get and against Vec-built lists (roots and SSZ bytes) at lengths around every leaf and inner-node boundary up to 2.4M; writes into a repeated list through set, get_mut, iter_cow, rebase_on and push leave the clone and untouched leaves unchanged. Ignored benches attestation_pass_bench, participation_rotation_bench, pending_deposits_epoch_rebuild_bench.
  • cargo test --profile release-fast -p ethlambda-ssz-tree --lib (80, also in the dev profile), -p ethlambda-types --lib (237), -p ethlambda-state-transition --lib (630), -p ethlambda-storage --lib (210); cargo check of blockchain, rpc, p2p
  • Beacon spec fixtures: ssz_static/ 1761, sanity/ 595, epoch_processing/ 804, /attestation/ 356, fork/ 138, transition/ 172, /random/ 208, fork_choice/ 206, /deposit_request/ 43, rewards/ 372, finality/ 41

Related Issues / PRs

  • Part of a set of Lighthouse ports from the same profile, each its own PR.

✅ Verification Checklist

  • Ran make fmt — clean
  • Ran make lint (clippy with -D warnings) — clean
  • Ran make test — not run; the crate lib tests and spec filters above were run instead

…persistent trees

On mainnet (about 2.4M validators) the post-block state_root check costs
about 27 ms per block, and perf attributes most of BeaconState::hash_tree_root
to plain SszList fields re-merkleized from scratch on every call: the two
participation lists (2.4 MB each) and pending_deposits. Lighthouse keeps every
state list in milhouse trees with cached node hashes.

EpochParticipation (altair through fulu), PendingDeposits (electra, fulu) and
their gloas progressive counterparts now use ethlambda_ssz_tree lists. Only the
current epoch's participation list is written by a block, so the previous
epoch's list and an untouched deposit queue reuse their cached roots. The SSZ
encoding and roots are unchanged (tests compare against the flat lists), so
DB_VERSION is not bumped.

Participation writes are buffered densely, not in a BTreeMap: at one slot's
worth of scattered attesters the BTreeMap inserts cost several times the
hashing they save. A quick ignored benchmark at 2.4M entries and 75k writes
measures about 13 ms for the flat lists against about 5 ms for the trees.

Reads go through ParticipationRef and ParticipationMut, since a tree has no
slice view. The participation scan walks the list in lockstep with the
registry instead of a tree descent per validator. Both lists are also rebased
onto a resident relative of a state decoded from storage.
@MegaRedHand

Copy link
Copy Markdown
Collaborator Author

Combined result for the four Lighthouse ports (#759 pubkey index, #760 column KZG, #761 progressive target balances, #762 tree-backed participation), squashed onto nightly b1fc143 as 080bd40..1d06bf9.

Offline import replay on ethlambda-5, same three mainnet corpora, both legs built at the commit and run with --warm-committee-sums, 2 rounds, steady state n=164, paired per block:

nightly b1fc143 + all four (1d06bf9) change 95% CI
STF per block 140.7 ms 20.7 ms -120.0 ms (-85.3%) [-123.5, -117.3]
wall (import + fork choice) 162.5 ms 43.8 ms -118.7 ms (-73.0%) [-122.1, -116.0]

Per STF step, ordinary blocks (n=162): sync_aggregate 71.4 -> 0.9 ms (#759), execution_requests 5.3 -> 0.0 ms (#759), state_root 24.8 -> 4.0 ms (#762), unattributed 28.0 -> 1.3 ms (#761's removed state clone and scan, #762's cheaper clone). Regressions being fixed: attestations +2.9 ms, process_epoch +9.2 ms at epoch boundaries, get_head +1.0 ms; a per-item attribution run is in progress.

Live on the ethlambda-2 mainnet follower (nightly 1d06bf9): steady stf ~30-40 ms per gossip block (nightly before the ports: ~175 ms).

…peat

Three primitives the participation-list fixes that follow need, kept in their
own commit so the fixes read as pure call-site changes.

- `List::set` / `ProgressiveList::set` buffer a value without first descending
  the tree to copy the old one into the write buffer, which `get_mut` does even
  when the caller already knows the old value.
- `sorted_reader()` reads non-decreasing indices keeping the current leaf's
  slice, descending only when an index leaves it. Pending writes are consulted
  first, exactly as `get` does, so the answers are identical.
- `List::repeat` / `ProgressiveList::repeat` build a list of identical elements
  by sharing one full leaf and one full inner node per level, each caching its
  hash once, so building and hashing cost the tree height plus the partial last
  leaf instead of the whole length. Nodes are immutable and every write copies
  the path it touches, so a shared leaf can never be mutated; tests write into a
  repeated list and check its clone and the untouched leaves, and compare roots
  against the Vec-built list at lengths around every leaf and node boundary.
…rotation

Two micro-benchmarks next to `participation_root_after_a_block_of_writes_bench`,
at 2.4M validators: the participation part of one `process_attestation`
(about 75k ascending reads, then the writes) in each combination of per-index
`get`/sorted reader and `get_mut`/`set`, and the epoch rotation's new list
built from a zeroed `Vec` against `List::repeat`, with the root that follows.
Run with `cargo test --profile release-fast -p ethlambda-types --lib --
--ignored --nocapture attestation_pass_bench participation_rotation_bench`.
The write phase did `get_mut(index)` and `*flags |= new_flags` for every
attester. On a tree-backed list `get_mut` descends the tree to copy the old
value into the write buffer, although the read phase had already read it as
`current_flags`. Micro-benchmark at 2.4M validators and about 74k ascending
attesters (best of five, release-fast): the write phase takes 2.16 ms with
`get_mut` and 0.94 ms with the blind `set`.

The read phase now records `current_flags | new_flags` and the write phase
stores it with the new `ParticipationMut::set`. That is exactly what `|=` would
leave: the attesting indices are distinct (members of disjoint committees, and
the signature set built before the read phase refuses a repeated index), so
each index is written once, and nothing writes the list between the two phases,
so the stored value is still `current_flags`. Applies to the altair, deneb,
electra (electra and fulu) and gloas versions of `process_attestation`.
… reader

Once the participation lists became trees, the read phase of
`process_attestation` paid a full tree descent per attester (`get` was a slice
index before). An attestation carries tens of thousands of attesters. Its
indices are sorted ascending and consecutive ones almost always share a leaf,
which holds thousands of flags.

`sorted_reader()` keeps the current leaf's slice and descends only when an
index leaves it, consulting pending writes first exactly as `get` does, so the
answers are identical. Micro-benchmark at 2.4M validators and about 74k
ascending attesters (best of five, release-fast): the read phase takes 0.70 ms
per-index and 0.10 ms with the reader; with the blind write from the previous
commit the whole participation pass goes from 2.86 ms to 1.03 ms. Every
`process_attestation` (altair, deneb, electra and fulu, gloas) now uses it;
the reader debug-asserts that indices do not decrease, which
`get_attesting_indices` guarantees by sorting.
…o leaf

`process_participation_flag_updates` installed the new current list as
`vec![0; validator_count]` converted into a tree: about 2.4M bytes allocated
and filled into hundreds of separate leaves, every one of which the next state
root then hashed. At epoch boundaries `process_epoch` went from 96.3 ms to
105.5 ms in the offline import replay once the lists became trees.

`List::repeat` / `ProgressiveList::repeat` (added with the other ssz-tree
primitives) build the list from one full leaf and one full inner node per level,
each shared through its `Arc` with its cached hash, so building and hashing cost
the tree height plus the partial last leaf. Micro-benchmark at 2.4M validators
(release-fast, steady state over three runs): the old build plus the root takes
3.0 to 6.0 ms, the repeated list 0.10 to 0.13 ms. Nodes are immutable and every
write copies its path, so sharing is invisible to later writes; the roots and
SSZ bytes are tested equal to the flat list's at lengths around every leaf and
node boundary, and a write to a repeated list is tested to leave its clone and
the other leaves alone.

Used by the altair-through-fulu rotation, gloas's own copy of it, and the
altair upgrade's two fresh lists.

PendingDeposits is rebuilt from a `Vec` once per epoch by
`process_pending_deposits`, which only drops a prefix and appends postponed
deposits. The tree cannot keep the suffix's cached hashes: leaves are aligned
runs, so dropping a prefix that is not a multiple of a leaf shifts every later
element into a different leaf, and the API has no operation that re-chunks
while carrying cached element roots. An ignored benchmark in `ethlambda-types`
puts the cost at about 7 ms for the copy and rebuild plus about 24 ms to hash,
for a queue of 200k deposits (about 1 ms plus 3 ms at 20k), once per epoch. The
hash was paid on every block before the trees, so this is left as it is.
@MegaRedHand

Copy link
Copy Markdown
Collaborator Author

Per-PR attribution on nightly, where the four ports are stacked in the order #759, #760 + #761, #762. Offline import replay on ethlambda-5, three mainnet corpora, --warm-committee-sums, 2 rounds, steady state n=164, paired per block:

nightly at STF per block change vs before the ports 95% CI
b1fc143 (before the ports) 140.1 ms
+ #759 (080bd40) 65.1 ms -75.0 ms (-53.5%) [-78.5, -72.3]
+ #760, #761 (33551eb) 39.9 ms -100.2 ms (-71.5%) [-103.7, -97.5]
+ #762 (1d06bf9) 20.8 ms -119.4 ms (-85.2%) [-122.9, -116.6]
+ follow-ups in #761 and #762 (2b51a33) 19.1 ms

#760 does not run in the replay (no custody columns), so the second step is #761's.

Regressions found by the per-step split, and what the follow-up commits (now pushed to #761 and #762) did about them:

step from added after the follow-ups
attestations, ordinary blocks #761: second validator read per attester +1.4 ms 5.8 -> 4.3 ms together (before the ports: 2.9)
attestations, ordinary blocks #762: per-attester tree read and write +1.5 ms
process_epoch, epoch boundaries #762 +9.1 ms 106.2 -> 104.8 ms (before the ports: 97.2)
get_head the #760 + #761 step +1.3 ms unchanged

get_head's code is untouched by either PR; a perf profile puts the extra time in walk_head's own code, so it looks like codegen rather than work. The same profile shows std SipHash in fork choice's vote tally as most of get_head's ~17 ms per block; that is a separate change, not part of these PRs.

ethlambda-2 (mainnet follower) runs nightly 2b51a33 since 2026-11-03 14:42 UTC.

@MegaRedHand MegaRedHand added performance Performance improvements or possible performance improvements beacon Ethereum Beacon Chain client labels Nov 3, 2026
@MegaRedHand
MegaRedHand marked this pull request as ready for review November 17, 2026 18:52
@github-actions

Copy link
Copy Markdown

🤖 Codex Code Review

No actionable findings. The tree-backed list migration appears to preserve participation updates, epoch rotation, and SSZ encoding and hash behavior. The sorted reader’s ordering assumption matches attester-index construction.

Tests could not run: the pinned Rust toolchain was unavailable, and the offline fallback lacked the required libssz dependency.


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

@github-actions

Copy link
Copy Markdown

🤖 Claude Code Review

Review: tree-backed participation lists and pending_deposits

This is a well-scoped performance PR. The SSZ encoding is unchanged, and the tests compare roots and encodings against the flat SszList and ProgressiveList across many edge lengths, including leaf and node boundaries and progressive subtree boundaries. I found no consensus-correctness bugs. Notes below, roughly by priority.

Correctness and robustness

  1. Blind-write invariant is only argued in comments, not enforced.

    • Affected code: stf/altair.rs, deneb.rs, electra.rs and gloas.rs, in each process_attestation.
    • Two things depend on attesting_indices being strictly ascending:
      • the sorted_reader fast path;
      • the exactness of set(index, current_flags | new_flags).
    • The reader stays correct out of order; it only slows down and trips a debug_assert.
    • A duplicate index would also double-count proposer_reward_numerator. That was already true before this PR, so the blind write introduces no new divergence.
    • However, a future refactor could pass a Vec built from unsorted committee concatenation in electra or gloas. Suggest one cheap guard before the read loop:
      debug_assert!(attesting_indices.windows(2).all(|w| w[0] < w[1]));
    • Adapt this if attesting_indices isn't a slice.
    • That makes both preconditions explicit, rather than relying on the "signature set refuses a repeated index" reasoning in a comment.
  2. Tree::leaf_run returns None on Tree::Zero (tree.rs, new fn).

    • This is only correct as long as in-range data is never represented as a Zero subtree.
    • Participation lists are mostly zeros, so "collapse all-zero leaves to Zero" is a tempting future optimization in apply_updates or repeat.
    • If anyone adds it, SortedReader::get returns None for a valid index. process_attestation would then reject valid blocks with IndexOutOfBounds, which is a consensus split.
    • Please document this invariant on Tree and leaf_run, or add a debug_assert! in SortedReader::get that index < len implies a hit.
    • The existing reader-vs-get tests would not catch it if get had the same blind spot.
  3. Tree::repeat final match (tree.rs).

    • The unreachable! relies on the earlier capacity assert!. That looks right; the levels == 0 case also works for single-leaf trees, which repeat_fits_trees_without_inner_nodes... covers.
    • No change needed. A one-line comment tying the unreachable! to the assert! would help the next reader.

Performance

  1. .into_inner() → .to_vec() now clones every deposit.

    • Affected code: helpers/electra.rs take_pending_deposits, and upgrade.rs:1023 (onboard_builders_from_pending_deposits).
    • Each PendingDeposit is about 190 B, so this adds a full clone of the queue on every epoch.
    • Consider a consuming into_vec / IntoIterator on ethlambda_ssz_tree::List. It can move out of uniquely-owned leaves via Arc::try_unwrap and fall back to cloning when they are shared.
    • Minor at today's queue sizes, but this is the exact path the new pending_deposits_epoch_rebuild_bench measures.
  2. set_pending_deposits rebuilds the tree from a Vec every epoch, even when nothing was consumed.

    • That discards all cached hashes, so the next root rehashes the whole queue.
    • When the processed prefix is empty, skip the take/set entirely, or keep the original list.
  3. ProgressiveList::sorted_reader allocates a Vec per call (progressive_list.rs).

    • This runs once per attestation, with about log₂(n) entries. It's negligible, but it could be lazy by building per-subtree readers on demand from current.

Maintainability

  1. The blind-write comment and loop are copy-pasted four times.

    • A ParticipationMut::apply(&mut self, updates: impl IntoIterator<Item = (ValidatorIndex, ParticipationFlags)>) -> Result<()> would keep the invariant documentation in one place.
    • It would also remove the duplicated IndexOutOfBounds construction.
    • Electra and deneb/altair can't use it directly, since they hold &mut EpochParticipation. A small generic helper over anything with a set would cover them too.
    • In electra.rs the copied comment exceeds the surrounding line width after re-indentation; rustfmt won't fix comments.
  2. rebase_participation_on (containers/mod.rs).

    • The mixed if let (Ok, Ok) / else if let (Gloas, Gloas) structure is correct.
    • Fulu→gloas pairs no-op because of the inner Bounded pattern, and gloas→fulu pairs fall through.
    • It's subtle, though. Mirroring rebase_pending_deposits_on's explicit match on (self, base) would read more clearly.
  3. DB_VERSION unchanged.

    • This is fine provided every persisted state and delta path goes through SSZ. Please confirm that beacon_state_delta doesn't snapshot these fields through any other encoding; only its test changed here.

Nits

  • SortedReader and ProgressiveSortedReader each run their own debug_assert on last, so the order is checked twice per read on gloas. This is harmless.
  • ParticipationRef: PartialEq compares contents across list kinds, while ptr_eq is never true across kinds. Both are fine; a one-line doc note on PartialEq would make the difference explicit.

Overall this looks good to merge once Item 1 (a cheap guard) and Item 2 (documenting the invariant) are addressed. Item 4 is worth a follow-up.


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

@github-actions

Copy link
Copy Markdown

🤖 Gemini Code Review

This PR looks great. The additions to ethlambda_ssz_tree (repeat, set, and SortedReader / ProgressiveSortedReader) and the migration of EpochParticipation and PendingDeposits to tree-backed lists are clean, well-tested, and well-documented.

A few highlights from reviewing the implementation:

  • Tree::repeat (crates/common/ssz-tree/src/tree.rs:179-223): Bottom-up construction sharing a single Arc for full nodes at each level while isolating the right-edge partial path (tail) is sound, and COW invariants on subsequent mutations are well-covered by the unit tests.
  • SortedReader & set in process_attestation (altair.rs, deneb.rs, electra.rs, gloas.rs): Using sorted_reader() on the sorted, deduplicated attesting_indices and set(index, current_flags | new_flags) in the write phase avoids per-attester tree descents on both reads and writes while preserving exact semantics.
  • scan (crates/blockchain/state_transition/src/beacon/helpers/participation.rs:141-146): Walking previous_list.iter() and current_list.iter() at the top of the validator loop keeps the iterators in lockstep with index and preserves the out-of-bounds error behavior when a participation list is shorter than the validator registry.
  • tree_fields! & rebase_on (crates/common/types/src/beacon/containers/mod.rs:437-467, 1219-1302): All forks from Altair through Gloas properly register the new tree-backed fields for apply_updates and rebase_on.

No issues found — LGTM.


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

@github-actions

Copy link
Copy Markdown

🤖 Grok Code Review

⚠️ Review failed: Grok API request failed: curl exit code 56


Automated review by Grok (xAI)

@github-actions

Copy link
Copy Markdown

🤖 Kimi Code Review

⚠️ Review failed: Kimi API request failed: curl exit code 56


Automated review by Kimi (Moonshot AI)

@github-actions

Copy link
Copy Markdown

🤖 DeepSeek Code Review

Reviewed the tree-backed migration for participation lists and pending_deposits. The repeat/set/root-equality tests are good, but I have a few concerns:

  • Sorted-reader order assumption is consensus-critical.
    SortedReader::get in crates/common/ssz-tree/src/interface.rs only enforces non-decreasing indices with debug_assert, and ProgressiveSortedReader::get in crates/common/ssz-tree/src/progressive_list.rs does index - *start without checked_sub. If attesting_indices are not strictly nondecreasing, release builds can return wrong flags or None for valid attesters, especially for gloas after the reader has advanced past a subtree.
    Ethereum’s get_attesting_indices is not inherently sorted because committees are shuffled. Please verify ethlambda’s helper explicitly sorts before process_attestation; if not, sort it or make the reader robust for arbitrary indices.

  • Blind set write relies on distinct attester indices.
    In stf/altair.rs, stf/deneb.rs, stf/electra.rs, and stf/gloas.rs, the write phase now stores current_flags | new_flags and writes with set. This is correct only if each index appears at most once. The comment says the signature set refuses repeats, but this must be true for all four variants; otherwise the old |= would have merged duplicates while the new set overwrites with the second full flags value, potentially losing flags.

  • API change may leave slice-specific callers behind.
    altair_validator_lists now returns ParticipationRef instead of &[ParticipationFlags], and epoch_participation_mut returns ParticipationMut instead of &mut [ParticipationFlags]. The updated scan/attestation paths are fine, but any remaining caller using slice-only operations such as binary_search, copy_from_slice, or chunks will fail or need rework.

  • Minor: ParticipationRef PartialEq compares by value across list kinds.
    A bounded and a progressive list with equal contents compare equal. That may be surprising if this type is ever used to distinguish forks or to gate rebase behavior; currently it is not, but worth documenting.

  • Pending-deposit epoch copy cost is real but intentional.
    take_pending_deposits now copies all queued deposits with .to_vec(). The included benchmark acknowledges this. Fine for the PR, but worth keeping an eye on for large queues.

The tree-backed sharing and root-equality coverage look otherwise solid.


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

ProgressiveSortedReader::get subtracted the current subtree's start from
an index below it, which wraps in release builds and answers None for an
element that exists. SortedReader answers right on a step back and only
pays a descent. The progressive one now restarts from the first subtree
when the index is below the subtree it last read, or after a read past
the end, so both readers keep one contract. In-order reads take the same
path as before; the existing reader-vs-get test, which reads past the
end, covers the restart after an end read.
…rite exact

Each fork's process_attestation said its attesting indices are sorted and
distinct because of a signature set built above. No such set is built
there: is_valid_indexed_attestation, verified just before the read phase,
refuses any index list that is not strictly ascending, in release builds
too. Both comments now name it, and electra's no longer runs past the
line width.
…cument two read invariants

rebase_participation_on reached gloas through an else-if that ran only
because altair_validator_lists_mut fails on a gloas state. It now matches
the gloas pair by name first, then the bounded pair, with the same
outcome for every pairing.

ParticipationRef's PartialEq compares entries across list kinds; its doc
now says so and points to ptr_eq. Tree::Zero's doc says a Zero only ever
stands past the end of the data, which Tree::get and leaf_run rely on.
@MegaRedHand

MegaRedHand commented Nov 20, 2026 •

Copy link
Copy Markdown
Collaborator Author

Round one (the automated review of 0960567). Fixed in ca69a1d, 46cc758 and 74690a0. make fmt, make lint and cargo clippy -p ethlambda-state-transition --all-targets --features beacon-spec-tests -- -D warnings are clean. Tests are left to CI.

Fixed

  • DeepSeek 1, the progressive reader out of order: ProgressiveSortedReader::get subtracted the current subtree's start from a smaller index. In a release build that wraps and answers None for an element that exists. SortedReader stays right on a step back, at the cost of a descent. The progressive reader now does the same: below the subtree it last read, or after a read past the end, it searches again from the first subtree. In-order reads are unchanged. No test runs the new restart yet: the existing reader-vs-get test reads past the end only once, as its last read. The step back itself cannot be tested in the test profile, where the reader's order debug_assert fires first.
  • Claude 1, DeepSeek 1 and 2, why the indices are ascending and distinct: the four process_attestation comments credited "the signature set built above". The check that holds it is is_valid_indexed_attestation, verified just before the read phase in all four forks. It refuses any index list that is not sorted and unique, in release builds too. Both comments now name it. Electra's no longer runs past the line width (Claude 7).
  • Claude 8, rebase_participation_on: it now matches the gloas pair by name first, then the bounded pair. Before, gloas was reached through an else if that ran only because altair_validator_lists_mut fails on a gloas state. Same outcome for every pairing, including the two that straddle the gloas upgrade.
  • Claude 2, Tree::Zero: its doc now says a Zero only ever stands past the end of the data, and that get and leaf_run rely on it to mean "past the end".
  • Claude, DeepSeek 4, ParticipationRef: PartialEq: documented as comparing entries across list kinds, with a pointer to ptr_eq.

Not changed

  • Claude 1, a debug_assert! on the indices: is_valid_indexed_attestation already enforces the order in release, and each reader asserts it on every read.
  • Claude 3, repeat's unreachable!: its message, "a tree that fits groups up into one root", sits right under the fit assert.
  • Claude 4 and 5, DeepSeek 5, the pending-deposit rebuild: about 1 ms plus 3 ms of hashing per epoch for 20k deposits (measured in the description), in place of a rehash on every block. Keeping the hashes across a dropped prefix needs re-chunking.
  • Claude 6, the reader's Vec: log n entries per attestation.
  • Claude 7, one shared write helper: each fork keeps its own process_attestation, and they hold different handles.
  • Claude 9, DB_VERSION: the state delta diffs the SSZ encoding, which this PR keeps byte-identical.
  • DeepSeek 3, slice-only callers: make lint builds every target, so one left behind would not compile.

Codex and Gemini found nothing to change. Grok's and Kimi's jobs failed (curl exit 56) and produced no review.

@MegaRedHand

Copy link
Copy Markdown
Collaborator Author

/review

@github-actions

Copy link
Copy Markdown

AI security review: 0 finding(s) to check

Reviewed by Opus, GPT, Kimi, GLM, DeepSeek.
Malicious-code check (tests, build and install scripts, hooks, editor tasks, dependency sources): nothing found.

No findings to check.

Housekeeping (not security): 7

Stale docs, missing tests, leftovers and inconsistencies, from a separate cheap model. Not checked by the judge.

Kind Item Where Fix
stale-docs PendingQueueFields doc: stale container types for pending_deposits crates/blockchain/state_transition/src/beacon/helpers/electra.rs:1047 Update to describe tree-backed types, remove deref to [T] claim.
stale-docs participation module doc: participation slices crates/blockchain/state_transition/src/beacon/helpers/participation.rs:9 Replace 'participation slices' with 'participation entries'.
stale-docs gloas epoch module doc: participation list type and deref stale crates/blockchain/state_transition/src/beacon/stf/epoch/gloas.rs:17 Update to ethlambda_ssz_tree::ProgressiveList for participation; remove Deref claim.
stale-docs process_justification_and_finalization doc: 'as plain slices' for participation crates/blockchain/state_transition/src/beacon/stf/epoch/mod.rs:127 Replace 'as plain slices, since gloas progressive rather than SszList' with 'through ParticipationRef'.
stale-docs fulu.rs process_deposit_request doc: stale PendingDeposits type crates/blockchain/state_transition/src/beacon/stf/fulu.rs:358 Replace 'libssz_types::ProgressiveList' with 'ethlambda_ssz_tree::ProgressiveList'.
stale-docs rewards test comment: plain slices and Deref to [T] for participation crates/blockchain/state_transition/tests/beacon_spec/rewards.rs:134 Update to say participation lists are accessed through ParticipationRef; remove Deref to [T] claim.
stale-docs docs: 'flat participation slices' is stale docs/beacon_stf.md:364 Change 'flat participation slices' to 'ParticipationRef iterators'.

Cost of this review: ~$5.34 of a $30 budget (estimated from token counts).

…g deposits where docs still said slices

The move to tree-backed lists left seven places describing the old
shapes:
1. PendingQueueFields said all three queues deref to [T] and offer
   slice views. pending_deposits is now a tree-backed list, reached
   only through push, take and set.
2. The participation module said its scan zips the registry against
   participation slices.
3. The gloas epoch module doc named libssz_types::ProgressiveList for
   all five progressive fields, and said the participation steps read
   plain slices.
4. process_justification_and_finalization said the same.
5. fulu's process_deposit_request named the wrong ProgressiveList for
   gloas's pending deposits.
6. The rewards spec-test runner's comment, and the same comment in the
   epoch_processing runner, said the lists deref to [T].
7. beacon_stf.md spoke of flat participation slices.

Each now names ParticipationRef (or InactivityScoresRef) and the
ethlambda_ssz_tree lists.
@MegaRedHand

Copy link
Copy Markdown
Collaborator Author

Round two (the automated review of 109b8f8). Fixed in 0428fb8, comments and docs only. make fmt, make lint and cargo clippy -p ethlambda-state-transition --all-targets --features beacon-spec-tests -- -D warnings are clean. Tests are left to CI.

The review raised no security findings. I checked each of the seven housekeeping items against the code, and all were stale docs from the move to tree-backed lists. Each is fixed in that one commit:

Fixed

  • PendingQueueFields: pending_deposits is no longer a slice. It is an ethlambda_ssz_tree::List (electra, fulu) or ProgressiveList (gloas), reached through push_pending_deposit and take_/set_pending_deposits. The doc now says only the other two queues have slice views.
  • The participation module doc: the scan walks iter_validators() in lockstep with the lists' ParticipationRef iterators, not slices.
  • The gloas epoch module doc: the participation lists and pending_deposits are ethlambda_ssz_tree::ProgressiveLists, and inactivity_scores and pending_consolidations are libssz_types::ProgressiveLists. The participation steps read through ParticipationRef/InactivityScoresRef, not Deref to [T].
  • process_justification_and_finalization: the gloas lists are reached as ParticipationRefs.
  • Fulu's process_deposit_request: gloas's PendingDeposits is an ethlambda_ssz_tree::ProgressiveList. The partial-withdrawal docs that name libssz_types::ProgressiveList are still right and unchanged.
  • The rewards runner's comment: reworded. The epoch_processing runner had the same sentence; fixed too.
  • docs/beacon_stf.md: no more "flat participation slices".

@MegaRedHand

Copy link
Copy Markdown
Collaborator Author

/review

@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.

I read this together with #761, at 0428fb8. The sorted reader and the blind writes are exact for the reasons the comments give, and merged with #761 every fork's process_attestation makes one sorted pass and reads each attester once. Two places where the tree still costs more than it needs to, inline; the second may be part of the process_epoch +7.6 ms the description says is still being profiled.

}

/// The flags at `index`, or `None` past the end. A tree descent.
pub fn get(&self, index: usize) -> Option<&'a ParticipationFlags> {

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.

pack_attestations (block_production.rs:265, outside the diff) still calls this once per attester of every candidate to count new attesters, so each call is now a tree descent where it used to be a slice read. It only runs when proposing, but over the whole pool. get_attesting_indices returns sorted indices, so sorted_reader() fits there the same way it does in process_attestation.

match self {
PendingQueueFields::Electra(state) => {
core::mem::take(&mut state.pending_deposits).into_inner()
core::mem::take(&mut state.pending_deposits).to_vec()

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.

The epoch code takes the whole queue out here, and set_pending_deposits builds a fresh tree from the Vec (single_pass.rs:535, stf/epoch/electra.rs:540). So every epoch boundary copies every pending deposit and discards all the cached hashes, even when no deposit was applied or postponed. When remaining is the queue unchanged, leaving the list in place would keep its root. to_vec() here also clones each deposit where into_inner() used to move it.

Could this be part of the process_epoch regression?

@github-actions

Copy link
Copy Markdown

AI security review: 0 finding(s) to check

Reviewed by Opus, GPT, Kimi, DeepSeek.
GLM (stopped) did not finish; Opus, GPT, Kimi, DeepSeek reviewed the whole PR. Comment /review continue to retry, with a new budget; reviewers that finished are reused.
Malicious-code check (tests, build and install scripts, hooks, editor tasks, dependency sources): nothing found.

No findings to check.

Cost of this review: ~$5.21 of a $30 budget (estimated from token counts).

@MegaRedHand
MegaRedHand added this pull request to the merge queue Nov 20, 2026
Merged via the queue into main with commit 5c7435e Nov 20, 2026
14 checks passed
@MegaRedHand
MegaRedHand deleted the perf/tree-backed-participation branch November 20, 2026 03:15
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

beacon Ethereum Beacon Chain client performance Performance improvements or possible performance improvements

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants