[wemeetagain]

Motivation

Ethereum P2P traffic is both bursty and adversarial. A peer can authenticate correctly and still send incomplete frames, advertise work that never arrives, withhold stream progress, or create more validation and serving work than the node can finish. Healthy slot-boundary bursts also exhaust queues. The node needs explicit rules for which work it admits, which work it retains, and when it recovers capacity.

This branch puts discovery, transport, protocol state, and gossip scheduling under one native owner. The goal is to make the cost and lifetime of remote work visible across the whole path: receipt, decoding, validation, forwarding, response production, and retirement. An item limit alone misses large payloads; a byte limit alone misses many small jobs; a timeout alone does not stop a database read or validation task that already started. Those distinctions drive the design.

The workload also includes substantial block and data-column fanout. Shared payload storage, explicit writable events, and batched UDP I/O let the implementation serve that workload while keeping pressure decisions in the protocol owners. The accompanying Lodestar integration, ChainSafe/lodestar#10375, supplies consensus validation, chain state, serving sources, and operating policy.

Description

Adds a native Ethereum beacon networking stack and Node binding, with bounded admission and explicit ownership from sockets through host delivery.

Ownership and execution

Owner	Responsibility	Boundary
udp, discv5, and quic	Datagram I/O, discovery, authenticated connections, streams, and transport events	Transport progress and protocol deadlines are explicit; connection and stream handles carry generations.
NetworkCore and its protocol owners	Negotiation, identify, peer lifecycle, request/response, gossipsub, and discovery-to-dial coordination	One thread serializes protocol state. Peer selection combines local demand, coverage, reputation, and outbound/trial capacity.
Gossip processor	Per-kind admission, grouping, dependency waits, slot eligibility, and selection for validation	Lodestar answers dependency checks and runs its existing validators. Compressed retention, decoded storage, and host execution have separate allowances.
NAPI runtime and JavaScript pump	Bounded operation storage, copied payload delivery, notifications, and completion settlement	A mutex protects shared bridge transitions. Host callbacks run on the owning JavaScript thread, outside that mutex.
Lodestar host	Consensus decisions, BLS/regen capacity, database and chain reads, configuration, and persistence	The host reports capacity and outcomes; native retains protocol ownership.

NetworkCore.advance performs one bounded turn from supplied readiness and time. The driver waits on socket/host readiness or the earliest scheduled work, then advances the core with a fresh clock. A blocked stream waits for writable readiness; retained events and unfinished bounded work keep the owner runnable. Monotonic deadlines are distinct from Unix time and consensus slots. This gives socket-driven production operation and deterministic tests the same protocol entry points.

The Node API exposes createNativeNetwork(config, host), promise-returning operations, and response iterators. Its internal exchange applies host actions and delivers bounded batches. Capacity notifications can coalesce and cause a fresh capacity read; they grant no reservation. Status and subscription intent can coalesce to the latest desired state, while operation completions and close obligations retain their own lifetimes. The public binding contract documents these distinctions.

Capacity and behavior under pressure

• configuration and Reservations: derive table and buffer requirements at startup and reject configurations that do not fit the configured budgets. Bound retained entries, payload bytes, and work per turn separately. Accounting covers allocations made through the owning allocator; its limits are not a whole-process RSS guarantee.
• delivery, gossip admission, and serving pools: combine global limits with per-peer or per-source allowances and dedicated capacity for control work. Forwarding descriptors have a protected per-peer share, with bounded borrowing from the remainder. Bulk traffic must not consume the capacity needed to complete control and lifecycle work. These rules limit monopolization; they do not establish that distinct peer identities are independent operators.
• Gossip receive storage: charge shared pages as bytes arrive, rather than reserving an advertised frame length. Under pressure, prefer incomplete frames below 25% completion, then reclaim the most pages within that band. Completion provides a preference, not immunity. An absolute large-frame deadline prevents drip-fed progress from retaining storage indefinitely.
• active_send: distinguish a queued forward from a frame already started on a reliable stream. Small active frames own a per-session copy; large frames retain shared payload backing under a separate per-kind allowance. History expiry can discard queued work without invalidating started frames. Large recipients share the payload's first-send deadline, so adding recipients does not extend its lifetime. An active-send deadline violation closes the connection. Complete-frame ordering also means control traffic can wait behind that frame for its bounded lifetime.
• Gossip validation and request serving: protocol expiry stops forwarding or response obligations, but delivered work remains charged until its host completion. A canceled request cannot immediately recycle capacity still occupied by asynchronous reads, serialization, or validation. Generation checks prevent a late result from acting on a reused slot.
• Peer reports: local queue pressure, resource refusal, and local cancellation are distinct from remote protocol faults. Delayed validation and response decoding carry the connection and endpoint observed with the work. Reconnecting a peer does not retroactively attribute old work to its new endpoint; unknown or mixed-path evidence stays unknown.

The beacon integration supplies the policy values, including message-kind limits and receive/send deadlines. They remain configurable at initialization. The adversarial assumptions and the limits of native/dependency accounting are documented in THREAT_MODEL.md.

Lifecycle and failure handling

One network runtime is live per process. stopDelivery stops new host work while completion processing continues. close stops native work, joins the owner, and resolves outstanding operation obligations; already-started host tasks can finish later. Explicit close and Node environment teardown both have cleanup paths.

Operational failures belong to the affected request, publication, or connection. Infrastructure failures terminate the runtime with their original cause. Once an exchange has committed ownership transitions, failure to construct or publish its result while JavaScript is still runnable is a fatal bridge-contract failure. Silently losing that result would strand obligations on both sides of the binding.

Other scope in this draft

• leveldb: adds bounded reads and result materialization, copied asynchronous inputs, and explicit cursor ownership through the native addon. Each handle allows two concurrent point/multi-get reads alongside serialized writes, cursors, and maintenance. Callers await writes before dependent reads. These are application admission/result bounds, not bounds on LevelDB's internal cache, compaction, or total memory. The companion controller migration applies to both network backends; the storage contract describes the independent adoption decision.
• Transport and build integration: pins quiche 0.30.0 through quiche-zig, including STOP_SENDING cause propagation and the C transport-parameter layout fix. Linux UDP uses bounded recvmmsg/sendmmsg batches and GSO with fallback. The branch also includes the ere archive compatibility work needed to link/load the combined addon.
• Observability: uses existing Lodestar metric names where semantics match, adds pressure and owner-phase measurements, and bounds log delivery. Optional Xray capture copies events into bounded storage and exports them from a dedicated Zig thread with replay/gap reporting. Capture timestamps describe application reads and transport acceptance, not arrival at a remote peer.
• Verification tools: includes deterministic time/I/O fixtures, socket integration tests, independent libp2p interoperability tests, fuzz targets, and focused network benchmarks/profiling support.

Validation

Recent local results for the current Zig revision:

test:network 16 shards, 1468 of 1468 tests, 123.8 s: passed
Test Files  53 passed (53)
Tests       922 passed | 20 skipped (942)

The binding run used the ReleaseSafe mainnet addon for x86_64-linux-gnu.2.35, CPU znver1. All ten network fuzz targets built in ReleaseSafe, replayed 120 corpus inputs, and passed three-second AFL smoke runs. The new transport-parameter handshake regression failed against the old dependency and passes with the patch. Repository formatting, tidy, and lint checks pass; formatting excludes downloaded dependency caches.

The preceding branch review also ran UDP, LevelDB, config/runtime, minimal-preset support, network tools, independent JS-libp2p interop, and real-collector Xray integration checks. These checks are distinct from full platform qualification and sustained adversarial fuzzing.

Before merge

• Resolve or explicitly accept the remaining quiche receive-memory risk tracked in cloudflare/quiche#2814. Fragment metadata/allocation overhead is outside the application's receive-byte accounting, and data behind a gap can remain below application visibility. This branch does not fix that risk.
• Qualify that decision with established-connection stream sequencing and allocation observations. The raw-datagram fuzzer covers parsing/admission, not encrypted stream-fragment lifecycles.
• Review separation of native LevelDB adoption, Xray integration, and ere compatibility from the network change.
• Complete supported-platform and packaged-artifact checks, dependency release ordering, and upstreaming of the local quiche fixes.

The native beacon path currently supports through Fulu. A future Gloas schedule is allowed, but activating Gloas or requesting unsupported native topics/serving is rejected.

AI Assistance Disclosure

Implementation, tests, and this description were primarily authored with OpenAI Codex, with architecture and policy decisions developed through iterative maintainer direction. This is a draft for human review.