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:
| Direction | Typed | Raw |
|---|---|---|
| Read | io::read<T>() -> T | io::read_slice<'a>() -> &'a [u8] |
| Commit | io::commit(value: &T) | io::commit_slice(buf: &[u8]) |
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.
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
| Name | Type | Description |
|---|---|---|
T | type parameter | Target type. Must implement serde::DeserializeOwned. |
Returns
| Type | Description |
|---|---|
T | The deserialized value read from the input stream. |
Example
let data = io::read::<u64>();
let data: Vec<u8> = io::read();
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.
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).
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
| Type | Description |
|---|---|
&[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
| Name | Type | Description |
|---|---|---|
value | &T | Reference 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);
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
| Name | Type | Description |
|---|---|---|
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
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()
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.