Skip to main content

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 time

Without --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 vs execute

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.

FlagShortDefaultDescription
--releasefalseBuild 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).

FlagShortDefaultDescription
--features <FEATURES>-FNoneActivate the named features on top of the defaults. Accepts a single string with values separated by spaces or commas.
--all-featuresActivate every feature declared by the crate.
--no-default-featuresSkip the crate's default feature set entirely. Combine with --features to opt back in to just the ones you need.

Runtime flags​

FlagShortDefaultDescription
--elf <elf>-eselected profile buildPath 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>-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. Omit for no input.
--profiling <reports>-pnoneCost report to emit. One of inline, summary, or complete — see Outputs. Omit for a plain run with no report.
--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.

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.

FlagDefaultDescription
--debugdefaultUse 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.

Remove profiling markers before proving

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.