Skip to main content

Input / Output (io)

The io module is the guest's only channel to the outside world. Inputs arrive as a sequential bytes written by the host and public outputs are committed into the proof during execution so they can be consumed after verification.

Overview​

ZisK guests execute inside a zkVM that has no operating system, no filesystem, no networking, and no environment. The only data that crosses into the guest is whatever the host wrote into the input region before execution started, and the only data the guest can publish is whatever it commits into the proof's public-output region. The io module is the interface for both directions. It provides four primitives that map directly onto the underlying memory regions:

DirectionTypedRaw
Readio::read<T>() -> Tio::read_slice<'a>() -> &'a [u8]
Commitio::commit(value: &T)io::commit_slice(buf: &[u8])
Input and output size limits

The input region is 2 GB at 0x1000_0000. Through cargo-zisk and the SDK the whole input stream can be at most 2 GB − 16 bytes (MAX_STDIN_SIZE). Standalone ziskemu has a smaller default: it rejects inputs larger than --max-input-mem (default 134217728, 128 MiB) minus 8 bytes, so raise that flag for bigger inputs. Every frame counts its 8-byte length header and its payload padded to a multiple of 8 bytes.

Public outputs are limited to 64 32-bit slots, 256 bytes in total. Committing past that traps with Maximum number of public outputs: 64. See Limits for the full memory map.

Reading inputs​

read<T>() -> T​

Deserializes the next value from the input stream into T using bincode 2 with bincode::config::standard() (variable-length integer encoding). The read order must match the order the values were written.

pub fn read<T: DeserializeOwned>() -> T

Internally this performs two reads from the input stream: first a u64 length header that says how many bytes the value occupies, then exactly that many payload bytes which are passed to bincode::serde::decode_from_slice(bytes, bincode::config::standard()) to reconstruct T. The host must encode the value the same way.

note

Reading past the end of the input stream panics the emulator (exit code 101). This also happens when the program is run with no input (-i omitted).

Parameters​

NameTypeDescription
Ttype parameterTarget type. Must implement serde::DeserializeOwned.

Returns​

TypeDescription
TThe deserialized value read from the input stream.

Example​

let data = io::read::<u64>();
let data: Vec<u8> = io::read();
warning

Read order must match write order exactly. A type mismatch produces a deserialization panic; a length mismatch is silent, leaving the next read out of sync


read_slice<'a>() -> &'a [u8]​

Returns the payload of the next input frame as a raw byte slice without deserializing it. Use this when the data is already in a binary format the guest can interpret directly, or when bincode adds unwanted overhead.

// In the guest (zkvm): a zero-copy borrow of the input region
pub fn read_slice<'a>() -> &'a [u8]

// Off-target (native execution): an owned copy
pub fn read_slice() -> Box<[u8]>

Internally this performs two reads from the input stream: first a u64 length header that says how many bytes the value occupies, then exactly that many payload bytes are read and returned raw.

note

Reading past the end of the input stream panics the emulator (exit code 101). This also happens when the program is run with no input (-i omitted).

Renamed

This function was previously read_input_slice. That name still exists as an alias, deprecated since 1.0.0-alpha, and forwards to read_slice; prefer read_slice in new code.

Returns​

TypeDescription
&[u8] (guest)Zero-copy borrow of the next input frame.
Box<[u8]> (native)Owned copy of the next input frame.

Example​

// Read a 32-byte digest written via stdin.write_slice on the host.
let digest = io::read_slice();
assert_eq!(digest.len(), 32);

// Reinterpret raw bytes without copying.
let words: &[u64] = unsafe {
core::slice::from_raw_parts(
digest.as_ptr() as *const u64,
digest.len() / 8,
)
};

Committing outputs​

commit(value: &T) -> ()​

Serializes value with bincode 2 (bincode::serde::encode_to_vec with bincode::config::standard()) and appends the bytes to the public output stream through commit_slice. Committed values are written into the proof and visible to the verifier. Integers use the variable-length encoding, so io::commit(&300u64) commits 3 bytes (fb 2c 01), not 8.

pub fn commit<T: Serialize>(value: &T)

Parameters​

NameTypeDescription
value&TReference to the value to commit. T must implement serde::Serialize.

Returns​

Nothing. The serialized bytes are appended to the public output byte stream.

Example​

MySummary must derive serde::Serialize, so this needs serde (with the derive feature) in the guest's dependencies.

#[derive(serde::Serialize)]
struct MySummary { ok: bool, count: u32 }

let result: u64 = compute(&input);
io::commit(&result);

let summary = MySummary { ok: true, count: 42 };
io::commit(&summary);
warning

The verifier reads public values in the same order they were committed. Two callers reading the same proof must agree on both the order and the type of each commit.


commit_slice(buf: &[u8]) -> ()​

The raw-bytes counterpart to commit. Appends buf to the public output byte stream, which is exposed as a sequence of 32-bit little-endian words. All commit and commit_slice calls append to one contiguous stream: a call that ends partway through a 32-bit slot leaves it open, and the next call continues filling it. Only the final partial word of the whole stream is zero-padded.

pub fn commit_slice(buf: &[u8])

Parameters​

NameTypeDescription
buf&[u8]Raw byte slice to write to the public output stream.

Returns​

Nothing. The bytes are appended to the stream; each 4 consecutive bytes of the stream form one little-endian u32 slot.

Example​

The first example uses the sha2 crate.

// Commit a digest (fills 8 slots exactly)
use sha2::{Digest, Sha256};
let digest: [u8; 32] = Sha256::digest(&input).into();
io::commit_slice(&digest);
// Partial slots are shared across calls
io::commit_slice(&[1, 2, 3]);
io::commit_slice(&[4]);
io::commit_slice(&[5, 6]);
io::commit_slice(&[7, 8, 9, 10]);
// Public outputs: 0x04030201 0x08070605 0x00000a09
warning

The verifier reads public values in the same order they were committed. Two callers reading the same proof must agree on both the order and the type of each commit.


Cursor controls​

Both directions are sequential: reads advance an input cursor and commits advance an output cursor. The input cursor can be rewound, which is useful in tests or when re-reading the input from the start. The output cursor cannot: committed public values are append-only.

read_input_reset() -> ()​

Reset the input cursor to the beginning so the next read / read_slice starts again from the first value. It lives at the crate root, not in io: call it as ziskos::read_input_reset().

pub fn read_input_reset()
Removed in 1.4.0-alpha

io::write_output_reset() no longer exists. Code that called it to discard committed values must be restructured to commit only once the values are final.