Setup
Pre-generates the proving key for a compiled guest ELF, which must exist before prove can produce a proof and must be regenerated whenever the ELF changes. Covers the input, proving-key, and backend flags and where the setup files are cached.
Generate the proving key for a compiled guest ELF. The proving key
encodes the arithmetic structure of the program and must exist before
cargo-zisk prove can produce a proof. Re-run setup whenever the ELF
changes — the key is tied to the exact compiled program.
cargo-zisk setup [OPTIONS]
Inputs
Identify the program to set up.
| 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. |
--aggregation <TOML> | Set up an aggregation definition (<programs>/aggregations/<name>.toml) as a recurser instead of a guest ELF. See Aggregate. |
--aggregation conflicts with --elf, --bin, --asm, --hints,
--proving-key-snark and --unlock-mapped-memory. Only --proving-key and
--verbose apply to a recurser setup; --release and --debug are accepted
alongside --aggregation but ignored.
setup --aggregation needs:
cargo-zisk setup --elf <guest ELF>already run for every guest in the definition'sprogramsallow-list (otherwise it fails withROM merkle setup has not been performed yet).- Node.js and npm on
PATH. npm installs the PIL compiler on the first setup (otherwiseCannot find pil2com…); Node.js runs it on every setup.
See Set up the recurser.
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
Reuse a precomputed key instead of generating one at the default location.
| Flag | Short | Default | Description |
|---|---|---|---|
--proving-key <PROVING_KEY> | -k | Path to a precomputed proving key. | |
--proving-key-snark <PROVING_KEY_SNARK> | -w | Path to a precomputed SNARK proving key. --proving-key-plonk is kept as an alias. |
Execution backend
The setup needed for proving depends on the executor it will run with.
| Flag | Short | Default | Description |
|---|---|---|---|
--asm | -a | false | Generate the setup for the native Assembly emulator (Linux x86_64) rather than the default Rust emulator. Rejected on macOS. |
--hints | false | Enable precompiles hints support for this program. Requires --asm. | |
--unlock-mapped-memory | -u | false | Unlock the memory map for the ROM file. Only applies with --asm. |
Diagnostics
| Flag | Short | Default | Description |
|---|---|---|---|
--verbose | -v | off | Increase output verbosity. Repeat it for more detail, up to -vvv. |
Examples
Generate the proving key from the auto-detected ELF, the typical post-build invocation:
cargo-zisk setup
Point at a specific ELF outside the current project:
cargo-zisk setup --elf ./dist/guest.elf
Generate the Assembly-backend setup with precompile hint support (the guest must have been built with the matching hints feature):
cargo-zisk setup --asm --hints
Set up a recurser from an aggregation definition:
cargo-zisk setup --aggregation ./programs/aggregations/pair.toml
Outputs
The setup files are written flat into the standard cache directory
(ZISK_CACHE_DIR overrides it), named by the blake3 hash of the ELF:
~/.zisk/cache/
The summary prints the program name and its Hash ID, the key the cached
files are named by. The setup is per hash mode: it follows the hash mode of
the proving key (Blake3 by default, see
hash modes), so a key
of the other mode needs its own setup. A recurser setup goes to
~/.zisk/recurser/ instead (build/, circom/, pil/ and
provingKey/recurser/<recurser-id>/) and prints its Recurser ID.
Downstream commands (cargo-zisk prove, etc.) pick up the setup files
from this location automatically. If no setup exists yet for the target
ELF, prove invokes setup itself on first use (execute needs no
setup); running it
explicitly is mainly a way to prewarm the cache so the next call to
prove doesn't pay for setup time.