feat: implement Engine API to interface with execution layer clients
- Dominant language
- Zig
- Stars
- 97
- Forks
- 39
- PR merge metrics
- No merged PRs in 30d
Description
## Summary
Implement the Ethereum **Engine API** in zeam so the consensus layer can drive and communicate with an external **execution layer (EL) client** (Geth, Reth, Nethermind, Besu, Erigon, …). Today zeam is consensus-only; this adds the standard CL↔EL control channel used for payload production, payload validation, and fork-choice/head signalling.
This is the Engine-API slice of the broader execution-integration direction tracked in the (now closed) EPIC #324 — scoped here as a standalone, independently-shippable piece.
## Motivation
To participate in a chain with an execution layer, the consensus client must:
- ask the EL to **build** an execution payload when proposing,
- **validate** execution payloads embedded in blocks it imports,
- tell the EL which block is **head / safe / finalized** so it can sync and reorg.
All of this happens over the authenticated Engine JSON-RPC channel. Without it, zeam cannot interoperate with any EL client.
## Scope
### 1. Engine JSON-RPC client (transport + auth)
- JSON-RPC 2.0 client over HTTP to the EL **authrpc** endpoint (default `:8551`).
- **JWT (HS256) authentication** per the Engine API spec: load the shared secret from a file, mint a token with an `iat` claim, send it as `Authorization: Bearer `, refresh within the allowed clock-skew window.
- Connection lifecycle: configurable endpoint + timeouts, retry/backoff, and clear surfacing of EL-down / auth-failure states.
### 2. Core Engine API methods
- `engine_newPayloadVX` — submit an execution payload for validation; handle `VALID` / `INVALID` / `SYNCING` / `ACCEPTED` statuses.
- `engine_forkchoiceUpdatedVX` (FCU) — set head/safe/finalized; with `payloadAttributes` to kick off payload building.
- `engine_getPayloadVX` — retrieve a built payload (+ block value / blobs bundle where applicable).
- `engine_exchangeCapabilities` — capability negotiation with the EL.
- Version negotiation so the right `VX` method is used for the active fork.
### 3. Wiring into zeam
- **Block production:** on propose, issue FCU-with-attributes → poll/`getPayload` → embed the returned execution payload into the produced block (respecting the proposal deadline).
- **Block import / fork choice:** call `newPayload` to validate the EL payload of imported blocks, and `forkchoiceUpdated` whenever zeam's head / finalized checkpoint changes, mapping CL fork-choice state onto the EL.
- Handle `SYNCING`/`ACCEPTED` (optimistic-import semantics) without stalling the consensus loop.
### 4. Configuration
- CLI / config: EL endpoint URL, JWT secret path, request timeout.
- Sensible defaults (`http://localhost:8551`) and clear startup logging of the configured EL.
## Out of scope (separate increments)
- In-process execution / EL block **proving** (the rest of #324).
- Blob/data-availability sidecar plumbing beyond what `getPayload`/`newPayload` return.
- Mainnet-specific payload fields not present on the target (lean) chain — include only the fields the active spec defines.
## References
- Engine API spec: https://github.com/ethereum/execution-apis/tree/main/src/engine
- JWT authentication: https://github.com/ethereum/execution-apis/blob/main/src/engine/authentication.md
- Related (closed) EPIC: #324
## Acceptance criteria
- [ ] Authenticated Engine JSON-RPC client with JWT, unit-tested against canned EL responses (incl. auth failure + `SYNCING`).
- [ ] `newPayload`, `forkchoiceUpdated`, `getPayload`, `exchangeCapabilities` implemented with per-fork version selection.
- [ ] Propose path requests and embeds an EL-built payload within the proposal deadline.
- [ ] Import / fork-choice path validates payloads and forwards head/finalized to the EL.
- [ ] Endpoint + JWT-secret configurable; clean failure surfacing when the EL is unreachable.
- [ ] End-to-end smoke against at least one real EL client (e.g. Geth or Reth), ideally wired into the existing Hive CI.
Contributor guide
No contributing guide indexed for this repository
Research direction
No repository files or tests are named. Start with the Engine API and JWT authentication references, then trace the existing proposal, block-import, and fork-choice paths described in the issue. Done means authenticated versioned Engine methods, configuration, consensus wiring, tests for canned EL responses, and a real-EL smoke test meeting the listed acceptance criteria.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- zig
- Domain
- api, blockchain, networking
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 25/100