state.h

Architecture

Asynchronous Execution Model

This module implements an asynchronous state machine for proof generation and verification. The state object (c4_state_t) is typically part of a context struct (prover_ctx_t or verify_ctx_t) and manages external data requests that cannot be fulfilled synchronously.

Execution Flow

The main execution function (e.g., c4_prover_execute) is called repeatedly in a loop until it returns either C4_SUCCESS or C4_ERROR. When external data is needed, the function:

1. Creates a data_request_t and adds it to the state

2. Returns C4_PENDING to signal that data is required

3. The host system fetches the required data

4. The host system calls the execution function again

5. The function resumes and processes the now-available data

This design allows the host system to use native async technologies (promises, async/await, futures, etc.) in the language bindings while keeping the C core synchronous and portable.

Request Lifecycle

Host System Implementation

The host system is responsible for executing data requests. When C4_PENDING is returned, the host system should iterate through all pending requests using c4_state_get_pending_request() and execute them according to the following rules:

Request Execution

For each data_request_t, the host system must:

1. Select Node: The host system maintains a list of nodes (max 16) for each data_request_type_t

   • Beacon API nodes for C4_DATA_TYPE_BEACON_API

   • Ethereum RPC nodes for C4_DATA_TYPE_ETH_RPC

   • Checkpointz servers for C4_DATA_TYPE_CHECKPOINTZ

   • etc.

2. Apply Filters:

   • Skip nodes where node_exclude_mask & (1 << node_index) is set

   • Prefer nodes matching preferred_client_type (if set, 0 = any client)

3. Build Request:

   • Use method field for HTTP method (C4_DATA_METHOD_GET, POST, etc.)

   • Use url field for the endpoint path (if set)

   • Use payload for POST body (if set, typically JSON-RPC for C4_DATA_TYPE_ETH_RPC)

   • Set Content-Type and Accept headers based on encoding:

     • C4_DATA_ENCODING_JSON: application/json

     • C4_DATA_ENCODING_SSZ: application/octet-stream

4. Execute Request:

   • Try the selected node

   • On failure: try next available node (respecting exclude mask)

   • On success: set response and response_node_index

   • If all nodes fail: set error

5. Caching:

   • If ttl is set (> 0), the response may be cached for the specified duration

   • Cache key should include request type, URL, and payload

6. Set Result:

   • Success: Allocate memory for response.data, copy data, set response.len and response_node_index

   • Failure: Allocate memory for error string describing the failure

   • Important: Both response.data and error will be freed by c4_state_free() - use malloc/strdup

Example Implementation

See bindings/emscripten/src/index.ts function handle_request() for a complete TypeScript implementation.

Best Practices

To minimize the number of execution cycles, developers should:

• Collect all required data requests as early as possible in the execution

• Use TRY_ADD_ASYNC to queue multiple requests before returning C4_PENDING

• The host system should fetch all pending requests in parallel when possible

• Cache responses according to ttl to avoid redundant network requests

• Implement smart node selection (e.g., prefer faster nodes, track reliability)

Example Usage

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:
      // Fetch all pending requests (can be done in parallel)
      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);

Macros for Async Control Flow

The TRY_ASYNC family of macros simplifies error handling and control flow:

• TRY_ASYNC(fn): Execute function, return immediately if not C4_SUCCESS

• TRY_ADD_ASYNC(status, fn): Queue multiple requests, only fail on C4_ERROR

• TRY_2_ASYNC(fn1, fn2): Execute two functions in parallel

• TRY_ASYNC_FINAL(fn, cleanup): Always run cleanup regardless of result

• TRY_ASYNC_CATCH(fn, cleanup): Run cleanup only on failure

These macros handle the repetitive pattern of checking status codes and allow the developer to focus on the business logic.

data_request_type_t

util/state.h

Defines the type of data source for a request.

typedef enum {
  C4_DATA_TYPE_BEACON_API  = 0, ///< Request is handled by the Beacon API
  C4_DATA_TYPE_ETH_RPC     = 1, ///< Request is handled by the Ethereum RPC
  C4_DATA_TYPE_REST_API    = 2, ///< Request is handled by a generic REST API
  C4_DATA_TYPE_INTERN      = 3, ///< Request is handled internally within the prover server
  C4_DATA_TYPE_PROVER      = 4, ///< Request is handled by the prover server
  C4_DATA_TYPE_CHECKPOINTZ = 5  ///< Request is handled by a checkpointz server

} data_request_type_t;

data_request_encoding_t

util/state.h

Defines the encoding format for request/response data.

typedef enum {
  C4_DATA_ENCODING_JSON = 0, ///< Data is encoded in JSON format
  C4_DATA_ENCODING_SSZ  = 1  ///< Data is encoded in SSZ (Simple Serialize) format
} data_request_encoding_t;

data_request_method_t

util/state.h

HTTP methods for data requests.

typedef enum {
  C4_DATA_METHOD_GET    = 0, ///< HTTP GET method
  C4_DATA_METHOD_POST   = 1, ///< HTTP POST method
  C4_DATA_METHOD_PUT    = 2, ///< HTTP PUT method
  C4_DATA_METHOD_DELETE = 3  ///< HTTP DELETE method
} data_request_method_t;

c4_status_t

util/state.h

Status codes for asynchronous operations.

typedef enum {
  C4_SUCCESS = 0,  ///< Operation completed successfully
  C4_ERROR   = -1, ///< Operation failed with an error
  C4_PENDING = 2   ///< Operation is pending and requires external data
} c4_status_t;

data_request_t

util/state.h

Represents a single asynchronous data request in the state machine.

This structure encapsulates all information needed to make, track, and retry external data requests. Requests can be to various data sources (Beacon API, Eth RPC, etc.) and support retry logic with node exclusion.

typedef struct data_request {
  chain_id_t              chain_id;              ///< The blockchain chain ID for this request
  data_request_type_t     type;                  ///< Type of data source (Beacon API, Eth RPC, etc.)
  data_request_encoding_t encoding;              ///< Encoding format for request/response (JSON or SSZ)
  char*                   url;                   ///< URL endpoint for the request (may be NULL for RPC)
  data_request_method_t   method;                ///< HTTP method to use (GET, POST, etc.)
  bytes_t                 payload;               ///< Request payload data (e.g., for POST requests)
  bytes_t                 response;              ///< Response data received from the request
  uint16_t                response_node_index;   ///< Index of the node that responded with the result
  uint16_t                node_exclude_mask;     ///< Bitlist marking nodes to exclude when retrying (bit 0 = index 0, max 16 nodes)
  uint32_t                preferred_client_type; ///< Preferred beacon client type bitmask (0 = any client)
  char*                   error;                 ///< Error message if request failed (NULL if no error)
  struct data_request*    next;                  ///< Pointer to next request in linked list
  bytes32_t               id;                    ///< Unique identifier for this request (32-byte hash)
  uint32_t                ttl;                   ///< Time-to-live or retry counter for this request
  bool                    validated;             ///< Whether the response has been validated
} data_request_t;

c4_state_t

util/state.h

Global state container for asynchronous operations.

Contains all pending data requests and accumulated error messages. Used by the async state machine to track operations that require external data.

typedef struct {
  data_request_t* requests; ///< Linked list of data requests (NULL if no requests)
  char*           error;    ///< Accumulated error messages (NULL if no errors)
} c4_state_t;

c4_state_free

util/state.h

Frees all resources associated with a state object.

Releases all memory allocated for data requests, URLs, payloads, responses, and error messages. Safe to call with partially initialized state objects.

void c4_state_free(c4_state_t* state);

Parameters

• state : Pointer to the state object to free

c4_state_get_data_request_by_id

util/state.h

Finds a data request by its unique identifier.

Performs a linear search through the request list to find a request with the matching 32-byte ID.

data_request_t* c4_state_get_data_request_by_id(c4_state_t* state, bytes32_t id);

Parameters

• state : Pointer to the state object

• id : 32-byte identifier to search for

Returns

Pointer to the matching request, or NULL if not found

c4_state_get_data_request_by_url

util/state.h

Finds a data request by its URL.

Performs a linear search through the request list to find a request with the matching URL string.

data_request_t* c4_state_get_data_request_by_url(c4_state_t* state, char* url);

Parameters

• state : Pointer to the state object

• url : URL string to search for

Returns

Pointer to the matching request, or NULL if not found

c4_state_is_pending

util/state.h

Checks if a request is still pending.

A request is considered pending if it has no error and no response data yet.

bool c4_state_is_pending(data_request_t* req);

Parameters

• req : Pointer to the request to check

Returns

true if pending, false if completed or failed

c4_state_add_request

util/state.h

Adds a new data request to the state.

Automatically generates a unique ID for the request if not already set (hash of payload or URL). Adds the request to the front of the linked list.

void c4_state_add_request(c4_state_t* state, data_request_t* data_request);

Parameters

• state : Pointer to the state object

• data_request : Pointer to the request to add (ownership transfers to state)

c4_state_get_pending_request

util/state.h

Gets the first pending request from the state.

Searches through the request list and returns the first request that is still pending (has no error and no response).

data_request_t* c4_state_get_pending_request(c4_state_t* state);

Parameters

• state : Pointer to the state object

Returns

Pointer to the first pending request, or NULL if none pending

c4_state_add_error

util/state.h

Adds an error message to the state.

Appends the error message to any existing error messages, separated by newlines. Handles NULL error parameter gracefully by using a generic message.

c4_status_t c4_state_add_error(c4_state_t* state, const char* error);

Parameters

• state : Pointer to the state object

• error : Error message to add (can be NULL)

Returns

Always returns C4_ERROR

c4_req_mockname

util/state.h

Generates a mock filename for a request (test mode only).

Creates a sanitized filename based on the request URL or payload, suitable for storing mock responses. Characters that are invalid in filenames are replaced with underscores.

Note: Only available when compiled with TEST flag.

char* c4_req_mockname(data_request_t* req);

Parameters

• req : Pointer to the data request

Returns

Allocated string with the mock filename (caller must free)