Utility REST API¶

The utility is a Flask application that serves circuit artefacts and manages asynchronous proof jobs. It listens on port 5002 by default (overridden via the UTILITY_PORT environment variable).

All request bodies are JSON. File-download endpoints return binary application/octet-stream responses. Error responses always include "error": true and a descriptive field.

Proof jobs¶

`POST /proof-jobs`¶

Submit a new asynchronous proof generation job. The job is queued immediately and executed on a background thread pool. Returns 202 Accepted with a job ID that can be used to poll status.

Request body

Field	Type	Description
`dataset`	string	Dataset identifier (`hai` or `ornl-ps`)
`config_combination`	string	Config path (e.g. `dval_scale12/DVAL16`)
`proof_type`	string	Circuit to prove (`prediction` or `hypothesis`)
`time_instance`	integer	DVAL interval index to prove
`job_id`	string	Caller-supplied unique job identifier

Success response — 202 Accepted

{
  "job_id": "<job_id>",
  "status_url": "proof-jobs/<job_id>"
}

Error response — 404

Returned if the witness file, compiled circuit, or proving key for the requested combination does not exist on the utility's filesystem.

{
  "error": true,
  "path_exists_error": "witness_exists:False compiled_model_exists:True pk_exists:True"
}

Note

The witness file must be generated by utility-gen-witness before a proof job can be submitted. Run zkstarctl.sh utility-gen-witness first.

`GET /proof-jobs/<job_id>`¶

Poll the status of a previously submitted proof job.

Response

Field	Type	Description
`status`	string	One of `queued`, `running`, `done`, `error`
`result`	object \| null	Proof output once status is `done`; `null` otherwise
`error`	string \| null	Error description if status is `error`; `null` otherwise

{
  "status": "done",
  "result": { "error": false, "proof": { ... } },
  "error": null
}

Tip

The regulator polls this endpoint with randomised exponential backoff. Proof generation can take several minutes depending on circuit size and available hardware.

`DELETE /proof-jobs/<job_id>`¶

Cancel a queued or running job by marking it as errored. Does not preempt an already-running thread — the background proof may still complete, but the job record will reflect error: cancelled.

Success response — 200

{ "ok": true }

Already finished — 409 Conflict

{ "ok": false, "msg": "Already finished" }

Circuit artefacts¶

`POST /fetch-vk`¶

Download the verification key for a given dataset/config/proof-type combination. The VK is required by the regulator to run ezkl.verify() locally. The regulator caches the VK after the first download.

Request body

Field	Type	Description
`dataset`	string	Dataset identifier
`config_combination`	string	Config path
`proof_type`	string	`prediction` or `hypothesis`

Success response — 200

Binary file download (test.vk) with Content-Type: application/octet-stream.

Error response — 404

{ "error": true, "vk": null, "detail": "No VK available" }

`POST /fetch-cc`¶

Download the compiled circuit artefact (network.compiled). Required by the regulator for independent verification alongside the VK and settings.

Request body — same fields as /fetch-vk.

Success response — 200

Binary file download (network.compiled).

Error response — 404

{ "error": true, "cc": null, "detail": "No compiled circuit available" }

`POST /fetch-settings`¶

Download the ezkl circuit settings file (settings.json). The settings encode the quantisation and precision parameters used during circuit compilation and are required for proof verification.

Request body — same fields as /fetch-vk.

Success response — 200

Binary file download (settings.json).

Error response — 404

{ "error": true, "settings": null, "detail": "No compiled circuit available" }

Witness inspection¶

`POST /prediction-io`¶

Returns the nonced Poseidon hashes of the prediction circuit witness inputs and outputs for a given time instance. Used by the regulator in --exam-hash yes mode to audit witness contents without generating a proof.

Request body

Field	Type	Description
`dataset`	string	Dataset identifier
`config_combination`	string	Config path
`proof_type`	string	`prediction`
`time_instance`	integer	DVAL interval index

Success response — 202

{
  "error": false,
  "response": {
    "time_instance": 4,
    "dataset": "hai",
    "config": "dval_scale12/DVAL16",
    "processed_inputs": {
      "poseidon_hash": [ ... ]
    },
    "processed_outputs": {
      "poseidon_hash": [ ... ]
    }
  }
}

Input hash index mapping (processed_inputs.poseidon_hash)

Index	Committed value
0	hash(current EKF hidden state h)
1	hash(current state covariance P)
2	hash(current residual δy)
3	hash(current innovation covariance CPCT_cov)
4	hash(sensor measurement y)
5	hash(state transition Jacobian jac_fh)
6	hash(observation Jacobian jac_Ch)
7	hash(transposed Kalman gain Kt)
8	hash(Kalman check status KCR_status)

Output hash index mapping (processed_outputs.poseidon_hash)

Index	Committed value
0	hash(predicted hidden state h)
1	hash(predicted state covariance P)
2	hash(predicted residual δy)
3	hash(predicted innovation covariance CPCT_cov)
4	hash(predicted KCR_status)

Error response — 404

{ "error": true, "path_exists_error": "witness_exists:False" }

`POST /hypothesis-io`¶

Returns the nonced Poseidon hashes of the hypothesis circuit witness inputs and the rescaled circuit outputs for a given time instance.

Request body

Field	Type	Description
`dataset`	string	Dataset identifier
`config_combination`	string	Config path
`proof_type`	string	`hypothesis`
`time_instance`	integer	DVAL interval index

Success response — 202

{
  "error": false,
  "response": {
    "time_instance": 4,
    "dataset": "hai",
    "config": "dval_scale12/DVAL16",
    "processed_inputs": {
      "poseidon_hash": [ ... ]
    },
    "processed_outputs": {
      "rescaled_outputs": [ ... ]
    }
  }
}

Input hash index mapping (processed_inputs.poseidon_hash)

Index	Committed value
0	hash(DVAL-summed residual δy)
1	hash(DVAL-summed innovation covariance CPCT_cov)
2	hash(SVD left singular vectors U)
3	hash(SVD inverse square-root singular values S)
4	hash(accumulated Kalman check status KCR)

Output index mapping (processed_outputs.rescaled_outputs)

Index	Value	Description
0	`alarm_status`	`1.0` if chi-squared statistic > UCL, else `0.0`
1	`svd_check_status`	`1.0` if SVD reconstruction check passes
2	`kcr_check_status`	`1.0` if Kalman gain check passes across all DVAL steps
3	`chi_squared_statistic`	Raw test statistic (sensitive — not included in public proof)
4	`svd_diff`	Element-wise SVD reconstruction error
5	`svd_threshold`	Per-element tolerance used in the SVD check

Error response — 404

{ "error": true, "path_exists_error": "witness_exists:False" }

Utility REST API¶

Proof jobs¶

POST /proof-jobs¶

GET /proof-jobs/<job_id>¶

DELETE /proof-jobs/<job_id>¶

Circuit artefacts¶

POST /fetch-vk¶

POST /fetch-cc¶

POST /fetch-settings¶

Witness inspection¶

POST /prediction-io¶

POST /hypothesis-io¶

`POST /proof-jobs`¶

`GET /proof-jobs/<job_id>`¶

`DELETE /proof-jobs/<job_id>`¶

`POST /fetch-vk`¶

`POST /fetch-cc`¶

`POST /fetch-settings`¶

`POST /prediction-io`¶

`POST /hypothesis-io`¶