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.
| Flag | Short | Default | Description |
|---|---|---|---|
--elf <ELF> | -e | auto-detected | Path to the program ELF. If omitted, the ELF is auto-detected from the current project. |
--inputs <INPUTS> | -i | empty | Input 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 seed | Use 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. |
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.
| Flag | Default | Description |
|---|---|---|
--release | Use the release-profile build. | |
--debug | default | Use 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.
| Flag | Short | Default | Description |
|---|---|---|---|
--proving-key <PROVING_KEY> | -k | cached key | Path to a precomputed STARK proving key. |
--proving-key-snark <PROVING_KEY_SNARK> | -w | cached key | Path 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.
| Flag | Short | Default | Description |
|---|---|---|---|
--output <OUTPUT> | -o | <unix-ts>-proof.bin | File path the generated proof is written to. The default name uses the current Unix time in seconds. |
--minimal | -c | false | Smaller STARK proof at the cost of longer proving time. Mutually exclusive with --pilfflonk and --plonk. |
--pilfflonk | false | Emit 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. | |
--plonk | false | Emit 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 | -y | false | Verify 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.
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.
| Flag | Short | Default | Description |
|---|---|---|---|
--asm | -a | false | Use 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.
| Flag | Short | Default | Description |
|---|---|---|---|
--gpu | -g | false | Use GPU acceleration during proof generation. Requires a supported CUDA GPU. Only in the GPU build of cargo-zisk. |
--cpu-mops | false | Run 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 | -m | false | Reduce memory footprint during proving at the cost of speed. |
--max-witness-stored <MAX_WITNESS_STORED> | -x | Maximum memory in bytes for witness storage during proving. Lowering this trades proving time for memory. | |
--unlock-mapped-memory | -u | false | Unlock the memory map for the ROM file. Only applies with --asm. |
--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
| Flag | Short | Default | Description |
|---|---|---|---|
--verbose | -v | off | Increase 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.