Skip to main content

WASM guests

ZisK can run a WebAssembly module built for the stock wasm32-wasip1 target, with no custom ZisK toolchain. The module is detected by its magic bytes and transpiled into a ZisK ROM at load time, exactly like a RISC-V ELF. This page covers how to build a guest, how WASI stdin and stdout map to the ZisK input and public output, the wasm2zisk tool, and the current limitations of the WASM machine.

How it works​

The transpiler entry point, program2rom, picks a frontend from the first bytes of the guest file. A file starting with \0asm goes to the WebAssembly frontend, wasm2rom. Every other part of the pipeline only ever sees the resulting ZiskRom, so the emulator and prover handle it exactly as they would a transpiled ELF.

The module must export a _start function of type () -> () (or declare a start section), which is what a wasm32-wasip1 command binary does by default.

Building a guest​

The wasm-fibonacci example is a plain Rust program. It reads an 8-byte little-endian n from stdin (default 10) and prints fib(n):

use std::io::Read;

fn fib(n: u64) -> u64 {
let (mut a, mut b) = (0u64, 1u64);
for _ in 0..n {
(a, b) = (b, a + b);
}
a
}

fn main() {
let mut buf = [0u8; 8];
let read = std::io::stdin().read(&mut buf).unwrap_or(0);
let n = if read == 8 { u64::from_le_bytes(buf) } else { 10 };

println!("fib({n}) = {}", fib(n));
}

Build it with the stock target. It is a standalone crate, outside the ZisK examples workspace, and does not use ziskos:

rustup target add wasm32-wasip1
cargo build --release --target wasm32-wasip1
# -> target/wasm32-wasip1/release/wasm-fibonacci.wasm

Running it​

Pass the .wasm file to ziskemu with -e / --elf. Despite the flag's name it accepts any guest format: ziskemu detects the magic bytes, transpiles the module and emulates it.

# default n = 10
ziskemu -e target/wasm32-wasip1/release/wasm-fibonacci.wasm
# -> fib(10) = 55

# n = 90 on stdin: an 8-byte length prefix followed by the 8-byte value
printf '\x08\x00\x00\x00\x00\x00\x00\x00\x5a\x00\x00\x00\x00\x00\x00\x00' > /tmp/n.bin
ziskemu -e target/wasm32-wasip1/release/wasm-fibonacci.wasm -i /tmp/n.bin
# -> fib(90) = 2880067194370816120

The prover backend and the ROM setup reach the same program2rom dispatcher, so format detection does not depend on the tool. Building is the exception: cargo-zisk build only produces RISC-V guests, so you build WASM guests with the stock toolchain as shown above.

See the ziskemu CLI reference for the other options.

WASI mapping​

The transpiler ships a minimal wasi_snapshot_preview1 runtime, generated as ZisK routines. It covers what a stock Rust, C or Go program needs to read stdin and write stdout. Imports from any other module are rejected at transpile time.

WASI functionBehaviour in ZisK
fd_read (fd 0, stdin)Reads from the ZisK input region (length-prefixed at INPUT_ADDR), advancing a cursor. Returns 0 bytes at end of input.
fd_write (fd 1 / 2, stdout / stderr)Writes every byte to the UART console and mirrors the first 256 bytes into the public output region. Bytes beyond that reach the console only; the call still reports success.
proc_exitExit code 0 publishes the output and ends the run. A nonzero code prints wasm: guest exited with a non-zero status and traps, so the execution fails and is never proven.
args_*, environ_*Report no arguments and no environment variables.
clock_time_getA deterministic clock that advances 1 ms per call. It does not track real time.
random_getA fixed-seed, insecure generator. The first call prints WARNING: Using insecure random number generator.
fd_fdstat_get, fd_seek, fd_close, poll_oneoff, sched_yield, …Minimal stubs so that language runtimes can initialise.
Any other WASI functionAccepted at transpile time; fails with ENOSYS when called.

Every pointer a guest passes to a WASI call is bounds-checked against its linear memory. An out-of-range buffer fails the call with EFAULT.

Public output is 256 bytes

Only the first 256 bytes of stdout and stderr (32 × 64-bit words) become public output. Write the value you want the verifier to see first, and keep logs short or send them after it.

wasm2zisk​

wasm2zisk is the WebAssembly counterpart of the RISC-V transpiler (zisk-transpiler-riscv): it transpiles a .wasm guest and saves the ROM as an x86-64 NASM file for the Assembly emulator. It is a developer tool in the zisk-transpiler-wasm crate, run from a ZisK checkout:

cargo run --release -p zisk-transpiler-wasm --bin wasm2zisk -- \
target/wasm32-wasip1/release/wasm-fibonacci.wasm /tmp/fib.asm --gen=0

The last argument picks the generation method: --gen=0 (fast), --gen=1 (minimal traces), --gen=2 (ROM histogram) or --gen=7 (memory operations). You don't need it to run or prove a WASM guest.

Floating point and Go guests​

WebAssembly f32 / f64 operators are lowered onto the RISC-V soft-float library. This only works when the tool is built with the float feature. Without it, floating-point code fails at transpile time. A floating-point operator, such as the f64 loads and arithmetic a Rust guest using f64 compiles to, fails with wasm: unsupported operator: F64Load { … } (the operator named is the first one met). A floating-point value type in a function signature or local fails with wasm: floating-point types require the `float` feature.

Go's GOOS=wasip1 GOARCH=wasm output runs too, but the Go runtime executes f64 arithmetic even in integer-only programs, so it needs an emulator built with float:

cargo build --release -p ziskemu --features float
GOOS=wasip1 GOARCH=wasm go build -o /tmp/guest.wasm .
ziskemu -e /tmp/guest.wasm -i /tmp/input.bin # 8-byte LE length, data, zero-padded to 8

Limitations​

The transpiler validates the module first, then rejects valid but unsupported constructs with a clear error instead of miscompiling them:

AreaNot supported
ProposalsSIMD (v128), threads and shared memory, exception handling, GC types, 64-bit memories and tables.
Memories & tablesMore than one memory, or any table other than table 0.
SegmentsPassive data segments, and passive or expression element segments.
ImportsAnything outside wasi_snapshot_preview1, and non-function imports.
Floating pointf32 / f64 without the float feature.

The WASM machine also has fixed capacity limits:

ResourceLimit
Linear memory[0xA1000000, 0xBF000000), about 480 MB (7,680 pages of 64 KB).
Call stackAbout 16 MB, from 0xBFFE0000 down to the top of linear memory. Calls past it trap.
Globals8,192.
Table entries65,536.
Public output256 bytes of stdout / stderr.

A WASM guest has no route to ZisK's precompiles or zkvmcalls: it can only import WASI. All hashing and curve arithmetic therefore runs as plain instructions, which costs far more than in a RISC-V guest that uses ziskos. For performance-sensitive guests, prefer the RISC-V path.

Where to go next​

  • ZisK assembly covers the other non-RISC-V input, hand-written .zisk programs.