proofman-setup

CLI for the PIL2 STARK proving-key setup pipeline. Compiles a .pilout into the artifacts the prover needs at runtime: stark info, expressions, verifier code, const trees, recursive aggregation circuits, and witness libraries.

proofman-setup <subcommand> [options]

Subcommands at a glance

setup

Run the full per-AIR setup, and (with --recursive) the compressor / recursive1 / recursive2 / vadcop_final / vadcop_final_compressed pipeline.

proofman-setup setup \
    --airout pil/zisk.pilout \
    --build-dir build \
    [--fixed-dir <dir>] \
    [--stark-structs starkstructs.json] \
    [--recursive] \
    [--recursive-jobs N] [--setup-jobs N] \
    [--output stats.txt]

Without --recursive, only the per-AIR artifacts are produced (<airgroup>/airs/<air>/air/<air>.{starkinfo,verifierinfo,expressionsinfo,verkey}.json, plus .const, .consttree, .bin, .verifier.bin, .verifier.rs).

With --recursive, the recursive layers are added under <airgroup>/airs/<air>/{compressor,recursive1}/, <airgroup>/recursive2/, vadcop_final/, and vadcop_final_compressed/ — each with its own const tree, witness .so/.dylib, and verifier artifacts.

stats

Print per-AIR statistics: constraints, intermediate polynomials per stage, column counts, etc. Useful for sizing the build before running it.

proofman-setup stats \
    --airout pil/zisk.pilout \
    [--output stats.txt] \
    [--starkstructs starkstructs.json] \
    [--airgroups Group1 Group2 ...] \
    [--airs Air1 Air2 ...] \
    [--impols]

Read-only — does not write to provingKey/.

setup-snark

Continues from a provingKey/ produced by setup --recursive, generating the final SNARK layer (recursivef + fflonk or plonk final).

proofman-setup setup-snark \
    --build-dir build \
    [--powers-of-tau ptau.ptau] \
    [--final-snark fflonk] \
    [--publics-info publics.json] \
    [--only-recursive-final]

Requires vadcop_final/vadcop_final.{starkinfo,verifierinfo,verkey}.json to already exist.

setup-recursive-test

Run a single recursive setup over a user-provided .circom file. Used by CI to exercise compressor / aggregation / final-vadcop / light templates without booting the full pipeline.

proofman-setup setup-recursive-test \
    --build-dir build \
    --circom path/to/test.circom \
    --name test \
    [--type aggregation]

rebuild-witness-libs

Rebuild only the witness libraries (.so / .dylib) inside a provingKey/ directory, without re-running the expensive setup steps (pil_info, plonk2pil, const-tree, etc.).

proofman-setup rebuild-witness-libs --proving-key build/provingKey

The command takes the provingKey/ path directly — no other folders need to exist alongside it. Useful when you've downloaded or copied just the proving key and want fresh witness libraries (e.g. macOS .dylibs on top of a Linux-built proving key).

What it does

For every circuit in provingKey/<global_name>/... that already has a witness library (compressor, recursive1, recursive2, vadcop_final, vadcop_final_compressed):

1. Loads the persisted *.starkinfo.json / *.verifierinfo.json / *.verkey.json from the proving key.
2. Regenerates the verifier circom via pil2circom and the wrapper circom via gen_circom.
3. Runs circom <name>.circom --c -O2 --prime goldilocks to emit C++.
4. Compiles the C++ into a shared library via the same make witness recipe the original setup uses.

No .dat, .const, .consttree, .exec, .bin, .verifier.rs files are touched.

Progress logging

The command prints a discovery summary, then [i/N] progress lines for each circuit. Sample output for fibonacci-square (with --jobs 1):

Discovered 6 witness library(ies) to rebuild:
  [1/6] compressor / FiboCPU.FibonacciSquare
  [2/6] recursive1 / FiboCPU.FibonacciSquare (with compressor)
  [3/6] recursive1 / FiboCPU.Module
  [4/6] recursive1 / FiboCPU.SpecifiedRanges
  [5/6] recursive2 / FiboCPU
  [6/6] vadcop_final
Running circom compiles with 1 job(s) in parallel
[1/6] compressor / FiboCPU.FibonacciSquare: loading starkinfo / verifierinfo / verkey
[1/6] compressor / FiboCPU.FibonacciSquare: generating circom sources (pil2circom + gen_circom)
[1/6] compressor / FiboCPU.FibonacciSquare: invoking circom (this is the slow step)
[1/6] compressor / FiboCPU.FibonacciSquare: circom done in 28.4s
[1/6] compressor / FiboCPU.FibonacciSquare: spawning witness library build (.so/.dylib)
...
All circom compiles complete; 6 witness library build(s) running in background

With --jobs > 1, lines from different circuits will be interleaved — the [i/N] prefix lets you trace which one each log belongs to.

Output extension is host-OS controlled

Output goes into the same per-circuit provingKey/build/... directories as the existing libraries. Running this on a Mac against a Linux-built proving key deposits a .dylib next to the existing .so (the prior .so is left alone). Running it on Linux when a .so is already present overwrites that .so.

When to use it

• You want macOS-compatible witness libs from a proving key originally built on Linux — run this on a Mac (or in a macos-latest CI runner) against the proving key, and you get .dylibs in place.
• You're iterating on circom templates and want to rebuild .sos without rerunning the full setup.

Environment variables

These override the auto-detected tooling paths used by setup, setup-snark, setup-recursive-test, and rebuild-witness-libs. All have sensible defaults that resolve relative to the repo or the executable's parent directories.

Path resolution checks (in order): the env var, the path relative to CWD, then walks up from the executable's directory looking for the same suffix. Set the env var explicitly when running outside the repo.

Typical end-to-end flow

# 1. Per-AIR + recursive setup
proofman-setup setup \
    -a pil/zisk.pilout -b build \
    -s starkstructs.json -r --recursive-jobs 4 --setup-jobs 4

# 2. Final SNARK on top
proofman-setup setup-snark -b build --powers-of-tau ptau/pot24.ptau

# 3. (Cross-platform) regenerate witness libs for the other OS
#    Run this on a Mac to get .dylibs into the same provingKey:
proofman-setup rebuild-witness-libs -p build/provingKey