feat: host-side prerequisites for the embedded beacon chain plugin (SSZ ulong limits, injectable discv5 ENR filter)

[asdacap]

Changes

The two host-side prerequisites of the embedded beacon-chain driver plugin (#11976), isolated so the plugin can be compiled and loaded as a standalone DLL (via the plugins/ directory) without the main PR:

• SSZ generator: list limits beyond int range. Beacon-chain lists use limits up to 2^40 (VALIDATOR_REGISTRY_LIMIT), which overflowed the int-typed SszListAttribute. The limit is now ulong end to end; decode-side count guards are omitted when the limit exceeds int.MaxValue (an int-typed count can never violate them). Regression test asserts the spec merkle root for a 2^40-limit list (basic and composite element paths).
• discv5: injectable consensus-only-ENR drop policy. The shared stack hard-dropped consensus-only node records in three places (NodesResponseHandler, KademliaAdapter acceptance, NodeSource). Discv5RecordFilter makes the policy injectable, defaulting to the existing execution-layer behavior (no functional change); a beacon-chain discovery scope registers AcceptAll.

No plugin code and no plugin registration here — with this branch in the host build, Nethermind.BeaconChain.dll (from #11976) is a drop-in plugin.

Types of changes

What types of changes does your code introduce?

• Bugfix (a non-breaking change that fixes an issue)
• New feature (a non-breaking change that adds functionality)
• Breaking change (a change that causes existing functionality not to work as expected)
• Optimization
• Refactoring
• Documentation update
• Build-related changes
• Other: Description

Testing

Requires testing

• Yes
• No

If yes, did you write tests?

• Yes
• No

Notes on testing

• Nethermind.Serialization.SszGenerator.Test: 52/52 (incl. the new 2^40-limit known-answer test).
• Nethermind.Network.Discovery.Test: 242/242 (1 pre-existing skip) — EL default filter behavior unchanged.

Documentation

Requires documentation update

• Yes
• No

Requires explanation in Release Notes

• Yes
• No

Remarks

Based on generic-kad-2 (the discv5 filter touches that branch's code). Extracted from #11976, which builds on this.

🤖 Generated with Claude Code

[claude]

Claude finished @asdacap's task in 5m 12s —— View job

---

Review: feat: host-side prerequisites for the embedded beacon chain plugin

• Read changed files
• Analyze SSZ ulong limit changes
• Analyze discv5 injectable filter changes
• Check tests
• Post review findings

---

Summary

Both changes are well-scoped and correct for the stated purpose. The SSZ ulong-limit change accurately propagates ulong end-to-end (attribute → generator → helpers → merkleization), and the discv5 filter change is cleanly injectable with zero behavioral change to the EL default path. Tests cover the 2^40-limit known-answer case and verify EL filter behavior remains unchanged.

One Medium inconsistency was found: ValidateSszBitlistLimit was not updated alongside ValidateSszListLimit, leaving it with an int limit parameter. This doesn't affect the beacon chain use case (no bitlist has a limit > int.MaxValue) but would produce a compile error if ever triggered.

---

Findings

Medium

ValidateSszBitlistLimit not updated for huge limits (line 648, SszGenerator.cs)

ValidateSszListLimit was correctly updated to ulong limit, but ValidateSszBitlistLimit (called from both Kind.BitList and the dead Kind.List when "BitArray" arm) still takes int limit. The code emits {property.Limit} — a ulong? — directly as an int argument. For limits ≤ int.MaxValue this compiles fine; for larger limits it produces a compile error in the downstream generated file.

The Kind.List when "BitArray" arm on line 648 is dead code (Kind.BitList is always emitted for a BitArray + [SszList] property per the Kind getter), but line 651 (Kind.BitList) is live.

Suggested fix — apply the same "skip guard for limits beyond int.MaxValue" pattern:

Kind.BitList => property.Limit is <= int.MaxValue
    ? $"ValidateSszBitlistLimit({expression}, {property.Limit}, nameof({decl.TypeReferenceName}), nameof({property.Name}));"
    : string.Empty,

Or lift ValidateSszBitlistLimit to ulong limit. Neither approach affects the current beacon chain bitlist sizes.

---

Low

NodesResponseHandler takes nullable Discv5RecordFilter? (line 13, NodesResponseHandler.cs)

The only call site is KademliaAdapter.FindNeighbours, which always passes a non-null filter. The nullable default is never exercised in production. Minor inconsistency with NodeSource and KademliaAdapter, which take non-nullable.

---

Notes (no action required)

• SszListAttribute(ulong limit) backward compat: The constructor change from int to ulong is non-breaking in practice. C#'s implicit constant-expression conversion allows const int values and integer literals to flow without a cast (§10.2.11 of the spec), so all existing [SszList(n)] usages compile without modification — confirmed by grepping all call sites.
• Merkleization correctness: The MerkleizeBasicList chunkCount calculation (limit × itemSize + 31) / 32 correctly uses ulong arithmetic throughout; the test's reference root Limit / 4 matches the helper's computation for 8-byte ulongs. ✓
• Discv5RecordFilter.Excludes() logic: Short-circuit evaluation on !acceptConsensusOnlyRecords ensures IsConsensusOnlyNodeRecord is never called for AcceptAll. ✓
• DI override path: KademliaModule registers ExecutionLayer as a singleton; the beacon-chain plugin can override by registering AcceptAll in the same or child scope (last-registered wins in Autofac). ✓

[claude]

Medium — ValidateSszBitlistLimit still takes int limit, but property.Limit is now ulong?.

Line 648 (Kind.List when "BitArray" — dead code per Kind getter, but still present) and line 651 (Kind.BitList) both emit {property.Limit} without a UL suffix into a call to ValidateSszBitlistLimit(BitArray? bits, int limit, ...). If a beacon chain type ever declares a bitlist with a limit > int.MaxValue, the generator will emit code that doesn't compile.

The Kind.List when "BitArray" arm can never fire (because a BitArray + [SszList] property resolves to Kind.BitList in the Kind getter), but the Kind.BitList arm on line 651 is live.

Consistent fix (same approach used everywhere else in this PR):

Kind.BitList => property.Limit is <= int.MaxValue
    ? $"ValidateSszBitlistLimit({expression}, {property.Limit}, nameof({decl.TypeReferenceName}), nameof({property.Name}));"
    : string.Empty,

Or change ValidateSszBitlistLimit to take ulong limit and update the comparison to (ulong)bits.Length > limit.

Beacon chain bitlists currently have limits ≤ int.MaxValue (MAX_VALIDATORS_PER_COMMITTEE = 2048), so this doesn't affect the PR's stated use case — but the inconsistency is real and would produce a compile error rather than a silent bug if triggered.

[asdacap]

Fixed in 2d06a9f (note: this reply is from the agent — Claude Code, model Claude Fable 5 — working on @asdacap's behalf). ValidateSszBitlistLimit now takes ulong limit with a (ulong)bits.Length comparison, the Kind.BitList emission carries the UL suffix, and the bitlist Encode emission clamps to int.MaxValue (that runtime parameter is int-typed and unused, and a BitArray cannot exceed int.MaxValue bits anyway). The dead Kind.List when BitArray arm is removed — such properties always resolve to Kind.BitList in the Kind getter. The huge-limit regression test now also declares a 2^40-limit bitlist, which fails to compile without the fix.

[claude]

Low — nullable Discv5RecordFilter? inconsistency. NodesResponseHandler takes Discv5RecordFilter? recordFilter = null with a null fallback inside Handle, while NodeSource and KademliaAdapter take a non-nullable Discv5RecordFilter recordFilter. The nullable default is never exercised in production (the only caller is KademliaAdapter.FindNeighbours, which always passes recordFilter). Consider making it required (non-nullable, no default) to match the rest of the API.

[asdacap]

Already addressed in b08af23, which landed after this review ran (reply from the agent — Claude Code, model Claude Fable 5 — on @asdacap's behalf): the filter is now a dedicated IDiscv5RecordFilter interface and a required, non-nullable dependency at every record-handling component — no optional parameters or null-coalesced defaults remain, including in NodesResponseHandler.

[claude]

Claude finished @asdacap's task in 4m 52s —— View job

---

Review: feat: host-side prerequisites for the embedded beacon chain plugin

• Read relevant agent rules (coding-style, robustness, di-patterns, test-infrastructure)
• Examine changed files in detail
• Check SSZ ulong limit changes (SszGenerator.cs, SszProperty.cs, SszSerializableAttribute.cs)
• Check discv5 injectable filter changes (IDiscv5RecordFilter.cs, KademliaAdapter.cs, NodeSource.cs, NodesResponseHandler.cs, KademliaModule.cs)
• Check tests
• Verify previous Medium/Low findings are resolved
• Post final review

---

Summary

Both changes are correct and complete. The SSZ ulong limit change is propagated end-to-end with no gaps, and the discv5 record filter is cleanly injectable with zero behavioral change to the EL default path. The two previously-raised issues (Medium: ValidateSszBitlistLimit not updated; Low: nullable filter parameter) are fully resolved.

---

Previous findings — resolved ✓

• Medium (commit 2d06a9f) — ValidateSszBitlistLimit now takes ulong limit with (ulong)bits.Length comparison; the dead Kind.List when "BitArray" arm is removed; the bitlist Encode emission clamps via Math.Min(property.Limit!.Value, int.MaxValue) for the unused int-typed Encode parameter.
• Low (commit b08af23) — IDiscv5RecordFilter is now a required non-nullable dependency at all three Kademlia-layer sites; no nullable defaults or null-coalescing remain.

---

Low

DiscoveryV5App.TryGetAcceptableNodeFromEnr has a fourth hard-coded IsConsensusOnlyNodeRecord call (DiscoveryV5App.cs:190)

This is intentionally out of this PR's stated scope (which targeted three Kademlia-layer sites: NodesResponseHandler, KademliaAdapter, NodeSource). TryGetAcceptableNodeFromEnr is called from AddNodeToDiscovery and AddBootNode in the EL app layer — a beacon-chain plugin would have its own app layer and would not reach this code path. No action required here, but worth flagging as the one remaining hard-coded filter site for future reference.

---

Notes (no action required)

• ulong propagation completeness: All limit emissions in ValidationStatement, MerkleizeRootStatement, MerkleizeEmptyCollectionRootStatement carry the UL suffix; all three decode-side pre-allocation guards are conditioned on property.Limit is <= int.MaxValue (correctly safe since int-typed counts can never exceed int.MaxValue).
• Math.Min(property.Limit!.Value, int.MaxValue) for BitList Encode: property.Limit.Value is ulong; int.MaxValue is a compile-time constant within ulong range and implicitly converts under §10.2.11 of the C# spec. The result is emitted as a decimal string (e.g. 2147483647) without suffix, which is a valid int literal at the call site. ✓
• SszListAttribute(ulong limit) backward compat: Existing [SszList(n)] call sites with int/constant literals continue to compile via §10.2.11 implicit constant-expression conversions; SszProperty.From() handles both ulong and int attribute argument types. ✓
• DI registration: KademliaModule registers ExecutionLayerDiscv5RecordFilter.Instance directly (valid — passing a pre-constructed instance avoids factory overhead for a stateless singleton). A beacon-chain plugin overrides with AcceptAllDiscv5RecordFilter in the same or child scope (last-registered wins in Autofac). ✓
• Thread safety in NodesResponseHandler.Handle(): recordFilter.Excludes() is called inside _lock. Both filter implementations are stateless. ✓
• Test coverage: The new Supports_list_limits_beyond_int_range test covers basic list, composite list, and bitlist paths at 2^40 limit, with known-answer merkle root assertions. ✓

[flcl42]

Why do we need to care about int if the attribute receives ulong now?

[flcl42]

src\Nethermind\Nethermind.Serialization.SszGenerator\Attributes.cs need to be changed too for consistency ig.

[asdacap]

Right, we don't — fixed in 4cd7a63. The attribute is ulong now, so ConstructorArguments[0].Value is always a boxed ulong; the int switch arm was dead. Parsed directly as Value as ulong? ?? 0UL.

(Reply from the agent — Claude Code, model Claude Opus 4.8 (1M context) — on @asdacap's behalf.)

[asdacap]

Done in 4cd7a63 — the generator's Attributes.cs mirror of SszListAttribute now takes ulong limit / ulong Limit, matching the runtime attribute in Nethermind.Serialization.Ssz.

(Reply from the agent — Claude Code, model Claude Opus 4.8 (1M context) — on @asdacap's behalf.)

[flcl42]

No need in comment

[asdacap]

Removed the <remarks> block, kept the one-line <summary>. 4cd7a63.

(Reply from the agent — Claude Code, model Claude Opus 4.8 (1M context) — on @asdacap's behalf.)

[flcl42]

Probably should be a generator error about not supporting it

[asdacap]

Agreed — done in 4cd7a63. Instead of silently clamping, the generator now rejects a BitArray list whose limit exceeds int.MaxValue at parse time (in SszProperty.From), surfaced through the existing SSZ003 generator error — a BitArray cannot hold more than int.MaxValue bits, so such a limit is meaningless. The Encode site then just emits property.Limit.Value (now guaranteed in range). Dropped the huge-limit bitlist test type and added a Bitlist_with_limit_beyond_int_range_reports_diagnostic regression test.

(Reply from the agent — Claude Code, model Claude Opus 4.8 (1M context) — on @asdacap's behalf.)