ZiskHints

ZiskHints is the in-memory carrier for the preprocessed precompile data the prover consumes during witness generation. Supplying hints lets the prover skip recomputing primitives such as SHA-256, Keccak-256, secp256k1 recovery, and BN254 / BLS12-381 pairings.

Overview

Hints are an auxiliary input channel, distinct from the standard input read by the guest with io::read*. The guest never sees hints directly; instead, the prover uses them to accelerate the witness for whichever precompile operations the guest invokes. Programs that do not use precompiles get nothing from enabling hints.

Two preconditions must line up:

1. The client must be built with the Assembly executor; the default emulator does not support hint-accelerated witness generation.
2. Setup must run with .with_hints() so the resulting verkey is compatible with hinted proofs.

Hints are then attached to the prove call with .hints(...) on the ProveRequest builder.

let client = ProverClient::embedded().assembly().build()?;
client.setup(&PROGRAM).with_hints().run()?.await?;

let hints = ZiskHints::from_file("hints.bin")?;
let proof = client
    .prove(&PROGRAM, stdin)
    .hints(hints)
    .run()?
    .await?;

ZiskHints and ZiskStream both implement Into<HintsSource>, so hints can be either fully buffered (ZiskHints) or live-streamed (ZiskStream).

---

Type

pub struct ZiskHints { /* private */ }

ZiskHints is Default (an empty buffer) and implements Into<HintsSource>. It does not expose mutable write methods — construct it from the source you already have, or use the streaming counterpart when hints need to be pushed incrementally.

---

Constructors

new

Create an empty in-memory hints buffer. Mostly useful as a placeholder; in practice the buffer is populated through one of the constructors below.

pub fn new() -> ZiskHints

---

memory

Create hints from raw bytes. Use when the hints already exist as a byte slice (for example, produced by an offline tool).

pub fn memory(data: impl AsRef<[u8]>) -> ZiskHints

Parameters

Name	Type	Description
data	impl AsRef<[u8]>	The raw hints bytes.

---

from

Create hints from a serializable Rust value. Bincode-serializes the value into the hints buffer.

pub fn from<T: Serialize>(data: &T) -> ZiskHints

Parameters

Name	Type	Description
data	&T: Serialize	The value to serialize as hints.

---

from_file

Load hints from a file on disk.

pub fn from_file(path: impl AsRef<Path>) -> Result<ZiskHints>

Parameters

Name	Type	Description
path	impl AsRef<Path>	Path to the hints file.

Errors

Returns an error if the file does not exist or is not accessible.

Example

let hints = ZiskHints::from_file("hints.bin")?;

---

from_uri

Load hints from a URI. Supports file://, unix://, and quic:// schemes, so the same call site can take buffered or transport-backed hints depending on the URI you pass.

pub fn from_uri<S: Into<String>>(uri: S) -> Result<ZiskHints>

Parameters

Name	Type	Description
uri	impl Into<String>	file://, unix://, or quic:// hints URI.

Example

let hints = ZiskHints::from_uri("file://hints.bin")?;

---

HintsSource

HintsSource is the enum the prover accepts when you attach hints to a ProveRequest.

pub enum HintsSource {
    Hints(Box<ZiskHints>),
    Stream(Box<ZiskStream>),
}

Variant	Carries	Use when
Hints	ZiskHints	Hints are fully materialized in memory or a file.
Stream	ZiskStream	Hints are produced live alongside the prover.

Both ZiskHints and ZiskStream implement From into HintsSource, so either type can be passed directly to .hints(...):

// In-memory or file-backed
client.prove(&PROGRAM, stdin)
    .hints(ZiskHints::from_file("hints.bin")?)
    .run()?;

// Live-streamed
let hints_stream = ZiskStream::unix();
client.prove(&PROGRAM, stdin)
    .hints(hints_stream.clone())
    .run()?;

Stream hints when the producer runs alongside the prover and the full payload would otherwise have to be materialized before proving starts.

---

Setup-time wiring

A verkey produced without .with_hints() will not accept a hinted prove call, and a verkey produced with .with_hints() expects hints to be attached when proving. Setup and prove must agree.

use zisk_sdk::ProverClient;

let client = ProverClient::embedded()
    .assembly()
    .build()?;

client.setup(&PROGRAM).with_hints().run()?.await?;

---

When hints are worth enabling

Hints accelerate witness generation for the precompile suite — SHA-256, Keccak-256, BLAKE2b, secp256k1 / secp256r1 ECDSA recovery and verification, BN254 and BLS12-381 pairings, modular exponentiation, KZG verification. The bigger the share of a guest's cost that comes from these primitives, the bigger the win.

For programs that do not call any precompile (or call them rarely), the cost of producing and shipping the hints outweighs the savings. The defaults — no .with_hints(), no .hints(...) — are the right choice in that case.