Skip to main content

Prove

Generates a cryptographic proof from a guest execution, emitting an aggregated STARK proof by default. Covers the input, proving-key, output, backend, and performance flags, including the pilfflonk final SNARK for on-chain verification.

Generate a cryptographic proof from the execution of the guest program. prove re-executes the guest, generates arithmetic constraints over the resulting trace, and writes the proof file to disk. STARK proofs are emitted by default.

cargo-zisk prove [OPTIONS]

Inputs​

Identify the program to prove and the data fed to it.

FlagShortDefaultDescription
--elf <ELF>-eauto-detectedPath to the program ELF. If omitted, the ELF is auto-detected from the current project.
--inputs <INPUTS>-iemptyInput fed to the guest. A bare value is a file path; file://path also works. Inline data is inline://[[1,2],[3]], a JSON array of u64 arrays with one frame per inner array.
--hints <HINTS>Precompiles hints URI for the guest. Requires the ASM backend (--asm).
--random-seed <HEX>fresh seedUse this random seed (up to 64 hex characters, zero-padded on the left) instead of drawing a fresh one. Also read from ZISK_RANDOM_SEED. See Host randomness.
note

If no program setup files are found at the resolved location, prove invokes setup automatically before generating the proof, so you can go straight from build to prove without an explicit setup step.

Binary and profile selection​

When the ELF is auto-detected (no --elf), these flags choose which build to use, just like selecting a Cargo target. All three are mutually exclusive with --elf.

FlagDefaultDescription
--releaseUse the release-profile build.
--debugdefaultUse the debug-profile build (the default).
--bin <BIN>Select the binary when the crate defines more than one.

Proving keys​

Use a proving key instead of pulling the one at the default location. Pick the right flag for the proof type you intend to generate.

FlagShortDefaultDescription
--proving-key <PROVING_KEY>-kcached keyPath to a precomputed STARK proving key.
--proving-key-snark <PROVING_KEY_SNARK>-wcached keyPath to a precomputed SNARK proving key. Only consulted when --pilfflonk or --plonk is set. --proving-key-plonk is kept as an alias.

Proof output​

Where the proof is written and what shape it takes.

FlagShortDefaultDescription
--output <OUTPUT>-o<unix-ts>-proof.binFile path the generated proof is written to. The default name uses the current Unix time in seconds.
--minimal-cfalseSmaller STARK proof at the cost of longer proving time. Mutually exclusive with --pilfflonk and --plonk.
--pilfflonkfalseEmit a pilfflonk final SNARK proof, the one the release SNARK proving key is set up for and the on-chain verifier contracts in zisk-contracts/<family>/ take. Mutually exclusive with --plonk and --minimal.
--plonkfalseEmit a PLONK final SNARK proof. Advanced: needs a Poseidon SNARK proving key you set up yourself with --final-snark plonk. Mutually exclusive with --pilfflonk and --minimal.
--verify-proof-yfalseVerify the proof immediately after generating it.

The SNARK proving key is set up for one protocol, and the flag must name it. Asking for --plonk with the release (pilfflonk) key fails before proving with a PLONK final SNARK was asked for, but the SNARK proving key <path> is set up for pilfflonk. See Choosing a proof format.

SNARK proofs: key and memory

ziskup --provingkey installs only the STARK proving key. The SNARK proving key is installed separately with ziskup setup_snark, which is not supported on macOS, so --pilfflonk and --plonk are unavailable there. On CPU, a pilfflonk final SNARK has a peak working set of more than 60 GB; use --gpu on a GPU build. A plain CPU STARK proof peaks at about 43 GB. On Linux you need that much RAM or enough swap, otherwise the kernel OOM-kills the process; on macOS a STARK proof also runs with less RAM (memory is compressed and swapped, so it is slower).

Execution backend​

By default prove runs the guest through the portable Rust emulator. On Linux x86_64 you can switch to the native Assembly emulator, which is significantly faster for large programs.

FlagShortDefaultDescription
--asm-afalseUse the native Assembly emulator instead of the default Rust emulator (Linux x86_64). Rejected on macOS.

Performance​

Flags that trade off speed against memory or unlock platform-specific acceleration.

FlagShortDefaultDescription
--gpu-gfalseUse GPU acceleration during proof generation. Requires a supported CUDA GPU. Only in the GPU build of cargo-zisk.
--cpu-mopsfalseRun the memory-operations planner on the CPU even when --gpu is set. A fallback for GPU-planner issues. Only in the GPU build.
--minimal-memory-mfalseReduce memory footprint during proving at the cost of speed.
--max-witness-stored <MAX_WITNESS_STORED>-xMaximum memory in bytes for witness storage during proving. Lowering this trades proving time for memory.
--unlock-mapped-memory-ufalseUnlock the memory map for the ROM file. Only applies with --asm.
GPU-only flags

--gpu and --cpu-mops exist only in the GPU build of cargo-zisk. The CPU-only build (including the macOS build) rejects them with error: unexpected argument '--gpu' found.

Diagnostics​

FlagShortDefaultDescription
--verbose-voffIncrease output verbosity. Repeat it for more detail, up to -vvv.

Examples​

Generate an aggregated STARK proof from the auto-detected ELF and an input — the simplest invocation:

cargo-zisk prove --inputs ./inputs/data.bin

Generate a proof for a binary input file and write it to a specific path:

cargo-zisk prove --inputs ./inputs/data.bin --output ./proofs/my-proof.bin

Generate a pilfflonk final SNARK proof for on-chain verification via the EVM verifier:

cargo-zisk prove --inputs ./inputs/data.bin --pilfflonk

Generate a smaller STARK proof (slower to produce):

cargo-zisk prove --inputs ./inputs/data.bin --minimal

Prove on a GPU (GPU build only):

cargo-zisk prove --inputs ./inputs/data.bin --gpu

Cap witness memory at 4 GiB and reduce overall memory footprint on a small host:

cargo-zisk prove --inputs ./inputs/data.bin --minimal-memory --max-witness-stored 4294967296

Outputs​

cargo-zisk prove forwards the guest's stdout to your terminal as it runs (several times over with the default Rust emulator, and not at all with --asm, as with execute), then writes the resulting proof to the path specified by --output (default <unix-ts>-proof.bin in the current directory).

The run ends with a summary like this:

--- PROVE SUMMARY -------------
Proof generated in 12.345s, steps: 1234567
Random seed: 3f9a6c0e1b2d4f5a6b7c8d9e0f1a2b3c4d5e6f708192a3b4c5d6e7f8091ac210
Proof saved to 1767225600-proof.bin

When running under MPI, only the rank that aggregates the proof holds a final proof. The other ranks write nothing and log No final proof to write for this run.