Skip to main content

Transpilation

This page explains how the transpiler bridges a standard RISC-V ELF and the ZisK ISA. It covers why transpilation runs at the start of every emulation rather than being cached, how ZisK's 8-bit instruction alignment leaves room to expand awkward RISC-V instructions, a worked layout example, and the address map the transpiled ROM, input data, and RAM live in at runtime.

The ISA & processor page described the shape the ZisK processor expects every instruction in: c = op(a, b) with four specific-purpose registers. But the binary you compile with cargo-zisk build is still a standard RISC-V ELF — RV64IMA plus the Zba/Zbb/Zbs/Zbkb bit-manipulation extensions, the hardware-style ISA. Something has to bridge those two worlds, and that something is the transpiler.

Why transpile at runtime?​

Transpilation runs at the start of every emulation, not once and cached. That sounds expensive, but in practice it's no slower than reading a previously transpiled ZisK binary from disk:

ApproachWhat it costs
Cache the transpiled ZisK ROMDisk I/O proportional to ROM size. Plus a versioning/invalidation story every time the transpiler changes.
Re-transpile from the RISC-V ELFCPU time proportional to ELF size. Cheap enough to be unnoticeable. No cache invalidation, no stale-output footguns.

Re-transpiling is the path of least friction: the RISC-V ELF is already the canonical artifact (the verification key is anchored to its transpiled form), so making the in-memory ZisK ROM a deterministic function of it removes a whole category of "which file is the real one?" questions.

The output of the transpiler is a ZisK ROM: a map from program counter to ZisK instruction, ready for the emulation loop in ISA & processor → How an instruction is emulated to walk through.

Guest formats​

RISC-V ELF is the usual input, but not the only one. A single entry point, program2rom in zisk-transpiler-common, picks the transpiler from the file's magic bytes:

InputDetected byHandled by
WebAssembly module\0asmwasm2rom
ziskbin ELF (ROM prebuilt by ziskasm)ELF with e_machine == EM_ZISKziskbin2rom — decoded directly, no transpilation
RISC-V ELFany other \x7fELFelf2rom

The emulator, the prover and the ROM setup all go through this entry point, so every format is proven the same way. See WASM guests and ZisK assembly for the two non-RISC-V inputs.

note

The Riscv2zisk API of the zisk-transpiler-riscv crate is deprecated since 1.4.0. Depend on zisk-transpiler-common and use ZiskTranspiler (same methods) or program2rom instead.

Alignment​

The translation between the two ISAs is mostly 1:1 — one RISC-V instruction becomes one ZisK instruction — but a handful of RISC-V instructions don't have a single-instruction ZisK equivalent, and the alignment scheme is designed to absorb the slack:

ISAInstruction widthAlignment
RV64IMA32 bits32-bit
RV64IMAC (with the C extension)16 or 32 bits16-bit
ZisKvariable8-bit

ZisK's 8-bit alignment is the key choice. It means every RISC-V instruction's address — 32-bit aligned, so a multiple of 4 — has room for four ZisK instructions before colliding with the next one. That headroom is exactly what the awkward cases need:

RISC-V instruction classHow it transpiles
Most RV64IMA instructionsOne ZisK instruction at the same address. The byte slots in between stay empty.
Atomic instructions2–4 ZisK instructions packed into the slots starting at the RISC-V instruction's address.
C-extension instructionsUsually one ZisK instruction; sometimes two when the 16-bit encoding implies more work than a single ZisK op can express.
note

C-extension decoding is behind the transpiler's compressed feature, which is off by default. Without it, ZisK follows the EF RISC-V-target standard: every instruction is 32-bit aligned (IALIGN = 32), a 16-bit parcel is an illegal instruction, and a guest whose entry point is not 4-byte aligned is rejected at transpilation time. Guests built with cargo-zisk build target riscv64ima-zisk-zkvm-elf, which does not emit C instructions.

The same scheme also makes it impossible to confuse one program's transpiled code with another's: ZisK addresses match RISC-V addresses everywhere a base RISC-V instruction lives, so RISC-V branch targets land on real ZisK instructions without any remapping table.

Example​

Take a snippet of RISC-V code starting at address 0, with one instruction of each kind for illustration:

The transpiler walks each RISC-V instruction and emits one or more ZisK instructions at the same address, leaving the in-between slots empty:

ZisK instructions don't actually have a fixed bit length — the diagram represents them as 8-bit because that's the alignment granularity. The "no code" gaps are exactly the slack that absorbs the variable-width RISC-V layout.

Special CSRs: precompiles, zkvmcalls and fcalls​

A guest reaches ZisK-specific functionality by writing to CSR numbers that have no meaning on real RISC-V hardware. The transpiler recognises them by instruction (not by symbol, so they also work on stripped ELFs) and rewrites them:

CSR rangeKindWhat the transpiler emits
0x800–0x84FSyscallsThe matching precompile opcode (Keccak-f, SHA-256, arith, curve ops…), proven by a specialized chip.
0x850–0x8BFzkvmcallsA tail jump into a hand-written .zisk routine in the ZisK-lib ROM (0x97E00000). The routine reads a0..a7, returns in a0 and rets straight to the caller.
0x8C0–0x8DFfcallsAn unconstrained fcall hint. The function id is (csr − 0x8C0) * 32 + imm, so 1024 ids fit in the range.

A zkvmcall's guest side is a two-instruction thunk, for example:

zkvm_modexp:
csrs 0x856, x0
ret

The transpiler replaces the csrs with a jump (no link) to the routine, so the thunk's own ret is never reached. Some zkvmcalls are marked inline and are expanded at the call site instead. The ZisK library is assembled and merged into the ROM only when the guest uses at least one zkvmcall.

Fcalls compute a result outside the circuit and hand it back as free input. The guest must check whatever it gets back, since nothing constrains the value. See ZisK assembly for the ZisK library and ziskos syscalls for the guest-side API.

The address map​

The transpiled ROM doesn't live alone in the address space. The ZisK runtime (ziskos) reserves a few regions for its own plumbing — entry/exit handlers, input data, RAM. Knowing where each region sits is useful when reading a guest program's disassembly or chasing down a memory issue.

High level​

FromToRegion
0x10000x0FFFFFFFziskos ROM
0x100000000x8FFFFFFFInput data (2 GB)
0x900000000x97FFFFFFProgram ROM (128 MB)
0x980000000x9FFFFFFFStack guard (unmapped)
0xA00000000xBFFFFFFFRAM (512 MB)

The regions split cleanly by purpose: ziskos ROM is runtime support, the input region is where the host's input bytes are placed before execution begins, the program ROM is where the transpiled guest lives, and RAM is read/write working memory. The 128 MB between the ROM and RAM is deliberately left unmapped as a stack guard: any access to it traps, so a stack overflow fails the execution instead of silently corrupting memory.

Inside the ROM region​

AddressSymbolWhat's there
0x1000ROM_ENTRYWhere execution starts. Jumps to the program launcher.
0x1004ROM_EXITWhere execution ends. Returning here halts the program.
0x1008FLOAT_HANDLER_ADDRSoft-float trampoline. Saves the RISC-V register file, calls into the float library, restores the register file. Used whenever an F or D instruction is transpiled.
0x1110Program launcherWrites initial values for ROM and RAM globals, then jumps to the first guest instruction at 0x90000000. Also hosts the syscall trap handler, including the exit sequence that commits public outputs and jumps to ROM_EXIT.
0x90000000Program codeThe transpiled guest. Execution ends with a syscall that returns control to the launcher's exit path.
0x97E00000ZisK-lib ROMHand-written .zisk library routines (1 MB) that zkvmcalls jump into. Merged into the ROM only when the guest uses a zkvmcall.
0x97F00000Float soft-libraryThe code the soft-float trampoline jumps into (1 MB).

Inside the RAM region​

AddressSymbolWhat's there
0xA0000000RAM_ADDR / STACK_ADDRThe guest stack (4 MB), growing down from 0xA0400000.
0xA0400000SYS_ADDRziskos system RAM (64 KB): 40 registers, UART at +0x200, float registers at +0x1000, CSRs at +0x8000.
0xA0410000OUTPUT_ADDRThe buffer the guest writes its public outputs into (128 KB). After proving, the host reads from here.
0xA0430000Program RAMThe guest's .data, .bss and heap.
0xBFFC0000ZISKLIB_RAM_ADDRScratch space for the ZisK-lib routines (192 KB).
0xBFFF0000Float soft-library RAMScratch space the soft-float code uses (64 KB).

Where this picks up​

You now know what runs (the ISA) and what it runs on (the processor and the transpiled ROM). The next page, Arithmetization, opens up the layer beneath: how an execution becomes a system of polynomial constraints the prover can prove.