Skip to main content

Execute

Runs the guest through the same pipeline as prove but without producing a proof, so you can validate inputs and hint streams and measure execution cost before paying for proof generation. Documents the input, backend, and diagnostic flags plus the execution-statistics output.

Execute the guest program through the same pipeline that cargo-zisk prove uses, but without generating a proof. Use execute to validate that your inputs and hint streams are consistent with the path prove will take, and to measure execution cost end-to-end before paying for proof generation.

cargo-zisk execute [OPTIONS]
execute vs run

execute runs through the full proving pipeline (minus the proof itself), so it catches input and hint mismatches that run would miss. Use run for quick logic checks and cycle profiling; use execute when you are ready to validate that your program is provable.

Inputs​

Identify the program to execute 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

execute does not run setup and does not need a proving key. With --asm, the first run for a given ELF generates the Assembly emulator binaries and reuses them on later runs.

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.

Execution backend​

By default execute runs the guest through the portable Rust emulator. On Linux x86_64 you can switch to the native Assembly emulator.

FlagShortDefaultDescription
--asm-afalseUse the native Assembly emulator instead of the default Rust emulator (Linux x86_64). Rejected on macOS.
--gpu-gfalseOffload witness generation to a CUDA-capable GPU. Only in the GPU build of cargo-zisk.

Advanced​

FlagShortDefaultDescription
--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​

Execute with the auto-detected ELF and a binary input file — the simplest invocation:

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

Execute with inline input data, two frames of u64 words:

cargo-zisk execute --inputs 'inline://[[1,2],[3]]'

Execute against a specific ELF, e.g. one built outside the current project:

cargo-zisk execute --elf ./dist/guest.elf --inputs ./inputs/data.bin

Execute a guest that expects precompile hints, supplying the hints file:

cargo-zisk execute --inputs ./inputs/data.bin --hints ./hints.bin

Switch to the native Assembly emulator instead of the default Rust emulator:

cargo-zisk execute --asm --inputs ./inputs/data.bin

Outputs​

cargo-zisk execute forwards what the guest writes to stdout to your terminal, with a caveat: with the default Rust emulator the guest output is printed several times, and with --asm it is not printed at all. Use run to inspect guest output. After the guest finishes, execute logs an execution summary (RISC-V steps, the random seed, per-stage timing and the planned instances) so you can check a dry run before paying for the proof. Every line is prefixed with a timestamp (omitted below) and the log level:

INFO: --- EXECUTE SUMMARY -----------
INFO: Execution completed in 6ms, steps: 106968, cost: N/A
INFO: Random seed: 0d008bc7a224c62885d5242dc6f3378bde5534d424aae21acaa1f0a647782c16
INFO: Execution time breakdown: 6ms [ Execution 4ms + Count&Plan 1ms + Count&Plan MO 0ms ]
INFO: Plan [ Arith: 1 | Binary: 1 | BinaryExtension: 1 | Dma: 1 | Dma64AlignedMem: 1 | DmaPrePost: 1 | DmaUnaligned: 1 | InputData: 1 | Keccakf: 1 | Main: 1 | Mem: 1 | MemAlign: 1 | Rom: 1 | RomData: 1 | VirtualTableZisk0: 1 ] Total instances: 15

The summary reports cost: N/A; use run --profiling for the cost breakdown. The PROOF INSTANCES SUMMARY table is printed by prove, not by execute.

With --asm, an Assembly execution speed: <time>ms (<speed> MHz) line follows the time breakdown.