Run
Runs the guest in the lightweight ZisK emulator — the fastest way to check guest behavior and profile where proving cost accumulates, with no trace or proof generated. Covers the compilation, runtime, and --profiling flags and their inline, summary, and complete cost reports.
Run the guest program inside the lightweight ZisK emulator. No
execution trace is recorded and no proof is generated, so run is
the fastest way to verify that the guest behaves correctly and to
profile where proving cost will accumulate well before paying for
a full proof. Unless --elf is given, cargo-zisk run invokes
cargo build for the guest on every call, then runs the resulting ELF.
run rebuilds every timeWithout --elf, each cargo-zisk run recompiles the guest from scratch
(a full recompile, not an incremental no-op). To iterate quickly on inputs,
build once and pass the ELF with --elf.
cargo-zisk run [OPTIONS]
run uses the lightweight emulator: fast, but it does not replicate
the full proving pipeline.
Use execute when you need to
validate that your inputs and hint streams are consistent with the
path prove will take.
Compilation options
Forwarded to the underlying build step that run performs when --elf
is not given.
| Flag | Short | Default | Description |
|---|---|---|---|
--release | false | Build with rustc optimizations enabled. Almost always what you want as debug builds run far more steps inside the emulator. |
Feature selection
Cargo features the guest crate exposes. These behave identically to
cargo build and only matter when run builds the guest (no --elf).
| Flag | Short | Default | Description |
|---|---|---|---|
--features <FEATURES> | -F | None | Activate the named features on top of the defaults. Accepts a single string with values separated by spaces or commas. |
--all-features | Activate every feature declared by the crate. | ||
--no-default-features | Skip the crate's default feature set entirely. Combine with --features to opt back in to just the ones you need. |
Runtime flags
| Flag | Short | Default | Description |
|---|---|---|---|
--elf <elf> | -e | selected profile build | Path to the guest ELF to execute. Without it, run builds the guest and runs the ELF of the selected profile under target/elf/riscv64ima-zisk-zkvm-elf/<profile>/ (debug by default, release with --release). |
--inputs <input> | -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. Omit for no input. |
--profiling <reports> | -p | none | Cost report to emit. One of inline, summary, or complete — see Outputs. Omit for a plain run with no report. |
--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. |
Binary and profile selection
Alongside --release above, these flags choose which build to run when
the ELF is auto-detected, just like selecting a Cargo target. They are
mutually exclusive with --elf.
| Flag | Default | Description |
|---|---|---|
--debug | default | Use the debug-profile build (the default). |
--bin <BIN> | Select the binary when the crate defines more than one. |
Examples
Smoke test — build and run with no input:
cargo-zisk run
Run with a binary input file:
cargo-zisk run --inputs ./inputs/data.bin
Run a specific pre-built ELF instead of letting cargo-zisk rebuild:
cargo-zisk run --elf ./dist/guest.elf --inputs ./inputs/data.bin
Print a structured cost-distribution summary to stdout (totals by category, the costliest opcodes, and the top cost functions):
cargo-zisk run --inputs ./inputs/data.bin --profiling summary
Write the full profiling trace to disk for interactive exploration in the Firefox Profiler:
cargo-zisk run --inputs ./inputs/data.bin --profiling complete
Outputs
cargo-zisk run forwards everything the guest writes to stdout
directly to your terminal so you can verify side-effects and log
output alongside the run.
Before emulating, run prints the random seed it uses on stderr, so a
failing run can be replayed with --random-seed. A seed you passed is
marked (provided):
Random seed: 3f9a6c0e1b2d4f5a6b7c8d9e0f1a2b3c4d5e6f708192a3b4c5d6e7f8091ac210
If the guest exits with a nonzero code, traps (unimp, ebreak, a
panic) or writes a read-only CSR, run prints
Error during emulation: ... and fails with Emulation failed and a
nonzero exit status. Such an execution can never be proven.
In addition, --profiling controls what cost report is appended
after the guest finishes. Three modes:
Inline
Prints the cost or step count of each region the guest wraps with profiling
macro markers (one [TAG] value line each, interleaved with the guest's
stdout), followed by the REPORT SUMMARY and COST DISTRIBUTION SUMMARY
and the accumulated STEPS PROFILE TAGS / COST PROFILE TAGS reports for
the regions wrapped with the report markers.
[INLINE_TAG1] 7102113
acc 0 x 11319712688895001480
╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║ ◆ REPORT SUMMARY (cost version 1) ║
╠══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╣
║ STEPS 106,968 ║
║ COST 303,222,943 ║
║ RAM 0.00 MB / 507.56 MB ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝
╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║ ◆ COST DISTRIBUTION SUMMARY ║
╠══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╣
║ CATEGORY COST % ║
║ ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄ ║
║ Base █████████████████████████████████████████████████████████████████████████░░░░░ 285,212,672 94.1% ║
║ Main ██░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 6,632,016 2.2% ║
║ Opcodes █░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 2,302,121 0.8% ║
║ Precompiles ██░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 8,449,689 2.8% ║
║ Memory ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 626,445 0.2% ║
║ ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄ ║
║ Total 303,222,943 100.0% ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝
╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║ ◆ COST PROFILE TAGS ║
╠══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╣
║ KECCAK_LOOP ███░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 10,759,751 3.5% ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝
Summary
Loads the ELF symbols (the Loading symbols… lines) and prints a
structured profiling report covering total steps, total cost, RAM usage,
the cost distribution by category, the costliest opcodes, and the top cost
functions:
Loading symbols from ELF file: <TMPDIR>/zisk_elf_<elf-hash>.elf
Loaded symbols from ELF file: heap 0xa0430508 - 0xbffc0000 (532216568 bytes), ZISK_BUMP_HEAP_POS @ 0xa0430018
Loaded 198 function symbols (0 marked as selected ROI)
[INLINE_TAG1] 7102113
acc 0 x 11319712688895001480
╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║ ◆ REPORT SUMMARY (cost version 1) ║
╠══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╣
║ STEPS 106,968 ║
║ COST 303,222,943 ║
║ RAM 0.00 MB / 507.56 MB ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝
╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║ ◆ COST DISTRIBUTION SUMMARY ║
╠══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╣
║ CATEGORY COST % ║
║ ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄ ║
║ Base █████████████████████████████████████████████████████████████████████████░░░░░ 285,212,672 94.1% ║
║ Main ██░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 6,632,016 2.2% ║
║ Opcodes █░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 2,302,121 0.8% ║
║ Precompiles ██░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 8,449,689 2.8% ║
║ Memory ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 626,445 0.2% ║
║ ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄ ║
║ Total 303,222,943 100.0% ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝
╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║ ◆ COST DISTRIBUTION BY OPCODE ║ ◆ OPS vs FROPS ║
╠══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╣
║ OPCODE COST % ║ OPS + FROPS FROPS % ║
║ ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄ ║ ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄ ║
║ keccak █░░░░░░░░░░░░░░░░░░░░░░ 8,302,600 2.7% ║ ║
║ eq ░░░░░░░░░░░░░░░░░░░░░░░ 552,255 0.2% ║ 592,570 40,315 6.8% ║
║ sub ░░░░░░░░░░░░░░░░░░░░░░░ 551,100 0.2% ║ 563,255 12,155 2.2% ║
║ sll ░░░░░░░░░░░░░░░░░░░░░░░ 549,945 0.2% ║ 559,405 9,460 1.7% ║
║ add ░░░░░░░░░░░░░░░░░░░░░░░ 520,986 0.2% ║ 606,435 85,449 14.1% ║
║ dma_xmemset ░░░░░░░░░░░░░░░░░░░░░░░ 94,002 0.0% ║ ║
║ xor ░░░░░░░░░░░░░░░░░░░░░░░ 88,110 0.0% ║ 198,165 110,055 55.5% ║
║ and ░░░░░░░░░░░░░░░░░░░░░░░ 33,440 0.0% ║ 52,910 19,470 36.8% ║
║ dma_memcpy ░░░░░░░░░░░░░░░░░░░░░░░ 27,087 0.0% ║ ║
║ dma_xmemcpy ░░░░░░░░░░░░░░░░░░░░░░░ 26,000 0.0% ║ ║
║ ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄ ║ ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄ ║
║ Total 10,751,810 3.5% ║ 11,075,629 323,819 2.9% ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝
╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║ ◆ TOP COST FUNCTIONS ║
╠══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╣
║ 0 ziskos::zisklib::lib::keccak256::keccak256 █░░░░░░░░░░░░░░░░░░░ 10,390,400 3.4% ║
║ 1 memset ░░░░░░░░░░░░░░░░░░░░ 164,250 0.1% ║
║ 2 std::io::stdio::_print ░░░░░░░░░░░░░░░░░░░░ 123,856 0.0% ║
║ 3 <&std::io::stdio::Stdout as core::io::write::Write>::write_fmt ░░░░░░░░░░░░░░░░░░░░ 115,227 0.0% ║
║ 4 core::fmt::write ░░░░░░░░░░░░░░░░░░░░ 110,619 0.0% ║
║ 5 <core::..::Adapter<…> as core::fmt::Write>::write_str ░░░░░░░░░░░░░░░░░░░░ 66,663 0.0% ║
║ 6 <std::io::stdio::StdoutLock as core::io::write::Write>::write_all ░░░░░░░░░░░░░░░░░░░░ 60,405 0.0% ║
║ 7 <u64 as core::fmt::Display>::fmt ░░░░░░░░░░░░░░░░░░░░ 37,954 0.0% ║
║ 8 <core::fmt::Formatter>::pad_integral ░░░░░░░░░░░░░░░░░░░░ 34,226 0.0% ║
║ 9 core::slice::memchr::memrchr_aligned ░░░░░░░░░░░░░░░░░░░░ 22,030 0.0% ║
║ 10 <u8 as core::fmt::Display>::fmt ░░░░░░░░░░░░░░░░░░░░ 18,207 0.0% ║
║ 11 sys_write ░░░░░░░░░░░░░░░░░░░░ 12,714 0.0% ║
║ 12 <…>::initialize::<…> ░░░░░░░░░░░░░░░░░░░░ 4,324 0.0% ║
║ 13 <core::fmt::Formatter>::pad_integral::write_prefix ░░░░░░░░░░░░░░░░░░░░ 3,616 0.0% ║
║ 14 ziskos::io::read_input_slice ░░░░░░░░░░░░░░░░░░░░ 1,406 0.0% ║
║ 15 std::io::stdio::print_to_buffer_if_capture_used ░░░░░░░░░░░░░░░░░░░░ 1,371 0.0% ║
║ 16 bincode::varint::decode_unsigned::deserialize_varint_cold_u64::<…> ░░░░░░░░░░░░░░░░░░░░ 1,245 0.0% ║
║ 17 <<…>::flush_buf::BufGuard as core::ops::drop::Drop>::drop ░░░░░░░░░░░░░░░░░░░░ 1,162 0.0% ║
║ 18 __rustc::__rust_alloc ░░░░░░░░░░░░░░░░░░░░ 1,090 0.0% ║
║ 19 __cxa_finalize ░░░░░░░░░░░░░░░░░░░░ 842 0.0% ║
║ 20 <<…>::flush_buf::BufGuard>::remaining ░░░░░░░░░░░░░░░░░░░░ 596 0.0% ║
║ 21 zkvm_init ░░░░░░░░░░░░░░░░░░░░ 234 0.0% ║
║ 22 __rustc::__rust_no_alloc_shim_is_unstable_v2 ░░░░░░░░░░░░░░░░░░░░ 117 0.0% ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝
Complete
Loads the ELF symbols (the same Loading symbols… lines as summary),
prints the REPORT SUMMARY and COST DISTRIBUTION SUMMARY, writes the full
profiling report to profile.json.gz in the current directory, and prints
Profiler output written to: profile.json.gz. Load the file at
profiler.firefox.com to explore the
call stack and inverted call stack interactively.
Profiling markers are for run only. A guest built with profile markers
cannot be proven: prove fails with Error generating witness for instance id 0 [0:0] of type VadcopFinal.
Remove the markers (or gate them behind a Cargo feature) before running
setup and prove.