# 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/v1.1.26/src/../bindings/colibri.h#L1252)

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.

**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 (e.g., 2 for `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/v1.1.26/src/../bindings/colibri.h#L1264)

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/v1.1.26/src/../bindings/colibri.h#L1275)

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/v1.1.26/src/../bindings/colibri.h#L1288)

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\_execute\_json\_status

[bindings/colibri.h](https://github.com/corpus-core/colibri-stateless/blob/v1.1.26/src/../bindings/colibri.h#L1335)

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/v1.1.26/src/../bindings/colibri.h#L1342)

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)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://corpus-core.gitbook.io/specification-colibri-stateless/developer-guide/apis/unified-rpc-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.