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 function | Behaviour 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_exit | Exit 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_get | A deterministic clock that advances 1 ms per call. It does not track real time. |
random_get | A 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 function | Accepted 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.
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:
| Area | Not supported |
|---|---|
| Proposals | SIMD (v128), threads and shared memory, exception handling, GC types, 64-bit memories and tables. |
| Memories & tables | More than one memory, or any table other than table 0. |
| Segments | Passive data segments, and passive or expression element segments. |
| Imports | Anything outside wasi_snapshot_preview1, and non-function imports. |
| Floating point | f32 / f64 without the float feature. |
The WASM machine also has fixed capacity limits:
| Resource | Limit |
|---|---|
| Linear memory | [0xA1000000, 0xBF000000), about 480 MB (7,680 pages of 64 KB). |
| Call stack | About 16 MB, from 0xBFFE0000 down to the top of linear memory. Calls past it trap. |
| Globals | 8,192. |
| Table entries | 65,536. |
| Public output | 256 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
.ziskprograms.