The consensus client drives one or more execution clients through authenticated
JSON-RPC. The Engine API uses a port separate from the public JSON-RPC port.
The default is TCP port 8551.
Authentication
Every HTTP request uses an Authorization: Bearer <token> header. The token is
an HMAC-SHA256 (HS256) JWT made from a shared 256-bit secret. It includes an
iat claim. The server rejects alg: none, a bad signature, or an issue time
more than 60 seconds from its clock. A WebSocket authenticates its initial HTTP
upgrade only; in-process IPC needs no JWT.
The two clients obtain the shared secret through local secure setup. They do not exchange it over the Engine API.
Wire surface
engine_exchangeCapabilities exchanges full versioned method names. The
execution client must support it, the request and response use a one-second
timeout, and the response must not include the capability method itself.
DATA values use even-length 0x-prefixed hex. QUANTITY values use minimal
big-endian 0x-prefixed hex.
Ordering and failure handling
The consensus client sends fork-choice updates in event order. The execution client processes them in receive order. A timeout leaves the outcome unknown, so the consensus client retries when it still needs the result.
Only one consensus writer may control an execution client's head and payload builds. Other consensus clients may submit payloads or read data. General many-writer control has undefined behavior.
Design rationale
A separate authenticated port keeps consensus control away from the public JSON-RPC surface and supports a simple shared-secret setup.