Skip to main content

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.

FlagShortDefaultDescription
--elf <ELF>-eauto-detectedPath 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.

Recurser setup prerequisites

setup --aggregation needs:

  1. cargo-zisk setup --elf <guest ELF> already run for every guest in the definition's programs allow-list (otherwise it fails with ROM merkle setup has not been performed yet).
  2. Node.js and npm on PATH. npm installs the PIL compiler on the first setup (otherwise Cannot 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.

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​

Reuse a precomputed key instead of generating one at the default location.

FlagShortDefaultDescription
--proving-key <PROVING_KEY>-kPath to a precomputed proving key.
--proving-key-snark <PROVING_KEY_SNARK>-wPath 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.

FlagShortDefaultDescription
--asm-afalseGenerate the setup for the native Assembly emulator (Linux x86_64) rather than the default Rust emulator. Rejected on macOS.
--hintsfalseEnable precompiles hints support for this program. Requires --asm.
--unlock-mapped-memory-ufalseUnlock the memory map for the ROM file. Only applies with --asm.

Diagnostics​

FlagShortDefaultDescription
--verbose-voffIncrease 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.