Skip to main content

Optimizing your program

This guide covers the two ergonomic ways to route expensive operations through ZisK native precompiles: patched crates, which accelerate an entire dependency with a single Cargo.toml change and no guest code changes, and zisklib wrappers, which replace individual call sites with safe Rust functions when no patch exists.

Understanding the approaches​

ZisK exposes native operations called precompiles that execute cryptographic and arithmetic primitives in a single VM step. Patches and Precompile wrappers (zisklib) are two ergonomic layers on top of them.

ApproachHow it worksTrade-off
PatchesSwap a crate dependency in Cargo.toml for a ZisK-accelerated fork. Every workspace crate that uses the library is accelerated automatically, with no source changes.Version pinning: each patch targets a specific upstream version, so upgrading a dependency may need a matching fork.
Precompile wrappersReplace individual call sites with safe Rust functions that dispatch directly to the corresponding ZisK state machine.Each call site must be updated manually.

Applying a patch​

This guide picks up where the profiling guide left off and uses the same merkle-tree project. Completing that guide is a prerequisite as it produces the workspace, the shared merkle_root logic in common/, and the guest in guest/src/main.rs that this guide patches and optimizes. If you have not finished the profiling guide yet, go through it first and then come back here.

Getting a baseline​

Before touching Cargo.toml, capture the unpatched cost so you have a reference to compare against. Build and run with --profiling summary to get the full cost breakdown. All the reports in this guide were produced at cost version 1, as their REPORT SUMMARY (cost version 1) header states. Compare only reports of the same cost version (see Cost model).

bash
cargo-zisk build --release
cargo-zisk run --release -i samples/example-input.bin --profiling summary
Random seed: ea7256ad1e00df9ca155fe25f97b9be799636e1c688057f5bd280eb6f957006b
merkle-root(1000) => 0xf94e7857a9aa655788bccc391771dbe005b9b9cbd2be8f26c56bd08c6c755da5

╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║ ◆ REPORT SUMMARY (cost version 1) ║
╠══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╣
║ STEPS 8,094,848 ║
║ COST 1,121,406,110 ║
║ RAM 0.03 MB / 507.56 MB ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝

╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║ ◆ COST DISTRIBUTION SUMMARY ║
╠══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╣
║ CATEGORY COST % ║
║ ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄ ║
║ Base ████████████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 285,212,672 25.4% ║
║ Main ███████████████████████████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 501,880,576 44.8% ║
║ Opcodes █████████████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 302,471,472 27.0% ║
║ Precompiles ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 1,325,964 0.1% ║
║ Memory ██░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 30,515,426 2.7% ║
║ ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄ ║
║ Total 1,121,406,110 100.0% ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝

╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║ ◆ COST DISTRIBUTION BY OPCODE ║ ◆ OPS vs FROPS ║
╠══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╣
║ OPCODE COST % ║ OPS + FROPS FROPS % ║
║ ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄ ║ ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄ ║
║ ror_w ██░░░░░░░░░░░░░░░░░░░░░ 95,103,360 8.5% ║ 95,103,360 0 0.0% ║
║ xor ██░░░░░░░░░░░░░░░░░░░░░ 92,022,260 8.2% ║ 95,213,910 3,191,650 3.4% ║
║ add █░░░░░░░░░░░░░░░░░░░░░░ 39,115,626 3.5% ║ 39,900,858 785,232 2.0% ║
║ and █░░░░░░░░░░░░░░░░░░░░░░ 31,874,315 2.8% ║ 31,876,295 1,980 0.0% ║
║ srl_w ░░░░░░░░░░░░░░░░░░░░░░░ 13,043,690 1.2% ║ 13,043,690 0 0.0% ║
║ or ░░░░░░░░░░░░░░░░░░░░░░░ 10,567,535 0.9% ║ 10,567,590 55 0.0% ║
║ andn ░░░░░░░░░░░░░░░░░░░░░░░ 10,567,040 0.9% ║ 10,567,040 0 0.0% ║
║ signextend_w ░░░░░░░░░░░░░░░░░░░░░░░ 4,847,205 0.4% ║ 4,847,205 0 0.0% ║
║ srl ░░░░░░░░░░░░░░░░░░░░░░░ 3,082,585 0.3% ║ 6,331,820 3,249,235 51.3% ║
║ rev8 ░░░░░░░░░░░░░░░░░░░░░░░ 1,871,320 0.2% ║ 3,577,255 1,705,935 47.7% ║
║ ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄ ║ ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄ ║
║ Total 303,797,436 27.1% ║ 313,402,633 9,605,197 3.1% ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝

╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║ ◆ TOP COST FUNCTIONS ║
╠══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╣
║ 0 sha2::sha256::compress256 ███████████████░░░░░ 817,629,138 72.9% ║
║ 1 merkle_tree_common::merkle_root ██████████░░░░░░░░░░ 557,596,520 49.7% ║
║ 2 <[u8; 32] as hex::ToHex>::encode_hex::<alloc::string::String> ░░░░░░░░░░░░░░░░░░░░ 185,595 0.0% ║
║ 3 std::io::stdio::_print ░░░░░░░░░░░░░░░░░░░░ 139,828 0.0% ║
║ 4 <&std::io::stdio::Stdout as core::io::write::Write>::write_fmt ░░░░░░░░░░░░░░░░░░░░ 131,188 0.0% ║
║ 5 core::fmt::write ░░░░░░░░░░░░░░░░░░░░ 126,580 0.0% ║
║ 6 <core::..::Adapter<…> as core::fmt::Write>::write_str ░░░░░░░░░░░░░░░░░░░░ 101,475 0.0% ║
║ 7 <std::io::stdio::StdoutLock as core::io::write::Write>::write_all ░░░░░░░░░░░░░░░░░░░░ 95,228 0.0% ║
║ 8 <hex::BytesToHexChars as core::..::Iterator>::next ░░░░░░░░░░░░░░░░░░░░ 90,353 0.0% ║
║ 9 sys_write ░░░░░░░░░░░░░░░░░░░░ 37,022 0.0% ║
║ 10 core::slice::memchr::memrchr_aligned ░░░░░░░░░░░░░░░░░░░░ 31,899 0.0% ║
║ 11 <u64 as core::fmt::Display>::fmt ░░░░░░░░░░░░░░░░░░░░ 22,862 0.0% ║
║ 12 <alloc::string::String as core::fmt::Display>::fmt ░░░░░░░░░░░░░░░░░░░░ 18,906 0.0% ║
║ 13 <str as core::fmt::Display>::fmt ░░░░░░░░░░░░░░░░░░░░ 18,399 0.0% ║
║ 14 <core::fmt::Formatter>::pad ░░░░░░░░░░░░░░░░░░░░ 18,089 0.0% ║
║ 15 <core::fmt::Formatter>::pad_integral ░░░░░░░░░░░░░░░░░░░░ 16,867 0.0% ║
║ 16 ziskos::io::commit_slice ░░░░░░░░░░░░░░░░░░░░ 12,155 0.0% ║
║ 17 write_output ░░░░░░░░░░░░░░░░░░░░ 12,031 0.0% ║
║ 18 <…>::reserve::do_reserve_and_handle::<alloc::alloc::Global> ░░░░░░░░░░░░░░░░░░░░ 5,129 0.0% ║
║ 19 <…>::initialize::<…> ░░░░░░░░░░░░░░░░░░░░ 4,324 0.0% ║
║ 20 __rustc::__rust_alloc ░░░░░░░░░░░░░░░░░░░░ 3,270 0.0% ║
║ 21 <alloc::raw_vec::RawVecInner>::finish_grow ░░░░░░░░░░░░░░░░░░░░ 3,110 0.0% ║
║ 22 bincode::varint::decode_unsigned::deserialize_varint_cold_u64::<…> ░░░░░░░░░░░░░░░░░░░░ 2,171 0.0% ║
║ 23 <core::fmt::Formatter>::pad_integral::write_prefix ░░░░░░░░░░░░░░░░░░░░ 1,808 0.0% ║
║ 24 ziskos::io::read_input_slice ░░░░░░░░░░░░░░░░░░░░ 1,406 0.0% ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝

Adding the patch​

The guest code stays exactly as it was, no changes needed. Just open guest/Cargo.toml and add the patch entry:

guest/Cargo.toml
[patch.crates-io]
sha2 = { git = "https://github.com/0xPolygonHermez/zisk-patch-hashes", package = "sha2", tag = "patch-sha2-0.10.9-zisk-0.16.0+" }

The tag field encodes both the patched crate version and the ZisK version it targets (patch-sha2-<crate-version>-zisk-<zisk-version>). Choose the tag whose crate version matches your sha2 dependency and whose ZisK version is the closest to the one you are using. The override applies to the guest's whole dependency graph, so every crate the guest builds that depends on sha2, common included, is accelerated automatically, with no changes to any source file.

Put the patch in the guest manifest

Cargo reads [patch] only from the root manifest of the workspace being built, and the guest is built as its own workspace. In a project created with cargo-zisk new there is no root Cargo.toml, and a root manifest that holds only a [patch] section is not valid. In the examples repository, examples/merkle-tree/guest/Cargo.toml declares its own [workspace], so a patch in examples/Cargo.toml is silently ignored. In both cases, add the entry to guest/Cargo.toml. The patch is not part of the example: in the cloned repository, uncomment the [patch.crates-io] lines already present in guest/Cargo.toml.

Rebuilding and measuring​

With the patch in place, rebuild and run the same profiling command as the baseline. Cargo will resolve sha2 to the patched fork automatically, with no other changes needed. The guest binary changes because the SHA-256 implementation is different, but the program logic, inputs, and committed output remain identical:

bash
cargo-zisk build --release
cargo-zisk run --release -i samples/example-input.bin --profiling summary
Random seed: c9554a3bde9fffa7be51c0579967fff6108c9b5557112d0b2056f38102a44686
merkle-root(1000) => 0xf94e7857a9aa655788bccc391771dbe005b9b9cbd2be8f26c56bd08c6c755da5

╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║ ◆ REPORT SUMMARY (cost version 1) ║
╠══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╣
║ STEPS 226,601 ║
║ COST 340,755,113 ║
║ RAM 0.03 MB / 507.56 MB ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝

╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║ ◆ COST DISTRIBUTION SUMMARY ║
╠══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╣
║ CATEGORY COST % ║
║ ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄ ║
║ Base █████████████████████████████████████████████████████████████████░░░░░░░░░░░░░ 285,212,672 83.7% ║
║ Main ███░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 14,049,262 4.1% ║
║ Opcodes █░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 3,695,832 1.1% ║
║ Precompiles ███████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 28,866,312 8.5% ║
║ Memory ██░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 8,931,035 2.6% ║
║ ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄ ║
║ Total 340,755,113 100.0% ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝

╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║ ◆ COST DISTRIBUTION BY OPCODE ║ ◆ OPS vs FROPS ║
╠══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╣
║ OPCODE COST % ║ OPS + FROPS FROPS % ║
║ ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄ ║ ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄ ║
║ sha256 ██░░░░░░░░░░░░░░░░░░░░░ 26,369,568 7.7% ║ ║
║ dma_xmemcpy ░░░░░░░░░░░░░░░░░░░░░░░ 1,888,757 0.6% ║ ║
║ signextend_w ░░░░░░░░░░░░░░░░░░░░░░░ 884,565 0.3% ║ 884,565 0 0.0% ║
║ srl ░░░░░░░░░░░░░░░░░░░░░░░ 880,660 0.3% ║ 883,190 2,530 0.3% ║
║ rev8 ░░░░░░░░░░░░░░░░░░░░░░░ 880,385 0.3% ║ 935,495 55,110 5.9% ║
║ dma_xmemset ░░░░░░░░░░░░░░░░░░░░░░░ 606,502 0.2% ║ ║
║ add ░░░░░░░░░░░░░░░░░░░░░░░ 389,598 0.1% ║ 481,473 91,875 19.1% ║
║ and ░░░░░░░░░░░░░░░░░░░░░░░ 338,305 0.1% ║ 340,340 2,035 0.6% ║
║ eq ░░░░░░░░░░░░░░░░░░░░░░░ 124,245 0.0% ║ 575,685 451,440 78.4% ║
║ xor ░░░░░░░░░░░░░░░░░░░░░░░ 110,550 0.0% ║ 110,550 0 0.0% ║
║ ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄ ║ ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄ ║
║ Total 32,562,144 9.6% ║ 33,384,804 822,660 2.5% ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝

╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║ ◆ TOP COST FUNCTIONS ║
╠══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╣
║ 0 sha2::sha256::compress256 ██░░░░░░░░░░░░░░░░░░ 36,978,599 10.9% ║
║ 1 sha256f_compress_c ██░░░░░░░░░░░░░░░░░░ 36,606,351 10.7% ║
║ 2 merkle_tree_common::merkle_root ██░░░░░░░░░░░░░░░░░░ 35,630,776 10.5% ║
║ 3 syscall_sha256_f ██░░░░░░░░░░░░░░░░░░ 26,906,926 7.9% ║
║ 4 <[u8; 32] as hex::ToHex>::encode_hex::<alloc::string::String> ░░░░░░░░░░░░░░░░░░░░ 185,595 0.1% ║
║ 5 std::io::stdio::_print ░░░░░░░░░░░░░░░░░░░░ 139,370 0.0% ║
║ 6 <&std::io::stdio::Stdout as core::io::write::Write>::write_fmt ░░░░░░░░░░░░░░░░░░░░ 130,730 0.0% ║
║ 7 core::fmt::write ░░░░░░░░░░░░░░░░░░░░ 126,122 0.0% ║
║ 8 <core::..::Adapter<…> as core::fmt::Write>::write_str ░░░░░░░░░░░░░░░░░░░░ 101,017 0.0% ║
║ 9 <std::io::stdio::StdoutLock as core::io::write::Write>::write_all ░░░░░░░░░░░░░░░░░░░░ 94,770 0.0% ║
║ 10 <hex::BytesToHexChars as core::..::Iterator>::next ░░░░░░░░░░░░░░░░░░░░ 90,353 0.0% ║
║ 11 sys_write ░░░░░░░░░░░░░░░░░░░░ 37,022 0.0% ║
║ 12 core::slice::memchr::memrchr_aligned ░░░░░░░░░░░░░░░░░░░░ 31,441 0.0% ║
║ 13 <u64 as core::fmt::Display>::fmt ░░░░░░░░░░░░░░░░░░░░ 22,862 0.0% ║
║ 14 <alloc::string::String as core::fmt::Display>::fmt ░░░░░░░░░░░░░░░░░░░░ 18,906 0.0% ║
║ 15 <str as core::fmt::Display>::fmt ░░░░░░░░░░░░░░░░░░░░ 18,399 0.0% ║
║ 16 <core::fmt::Formatter>::pad ░░░░░░░░░░░░░░░░░░░░ 18,089 0.0% ║
║ 17 <core::fmt::Formatter>::pad_integral ░░░░░░░░░░░░░░░░░░░░ 16,867 0.0% ║
║ 18 ziskos::io::commit_slice ░░░░░░░░░░░░░░░░░░░░ 12,155 0.0% ║
║ 19 write_output ░░░░░░░░░░░░░░░░░░░░ 12,031 0.0% ║
║ 20 <…>::reserve::do_reserve_and_handle::<alloc::alloc::Global> ░░░░░░░░░░░░░░░░░░░░ 5,129 0.0% ║
║ 21 <…>::initialize::<…> ░░░░░░░░░░░░░░░░░░░░ 4,324 0.0% ║
║ 22 __rustc::__rust_alloc ░░░░░░░░░░░░░░░░░░░░ 3,270 0.0% ║
║ 23 <alloc::raw_vec::RawVecInner>::finish_grow ░░░░░░░░░░░░░░░░░░░░ 3,110 0.0% ║
║ 24 bincode::varint::decode_unsigned::deserialize_varint_cold_u64::<…> ░░░░░░░░░░░░░░░░░░░░ 2,171 0.0% ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝

Total cost drops from about 1,121M to about 340.8M with zero changes to guest code. sha2::sha256::compress256 still heads the top cost functions, but it fell from 72.9% of a 1,121M total to 10.9% of a 340.8M one, because it now hands each block to the sha256f precompile instead of running the rounds in software. SHA-256 work has migrated out of Opcodes and into Precompiles at a fraction of its prior rate, and the xor/or/shift-heavy opcode pattern the software implementation produced has vanished from the opcode table.

Most of what remains is Base, the fixed floor every proof pays, now about 84% of the total. The variable cost left is the sha256 precompile itself and the Merkle tree structure: memory accesses, vector allocation, and the loop, which are the irreducible costs of the algorithm regardless of how SHA-256 is implemented.

Available patches​

Tags follow the pattern patch-{X}-zisk-{Y} where X is the patched crate version and Y is the ZisK version. A + suffix on the ZisK version (e.g. 0.16.0+) means the patch is forward-compatible from that release onward. For repos that don't carry tags, pick the branch that matches your upstream version. The Copy button copies the latest [patch.crates-io] entry for that crate.

Hash functions​

CrateRepoCrate versionZisk versions
sha2zisk-patch-hashes0.10.90.11.0–0.15.0, 0.16.0+
sha3zisk-patch-hashes0.10.80.11.0–0.15.0, 0.16.0+
tiny-keccakzisk-patch-tiny-keccak2.0.20.15.0, 0.16.0+

Elliptic curves​

CrateRepoCrate versionZisk versions
k256zisk-patch-elliptic-curves0.13.40.11.0–0.15.0, 0.17.0, 1.4.0
p256zisk-patch-elliptic-curves0.13.20.11.0–0.15.0, 0.17.0, 1.4.0
substrate-bnzisk-patch-bn0.6.00.11.0–0.15.0, 0.17.0, 1.4.0
blstzisk-patch-blst0.3.15, 0.3.160.15.0, 0.17.0 (0.3.15), 1.4.0 (0.3.16)

The blst patch compiles C code for the guest target, so it needs the riscv64-unknown-elf-gcc cross compiler from the RISC-V GNU toolchain on your PATH. Without it the build script fails with failed to find tool "riscv64-unknown-elf-gcc".

Big-integer arithmetic​

CrateRepoCrate versionZisk versions
ruintzisk-patch-ruint1.17.0, 1.17.2, 1.19.10.13.1, 0.15.0, 0.17.0, 1.0.0+ (1.19.1)
aurora-engine-modexpzisk-patch-modexp1.2.00.13.0, 0.15.0, 0.16.0+

ruint 1.19.1 is not published on crates.io. To use the 1.19.1 patch, depend on ruint = "1.19" and let the patch supply 1.19.1.


Applying a precompile wrapper​

Use zisklib when no patch exists, to avoid version pinning, or for maximum efficiency. It calls the ZisK precompile directly with no intermediate crate layer, producing fewer guest instructions than a patch. Because it is a regular dependency, it must be declared in every crate that uses it, both common and guest in the example we are working on.

Updating the common crate​

To continue with the same merkle-tree add ziskos in the common crate dependencies.

common/Cargo.toml
[package]
name = "merkle-tree-common"
version = "0.1.0"
edition = "2024"

[dependencies]
sha2 = "0.10.9"
hex = "0.4.3"
ziskos = "1.4.0-alpha"
Use the same ziskos source in every crate

common must take ziskos from exactly the same source as the guest. If one crate uses ziskos = "1.4.0-alpha" from crates.io and the other a path or git dependency, Cargo links two copies of ziskos and the build fails with the `#[global_allocator]` in ziskos conflicts with global allocator in: ziskos. In the examples repository the guest uses ziskos = { path = "../../../ziskos/entrypoint" }, so common must use that same path.

Then update common/src/lib.rs and add a new function that computes merkle_root but calls ziskos::zisklib::sha256:

common/src/lib.rs
/// Same as [`merkle_root`] but delegates SHA-256 to the ZisK built-in
/// (`ziskos::zisklib::sha256`), which maps to a highly optimised ROM operation
/// inside the zkVM instead of executing the hash circuit in user space.
pub fn merkle_root_zisklib(mut leaves: Vec<Hash>) -> Hash {
let mut buf = [0u8; 64];
while leaves.len() > 1 {
let next_len = leaves.len().div_ceil(2);
for i in 0..next_len {
let left = leaves[2 * i];
let right = leaves.get(2 * i + 1).copied().unwrap_or(left);
buf[..32].copy_from_slice(&left);
buf[32..].copy_from_slice(&right);
leaves[i] = ziskos::zisklib::sha256(&buf);
}
leaves.truncate(next_len);
}
leaves[0]
}

Updating the guest crate​

Create a new guest/src/zisklib.rs so the binaries from the previous guides keep working. It drops the Sha256 import and replaces the leaf generation call with ziskos::zisklib::sha256 and the merkle computation with merkle_tree_common::merkle_root_zisklib. The rest of the program stays the same:

guest/src/zisklib.rs
#![no_main]
ziskos::entrypoint!(main);

use merkle_tree_common::{hex, merkle_root_zisklib, Hash};

fn main() {
// Read the number of leaves from the guest's standard input stream.
let n: u64 = ziskos::io::read::<u64>();

// Build leaves using the ZisK Lib built-in SHA-256 operation.
let leaves: Vec<Hash> = (1..=n).map(|i| ziskos::zisklib::sha256(&i.to_le_bytes())).collect();

// Compute the Merkle root using the built-in SHA-256 variant.
let root = merkle_root_zisklib(leaves);

// Commit the root as a public output so a verifier can inspect it
// without re-executing the program.
ziskos::io::commit_slice(&root);

println!("merkle-root({n}) => 0x{}", hex::encode(root));
}

Register the new binary in guest/Cargo.toml alongside the existing ones so they all remain buildable:

guest/Cargo.toml
[[bin]]
name = "zisklib-guest"
path = "src/zisklib.rs"

Rebuilding and measuring​

With the wrappers in place, rebuild and run the same profiling command. The committed output is identical to both the baseline and the patched version, only the implementation of SHA-256 changed, not the program's observable behavior:

bash
cargo-zisk build --release --bin zisklib-guest
cargo-zisk run --release --bin zisklib-guest -i samples/example-input.bin --profiling summary
Random seed: ff83f7c22a2b5fbe4c417bb3a4cac322e34238c4a412945c75d13e37000283f7
merkle-root(1000) => 0xf94e7857a9aa655788bccc391771dbe005b9b9cbd2be8f26c56bd08c6c755da5

╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║ ◆ REPORT SUMMARY (cost version 1) ║
╠══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╣
║ STEPS 205,587 ║
║ COST 335,941,092 ║
║ RAM 0.03 MB / 507.56 MB ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝

╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║ ◆ COST DISTRIBUTION SUMMARY ║
╠══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╣
║ CATEGORY COST % ║
║ ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄ ║
║ Base ██████████████████████████████████████████████████████████████████░░░░░░░░░░░░ 285,212,672 84.9% ║
║ Main ███░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 12,746,394 3.8% ║
║ Opcodes █░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 3,529,151 1.1% ║
║ Precompiles ██████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 27,541,222 8.2% ║
║ Memory ██░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 6,911,653 2.1% ║
║ ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄ ║
║ Total 335,941,092 100.0% ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝

╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║ ◆ COST DISTRIBUTION BY OPCODE ║ ◆ OPS vs FROPS ║
╠══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╣
║ OPCODE COST % ║ OPS + FROPS FROPS % ║
║ ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄ ║ ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄ ║
║ sha256 ██░░░░░░░░░░░░░░░░░░░░░ 26,369,568 7.8% ║ ║
║ signextend_w ░░░░░░░░░░░░░░░░░░░░░░░ 884,565 0.3% ║ 884,565 0 0.0% ║
║ srl ░░░░░░░░░░░░░░░░░░░░░░░ 880,660 0.3% ║ 883,740 3,080 0.3% ║
║ rev8 ░░░░░░░░░░░░░░░░░░░░░░░ 880,385 0.3% ║ 990,495 110,110 11.1% ║
║ dma_xmemcpy ░░░░░░░░░░░░░░░░░░░░░░░ 780,910 0.2% ║ ║
║ and ░░░░░░░░░░░░░░░░░░░░░░░ 393,305 0.1% ║ 395,285 1,980 0.5% ║
║ add ░░░░░░░░░░░░░░░░░░░░░░░ 317,805 0.1% ║ 409,806 92,001 22.4% ║
║ dma_xmemset ░░░░░░░░░░░░░░░░░░░░░░░ 196,196 0.1% ║ ║
║ dma_memcpy ░░░░░░░░░░░░░░░░░░░░░░░ 194,548 0.1% ║ ║
║ eq ░░░░░░░░░░░░░░░░░░░░░░░ 138,600 0.0% ║ 410,575 271,975 66.2% ║
║ ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄ ║ ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄ ║
║ Total 31,070,373 9.2% ║ 32,265,179 1,194,806 3.7% ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝

╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║ ◆ TOP COST FUNCTIONS ║
╠══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╣
║ 0 ziskos::zisklib::lib::sha256::sha256 ███░░░░░░░░░░░░░░░░░ 47,779,438 14.2% ║
║ 1 merkle_tree_common::merkle_root_zisklib ██░░░░░░░░░░░░░░░░░░ 30,436,499 9.1% ║
║ 2 syscall_sha256_f ██░░░░░░░░░░░░░░░░░░ 27,129,037 8.1% ║
║ 3 <[u8; 32] as hex::ToHex>::encode_hex::<alloc::string::String> ░░░░░░░░░░░░░░░░░░░░ 185,595 0.1% ║
║ 4 std::io::stdio::_print ░░░░░░░░░░░░░░░░░░░░ 140,224 0.0% ║
║ 5 <&std::io::stdio::Stdout as core::io::write::Write>::write_fmt ░░░░░░░░░░░░░░░░░░░░ 131,584 0.0% ║
║ 6 core::fmt::write ░░░░░░░░░░░░░░░░░░░░ 126,976 0.0% ║
║ 7 <core::..::Adapter<…> as core::fmt::Write>::write_str ░░░░░░░░░░░░░░░░░░░░ 101,871 0.0% ║
║ 8 <std::io::stdio::StdoutLock as core::io::write::Write>::write_all ░░░░░░░░░░░░░░░░░░░░ 95,624 0.0% ║
║ 9 <hex::BytesToHexChars as core::..::Iterator>::next ░░░░░░░░░░░░░░░░░░░░ 90,353 0.0% ║
║ 10 sys_write ░░░░░░░░░░░░░░░░░░░░ 37,022 0.0% ║
║ 11 core::slice::memchr::memrchr_aligned ░░░░░░░░░░░░░░░░░░░░ 32,295 0.0% ║
║ 12 <u64 as core::fmt::Display>::fmt ░░░░░░░░░░░░░░░░░░░░ 22,862 0.0% ║
║ 13 <alloc::string::String as core::fmt::Display>::fmt ░░░░░░░░░░░░░░░░░░░░ 18,906 0.0% ║
║ 14 <str as core::fmt::Display>::fmt ░░░░░░░░░░░░░░░░░░░░ 18,399 0.0% ║
║ 15 <core::fmt::Formatter>::pad ░░░░░░░░░░░░░░░░░░░░ 18,089 0.0% ║
║ 16 <core::fmt::Formatter>::pad_integral ░░░░░░░░░░░░░░░░░░░░ 16,867 0.0% ║
║ 17 ziskos::io::commit_slice ░░░░░░░░░░░░░░░░░░░░ 12,155 0.0% ║
║ 18 write_output ░░░░░░░░░░░░░░░░░░░░ 12,031 0.0% ║
║ 19 <…>::reserve::do_reserve_and_handle::<alloc::alloc::Global> ░░░░░░░░░░░░░░░░░░░░ 5,129 0.0% ║
║ 20 <…>::initialize::<…> ░░░░░░░░░░░░░░░░░░░░ 4,324 0.0% ║
║ 21 __rustc::__rust_alloc ░░░░░░░░░░░░░░░░░░░░ 3,270 0.0% ║
║ 22 <alloc::raw_vec::RawVecInner>::finish_grow ░░░░░░░░░░░░░░░░░░░░ 3,110 0.0% ║
║ 23 bincode::varint::decode_unsigned::deserialize_varint_cold_u64::<…> ░░░░░░░░░░░░░░░░░░░░ 2,171 0.0% ║
║ 24 <core::fmt::Formatter>::pad_integral::write_prefix ░░░░░░░░░░░░░░░░░░░░ 1,808 0.0% ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝

The result matches the patched version, and is slightly cheaper on top of it. sha2 is gone from the dependency tree entirely, so there is no version to pin and no tag to keep synchronized as ZisK evolves. Each call also dispatches straight to the precompile without going through the upstream crate's outer API layer, which trims a few instructions per invocation, small per call, but visible in the totals on a tight hashing loop like this one.


Available wrappers​

For the full list of zisklib function signatures grouped by curve and operation, see the zisklib reference.


Summary​

Patches and precompile wrappers both route expensive operations through ZisK native precompiles and produce cost reductions. Patches require no guest code changes but are version-pinned to a specific upstream release. Precompile wrappers require updating each call site but carry no version constraint and stay current as ZisK evolves. Check the patches table first: if a fork exists, one line in Cargo.toml is all it takes.


Next steps​

With your guest program written and optimized, the next step is to prove it: