> For the complete documentation index, see [llms.txt](https://corpus-core.gitbook.io/specification-colibri-stateless/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://corpus-core.gitbook.io/specification-colibri-stateless/developer-guide/apis/rest-api.md).

# REST API

The Colibri Stateless server provides a comprehensive REST API for generating and verifying cryptographic proofs for blockchain data. This API enables lightweight, stateless verification of Ethereum and Layer-2 blockchain operations.

## Overview

The API consists of the following main categories:

* **Proof Generation** - Create cryptographic proofs for blockchain data
* **Proof Verification** - Verify proofs and execute JSON-RPC requests
* **Beacon Chain API** - Light client sync endpoints for Ethereum consensus layer
* **Health & Monitoring** - Server health checks and Prometheus metrics
* **Configuration** - Server configuration management (requires WEB\_UI\_ENABLED)

## OpenAPI Specification

The complete API is documented using OpenAPI 3.1.0 specification. You can access the specification in the following ways:

### Live Server Endpoint

If you have a running Colibri server instance, the OpenAPI specification is available at:

```
http://localhost:8090/openapi.yaml
```

Replace `localhost:8090` with your server's host and port.

### Static Specification

The specification is also available in the source repository at:

```
src/server/openapi.yaml
```

## Interactive API Documentation

The OpenAPI specification below provides interactive documentation for all available endpoints.

**Note**: First, add the OpenAPI specification to GitBook via the OpenAPI panel or CLI, then replace `colibri-api` below with your spec name.

### Endpoints

## Verify and Execute JSON-RPC Request

> \*\*Primary Use Case: Local RPC Provider Replacement\*\*\
> \
> This endpoint is designed to serve as a \*\*complete, trustless replacement for traditional RPC providers\*\*. When running the Colibri server locally (using the \[installer packages]\(<https://corpus-core.gitbook.io/specification-colibri-stateless/developer-guide/installer>)), you can configure this endpoint as your RPC provider in wallets like MetaMask, enabling fully verified, trustless access to the blockchain without relying on third-party infrastructure.\
> \
> \*\*How It Works:\*\*\
> \
> The endpoint processes JSON-RPC requests through the following flow:\
> 1\. \*\*Proof Generation\*\*: Creates or fetches cryptographic proofs for the request (locally or from configured prover nodes)\
> 2\. \*\*Verification\*\*: Verifies the proof against the current sync committee state\
> 3\. \*\*Response\*\*: Returns the verified JSON-RPC response in standard format\
> \
> \*\*Supported Methods:\*\*\
> \
> This endpoint supports \*\*all\*\* Ethereum JSON-RPC methods, including:\
> \- Methods with proofs (see \[Supported RPC Methods]\(<https://corpus-core.gitbook.io/specification-colibri-stateless/specifications/ethereum/supported-rpc-methods))\\>
> \- Local methods without proofs (\`eth\_chainId\`, \`web3\_clientVersion\`, etc.)\
> \- Filter methods (\`eth\_newFilter\`, \`eth\_getFilterChanges\`, etc.)\
> \- Subscription methods (\`eth\_subscribe\`, \`eth\_unsubscribe\`)\
> \
> \*\*Local Setup Example:\*\*\
> \
> \`\`\`bash\
> \# Install and run locally (macOS/Linux/Windows)\
> \# See: <https://corpus-core.gitbook.io/specification-colibri-stateless/developer-guide/installer\\>
> \
> \# Configure in MetaMask:\
> \# Network Name: Colibri Verified Ethereum\
> \# RPC URL: <http://localhost:8090/rpc\\>
> \# Chain ID: 1 (or your configured chain)\
> \`\`\`\
> \
> The \`/config\` and \`/config.html\` endpoints complement this use case by providing an easy-to-use configuration interface for non-developers, allowing them to adjust settings like RPC nodes, beacon nodes, and caching without editing configuration files.<br>

````json
{"openapi":"3.1.0","info":{"title":"Colibri Stateless REST API","version":"4.1.0"},"tags":[{"name":"Verifier","description":"Endpoints for verifying proofs and executing JSON-RPC calls"}],"servers":[{"url":"http://{host}:{port}","description":"Colibri Stateless Server","variables":{"host":{"default":"127.0.0.1","description":"Server host address"},"port":{"default":"8090","description":"Server port"}}}],"paths":{"/rpc":{"post":{"tags":["Verifier"],"summary":"Verify and Execute JSON-RPC Request","description":"**Primary Use Case: Local RPC Provider Replacement**\n\nThis endpoint is designed to serve as a **complete, trustless replacement for traditional RPC providers**. When running the Colibri server locally (using the [installer packages](https://corpus-core.gitbook.io/specification-colibri-stateless/developer-guide/installer)), you can configure this endpoint as your RPC provider in wallets like MetaMask, enabling fully verified, trustless access to the blockchain without relying on third-party infrastructure.\n\n**How It Works:**\n\nThe endpoint processes JSON-RPC requests through the following flow:\n1. **Proof Generation**: Creates or fetches cryptographic proofs for the request (locally or from configured prover nodes)\n2. **Verification**: Verifies the proof against the current sync committee state\n3. **Response**: Returns the verified JSON-RPC response in standard format\n\n**Supported Methods:**\n\nThis endpoint supports **all** Ethereum JSON-RPC methods, including:\n- Methods with proofs (see [Supported RPC Methods](https://corpus-core.gitbook.io/specification-colibri-stateless/specifications/ethereum/supported-rpc-methods))\n- Local methods without proofs (`eth_chainId`, `web3_clientVersion`, etc.)\n- Filter methods (`eth_newFilter`, `eth_getFilterChanges`, etc.)\n- Subscription methods (`eth_subscribe`, `eth_unsubscribe`)\n\n**Local Setup Example:**\n\n```bash\n# Install and run locally (macOS/Linux/Windows)\n# See: https://corpus-core.gitbook.io/specification-colibri-stateless/developer-guide/installer\n\n# Configure in MetaMask:\n# Network Name: Colibri Verified Ethereum\n# RPC URL: http://localhost:8090/rpc\n# Chain ID: 1 (or your configured chain)\n```\n\nThe `/config` and `/config.html` endpoints complement this use case by providing an easy-to-use configuration interface for non-developers, allowing them to adjust settings like RPC nodes, beacon nodes, and caching without editing configuration files.\n","operationId":"verifyAndExecute","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcRequest"}}}},"responses":{"200":{"description":"Request verified and executed successfully","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/JsonRpcResponse"},{"$ref":"#/components/schemas/JsonRpcErrorResponse"}]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"schemas":{"JsonRpcRequest":{"type":"object","required":["jsonrpc","method","params","id"],"properties":{"jsonrpc":{"type":"string","enum":["2.0"],"description":"JSON-RPC version"},"method":{"type":"string","description":"RPC method name"},"params":{"type":"array","description":"Method parameters","items":{}},"id":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"null"}],"description":"Request identifier"}}},"JsonRpcResponse":{"type":"object","required":["jsonrpc","result","id"],"properties":{"jsonrpc":{"type":"string","enum":["2.0"]},"result":{"description":"Method result (type varies by method)"},"id":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"null"}]}}},"JsonRpcErrorResponse":{"type":"object","required":["jsonrpc","error","id"],"properties":{"jsonrpc":{"type":"string","enum":["2.0"]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"integer","description":"JSON-RPC error code"},"message":{"type":"string","description":"Error message"},"data":{"description":"Additional error data (optional)"}}},"id":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"null"}]}}},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Error message"}}}}}}
````

## Generate Proof

> Generates a cryptographic proof for a JSON-RPC request.\
> \
> This endpoint accepts standard JSON-RPC requests with additional optional properties:\
> \- \`c4\`: Hex-encoded state of the requested client for proof decisions\
> \- \`include\_code\`: Include bytecode in eth\_call proofs\
> \
> The response is an SSZ-encoded \`C4Request\` container defined in the \[Ethereum Main Proof Request specification]\(<https://corpus-core.gitbook.io/specification-colibri-stateless/specifications/ethereum/ethereum-main-proof-request).\\>
> \
> \*\*Supported Methods with Proofs:\*\*\
> \
> This endpoint only accepts RPC methods that have an associated ProofType. The ProofType determines the structure used in the \`C4Request.proof\` union.\
> \
> For the complete list of supported methods and their proof types, see the \[Supported RPC Methods]\(<https://corpus-core.gitbook.io/specification-colibri-stateless/specifications/ethereum/supported-rpc-methods>) documentation.\
> \
> \*\*Common Methods:\*\*\
> \- \`eth\_call\` → EthCallProof\
> \- \`eth\_getBalance\` → EthAccountProof\
> \- \`eth\_getStorageAt\` → EthAccountProof\
> \- \`eth\_getCode\` → EthAccountProof\
> \- \`eth\_getProof\` → EthAccountProof\
> \- \`eth\_getTransactionByHash\` → EthTransactionProof\
> \- \`eth\_getTransactionReceipt\` → EthReceiptProof\
> \- \`eth\_getLogs\` → List\[EthLogsBlock]\
> \- \`eth\_getBlockByNumber\` → EthBlockProof\
> \- \`eth\_getBlockByHash\` → EthBlockProof\
> \- \`eth\_blockNumber\` → EthBlockNumberProof\
> \- \`colibri\_simulateTransaction\` → EthCallProof\
> \
> \*\*Note:\*\* Methods without a ProofType (like \`eth\_chainId\`, \`web3\_clientVersion\`) are not supported by this endpoint. Use the \`/rpc\` endpoint instead, which handles all methods.<br>

```json
{"openapi":"3.1.0","info":{"title":"Colibri Stateless REST API","version":"4.1.0"},"tags":[{"name":"Prover","description":"Endpoints for generating cryptographic proofs"}],"servers":[{"url":"http://{host}:{port}","description":"Colibri Stateless Server","variables":{"host":{"default":"127.0.0.1","description":"Server host address"},"port":{"default":"8090","description":"Server port"}}}],"paths":{"/proof":{"post":{"tags":["Prover"],"summary":"Generate Proof","description":"Generates a cryptographic proof for a JSON-RPC request.\n\nThis endpoint accepts standard JSON-RPC requests with additional optional properties:\n- `c4`: Hex-encoded state of the requested client for proof decisions\n- `include_code`: Include bytecode in eth_call proofs\n\nThe response is an SSZ-encoded `C4Request` container defined in the [Ethereum Main Proof Request specification](https://corpus-core.gitbook.io/specification-colibri-stateless/specifications/ethereum/ethereum-main-proof-request).\n\n**Supported Methods with Proofs:**\n\nThis endpoint only accepts RPC methods that have an associated ProofType. The ProofType determines the structure used in the `C4Request.proof` union.\n\nFor the complete list of supported methods and their proof types, see the [Supported RPC Methods](https://corpus-core.gitbook.io/specification-colibri-stateless/specifications/ethereum/supported-rpc-methods) documentation.\n\n**Common Methods:**\n- `eth_call` → EthCallProof\n- `eth_getBalance` → EthAccountProof\n- `eth_getStorageAt` → EthAccountProof\n- `eth_getCode` → EthAccountProof\n- `eth_getProof` → EthAccountProof\n- `eth_getTransactionByHash` → EthTransactionProof\n- `eth_getTransactionReceipt` → EthReceiptProof\n- `eth_getLogs` → List[EthLogsBlock]\n- `eth_getBlockByNumber` → EthBlockProof\n- `eth_getBlockByHash` → EthBlockProof\n- `eth_blockNumber` → EthBlockNumberProof\n- `colibri_simulateTransaction` → EthCallProof\n\n**Note:** Methods without a ProofType (like `eth_chainId`, `web3_clientVersion`) are not supported by this endpoint. Use the `/rpc` endpoint instead, which handles all methods.\n","operationId":"generateProof","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProofRequest"}}}},"responses":{"200":{"description":"Proof generated successfully","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary","description":"SSZ-encoded C4Request container. See the [C4Request specification](https://corpus-core.gitbook.io/specification-colibri-stateless/specifications/ethereum/ethereum-main-proof-request) for detailed structure.\n\nThe container includes:\n- `version`: 4-byte version (domain, major, minor, patch)\n- `data`: Union of different proof data types\n- `proof`: Union of different proof types\n- `sync_data`: Optional light client updates\n"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"schemas":{"ProofRequest":{"allOf":[{"$ref":"#/components/schemas/JsonRpcRequest"},{"type":"object","properties":{"c4":{"type":"string","format":"hex","description":"Hex-encoded state of the requested client. Allows the prover to make\ndecisions about required header proofs (e.g., for historic blocks).\n"},"include_code":{"type":"boolean","description":"If true, eth_call proofs will include the required contract bytecode\nin the proof, enabling stateless verification.\n","default":false}}}]},"JsonRpcRequest":{"type":"object","required":["jsonrpc","method","params","id"],"properties":{"jsonrpc":{"type":"string","enum":["2.0"],"description":"JSON-RPC version"},"method":{"type":"string","description":"RPC method name"},"params":{"type":"array","description":"Method parameters","items":{}},"id":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"null"}],"description":"Request identifier"}}},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Error message"}}}}}}
```

## Generate Block Proof (cache-friendly GET)

> CDN-cache-friendly GET variant used by clients in \*\*hybrid mode\*\* for the delegated block\
> methods \`eth\_getBlockHeader\` and \`eth\_getBlockByNumber\`. All request parameters are encoded\
> into the path so shared caches / CDNs can serve repeated requests for the same head without\
> hitting the prover.\
> \
> The response is identical to the SSZ-encoded \`C4Request\` returned by \`POST /proof\`.\
> \
> A \`Cache-Control\` header is set based on the block identifier:\
> \- concrete block number / hash → \`public, max-age=31536000, immutable\`\
> \- \`finalized\` → one epoch\
> \- \`safe\` / \`justified\` → half an epoch\
> \- \`latest\` → half a block time (\`public, max-age=\<n>, stale-while-revalidate=\<n>\`)\
> \
> The \`includeTx\` boolean of \`eth\_getBlockByNumber\` is intentionally not part of the URL,\
> because the full execution payload is always included in the proof.<br>

```json
{"openapi":"3.1.0","info":{"title":"Colibri Stateless REST API","version":"4.1.0"},"tags":[{"name":"Prover","description":"Endpoints for generating cryptographic proofs"}],"servers":[{"url":"http://{host}:{port}","description":"Colibri Stateless Server","variables":{"host":{"default":"127.0.0.1","description":"Server host address"},"port":{"default":"8090","description":"Server port"}}}],"paths":{"/proof/{method}/{block}/{version}/{zk}/{c4}":{"get":{"tags":["Prover"],"summary":"Generate Block Proof (cache-friendly GET)","description":"CDN-cache-friendly GET variant used by clients in **hybrid mode** for the delegated block\nmethods `eth_getBlockHeader` and `eth_getBlockByNumber`. All request parameters are encoded\ninto the path so shared caches / CDNs can serve repeated requests for the same head without\nhitting the prover.\n\nThe response is identical to the SSZ-encoded `C4Request` returned by `POST /proof`.\n\nA `Cache-Control` header is set based on the block identifier:\n- concrete block number / hash → `public, max-age=31536000, immutable`\n- `finalized` → one epoch\n- `safe` / `justified` → half an epoch\n- `latest` → half a block time (`public, max-age=<n>, stale-while-revalidate=<n>`)\n\nThe `includeTx` boolean of `eth_getBlockByNumber` is intentionally not part of the URL,\nbecause the full execution payload is always included in the proof.\n","operationId":"generateBlockProofGet","parameters":[{"name":"method","in":"path","required":true,"description":"The delegated RPC method.","schema":{"type":"string","enum":["eth_getBlockHeader","eth_getBlockByNumber"]}},{"name":"block","in":"path","required":true,"description":"Block identifier (tag such as `latest`/`safe`/`finalized`, a `0x`-prefixed block number, or a `0x`-prefixed block hash).","schema":{"type":"string"}},{"name":"version","in":"path","required":true,"description":"The requesting client version number (so the prover builds a compatible proof).","schema":{"type":"integer","format":"int32"}},{"name":"zk","in":"path","required":true,"description":"Whether a ZK-based sync proof may be embedded (`zk`) or not (`std`).","schema":{"type":"string","enum":["zk","std"]}},{"name":"c4","in":"path","required":true,"description":"Hex-encoded client state snapshot (`0x` when empty). Encodes the synced periods / trusted checkpoint the client already holds.","schema":{"type":"string"}},{"name":"signers","in":"query","required":false,"description":"Optional hex-encoded witness/signer public keys.","schema":{"type":"string"}}],"responses":{"200":{"description":"Proof generated successfully","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary","description":"SSZ-encoded C4Request container (identical to `POST /proof`)."}}}},"400":{"description":"Malformed proof GET path or parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"schemas":{"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Error message"}}}}}}
```

## Get Configuration Web UI

> Serves the web-based configuration interface for managing server settings.\
> \
> \*\*Use Case: Local RPC Provider Setup\*\*\
> \
> This endpoint is specifically designed for users running Colibri locally as a trustless RPC provider (see \`/rpc\` endpoint). The Web UI provides an accessible way for non-developers to configure the server without editing configuration files directly.\
> \
> \*\*Configuration Options:\*\*\
> \- RPC node endpoints (upstream Ethereum nodes)\
> \- Beacon node endpoints (for light client sync)\
> \- Memcached settings (for proof caching)\
> \- Network settings (host, port, chain ID)\
> \- Prover settings (local vs. remote proof generation)\
> \
> \*\*Security Note:\*\* This endpoint is disabled by default for security reasons. Enable it with \`WEB\_UI\_ENABLED=1\` environment variable or the \`-u\` command-line flag. \*\*Only enable on trusted networks\*\* (typically localhost for local RPC provider setup).<br>

```json
{"openapi":"3.1.0","info":{"title":"Colibri Stateless REST API","version":"4.1.0"},"tags":[{"name":"Configuration","description":"Server configuration and management (requires WEB_UI_ENABLED)"}],"servers":[{"url":"http://{host}:{port}","description":"Colibri Stateless Server","variables":{"host":{"default":"127.0.0.1","description":"Server host address"},"port":{"default":"8090","description":"Server port"}}}],"paths":{"/config.html":{"get":{"tags":["Configuration"],"summary":"Get Configuration Web UI","description":"Serves the web-based configuration interface for managing server settings.\n\n**Use Case: Local RPC Provider Setup**\n\nThis endpoint is specifically designed for users running Colibri locally as a trustless RPC provider (see `/rpc` endpoint). The Web UI provides an accessible way for non-developers to configure the server without editing configuration files directly.\n\n**Configuration Options:**\n- RPC node endpoints (upstream Ethereum nodes)\n- Beacon node endpoints (for light client sync)\n- Memcached settings (for proof caching)\n- Network settings (host, port, chain ID)\n- Prover settings (local vs. remote proof generation)\n\n**Security Note:** This endpoint is disabled by default for security reasons. Enable it with `WEB_UI_ENABLED=1` environment variable or the `-u` command-line flag. **Only enable on trusted networks** (typically localhost for local RPC provider setup).\n","operationId":"getConfigUI","responses":{"200":{"description":"Configuration UI HTML page","content":{"text/html":{"schema":{"type":"string","description":"HTML page with interactive configuration editor"}}}},"403":{"description":"Web UI is disabled","content":{"text/html":{"schema":{"type":"string","description":"HTML error page explaining how to enable the Web UI"}}}}}}}}}
```

## Get Server Configuration

> Returns the current server configuration as JSON.\
> \
> This endpoint is used by the configuration Web UI (\`/config.html\`) to display and manage settings. It's part of the local RPC provider setup workflow, allowing programmatic access to server configuration for management tools.\
> \
> \*\*Security Note:\*\* This endpoint is disabled by default. Enable it with \`WEB\_UI\_ENABLED=1\` environment variable or the \`-u\` command-line flag. Only enable on trusted networks.<br>

```json
{"openapi":"3.1.0","info":{"title":"Colibri Stateless REST API","version":"4.1.0"},"tags":[{"name":"Configuration","description":"Server configuration and management (requires WEB_UI_ENABLED)"}],"servers":[{"url":"http://{host}:{port}","description":"Colibri Stateless Server","variables":{"host":{"default":"127.0.0.1","description":"Server host address"},"port":{"default":"8090","description":"Server port"}}}],"paths":{"/config":{"get":{"tags":["Configuration"],"summary":"Get Server Configuration","description":"Returns the current server configuration as JSON.\n\nThis endpoint is used by the configuration Web UI (`/config.html`) to display and manage settings. It's part of the local RPC provider setup workflow, allowing programmatic access to server configuration for management tools.\n\n**Security Note:** This endpoint is disabled by default. Enable it with `WEB_UI_ENABLED=1` environment variable or the `-u` command-line flag. Only enable on trusted networks.\n","operationId":"getConfig","responses":{"200":{"description":"Current server configuration","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfigResponse"}}}},"403":{"description":"Web UI is disabled","content":{"text/html":{"schema":{"type":"string"}}}}}}}},"components":{"schemas":{"ConfigResponse":{"type":"object","required":["parameters"],"properties":{"parameters":{"type":"array","items":{"$ref":"#/components/schemas/ConfigParameter"}}}},"ConfigParameter":{"type":"object","required":["name","env","description","type"],"properties":{"name":{"type":"string","description":"Parameter name"},"env":{"type":"string","description":"Environment variable name"},"description":{"type":"string","description":"Human-readable parameter description"},"type":{"type":"string","enum":["int","string","key"],"description":"Parameter type"},"value":{"description":"Current parameter value (not included for 'key' type)"},"min":{"type":"integer","description":"Minimum value (for 'int' type)"},"max":{"type":"integer","description":"Maximum value (for 'int' type)"}}}}}}
```

## Update Server Configuration

> Updates the server configuration and triggers an automatic restart.\
> \
> \*\*How It Works:\*\*\
> \
> 1\. \*\*Validation\*\*: The server validates all parameter values against their definitions (type, range, etc.)\
> 2\. \*\*Save\*\*: Valid parameters are written to the configuration file\
> 3\. \*\*Restart\*\*: The server executes \`exit(0)\`, relying on the service manager (systemd, launchd, docker-compose) to restart it with the new configuration\
> \
> \*\*Requirements:\*\*\
> \
> \- Server must be started with a config file: \`-f \<CONFIG>\` or \`--config \<CONFIG>\`\
> \- \`WEB\_UI\_ENABLED=1\` must be set (enabled by default with \[installer packages]\(<https://corpus-core.gitbook.io/specification-colibri-stateless/developer-guide/installer))\\>
> \- Service manager (systemd/launchd/docker-compose) must be configured to restart on exit\
> \
> \*\*Restrictions:\*\*\
> \
> \- \*\*Sensitive parameters\*\* (type: \`key\`) cannot be updated via this endpoint for security reasons\
> \- \*\*Integer parameters\*\* must be within their defined min/max range\
> \- Changes take effect after server restart (typically 1-2 seconds)\
> \
> \*\*Use Case:\*\*\
> \
> This endpoint is specifically designed for the local RPC provider setup, allowing non-technical users to adjust settings like RPC endpoints, beacon nodes, or caching options through the Web UI without manually editing configuration files.\
> \
> \*\*Security Note:\*\* This endpoint is disabled by default. Only enable on trusted networks (typically localhost for local installations).<br>

```json
{"openapi":"3.1.0","info":{"title":"Colibri Stateless REST API","version":"4.1.0"},"tags":[{"name":"Configuration","description":"Server configuration and management (requires WEB_UI_ENABLED)"}],"servers":[{"url":"http://{host}:{port}","description":"Colibri Stateless Server","variables":{"host":{"default":"127.0.0.1","description":"Server host address"},"port":{"default":"8090","description":"Server port"}}}],"paths":{"/config":{"post":{"tags":["Configuration"],"summary":"Update Server Configuration","description":"Updates the server configuration and triggers an automatic restart.\n\n**How It Works:**\n\n1. **Validation**: The server validates all parameter values against their definitions (type, range, etc.)\n2. **Save**: Valid parameters are written to the configuration file\n3. **Restart**: The server executes `exit(0)`, relying on the service manager (systemd, launchd, docker-compose) to restart it with the new configuration\n\n**Requirements:**\n\n- Server must be started with a config file: `-f <CONFIG>` or `--config <CONFIG>`\n- `WEB_UI_ENABLED=1` must be set (enabled by default with [installer packages](https://corpus-core.gitbook.io/specification-colibri-stateless/developer-guide/installer))\n- Service manager (systemd/launchd/docker-compose) must be configured to restart on exit\n\n**Restrictions:**\n\n- **Sensitive parameters** (type: `key`) cannot be updated via this endpoint for security reasons\n- **Integer parameters** must be within their defined min/max range\n- Changes take effect after server restart (typically 1-2 seconds)\n\n**Use Case:**\n\nThis endpoint is specifically designed for the local RPC provider setup, allowing non-technical users to adjust settings like RPC endpoints, beacon nodes, or caching options through the Web UI without manually editing configuration files.\n\n**Security Note:** This endpoint is disabled by default. Only enable on trusted networks (typically localhost for local installations).\n","operationId":"updateConfig","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfigUpdateRequest"}}}},"responses":{"200":{"description":"Configuration updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfigUpdateResponse"}}}},"400":{"description":"Validation error or invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Web UI is disabled","content":{"text/html":{"schema":{"type":"string","description":"HTML error page explaining how to enable the Web UI"}}}},"500":{"description":"Failed to save configuration","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"schemas":{"ConfigUpdateRequest":{"type":"object","required":["parameters"],"properties":{"parameters":{"type":"array","description":"Array of parameters to update","items":{"type":"object","required":["env","value"],"properties":{"env":{"type":"string","description":"Environment variable name (must match a valid parameter)"},"value":{"oneOf":[{"type":"string"},{"type":"integer"}],"description":"New value for the parameter (type depends on parameter definition)"}}}}}},"ConfigUpdateResponse":{"type":"object","required":["success","restart_required","message","updated_count"],"properties":{"success":{"type":"boolean","description":"Whether the configuration was successfully updated"},"restart_required":{"type":"boolean","description":"Whether a server restart is required (always true for successful updates)"},"message":{"type":"string","description":"Human-readable status message"},"updated_count":{"type":"integer","description":"Number of parameters that were successfully updated"}}},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Error message"}}}}}}
```

## Health Check

> Returns the server health status and operational statistics.\
> \
> Use this endpoint for monitoring and health checks in production deployments.<br>

```json
{"openapi":"3.1.0","info":{"title":"Colibri Stateless REST API","version":"4.1.0"},"tags":[{"name":"Health","description":"Health checks and monitoring"}],"servers":[{"url":"http://{host}:{port}","description":"Colibri Stateless Server","variables":{"host":{"default":"127.0.0.1","description":"Server host address"},"port":{"default":"8090","description":"Server port"}}}],"paths":{"/health":{"get":{"tags":["Health"],"summary":"Health Check","description":"Returns the server health status and operational statistics.\n\nUse this endpoint for monitoring and health checks in production deployments.\n","operationId":"healthCheck","responses":{"200":{"description":"Server is healthy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}},"500":{"description":"Server is unhealthy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"schemas":{"HealthResponse":{"type":"object","required":["status","stats"],"properties":{"status":{"type":"string","enum":["ok","error"],"description":"Overall health status"},"stats":{"type":"object","required":["total_requests","total_errors","last_sync_event","last_request_time","open_requests"],"properties":{"total_requests":{"type":"integer","description":"Total number of requests processed since server start"},"total_errors":{"type":"integer","description":"Total number of errors encountered"},"last_sync_event":{"type":"integer","description":"Timestamp of last sync committee event"},"last_request_time":{"type":"integer","description":"Unix timestamp of last request"},"open_requests":{"type":"integer","description":"Number of currently active requests"}}}}},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Error message"}}}}}}
```

## Prometheus Metrics

> Returns Prometheus-compatible metrics for monitoring server performance and operations.\
> \
> Configure your Prometheus instance to scrape this endpoint for comprehensive\
> monitoring of proof generation, verification, and RPC operations.<br>

```json
{"openapi":"3.1.0","info":{"title":"Colibri Stateless REST API","version":"4.1.0"},"tags":[{"name":"Health","description":"Health checks and monitoring"}],"servers":[{"url":"http://{host}:{port}","description":"Colibri Stateless Server","variables":{"host":{"default":"127.0.0.1","description":"Server host address"},"port":{"default":"8090","description":"Server port"}}}],"paths":{"/metrics":{"get":{"tags":["Health"],"summary":"Prometheus Metrics","description":"Returns Prometheus-compatible metrics for monitoring server performance and operations.\n\nConfigure your Prometheus instance to scrape this endpoint for comprehensive\nmonitoring of proof generation, verification, and RPC operations.\n","operationId":"getMetrics","responses":{"200":{"description":"Prometheus metrics","content":{"text/plain":{"schema":{"type":"string","description":"Prometheus text-based exposition format"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"schemas":{"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Error message"}}}}}}
```

## Get Beacon Block Header

> Retrieves the beacon block header for a given block identifier.\
> \
> This endpoint is part of the Ethereum Beacon Chain API and is used for\
> light client sync operations. Requests are proxied to configured beacon nodes.<br>

```json
{"openapi":"3.1.0","info":{"title":"Colibri Stateless REST API","version":"4.1.0"},"tags":[{"name":"Beacon","description":"Ethereum Beacon Chain light client endpoints"}],"servers":[{"url":"http://{host}:{port}","description":"Colibri Stateless Server","variables":{"host":{"default":"127.0.0.1","description":"Server host address"},"port":{"default":"8090","description":"Server port"}}}],"paths":{"/eth/v1/beacon/headers/{block_id}":{"get":{"tags":["Beacon"],"summary":"Get Beacon Block Header","description":"Retrieves the beacon block header for a given block identifier.\n\nThis endpoint is part of the Ethereum Beacon Chain API and is used for\nlight client sync operations. Requests are proxied to configured beacon nodes.\n","operationId":"getBlockHeader","parameters":[{"name":"block_id","in":"path","required":true,"schema":{"type":"string"},"description":"Block identifier. Can be one of:\n- `head` - Canonical head in node's view\n- `genesis` - Genesis block\n- `finalized` - Latest finalized block\n- `<slot>` - Specific slot number\n- `<hex_root>` - Hex-encoded block root with 0x prefix\n"}],"responses":{"200":{"description":"Block header retrieved successfully","content":{"application/json":{"schema":{"type":"object","required":["execution_optimistic","finalized","data"],"properties":{"execution_optimistic":{"type":"boolean","description":"True if the response references an unverified execution payload"},"finalized":{"type":"boolean","description":"True if the response references the finalized history"},"data":{"type":"object","required":["root","canonical","header"],"properties":{"root":{"type":"string","format":"hex","pattern":"^0x[a-fA-F0-9]{64}$"},"canonical":{"type":"boolean"},"header":{"type":"object","description":"SignedBeaconBlockHeader object"}}}}}}}},"400":{"$ref":"#/components/responses/BeaconBadRequest"},"404":{"$ref":"#/components/responses/BeaconNotFound"},"500":{"$ref":"#/components/responses/BeaconError"}}}}},"components":{"responses":{"BeaconBadRequest":{"description":"Bad request - invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BeaconErrorResponse"}}}},"BeaconNotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BeaconErrorResponse"}}}},"BeaconError":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BeaconErrorResponse"}}}}},"schemas":{"BeaconErrorResponse":{"type":"object","required":["code","message"],"properties":{"code":{"type":"integer","description":"Error code or HTTP status code"},"message":{"type":"string","description":"Error message"},"stacktraces":{"type":"array","description":"Optional stack traces (debug mode only)","items":{"type":"string"}}}}}}}
```

## Get Light Client Bootstrap

> Requests the LightClientBootstrap structure for a given post-Altair beacon block root.\
> \
> This is used to initialize light clients with the current sync committee.\
> See the \[Ethereum Consensus Specs]\(<https://github.com/ethereum/consensus-specs/blob/v1.3.0/specs/altair/light-client/sync-protocol.md#lightclientbootstrap)\\>
> for details.<br>

```json
{"openapi":"3.1.0","info":{"title":"Colibri Stateless REST API","version":"4.1.0"},"tags":[{"name":"Beacon","description":"Ethereum Beacon Chain light client endpoints"}],"servers":[{"url":"http://{host}:{port}","description":"Colibri Stateless Server","variables":{"host":{"default":"127.0.0.1","description":"Server host address"},"port":{"default":"8090","description":"Server port"}}}],"paths":{"/eth/v1/beacon/light_client/bootstrap/{block_root}":{"get":{"tags":["Beacon"],"summary":"Get Light Client Bootstrap","description":"Requests the LightClientBootstrap structure for a given post-Altair beacon block root.\n\nThis is used to initialize light clients with the current sync committee.\nSee the [Ethereum Consensus Specs](https://github.com/ethereum/consensus-specs/blob/v1.3.0/specs/altair/light-client/sync-protocol.md#lightclientbootstrap)\nfor details.\n","operationId":"getLightClientBootstrap","parameters":[{"name":"block_root","in":"path","required":true,"schema":{"type":"string","format":"hex","pattern":"^0x[a-fA-F0-9]{64}$"},"description":"Hex-encoded block root with 0x prefix"}],"responses":{"200":{"description":"Light client bootstrap data","headers":{"Eth-Consensus-Version":{"required":true,"schema":{"type":"string","enum":["phase0","altair","bellatrix","capella","deneb","electra","fulu"]},"description":"The active consensus version"}},"content":{"application/json":{"schema":{"type":"object","required":["version","data"],"properties":{"version":{"type":"string","enum":["phase0","altair","bellatrix","capella","deneb","electra","fulu"]},"data":{"type":"object","description":"LightClientBootstrap structure"}}}}}},"400":{"$ref":"#/components/responses/BeaconBadRequest"},"404":{"$ref":"#/components/responses/BeaconNotFound"},"500":{"$ref":"#/components/responses/BeaconError"}}}}},"components":{"responses":{"BeaconBadRequest":{"description":"Bad request - invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BeaconErrorResponse"}}}},"BeaconNotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BeaconErrorResponse"}}}},"BeaconError":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BeaconErrorResponse"}}}}},"schemas":{"BeaconErrorResponse":{"type":"object","required":["code","message"],"properties":{"code":{"type":"integer","description":"Error code or HTTP status code"},"message":{"type":"string","description":"Error message"},"stacktraces":{"type":"array","description":"Optional stack traces (debug mode only)","items":{"type":"string"}}}}}}}
```

## Get Light Client Updates

> Requests LightClientUpdate instances in the sync committee period range\
> \[start\_period, start\_period + count), leading up to the current head.\
> \
> Used for light client sync to track sync committee changes across periods.\
> See the \[Ethereum Consensus Specs]\(<https://github.com/ethereum/consensus-specs/blob/v1.3.0/specs/altair/light-client/sync-protocol.md#lightclientupdate)\\>
> for details.<br>

```json
{"openapi":"3.1.0","info":{"title":"Colibri Stateless REST API","version":"4.1.0"},"tags":[{"name":"Beacon","description":"Ethereum Beacon Chain light client endpoints"}],"servers":[{"url":"http://{host}:{port}","description":"Colibri Stateless Server","variables":{"host":{"default":"127.0.0.1","description":"Server host address"},"port":{"default":"8090","description":"Server port"}}}],"paths":{"/eth/v1/beacon/light_client/updates":{"get":{"tags":["Beacon"],"summary":"Get Light Client Updates","description":"Requests LightClientUpdate instances in the sync committee period range\n[start_period, start_period + count), leading up to the current head.\n\nUsed for light client sync to track sync committee changes across periods.\nSee the [Ethereum Consensus Specs](https://github.com/ethereum/consensus-specs/blob/v1.3.0/specs/altair/light-client/sync-protocol.md#lightclientupdate)\nfor details.\n","operationId":"getLightClientUpdatesByRange","parameters":[{"name":"start_period","in":"query","required":true,"schema":{"type":"string"},"description":"Starting sync committee period"},{"name":"count","in":"query","required":true,"schema":{"type":"string"},"description":"Number of periods to request"}],"responses":{"200":{"description":"Array of light client updates","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","required":["version","data"],"properties":{"version":{"type":"string","enum":["phase0","altair","bellatrix","capella","deneb","electra","fulu"]},"data":{"type":"object","description":"LightClientUpdate structure"}}}}}}},"400":{"$ref":"#/components/responses/BeaconBadRequest"},"500":{"$ref":"#/components/responses/BeaconError"}}}}},"components":{"responses":{"BeaconBadRequest":{"description":"Bad request - invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BeaconErrorResponse"}}}},"BeaconError":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BeaconErrorResponse"}}}}},"schemas":{"BeaconErrorResponse":{"type":"object","required":["code","message"],"properties":{"code":{"type":"integer","description":"Error code or HTTP status code"},"message":{"type":"string","description":"Error message"},"stacktraces":{"type":"array","description":"Optional stack traces (debug mode only)","items":{"type":"string"}}}}}}}
```

## Get OpenAPI Specification

> Returns this OpenAPI specification document in YAML format

```json
{"openapi":"3.1.0","info":{"title":"Colibri Stateless REST API","version":"4.1.0"},"tags":[{"name":"Configuration","description":"Server configuration and management (requires WEB_UI_ENABLED)"}],"servers":[{"url":"http://{host}:{port}","description":"Colibri Stateless Server","variables":{"host":{"default":"127.0.0.1","description":"Server host address"},"port":{"default":"8090","description":"Server port"}}}],"paths":{"/openapi.yaml":{"get":{"tags":["Configuration"],"summary":"Get OpenAPI Specification","description":"Returns this OpenAPI specification document in YAML format","operationId":"getOpenApiSpec","responses":{"200":{"description":"OpenAPI specification","content":{"text/yaml":{"schema":{"type":"string"}}}}}}}}}
```

### Schemas

## The ProofRequest object

```json
{"openapi":"3.1.0","info":{"title":"Colibri Stateless REST API","version":"4.1.0"},"components":{"schemas":{"ProofRequest":{"allOf":[{"$ref":"#/components/schemas/JsonRpcRequest"},{"type":"object","properties":{"c4":{"type":"string","format":"hex","description":"Hex-encoded state of the requested client. Allows the prover to make\ndecisions about required header proofs (e.g., for historic blocks).\n"},"include_code":{"type":"boolean","description":"If true, eth_call proofs will include the required contract bytecode\nin the proof, enabling stateless verification.\n","default":false}}}]},"JsonRpcRequest":{"type":"object","required":["jsonrpc","method","params","id"],"properties":{"jsonrpc":{"type":"string","enum":["2.0"],"description":"JSON-RPC version"},"method":{"type":"string","description":"RPC method name"},"params":{"type":"array","description":"Method parameters","items":{}},"id":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"null"}],"description":"Request identifier"}}}}}}
```

## The JsonRpcRequest object

```json
{"openapi":"3.1.0","info":{"title":"Colibri Stateless REST API","version":"4.1.0"},"components":{"schemas":{"JsonRpcRequest":{"type":"object","required":["jsonrpc","method","params","id"],"properties":{"jsonrpc":{"type":"string","enum":["2.0"],"description":"JSON-RPC version"},"method":{"type":"string","description":"RPC method name"},"params":{"type":"array","description":"Method parameters","items":{}},"id":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"null"}],"description":"Request identifier"}}}}}}
```

## The JsonRpcResponse object

```json
{"openapi":"3.1.0","info":{"title":"Colibri Stateless REST API","version":"4.1.0"},"components":{"schemas":{"JsonRpcResponse":{"type":"object","required":["jsonrpc","result","id"],"properties":{"jsonrpc":{"type":"string","enum":["2.0"]},"result":{"description":"Method result (type varies by method)"},"id":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"null"}]}}}}}}
```

## The JsonRpcErrorResponse object

```json
{"openapi":"3.1.0","info":{"title":"Colibri Stateless REST API","version":"4.1.0"},"components":{"schemas":{"JsonRpcErrorResponse":{"type":"object","required":["jsonrpc","error","id"],"properties":{"jsonrpc":{"type":"string","enum":["2.0"]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"integer","description":"JSON-RPC error code"},"message":{"type":"string","description":"Error message"},"data":{"description":"Additional error data (optional)"}}},"id":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"null"}]}}}}}}
```

## The ErrorResponse object

```json
{"openapi":"3.1.0","info":{"title":"Colibri Stateless REST API","version":"4.1.0"},"components":{"schemas":{"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Error message"}}}}}}
```

## The HealthResponse object

```json
{"openapi":"3.1.0","info":{"title":"Colibri Stateless REST API","version":"4.1.0"},"components":{"schemas":{"HealthResponse":{"type":"object","required":["status","stats"],"properties":{"status":{"type":"string","enum":["ok","error"],"description":"Overall health status"},"stats":{"type":"object","required":["total_requests","total_errors","last_sync_event","last_request_time","open_requests"],"properties":{"total_requests":{"type":"integer","description":"Total number of requests processed since server start"},"total_errors":{"type":"integer","description":"Total number of errors encountered"},"last_sync_event":{"type":"integer","description":"Timestamp of last sync committee event"},"last_request_time":{"type":"integer","description":"Unix timestamp of last request"},"open_requests":{"type":"integer","description":"Number of currently active requests"}}}}}}}}
```

## The ConfigResponse object

```json
{"openapi":"3.1.0","info":{"title":"Colibri Stateless REST API","version":"4.1.0"},"components":{"schemas":{"ConfigResponse":{"type":"object","required":["parameters"],"properties":{"parameters":{"type":"array","items":{"$ref":"#/components/schemas/ConfigParameter"}}}},"ConfigParameter":{"type":"object","required":["name","env","description","type"],"properties":{"name":{"type":"string","description":"Parameter name"},"env":{"type":"string","description":"Environment variable name"},"description":{"type":"string","description":"Human-readable parameter description"},"type":{"type":"string","enum":["int","string","key"],"description":"Parameter type"},"value":{"description":"Current parameter value (not included for 'key' type)"},"min":{"type":"integer","description":"Minimum value (for 'int' type)"},"max":{"type":"integer","description":"Maximum value (for 'int' type)"}}}}}}
```

## The ConfigParameter object

```json
{"openapi":"3.1.0","info":{"title":"Colibri Stateless REST API","version":"4.1.0"},"components":{"schemas":{"ConfigParameter":{"type":"object","required":["name","env","description","type"],"properties":{"name":{"type":"string","description":"Parameter name"},"env":{"type":"string","description":"Environment variable name"},"description":{"type":"string","description":"Human-readable parameter description"},"type":{"type":"string","enum":["int","string","key"],"description":"Parameter type"},"value":{"description":"Current parameter value (not included for 'key' type)"},"min":{"type":"integer","description":"Minimum value (for 'int' type)"},"max":{"type":"integer","description":"Maximum value (for 'int' type)"}}}}}}
```

## The ConfigUpdateRequest object

```json
{"openapi":"3.1.0","info":{"title":"Colibri Stateless REST API","version":"4.1.0"},"components":{"schemas":{"ConfigUpdateRequest":{"type":"object","required":["parameters"],"properties":{"parameters":{"type":"array","description":"Array of parameters to update","items":{"type":"object","required":["env","value"],"properties":{"env":{"type":"string","description":"Environment variable name (must match a valid parameter)"},"value":{"oneOf":[{"type":"string"},{"type":"integer"}],"description":"New value for the parameter (type depends on parameter definition)"}}}}}}}}}
```

## The ConfigUpdateResponse object

```json
{"openapi":"3.1.0","info":{"title":"Colibri Stateless REST API","version":"4.1.0"},"components":{"schemas":{"ConfigUpdateResponse":{"type":"object","required":["success","restart_required","message","updated_count"],"properties":{"success":{"type":"boolean","description":"Whether the configuration was successfully updated"},"restart_required":{"type":"boolean","description":"Whether a server restart is required (always true for successful updates)"},"message":{"type":"string","description":"Human-readable status message"},"updated_count":{"type":"integer","description":"Number of parameters that were successfully updated"}}}}}}
```

## The BeaconErrorResponse object

```json
{"openapi":"3.1.0","info":{"title":"Colibri Stateless REST API","version":"4.1.0"},"components":{"schemas":{"BeaconErrorResponse":{"type":"object","required":["code","message"],"properties":{"code":{"type":"integer","description":"Error code or HTTP status code"},"message":{"type":"string","description":"Error message"},"stacktraces":{"type":"array","description":"Optional stack traces (debug mode only)","items":{"type":"string"}}}}}}}
```

## Quick Start Examples

### Generate a Proof

Generate a cryptographic proof for an `eth_getBalance` request:

```bash
curl -X POST http://localhost:8090/proof \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "eth_getBalance",
    "params": ["0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb", "latest"],
    "id": 1
  }' \
  --output proof.ssz
```

The response is an SSZ-encoded `C4Request` container. For details on the proof format, see the [Ethereum Main Proof Request](https://corpus-core.gitbook.io/specification-colibri-stateless/specifications/ethereum/ethereum-main-proof-request) specification.

### Verify and Execute a Request

Execute a JSON-RPC request with automatic proof verification:

```bash
curl -X POST http://localhost:8090/rpc \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "eth_getBalance",
    "params": ["0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb", "latest"],
    "id": 1
  }'
```

Response:

```json
{
  "jsonrpc": "2.0",
  "result": "0x0000000000000000000000000000000000000000000000000de0b6b3a7640000",
  "id": 1
}
```

### Execute a Smart Contract Call with Proof

Generate a proof for an `eth_call` request with bytecode included:

```bash
curl -X POST http://localhost:8090/proof \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "eth_call",
    "params": [{
      "to": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
      "data": "0x06fdde03"
    }, "latest"],
    "id": 1,
    "include_code": true
  }' \
  --output call_proof.ssz
```

The `include_code` property ensures that the contract bytecode is included in the proof, enabling fully stateless verification.

### Update Configuration

Update server configuration programmatically (requires `WEB_UI_ENABLED=1` and a config file):

```bash
curl -X POST http://localhost:8090/config \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": [
      {"env": "PORT", "value": 8091},
      {"env": "RPC_NODES", "value": "https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY"}
    ]
  }'
```

Response:

```json
{
  "success": true,
  "restart_required": true,
  "message": "Configuration saved. Restart server to apply changes.",
  "updated_count": 2
}
```

**Note:** After a successful configuration update, the server automatically restarts (via `exit(0)`), relying on the service manager (systemd/launchd/docker-compose) to restart it with the new settings. This is automatically configured by the [installer packages](https://corpus-core.gitbook.io/specification-colibri-stateless/developer-guide/installer).

### Health Check

Check the server's operational status:

```bash
curl http://localhost:8090/health
```

Response:

```json
{
  "status": "ok",
  "stats": {
    "total_requests": 1523,
    "total_errors": 12,
    "last_sync_event": 125705,
    "last_request_time": 1698234567,
    "open_requests": 3
  }
}
```

### Prometheus Metrics

Retrieve metrics for monitoring:

```bash
curl http://localhost:8090/metrics
```

## Advanced Features

### Client State Parameter

For historic block proofs, you can provide the client's state to optimize proof generation:

```json
{
  "jsonrpc": "2.0",
  "method": "eth_getBalance",
  "params": ["0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb", "0x100000"],
  "id": 1,
  "c4": "0x1234567890abcdef..."
}
```

The `c4` parameter is a hex-encoded representation of the client's current sync committee state, allowing the prover to determine which header proofs are necessary.

### Supported JSON-RPC Methods

The following Ethereum JSON-RPC methods are supported with proof generation:

**Account & Storage:**

* `eth_getBalance`
* `eth_getCode`
* `eth_getStorageAt`
* `eth_getProof`

**Transactions:**

* `eth_getTransactionByHash`
* `eth_getTransactionReceipt`
* `eth_getTransactionCount`

**Blocks:**

* `eth_getBlockByNumber`
* `eth_getBlockByHash`
* `eth_blockNumber`

**Contract Calls:**

* `eth_call`

**Events & Logs:**

* `eth_getLogs`

**Colibri-Specific:**

* `colibri_simulateTransaction` - Simulate transaction execution with proof

For a complete list of supported methods, see the [Supported RPC Methods](https://corpus-core.gitbook.io/specification-colibri-stateless/specifications/ethereum/supported-rpc-methods) documentation.

## Beacon Chain API

The server also provides light client endpoints from the Ethereum Beacon Chain API for sync committee updates:

* `GET /eth/v1/beacon/headers/{block_id}` - Retrieve beacon block headers
* `GET /eth/v1/beacon/light_client/bootstrap/{block_root}` - Initialize light client
* `GET /eth/v1/beacon/light_client/updates` - Sync committee period updates

These endpoints are used internally by the verifier to maintain the current sync committee state and are also available for external light client implementations.

## Error Handling

### HTTP Status Codes

* **200 OK** - Request successful
* **400 Bad Request** - Invalid request format or parameters
* **403 Forbidden** - Web UI disabled (for `/config` and `/config.html`)
* **404 Not Found** - Endpoint or resource not found
* **500 Internal Server Error** - Server error during processing

### Error Response Format

Error responses use the following JSON format:

```json
{
  "error": "Error message describing what went wrong"
}
```

For JSON-RPC errors, the standard JSON-RPC error format is used:

```json
{
  "jsonrpc": "2.0",
  "error": {
    "code": -32000,
    "message": "execution reverted"
  },
  "id": 1
}
```

## Rate Limiting & Performance

The server is designed for high-performance proof generation and verification. Key performance characteristics:

* **Concurrent Requests**: Multiple requests can be processed in parallel
* **Proof Generation**: Typically 100-500ms depending on proof complexity
* **Proof Verification**: Typically 50-200ms depending on proof size
* **Light Client Sync**: Sync committee updates every \~27 hours

For production deployments, consider:

* Using memcached for caching frequently requested proofs (configure via `MEMCACHED_HOST` and `MEMCACHED_PORT`)
* Monitoring via Prometheus metrics at `/metrics`
* Load balancing across multiple RPC nodes (configure via `RPC_NODES`)

## Security Considerations

### Web UI Access

The configuration endpoints (`/config` and `/config.html`) are **disabled by default** for security reasons. Only enable them on trusted networks using:

```bash
# Environment variable
export WEB_UI_ENABLED=1

# Command line flag
./colibri-server -u
```

### Network Binding

By default, the server binds to `127.0.0.1` (localhost only). To expose the server to other machines:

```bash
export HOST=0.0.0.0
export PORT=8090
```

**Warning**: Only expose the server to untrusted networks if you have proper security measures in place (firewall, authentication proxy, etc.).

## Additional Resources

* [Full Specification Documentation](https://corpus-core.gitbook.io/specification-colibri-stateless/)
* [Ethereum Main Proof Request Format](https://corpus-core.gitbook.io/specification-colibri-stateless/specifications/ethereum/ethereum-main-proof-request)
* [Supported RPC Methods](https://corpus-core.gitbook.io/specification-colibri-stateless/specifications/ethereum/supported-rpc-methods)
* [Building & Installation Guide](https://corpus-core.gitbook.io/specification-colibri-stateless/developer-guide/building)
* [GitHub Repository](https://github.com/corpus-core/colibri-stateless)