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 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.
| 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. |
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.
| 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. |
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.
| Flag | Short | Default | Description |
|---|---|---|---|
--asm | -a | false | Use the native Assembly emulator instead of the default Rust emulator (Linux x86_64). Rejected on macOS. |
--gpu | -g | false | Offload witness generation to a CUDA-capable GPU. Only in the GPU build of cargo-zisk. |
Advanced
| Flag | Short | Default | Description |
|---|---|---|---|
--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
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.