openapi.json

{
    "openapi": "3.1.0",
    "info": {
        "title": "Proof Node API",
        "description": "HTTP API for CL to request execution proof generation/verification of different EL/zkVM combinations. Proofs are generated asynchronously; Server-Sent Events notify when a proof request completes or fails.",
        "version": "0.1.0"
    },
    "servers": [
        {
            "url": "http://localhost:3000",
            "description": "Default local server"
        }
    ],
    "paths": {
        "/v1/execution_proof_requests": {
            "post": {
                "operationId": "postExecutionProofRequests",
                "summary": "Submit an execution proof request",
                "description": "Accepts an SSZ-encoded ProofRequestBody (fork, payload, chain config, and proof types) and enqueues proof generation. Returns the tree-hash root computed from the submitted payload.",
                "requestBody": {
                    "required": true,
                    "description": "SSZ-encoded ProofRequestBody containing the active fork, the NewPayloadRequest (transparent union across fork variants), the chain config, and the proof types to generate.",
                    "content": {
                        "application/octet-stream": {
                            "schema": {
                                "$ref": "#/components/schemas/ProofRequestBody"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Proof request accepted.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ProofRequestResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Invalid SSZ body, a fork that does not select the submitted payload's schema, empty or missing proof_types, or unconfigured proof type.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                },
                                "examples": {
                                    "invalid_ssz": {
                                        "summary": "Invalid SSZ body",
                                        "value": {
                                            "code": 400,
                                            "message": "invalid SSZ body: OffsetOutOfBounds(0)"
                                        }
                                    },
                                    "unconfigured_proof_type": {
                                        "summary": "Unconfigured proof type",
                                        "value": {
                                            "code": 400,
                                            "message": "no zkVM configured for proof type 'reth-sp1'"
                                        }
                                    },
                                    "fork_payload_mismatch": {
                                        "summary": "Fork does not select the payload schema",
                                        "value": {
                                            "code": 400,
                                            "message": "submitted payload is not valid variant for fork Cancun"
                                        }
                                    },
                                    "empty_proof_types": {
                                        "summary": "Empty proof_types",
                                        "value": {
                                            "code": 400,
                                            "message": "proof_types must contain at least one valid value"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Internal queue failure.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                },
                                "example": {
                                    "code": 500,
                                    "message": "failed to enqueue proof: channel closed"
                                }
                            }
                        }
                    }
                }
            },
            "get": {
                "operationId": "getExecutionProofRequests",
                "summary": "Subscribe to execution proof events via SSE",
                "description": "Opens a Server-Sent Events stream for proof completion and failure notifications.\n\nThe server sends SSE comment lines (`:` prefix, per SSE spec) every 15 seconds as keep-alive. These are not events and should be ignored by conforming SSE clients.\n\nWhen `new_payload_request_root` is provided, the server first emits cached `proof_complete` events for cached proofs that completed before the subscription started (catch-up), then streams live events filtered to that root.\n\nCompleted proofs are held in a bounded LRU cache. Clients should download proofs promptly after receiving a `proof_complete` event, as proofs may be evicted under memory pressure.\n\n**Event types:**\n- `proof_complete` - Data payload: ProofCompleteEvent (JSON)\n- `proof_failure` - Data payload: ProofFailureEvent (JSON)",
                "parameters": [
                    {
                        "name": "new_payload_request_root",
                        "in": "query",
                        "required": false,
                        "description": "Filter events to only this root. When omitted, all events are streamed.",
                        "schema": {
                            "$ref": "#/components/schemas/Hash256"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "SSE event stream opened. Events are delivered as `text/event-stream`.",
                        "content": {
                            "text/event-stream": {
                                "schema": {
                                    "description": "SSE stream. Each message has an `event` field (event type name) and a `data` field (JSON payload). See the SSE event schemas for the payload format of each event type.",
                                    "type": "string"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v1/execution_proofs/{new_payload_request_root}/{proof_type}": {
            "get": {
                "operationId": "getExecutionProofs",
                "summary": "Download a completed execution proof",
                "description": "Returns the raw proof bytes for a completed proof identified by its root and proof type.",
                "parameters": [
                    {
                        "name": "new_payload_request_root",
                        "in": "path",
                        "required": true,
                        "description": "The root from the original proof request response.",
                        "schema": {
                            "$ref": "#/components/schemas/Hash256"
                        }
                    },
                    {
                        "name": "proof_type",
                        "in": "path",
                        "required": true,
                        "description": "The proof type to download.",
                        "schema": {
                            "$ref": "#/components/schemas/ProofType"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Raw proof bytes.",
                        "content": {
                            "application/octet-stream": {
                                "schema": {
                                    "type": "string",
                                    "format": "binary"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Proof not yet available or does not exist.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                },
                                "example": {
                                    "code": 404,
                                    "message": "proof not found for root 0xabcd...1234 and type reth-sp1"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v1/execution_proof_verifications": {
            "post": {
                "operationId": "postExecutionProofVerifications",
                "summary": "Verify an execution proof",
                "description": "Verifies an SSZ-encoded ProofVerificationBody against the server's configured zkVM backend. A 200 response with `INVALID` status means verification ran successfully but the proof did not pass. HTTP error codes (4xx, 5xx) mean the request itself was malformed or the server could not process it.",
                "requestBody": {
                    "required": true,
                    "description": "SSZ-encoded ProofVerificationBody containing the active fork, the payload root, the chain config, the proof type, and the proof bytes.",
                    "content": {
                        "application/octet-stream": {
                            "schema": {
                                "$ref": "#/components/schemas/ProofVerificationBody"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Verification result.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ProofVerificationResponse"
                                },
                                "examples": {
                                    "valid": {
                                        "summary": "Proof is valid",
                                        "value": {
                                            "status": "VALID"
                                        }
                                    },
                                    "invalid": {
                                        "summary": "Proof is invalid",
                                        "value": {
                                            "status": "INVALID"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Invalid SSZ body.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                },
                                "example": {
                                    "code": 400,
                                    "message": "invalid SSZ body: OffsetOutOfBounds(0)"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "The requested proof type is not configured on this server.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                },
                                "example": {
                                    "code": 404,
                                    "message": "unknown proof_type: reth-sp1"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v1/proof_types": {
            "get": {
                "operationId": "getProofTypes",
                "summary": "List configured proof types and their capabilities",
                "description": "Returns the list of proof types initialized on this server, along with their backend kind and capabilities (can_prove, can_verify). Useful for discovering what proof types are available before submitting requests.",
                "responses": {
                    "200": {
                        "description": "List of configured proof types.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ProofTypesResponse"
                                },
                                "example": {
                                    "proof_types": [
                                        {
                                            "proof_type": "reth-sp1",
                                            "kind": "ere",
                                            "can_prove": true,
                                            "can_verify": true
                                        },
                                        {
                                            "proof_type": "reth-zisk",
                                            "kind": "verifier",
                                            "can_prove": false,
                                            "can_verify": true
                                        }
                                    ]
                                }
                            }
                        }
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "ProofRequestBody": {
                "type": "object",
                "required": [
                    "fork",
                    "new_payload_request",
                    "chain_config",
                    "proof_types"
                ],
                "properties": {
                    "fork": {
                        "$ref": "#/components/schemas/ProtocolFork"
                    },
                    "new_payload_request": {
                        "$ref": "#/components/schemas/NewPayloadRequest"
                    },
                    "chain_config": {
                        "$ref": "#/components/schemas/ChainConfig"
                    },
                    "proof_types": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/ProofType"
                        },
                        "description": "Proof types to generate for this payload. Must be non-empty with no duplicates."
                    }
                },
                "description": "Logical field layout of the body for POST /v1/execution_proof_requests. The wire format is SSZ (application/octet-stream), not JSON."
            },
            "NewPayloadRequest": {
                "type": "object",
                "description": "Consensus-layer new-payload request, an SSZ transparent union across fork variants (Bellatrix, Capella, Deneb, Electra/Fulu, Gloas). See the consensus-specs NewPayloadRequest for the per-variant field layout.",
                "properties": {
                    "execution_payload": {
                        "type": "object",
                        "description": "The fork-dependent ExecutionPayload."
                    }
                }
            },
            "ChainConfig": {
                "type": "object",
                "required": [
                    "chain_id",
                    "active_fork"
                ],
                "properties": {
                    "chain_id": {
                        "type": "integer",
                        "format": "uint64",
                        "description": "EIP-155 chain id."
                    },
                    "active_fork": {
                        "$ref": "#/components/schemas/ForkConfig"
                    }
                },
                "description": "The chain configuration the proof is verified against. It carries chain_id and the activation point of the active fork. The fork itself is a sibling field of the request body."
            },
            "ForkConfig": {
                "type": "object",
                "required": [
                    "activation"
                ],
                "properties": {
                    "activation": {
                        "$ref": "#/components/schemas/ForkActivation"
                    }
                },
                "description": "Configuration of the fork active for the block."
            },
            "ProtocolFork": {
                "type": "integer",
                "format": "uint8",
                "minimum": 1,
                "maximum": 21,
                "description": "SSZ enum discriminant selecting the active execution-layer fork, in fork order, encoded as a single byte. It selects the stateless input schema the payload is encoded under. Values outside the assigned range are rejected when the body is decoded."
            },
            "ForkActivation": {
                "type": "object",
                "description": "Activation point of the fork. At least one of block_number or timestamp is set, each SSZ-encoded as a list of zero or one element.",
                "properties": {
                    "block_number": {
                        "type": "array",
                        "maxItems": 1,
                        "items": {
                            "type": "integer",
                            "format": "uint64"
                        },
                        "description": "Activation block number, for pre-merge forks."
                    },
                    "timestamp": {
                        "type": "array",
                        "maxItems": 1,
                        "items": {
                            "type": "integer",
                            "format": "uint64"
                        },
                        "description": "Activation timestamp, for post-merge forks."
                    }
                }
            },
            "ProofType": {
                "type": "string",
                "enum": [
                    "ethrex-openvm",
                    "ethrex-sp1",
                    "ethrex-zisk",
                    "reth-openvm",
                    "reth-sp1",
                    "reth-zisk"
                ],
                "description": "Case-sensitive identifier for an EL/zkVM combination."
            },
            "ProofRequestResponse": {
                "type": "object",
                "required": [
                    "new_payload_request_root"
                ],
                "properties": {
                    "new_payload_request_root": {
                        "$ref": "#/components/schemas/Hash256"
                    }
                },
                "description": "Response for a successful proof request submission."
            },
            "Hash256": {
                "type": "string",
                "pattern": "^0x[0-9a-f]{64}$",
                "minLength": 66,
                "maxLength": 66,
                "description": "A 32-byte hash represented as a 0x-prefixed lowercase hex string (66 characters total). The 0x prefix is required in both requests and responses.",
                "examples": [
                    "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
                ]
            },
            "ErrorResponse": {
                "type": "object",
                "required": [
                    "code",
                    "message"
                ],
                "properties": {
                    "code": {
                        "type": "integer",
                        "description": "HTTP status code."
                    },
                    "message": {
                        "type": "string",
                        "description": "Human-readable error message."
                    }
                },
                "description": "Standard error response returned by all endpoints on failure."
            },
            "ProofCompleteEvent": {
                "type": "object",
                "required": [
                    "new_payload_request_root",
                    "proof_type"
                ],
                "properties": {
                    "new_payload_request_root": {
                        "$ref": "#/components/schemas/Hash256"
                    },
                    "proof_type": {
                        "$ref": "#/components/schemas/ProofType"
                    }
                },
                "description": "SSE event payload for `proof_complete`. The proof can be downloaded at `/v1/execution_proofs/{new_payload_request_root}/{proof_type}`."
            },
            "ProofFailureEvent": {
                "type": "object",
                "required": [
                    "new_payload_request_root",
                    "proof_type",
                    "reason",
                    "error"
                ],
                "properties": {
                    "new_payload_request_root": {
                        "$ref": "#/components/schemas/Hash256"
                    },
                    "proof_type": {
                        "$ref": "#/components/schemas/ProofType"
                    },
                    "reason": {
                        "$ref": "#/components/schemas/FailureReason"
                    },
                    "error": {
                        "type": "string",
                        "description": "Human-readable error message with details about the failure."
                    }
                },
                "description": "SSE event payload for `proof_failure`."
            },
            "FailureReason": {
                "type": "string",
                "enum": [
                    "witness_timeout",
                    "proving_timeout",
                    "proving_error",
                    "internal_error"
                ],
                "description": "Reason a proof request failed. witness_timeout: witness fetch timed out. proving_timeout: proof generation timed out. proving_error: a general error occurred during proving. internal_error: an internal error occurred."
            },
            "ProofVerificationBody": {
                "type": "object",
                "required": [
                    "fork",
                    "new_payload_request_root",
                    "chain_config",
                    "proof_type",
                    "proof"
                ],
                "properties": {
                    "fork": {
                        "$ref": "#/components/schemas/ProtocolFork"
                    },
                    "new_payload_request_root": {
                        "$ref": "#/components/schemas/Hash256"
                    },
                    "chain_config": {
                        "$ref": "#/components/schemas/ChainConfig"
                    },
                    "proof_type": {
                        "$ref": "#/components/schemas/ProofType"
                    },
                    "proof": {
                        "type": "string",
                        "format": "binary",
                        "description": "The proof bytes to verify."
                    }
                },
                "description": "Logical field layout of the body for POST /v1/execution_proof_verifications. The wire format is SSZ (application/octet-stream), not JSON."
            },
            "ProofVerificationResponse": {
                "type": "object",
                "required": [
                    "status"
                ],
                "properties": {
                    "status": {
                        "$ref": "#/components/schemas/ProofStatus"
                    }
                },
                "description": "Response for a proof verification request."
            },
            "ProofStatus": {
                "type": "string",
                "enum": [
                    "VALID",
                    "INVALID"
                ],
                "description": "Verification result. VALID means the proof passed verification. INVALID means verification ran but the proof did not pass."
            },
            "ProofTypesResponse": {
                "type": "object",
                "required": [
                    "proof_types"
                ],
                "properties": {
                    "proof_types": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/ProofTypeInfo"
                        },
                        "description": "List of initialized proof types, sorted by proof_type."
                    }
                },
                "description": "Response for GET /v1/proof_types."
            },
            "ProofTypeInfo": {
                "type": "object",
                "required": [
                    "proof_type",
                    "kind",
                    "can_prove",
                    "can_verify"
                ],
                "properties": {
                    "proof_type": {
                        "$ref": "#/components/schemas/ProofType"
                    },
                    "kind": {
                        "$ref": "#/components/schemas/BackendKind"
                    },
                    "can_prove": {
                        "type": "boolean",
                        "description": "Whether this backend can generate proofs."
                    },
                    "can_verify": {
                        "type": "boolean",
                        "description": "Whether this backend can verify proofs."
                    }
                },
                "description": "Information about a single initialized proof type."
            },
            "BackendKind": {
                "type": "string",
                "enum": [
                    "ere",
                    "mock",
                    "verifier"
                ],
                "description": "Backend kind for a zkVM instance. ere: remote ere-server backend. mock: in-process mock backend for testing. verifier: in-process verifier-only backend (cannot prove)."
            }
        }
    }
}