ZEVM Internal Support: Transport And Error Semantics

This page is non-normative support for:

Use the JSON-RPC contract for exact request/response tuples and method-level error mapping.

1. Transport Invariants

HTTP JSON-RPC 2.0 only
JSON-RPC endpoint path is / only
JSON-RPC method is POST only
request path other than / returns HTTP 404 with no JSON-RPC body
non-POST request to / returns HTTP 405 with no JSON-RPC body
POST / must use content type application/json (media-type parameters allowed); unsupported or missing content type returns HTTP 415 with no JSON-RPC body
JSON-RPC success and error envelopes return HTTP 200
notification-only request or notification-only batch returns HTTP 204 with empty body
request bodies larger than 1,048,576 bytes return HTTP 413 with no JSON-RPC body
HTTP headers are read through an 8,192 byte buffer; oversized or malformed headers close the connection without a JSON-RPC body
the phase-1 listener has a fixed 64 active TCP connection limit, 15,000 ms read timeout, and 15,000 ms write timeout
connection handling is concurrent up to the active connection limit; JSON-RPC handler dispatch is serialized per process to protect runtime state
server shutdown stops the accept loop, shuts down active connection sockets, and waits for active connection handlers to exit before listener deinit returns
one canonical ZEVM-owned HTTP transport/parser stack is the shipping path for request parsing and envelope dispatch; divergent production parser stacks are outside the phase-1 contract
whenever a JSON body is returned, content type is application/json

single requests are supported
batches are supported
empty batch [] is invalid request content and returns JSON-RPC -32600 with id: null
notification means request object without id
notifications do not produce JSON-RPC response bodies
mixed batches return responses only for entries that included id, in the same relative order as those entries in the request batch
"id": null is not a notification and receives a response

method unsupported in active mode: -32010
light mode not ready for proof-backed reads: -32011
reserved startup checkpoint-age condition code (not runtime-emitted): -32012
reserved startup checkpoint-malformed condition code (not runtime-emitted): -32013
proof verification failed: -32014
malformed data from upstream proof source: -32015

malformed addresses, selectors, quantities, hex values, tuple lengths, and invalid field combinations fail with -32602
well-formed request for a method defined by the contract but unavailable in active mode fails with -32010
well-formed request using a deferred/out-of-contract JSON-RPC method name fails with -32601
trusted lookup misses for block/tx/receipt-returning methods return null
eth_getLogs with no matches returns []
stale/malformed selected startup checkpoint failures happen before listening; -32012 and -32013 remain reserved and are not emitted once the listener is active
WebSocket remains transport-level unsupported; it is not a JSON-RPC method-level error mapping

phase-1 release qualification verifies transport behavior on the shipping path using a real bound HTTP listener socket in trusted mode and in light startup/resume coverage
notification-only single requests and notification-only batches are explicitly verified to return HTTP 204 with empty body
release verification is expected to exercise one canonical ZEVM-owned HTTP transport/parser stack on the shipping path (no divergent production parser stacks)