prover.h

The prover API is used to create proofs for a given method and parameters.

Example:

prover_ctx_t* ctx = c4_prover_create("eth_getBlockByNumber", "[\"latest\", false]", chain_id, C4_PROVER_FLAG_INCLUDE_CODE);

// Execute prover in a loop:
data_request_t* data_request = NULL;
bytes_t proof = {0};
while (true) {
  switch (c4_prover_execute(ctx)) {
    case C4_SUCCESS:
      proof = bytes_dup(ctx->proof);
      break;
    case C4_PENDING:
      while ((data_request = c4_state_get_pending_request(&ctx->state)))
         fetch_data(data_request);
      break;
    case C4_ERROR:
      printf("Error: %s\n", ctx->state.error);
      break;
  }
}
c4_prover_free(ctx);

prover_flag_types_t

prover/prover.h

a bitmask holding flags used during the prover context.

typedef enum {
  C4_PROVER_FLAG_INCLUDE_CODE       = 1 << 0, // includes the code of the contracts when creating the proof for eth_call, otherwise the verifier will need to fetch and cache the code as needed
  C4_PROVER_FLAG_UV_SERVER_CTX      = 1 << 1, // the proofser is running in a UV-server and if the we expect cpu-intensice operations, we should return pending after setting the C4_PROVER_FLAG_UV_WORKER_REQUIRED flag.
  C4_PROVER_FLAG_UV_WORKER_REQUIRED = 1 << 2, // requests the proof execution to run in a worker thread instead of the main eventloop.
  C4_PROVER_FLAG_CHAIN_STORE        = 1 << 3, // allows the prover to use internal request with data from the chain stroe
  C4_PROVER_FLAG_UNSTABLE_LATEST    = 1 << 4, // usually we use latest-1, but if this is set we return the real "latest"
  C4_PROVER_FLAG_INCLUDE_SYNC       = 1 << 5, // if true, the sync data will be included in the proof (requires the client_state to be set)
  C4_PROVER_FLAG_USE_ACCESSLIST     = 1 << 6, // if true, eth_call will use eth_createAccessList instead of eth_debug_traceCall
  C4_PROVER_FLAG_ZK_PROOF           = 1 << 7, // if true, the the prover will try to store the zk_proof within the sync_section
} prover_flag_types_t;

prover_flags_t

prover/prover.h

a bitmask holding flags used during the prover context.

typedef uint32_t prover_flags_t;

prover_trace_span_t

prover/prover.h

a struct holding the prover context.

#ifdef PROVER_TRACE
// Forward declaration for pointer fields
typedef struct prover_trace_span prover_trace_span_t;

c4_prover_create

prover/prover.h

create a new prover context Always returns a valid context - check ctx->state.error for validation errors.

prover_ctx_t* c4_prover_create(char* method, char* params, chain_id_t chain_id, prover_flags_t flags) M_RET;

Parameters

• method : the rpc-method to proof (required, cannot be NULL)

• params : the rpc-params to proof (optional, defaults to "[]" if NULL)

• chain_id : the target chain

• flags : the prover flags

Returns

the prover context, which needs to get freed with c4_prover_free.

c4_prover_free

prover/prover.h

cleanup for the ctx

void c4_prover_free(prover_ctx_t* ctx) M_TAKE(1);

Parameters

• ctx : the prover context

c4_prover_execute

prover/prover.h

tries to create the proof, but if there are pending requests, they need to fetched before calling it again. This function should be called until it returns C4_SUCCESS or C4_ERROR.

c4_status_t c4_prover_execute(prover_ctx_t* ctx);

Parameters

• ctx : the prover context

Returns

the status of the prover

c4_prover_status

prover/prover.h

returns the status of the prover

c4_status_t c4_prover_status(prover_ctx_t* ctx);

Parameters

• ctx : the prover context

Returns

the status of the prover

c4_prover_cache_get

prover/prover.h

Retrieve a cached value by key. First checks local cache, then global cache. If found in global cache, copies entry to local cache for thread-safety. Caller MUST NOT modify the returned data. Pointer is valid until cache cleanup or context destruction.

const void* c4_prover_cache_get(prover_ctx_t* ctx, bytes32_t key);

Parameters

• ctx : the prover context

• key : 32-byte cache key

Returns

read-only pointer to cached value, or NULL if not found.

c4_prover_cache_get_local

prover/prover.h

Retrieve a cached value by key, but only from the local cahe. Caller MUST NOT modify the returned data. Pointer is valid until cache cleanup or context destruction.

const void* c4_prover_cache_get_local(prover_ctx_t* ctx, bytes32_t key);

Parameters

• ctx : the prover context

• key : 32-byte cache key

Returns

read-only pointer to cached value, or NULL if not found.

c4_prover_cache_set

prover/prover.h

Store a value in the local cache. Will be moved to global cache on context destruction if duration_ms > 0.

void c4_prover_cache_set(prover_ctx_t* ctx, bytes32_t key, void* value, uint32_t size, uint64_t duration_ms, cache_free_cb free) M_TAKE(3);

Parameters

• ctx : the prover context

• key : 32-byte cache key

• value : pointer to the value to cache (ownership transferred)

• size : size of the cached value in bytes

• duration_ms : cache TTL in milliseconds (0 = local-only, never moved to global)

• free : function to free the value when cache entry is removed

c4_prover_cache_cleanup

prover/prover.h

Clean up expired entries from global cache and enforce size limits. Removes entries that are expired OR would exceed size limit (unless in use).

void c4_prover_cache_cleanup(uint64_t now, uint64_t extra_size);

Parameters

• now : current timestamp in milliseconds

• extra_size : additional size to reserve (for new entries)

c4_prover_cache_invalidate

prover/prover.h

Invalidate a cache entry by key (marks as expired).

void c4_prover_cache_invalidate(bytes32_t key);

Parameters

• key : 32-byte cache key to invalidate

c4_prover_cache_stats

prover/prover.h

Get statistics about the global cache.

void c4_prover_cache_stats(uint64_t* entries, uint64_t* size, uint64_t* max_size, uint64_t* capacity);

Parameters

• entries : number of entries in global cache

• size : current total size of cached data in bytes

• max_size : maximum allowed cache size in bytes

• capacity : current allocated capacity of the cache array

REQUEST_WORKER_THREAD

prover/prover.h

Simplified version of REQUEST_WORKER_THREAD_CATCH without cleanup code.

#define REQUEST_WORKER_THREAD(ctx) REQUEST_WORKER_THREAD_CATCH(ctx, );

Parameters

• ctx : the prover context