Skip to main content

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
ParameterTypeDescription
urlimpl 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:

FeatureAvailable on
verify_constraintsEmbeddedClient only (extension trait)
.run_sync()EmbeddedClient only
setup_by_idRemoteClient 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:

FinisherReturnsUse 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().

Embedded-only

.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:

SetterDefaultDescription
.with_hints()disabledEnable hint-accelerated witness generation. Takes effect only on a client built with .assembly(); an emulator client silently ignores it.
.emulator_only()disabledGenerate only the setup needed by the emulator, skipping Assembly-backend artifacts.
.timeout(Duration)no timeoutCancel setup if it takes longer than this.
.output_dir(PathBuf)ZisK cache dirDirectory 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:

SetterDefaultDescription
.hints(impl Into<HintsSource>)noneAttach a hints source for this execute call.
.random_seed(impl Into<Option<RandomSeed>>)fresh seedRun with this host randomness seed instead of drawing a fresh one. See Random seed.
.executor(ExecutorKind)client defaultOverride the executor (Emulator or Assembly) for this single request. Assembly needs a client built with .assembly().
.timeout(Duration)no timeoutCancel 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:

SetterDefaultDescription
.hints(impl Into<HintsSource>)noneAttach a hints source. Requires .with_hints() at setup time and the Assembly executor.
.random_seed(impl Into<Option<RandomSeed>>)fresh seedRun with this host randomness seed instead of drawing a fresh one. See Random seed.
.executor(ExecutorKind)client defaultOverride the executor for this single request. Assembly needs a client built with .assembly().
.timeout(Duration)no timeoutCancel proving if it takes longer than this.
.wrap(ProofKind)ProofKind::VadcopFinalSet the proof wrapping mode. ProofKind::Snark needs a client built with a final SNARK (.pilfflonk() or .plonk()).
.on(JobEvent, callback)no callbackRegister 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),
}
VariantDescription
AllSubscription filter meaning "receive every event". Never delivered to a callback as a concrete event.
StartedJob accepted and execution started.
Progress(u8)Proof-generation progress, 0–100.
CompletedProof 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:

SetterDefaultDescription
.with_publics(PublicValues)from the proofOverride the public values used for the wrapped proof. Embedded-only (see below).
.with_program_vk(ProgramVK)from the proofOverride the program verification key. Embedded-only (see below).
.timeout(Duration)no timeoutCancel the wrap job if it takes longer than this.
use zisk_sdk::ProofKind;

let snark = client
.wrap_proof(&stark_proof, ProofKind::Snark)
.run()?
.await?;
RemoteClient gotcha

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>;
SetterDefaultDescription
.root_c_recurser_agg([u64; 4])the recurser's verkeyOverride rootCRecurserAgg.
.timeout(Duration)no timeoutCancel the fold if it takes longer than this.
.on(JobEvent, callback)no callbackRegister 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:

SetterDefaultDescription
.debug_info(impl Into<Option<String>>)disabledEnable debug-info output. Pass None for the default path, or Some(path) to write elsewhere.
.executor(ExecutorKind)client defaultOverride the executor for this check. Assembly needs a client built with .assembly().
.hints(impl Into<HintsSource>)noneAttach a hints source. Requires .with_hints() at setup time and the Assembly executor.
.random_seed(impl Into<Option<RandomSeed>>)fresh seedRun with this host randomness seed instead of drawing a fresh one. See Random seed.
.timeout(Duration)no timeoutCancel the constraint check if it takes longer than this.
Extension-trait gating

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:

MethodReturns
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.

MethodReturnsDescription
handle.cancel().awaitResult<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().awaitResult<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.

Remote only

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 deprecated

RemoteClientExt, 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:

MethodUse 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.