Skip to content

feat(rpc): emit single_attestation on /eth/v1/events - #757

Open
MegaRedHand wants to merge 11 commits into
feat/beacon-gloas-eventsfrom
feat/beacon-single-attestation-event
Open

MegaRedHand wants to merge 11 commits into
feat/beacon-gloas-eventsfrom
feat/beacon-single-attestation-event

Conversation

@MegaRedHand

Copy link
Copy Markdown
Collaborator

Motivation

ethPandaOps' contributoor (the xatu sentry behind lab.ethpandaops.io) subscribes to single_attestation and never to attestation. ethlambda accepted a single_attestation subscription but never sent anything on it, so the lab shows no attestation data for our nodes, while Lighthouse nodes running the same contributoor config do send it.

Stacked on #748, whose GossipEventSink this reuses.

Description

Two commits, so the second can be dropped on its own:

  1. Gossip (feat(rpc): emit single_attestation for gossip-accepted subnet attestations): subnet attestations are validated in ethlambda-p2p and never reach the chain actor, so publish_gossip_event (p2p/src/beacon/verdict.rs) reports an accepted one as GossipEvent::SingleAttestation, which the event bus maps to ChainEvent::SingleAttestation on Topic::SingleAttestation. This is the highest-rate event the node has, so the attestation is cloned only when a client is subscribed, and the payload is boxed. The payload is the existing electra SingleAttestation container, so the JSON is the spec's.
  2. API (feat(rpc): emit single_attestation for API-submitted attestations): POST /eth/v2/beacon/pool/attestations reports each attestation that passed validation and was handed to the network actor, the spec's "(from P2P or API)" half. Kept separate because emitting our own validators' attestations, with near-zero propagation time, can link validator indices to the node (why contributoor makes the topic opt-in). Dropping it would need a line in docs/spec_deviations.md.

docs/rpc.md moves single_attestation from "never emitted" to the emitted table.

Note for the lab: contributoor derives the subnet as committee_index % 64, which only equals the real subnet with 64 committees per slot. On Sepolia (1 committee per slot) it drops every attestation, so this shows up on mainnet and Hoodi only.

How to test

  • cargo test -p ethlambda-blockchain --lib events (spec example JSON shape, gossip event to topic mapping)
  • cargo test -p ethlambda-p2p --lib (accepted attestation reaches the sink only on Accept and only when subscribed)
  • cargo test -p ethlambda-rpc --lib (an accepted API attestation reaches the bus, a refused one does not)
  • Live: curl -N 'localhost:5052/eth/v1/events?topics=single_attestation' on a beacon node.

…tions

ethPandaOps' contributoor subscribes to single_attestation and never to
attestation, and ethlambda accepted that topic without ever sending it, so
the lab showed no attestation data for our nodes.

Subnet attestations are validated in ethlambda-p2p and never reach the chain
actor, so p2p reports an accepted one through the GossipEventSink that #748
added, and the event bus maps it to a ChainEvent on Topic::SingleAttestation.
It is the highest-rate event the node has (every attestation on its backbone
subnets), so the attestation is cloned only when a client is subscribed, and
the payload is boxed to keep the broadcast ring sized for the smaller
variants. The payload is the existing electra SingleAttestation container, so
its JSON form is the specification's.
This is the specification's "(from P2P or API)" half of single_attestation:
POST /eth/v2/beacon/pool/attestations now reports each attestation that
passed validation and was handed to the network actor, the way the other
API handlers report what a validator client or builder submits.

It is a separate commit because emitting our own validators' attestations,
with near-zero propagation time, can link validator indices to this node,
which is why contributoor makes the topic opt-in. Dropping this commit leaves
the gossip-accepted events alone; docs/spec_deviations.md would then need a
line saying API submissions are not reported.
MegaRedHand added a commit that referenced this pull request Nov 2, 2026
feat(rpc): emit single_attestation for gossip-accepted subnet attestations

ethPandaOps' contributoor subscribes to single_attestation and never to
attestation, and ethlambda accepted that topic without ever sending it, so
the lab showed no attestation data for our nodes.

Subnet attestations are validated in ethlambda-p2p and never reach the chain
actor, so p2p reports an accepted one through the GossipEventSink that #748
added, and the event bus maps it to a ChainEvent on Topic::SingleAttestation.
It is the highest-rate event the node has (every attestation on its backbone
subnets), so the attestation is cloned only when a client is subscribed, and
the payload is boxed to keep the broadcast ring sized for the smaller
variants. The payload is the existing electra SingleAttestation container, so
its JSON form is the specification's.

Second commit: feat(rpc): emit single_attestation for API-submitted attestations

This is the specification's "(from P2P or API)" half of single_attestation:
POST /eth/v2/beacon/pool/attestations now reports each attestation that
passed validation and was handed to the network actor, the way the other
API handlers report what a validator client or builder submits.

It is a separate commit because emitting our own validators' attestations,
with near-zero propagation time, can link validator indices to this node,
which is why contributoor makes the topic opt-in. Dropping this commit leaves
the gossip-accepted events alone; docs/spec_deviations.md would then need a
line saying API submissions are not reported.

Cherry-picked from feat/beacon-single-attestation-event at 6a62106.
Adapted onto #749: events.rs keeps both the BeaconFastConfirmation and SingleAttestation variants and topic arms.
@MegaRedHand
MegaRedHand marked this pull request as ready for review November 17, 2026 18:52
@github-actions

Copy link
Copy Markdown

🤖 Grok Code Review

I'll review the single-attestation event path against the existing gossip and API emission patterns. I need the surrounding helpers and types before judging correctness.


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

@github-actions

Copy link
Copy Markdown

🤖 Gemini Code Review

The changes look good. The implementation cleanly wires single_attestation events from both P2P gossip validation (beacon_attestation_{subnet_id}) and the POST /eth/v2/beacon/pool/attestations RPC endpoint, avoids unnecessary allocations when there are no active subscribers, and matches the Beacon API event stream specification.


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

@github-actions

Copy link
Copy Markdown

🤖 Claude Code Review

Review: PR 757 — single_attestation event

Overall this is clean and well tested. The p2p path correctly emits only on Accept, and the API path emits only after a successful hand-off to p2p. The JSON test confirms the event is unversioned, which matches the spec. I have a few points.

1. Subscriber gating is global, not per-topic (main concern)

Where: verdict.rs (publish_gossip_event, new Validated::Attestation arm), events.rs

sink.has_subscribers() reports whether anyone is subscribed to the bus, not whether anyone wants single_attestation. Every SSE client therefore turns on this firehose, including a validator client that only listens to head. That client would see:

  • Attestation churn. Every backbone-subnet attestation is cloned, boxed and pushed into the shared broadcast ring.
  • Ring lag. On mainnet that is roughly hundreds of attestations per subnet per slot. With a single tokio::broadcast ring, a head/block/finalized_checkpoint subscriber can start getting RecvError::Lagged and silently miss the low-rate events it actually asked for. That is a correctness regression for existing consumers, not just a performance cost.

Suggestions:

  • Track interest per topic, for example a per-Topic subscriber count kept up by the SSE handler, and gate on sink.wants(Topic::SingleAttestation). Alternatively, give high-rate topics their own channel.
  • At minimum, the comments in events.rs ("the clone is only made when someone listens") and the docs/rpc.md wording ("nothing is built unless a client is subscribed") should say "subscribed to any topic". As written they overstate the protection.

2. Unconditional clone on the API path

Where: pool.rs, post_pool_attestations

let for_event = attestation.clone();
p2p.publish_beacon_attestation(checked.subnet_id, attestation)
    .map(|()| emit_accepted(events.as_deref(), || GossipEvent::SingleAttestation(Box::new(for_event))))

The lazy closure handed to emit_accepted is defeated because the clone happens eagerly, whether or not there is a bus or a subscriber. This is cheap per item but contradicts the stated design. Consider:

let for_event = events.as_deref()
    .filter(|bus| bus.has_subscribers())
    .map(|_| attestation.clone());

Alternatively, make publish_beacon_attestation return or borrow the attestation back. A batch POST from a large validator client can contain many items, so this is worth tightening.

3. Minor

  • net/api/src/lib.rs, GossipEvent::SingleAttestation doc. The comment says "the event ring is sized for the largest variant". That holds for ChainEvent (the broadcast element type), not GossipEvent, which is passed by value to emit. Boxing is still fine, but the rationale is slightly off.
  • verdict.rs test. It swaps server.gossip_events between two sinks. The Ignore and Reject cases are only checked against the subscribed sink, which is the right one, so this is fine. It may be worth a one-line comment that the silent sink exercises the has_subscribers guard specifically.
  • docs/rpc.md. The new row sits between payload_attestation_message and proposer_preferences, which breaks the gloas-topic grouping. Consider moving it after proposer_preferences.

Correctness notes (no action needed)

  • Gossipsub does not loop back locally published messages, so an API submission won't produce a duplicate event from the p2p path.
  • Emitting the electra SingleAttestation unchanged in gloas is correct. The container is the same; only the semantics of data.index change.

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

@github-actions

Copy link
Copy Markdown

🤖 Codex Code Review

No actionable findings. The event wiring preserves validation gates and serialization, with no changes to consensus processing.

Could not run targeted tests: rustup requires writing to /home/runner/.rustup/tmp, which is read-only in this environment.


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

@github-actions

Copy link
Copy Markdown

🤖 Kimi Code Review

No correctness or security issues found. The gossip path correctly emits only on Accept, and both gossip and API paths preserve the expected SingleAttestation representation.

  • Low — avoid an unconditional clone: crates/net/rpc/src/beacon/pool.rs:139 clones every validated API attestation into for_event, even when no event bus is configured or nobody is subscribed. This slightly contradicts the “nothing is built unless a client is subscribed” statement in docs/rpc.md and adds avoidable work for batch submissions. Consider gating the pre-publication clone on subscriber presence, as the gossip path already does in verdict.rs:437.

Otherwise, the boxing, topic mapping, acceptance-only emission, and regression tests look good.


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

@github-actions

Copy link
Copy Markdown

🤖 DeepSeek Code Review

Overall the patch is straightforward and the p2p-side gating is correct. A few points worth addressing:

  • crates/net/rpc/src/beacon/pool.rs:139 — let for_event = attestation.clone(); runs for every accepted attestation even when no EventBus is present or no subscriber exists. The p2p path only clones after has_subscribers(), so the API path should do the same to preserve that optimization. Suggest cloning lazily inside emit_accepted or only when events.as_deref().is_some_and(|bus| bus.has_subscribers()).

  • crates/net/rpc/src/beacon/pool.rs:94 — Making events an Option<Extension<EventBus>> means API-origin single_attestation events silently disappear if the production router forgets to add the EventBus extension. Confirm the server wiring actually layers it; otherwise the documented API-origin event path is a no-op.

  • docs/rpc.md:897 — The paragraph still says “The gloas topics are emitted ...”, but now includes single_attestation, which is Electra. The wording is now slightly inaccurate; consider saying “these topics” or separating the Electra event.

  • crates/net/p2p/src/beacon/verdict.rs:438 — The p2p Validated::Attestation arm is correctly gated on sink.has_subscribers() before cloning, which matters for a high-rate topic.

No security or consensus-critical issues found in the diff.


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

…ne listens

`post_pool_attestations` cloned every accepted attestation for the
`single_attestation` event before publishing it, whether or not the node
had a bus or a subscriber, so `emit_accepted`'s lazy closure saved
nothing. A batch can carry a whole validator client's votes.

The copy is now made only when the bus has a subscriber, the check
`emit_accepted` itself makes.
… topic

The comments and `docs/rpc.md` said the event is built only when someone
listens. `has_subscribers` counts every SSE client, whatever topics it
asked for, so a client subscribed to `head` alone turns the highest-rate
topic on, and since all topics share one ring it then lags sooner. Both
now say so.

Also: `GossipEvent::SingleAttestation`'s box is explained by the
`ChainEvent` it becomes, not by a ring `GossipEvent` never enters; the
`single_attestation` row moves next to `attestation`, out of the gloas
rows; the paragraph naming who emits what no longer calls it a gloas
topic; and the p2p test says what its silent sink exercises.
@MegaRedHand

Copy link
Copy Markdown
Collaborator Author

Round one (the automated review of 5388939). Fixed in ac82291 and 38d206a. make fmt and make lint pass. Tests were not run locally; CI runs them. The two commits merge cleanly with #748's round-one commits.

Fixed

  • The API path cloned every attestation (Claude, item 2; Kimi; DeepSeek, item 1): post_pool_attestations now copies an accepted attestation for the event only when the bus has a subscriber, the check emit_accepted makes itself. Before, the copy was made for every accepted attestation in the batch. ac82291
  • "Only when someone listens" overstated the protection (Claude, item 1): has_subscribers counts every SSE client whatever its topics, so a client subscribed to head alone turns single_attestation on. All topics share one ring, so that client also lags sooner if it stalls. The ChainEvent and p2p comments and the docs/rpc.md row now say so. 38d206a
  • GossipEvent::SingleAttestation's box (Claude, item 3): the reason given was the ring's slot size, which applies to ChainEvent, not GossipEvent. The doc now says the bus moves the box as is into ChainEvent::SingleAttestation, which the ring stores. 38d206a
  • docs/rpc.md placement and wording (Claude, item 3; DeepSeek, item 3): the row now sits next to attestation, out of the gloas rows. The paragraph on who emits what says "the gloas topics and single_attestation". 38d206a
  • The silent sink in the p2p test (Claude, item 3): a comment says it exercises the has_subscribers guard. 38d206a

Follow-up

Not changed

  • Is the bus layered in production? (DeepSeek, item 2): yes. start_beacon_rpc_server layers Extension(handles.events) over the whole beacon router (crates/net/rpc/src/lib.rs:338), which merges pool::routes(). /eth/v1/events extracts the bus non-optionally, so it would fail too without it. The Option is for the handler tests' routers.

Gemini and Codex found nothing. Grok posted only its opening line.

@MegaRedHand

Copy link
Copy Markdown
Collaborator Author

/review

@github-actions

Copy link
Copy Markdown

🤖 Grok Code Review

I'll read the surrounding event, pool, and gossip paths so the review is grounded in how these events are actually emitted.


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

@github-actions

Copy link
Copy Markdown

🤖 Gemini Code Review

This PR looks good. The implementation cleanly wires single_attestation SSE events from both gossip validation (crates/net/p2p/src/beacon/verdict.rs) and POST /eth/v2/beacon/pool/attestations (crates/net/rpc/src/beacon/pool.rs) through EventBus, guards cloning behind has_subscribers(), reuses the Box<SingleAttestation> allocation across GossipEvent and ChainEvent, and includes solid test coverage and documentation updates.


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

@github-actions

Copy link
Copy Markdown

🤖 Claude Code Review

Review: PR 757, emit single_attestation on the event stream

The PR is small and well tested. The gating on Accept only (p2p) and on successful publish (API) matches the Beacon API wording: "passes validation rules of the beacon_attestation_{subnet_id} topic (from P2P or API)". The Validated::Attestation arm in verdict.rs reuses the existing Accept-only funnel, so ignored or rejected attestations are not emitted. The tests cover both sources and the no-subscriber path. I found no correctness bugs. My concerns are mostly about throughput and the shared ring.

1. Existing subscribers can lose events (most significant)

docs/rpc.md acknowledges this, but it affects clients that never asked for this topic. The gate is has_subscribers() on the whole bus, and all topics share one broadcast ring. As a result, a client subscribed only to head or finalized_checkpoint now receives every subnet attestation in its ring.

  • With default backbone subnets, the rate is modest.
  • With --subscribe-all-subnets, or on a large-validator-count network, it can be thousands per second.

A head consumer that reads slowly will hit RecvError::Lagged and silently drop head or reorg events. That is a regression for existing consumers. Two possible fixes:

  • Track per-topic subscriber counts so the clone and send happen only when someone wants single_attestation.
  • Give SingleAttestation its own broadcast channel, so a flood cannot evict low-rate topics.

If you'd rather defer this, consider a TODO or issue reference next to has_subscribers in verdict.rs:437-442.

2. Every receiver allocates per event (events.rs:~351)

tokio::sync::broadcast clones T on every recv(). With Box<SingleAttestation> (about 240 bytes), each subscriber does a heap allocation and memcpy for every attestation. This happens even if the SSE stream then filters it out by topic.

Using Arc<electra::SingleAttestation> for both ChainEvent::SingleAttestation and GossipEvent::SingleAttestation would make that cost a refcount bump. The p2p side could also hand over an Arc once instead of cloning the box. This matters more for this topic than for any other, given its rate.

3. Redundant double gate in pool.rs:139-155

for_event is already Some only when the bus has subscribers. emit_accepted then re-checks has_subscribers and wraps the payload in a closure. You could emit directly:

.map(|()| {
    if let (Some(bus), Some(attestation)) = (events.as_deref(), for_event) {
        bus.emit(ChainEvent::SingleAttestation(Box::new(attestation)));
    }
})

Alternatively, keep emit_accepted but drop the outer if let by making for_event the thing captured. As written, it reads as two layers of the same check. This is cosmetic.

4. Event timing on the API path

publish_beacon_attestation returning Ok(()) means the message was enqueued to the p2p actor, not that it was gossiped. This is fine and matches "accepted by the API". The doc row could say "accepted" rather than imply publication. It currently does say "accepted", so this is just a note.

5. Doc comments

  • crates/net/api/src/lib.rs:565-569: the boxing rationale is convoluted ("moves the box as is into its … the element its ring stores, which is boxed…"). Something like "Boxed so the bus can move it into ChainEvent::SingleAttestation without re-allocating" is enough. If you adopt Item 2, this becomes Arc and the comment changes anyway.
  • events.rs:345-350: the doc on the variant mixes in a bus-level caveat about has_subscribers. That caveat belongs at the emit sites, where it already exists.

6. Tests

  • The verdict.rs test is good: it covers no subscriber, Ignore, Reject, and Accept.
  • The pool test asserts partial-batch semantics: a bad item gives 400 while the good one is still emitted. That is the right behavior per spec.
  • You could also add a pool test with events = Some(bus) but no subscriber, asserting the publish still happens. This would guard the .then(...) path from accidentally short-circuiting the publish.

Overall this is mergeable as is. I'd recommend addressing Item 1, or at least Item 2, before this lands on a node serving SSE clients on mainnet-scale subnets.


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

@github-actions

Copy link
Copy Markdown

🤖 Codex Code Review

No actionable findings. Event emission is gated on accepted attestations, preserves the expected payload, and avoids cloning when there are no subscribers. Consensus validation and state transitions are unchanged.

Tests could not run because Rustup attempted to write to a read-only directory.


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

@github-actions

Copy link
Copy Markdown

🤖 Kimi Code Review

No blocking correctness, security, or consensus issues found.

  • crates/net/p2p/src/beacon/verdict.rs:437-441: Emission is correctly restricted to Outcome::Accept; ignored and rejected attestations stay off the stream. The has_subscribers() guard avoids cloning in the common no-listener case.
  • crates/net/rpc/src/beacon/pool.rs:139-153: The RPC path clones before moving the attestation into publication and emits only after successful submission to the network actor. The mixed valid/invalid batch test appropriately verifies that valid attestations are still reported while invalid ones are not.
  • crates/blockchain/src/events.rs: Topic mapping, boxing, and gossip-to-chain-event conversion are consistent with existing events. The specification-example test usefully covers quoted integers and Electra field names.
  • docs/rpc.md: The documentation accurately describes both sources and the shared-ring/backpressure behavior.

Non-blocking performance consideration: because has_subscribers() is global, a subscriber to any topic enables cloning and ring insertion for every accepted subnet attestation. This is explicitly documented and therefore appears intentional. If attestation traffic causes unrelated event subscribers to lag, per-topic subscriber counts or separate rings would be the natural follow-up; no change is required for this PR.


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

@github-actions

Copy link
Copy Markdown

🤖 DeepSeek Code Review

Overall the wiring looks correct: p2p emits only on Accept and only when a subscriber is connected, the API handler emits only after successful validation/publish, and the EventBus conversion preserves the boxed event. Tests cover the no-subscriber, reject/ignore, and API partial-batch cases well.

A few non-blocking notes:

  • Performance — crates/net/p2p/src/beacon/verdict.rs around the new arm.
    attestation.clone() performs a full deep clone of the SingleAttestation for every accepted subnet attestation when any subscriber exists. Since this is described as the highest-rate topic, and ChainEvent/GossipEvent likely use Clone for fan-out to each subscriber, each event may be deep-cloned multiple times. Consider storing Arc<SingleAttestation> in the event types instead of Box, so fan-out is cheap while still keeping the event-bus ring slot small.

  • Performance/readability — crates/net/rpc/src/beacon/pool.rs around the new for_event.
    events.as_deref().is_some_and(EventBus::has_subscribers) is evaluated per attestation inside the batch loop. Hoisting that once before into_iter() would avoid repeated checks for large validator batches.

  • Docs consistency — crates/blockchain/src/events.rs Topic::SingleAttestation.
    The enum comment only mentions beacon_attestation_{subnet_id} gossip rules, while docs/rpc.md correctly says the event is also emitted for POST /eth/v2/beacon/pool/attestations. The comment could mention the API path too.

  • Deployment consideration — crates/net/rpc/src/beacon/pool.rs.
    The API event is silently disabled if the EventBus extension layer is not installed, because the extractor is optional. That is fine for tests, but production routers must ensure the layer is present to satisfy the documented single_attestation behavior for API-submitted attestations.

No consensus, fork-choice, or SSZ handling concerns are touched by this diff.


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

@MegaRedHand

Copy link
Copy Markdown
Collaborator Author

Round two (the automated review of 38d206a). Nothing changed: the round raised no defect, and its one substantive point was settled in round one and is tracked in #845.

Not changed

  • The shared ring and a bus-wide subscriber check (Claude, item 1; Kimi): settled in round one; per-topic interest or a ring of their own for the high-rate topics is Event bus: build high-rate topics only for clients that subscribed to them #845.
  • Arc instead of Box for the payload (Claude, item 2; DeepSeek): every large payload on the bus is a Box (BeaconAttestation too), so the per-receiver clone is the bus's existing cost. It is about 240 bytes per subscriber per event, not measured to matter. If Event bus: build high-rate topics only for clients that subscribed to them #845 gives the high-rate topics their own ring, that ring can carry Arcs.
  • The subscriber check made twice in pool.rs (Claude, item 3): emit_accepted checks as its own contract for every caller, and the caller's check is what saves the clone. Cosmetic.
  • A pool test with a bus but no subscriber (Claude, item 6): publish_beacon_attestation is called unconditionally; the check only decides whether the event gets a copy. No path skips the publish, and the no-bus test already takes the same branch.
  • The two doc comments (Claude, item 5): both are accurate; wording preference.
  • Hoist the check out of the batch loop (DeepSeek): it is one atomic read, and checking per item lets a client that subscribes mid-batch see the rest.
  • Topic::SingleAttestation names only the gossip rules (DeepSeek): the API path validates with the same topic rules, so the doc covers both sources, as the specification's wording does. docs/rpc.md names both.
  • The optional bus extractor (DeepSeek): answered in round one; production layers the bus over the whole beacon router.

Gemini and Codex found nothing, and Grok posted only its opening line.

@MegaRedHand

Copy link
Copy Markdown
Collaborator Author

The review loop for this PR stops here: the last round raised nothing left to address. Every point was either answered in the code or settled in an earlier round. The follow-up still open from this PR's rounds is #845 (building the high-rate event topics only for clients that subscribed to them).

This branch has not been deployed

No deployments
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.

1 participant