risc0-zkvm-platform

Platform definitions and syscalls for RISC Zero zkVM

risc0-zkvm-platform

The risc0-zkvm-platform crate provides low-level platform definitions, syscalls, and runtime components for the RISC Zero zkVM.

Installation

[dependencies]
risc0-zkvm-platform = "5.0.0"

Overview

This crate contains the foundational components needed for both guest and host code to interact with the zkVM platform. It defines syscalls, memory layout, and provides optional runtime components.

This is a low-level crate. Most users should use risc0-zkvm instead.

Feature Flags

rust-runtime · feature

Builds a Rust runtime for guest programs.

• Implies: export-libm, export-syscalls

entrypoint · feature

Provides the _start entrypoint for guest programs.

panic-handler · feature

Provides a panic handler for guest programs.

export-syscalls · feature

Exports syscall implementations.

export-libm · feature

Exports libm (math library) functions.

getrandom · feature

Enables getrandom implementation using sys_random syscall.

• Implies: export-getrandom
• Default: Panics when called

export-getrandom · feature

Exports a getrandom implementation (panics by default).

heap-embedded-alloc · feature

Uses embedded-alloc for heap allocation instead of the default bump allocator.

• Trade-off: Slower but reclaims freed memory

sys-getenv · feature

Enables the sys_getenv syscall.

sys-args · feature

Enables the sys_argc and sys_argv syscalls.

unstable · feature

Enables unstable/experimental features.

Constants

Memory

PAGE_SIZE · const

Size of a zkVM memory page.

pub const PAGE_SIZE: usize = 1024;

WORD_SIZE · const

Size of a zkVM machine word in bytes (32-bit architecture).

pub const WORD_SIZE: usize = 4;

File Descriptors

fileno · module

Standard IO file descriptors.

pub mod fileno {
    pub const STDIN: u32 = 0;
    pub const STDOUT: u32 = 1;
    pub const STDERR: u32 = 2;
    pub const JOURNAL: u32 = 3;
}

Functions

align_up

align_up · function

Aligns an address upwards to the specified alignment.

pub const fn align_up(addr: usize, align: usize) -> usize

Parameters:

• addr: Address to align
• align: Alignment (must be a power of 2)

Returns: Smallest aligned address >= addr

Example:

let aligned = align_up(1000, 1024); // Returns 1024

Syscalls

The crate provides the declare_syscall! macro for defining and calling syscalls.

declare_syscall!

declare_syscall! · macro

Declares a syscall interface.

declare_syscall!(
    SYS_READ,
    fn sys_read(fd: u32, buf: *mut u8, len: usize) -> usize
);

Standard Syscalls

The following syscalls are available:

I/O Syscalls

• sys_read(fd: u32, buf: *mut u8, len: usize) -> usize
• sys_write(fd: u32, buf: *const u8, len: usize)

Memory Syscalls

• sys_alloc_words(nwords: u32) -> *mut u32
• sys_alloc_aligned(bytes: u32, align: u32) -> *mut u8

Cryptographic Syscalls

• sys_sha_compress(digest: *mut [u32; 8], data: *const [u32; 16])
• sys_sha_buffer(digest: *mut [u32; 8], buf: *const u8, len: u32)
• sys_random(out: *mut u32, len: usize)

Control Flow Syscalls

• sys_halt()
• sys_pause()
• sys_verify(control_id: *const u32, claim: *const u32) -> u32

Proof-of-Work Syscalls

• sys_povw_preflight(job_id: u64, nonce: *const u32) -> u32
• sys_povw_prove(job_id: u64, nonce: *const u32)
• sys_povw_gen_nonce(nonce: *mut u32)

Memory Module

memory · module

Defines zkVM memory layout.

pub mod memory {
    pub const TEXT_START: u32 = 0x0020_0400;
    pub const STACK_TOP: u32 = 0x0800_0000;
    pub const HEAP_START: u32 = 0x0800_0000;
    pub const GUEST_MAX_MEM: u32 = 0x1000_0000;
}

Heap Module

heap · module

Heap allocator implementations (available with rust-runtime feature).

Allocators:

• Default: Bump allocator (fast, no deallocation)
• With heap-embedded-alloc: Linked-list allocator (slower, reuses memory)

Examples

Using Syscalls in Guest Code

use risc0_zkvm_platform::syscall::*;
use risc0_zkvm_platform::fileno;

// Write to stdout
let message = b"Hello from zkVM!\n";
unsafe {
    sys_write(
        fileno::STDOUT,
        message.as_ptr(),
        message.len(),
    );
}

// Read from stdin
let mut buffer = [0u8; 64];
let bytes_read = unsafe {
    sys_read(
        fileno::STDIN,
        buffer.as_mut_ptr(),
        buffer.len(),
    )
};

Memory Alignment

use risc0_zkvm_platform::{PAGE_SIZE, align_up};

let addr = 1000;
let page_aligned = align_up(addr, PAGE_SIZE);
assert_eq!(page_aligned, 1024);

Custom Runtime

You can build a custom runtime without depending on risc0-zkvm:

// In build.rs
use risc0_build::build_rust_runtime;

fn main() {
    let runtime_lib = build_rust_runtime();
    println!("cargo:rustc-link-lib=static={}", runtime_lib);
}

Links

• docs.rs
• GitHub
• Crate