Skip to content

http-api.md

Latest commit

 

History

History
91 lines (71 loc) · 3.34 KB

http-api.md

File metadata and controls

91 lines (71 loc) · 3.34 KB
Raw

HTTP API reference

Purpose: the HTTP surface external apps use. The machine-readable source of truth is GET /openapi.json (built in src/openapi.rs); this page is the human-friendly companion. If they disagree, the code/openapi wins — fix this page. Status: current as of 2026-06-04 (commit bb69635).

Base URL: http://127.0.0.1:9909 (configurable via DINNER_BIND). Permissive CORS. No authentication and no secrets are served here.

Method Path Purpose
GET /health capability probe (backend, readiness, version, docs link)
GET /openapi.json this API as OpenAPI 3.1
POST /v1/prove enqueue a proving job
POST /v1/prove/jobs alias of /v1/prove (gateway-compatible clients)
GET /v1/prove/jobs/:id poll a job
GET /v1/activity recent proof activity

Prove

POST /v1/prove

{ "payload": { "any": "json" }, "network": "mainnet", "label": "optional" }
  • network: "mainnet" (default) or "testnet".
  • If the body has no payload key, the whole body is treated as the payload.

Response 202:

{ "job_id": "p0", "status": "queued", "status_url": "/v1/prove/jobs/p0" }

Poll

GET /v1/prove/jobs/:id → 200:

{ "job_id": "p0", "status": "succeeded", "label": "demo", "result": { /* proof */ } }

status ∈ queued | proving | succeeded | failed. On failure, error is set. 404 if the id is unknown (jobs are in-memory and lost on restart).

Example

ID=$(curl -s -XPOST localhost:9909/v1/prove \
  -d '{"network":"testnet","payload":{"x":1}}' | jq -r .job_id)
curl -s localhost:9909/v1/prove/jobs/$ID | jq

Agent / client quickstart

dinner is self-describing — point a client/agent at the base URL and:

  1. GET / — the response explains how to prove (submit + poll), the payload shape, and the rules. That alone is enough to use it; the steps below are the same thing spelled out.
  2. Confirm it's up & which backend: GET /health (prover, prover_ready). For docker, prover_ready is false when the daemon is down; for native, when the local prover stack is missing. A failed request means dinner isn't running.
  3. Formal contract: GET /openapi.json (OpenAPI 3.1).
  4. Submit + poll: POST /v1/prove → {job_id}; then GET /v1/prove/jobs/:id until status is succeeded (proof in result) or failed (error).
  5. You must send an already-signed transaction — dinner never signs. For the docker backend the body is: 
    {
  "network": "mainnet",
  "payload": {
    "transaction":  { /* signed invoke-v3 Tx A */ },
    "block_number": 1234567
  }
}
    block_number is optional (omit → RPC latest − 2). When you include it, the virtual tx's nonce must match the account nonce at that exact block — dinner runs a preflight check and returns a clear error if they differ. See docker-prover.md for the full payload + result shape and the RPC-spec-≥0.8 requirement.
  6. Success returns result.proof, result.proof_facts, and result.l2_to_l1_messages (the messages the contract emitted; [] if none).

Not on HTTP

Settings (per-network RPC/prover/keys) and storage management are IPC-only (desktop app) — see desktop.md — because they carry secrets.