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. By default cargo-zisk run builds the guest if it isn't already built, then runs the resulting 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 cargo-zisk build step when run needs to build the guest.

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 triggers a (re)build.

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`	latest build	Path to the guest ELF to execute. Defaults to the most recent build under `target/elf/.../<program-name>`.
`--inputs <input>`	`-i`	empty	Input fed to the guest. Accepts a path to a binary file, an inline string, or a stream descriptor. Omit for no input.
`--profiling <reports>`	`-p`	`inline`	Cost report to emit. One of `inline`, `summary`, or `complete` — see Outputs.

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 (if needed) 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.

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, plus accumulated STEPS PROFILE TAGS and COST PROFILE TAGS reports for the regions wrapped with the report markers.

[`INLINE_TAG1`]    320,750
[`INLINE_TAG2`]    823,540
[`INLINE_TAG3`]    823,540
...

╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║  ◆ REPORT SUMMARY                                                                                                    ║
╠══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╣
║  STEPS                                                                                                   13,285,457  ║
║  COST                                                                                                 1,761,570,966  ║
║  RAM                                                                                            0.03 MB / 507.75 MB  ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝
╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║  ◆ COST DISTRIBUTION SUMMARY                                                                                         ║
╠══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╣
║  CATEGORY                                                                                               COST      %  ║
║  ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄  ║
║  Base         █████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░     293,601,280  16.7%  ║
║  Main         ████████████████████████████████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░     903,411,076  51.3%  ║
║  Opcodes      ███████████████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░     512,255,611  29.1%  ║
║  Precompiles  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░         895,305   0.1%  ║
║  Memory       ██░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░      51,407,694   2.9%  ║
║  ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄  ║
║  Total                                                                                         1,761,570,966 100.0%  ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝
╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║  ◆ STEPS PROFILE TAGS                                                                                                ║
╠══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╣
║  INLINE_TAG1    ██████████████████████████████████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░       7,386,714  55.6%  ║
║  INLINE_TAG2    █████████████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░       3,680,072  27.7%  ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝
╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║  ◆ COST PROFILE TAGS                                                                                                 ║
╠══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╣
║  INLINE_TAG1    ██████████████████████████████████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░     979,074,124  55.6%  ║
║  INLINE_TAG2    █████████████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░     487,471,119  27.7%  ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝

Summary

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:

╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║  ◆ REPORT SUMMARY                                                                                                    ║
╠══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╣
║  STEPS                                                                                                  843,541,983  ║
║  COST                                                                                                91,508,866,391  ║
║  RAM                                                                                           92.70 MB / 507.75 MB  ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝
╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║  ◆ COST DISTRIBUTION SUMMARY                                                                                         ║
╠══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╣
║  CATEGORY                                                                                               COST      %  ║
║  ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄  ║
║  Base         ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░     293,601,280   0.3%  ║
║  Main         █████████████████████████████████████████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░  57,360,854,844  62.7%  ║
║  Opcodes      █████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░  10,219,173,311  11.2%  ║
║  Precompiles  ████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░  13,809,713,056  15.1%  ║
║  Memory       ████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░   9,825,523,900  10.7%  ║
║  ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄  ║
║  Total                                                                                        91,508,866,391 100.0%  ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝
╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║  ◆ COST DISTRIBUTION BY OPCODE                                            ║  ◆ OPS vs FROPS                          ║
╠══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╣
║  OPCODE                                                      COST      %  ║      OPS + FROPS           FROPS      %  ║
║  ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄  ║  ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄  ║
║  keccak                   ███░░░░░░░░░░░░░░░░░░░░  11,476,724,950  12.5%  ║                                          ║
║  or                       █░░░░░░░░░░░░░░░░░░░░░░   2,670,229,800   2.9%  ║    3,277,791,660     607,561,860  18.5%  ║
║  and                      ░░░░░░░░░░░░░░░░░░░░░░░   1,913,578,920   2.1%  ║    2,118,489,660     204,910,740   9.7%  ║
║  add                      ░░░░░░░░░░░░░░░░░░░░░░░   1,791,443,325   2.0%  ║    2,219,017,100     427,573,775  19.3%  ║
║  arith256                 ░░░░░░░░░░░░░░░░░░░░░░░   1,195,960,640   1.3%  ║                                          ║
║  ltu                      ░░░░░░░░░░░░░░░░░░░░░░░     798,536,820   0.9%  ║    1,429,991,280     631,454,460  44.2%  ║
║  eq                       ░░░░░░░░░░░░░░░░░░░░░░░     782,701,980   0.9%  ║    2,432,813,460   1,650,111,480  67.8%  ║
║  sll                      ░░░░░░░░░░░░░░░░░░░░░░░     515,699,116   0.6%  ║    3,482,470,629   2,966,771,513  85.2%  ║
║  sub                      ░░░░░░░░░░░░░░░░░░░░░░░     448,572,420   0.5%  ║      593,595,420     145,023,000  24.4%  ║
║  mul                      ░░░░░░░░░░░░░░░░░░░░░░░     332,241,980   0.4%  ║      388,728,030      56,486,050  14.5%  ║
║  ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄  ║  ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄  ║
║  Total                                             24,028,886,367  26.3%  ║   31,179,597,925   7,150,711,558  22.9%  ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝
╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║  ◆ TOP COST FUNCTIONS                                                                                                ║
╠══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╣
║   0 <…>::execute                                                        ██████████████░░░░░░  66,299,475,262  72.5%  ║
║   1 <…>::execute_block::<…>                                             ██████████████░░░░░░  65,801,711,800  71.9%  ║
║   2 <…>::execution                                                      ██████████████░░░░░░  64,892,630,519  70.9%  ║
║   3 ziskos::zisklib::lib::keccak256::keccak256                          ████░░░░░░░░░░░░░░░░  17,075,562,712  18.7%  ║
║   4 <revm_context::evm::Evm<…> as revm_handler::evm::EvmTr>::frame_init ███░░░░░░░░░░░░░░░░░  15,446,355,181  16.9%  ║
║   5 <…>::new                                                            ███░░░░░░░░░░░░░░░░░  14,783,606,858  16.2%  ║
║   6 <…>::resolve_digests::<…>                                           ███░░░░░░░░░░░░░░░░░  14,004,462,832  15.3%  ║
║   7 revm_precompile::modexp::osaka_run                                  ███░░░░░░░░░░░░░░░░░  13,074,939,885  14.3%  ║
║   8 <…>::modexp                                                         ███░░░░░░░░░░░░░░░░░  12,974,488,605  14.2%  ║
║   9 modexp_bytes_c                                                      ███░░░░░░░░░░░░░░░░░  12,970,972,921  14.2%  ║
║  10 <…>::load_account_mut_optional::<…>                                 ██░░░░░░░░░░░░░░░░░░  10,890,961,538  11.9%  ║
║  11 <…>::load_account_optional::<…>                                     ██░░░░░░░░░░░░░░░░░░  10,841,824,148  11.8%  ║
║  12 <revm_database::states::state::State<…>>::load_cache_account_with   ██░░░░░░░░░░░░░░░░░░  10,633,084,126  11.6%  ║
║  13 <…>::basic                                                          ██░░░░░░░░░░░░░░░░░░  10,562,554,845  11.5%  ║
║  14 <…>::load_account_info_skip_cold_load                               ██░░░░░░░░░░░░░░░░░░   9,531,169,870  10.4%  ║
║  15 <…>::load_account_info_skip_cold_load                               ██░░░░░░░░░░░░░░░░░░   9,516,929,791  10.4%  ║
║  16 revm_interpreter::instructions::contract::call_helpers::..::<…>     ██░░░░░░░░░░░░░░░░░░   9,455,808,217  10.3%  ║
║  17 revm_interpreter::instructions::contract::call_helpers::..::<…>     ██░░░░░░░░░░░░░░░░░░   9,418,548,072  10.3%  ║
║  18 revm_interpreter::instructions::contract::call_helpers::..::<…>     ██░░░░░░░░░░░░░░░░░░   9,400,196,648  10.3%  ║
║  19 ziskos::zisklib::lib::array_lib::rem_short::rem_short               ██░░░░░░░░░░░░░░░░░░   9,064,900,832   9.9%  ║
║  20 <zeth_mpt::..::Node<…> as alloy_rlp::decode::Decodable>::decode     ██░░░░░░░░░░░░░░░░░░   8,651,905,540   9.5%  ║
║  21 revm_interpreter::instructions::contract::call::<…>                 ██░░░░░░░░░░░░░░░░░░   8,364,088,863   9.1%  ║
║  22 <…>::calculate_state_root                                           █░░░░░░░░░░░░░░░░░░░   6,097,456,078   6.7%  ║
║  23 <…>::get_or_insert_with::<…>                                        █░░░░░░░░░░░░░░░░░░░   5,748,942,416   6.3%  ║
║  24 <zeth_mpt::mpt::node::Node<zeth_mpt::mpt::memoize::Cache>>::memoize █░░░░░░░░░░░░░░░░░░░   5,746,493,431   6.3%  ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝

Complete

Writes the full profiling report to profiling/ in the workspace root. Load the file at profiler.firefox.com to explore the call stack and inverted call stack interactively.

Compilation Options​

Feature Selection​

Runtime Flags​

Binary and profile selection​

Examples​

Outputs​

Inline​

Summary​

Complete​