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

post

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), 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:

Proof Generation: Creates or fetches cryptographic proofs for the request (locally or from configured prover nodes)
Verification: Verifies the proof against the current sync committee state
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)
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:

# 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.

Body

jsonrpcstring · enumRequired

JSON-RPC version

Possible values:

methodstringRequired

RPC method name

Example: eth_call

idone ofRequired

Request identifier

stringOptional

numberOptional

nullOptional

Responses

200

Request verified and executed successfully

application/json

500

Internal server error

application/json

post

/rpc

POST /rpc HTTP/1.1
Host: 127.0.0.1:8090
Content-Type: application/json
Accept: */*
Content-Length: 351

{
  "jsonrpc": "2.0",
  "method": "eth_call",
  "params": [
    {
      "to": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
      "data": "0x06fdde03"
    },
    "latest",
    {
      "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb": {
        "balance": "0x1",
        "stateDiff": {
          "0x0000000000000000000000000000000000000000000000000000000000000000": "0x0000000000000000000000000000000000000000000000000000000000000001"
        }
      }
    }
  ],
  "id": 1
}

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

Generate Proof

post

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.

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 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.

Body

jsonrpcstring · enumRequired

JSON-RPC version

Possible values:

methodstringRequired

RPC method name

Example: eth_call

idone ofRequired

Request identifier

stringOptional

numberOptional

nullOptional

c4string · hexOptional

Hex-encoded state of the requested client. Allows the prover to make decisions about required header proofs (e.g., for historic blocks).

Example: 0x1234567890abcdef

include_codebooleanOptional

If true, eth_call proofs will include the required contract bytecode in the proof, enabling stateless verification.

Default: false

Responses

200

Proof generated successfully

application/octet-stream

string · binaryOptional

SSZ-encoded C4Request container. See the C4Request specification for detailed structure.

The container includes:

version: 4-byte version (domain, major, minor, patch)
data: Union of different proof data types
proof: Union of different proof types
sync_data: Optional light client updates

500

Internal server error

application/json

post

/proof

POST /proof HTTP/1.1
Host: 127.0.0.1:8090
Content-Type: application/json
Accept: */*
Content-Length: 371

{
  "jsonrpc": "2.0",
  "method": "eth_call",
  "params": [
    {
      "to": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
      "data": "0x06fdde03"
    },
    "latest",
    {
      "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb": {
        "balance": "0x1",
        "stateDiff": {
          "0x0000000000000000000000000000000000000000000000000000000000000000": "0x0000000000000000000000000000000000000000000000000000000000000001"
        }
      }
    }
  ],
  "id": 1,
  "include_code": true
}

binary

Get Configuration Web UI

get

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).

Responses

200

Configuration UI HTML page

text/html

stringOptional

HTML page with interactive configuration editor

403

Web UI is disabled

text/html

get

/config.html

GET /config.html HTTP/1.1
Host: 127.0.0.1:8090
Accept: */*

text

Get Server Configuration

get

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.

Responses

200

Current server configuration

application/json

403

Web UI is disabled

text/html

get

/config

GET /config HTTP/1.1
Host: 127.0.0.1:8090
Accept: */*

{
  "parameters": [
    {
      "name": "host",
      "env": "HOST",
      "description": "Host/IP address to bind to (127.0.0.1=localhost only, 0.0.0.0=all interfaces)",
      "type": "string",
      "value": "127.0.0.1"
    },
    {
      "name": "port",
      "env": "PORT",
      "description": "Port to listen on",
      "type": "int",
      "value": 8090,
      "min": 1,
      "max": 65535
    },
    {
      "name": "rpc_nodes",
      "env": "RPC_NODES",
      "description": "Comma-separated list of Ethereum RPC node URLs",
      "type": "string",
      "value": "https://eth-mainnet.g.alchemy.com/v2/..."
    }
  ]
}

Update Server Configuration

post

Updates the server configuration and triggers an automatic restart.

How It Works:

Validation: The server validates all parameter values against their definitions (type, range, etc.)
Save: Valid parameters are written to the configuration file
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)
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).

Body

Responses

200

Configuration updated successfully

application/json

successbooleanRequired

Whether the configuration was successfully updated

Example: true

restart_requiredbooleanRequired

Whether a server restart is required (always true for successful updates)

Example: true

messagestringRequired

Human-readable status message

Example: Configuration saved. Restart server to apply changes.

updated_countintegerRequired

Number of parameters that were successfully updated

Example: 2

400

Validation error or invalid request

application/json

403

Web UI is disabled

text/html

500

Failed to save configuration

application/json

post

/config

POST /config HTTP/1.1
Host: 127.0.0.1:8090
Content-Type: application/json
Accept: */*
Content-Length: 194

{
  "parameters": [
    {
      "env": "PORT",
      "value": 8091
    },
    {
      "env": "RPC_NODES",
      "value": "https://eth-mainnet.g.alchemy.com/v2/YOUR_API_KEY,https://rpc.ankr.com/eth"
    },
    {
      "env": "MEMCACHED_HOST",
      "value": "localhost"
    }
  ]
}

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

Health Check

get

Returns the server health status and operational statistics.

Use this endpoint for monitoring and health checks in production deployments.

Responses

200

Server is healthy

application/json

statusstring · enumRequired

Overall health status

Possible values:

500

Server is unhealthy

application/json

get

/health

GET /health HTTP/1.1
Host: 127.0.0.1:8090
Accept: */*

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

Prometheus Metrics

get

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.

Responses

200

Prometheus metrics

text/plain

stringOptional

Prometheus text-based exposition format

500

Internal server error

application/json

get

/metrics

GET /metrics HTTP/1.1
Host: 127.0.0.1:8090
Accept: */*

# HELP c4_total_requests Total number of requests processed
# TYPE c4_total_requests counter
c4_total_requests 1523
# HELP c4_total_errors Total number of errors encountered
# TYPE c4_total_errors counter
c4_total_errors 12
# HELP c4_open_requests Number of currently open requests
# TYPE c4_open_requests gauge
c4_open_requests 3

Get Beacon Block Header

get

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.

Path parameters

block_idstringRequired

Block identifier. Can be one of:

head - Canonical head in node's view
genesis - Genesis block
finalized - Latest finalized block
<slot> - Specific slot number
<hex_root> - Hex-encoded block root with 0x prefix

Example: head

Responses

200

Block header retrieved successfully

application/json

execution_optimisticbooleanRequired

True if the response references an unverified execution payload

finalizedbooleanRequired

True if the response references the finalized history

400

Bad request - invalid input

application/json

404

Resource not found

application/json

500

Internal server error

application/json

get

/eth/v1/beacon/headers/{block_id}

GET /eth/v1/beacon/headers/{block_id} HTTP/1.1
Host: 127.0.0.1:8090
Accept: */*

{
  "execution_optimistic": true,
  "finalized": true,
  "data": {
    "root": "text",
    "canonical": true,
    "header": {}
  }
}

Get Light Client Bootstrap

get

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 for details.

Path parameters

block_rootstring · hexRequired

Hex-encoded block root with 0x prefix

Example: 0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2Pattern: ^0x[a-fA-F0-9]{64}$

Responses

200

Light client bootstrap data

application/json

400

Bad request - invalid input

application/json

404

Resource not found

application/json

500

Internal server error

application/json

get

/eth/v1/beacon/light_client/bootstrap/{block_root}

GET /eth/v1/beacon/light_client/bootstrap/{block_root} HTTP/1.1
Host: 127.0.0.1:8090
Accept: */*

{
  "version": "phase0",
  "data": {}
}

Get Light Client Updates

get

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 for details.

Query parameters

start_periodstringRequired

Starting sync committee period

Example: 1

countstringRequired

Number of periods to request

Example: 1

Responses

200

Array of light client updates

application/json

versionstring · enumRequiredPossible values:

dataobjectRequired

LightClientUpdate structure

400

Bad request - invalid input

application/json

500

Internal server error

application/json

get

/eth/v1/beacon/light_client/updates

GET /eth/v1/beacon/light_client/updates?start_period=text&count=text HTTP/1.1
Host: 127.0.0.1:8090
Accept: */*

[
  {
    "version": "phase0",
    "data": {}
  }
]

Get OpenAPI Specification

get

Returns this OpenAPI specification document in YAML format

Responses

200

OpenAPI specification

text/yaml

stringOptional

get

/openapi.yaml

GET /openapi.yaml HTTP/1.1
Host: 127.0.0.1:8090
Accept: */*

200

OpenAPI specification

text

Schemas

Quick Start Examples

Generate a Proof

Generate a cryptographic proof for an eth_getBalance request:

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 specification.

Verify and Execute a Request

Execute a JSON-RPC request with automatic proof verification:

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:

{
  "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:

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):

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:

{
  "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.

Health Check

Check the server's operational status:

curl http://localhost:8090/health

Response:

{
  "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:

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:

{
  "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 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:

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

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

{
  "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:

# 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:

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

PreviousUnified RPC API NextProver Service

Last updated 5 months ago

hashtagOverview

hashtagOpenAPI Specification

hashtagLive Server Endpoint

hashtagStatic Specification

hashtagInteractive API Documentation

hashtagEndpoints

hashtagVerify and Execute JSON-RPC Request

hashtagGenerate Proof

hashtagGet Configuration Web UI

hashtagGet Server Configuration

hashtagUpdate Server Configuration

hashtagHealth Check

hashtagPrometheus Metrics

hashtagGet Beacon Block Header

hashtagGet Light Client Bootstrap

hashtagGet Light Client Updates

hashtagGet OpenAPI Specification

hashtagSchemas

hashtagQuick Start Examples

hashtagGenerate a Proof

hashtagVerify and Execute a Request

hashtagExecute a Smart Contract Call with Proof

hashtagUpdate Configuration

hashtagHealth Check

hashtagPrometheus Metrics

hashtagAdvanced Features

hashtagClient State Parameter

hashtagSupported JSON-RPC Methods

hashtagBeacon Chain API

hashtagError Handling

hashtagHTTP Status Codes

hashtagError Response Format

hashtagRate Limiting & Performance

hashtagSecurity Considerations

hashtagWeb UI Access

hashtagNetwork Binding

hashtagAdditional Resources

Overview

OpenAPI Specification

Live Server Endpoint

Static Specification

Interactive API Documentation

Endpoints

Verify and Execute JSON-RPC Request

Generate Proof

Get Configuration Web UI

Get Server Configuration

Update Server Configuration

Health Check

Prometheus Metrics

Get Beacon Block Header

Get Light Client Bootstrap

Get Light Client Updates

Get OpenAPI Specification

Schemas

Quick Start Examples

Generate a Proof

Verify and Execute a Request

Execute a Smart Contract Call with Proof

Update Configuration

Health Check

Prometheus Metrics

Advanced Features

Client State Parameter

Supported JSON-RPC Methods

Beacon Chain API

Error Handling

HTTP Status Codes

Error Response Format

Rate Limiting & Performance

Security Considerations

Web UI Access

Network Binding

Additional Resources