> 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/unified-rpc-api.md).

# Unified RPC API

The unified RPC API combines method type detection, proof generation (local or remote), and verification into a single context. This eliminates the need for bindings to implement the orchestration logic (method type check, prover/verifier decision, proof flow).

The host system only needs to:

1. Create an RPC context with `c4_create_rpc_ctx()`
2. Call `c4_rpc_execute_json_status()` in a loop
3. Handle pending data requests (same as with prover/verifier APIs)
4. Free the context with `c4_free_rpc_ctx()`

The existing `c4_create_prover_ctx()` and `c4_verify_create_ctx()` APIs remain available for use cases that need separate proof generation and verification (e.g. proof transport via Bluetooth to embedded devices).

## c4\_create\_rpc\_ctx

[bindings/colibri.h](https://github.com/corpus-core/colibri-stateless/blob/v2.0.4/src/../bindings/colibri.h#L1276)

Creates a unified RPC context that handles method type detection, proof generation, and verification.

This is a convenience API that wraps the separate prover and verifier APIs. It automatically determines whether a method is proofable, local, or unproofable, and drives the appropriate flow internally.

```
                `64` = `VERIFY_FLAG_OBLIVIOUS`, `128` = `VERIFY_FLAG_SKIP_WSP_CHECK`
                (SECURITY: disables the Weak Subjectivity Period anchor; only safe with an
                alternative trust anchor such as witness signatures or a hard-coded checkpoint).
```

**Example**:

```c
void* ctx = c4_create_rpc_ctx(
    "eth_getBalance",
    "[\"0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045\", \"latest\"]",
    1,    // Ethereum Mainnet
    0,    // No special prover flags
    0,    // No special verify flags
    2     // Use hybrid prover mode
);
```

```c
void* c4_create_rpc_ctx(char* method, char* params, uint64_t chain_id, uint32_t prover_flags, uint32_t verify_flags, int prover_mode);
```

**Parameters**

* **`method`** : The Ethereum RPC method (e.g., "eth\_getBalance")
* **`params`** : The method parameters as a JSON array string
* **`chain_id`** : The blockchain chain ID
* **`prover_flags`** : Flags for proof generation (see prover flag types)
* **`verify_flags`** : Flags for verification bitmask. Common values: `2` = `VERIFY_FLAG_PAP`,
* **`prover_mode`** : proof generation mode: 0 = local, 1 = remote, 2 = hybrid (header proof from server, execution data from RPC provider)

**Returns**

A new RPC context pointer, or NULL if creation failed

## c4\_set\_checkpoint

[bindings/colibri.h](https://github.com/corpus-core/colibri-stateless/blob/v2.0.4/src/../bindings/colibri.h#L1288)

Sets a trusted checkpoint for a chain (context-independent).

Parses a hex checkpoint string and stores it globally for the given chain. Call this once before any verification if the host has a known checkpoint. The checkpoint persists across all prover/verifier/RPC contexts for the chain.

```c
void c4_set_checkpoint(uint64_t chain_id, const char* trusted_checkpoint);
```

**Parameters**

* **`chain_id`** : target chain ID
* **`trusted_checkpoint`** : hex string with "0x" prefix (66 chars total), or NULL (no-op)

## c4\_rpc\_set\_witness\_keys

[bindings/colibri.h](https://github.com/corpus-core/colibri-stateless/blob/v2.0.4/src/../bindings/colibri.h#L1299)

Sets witness/signer keys on an RPC context (hex-encoded).

Used for sync committee weak subjectivity signing during proof generation (sent to remote prover as `"signers"`) and verification.

```c
void c4_rpc_set_witness_keys(void* ctx, const char* witness_keys);
```

**Parameters**

* **`ctx`** : The RPC context created by `c4_create_rpc_ctx()`
* **`witness_keys`** : hex string with "0x" prefix (e.g. "0xabcd..."), or NULL to clear

## c4\_rpc\_set\_proxy\_urls

[bindings/colibri.h](https://github.com/corpus-core/colibri-stateless/blob/v2.0.4/src/../bindings/colibri.h#L1312)

Sets comma-separated RPC and Beacon API URLs for proxy mode.

When the prover mode is `C4_PROVER_MODE_PROXY` (3), the client supplies its own RPC and Beacon API endpoints. Call this after `c4_create_rpc_ctx()` and before the first `c4_rpc_execute_json_status()`.

```c
void c4_rpc_set_proxy_urls(void* ctx, const char* rpc_urls, const char* beacon_urls);
```

**Parameters**

* **`ctx`** : The RPC context created by `c4_create_rpc_ctx()`
* **`rpc_urls`** : comma-separated HTTPS RPC endpoint URLs, or NULL
* **`beacon_urls`** : comma-separated Beacon API base URLs, or NULL

## c4\_rpc\_set\_min\_latest\_block\_ts

[bindings/colibri.h](https://github.com/corpus-core/colibri-stateless/blob/v2.0.4/src/../bindings/colibri.h#L1327)

Sets the lower bound for `block.timestamp` on `"latest"` requests.

The verifier rejects proofs whose block timestamp is older than `ts` for `eth_call`, `eth_estimateGas`, and `colibri_simulateTransaction` when the request uses the `"latest"` block tag. Pass `0` to disable the check. The host typically computes `ts = now - max_age_seconds` from the platform wallclock; the C library never reads the wallclock itself so the check works the same way on native, WASM, and embedded targets.

```c
void c4_rpc_set_min_latest_block_ts(void* ctx, uint64_t ts);
```

**Parameters**

* **`ctx`** : The RPC context created by `c4_create_rpc_ctx()`
* **`ts`** : Lower bound as Unix timestamp in seconds (`0` disables the check)

## c4\_rpc\_execute\_json\_status

[bindings/colibri.h](https://github.com/corpus-core/colibri-stateless/blob/v2.0.4/src/../bindings/colibri.h#L1374)

Executes one step of the unified RPC state machine.

This function drives the full RPC lifecycle: method type detection, proof generation (or remote proof fetching), and verification. Call it repeatedly until it returns `"success"` or `"error"`.

The returned JSON format is identical to `c4_verify_execute_json_status()`:

* `"success"` with a `"result"` field containing the verified RPC result
* `"error"` with an `"error"` field
* `"pending"` with a `"requests"` array of data requests to fulfill

For `"pending"` responses, the `"requests"` array may contain requests of type `"prover"` (when using a remote prover) or `"eth_rpc"` (for unproofable methods), in addition to the usual `"beacon_api"` and `"eth_rpc"` requests from the prover/verifier.

**Memory Management**: The returned JSON string must be freed by the caller using `free()`.

**Example**:

```c
void* ctx = c4_create_rpc_ctx("eth_getBalance", "[\"0xabc...\", \"latest\"]", 1, 0, 0, 0);

while (1) {
    char* status_json = c4_rpc_execute_json_status(ctx);
    json_t status = parse_json(status_json);
    free(status_json);

    if (strcmp(status.status, "success") == 0) {
        printf("Result: %s\n", json_stringify(status.result));
        break;
    } else if (strcmp(status.status, "error") == 0) {
        fprintf(stderr, "Error: %s\n", status.error);
        break;
    } else if (strcmp(status.status, "pending") == 0) {
        for (int i = 0; i < status.requests_count; i++)
            handle_request(&status.requests[i]);
    }
}

c4_free_rpc_ctx(ctx);
```

```c
char* c4_rpc_execute_json_status(void* ctx);
```

**Parameters**

* **`ctx`** : The RPC context created by `c4_create_rpc_ctx()`

**Returns**

A JSON string describing the current status

## c4\_free\_rpc\_ctx

[bindings/colibri.h](https://github.com/corpus-core/colibri-stateless/blob/v2.0.4/src/../bindings/colibri.h#L1381)

Frees all resources associated with an RPC context.

```c
void c4_free_rpc_ctx(void* ctx);
```

**Parameters**

* **`ctx`** : The RPC context to free (may be NULL, in which case this is a no-op)