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:
| Approach | What it costs |
|---|---|
| Cache the transpiled ZisK ROM | Disk I/O proportional to ROM size. Plus a versioning/invalidation story every time the transpiler changes. |
| Re-transpile from the RISC-V ELF | CPU 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:
| Input | Detected by | Handled by |
|---|---|---|
| WebAssembly module | \0asm | wasm2rom |
ziskbin ELF (ROM prebuilt by ziskasm) | ELF with e_machine == EM_ZISK | ziskbin2rom — decoded directly, no transpilation |
| RISC-V ELF | any other \x7fELF | elf2rom |
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.
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:
| ISA | Instruction width | Alignment |
|---|---|---|
| RV64IMA | 32 bits | 32-bit |
| RV64IMAC (with the C extension) | 16 or 32 bits | 16-bit |
| ZisK | variable | 8-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 class | How it transpiles |
|---|---|
| Most RV64IMA instructions | One ZisK instruction at the same address. The byte slots in between stay empty. |
| Atomic instructions | 2–4 ZisK instructions packed into the slots starting at the RISC-V instruction's address. |
| C-extension instructions | Usually one ZisK instruction; sometimes two when the 16-bit encoding implies more work than a single ZisK op can express. |
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 range | Kind | What the transpiler emits |
|---|---|---|
0x800–0x84F | Syscalls | The matching precompile opcode (Keccak-f, SHA-256, arith, curve ops…), proven by a specialized chip. |
0x850–0x8BF | zkvmcalls | A 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–0x8DF | fcalls | An 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
| From | To | Region |
|---|---|---|
0x1000 | 0x0FFFFFFF | ziskos ROM |
0x10000000 | 0x8FFFFFFF | Input data (2 GB) |
0x90000000 | 0x97FFFFFF | Program ROM (128 MB) |
0x98000000 | 0x9FFFFFFF | Stack guard (unmapped) |
0xA0000000 | 0xBFFFFFFF | RAM (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
| Address | Symbol | What's there |
|---|---|---|
0x1000 | ROM_ENTRY | Where execution starts. Jumps to the program launcher. |
0x1004 | ROM_EXIT | Where execution ends. Returning here halts the program. |
0x1008 | FLOAT_HANDLER_ADDR | Soft-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. |
0x1110 | Program launcher | Writes 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. |
0x90000000 | Program code | The transpiled guest. Execution ends with a syscall that returns control to the launcher's exit path. |
0x97E00000 | ZisK-lib ROM | Hand-written .zisk library routines (1 MB) that zkvmcalls jump into. Merged into the ROM only when the guest uses a zkvmcall. |
0x97F00000 | Float soft-library | The code the soft-float trampoline jumps into (1 MB). |
Inside the RAM region
| Address | Symbol | What's there |
|---|---|---|
0xA0000000 | RAM_ADDR / STACK_ADDR | The guest stack (4 MB), growing down from 0xA0400000. |
0xA0400000 | SYS_ADDR | ziskos system RAM (64 KB): 40 registers, UART at +0x200, float registers at +0x1000, CSRs at +0x8000. |
0xA0410000 | OUTPUT_ADDR | The buffer the guest writes its public outputs into (128 KB). After proving, the host reads from here. |
0xA0430000 | Program RAM | The guest's .data, .bss and heap. |
0xBFFC0000 | ZISKLIB_RAM_ADDR | Scratch space for the ZisK-lib routines (192 KB). |
0xBFFF0000 | Float soft-library RAM | Scratch 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.