Skip to main content

ZisK assembly

ziskasm is ZisK's own assembly language and toolchain. You can write .zisk programs directly against the ZisK ISA, skipping the Rust → RISC-V → ZisK path. The same toolchain builds the ZisK library, the hand-written routines that RISC-V, C and C++ guests reach through zkvmcalls. This page is an overview. The full specifications live in the ZisK repository and are linked throughout.

What ziskasm is​

A .zisk file is a list of ZisK instructions in the (c, flag) = op(a, b) shape. The assembler parses it and builds a ZiskRom directly, using the same instruction encoder as the RISC-V transpiler, so the emulator and prover see no difference between an assembled and a transpiled ROM.

A short excerpt from the doubler-min example, which doubles every u64 in the input:

define INPUT_COUNT 0x10000008 ; address of N (the value count)
define INPUT_VALUES 0x10000010 ; address of value[0]
define OUTPUT_ADDR 0xa0410000 ; address of result[0]

main:
copyb(0, [INPUT_COUNT]) -> r6 ; r6 = N
copyb(0, INPUT_VALUES) -> r10 ; r10 = input pointer
copyb(0, OUTPUT_ADDR) -> r11 ; r11 = output pointer
copyb(0, 0) -> r5 ; r5 = i = 0
eq(r6, 0), j(_return) ; nothing to do when N == 0

loop:
copyb(r10, 8[a + 0]) -> r7 ; r7 = mem[r10]
add(r7, r7) -> r8 ; r8 = 2 * r7
copyb(r11, r8) -> 8[a + 0] ; mem[r11] = r8
...

The language includes:

  • definitions (define), labels, and const / RAM data declarations;
  • ifdef / ifndef conditional compilation;
  • the pseudo-instructions call, ret, jump, ret_to_bios and push / pop.

If a program defines no _start, the assembler synthesises a launcher around its main (or _zisk_main) label, so a program can be just its own code.

DocumentWhat it covers
ziskasm/README.mdDesign, architecture, examples and status of the toolchain.
ziskasm/ziskasm.mdThe language specification: registers, sources, storage, jumps, data, pseudo-instructions, entry point.
ziskasm/ziskbin.mdThe ziskbin binary format for shipping a built ROM inside an ELF.
ziskasm/ziskcsr.mdThe CSR-sequence ABI that guests use to call accelerators and U256 functions.
ziskasm/zisklib.mdCalling ZisK-library routines from a Rust guest.
ziskasm/lang/c/README.mdThe C/C++ bindings and the libzisklib_c.a package.
note

The ziskasm README lists proving fidelity of standalone .zisk programs (beyond emulation) as a roadmap item. The ZisK-library routines that guests reach through zkvmcalls are part of the normal proving path.

Running a .zisk program​

ziskemu -z assembles and runs a single .zisk file or a directory of them. It is mutually exclusive with -e (ELF) and -r (ROM):

ziskemu -z ziskasm/examples/doubler-min -i ziskasm/examples/doubler/input.bin -c

In a directory, file order does not matter: the assembler places the file that defines _start first, so _start lands at 0x90000000. See the ziskemu CLI reference for the other flags.

The zisk2zisk binary is the .zisk counterpart of the RISC-V transpiler (zisk-transpiler-riscv). It takes the same arguments, except that the input may be a directory. It emits either x86-64 NASM for the Assembly emulator (--gen=0|1|2|7) or a ziskbin ELF (--elf):

cargo run -p zisk-asm --bin zisk2zisk -- ziskasm/examples/doubler out.asm --gen=0
cargo run -p zisk-asm --bin zisk2zisk -- ziskasm/examples/doubler doubler.elf --elf

The ziskbin container​

A ziskbin is a fully built ZiskRom, serialised compactly and wrapped in a minimal ELF. The ELF is marked with a private e_machine value (EM_ZISK) and carries the ROM in a .ziskrom section. Because it is still an ELF, it passes every ELF check in the pipeline. program2rom recognises the marker and decodes the ROM directly instead of transpiling it, so cargo-zisk execute, prove and ROM setup accept a ziskbin like any other guest.

The container also records which zkvmcalls the ROM uses, so tooling that depends on them (for example the random-seed and hints checks) keeps working on a prebuilt ROM.

zkvmcalls and the ZisK library​

The ZisK library is a set of hand-written .zisk routines in ziskasm/zisklib/:

  • the EF zkVM accelerators (Keccak-256, SHA-256, RIPEMD-160, secp256k1/r1, modexp, BN254, BLS12-381, …);
  • U256 arithmetic;
  • memory functions and the EVM JUMPDEST bitmap;
  • zkvm_random_u64.

The routines run as ordinary ZisK instructions and use precompiles directly, so they are provable without any new chip.

A guest reaches a routine through a zkvmcall: a csrs to a CSR in 0x850–0x8BF. The guest side comes in two forms.

FormGuest codeWhat the transpiler emits
ThunkA two-instruction stub, for example zkvm_modexp: csrs 0x856, x0; ret.A jump (no link) to ziskasm_zkvm_modexp in the ZisK-lib ROM. The routine reads a0..a7, returns in a0 and rets straight to the caller.
InlineOne csrs per pointer argument at the call site (argument k ≥ 1 on 0x8E0 + k − 1).The routine's body, expanded in place. It uses only the extra registers r32..r39 and the ZisK-lib RAM, so it clobbers no guest register.

Thunks suit long routines (one shared copy in ROM); inline calls suit short ones (no call overhead). The transpiler finds zkvmcalls by instruction, so the guest ELF may be stripped. It assembles the library and merges it into the ROM, at 0x97E00000, only when the guest makes at least one zkvmcall.

Rust guests get these routines through ziskos and the zisklib crate. See ziskos syscalls and, for example, Ed25519.

ZisK only

These CSR sequences mean something only under the ZisK transpiler. On any other RISC-V target they raise an illegal-instruction exception or do something unrelated, and they never compute the result. Don't run a guest built from them outside ZisK.

C and C++ guests​

ziskasm/lang/c is the C binding to the same library. It ships the EF zkVM standard headers:

  • zkvm_accelerators.h
  • zkvm_io.h
  • zkvm_u256.h (with an optional inline implementation in zkvm_u256_inline.h, selected by defining ZKVM_U256_INLINE)
  • zkvm_random.h

and ZisK's extensions to them:

  • zkvm_u256_le.h
  • zkvm_mem.h
  • zkvm_evm.h
  • zkvm_zisklib.h

It also builds the zisklib_c static library.

In a CMake project:

add_subdirectory(/path/to/zisk/ziskasm/lang/c zisklib_c)
target_link_libraries(my_guest PRIVATE zisklib_c)

package.sh stages a self-contained distribution for EF zkVM standard §9: the headers, lib/libzisklib_c.a and the guest linker script. A guest then builds with a plain RISC-V GCC:

riscv64-unknown-elf-gcc -march=rv64ima_zicsr -mabi=lp64 -mcmodel=medany \
-nostdlib -ffreestanding -O2 -Wl,--gc-sections \
-Idist/include -T dist/share/zisk/zisk_linker_script.ld \
-o guest.elf guest.c dist/lib/libzisklib_c.a

A few things set this archive apart from an ordinary static library:

  • It only works under ZisK. Every accelerator and I/O function is a zkvmcall thunk. The exceptions are _start and the mem* routines, which are real code.
  • It defines memcpy, memmove, memcmp and memset on the DMA precompiles. They always win symbol resolution, and a libc that also defines them causes a multiple-definition link error.
  • The linker script is required. _start depends on symbols only the script defines.
  • It is built rv64ima, not rv64imac. ZisK decodes the C extension only under the off-by-default compressed feature.
  • Use --gc-sections. Without it every thunk stays in the ELF, and the transpiler assembles the ZisK library even for a guest that calls none of it.

Where to go next​