adds beacon api

[0w3n-d]

No description provided.

[vladimir-ea]

can we add the beacon api to the engine api tile? it seems overkill to have cores assigned to marshalling http requests and responses for each api?

we could make this a component that is not an actual Tile but has a spin or loop method that could be called from a tile? that would give some flexibility in how it is deployed.

[vladimir-ea]

can we add the beacon api to the engine api tile? it seems overkill to have cores assigned to marshalling http requests and responses for each api?

we could make this a component that is not an actual Tile but has a spin or loop method that could be called from a tile? that would give some flexibility in how it is deployed.

also - if we run the http server as a separate tile then we should just run Axum in a single thread runtime and not take on the maintenance risk of writing our own web-server.

[0w3n-d]

can we add the beacon api to the engine api tile? it seems overkill to have cores assigned to marshalling http requests and responses for each api?

we could make this a component that is not an actual Tile but has a spin or loop method that could be called from a tile? that would give some flexibility in how it is deployed.

I do think the current tile setup is likely not optimal but we should probably wait until everything is running and we've gathered a bunch of data before deciding to consolidate tiles? When feature complete the system will have 3 integration points. p2p, Beacon api, and engine api. Currently it looks like we have 3 tiles for p2p stuff. Putting the Beacon and engine api in the same tile seems premature.

[0w3n-d]

can we add the beacon api to the engine api tile? it seems overkill to have cores assigned to marshalling http requests and responses for each api?
we could make this a component that is not an actual Tile but has a spin or loop method that could be called from a tile? that would give some flexibility in how it is deployed.

also - if we run the http server as a separate tile then we should just run Axum in a single thread runtime and not take on the maintenance risk of writing our own web-server.

I don't see why we'd go in that direction. That would pull in all of tokio and so on. Seems like the opposite to our approach elsewhere. The Beacon api is the interface to the validator client and commit boost and so on. If our design goals center low level, high performance, and innovation we probably shouldn't outsource a key interface to the axum, hypr, tokio stack.

Axum is just a nice wrapper around hypr and hypr is just state machine that sits on the same two crates I'm using here. Mio and httparse. And unlike the p2p interface, this one is purely internal so minimal security risk.

[vladimir-ea]

can we add the beacon api to the engine api tile? it seems overkill to have cores assigned to marshalling http requests and responses for each api?
we could make this a component that is not an actual Tile but has a spin or loop method that could be called from a tile? that would give some flexibility in how it is deployed.

I do think the current tile setup is likely not optimal but we should probably wait until everything is running and we've gathered a bunch of data before deciding to consolidate tiles? When feature complete the system will have 3 integration points. p2p, Beacon api, and engine api. Currently it looks like we have 3 tiles for p2p stuff. Putting the Beacon and engine api in the same tile seems premature.

well yes to not predetermining the tiles - which is why it makes sense as much as possible to create components that are not tiles but can be called from tiles

[vladimir-ea]

can we add the beacon api to the engine api tile? it seems overkill to have cores assigned to marshalling http requests and responses for each api?
we could make this a component that is not an actual Tile but has a spin or loop method that could be called from a tile? that would give some flexibility in how it is deployed.

also - if we run the http server as a separate tile then we should just run Axum in a single thread runtime and not take on the maintenance risk of writing our own web-server.

I don't see why we'd go in that direction. That would pull in all of tokio and so on. Seems like the opposite to our approach elsewhere. The Beacon api is the interface to the validator client and commit boost and so on. If our design goals center low level, high performance, and innovation we probably shouldn't outsource a key interface to the axum, hypr, tokio stack.

Axum is just a nice wrapper around hypr and hypr is just state machine that sits on the same two crates I'm using here. Mio and httparse. And unlike the p2p interface, this one is purely internal so minimal security risk.

the concern is not security, its just maintaining code which implements something that is already available and widely used - I see no issue in running tokio in a separate tile - or separate process on the same machine - if its for non-hot-path things.

[Bronek]

I have worked with Claude.ai to prepare a new design for Beacon API - the basic principles have been added to this branch in d096b51. Comments below will provide more details.

[Bronek]

Design notes from Claude.ai

---

Goal (from team, channeled by Bronek)

• No separate tile (loop_body) for any API access — serving (beacon_api) or calling (engine).
• One new spine-attached tile (working name client_server) hosting hardcoded crates: beacon_api (kept name, refactored mechanics, HTTP server) and engine_api (renamed from engine, HTTP client).
• Open: seam location for HTTP machinery (host implements client+server and provides them to hosted crates, vs crates implement internally).
• Wanted: table-based dispatch for HTTP request handling (server side). Open: same for engine_api client side — decide on pros/cons.
• Principles: simplicity without performance compromise; for HTTP specifically, simplicity + consistency take precedence (unavoidable multi-ms latency tax).

Mapped facts the designs rest on

• TileConfig::new(n, None): n is a CPU core id; each tile = one OS thread pinned to its own core, busy-polling. Cores 1–7 taken (Controller, Network, BeaconState, Storage, Engine, DataColumns, BeaconApi). Merging engine + beacon_api frees a core — the mechanical driver behind "one tile for APIs".
• crates/beacon_api (prototype, 596 lines): mio+httparse server, hardcoded 0.0.0.0:5051, blocking poll(100ms) in loop_body (must die in a shared loop), exact-match routing via closure F: Fn(&ParsedRequest, &mut Vec<u8>), 2 endpoints, no live state, 16 MiB/conn read buffers, no conn cap, ignores spine adapter. In-code TODO: parameterised routing needed.
• crates/engine (mature): non-blocking mio client (poll Duration::ZERO), HttpPool one-req-per-conn growing unboundedly (10 MB read + 10 MB write per conn), hand-rolled JWT HS256 (1 s token cache), simd_json. One free function per method; response correlation FxHashMap<u64, ReqKind>; dispatch = match on EngineReq (inbound) and ReqKind (completion). HOT PATH: newPayload transcodes SSZ→JSON straight into persistent 10 MB scratch (client.rs:156-177, types.rs:269,345) — must be preserved verbatim. Dead parallel UDS transport ipc.rs (474-line near-copy of http.rs).
• Spine contract (unchanged by any design): queues engine_reqs / engine_resps / engine_health; requests carry TCacheRead handles; responses written to tile-owned TCache. Producers: BeaconState, DataColumns.
• State access for future endpoints: BeaconStateReader::read(|rv| ..) seqlock; closures short + re-runnable; None pre-bootstrap (docs/beacon-state-architecture.md §4-5).
• Test gap: neither mio event loop has any end-to-end test (test-or-broken rule).
• SpineAdapter::connect_tile is public — tests can build a real spine and drive loop_body by hand (verified by design agent A).

Recommendation (Claude's, for team review)

1. Crates: client_server (tile: single mio Poll, token slab, loop composition), httpcore (one connection state machine, both roles, byte interfaces — no Poll, no sockets in signatures), beacon_api (ROUTES table + handlers + Request/Response/ApiCtx, transport-free), engine_api (renamed engine: codecs, correlation, JWT, ReqKind match, transport-free; scratch handed in, hot path verbatim).
2. No traits at host↔hosted seams: two hardcoded crates = plain fields + fn calls (one adapter = hypothetical seam). A future third crate edits the host tile — accepted, cheap, honest.
3. Transport testability via byte-level interfaces (C/D convergence): httpcore machines tested on byte slices with deterministic chunking (partial reads, pipelining, keep-alive, oversize) — no Mux trait needed when the seam is already &[u8].
   3a. Two production transports (team decision): TCP + UDS. Because the transport set is closed and we control it, represent it as an enum, not a trait — enum Stream { Tcp(mio::net::TcpStream), Uds(mio::net::UnixStream) } with match-forwarding read/write/register (both impl Read+Write+Source), plus enum Bind { Tcp(SocketAddr), Unix(PathBuf) } in config (B's shape). Same principle as client dispatch: closed set → enum; open set → table. Monomorphic, no generics in hosted-crate signatures (D's TcpOrUds). UDS applies to the engine_api client pool first; the server side gets the same Bind enum for free. UnixStream::pair() doubles as a portless, deterministic test transport for full-machine tests (B's suggestion).
4. Dispatch: server table as converged; client enum match as unanimous.
5. Test plan (test-or-broken), three tiers:
   a. Unit (socket-free, fast): router+handler tests through the table with real seqlock fixture pairs (typos in patterns fail in tests, not prod); httpcore byte-machine tests with deterministic chunking; golden-byte engine tests incl. counting-allocator assertion that newPayload allocates zero (the hot-path invariant finally gets a failing test).
   b. Integration over REAL http://localhost (team-requested, 2026-08-14): cargo tests/ dir tests that construct the real tile (real mio Poll, real TCP listener) and hand-crank loop_body in a plain test loop — no flux threads/pinning needed since loop_body is a plain fn and SpineAdapter::connect_tile is public. Test issues real HTTP over loopback (std::net or minimal client). DESIGN REQUIREMENTS this imposes: (i) bind address configurable (kills hardcoded 0.0.0.0:5051), (ii) bind to port 0 in tests and EXPOSE the actual bound address (local_addr()) so tests discover the ephemeral port, (iii) everything non-blocking means the test loop spins deterministically — fast, no sleeps. Same technique covers the UDS bind (tempdir socket path).
   c. Full-loop: beacon-api request served over loopback WHILE an EL call is in flight against a canned local EL — the merged-loop interleaving invariant no prototype ever tested; one such smoke test per transport as the seatbelt.
6. Bounded client pool + server conn cap + configurable bind (kills three prototype liabilities in passing).

[Bronek]

Implementation plan from Claude.ai

---

Commit sequence

Strategy: build the new transport alongside the old, migrate consumers one by one, consolidate tiles last. No commit mixes a move with a behavior change.

C1 — crates/httpcore skeleton (server role). b977f93
New crate silver_httpcore: the server-side connection byte-machine extracted from beacon_api's tile.rs (parse → dispatch-closure → frame response; keep-alive + pipelining preserved). Interfaces are bytes/ frames — no Poll, no sockets in signatures. Migrate beacon_api's 14 parser tests + add deterministic-chunking tests (partial reads, pipelined split across pumps, oversize reject). beacon_api crate switches to httpcore for framing but its tile stays attached and behaviorally identical (still its own Poll; the 100 ms block dies in C5, not here).

C2 — httpcore client role; engine consumes it; delete ipc.rs. 42d86da
Client-side connection machine (one-request-per-conn, Content-Length framing, WouldBlock resumption) moves from engine http.rs into httpcore, generic over Stream. ipc.rs (474 dead lines) deleted — UDS is now a Stream variant. Engine crate keeps: pool policy, JSON-RPC, JWT, correlation, ReqKind — all protocol. Engine's 66 tests keep passing; add golden-byte round-trip test through the new machine incl. JWT header. Bounded pool cap introduced here (config, default generous).

C3 — beacon_api table dispatch + Request/Response/ApiCtx. e7cbd99
Const ROUTES table ((Method, pattern) → handler fn), pattern compiled to Lit/Param segments at init, zero-alloc Params (inline ≤4), router owns 404/405, handlers own 400; ApiCtx { state: BeaconStateReader, identity, outbox }. Rewrite the two existing endpoints as table rows; /metrics still stubbed. Router+handler tests through the table with fixture seqlock pairs; 503-before-bootstrap test. [AMENDED: Accept/content-type field deferred to the M2 SSZ-negotiation work — httpcore doesn't expose request headers yet, and a parsed-but-unread field is dead API. Outbox/NodeCommand deferred to its first consumer (same principle as the C1 Stream/Bind deferral). Reader-in-ApiCtx conditional on cheap fixture + srv.rs-example construction — implementer investigates and reports. New behavior sanctioned: 405 for known-path-wrong-method (today the method is ignored entirely).]

C4 — rename crates/engine → crates/engine_api. 96a900c
Purely mechanical, own commit: directory, package name silver_engine_api, workspace member + dep entries, imports, docs/spine-message-flow.md prose. "Names track current reality" — also rename lingering engine-named locals in touched files. No logic changes.

C5 — crates/client_server tile; consolidation. 36f291e
New tile crate constructs/holds the beacon_api server component and the engine_api client component; loop_body composes their pumps (all non-blocking). [AMENDED: TWO Polls, not the single shared Poll + token slab from the recommendation sketch — C2 landed the pool with its own Poll inside engine_api's verified event paths; unifying would churn them to save one epoll_wait(0)/iteration (noise per team latency ruling) at the cost of token-space partitioning. Design D's argument, now backed by C2's shape. Revisit only if measurement ever says otherwise. No outbox — deferred since C3.] beacon_api's own tile and EngineTile deleted; main.rs attaches client_server once (cores renumber, one core freed); srv.rs example updated. Config: beacon-api bind via Config builder + file + --beacon-api-bind; execution_endpoint accepts socket path; tile exposes local_addr(). Tests: tier-b integration (real localhost HTTP against hand-cranked loop_body via public SpineAdapter::connect_tile, port 0 + local_addr); tier-c full-loop (beacon-api request served WHILE canned-EL call in flight); UDS variants of both (tempdir socket path).

C6 — counting-allocator hot-path test + smoke. bd42255
Zero-allocation assertion on the newPayload transcode path (CountingAllocator exists in main.rs idiom); one real-socket smoke per transport per direction. Any leftover prototype liabilities: connection cap on server, 16 MiB→sane read cap, /eth/v1/events → clean 404.

[Bronek]

@vladimir-ea @0w3n-d note a limitation in the C5, we may want to revisit it:

---

Single beacon_api bind As of C5 the node binds exactly ONE listener — TCP or UDS, chosen by beacon_api_bind. If we want simultaneous surfaces (local VC over UDS + TCP on specific interfaces), the additive change is: BeaconApi holds a list of listeners (one reserved token each; accept loop per listener; connections already transport-uniform via Stream), config becomes a list of binds. Router, handlers, connection handling untouched.

[vladimir-ea]

Recommendation (Claude's, for team review)

1. Crates: client_server (tile: single mio Poll, token slab, loop composition), httpcore (one connection state machine, both roles, byte interfaces — no Poll, no sockets in signatures), beacon_api (ROUTES table + handlers + Request/Response/ApiCtx, transport-free), engine_api (renamed engine: codecs, correlation, JWT, ReqKind match, transport-free; scratch handed in, hot path verbatim).

agree that a single mio::Poll should be used across both apis - note that you can have a blocking poll if we are using the Flux thread_park feature (which we should probably make the default for silver?) b/c that hooks the Poll into the signalling mechanism (via mio::Waker https://github.com/gattaca-com/flux/blob/c73a663f62111fd4466551e53790b2d2f576608f/crates/flux-communication/src/park.rs#L160).

[0w3n-d]

@vladimir-ea @0w3n-d note a limitation in the C5, we may want to revisit it:

Single beacon_api bind As of C5 the node binds exactly ONE listener — TCP or UDS, chosen by beacon_api_bind. If we want simultaneous surfaces (local VC over UDS + TCP on specific interfaces), the additive change is: BeaconApi holds a list of listeners (one reserved token each; accept loop per listener; connections already transport-uniform via Stream), config becomes a list of binds. Router, handlers, connection handling untouched.

Probably OK for now. UDS would most likely be used for out bound connections to the EL, as EL and CL often run on the same machine. But on the listener side normally people run a VC on a different machine for security, maybe used by solo stakers or for testing but TCP is probably fine for those cases too.

[Bronek]

Proposed API scope by Claude.ai

---

Beacon API: the validator-client surface (scoping beacon_api v1)

Date: 2026-08-14. Method: primary sources only — ethereum/beacon-APIs OpenAPI at tag v4.0.0 (current stable, 2025-10-14, Fulu-era; v5.0.0-alpha.x = Gloas dev), plus source of five VCs: Lighthouse sigp/lighthouse@unstable (LH), Teku Consensys/teku@master (TK), Nimbus status-im/nimbus-eth2@unstable (NB), Prysm OffchainLabs/prysm@develop (PR), Vouch attestantio/vouch + attestantio/go-eth2-client (VO). Five parallel research agents, one per client; every claim below carries a file path.

Caveat: PR's REST mode is still experimental and flag-gated (--enable-beacon-rest-api, config/features/flags.go:128; gRPC stays default through v8). PR-only rows are weighted accordingly.

Spec baseline (v4.0.0): v1 variants of pool attestations, aggregate_attestation, aggregate_and_proofs, and block/blinded-block publish are REMOVED (release notes, PR #549); block production is v3-only. So the Electra/Fulu-era surface is v2/v3 where marked below — silver never needs the v1 variants. Gloas (v5-alpha) later adds: v4 blocks, v2 proposer duties, ptc duties, payload_attestation_data, pool/payload_attestations, execution_payload_envelopes/bids, proposer_preferences, v2 node/version, topics head_v2 / execution_payload_available. LH/TK/PR already carry client code for these — out of v1 scope but the routing table should expect them.

(a) Endpoint table

Spec link = path under github.com/ethereum/beacon-APIs/blob/v4.0.0/. Verdict: MUST = exercised by ≥1 surveyed VC in default-config normal operation; SHOULD = specific clients / common configs; OPT = niche, subcommand, or DVT.

MUST — core duty cycle (all five VCs unless noted)

Endpoint	Method	Spec (apis/…)	VCs	Verdict
/eth/v1/beacon/genesis	GET	beacon/genesis.yaml	all	MUST (startup poll loops: LH wait_for_genesis, PR 1 s retry)
/eth/v1/config/spec	GET	config/spec.yaml	LH TK NB VO	MUST (TK/VO hard-require at startup; LH/NB compat checks; PR never calls it)
/eth/v1/config/fork_schedule	GET	config/fork_schedule.yaml	NB VO	MUST (NB polls every epoch, fork_service.nim; VO computes domains from it, gec http/domain.go:95)
/eth/v1/node/version	GET	node/version.yaml	LH NB PR VO	MUST (trivial)
/eth/v1/node/syncing	GET	node/syncing.yaml	all	MUST (health/readiness polling in every client)
/eth/v1/beacon/states/{id}/validators	POST + GET	beacon/states/validators.yaml	TK NB PR VO	MUST both verbs (TK/PR POST-first with GET fallback; NB POST-only; VO POST w/ pubkeys)
/eth/v1/beacon/states/{id}/validators/{validator_id}	GET	beacon/states/validator.yaml	LH	MUST (LH resolves indices per-pubkey, duties_service.rs ~L822)
/eth/v1/validator/duties/attester/{epoch}	POST	validator/duties/attester.yaml	all	MUST
/eth/v1/validator/duties/proposer/{epoch}	GET	validator/duties/proposer.yaml	all	MUST (v1; LH-unstable already prefers Gloas v2 w/ v1 fallback flag)
/eth/v1/validator/duties/sync/{epoch}	POST	validator/duties/sync.yaml	all	MUST
/eth/v1/validator/attestation_data	GET	validator/attestation_data.yaml	all	MUST (latency-critical, ~1/3 slot deadline)
/eth/v2/beacon/pool/attestations	POST	beacon/pool/attestations.v2.yaml	all	MUST (v2 only post-Electra; carries Eth-Consensus-Version req header)
/eth/v2/validator/aggregate_attestation	GET	validator/aggregate_attestation.v2.yaml	all	MUST (v2 only)
/eth/v2/validator/aggregate_and_proofs	POST	validator/aggregate_and_proofs.v2.yaml	all	MUST (v2 only; version header)
/eth/v3/validator/blocks/{slot}	GET	validator/block.v3.yaml	all	MUST (params: randao_reveal, graffiti, skip_randao_verification, builder_boost_factor; resp headers: Eth-Consensus-Version, Eth-Execution-Payload-Blinded, Eth-Execution-Payload-Value, Eth-Consensus-Block-Value)
/eth/v2/beacon/blocks	POST	beacon/blocks/blocks.v2.yaml	all	MUST (must parse broadcast_validation query: TK always sends it, NB sends gossip, LH omits; version header)
/eth/v1/beacon/pool/sync_committees	POST	beacon/pool/sync_committees.yaml	all	MUST
/eth/v1/validator/sync_committee_contribution	GET	validator/sync_committee_contribution.yaml	all	MUST
/eth/v1/validator/contribution_and_proofs	POST	validator/sync_committee_contribution_and_proof.yaml	all	MUST
/eth/v1/beacon/blocks/{block_id}/root	GET	beacon/blocks/root.yaml	LH NB PR VO	MUST (sync-committee message path, block_id=head)
/eth/v1/validator/beacon_committee_subscriptions	POST	validator/beacon_committee_subscriptions.yaml	all	MUST
/eth/v1/validator/sync_committee_subscriptions	POST	validator/sync_committee_subscriptions.yaml	LH TK NB VO	MUST (PR derives subnets itself)
/eth/v1/validator/prepare_beacon_proposer	POST	validator/prepare_beacon_proposer.yaml	all	MUST (NB re-sends every slot)
/eth/v1/validator/liveness/{epoch}	POST	validator/liveness.yaml	LH TK NB PR	MUST (doppelganger; NB default-ON conf.nim; LH/TK opt-in)
/eth/v1/beacon/headers/{block_id}	GET	beacon/headers/header.yaml	NB PR VO	MUST (NB default paths: finalized-header slashing-db pruning duties_service.nim:747, poll block monitor; VO proposer path)
/eth/v1/events	GET (SSE)	eventstream/index.yaml	all connect by default	MUST for production quality; deferrable at bring-up — see (b)

SHOULD — client- or config-specific

Endpoint	Method	Spec (apis/…)	VCs	Verdict
/eth/v2/beacon/blinded_blocks	POST	beacon/blocks/blinded_blocks.v2.yaml	LH TK NB PR	SHOULD — only reachable once produceBlockV3 can return blinded (external builder); VO unblinds via relay instead
/eth/v1/validator/register_validator	POST	validator/register_validator.yaml	all, builder-gated	SHOULD — accept-and-ignore is valid until builder support (NB asserts --payload-builder; VO posts as secondary)
/eth/v1/node/health	GET	node/health.yaml	PR	SHOULD (trivial: 200/206/503 by sync state)
/eth/v1/node/peer_count	GET	node/peer_count.yaml	TK	SHOULD (TK BeaconNodeReadinessManager wants ≥50 peers)
/eth/v1/config/deposit_contract	GET	config/deposit_contract.yaml	PR VO	SHOULD (static data)
/eth/v1/beacon/states/{id}/fork	GET	beacon/states/fork.yaml	PR	SHOULD
/eth/v1/beacon/states/{id}/finality_checkpoints	GET	beacon/states/finality_checkpoints.yaml	PR	SHOULD
/eth/v1/beacon/states/{id}/committees	GET	beacon/states/committees.yaml	PR	SHOULD (PR duties.go Committees)
/eth/v1/beacon/headers	GET (list)	beacon/headers/headers.yaml	PR	SHOULD
/eth/v2/beacon/blocks/{block_id}	GET	beacon/blocks/block.v2.yaml	VO	SHOULD (sync-duty inclusion verification, cache)

OPT — niche / out of normal operation

Endpoint	VCs	Note
GET /eth/v2/beacon/pool/attestations	VO	multi-instance mode only
POST /eth/v1/beacon/pool/voluntary_exits	TK PR	exit subcommands, not duty flow
POST /eth/v1/validator/{beacon,sync}_committee_selections	LH TK NB PR	DVT-only (--distributed / Obol flag)
POST validator/persistent_subnets_subscription	TK	Teku-proprietary (non-/eth); 404 is tolerated
Gloas set (v4 blocks, ptc duties, payload attestations, envelopes, proposer_preferences)	LH TK PR	defer until Gloas fork scheduling

(b) /eth/v1/events per client — NO client hard-requires it

• LH (new on unstable): head monitor ON by default (enable_beacon_head_monitor: true, validator_client/src/config.rs L139), topic head only (beacon_node_fallback/src/beacon_head_monitor.rs L109). Purpose: attest immediately on head arrival. Stream failure = warn + auto-restart; attestations fall back to the ~1/3-slot deadline poll (attestation_service.rs L297–327). --disable-beacon-head-monitor exists.
• TK: EventSourceBeaconChainEventAdapter subscribes head always; + attester_slashing, proposer_slashing only with --shut-down-when-validator-slashed-enabled (default false). ForkAwareTimeBasedEventAdapter runs CONCURRENTLY from genesis — all duty timers fire with or without the stream; SSE only adds early attestation + reorg-aware duty refresh.
• NB: block monitor --block-monitor-type ∈ {disabled, poll, event}, default event (conf.nim:1113), topic head only (block_service.nim:503). poll mode (3× GET headers/head per slot) is a fully supported alternative; SSE failure = debug log + retry.
• PR: topics head_v2 + execution_payload_available (api/client/event/event_stream.go:34); auto-falls back to head if the BN 400s on head_v2 (multi_event_stream.go L145). Reconnects forever (1 s→16 s backoff); duties are polled regardless. Without events: attests at full deadline, no dependent-root duty refresh.
• VO: topics head + block (services/controller/standard/service.go:187-188), SSE via r3labs/sse, reconnect every 1 s (gec http/events.go:62). Drives early attest/sync-msg (fastTrackJobs), reorg duty re-fetch, block-root cache. Attestation jobs are ALSO scheduled at slot+slotDuration/3 (attester.go:110) — stream absence slows, not breaks.

Conclusion: polling fallback exists everywhere; the penalty for omitting SSE is degraded attestation latency (no early attest), no reorg-triggered duty refresh, and constant reconnect hammering (VO every 1 s, PR ≤16 s, LH/NB retries) polluting logs on both sides. Union of topics to serve when implemented: head, block (head_v2 declined via 400 is handled by PR). Slashing topics only for TK's opt-in shutdown feature.

(c) SSZ vs JSON

MUST accept/serve SSZ (application/octet-stream):

• POST /eth/v2/beacon/blocks + blinded: LH sends SSZ ONLY — no JSON fallback (post_beacon_blocks_v2_ssz, eth2 lib L525; block_service.rs L741–770). TK/PR/VO also post SSZ-first (TK sticky-flips to JSON on 415; PR caches 415 per host w/ TTL; VO submitproposal.go:80). NB posts JSON. => server must decode BOTH, keyed by Content-Type + Eth-Consensus-Version request header.
• GET /eth/v3/validator/blocks/{slot}: all five send Accept preferring octet-stream (TK q=0.9 default-on flag; LH SSZ-first w/ JSON retry; NB preferSSZ; PR q=0.95; VO q=1.0). Serving JSON is legal (clients switch on response Content-Type) but SSZ is the expected fast path; version/blinded-ness MUST come via response headers either way.

JSON-only in practice (spec allows SSZ on some, no surveyed VC uses it): attestation_data, aggregate_attestation v2, aggregate_and_proofs v2, pool attestations v2 (NB batch mode --batch-attestations posts SSZ, default off), register_validator (TK hardcodes JSON, OkHttpValidatorTypeDefClient), all duties, subscriptions, sync-committee family, validators queries, liveness, all bootstrap. VO alone sends SSZ-preferring Accept on GET v2 blocks/{id} (gec http.go:270) — JSON response is accepted.

v1 rule of thumb: SSZ decode on block publish, SSZ encode on block produce; JSON everywhere (incl. those two, for NB publish and any 415/downgrade path). Everything else JSON-only is spec-conformant and matches observed client behaviour.

(d) Conclusion for the client_server tile design

1. v1 must serve ~25 routes (MUST rows): 3 duties, attestation_data + 3 attestation submit/aggregate routes (v2), produce v3 + publish v2, 3 sync-committee routes + contribution pair, 2 subnet subscriptions, prepare_beacon_proposer, liveness, validators lookup (POST+GET+by-id), genesis/spec/fork_schedule/version/syncing, blocks/{id}/root, headers/{id}. The SHOULD tier adds ~10 mostly-trivial reads. Fits the const ROUTES table + linear scan design comfortably.
2. SSE is avoidable at first: every surveyed VC degrades to polling. Acceptable for bring-up; not acceptable for production (latency + reconnect spam). It slots into the accepted design exactly as anticipated: an additive subscription mode on the connection state machine (long-lived conn, small appended writes on head/block from spine events, periodic : keep-alive comments), NOT big-body streaming. Return 400 for unsupported topics per spec (PR relies on this for head_v2 negotiation).
3. Nothing else conflicts with the materialized-in-buffer model. Zero long-polling or chunked responses in any client path. Bounded worst cases: produceBlockV3 SSZ (single- digit MB), validators queries (VCs always pass their own id lists; only TK's GET fallback and VO's no-ids call could ask for more — cap/paginate is a policy choice, not a streaming need). Client call timeouts are tight (TK 10 s hard; attestation_data effectively sub-second useful window) — the sync-handler + short-seqlock-read model is the right fit.
4. Content negotiation is part of the router contract: Accept parsing on produce-v3 (and optionally attestation_data/aggregate later), Content-Type + Eth-Consensus-Version on the three v2 publish routes, broadcast_validation query on block publish, and the four produce-v3 response headers. 415 responses are load-bearing (TK/PR downgrade logic); so is 400-on-bad-topic for /eth/v1/events.

[vladimir-ea]

@vladimir-ea @0w3n-d note a limitation in the C5, we may want to revisit it:
Single beacon_api bind As of C5 the node binds exactly ONE listener — TCP or UDS, chosen by beacon_api_bind. If we want simultaneous surfaces (local VC over UDS + TCP on specific interfaces), the additive change is: BeaconApi holds a list of listeners (one reserved token each; accept loop per listener; connections already transport-uniform via Stream), config becomes a list of binds. Router, handlers, connection handling untouched.

Probably OK for now. UDS would most likely be used for out bound connections to the EL, as EL and CL often run on the same machine. But on the listener side normally people run a VC on a different machine for security, maybe used by solo stakers or for testing but TCP is probably fine for those cases too.

note that you do not need an 'accept loop' for each listener - it is simply another token registered with the poll and you handle as an accept when it becomes readable - this is how the tcp accept currently works with mio.

[Bronek]

@vladimir-ea @0w3n-d note a limitation in the C5, we may want to revisit it:
Single beacon_api bind As of C5 the node binds exactly ONE listener — TCP or UDS, chosen by beacon_api_bind. If we want simultaneous surfaces (local VC over UDS + TCP on specific interfaces), the additive change is: BeaconApi holds a list of listeners (one reserved token each; accept loop per listener; connections already transport-uniform via Stream), config becomes a list of binds. Router, handlers, connection handling untouched.

Probably OK for now. UDS would most likely be used for out bound connections to the EL, as EL and CL often run on the same machine. But on the listener side normally people run a VC on a different machine for security, maybe used by solo stakers or for testing but TCP is probably fine for those cases too.

note that you do not need an 'accept loop' for each listener - it is simply another token registered with the poll and you handle as an accept when it becomes readable - this is how the tcp accept currently works with mio.

Yes, which is why I think this should be a cheap fix, so perhaps we just need to do it.

[Bronek]

Updated docs/adr in 828ebdb to include streaming in scope, for future implementation of /eth/v1/events (polling is wasteful on resources)

[Bronek]

Beacon API: endpoints implemented

All endpoints are JSON over HTTP/1.1 (TCP and Unix sockets), served synchronously from the node's published head state. Target compatibility is the union of the five mainstream validator clients (Lighthouse, Teku, Nimbus, Prysm-REST, Vouch); error-code and response-shape choices were verified against client source, not just the OpenAPI schema.

Node & configuration

Endpoint	Status	Notes
GET /eth/v1/node/version	✅ Complete
GET /eth/v1/node/identity	✅ Complete
GET /eth/v1/node/health	✅ Complete	Shares its sync predicate with syncing
GET /eth/v1/node/syncing	✅ Complete	Distance-based; honest pre-bootstrap answers
GET /eth/v1/node/peer_count	✅ Complete
GET /eth/v1/config/spec	✅ Complete	Serves every key clients gate on; CONFIG_NAME derives from the genesis fork version when a config file leaves it unset
GET /eth/v1/config/fork_schedule	✅ Complete
GET /eth/v1/config/deposit_contract	✅ Complete
GET /metrics	✅ Complete	Non-spec extra (Prometheus)

Chain & state reads

Endpoint	Status	Notes
GET /eth/v1/beacon/genesis	✅ Complete
GET /eth/v1/beacon/states/{state_id}/fork	✅ Complete
GET /eth/v1/beacon/states/{state_id}/finality_checkpoints	✅ Complete
GET /eth/v1/beacon/blocks/{block_id}/root	🟡 Partial	head, finalized, the head block's own root, and any slot still recorded in the state's block_roots ring; every other root needs the block-store read path
GET /eth/v1/beacon/headers/{block_id}	🟡 Partial	The head block's header only, under all three of its names (head, its slot, its root), and only from the next slot's process_slot — a just-arrived block's latest_block_header still carries a zero state_root, so the root endpoint can name it while the header endpoint cannot. Older slots and finalized name a root but have no header here; the arbitrary-root and list forms need the block-store read path

{state_id} is served for the head keyword alone: a slot number or a state root is answered 404 even when it names the published state itself, and historical state queries are out of scope until a storage read path exists.

Validator registry

Endpoint	Status	Notes
GET /eth/v1/beacon/states/{state_id}/validators	✅ Complete	id/status filters; unfiltered full-registry reads served (measured at mainnet scale)
POST /eth/v1/beacon/states/{state_id}/validators	✅ Complete	Unchunked full-keyset posts from all clients handled
GET /eth/v1/beacon/states/{state_id}/validators/{validator_id}	✅ Complete

Duties

Endpoint	Status	Notes
GET /eth/v1/validator/duties/proposer/{epoch}	✅ Complete
GET /eth/v2/validator/duties/proposer/{epoch}	✅ Complete	Lighthouse calls v2 by default; both served
POST /eth/v1/validator/duties/sync/{epoch}	✅ Complete	Both sync-committee periods within reach

Attester duties are not yet served — they need the per-epoch shuffling publication (tracked separately) and only make sense together with the rest of the attestation duty cycle.

Silver targets post-Fulu networks only, and the v2 duty-dependent root is served accordingly: beacon-APIs now defines it unconditionally as start_slot(epoch - 1) - 1 (ethereum/beacon-APIs#590 superseding the fork-conditional form of #563), which assumes a chain that is post-Fulu throughout. The physically different answer at a Fulu activation boundary on a pre-Fulu chain is deliberately out of contract.

Validator receipt endpoints

These accept and validate requests so validator clients run their duty loops against this node, but the node does not yet act on the submitted data. Each limitation is stated in the serving code and commit history.

Endpoint	Status	Notes
POST /eth/v1/validator/register_validator	🟡 Accepted, not acted on	No builder-network integration yet; 415 content negotiation in place
POST /eth/v1/validator/prepare_beacon_proposer	🟡 Accepted, not acted on	No block-production consumer yet
POST /eth/v1/validator/liveness/{epoch}	🟡 Interim	Answers not-live for every index (spec-legal best-effort); warns on every call — doppelganger detection is not yet backed by observed data
POST /eth/v1/validator/beacon_committee_subscriptions	🟡 Stub	Accepted and logged; no subnet control channel yet
POST /eth/v1/validator/sync_committee_subscriptions	🟡 Stub	Accepted and logged; no subnet control channel yet

Transport & robustness

• Hand-rolled non-blocking HTTP/1.1 server (mio), no TLS, JSON only for now (SSZ planned with the block/attestation publish family).
• Oversized request bodies (beyond the 16 MiB read buffer) are answered with 413 at header-parse time, off the declared Content-Length, before a body byte arrives — large operators post entire validator sets unchunked. The connection then half-closes and drains the in-flight body (nginx-style lingering close), so the client reliably receives the status instead of a connection reset — the difference between a logged error and a failover in some client stacks. A request whose framing cannot be parsed at all takes the same path with a 400; HTTP/1.0 gets 505.
• Request/response deadlines on both directions; event streams (SSE) are not yet served (404).

Not yet implemented (planned, currently blocked, another PR to come)

Attester duties and the attestation data/aggregation/publish family, block production and publish, historical block/state reads, SSZ request/response encoding, and event streams. Each is gated on a cross-component capability (shuffling publication, fork-choice head publication per block, a storage read path, a gossip-publish primitive) rather than on API-layer work.

[Bronek]

Minor correction to the "Serve the validator client's receipt POSTs" 93cf03a . It justifies the 415 on register_validator by saying Teku posts the registrations as application/octet-stream first and turns SSZ off only inside its 415 handler. That is wrong for production Teku: the SSZ-first machinery in RegisterValidatorsRequest exists, but its only non-test call site constructs it with preferSszEncoding=false hardcoded (OkHttpValidatorTypeDefClient.java:179, at teku 8bf7e9ea81), so Teku sends these registrations as JSON and never exercises the 415. Teku's block publish does use genuine SSZ-first with a sticky 415 downgrade, which is where the claim was generalized from.

The code is unaffected — the 415 is correct because this endpoint's schema declares it, whoever triggers it — and the code comments repeating the Teku claim were already rewritten in "Correct client-behaviour claims and the v2 dependent root".

[vladimir-ea]

references a machine local file

[Bronek]

Thanks, will remove. For reference - the useful output of these trial designs has been preserved in #81 (comment)

[vladimir-ea]

here also

[Bronek]

thanks, will replace with actual VCs from the document.

[Bronek]

More details on this preserved in #81 (comment)

[vladimir-ea]

note that when we run flux in 'park' mode (instead of busy spin) we can poll for non-zero duration if we register an mio Waker with the Flux work signal, e.g. in the network tile:

impl Tile<SilverSpine> for NetworkTile {
    fn loop_body(&mut self, adapter: &mut SpineAdapter<SilverSpine>) {
        self.body(adapter);
    }

    #[cfg(feature = "thread_park")]
    fn try_init(&mut self, adapter: &mut SpineAdapter<SilverSpine>) -> bool {
        const WAKER_TOKEN: Token = Token(3);

        let waker = mio::Waker::new(self.inner.poll.registry(), WAKER_TOKEN)
            .expect("failed to create network waker");
        adapter.register_waker(waker);
        true
    }
   ...

this is maybe worth doing b/c poll with duration ZERO can impact throughput negatively

[Bronek]

Agreed — and for this tile it's a correctness point rather than only throughput.

The flux work signal fires on spine publishes alone, so socket readiness can never reach it, and the tile loop parks whenever !worked && !waker_registered (flux/src/tile/mod.rs:151). The application-boundary tile registers no waker, so a park build would sleep through an inbound HTTP request until unrelated spine traffic happened to wake it — request latency bounded by the spine rather than by readiness.

Applying your pattern needs one change first: this tile drives two independent Polls (beacon_api/src/server.rs:119 and engine_api/src/client.rs:85), and blocking in either starves the other. So the tile will own a single Poll, both sides registering into that one registry over a partitioned token space, and then the waker plus a non-zero timeout drops in exactly as you wrote it. Its own commit with a measurement, after this PR.

ADR-0004 now records that Duration::ZERO is the busy-spin build's mechanism and not the decision.

Separately, and not this PR: silver/thread_park expands to ["flux/park", "silver_common/thread_park"] and never enables silver_network/thread_park. cargo tree -p silver --features thread_park resolves silver_network with no features, so NetworkTile::try_init isn't compiled and POLL_TIMEOUT stays Duration::ZERO — the network tile parks with no waker in a park build. The code itself is fine (cargo check -p silver_network --features thread_park passes), it's just unreachable from the binary's own feature. Happy to file it if you want it tracked.

[ninaiiad]

we don't need these?

[ninaiiad]

?

[Bronek]

Same coupling from the writing side: this makes the block-import path maintain a third copy of the head root, beside last_applied_block_root and fork choice's own find_head(). It goes with the control-word field. Answered in full on the status_event thread: #81 (comment)

[ninaiiad]

if you need a head root, ideally you derive it from this event and cache until a new update comes in

[Bronek]

Agreed, and the strongest argument for your shape is that we already do it for the flag sitting right next to the root. head_optimistic travels on this same event, gets cached in NodeStatus by the boundary tile's refresh_node_status, and is read back as execution_optimistic(). So today one field of the same response envelope arrives by event-and-cache and the other by a 32-byte addition to the state's seqlock control word. That is indefensible as a pair, and the event is the side to unify on.

The coupling is worse than one field, too: set_head_block_root makes the state's block-import path maintain a third copy of something fork choice already owns, beside last_applied_block_root and find_head(), and ControlInner is the hottest read path in the state architecture carrying a value no state read uses.

One sequencing constraint before I rip it out. status_event is produced at startup, on ReplayComplete, and on SlotStart when the state advanced or the head moved (tile.rs:641, :713, :726) — nothing publishes it on block import. Blocks land ~4 s into a slot, so a cache fed by today's event would name the previous head for the rest of the slot, which is the exact window the control-word field was added to cover: the state's latest_block_header names the parent until the next process_slot, and the block_roots entry naming the new block is written by that same process_slot. Caching now would regress GET /eth/v1/beacon/blocks/head/root and headers/head to a wrong-but-plausible answer for roughly half of every slot.

That publish cadence is CL-118 item 1 ("head block root published per accepted block, not per slot"), which we already believe is in your branch's scope. So the order I would like is:

1. BeaconStateEvent::Status carries head_block_root explicitly and is published per accepted block. Explicitly, please, not read out of the ssz Status payload — the API parsing the p2p wire format to find it would just trade this coupling for a worse one.
2. The boundary tile caches it in NodeStatus beside head_optimistic.
3. ControlInner::head_block_root, set_head_block_root, and read_head's root parameter all come out.

Steps 2 and 3 are mine and I will do them as soon as 1 lands — tell me if your branch already publishes per block and I will start now.

Residual worth naming: the cache is a separate observation from the seqlock read, so a state read can be one publish ahead of the cached root, where today they are atomic. For "what is the head root" an off-by-one names the previous head, which is what every other client's cached head does, and execution_optimistic already has exactly that property — so this makes the envelope internally consistent rather than less so. I do not think the atomicity is worth the coupling.

[Bronek]

Correcting myself: my cadence claim above was wrong. on_accept produces a status event unconditionally (orphan_pool.rs:197), and its only two callers are handle_gossip (gossip.rs:727) and handle_rpc_block (orphan_pool.rs:245) — both block-import paths. So every accepted block does publish a status event, and I was wrong that the head root would go stale mid-slot. I had grepped tile.rs alone and missed orphan_pool.rs. There is no CL-118 item 1 dependency here.

But the two mechanisms do not carry the same value, and that is what is left to settle.

set_head_block_root records the root of the block just applied — block.rs:341-342 sets it beside last_applied_block_root, before recompute_head(). The status event computes head_root = self.fork_choice.find_head() (tile.rs:467). Those diverge whenever fork choice does not head the block that was just applied: a late or equivocating proposal, or an import onto a non-canonical branch.

That matters for headers/{block_id}, because it returns a root and a header that must describe the same block. The header comes from the published state's latest_block_header, i.e. from last_applied. Pair it with find_head()'s root and, exactly when the two disagree, we serve one block's root beside another block's header. Today the control word makes that pairing consistent by construction, since both sides come from last_applied — which is also why blocks.rs can only assert canonical: true rather than prove it.

So I still want the coupling gone, on the event, and what I need on the event is the root of the block the published state was applied from — not, or not only, the fork-choice head. Concretely: BeaconStateEvent::Status carrying head_block_root as an explicit field (it is currently only inside the ssz payload, and the API parsing the p2p wire format to dig it out would be a worse coupling than the one we are removing), with the applied-block root either as that field or beside it. CL-118 item 7 already asks for a purpose-built head-changed event carrying the head block root and head state root together, which is the natural home if you would rather not widen Status.

Tell me which of the two roots you would rather publish and I will do the API side — cache it beside head_optimistic and delete ControlInner::head_block_root, set_head_block_root and read_head's root parameter. If you publish the fork-choice head only, that is still workable; it just means headers/head has to stop serving a header whenever the published state's own block is not the head, rather than pairing them and hoping.

[Bronek]

(actual @Bronek here): we (Claude and me) made a mistake of using grep rather than LSP. Corrected.

[Bronek]

You are right, and my objection was worse than wrong — it was contradicted by the crate I was defending. beacon_api already imports from ssz_view (crates/beacon_api/src/config.rs:17), and ssz_view:: appears in around sixty files across nearly every crate in the workspace, including control, columns, peer, storage and engine_api. There is no p2p boundary being crossed; SSZ views are how this project reads bytes. Withdrawn.

It also makes the fix smaller than what I proposed, which I should have found before arguing. StatusView::head_root already exists (crates/ssz/src/ssz_view.rs:1292, offset 44), so the fork-choice head root is available to the API today from the event it already consumes — no new field on BeaconStateEvent::Status, no tile change at all. The API caches StatusView::head_root(&ssz) in NodeStatus beside head_optimistic, and ControlInner::head_block_root, set_head_block_root and read_head's root parameter come straight out.

So the only thing still open is the semantic question from my previous comment, which the SSZ point does not touch: the Status payload's head root is fork_choice.find_head() (tile.rs:467), while the control word carries the root of the block the published state was applied from (block.rs:341-342, before recompute_head()). GET /eth/v1/beacon/headers/{block_id} has to return a root and a header describing the same block, and the header comes from the published state's latest_block_header — so on a late or equivocating proposal, pairing find_head()'s root with that header names two different blocks.

I can handle that entirely on the API side without asking you for anything: the event already carries latest_block_slot, and StatusView::head_slot gives the head's slot, so when the published state's block is not the head I withhold the header rather than pairing them. That leaves one residual — a same-slot equivocation is invisible to a slot comparison — which I would rather accept than keep the control-word field for. Both endpoints' existing tests cover the divergence case, so I will pin that behaviour explicitly.

Unless you would rather the applied-block root be published, I will take that route: no tile change, no event change, coupling gone.

[ninaiiad]

given that we aren't able to support these forks I would prefer to remove this

[ninaiiad]

do we need these?

[ninaiiad]

doesn't this just test the parser?

[ninaiiad]

?

[Bronek]

This field is the coupling you flagged on the tile's status_event — a value no state read uses, in the control word every state read goes through. Agreed it should not be here; it comes out once the head root is published per accepted block on BeaconStateEvent::Status. Answered in full there: #81 (comment)

[Bronek]

@clanky-gattaca review

[alexX512]

Why not a constant with array? Also from where we get that numbers?