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

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:

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

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

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)

• use_remote_prover : If non-zero, request proof from a remote prover server instead of generating locally

Returns

A new RPC context pointer, or NULL if creation failed

c4_set_checkpoint

bindings/colibri.h

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.

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

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.

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_execute_json_status

bindings/colibri.h

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:

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

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

Frees all resources associated with an RPC context.

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)