zkstarctl — CLI Orchestration¶

zkstarctl.sh is the main entry point for running the full zkSTAR pipeline via Docker Compose. It wraps docker compose with sensible defaults and exposes a consistent interface across all pipeline stages.

Prerequisites¶

Docker ≥ 24 with Compose v2.
A Docker Hub account — docker login before the first run to avoid pull rate limits.
The repository cloned locally with your dataset placed in data/.

Subcommands¶

bash zkstarctl.sh <subcommand> [options]

Subcommand	Mode	Description
`clean`	—	Stop and remove zkSTAR containers (all or a specific service)
`utility-setup`	one-shot	Compile both circuits and run the trusted setup
`utility-gen-witness`	one-shot	Run the EKF forward pass and generate all circuit witnesses
`utility-prover`	detached	Start the utility REST API server (prover + endpoints)
`utility-stats-logger`	detached	Start the Docker resource stats logger
`regulator`	one-shot	Submit a proof job, poll, verify, and log compliance decisions

The required order for a fresh run is: utility-setup → utility-gen-witness → utility-prover → regulator

Common options¶

These options apply to utility-setup, utility-gen-witness, utility-prover, and regulator and must be passed consistently across all steps:

Option	Values	Default	Description
`--dataset`	`hai`, `ornl-ps`	`hai`	Dataset to use
`--config`	`<scale_family>/<DVAL>`	`dval_scale12/DVAL16`	Circuit config path under `configs_container_qs/`
`--utility-ip`	IP address	`localhost`	IP of the utility prover
`--utility-port`	port	`6002`	Port of the utility prover
`--utility-stats-logger-port`	port	`6003`	Port of the stats logger

Clean options¶

Option	Values	Default	Description
`--service`	`all`, `utility-setup`, `utility-gen-witness`, `utility-prover`, `utility-stats-logger`, `regulator`	`all`	Which container to remove

bash zkstarctl.sh clean                          # remove all containers
bash zkstarctl.sh clean --service utility-prover # remove only the prover

Utility-setup options¶

utility-setup compiles both circuits and runs the ezkl trusted setup. Two tolerance parameters control the integrity checks that are baked into the circuits at compile time:

Option	Default	Description
`--max-svd-tol`	`0.1`	Absolute tolerance for `SVDReconstructionCheck` inside the hypothesis circuit
`--max-kcr-tol`	`0.1`	Absolute tolerance for `KalmanReconstructionCheck` inside the prediction circuit

After setup completes, a zero-byte marker file recording these tolerance values is written to PRELOADED_PROOF_ROOT (results/proofs/<dataset>/<config>/), e.g.:

results/proofs/P1_all/dval_scale12/DVAL8/tol.svd=0.11.kcr=0.11

This provides a permanent, inspectable record of the circuit parameters for a given setup run. An ls of the proof root is sufficient to determine the tolerances used to build the circuits.

Regulator options¶

Option	Values	Default	Description
`--proof-type`	`prediction`, `hypothesis`	`prediction`	Which circuit to run
`--time-instance`	`<int[,int,...]>`	`4`	DVAL interval index. Multiple values only allowed when `--exam-hash yes`.
`--exam-hash`	`yes`, `no`	`no`	Print nonced Poseidon hashes of circuit I/O instead of proving
`--verify-proof`	`yes`, `no`	`yes`	Run `ezkl.verify()` after proof generation. Only active when `--exam-hash no`.

Quickstart (default settings)¶

# 1. Clean up any prior state
bash zkstarctl.sh clean

# 2. Start the stats logger in the background
bash zkstarctl.sh utility-stats-logger --utility-stats-logger-port 6003

# 3. Compile circuits and run trusted setup
bash zkstarctl.sh utility-setup --dataset hai --config dval_scale12/DVAL16

# 4. Generate witnesses — wait for this to finish
bash zkstarctl.sh utility-gen-witness --dataset hai --config dval_scale12/DVAL16

# 5. Start the prover, then run the regulator
bash zkstarctl.sh utility-prover --dataset hai --config dval_scale12/DVAL16
bash zkstarctl.sh regulator --dataset hai --config dval_scale12/DVAL16 \
    --proof-type prediction --time-instance 4 --verify-proof yes

Custom dataset and config¶

Pass --dataset and --config consistently to all steps:

bash zkstarctl.sh clean
bash zkstarctl.sh utility-stats-logger --utility-stats-logger-port 6003
bash zkstarctl.sh utility-setup      --dataset ornl-ps --config dval_scale12/DVAL16
bash zkstarctl.sh utility-gen-witness --dataset ornl-ps --config dval_scale12/DVAL16
bash zkstarctl.sh utility-prover      --dataset ornl-ps --config dval_scale12/DVAL16
bash zkstarctl.sh regulator           --dataset ornl-ps --config dval_scale12/DVAL16

Hypothesis test circuit¶

Use --proof-type hypothesis with a DVAL ≥ 16 config:

bash zkstarctl.sh clean
bash zkstarctl.sh utility-stats-logger --utility-stats-logger-port 6003
bash zkstarctl.sh utility-setup       --dataset hai --config scale_DVAL16/scale12
bash zkstarctl.sh utility-gen-witness --dataset hai --config scale_DVAL16/scale12
bash zkstarctl.sh utility-prover      --dataset hai --config scale_DVAL16/scale12
bash zkstarctl.sh regulator           --dataset hai --config scale_DVAL16/scale12 \
                                      --proof-type hypothesis

Inspecting witness hashes¶

Print the nonced Poseidon hashes of circuit inputs and outputs without generating a full proof. Multiple time instances are allowed in this mode:

bash zkstarctl.sh clean
bash zkstarctl.sh utility-stats-logger --utility-stats-logger-port 6003
bash zkstarctl.sh utility-setup       --dataset hai --config dval_scale12/DVAL16
bash zkstarctl.sh utility-gen-witness --dataset hai --config dval_scale12/DVAL16
bash zkstarctl.sh utility-prover      --dataset hai --config dval_scale12/DVAL16

# Single instance
bash zkstarctl.sh regulator --dataset hai --config dval_scale12/DVAL16 \
    --proof-type prediction --time-instance 4 --exam-hash yes

# Multiple instances
bash zkstarctl.sh regulator --dataset hai --config dval_scale12/DVAL16 \
    --proof-type prediction --time-instance 1,2,3,4 --exam-hash yes

Warning

Proof generation (--exam-hash no) is resource-intensive and is restricted to a single --time-instance. Passing multiple instances without --exam-hash yes will result in an error.