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.
| Approach | How it works | Trade-off |
|---|---|---|
| Patches | Swap 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 wrappers | Replace 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).
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:
[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.
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:
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
| Crate | Repo | Crate version | Zisk versions | |
|---|---|---|---|---|
sha2 | zisk-patch-hashes | 0.10.9 | 0.11.0–0.15.0, 0.16.0+ | |
sha3 | zisk-patch-hashes | 0.10.8 | 0.11.0–0.15.0, 0.16.0+ | |
tiny-keccak | zisk-patch-tiny-keccak | 2.0.2 | 0.15.0, 0.16.0+ |
Elliptic curves
| Crate | Repo | Crate version | Zisk versions | |
|---|---|---|---|---|
k256 | zisk-patch-elliptic-curves | 0.13.4 | 0.11.0–0.15.0, 0.17.0, 1.4.0 | |
p256 | zisk-patch-elliptic-curves | 0.13.2 | 0.11.0–0.15.0, 0.17.0, 1.4.0 | |
substrate-bn | zisk-patch-bn | 0.6.0 | 0.11.0–0.15.0, 0.17.0, 1.4.0 | |
blst | zisk-patch-blst | 0.3.15, 0.3.16 | 0.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
| Crate | Repo | Crate version | Zisk versions | |
|---|---|---|---|---|
ruint | zisk-patch-ruint | 1.17.0, 1.17.2, 1.19.1 | 0.13.1, 0.15.0, 0.17.0, 1.0.0+ (1.19.1) | |
aurora-engine-modexp | zisk-patch-modexp | 1.2.0 | 0.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.
[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"
ziskos source in every cratecommon 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:
/// 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:
#![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:
[[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:
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:
- Your first proof: drive the full proving pipeline end to end via CLI or SDK.