docs(rpc): add HTTP API endpoint reference

[MegaRedHand]

What

Adds docs/rpc.md, a single reference page for the RPC crate's HTTP surface, and links it from the mdBook TOC. Trims the duplicated (and partially stale) endpoint list in CLAUDE.md down to a pointer at the canonical doc.

Contents

The page documents every endpoint with method, path, response format, status codes, error bodies, and content types:

• API server (:5052) — health, finalized state (SSZ), finalized block (SSZ), justified checkpoint, blocks by root/slot + header, fork-choice tree (JSON) + D3.js UI, runtime aggregator toggle (GET/POST).
• Metrics & debug server (:5054) — Prometheus /metrics, /health, jemalloc heap profiling (/debug/pprof/allocs + flamegraph).
• Hive test-driver endpoints — activated by HIVE_LEAN_TEST_DRIVER, the four POST /lean/v0/test_driver/... routes plus the health stub.

Why

Endpoint details were only in CLAUDE.md, where they had already drifted from the code (missing /lean/v0/blocks/finalized and the metrics-server /health). Keeping the reference in docs/ puts it next to the spec/ops docs and gives a single source of truth.

Verification

Documentation was fact-checked endpoint-by-endpoint against the source in crates/net/rpc (routes, handlers, content-type constants, status-code branches, and serde shapes for Checkpoint/H256/ForkChoiceResponse). The compact /health body and the /blocks/finalized 404 edge case are reflected accurately.

[github-actions]

🤖 Kimi Code Review

Documentation Structure: Good move extracting the HTTP API reference into a dedicated docs/rpc.md file. The CLAUDE.md overview is cleaner while preserving discoverability via SUMMARY.md.

Technical Accuracy Concerns:

1. Server Concurrency Model (docs/rpc.md:15 vs CLAUDE.md:282):

   • Old text: "Both servers are spawned as independent tokio::spawn tasks"
   • New text: "runs in a single tokio::spawn task... start_rpc_server then drives the two servers concurrently"
   • These are materially different architectures. Verify which is correct—if the code uses tokio::try_join! within one spawned task, the new description is accurate; if main.rs spawns two separate tasks, the old text was correct.

2. Implementation Detail Risk (docs/rpc.md:15):

   • "via tokio::try_join! when the ports differ, or one merged router when they're equal" describes specific implementation details that may drift from the code. Consider simplifying to "handles both cases appropriately" to reduce documentation maintenance burden.

3. External Reference (docs/rpc.md:93):

   • "ported from leanSpec PR #636" references an external repository's PR. For ethlambda documentation, either remove this or clarify the provenance. External PR references become dead context quickly.

Consistency Check:

4. Endpoint Verification:

   • The new /lean/v0/blocks/finalized endpoint (docs/rpc.md:44) and /lean/v0/admin/aggregator (docs/rpc.md:84-85) are significant additions not present in the old CLAUDE.md. Confirm these are implemented in the actual RPC server code—this diff shows only documentation changes.

5. Environment Variable (docs/rpc.md:122):

   • HIVE_LEAN_TEST_DRIVER=1 accepts 1/true/yes. Verify the implementation actually handles all three case-insensitively, or document only the canonical value.

Minor:

6. Line 96: The note about gossip subnets not being resubscribed implies specific networking behavior—ensure this matches the actual libp2p/gossipsub integration.

7. Line 114: "only functional on Linux" platform limitation—verify this is enforced in the code (e.g., via #[cfg(target_os = "linux")] or runtime checks).

Overall: The documentation is well-structured with clear tables and examples. Just verify the concurrency model description matches the actual main.rs implementation.

---

Automated review by Kimi (Moonshot AI) · kimi-k2.5 · custom prompt

[github-actions]

🤖 Codex Code Review

1. docs/rpc.md documents the admin endpoint as returning JSON, and the 400/503 table reads like structured API errors, but the implementation returns plain-text bodies on those paths via (StatusCode, &'static str).into_response(). That is an operator/client-visible contract mismatch: error handlers expecting JSON will fail to parse these responses. Either document these errors as plain text or change the handlers to emit JSON consistently. Code: crates/net/rpc/src/admin.rs.

2. docs/rpc.md says “The genesis/anchor block has no stored signature,” which is too broad. The storage layer only synthesizes a blank proof for the slot-0 genesis anchor; checkpoint-sync anchors are explicitly inserted with their fetched signature, and any other missing proof returns None/404. As written, the docs misstate finalized-block behavior after checkpoint sync. Wording this as “genesis block” instead of “genesis/anchor block” would match reality. Code: crates/storage/src/store.rs, bin/ethlambda/src/main.rs.

No other correctness, security, performance, or consensus-layer findings from this PR. The diff is docs-only, and it does not touch fork choice, attestation validation, STF, XMSS verification, or SSZ code paths. I did not run tests.

---

Automated review by OpenAI Codex · gpt-5.4 · custom prompt

[greptile-apps]

Greptile Summary

This PR adds a canonical HTTP API reference for the RPC crate. The main changes are:

• New docs/rpc.md page covering API, metrics/debug, admin, and Hive test-driver endpoints.
• New mdBook table-of-contents entry for the HTTP API page.
• Shortened CLAUDE.md HTTP server notes pointing to the new docs page.

Confidence Score: 5/5

This looks safe to merge.

• No blocking issues found in the changed code.

Important Files Changed

Filename	Overview
docs/rpc.md	Adds the HTTP API reference with endpoint paths, methods, response shapes, status codes, content types, ports, admin controls, metrics/debug routes, and Hive test-driver notes.
docs/SUMMARY.md	Adds the HTTP API page to the mdBook navigation using the existing relative-link style.
CLAUDE.md	Replaces the duplicated HTTP endpoint list with a pointer to the new canonical docs page.

_{Reviews (1): Last reviewed commit: "docs(rpc): add HTTP API endpoint referen..." | Re-trigger Greptile}

[github-actions]

🤖 Claude Code Review

Now I have everything I need to write the review.

---

Review: docs(rpc): add HTTP API endpoint reference (PR #476)

This PR adds docs/rpc.md, a comprehensive HTTP API reference for the RPC crate, wires it into the mdBook TOC in docs/SUMMARY.md, and replaces the now-duplicated (and partially stale) endpoint list in CLAUDE.md with a single-sentence pointer. The new documentation is thorough and was clearly verified endpoint-by-endpoint: all paths, status codes, response shapes, content types, and conditional-compilation behaviours (501 on non-Linux for heap profiling, HIVE_LEAN_TEST_DRIVER truthy values) checked out correctly against the source. The PR also quietly corrects a factual inaccuracy in CLAUDE.md — the old text claimed "both servers are spawned as independent tokio::spawn tasks" when in reality start_rpc_server is one tokio::spawn that internally runs both servers via tokio::try_join!.

---

Findings

docs/rpc.md:104 — Curl comment says "JSON boolean" but the body is a JSON object

The inline comment reads:

# Toggle role; body must be a JSON boolean
curl -X POST ... -d '{"enabled": false}'

The comment is wrong: the expected body is a JSON object ({"enabled": bool}), not a bare JSON boolean literal. The curl invocation on the next line is correct, but a reader skimming only the comment could send -d 'false' or -d 'true' and receive 400 Bad Request. The status-code table on line 113 is accurate ("missing enabled" is a 400 trigger), but it conflicts with the comment that implies the body itself is the boolean.

Suggested fix:

# Toggle role; body is a JSON object with an "enabled" boolean field

---

Minor notes (no action required)

• The test-driver response table (lines 135–141) lists type names (StepResponse, StateTransitionResponse, VerifySignaturesResponse) without spelling out the JSON field names. Those structs use #[serde(rename_all = "camelCase")], so fields like head_root serialize as headRoot. This is fine for an internal Hive driver, but worth noting if external tooling ever needs to parse these responses.

• The SUMMARY.md placement ("HTTP API" before "Metrics") is a sensible ordering change and reads well.

---

Automated review by Claude (Anthropic) · sonnet · custom prompt