Hints Stream

The hints stream accelerates proof generation by offloading expensive operations outside the zkVM execution, then feeding the results back as verifiable data through a high-performance, parallel pipeline. Hints are preprocessed results that allow operations to be handled externally while remaining fully verifiable inside the VM. The system supports two categories of hints:

1. Precompile hints: Cryptographic operations (SHA-256, Keccak-256, elliptic curve operations, pairings, etc.) that are computationally expensive inside a zkVM.
2. Input hints: Data that needs to be passed to the zkVM as input during execution.

The system is designed around three core principles:

1. Pre-computing results outside the VM: The guest program emits hint requests describing the operation and its inputs.
2. Streaming results back: A dedicated pipeline processes these requests in parallel, maintaining order, and feeds results to the prover via shared memory.
3. Verifying inside the VM: The zkVM circuits verify that the precomputed results are correct, avoiding the cost of computing them inside the zkVM.

flowchart LR
    A["Guest program<br/><small>Emits hints request</small>"] --> B["ZiskStream"]
    B --> C["HintsProcessor<br/><small>Parallel engine</small>"]
    C --> D["StreamSink<br/><small>ASM emulator/file output</small>"]

Table of Contents

1. Hint Format and Protocol
2. Using Hints with the SDK
3. Hints in Distributed Execution
4. Custom Hint Handlers
5. Generating Hints in Guest Programs

1. Hint Format and Protocol

1.1. Hint Request Format

Hints are transmitted as a stream of u64 values. Each hint request consists of a header (1 u64) followed by data (N u64 values).

┌─────────────────────────────────────────────────────────────┐
│                         Header (u64)                        │
├·····························································┤
│      Hint Code (32 bits)           Length (32 bits).        │
├─────────────────────────────────────────────────────────────┤
│                        Data[0] (u64)                        │
├─────────────────────────────────────────────────────────────┤
│                        Data[1] (u64)                        │
├─────────────────────────────────────────────────────────────┤
│                             ...                             │
├─────────────────────────────────────────────────────────────┤
│                       Data[N-1] (u64)                       │
└─────────────────────────────────────────────────────────────┘
where N = ceil(Length / 8)

• Hint Code (upper 32 bits): Control code or Data Hint Type
• Length (lower 32 bits): Payload data size in bytes. The last u64 may contain padding bytes.

1.2. Control Hint Types:

The following control codes are defined:

• 0x00 (START): Start a new hint stream. Resets processor state and sequence counters. Must be the first hint in the first batch.
• 0x01 (END): End the current hint stream. The processor will wait for all pending hints to be processed before returning. Must be the last hint in its batch; only a CTRL_START may follow in a subsequent batch.
• 0x02 (CANCEL): [Reserved for future use] Cancel current stream and stop processing further hints.
• 0x03 (ERROR): [Reserved for future use] Indicate an error has occurred; stop processing further hints.

Control codes are for control only and do not have any associated data (Length should be zero).

1.3. Data Hint Types

For data hints, the hint code (32 bits) is structured as follows:

• Bit 31 (MSB): Pass-through flag. When set, the data bypasses computation and is forwarded directly to the sink.
• Bits 0-30: The hint type identifier (control, built-in, or custom code). (e.g., HINT_SHA256, HINT_BN254_G1_ADD, HINT_SECP256K1_RECOVER, etc.)

Example: A SHA-256 hint (0x0100) with a 32-byte input:

Header: 0x00000100_00000020
Data[0]: first_8_input_bytes_as_u64
Data[1]: next_8_input_bytes_as_u64
Data[2]: next_8_input_bytes_as_u64
Data[3]: last_8_input_bytes_as_u64

The same hint with the pass-through flag set (bit 31), forwarding pre-computed data directly to the sink without invoking the SHA-256 handler:

Header: 0x80000100_00000020

1.3.1 Stream Batching

The hints protocol supports chunking for individual hints that exceed the transport’s message size limit (currently 128 KB). Each message in the stream contains either a single complete hint or one chunk of a larger hint — hints are never combined in the same message.

When a hint exceeds the size limit, it must be split into multiple sequential chunks, each sent as a separate message. Each chunk includes a header specifying the total length of the complete hint, allowing the receiver to reassemble all chunks before processing. For example, a hint with a 300 KB payload would be split into three messages:

Message 2: Header (code + total length), Data[0..N] (second 128 KB chunk)
Message 3: Header (code + total length), Data[0..M] (final 44 KB chunk)

The receiver buffers incoming chunks and reassembles them based on the total length specified in the header before invoking the hint handler. This allows the system to handle arbitrarily large hints while respecting transport limitations.

1.3.2 Pass-Through Hints

When bit 31 of the hint code is set (e.g., 0x8000_0000 | actual_code), the hint is marked as pass-through:

• The data payload is forwarded directly to the sink without invoking any handler.
• No worker thread is spawned; the data is queued immediately in the reorder buffer.
• This is useful for pre-computed results that don't need processing.

1.4. Hint Code Types

Note: Custom hint codes can technically use any value not occupied by control or built-in codes. By convention, codes 0xA000-0xFFFF are recommended for custom use to avoid future conflicts as new built-in types are added. The processor does not enforce a range restriction — any unrecognized code is treated as custom.

1.4.1. Control Codes

Control codes manage the stream lifecycle and do not carry computational data:

1.4.2. Built-in Hint Types

1.4.3. Input Hint Type

Input hints allow passing data to the zkVM during execution. Unlike precompile hints that are processed by worker threads, input hints are forwarded directly to a separate inputs sink.

The input hint payload format is:

• First 8 bytes: Length of the input data (as u64 little-endian)
• Remaining bytes: The actual input data, padded to 8-byte alignment

Input hints are not processed by the parallel worker pool; instead, they are immediately submitted to the inputs sink for consumption by the zkVM.

1.4.4. Custom Hint Types

Custom hint types allow users to define their own hint handlers for application-specific logic. Users can register custom handlers via the HintsProcessor builder API, providing a mapping from hint code to a processing function (see Custom Hint Handlers). By convention, codes in the range 0xA000-0xEFFFF are recommended for custom use to avoid conflicts with current and future built-in types. If a data hint is received with an unregistered code, the processor returns an error and stops processing immediately.

1.5. Stream Protocol

A valid hint stream follows this protocol:

CTRL_START                          ← Reset state, begin stream
  [Hint_1] [Hint_2] ... [Hint_N]   ← Data hints (precompile, input, or custom)
CTRL_END                            ← Wait for completion, end stream

2. Consuming Hints

Once a guest program has produced a hints binary file (see Section 5), you can feed it to the prover either programmatically through the ZisK SDK or via the ZisK CLI.

Note: Hints are only supported with the Assembly executor. The emulator-based executor does not use the hints pipeline.

2.1 SDK

Load the file with ZiskHints::from_file and pass it to .hints(...) on the executor:

use anyhow::Result;
use zisk_sdk::{ExecutorKind, GuestProgram, ProverClient, ZiskStdin, ZiskHints};

#[tokio::main]
async fn main() -> Result<()> {
    let elf_path = "hints/example/zec-reth.elf";
    let program = GuestProgram::from_uri(elf_path)?;

    let hints_path = "hints/example/24654300_hints.bin";
    let hints = ZiskHints::from_file(hints_path)?;

    let client = ProverClient::embedded()
        .executor(ExecutorKind::Assembly)
        .build()?;

    client.upload(&program).run()?;
    client.setup(&program).with_hints().run()?.await?;

    let result = client
        .execute(&program, ZiskStdin::new())
        .hints(hints)
        .executor(ExecutorKind::Assembly)
        .run()?
        .await?;

    println!(
        "Program executed successfully: {} cycles in {:.2?} ms",
        result.get_execution_steps(),
        result.get_execution_time()
    );

    Ok(())
}

Notes:

• Setup must be run with .with_hints() so the assembly ROM is generated with hint support enabled. Without it, the prover will not consume the hints stream.
• ZiskHints::from_file loads the binary produced by the guest's hint generation. The returned value can be reused across multiple .execute(...) / .prove(...) calls.
• The same pattern works for prove, verify-constraints, and stats operations exposed by ProverClient.

A complete runnable example is available at examples/hints/host/src/main.rs.

2.2 CLI

Four cargo-zisk commands accept a --hints flag pointing to the hints file: execute, prove, verify-constraints, and stats. Pass the path with the file:// scheme:

--hints file://path      → File stream reader

Example:

cargo-zisk prove --elf program.elf --hints file:///abs/path/hints.bin

--hints is mutually exclusive with --inputs (-i): if you provide hints, the inputs are recovered from the hint stream itself rather than from a separate input file.

3. Hints in Distributed Execution

In the distributed proving system, hints are received by the coordinator and broadcasted to all workers via gRPC. The coordinator runs a relay that validates incoming hint messages, assigns sequence numbers for ordering, and dispatches them to workers asynchronously. Workers buffer incoming messages and reorder them by sequence number before processing. The processed hints are then submitted to the sink in the correct order. There is another mode where workers can load hints from a local path/URI instead of streaming from the coordinator, which is useful for debugging.

3.1. Architecture

flowchart TD
    A["Guest program<br/><small>Emits hints request</small>"] --> B

    subgraph H["Coordinator"]
        B["ZiskStream"]
        B --> C["Hints Relay<br/><small>Validates<br>Broadcast to all workers (async)</small>"]
    end

    C --> E["Worker 1<br/><small>Stream incoming hints + Reorder</small>"]
    C --> F["Worker 2<br/><small>Stream incoming hints + Reorder</small>"]
    C --> G["Worker N<br/><small>Stream incoming hints + Reorder</small>"]

    E --> E1["HintsProcessor<br/><small>Parallel engine</small>"]
    E1 --> E2["StreamSink<br/><small>ASM emulator/file output</small>"]

    F --> F1["HintsProcessor<br/><small>Parallel engine</small>"]
    F1 --> F2["StreamSink<br/><small>ASM emulator/file output</small>"]

    G --> G1["HintsProcessor<br/><small>Parallel engine</small>"]
    G1 --> G2["StreamSink<br/><small>ASM emulator/file output</small>"]

    style H fill:transparent,stroke-dasharray: 5 5

When the coordinator receives a hint request from the guest program, it parses the incoming u64 stream, validates control codes, assigns sequence numbers for ordering, and broadcasts the data to all workers.

Three message types are sent over gRPC to workers:

Each worker receives the stream of hints, buffers them if they arrive out of order, and sends them to the HintsProcessor for parallel processing. The HintsProcessor ensures that results are submitted to the sink in the original order.

3.2. Hints Mode Configuration

When calling the coordinator with .hints() prepares to receive hints from the coordinator. A hints system can be configured in two ways:

• Streaming mode: Workers receive hints from the coordinator via gRPC. This is the default and recommended mode for production, as it allows real-time processing of hints as they are generated.
• Path mode: Workers load hints from a local path/URI. This is useful for debugging or when hints are pre-generated and stored in a file. In this mode, the coordinator does not send hints to workers; instead, each worker reads the hints directly from the specified path.

3.2.1 Coordinator Hints Streaming Mode

The transport for the live hints stream is chosen on the SDK side by constructing a ZiskStream and passing it as the hints source on the execute/prove call.

Example launching a prove job with hints streamed over a Unix socket:

use anyhow::Result;
use zisk_sdk::{ExecutorKind, GuestProgram, ProverClient, ZiskStdin, ZiskStream};

#[tokio::main]
async fn main() -> Result<()> {
    let program = GuestProgram::from_uri("hints/example/zec-reth.elf")?;

    let client = ProverClient::remote("http://127.0.0.1:7000").build()?;
    let hints = ZiskStream::unix();

    let prove_handle = client
        .prove(&program, ZiskStdin::new())
        .hints(hints.clone())
        .executor(ExecutorKind::Assembly)
        .run()?;

    let proof = prove_handle.await?;

    Ok(())
}

Switching transports is a one-line change at the call site — replace ZiskStream::unix() with ZiskStream::grpc() or ZiskStream::quic("quic://0.0.0.0:0").

3.2.2 Worker Hints non-Streaming Mode

Non-streaming mode is also selected from the SDK call. Instead of constructing a ZiskStream, build a ZiskHints from a pre-generated file (or in-memory bytes) and pass it to .hints(...). The coordinator skips broadcasting in this case — each worker loads the hints directly from the URI baked into the ZiskHints value. This is useful for debugging or when hints are pre-generated.

Example launching a prove job that loads hints from a file:

use anyhow::Result;
use zisk_sdk::{ExecutorKind, GuestProgram, ProverClient, ZiskStdin, ZiskHints};

#[tokio::main]
async fn main() -> Result<()> {
    let program = GuestProgram::from_uri("hints/example/zec-reth.elf")?;

    let client = ProverClient::remote("http://127.0.0.1:7000").build()?;
    let hints = ZiskHints::from_file("/var/lib/zisk/hints/24654300_hints.bin")?;

    let proof = client
        .prove(&program, ZiskStdin::new())
        .hints(hints)
        .executor(ExecutorKind::Assembly)
        .run()?
        .await?;

    Ok(())
}

The same ZiskHints value can be reused across multiple .execute(...) / .prove(...) calls. As with streaming mode, no coordinator or worker flags are required to switch between sources — the SDK call decides.

4. Custom Hint Handlers

Register custom handlers via the builder pattern:

#![allow(unused)]
fn main() {
let processor = HintsProcessor::builder(my_sink)
    .custom_hint(0xA000, |data: &[u64]| -> Result<Vec<u64>> {
        // Custom processing logic
        Ok(vec![data[0] * 2])
    })
    .custom_hint(0xA001, |data| {
        // Another custom handler
        Ok(transform(data))
    })
    .build()?;
}

Requirements:

• Handler function must be Fn(&[u64]) -> Result<Vec<u64>> + Send + Sync + 'static.
• Custom hint codes should not conflict with built-in codes (0x0000-0x0700). By convention, use codes in the range 0xA000-0xFFFF.

5. Generating Hints in Guest Programs

To generate hints from the guest program you need to follow these steps and requirements:

1. Emit hint requests: Patch your code or dependent crates to call the external FFI Hints helper functions that generate the hints input data required later by the HintsProcessor. See FFI Hints Helper Functions for the list of available built-in FFI Hints helper functions, or Custom Hints Generation to learn how to generate custom hints from the guest program.
2. Add the ziskos crate to your guest Cargo.toml.
3. Initialize and finalize the hint stream: Call the hints init and close functions immediately before and after the section of code that executes precompile logic.
4. Enable hints at compile time: Compile your guest program with RUSTFLAGS='--cfg zisk_hints' for the native target to activate hint code generation and FFI helper functions in the ziskos crate.
5. Ensure deterministic execution: Verify that both the native execution that generates hints and the guest compiled for the zkvm/zisk target execute deterministically and produce/consume hints in the exact same order. See Deterministic Execution Requirement.

To illustrate these steps, consider the zec-reth guest program, which executes and verifies Ethereum Mainnet blocks using the ZisK zkVM:

https://github.com/0xPolygonHermez/zisk-eth-client/tree/main-reth/bin/guest

5.1 Emit Hint Requests

zec-reth relies on reth crates, which expose a Crypto trait that allows a guest program to override precompile implementations. This enables zkVM-optimized implementations while also emitting hints so the computation can be performed outside the zkVM.

For example, the BN254 elliptic curve addition (bn254_g1_add) implementation for the Crypto trait can be found here:

https://github.com/0xPolygonHermez/zisk-eth-client/blob/86b71b39d35efb9894696cab115a1177f3e47dbf/crates/guest-reth/src/crypto/impls.rs#L87

In that file, two target-specific implementations are provided: one for zkvm/zisk and one for native (non-zkVM) targets. When compiling with --cfg zisk_hints for the native target, the zkVM-specific implementation emits a hint request using the FFI helper:

#![allow(unused)]
fn main() {
#[cfg(zisk_hints)]
unsafe {
    pub fn hint_bn254_g1_add(p1: *const u8, p2: *const u8);
}
}

This call generates the hint input data using the exact input values that will later be used by the ZisK zkVM when executing the zkvm/zisk target code. This hint input data is consumed later by the HintsProcessor, allowing the bn254_g1_add computation to be performed outside the zkVM while remaining fully verifiable inside the circuit.

After the hint generation, execution continues in the native target code to compute the bn254_g1_add result.

From the guest program, we generate hints containing the input data for the corresponding zisklib functions (in this example, the bn254_g1_add_c function). These zisklib functions may internally invoke one or more precompiles to produce the final result.

When the hints are processed by the HintsProcessor, it executes the same zisklib function using the implementation code for the zkvm/zisk target. This produces the exact precompile results expected when executing the guest ELF inside the zkVM.

As a result, for each zisklib function invocation, the HintsProcessor may generate one or more precompile hint results corresponding to the precompile inputs originally emitted by the guest.

5.2 Initialize/Finalize Hint Stream

When using the ziskos::entrypoint!(main) macro, hint generation is initialized and finalized automatically around your guest entry function. You only need to compile with --cfg zisk_hints (see 5.3) and, optionally, set environment variables to control the output paths.

The macro expands to roughly:

fn main() {
    zkvm_init();         // initialize hints
    super::ZISK_ENTRY();  // your guest entry function
    zkvm_deinit();       // closes hints
}

zkvm_init and zkvm_deinit are also exposed as extern "C" symbols so they can be called from C guest programs (see 5.7 Using Hints from C Guest Programs).

5.2.1 Environment Variables

The ./tmp/ directory is created automatically if it does not exist.

5.2.2 Manual API

If you need finer control (e.g., streaming hints over a Unix socket, configuring a debug file, providing a synchronization signal to the host), call the lower-level functions directly instead of relying on the entrypoint! macro.

#![allow(unused)]
fn main() {
pub fn init_hints_file(hints_file_path: PathBuf, ready: Option<oneshot::Sender<()>>) -> Result<()>
}

Stores the generated hints in the file specified by hints_file_path.

#![allow(unused)]
fn main() {
pub fn init_hints_socket(
    socket_path: PathBuf,
    debug_file: Option<PathBuf>,
    write_flush_threshold: Option<usize>,
    ready: Option<oneshot::Sender<()>>,
) -> Result<()>
}

Sends the hints through the Unix socket specified by socket_path.

• The optional debug_file stores a copy of the hints sent through the socket, useful for later debugging.
• The optional write_flush_threshold controls the buffered-write flush size; None uses the default.
• The optional ready parameter can be used for synchronization with the host when the guest is executed in a separate thread to generate hints in parallel. It signals ready when the writer is ready to start sending hints over the socket.

To close hints generation:

#![allow(unused)]
fn main() {
pub fn close_hints() -> Result<()>
}

Place these calls under #[cfg(zisk_hints)] so they are only compiled into the native target used for hints generation:

#![allow(unused)]
fn main() {
#[cfg(zisk_hints)]
{
    // Initialization / finalization code
    ...
}
}

You can review how hints generation is initialized and finalized in the zec-reth guest here:

https://github.com/0xPolygonHermez/zisk-eth-client/blob/main-reth/bin/guest/src/main.rs

5.3 Enable Hints at Compile Time

Once the guest program is set up to generate hints for the native target, it must be compiled with the zisk_hints configuration flag enabled:

RUSTFLAGS='--cfg zisk_hints' cargo build --release

After compiling, executing the guest program will generate the hints. By default — when relying on the entrypoint! macro — the binary file is written to ./tmp/hints.bin; set ZISK_HINTS_OUTPUT to override the path. If you used the manual API instead, the file/socket location follows what was passed to init_hints_file/init_hints_socket.

If a hints file was generated, it can be consumed using the --hints flag in the cargo-zisk commands that support hints (as explained in Hints in CLI Execution).

If you want to display metrics in the console about the number of hints generated during native guest execution, you can additionally compile the guest with the --cfg zisk_hints_metrics flag.

To enable hint support when executing the guest inside the zkVM (ELF guest), you must pass the --hints flag when generating the assembly ROM using the cargo-zisk rom-setup command.

NOTE: Hint processing is not supported when executing the guest ELF file in emulation mode.

5.4 Deterministic Execution Requirement

An important requirement of the hints generation flow is that the native execution that generates the hints must be fully deterministic and always produce hints in the exact same order.

Furthermore, the order of hints generated during native execution must match the order in which the guest program compiled for the zkvm/zisk target expects to receive them. Since the zkVM execution is also deterministic, any divergence in hint ordering between native execution and zkVM execution will result in incorrect behavior.

To guarantee deterministic hint generation, the code paths that directly or indirectly generate hints must avoid:

• The use of threads or parallel execution.
• Data structures such as HashMap (or any structure based on randomized hash seeds) when iterated in loops that directly or indirectly call precompile/hint functions.

Using threads or iterating over non-deterministically ordered data structures may cause the hint generation order to vary between runs, breaking the required alignment between native and zkVM executions.

5.5 FFI Hints Helper Functions

5.6 Custom Hints Generation

To extend the built-in hints, you can generate custom hints for new operations. The first step is to register the new hint in the HintsProcessor, as explained in section Custom Hint Handlers. Once the hint is registered, you can generate hints for it from the guest program using the following FFI function:

#![allow(unused)]
fn main() {
fn hint_custom(hint_id: u32, data_ptr: *const u8, data_len: usize, is_result: u8);
}

and following the same guidelines described for the built-in FFI hint helper functions.

5.7 Using Hints from C Guest Programs

The ziskos crate is published as both an rlib and a staticlib, so C guest programs can link against the resulting .a archive and call the hint lifecycle functions through the C ABI. Two symbols are exposed:

extern void zkvm_init(void);
extern void zkvm_deinit(void);

zkvm_init initializes the hint stream and zkvm_deinit finalizes it. They are no-ops when compiled without --cfg zisk_hints, so the same C code works for both native (hint generation) and zkVM target builds without modification.

A minimal C guest program looks like:

extern void zkvm_init(void);
extern void zkvm_deinit(void);

int main(void) {
    zkvm_init();

    // Guest logic, including any FFI hint calls
    // (hint_sha256, hint_keccak256, hint_input_data, ...)

    zkvm_deinit();
    return 0;
}

When linking the C guest against ziskos for native hint generation, the same environment variables described in 5.2.1 (ZISK_HINTS_OUTPUT, ZISK_INPUT_FILE) control the file paths used by zkvm_init and the input reader.

The FFI hint helper functions listed in 5.5 FFI Hints Helper Functions are all extern "C" and use the same signatures from C — declare them with extern in your C source and link against the same ziskos archive.