ProverClient
ProverClient is the entry-point namespace from which you obtain a
configured client for the ZisK proving pipeline. Call
ProverClient::embedded() for an in-process client or
ProverClient::remote(url) for one that talks to a coordinator,
finalize the returned builder with .build(), and use the resulting
EmbeddedClient or RemoteClient to drive setup, execute,
prove, upload, and wrap_proof. Each call returns a request
builder that you configure and submit with .run(), yielding a
JobHandle that you .await to collect the result.
Overview
ProverClient itself is a zero-sized namespace struct exposing two
constructors. The actual work happens on the typed clients the
constructors produce:
pub struct ProverClient;
impl ProverClient {
pub fn embedded() -> EmbeddedClientBuilder;
pub fn remote(url: impl Into<String>) -> RemoteClientBuilder;
}
Both clients expose the same pipeline (setup, execute, prove,
upload, wrap_proof, and aggregate_proofs) with identical
signatures.
A typical proving run looks like this:
use zisk_sdk::{ProverClient, ZiskStdin};
let client = ProverClient::embedded().build()?;
client.setup(&PROGRAM).run()?.await?;
let stdin = ZiskStdin::new();
stdin.write(&42u32);
let result = client.prove(&PROGRAM, stdin).run()?.await?;
result.save_proof("./proof.bin")?;
This page documents the ProverClient namespace and the two backend
clients.
ProverClient
The ProverClient struct is purely a namespace; it is never
instantiated. Its two static-style methods return builders for the
two backend kinds:
pub struct ProverClient;
impl ProverClient {
pub fn embedded() -> EmbeddedClientBuilder;
pub fn remote(url: impl Into<String>) -> RemoteClientBuilder;
}
For the full configuration surface returned by each constructor (executor selection, GPU, key paths, timeouts, runtime options) see Client builders.
embedded
Create a builder for an in-process client.
pub fn embedded() -> EmbeddedClientBuilder
Defaults to the emulator executor and CPU device.
use zisk_sdk::ProverClient;
// Default: emulator + CPU
let client = ProverClient::embedded().build()?;
remote
Create a builder targeting a remote proving coordinator at the given URL.
pub fn remote(url: impl Into<String>) -> RemoteClientBuilder
| Parameter | Type | Description |
|---|---|---|
url | impl Into<String> | Full base URL of the remote coordinator. |
use std::time::Duration;
use zisk_sdk::ProverClient;
let client = ProverClient::remote("http://coordinator:50051")
.build()?;
EmbeddedClient & RemoteClient
Both clients implement the same pipeline surface with identical
method signatures. EmbeddedClient is constructed by
EmbeddedClientBuilder::build() and runs the prover in-process;
RemoteClient is constructed by RemoteClientBuilder::build() and
delegates to a coordinator over gRPC.
pub struct EmbeddedClient { /* ... */ }
pub struct RemoteClient { /* ... */ }
The pipeline operations below apply to both clients, with a few backend-specific exceptions:
| Feature | Available on |
|---|---|
verify_constraints | EmbeddedClient only (extension trait) |
.run_sync() | EmbeddedClient only |
setup_by_id | RemoteClient only |
.metadata(...) | RemoteClient requests only |
Methods
Each method takes the program and an input source by reference and
returns a request builder. Configure with the setters listed below
(all optional), then submit with one of two finishers — .run() for
async code, .run_sync() when you don't have an async runtime. See
Submitting: run vs run_sync for the
difference.
Submitting: run vs run_sync
Every operation builder offers two finishers:
| Finisher | Returns | Use when |
|---|---|---|
.run() | Result<JobHandle<T>> | You are in an async context. .await the handle to get T; it also exposes .cancel()/.job_id(). |
.run_sync() | Result<T> | You have no async runtime. Blocks until the job completes and returns the result directly. |
// Async — await the JobHandle
let result = client.prove(&PROGRAM, stdin.clone()).run()?.await?;
// Sync — blocks, returns the result directly (no .await)
let result = client.prove(&PROGRAM, stdin).run_sync()?;
.run_sync() is available on setup, execute, prove, and
wrap_proof. verify_constraints and aggregate_proofs offer only
.run().
.run_sync() is implemented for EmbeddedClient only.
RemoteClient is async-only: submit remote jobs with .run() and
.await the returned JobHandle. Calling .run_sync() on a remote
client is a compile-time error.
upload is already synchronous — .run() returns UploadResult
directly, with no JobHandle and no .run_sync() variant.
upload
Register the ELF with the coordinator. The target is a
&GuestProgram or a &Recurser (anything Into<UploadTarget>). On EmbeddedClient this is
a no-op since the ELF is already local. The builder takes no
setters. Returns an UploadResult directly — not a JobHandle,
because uploading is a synchronous accept/reject with no
long-running job to watch.
pub fn upload<'a, T: Into<UploadTarget<'a>>>(&'a self, target: T)
-> UploadRequest<'a, Self>;
let upload = client.upload(&program).run()?;
println!("registered hash_id: {}", upload.hash_id());
setup
Derive the proving key for the program. The target is a
&GuestProgram or a &Recurser (anything Into<SetupTarget>).
Returns Result<JobHandle<SetupResult>>.
pub fn setup<'a, T: Into<SetupTarget<'a>>>(&'a self, target: T)
-> SetupRequest<'a, Self>;
Configure with the following setters before submitting:
| Setter | Default | Description |
|---|---|---|
.with_hints() | disabled | Enable hint-accelerated witness generation. Takes effect only on a client built with .assembly(); an emulator client silently ignores it. |
.emulator_only() | disabled | Generate only the setup needed by the emulator, skipping Assembly-backend artifacts. |
.timeout(Duration) | no timeout | Cancel setup if it takes longer than this. |
.output_dir(PathBuf) | ZisK cache dir | Directory where the verkey file is written when setup completes. |
use std::path::PathBuf;
use std::time::Duration;
client.setup(&program)
.with_hints()
.output_dir(PathBuf::from("./keys"))
.timeout(Duration::from_secs(300))
.run()?
.await?;
execute
Run the guest without generating a proof. Returns
Result<JobHandle<ExecuteResult>>. The input source accepts both
ZiskStdin and ZiskStream.
pub fn execute<'a>(
&'a self,
program: &'a GuestProgram,
stdin: impl Into<InputSource>,
) -> ExecuteRequest<'a, Self>;
Configure with the following setters before submitting:
| Setter | Default | Description |
|---|---|---|
.hints(impl Into<HintsSource>) | none | Attach a hints source for this execute call. |
.random_seed(impl Into<Option<RandomSeed>>) | fresh seed | Run with this host randomness seed instead of drawing a fresh one. See Random seed. |
.executor(ExecutorKind) | client default | Override the executor (Emulator or Assembly) for this single request. Assembly needs a client built with .assembly(). |
.timeout(Duration) | no timeout | Cancel execution if it takes longer than this. |
On an EmbeddedClient, execute needs the program set up in the
same process first. Without a prior setup(&program) on that client
it fails with Program '<name>' not found in cache. Call setup() first.
ExecutorKind::Assembly on a client built without .assembly()
fails with Assembly executor not enabled — call .assembly() on the builder.
use std::time::Duration;
use zisk_sdk::ExecutorKind;
// client built with ProverClient::embedded().assembly()
let exec = client
.execute(&program, stdin)
.executor(ExecutorKind::Assembly)
.timeout(Duration::from_secs(10))
.run()?
.await?;
prove
Generate a proof for a guest run. Returns
Result<JobHandle<ProveResult>>.
pub fn prove<'a>(
&'a self,
program: &'a GuestProgram,
stdin: impl Into<InputSource>,
) -> ProveRequest<'a, Self>;
Configure with the following setters before submitting:
| Setter | Default | Description |
|---|---|---|
.hints(impl Into<HintsSource>) | none | Attach a hints source. Requires .with_hints() at setup time and the Assembly executor. |
.random_seed(impl Into<Option<RandomSeed>>) | fresh seed | Run with this host randomness seed instead of drawing a fresh one. See Random seed. |
.executor(ExecutorKind) | client default | Override the executor for this single request. Assembly needs a client built with .assembly(). |
.timeout(Duration) | no timeout | Cancel proving if it takes longer than this. |
.wrap(ProofKind) | ProofKind::VadcopFinal | Set the proof wrapping mode. ProofKind::Snark needs a client built with a final SNARK (.pilfflonk() or .plonk()). |
.on(JobEvent, callback) | no callback | Register a pre-submission event callback. Use JobEvent::All to receive every event. |
Callbacks registered via .on(...) before .run() are guaranteed
to see every event, including ones that fire between submission and
the first post-submission .on(...) on the returned JobHandle.
The event type is:
pub enum JobEvent {
All,
Started,
Progress(u8),
Completed,
Failed(String),
}
| Variant | Description |
|---|---|
All | Subscription filter meaning "receive every event". Never delivered to a callback as a concrete event. |
Started | Job accepted and execution started. |
Progress(u8) | Proof-generation progress, 0–100. |
Completed | Proof completed successfully. |
Failed(String) | Proof generation failed, with the reason. |
Pass a specific variant to filter — .on(JobEvent::Completed, ...)
fires only on completion — or JobEvent::All to receive everything.
use std::time::Duration;
use zisk_sdk::{JobEvent, ProofKind};
let proof = client
.prove(&program, stdin)
.wrap(ProofKind::VadcopFinalMinimal)
.timeout(Duration::from_secs(300))
.on(JobEvent::All, |e| println!("event: {e:?}"))
.run()?
.await?;
wrap_proof
Convert an existing proof into another ProofKind without
re-executing the guest. Returns Result<JobHandle<ProveResult>> —
wrapped proofs share the same result shape as freshly generated ones.
pub fn wrap_proof<'a>(
&'a self,
proof: &'a Proof,
proof_kind: ProofKind,
) -> WrapRequest<'a, Self>;
Configure with the following setters before submitting:
| Setter | Default | Description |
|---|---|---|
.with_publics(PublicValues) | from the proof | Override the public values used for the wrapped proof. Embedded-only (see below). |
.with_program_vk(ProgramVK) | from the proof | Override the program verification key. Embedded-only (see below). |
.timeout(Duration) | no timeout | Cancel the wrap job if it takes longer than this. |
use zisk_sdk::ProofKind;
let snark = client
.wrap_proof(&stark_proof, ProofKind::Snark)
.run()?
.await?;
with_publics and with_program_vk are honoured only by
EmbeddedClient::wrap_proof. RemoteClient::wrap_proof ignores
them — the coordinator always re-derives both from the wrapped
proof.
Wrapping into ProofKind::Snark needs a client built with a final
SNARK (.pilfflonk() or .plonk()), and the source proof must be an
uncompressed VadcopFinal proof. A VadcopFinalMinimal proof cannot
be SNARK-wrapped.
A wrapped aggregate verifies only under its recurser's key, which no release publishes. Pass it on the result before verifying:
let agg_vk = AGG.vk()?.vk;
let wrapped = client.wrap_proof(&aggregate, ProofKind::Snark).run()?.await?;
wrapped.with_setup_vk(agg_vk).verify()?;
aggregate_proofs
Fold two Vadcop proofs into one with a recurser. Returns
Result<JobHandle<ProveResult>>. Upload (remote only) and set up the
recurser first with client.upload(&AGG) and client.setup(&AGG).
pub fn aggregate_proofs<'a>(
&'a self,
agg: &'a Recurser,
input_a: impl Into<AggregationInput<'a>>,
input_b: impl Into<AggregationInput<'a>>,
) -> AggregateProofsRequest<'a, Self>;
| Setter | Default | Description |
|---|---|---|
.root_c_recurser_agg([u64; 4]) | the recurser's verkey | Override rootCRecurserAgg. |
.timeout(Duration) | no timeout | Cancel the fold if it takes longer than this. |
.on(JobEvent, callback) | no callback | Register a pre-submission event callback. |
Each side takes a &Proof, or proof.with_free_inputs(values) (from
the ProofExt trait) when the recurser declares free inputs.
aggregate_proofs has no .run_sync(). See
Aggregating proofs.
verify_constraints (embedded-only)
EmbeddedClient also gains a verify_constraints method when the
VerifyConstraintsExtension trait is brought into scope. The
constraint checker runs the guest, builds the witness, and checks
every arithmetic constraint without generating a proof — the
fastest way to validate that a program and its inputs produce a
consistent execution trace. Returns
Result<JobHandle<VerifyConstraintsResult>>.
fn verify_constraints<'a>(
&'a self,
program: &'a GuestProgram,
stdin: ZiskStdin,
) -> VerifyConstraintsRequest<'a, Self>;
Configure with the following setters before submitting:
| Setter | Default | Description |
|---|---|---|
.debug_info(impl Into<Option<String>>) | disabled | Enable debug-info output. Pass None for the default path, or Some(path) to write elsewhere. |
.executor(ExecutorKind) | client default | Override the executor for this check. Assembly needs a client built with .assembly(). |
.hints(impl Into<HintsSource>) | none | Attach a hints source. Requires .with_hints() at setup time and the Assembly executor. |
.random_seed(impl Into<Option<RandomSeed>>) | fresh seed | Run with this host randomness seed instead of drawing a fresh one. See Random seed. |
.timeout(Duration) | no timeout | Cancel the constraint check if it takes longer than this. |
verify_constraints is provided by the VerifyConstraintsExtension
trait, not as an inherent method on EmbeddedClient. The trait is
sealed to internal types and is not implemented for
RemoteClient — calling it on a remote client is a compile-time
error. Unlike execute and prove, stdin is taken by value
(ZiskStdin), not by impl Into<InputSource> — the constraint
checker does not stream inputs.
use std::time::Duration;
use zisk_sdk::VerifyConstraintsExtension;
let result = client
.verify_constraints(&program, stdin)
.timeout(Duration::from_secs(60))
.run()?
.await?;
setup_by_id (remote-only)
RemoteClient::setup_by_id runs setup for a program the coordinator
already holds, keyed by its hash_id, without sending the ELF. The
program must have been uploaded before, or the coordinator returns
ProgramNotFound. It takes programs only; set up a recurser with
setup(&recurser). Returns a SetupByIdRequest with the same setters
as setup (.with_hints(), .emulator_only(), .timeout(Duration),
.output_dir(PathBuf)) and an async .run().
pub fn setup_by_id(&self, hash_id: impl Into<String>) -> SetupByIdRequest<'_>;
let hash_id = remote.upload(&PROGRAM).run()?.hash_id().to_string();
remote.setup_by_id(hash_id).run()?.await?;
ZiskClient
ZiskClient holds either an EmbeddedClient or a RemoteClient and
picks the backend at runtime, for example from a CLI flag. Build it
with ZiskClient::embedded() or ZiskClient::remote(url). They
return the same builders as ProverClient, and their .build()
yields a ZiskClient. You can also convert a built client with
.into().
use zisk_sdk::ZiskClient;
let client = if use_remote {
ZiskClient::remote("http://coordinator:7000").build()?
} else {
ZiskClient::embedded().assembly().build()?
};
client.setup(&PROGRAM).run()?.await?;
ZiskClient offers the operations both backends share (upload,
setup, execute, prove, wrap_proof, aggregate_proofs) with
.run() only. It has no .run_sync(), verify_constraints,
setup_by_id, or .metadata(...). To reach those, recover the
concrete client:
| Method | Returns |
|---|---|
as_embedded() | Option<&EmbeddedClient> |
as_remote() | Option<&RemoteClient> |
Random seed
Every execution runs with a 256-bit host randomness seed. The guest
reads values derived from it with zkvm_random_u64 (see
Randomness). By default each run draws a
fresh seed. Pass one with .random_seed(...) on execute, prove or
verify_constraints to reproduce an earlier run.
use zisk_sdk::RandomSeed;
let first = client.execute(&program, stdin.clone()).run()?.await?;
let seed: Option<RandomSeed> = first.get_random_seed();
// Replays the same random values in the guest
let again = client.execute(&program, stdin).random_seed(seed).run()?.await?;
RandomSeed is re-exported by zisk_sdk. It parses from a hex
string ("…".parse::<RandomSeed>()) and prints as one. Every result
reports the seed it ran with through get_random_seed(). See
Results & outputs.
The seed is unconstrained: verification ignores it, and a guest's
public outputs must not depend on it. A remote coordinator rejects a
client-supplied seed with CLIENT_RANDOM_SEED_NOT_ALLOWED (1006) unless
it is configured with allow_client_random_seed = true.
Cancelling a job
JobHandle has two ways to cancel a job.
| Method | Returns | Description |
|---|---|---|
handle.cancel().await | Result<bool> | Cancel through the handle you still hold (takes &mut self). Remote only. |
handle.canceller() | Option<JobCanceller> | A cloneable canceller, for cancelling while the handle is awaited. None for an embedded job. |
canceller.cancel().await | Result<bool> | Cancel the remote job. true if the coordinator cancelled it, false if it had already ended. |
handle.cancel() borrows the handle mutably, so bind it with let mut:
let mut handle = client.prove(&program, stdin).run()?;
let cancelled = handle.cancel().await?;
Awaiting a JobHandle consumes it, so take a JobCanceller first
when another task must be able to cancel the job:
let handle = client.prove(&program, stdin).run()?;
let canceller = handle.canceller().expect("remote job");
tokio::spawn(async move {
tokio::time::sleep(std::time::Duration::from_secs(600)).await;
let _ = canceller.cancel().await;
});
let result = handle.await;
Embedded jobs cannot be cancelled yet: canceller() returns None,
and cancel() on an embedded handle panics.
zisk_sdk also exports CancellationToken, a cloneable flag with
new(), cancel(), is_cancelled() and as_cancel_fn(). No SDK
request takes one in 1.4.0-alpha, so it does not cancel jobs. Use
JobHandle::cancel or JobCanceller for that.
Inputs
The guest's input region holds up to 2 GiB − 16 bytes. Both clients
accept a ZiskStdin of that size.
A RemoteClient sends a buffered ZiskStdin inline in the job
request when it fits in 127 MiB, together with any hints. Larger
inputs are pushed to the coordinator through the job's gRPC input
stream (PushJobInput), with no change to your code. A ZiskStdin
over the 2 GiB − 16 bytes limit fails on the client, before the job is
submitted. The coordinator refuses oversized input with
INPUT_TOO_LARGE (1009).
Hints have a stricter limit on a remote client. A ZiskHints is read
whole on the client and always sent inline, so hints over 127 MiB are
refused. Stream larger hints with a ZiskStream instead. See
ZiskHints.
Job metadata
A remote job can carry opaque, job-level key/value metadata. Use it to tag jobs with your own request IDs, tenant names or run labels, so you can correlate them on the coordinator side. The coordinator keeps the pairs with the job and logs them when the job completes. ZisK does not interpret them.
.metadata(key, value) is available on the RemoteClient request
builders for prove, execute, wrap_proof and aggregate_proofs.
Call it repeatedly to add more pairs. A key given twice keeps its last
value.
pub fn metadata(self, key: impl Into<String>, value: impl Into<String>) -> Self
use std::time::Duration;
use zisk_sdk::{JobEvent, ProverClient};
let client = ProverClient::remote("http://coordinator:7000").build()?;
let proof = client
.prove(&program, stdin)
.metadata("request_id", "8f31c2")
.metadata("tenant", "acme")
.timeout(Duration::from_secs(300))
.on(JobEvent::All, |e| println!("event: {e:?}"))
.run()?
.await?;
The coordinator accepts up to 32 pairs per job, with keys of up to
128 bytes and values of up to 1 KiB. A coordinator configured with
allow_job_metadata = false rejects any job that carries metadata
with JOB_METADATA_NOT_ALLOWED (1007). See
Error codes.
Metadata is a coordinator feature, so .metadata(...) exists only on
RemoteClient requests. It is not available on EmbeddedClient or
on ZiskClient. With a ZiskClient, reach the remote client through
ZiskClient::as_remote():
if let Some(remote) = client.as_remote() {
remote.prove(&program, stdin).metadata("tenant", "acme").run()?.await?;
}
RemoteClientExt is deprecatedRemoteClientExt, ProveRequestExt and ExecuteRequestExt, and
RemoteClientBuilder::build_ext() that returns them, are
#[deprecated(since = "1.4.0-alpha")] and will be removed in the
first non-alpha release. ProveRequestExt and ExecuteRequestExt are
now aliases of ProveRequest<RemoteClient> and
ExecuteRequest<RemoteClient>. Build the client with .build() and
call .metadata(...) on its requests.
Full pipeline example
use std::time::Duration;
use zisk_sdk::{
GuestProgram, JobEvent, ProofKind, ProverClient, ZiskStdin, load_program,
};
// Built by `build_program("../my-guest")` in host/build.rs
static PROGRAM: GuestProgram = load_program!("my-guest");
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let client = ProverClient::embedded().assembly().build()?;
// One-time setup per ELF
client.setup(&PROGRAM).run()?.await?;
// Validate the input cheaply before paying for proving
let stdin = ZiskStdin::new();
stdin.write(&vec![10u32, 20, 30]);
let exec = client
.execute(&PROGRAM, stdin.clone())
.timeout(Duration::from_secs(10))
.run()?
.await?;
println!("execute steps: {}", exec.get_execution_steps());
// Generate the proof, streaming progress events
let result = client
.prove(&PROGRAM, stdin)
.wrap(ProofKind::VadcopFinalMinimal)
.on(JobEvent::All, |e| println!("event: {e:?}"))
.run()?
.await?;
// The result derefs to ProveOutput — full access to its methods.
// An embedded result verifies under the keys of the setup that produced it.
result.verify()?;
result.save_proof("./proof.bin")?;
println!("proving time: {} ms", result.get_proving_time());
Ok(())
}
Verifying a result
ProveResult::verify() never trusts the keys a proof carries. An
EmbeddedClient result verifies under the keys of the local setup
that produced it. A RemoteClient result has no producing setup on
the client, so it verifies under the release keys compiled into ZisK.
If the cluster runs a self-built setup, or the proof is an aggregate,
pass the trusted key on the result first:
| Method | Use when |
|---|---|
.with_leaf_setup_vk(Vec<u64>) | The cluster runs a non-release setup. Its vadcop_final.verkey.json (vadcop_final_compressed.verkey.json for a minimal proof). |
.with_setup_vk(Vec<u64>) | The proof is an aggregate. The recurser's verkey, AGG.vk()?.vk. |
.with_plonk_vk(PlonkVkey) | The proof is a PLONK SNARK. Its final.verkey.json; the release publishes no PLONK key. |
.with_pilfflonk_vkey(String) | The proof is a pilfflonk SNARK of a non-release key. The JSON of its pilfflonk.vkey.json. |
let vk: Vec<u64> = serde_json::from_str(&std::fs::read_to_string(
"vadcop_final.verkey.json",
)?)?;
let result = client.prove(&PROGRAM, stdin).run()?.await?.with_leaf_setup_vk(vk);
result.with_program_vk(&PROGRAM.vk()?).verify()?;
See Proof › verify for the full trust model.