Implement gossip verification of inclusion lists

[rahulbarmann]

Issue Addressed

Part of FOCIL (EIP-7805). Follow-up to #9846, which wired up the inclusion_list topic but ignored every message.

Proposed Changes

• Add a new inclusion_list_verification module that runs the validate_inclusion_list_gossip checks in the order defined by the spec, with unit tests in tests.rs.
• Make the gossip handler add verified lists to the store and decide whether to propagate based on the store result. This means concurrent workers can't end up forwarding a third list from the same validator.
• Re-key the store's first-or-second count by (dependent_root, validator), following consensus-specs#5605.
• Make InclusionListStore::process_inclusion_list take a GossipVerifiedInclusionList instead of a raw list and timeliness flag.
• Change inclusion_list_signature_set to take the genesis_validators_root instead of a state.
• Add ChainSpec::get_inclusion_list_due for the timeliness check.

Additional Info

The transaction bounds check is copied from #10008 and get_inclusion_list_due from conache#8, so whichever PR merges second will need a small rebase.

[eserilev]

tests claude thinks we might want to add:

inclusion_list_verification/tests.rs

1. Edge of the clock window. future_slot (line 194) and past_slot (line 210) test only slots outside the allowed window. Add tests where the clock is a few ms before slot N+1 and a list for N+1 is accepted, and a few ms after slot N and a list for N is accepted but marked not timely. These cover the MAXIMUM_GOSSIP_CLOCK_DISPARITY allowance.
2. Committee on a fork. The committee() helper (line 72) uses the head block root, and all tests build one straight chain. So a bug that took the committee from the head state instead of the dependent root's state would pass. Add a test with two branches whose committees differ. Sign a list from the non-head branch's committee. It has to pass, and a list from the head's committee has to fail.
3. A failed check does not count. Send a list with a bad signature, then two valid lists from the same validator. Both valid lists have to pass. The count is allowed to increase only after a list passes every check.
4. First Heze epoch. Add a test for a slot in HEZE_FORK_EPOCH. The dependent state is still Gloas there. Check that the committee and the signature domain (Heze fork version) are correct.

network_beacon_processor/tests.rs
5. Equivocation mapping. The new test (test_gossip_inclusion_list_propagation_follows_the_store_outcome) checks only the first message (Accept) and an exact duplicate (Ignore). Add a test where a different second list from the same validator gives Equivocating and Accept, so it is forwarded. A third list has to give SubsequentEquivocation and Ignore. Also check that a REJECT result applies a peer penalty.

[rahulbarmann]

@eserilev added all of these, thanks!

[conache]

Adding one more case we might want to add a test for - from claude too:

To be added in inclusion_list_verification/tests.rs.

Possible dependent block at the boundary. The [IGNORE] check requires a child strictly after dependent_slot (child.slot > dependent_slot), but no test fails if it becomes >=. Add a test where the dependent root R is not the head and its only child sits exactly at dependent_slot. A list with dependent_root = R has to be ignored with InvalidDependentRoot, since on that branch the child, not R, is the latest block at or before dependent_slot.

[SamAg19]

PR #10228 which enabled inclusion_list SSE event to be emitted was merged in the focil devnet branches so can those changes be incorporated in this PR itself or is the plan to introduce it in a subsequent PR when this PR is merged?

[rahulbarmann]

good call, thanks! pulled it in here

[eserilev]

we are reading the slot clock twice, this could cause a race condition. it's on on the order of a microsecond, so not realistic tbh. but still i think its cleaner to read the slot clock once

something like:

let now = ctx
    .slot_clock
    .now_duration()
    .ok_or(InclusionListVerificationError::UnableToReadSlot)?;
let current_slot = ctx
    .slot_clock
    .slot_of(now)
    .ok_or(InclusionListVerificationError::UnableToReadSlot)?;

[rahulbarmann]

that makes sense, thanks! switched to reading it once

[eserilev]

i'm wondering if validator_counts is even necessary? could we just check equivocators directly?

[rahulbarmann]

good point, it was always the same as being in equivocators, so removed it

[eserilev]

nit:

// The block with root dependent_root is after dependent_slot.

[rahulbarmann]

done f6c430e

[eserilev]

I think we need to get the actual seen_timestamp (like when we actually first saw the IL). if we calculate it here we are ignoring the time that the IL sat in the beacon processor/got requeued etc

you can get that info in router.rs and pass it down to here

[rahulbarmann]

done, it's now passed down from the router and used for the timeliness check

[eserilev]

can we add gossip metrics for IL's? we do a similar thing for payload atteestations.

we can add a counter for

• IL processing requests
• IL processing sucecess
• IL verification errors

also maybe a metric for equivocations

[rahulbarmann]

added the request, success and per-type error counters, plus one for equivocations

[eserilev]

nice, lgtm!

[mergify]

Queued — the merge queue status continues in this comment ↓.

[mergify]

Merge Queue Status

• ✅ Entered queue — 2026-10-12 04:40 UTC · Rule: default · triggered by rule Add ready-to-merge labeled PRs to merge queue
• ✅ Checks passed · on draft merge queue: checking #10182 on unstable (97c3aaa), stacked on #10304 and #10234 #10311
• ✅ Merged — 2026-10-12 05:10 UTC · at f83aeef6ddd55871f8e0684daae6134b24d5a0fb · squash

This pull request spent 30 minutes 10 seconds in the queue, including 28 minutes 19 seconds running CI.

Required conditions to merge

• check-success=local-testnet-success
• check-success=test-suite-success
• github-review-approved [🛡 GitHub branch protection]
  • Implement gossip verification of inclusion lists #10182