Skip to content

Regulator

The regulator is the verifying party in the zkSTAR compliance workflow. It has no REST endpoints of its own — it queries the utility's endpoints, verifies proofs locally, and logs compliance decisions.

The regulator logic is implemented in regulator.py and is invoked via zkstarctl.sh regulator inside the Docker workflow, or directly for development:

python regulator.py --dataset hai --config dval_scale12/DVAL16 \
                    --proof-type prediction --tinst 4

Workflow

  1. Submit proof job — POST to /proof-jobs on the utility to trigger witness generation and proving for the requested dataset/config/proof-type.

  2. Poll with backoff — GET /proof-jobs/<job_id> until status is completed. The regulator retries with randomized exponential backoff to tolerate the long proving times.

  3. Fetch and cache VK + settings — downloads the verification key (/fetch-vk) and circuit settings (/fetch-settings) from the utility once per dataset/config/proof-type combination and caches them locally.

  4. Verify proof — calls ezkl.verify(proof, vk, settings) locally. No interaction with the utility is needed for this step.

  5. Request stats snapshot — queries the stats-logger for a resource utilisation snapshot covering the duration of the proof job.

--exam-hash mode

When --exam-hash yes is passed, the regulator skips proof generation entirely and instead queries /prediction-io or /hypothesis-io to print the nonced Poseidon hashes of circuit inputs and outputs for each requested time instance. This is useful for auditing witness contents without incurring proving overhead.

Multiple time instances may be specified with --tinst in this mode:

python regulator.py --dataset hai --config dval_scale12/DVAL16 \
                    --proof-type prediction --tinst 1,2,3,4 --exam-hash yes

Utility endpoints consumed

Endpoint Method Purpose
/proof-jobs POST Submit a new proof job
/proof-jobs/<job_id> GET Poll job status
/proof-jobs/<job_id> DELETE Cancel a job
/fetch-vk POST Download verification key
/fetch-cc POST Download compiled circuit artefact
/fetch-settings POST Download circuit settings
/prediction-io POST Fetch prediction witness hashes
/hypothesis-io POST Fetch hypothesis witness hashes