Client builders
EmbeddedClientBuilder and RemoteClientBuilder configure the proving
backend before constructing a client. Start the chain with
ProverClient::embedded() or ProverClient::remote(url), then finalize
with .build().
Overview
Builders are never constructed directly. They are returned by:
// Signatures, not runnable code
ProverClient::embedded() // → EmbeddedClientBuilder
ProverClient::remote("https://prover.tld") // → RemoteClientBuilder
Both follow the method-chaining pattern: every configuration method
returns Self, so options can be composed in any order. Call
.build() at the end to validate the configuration and produce the
client.
use std::time::Duration;
use zisk_sdk::ProverClient;
// Embedded client with the assembly executor and GPU
let client = ProverClient::embedded()
.assembly()
.gpu()
.build()?;
// Remote client with custom timeouts
let client = ProverClient::remote("https://prover.example.com")
.connect_timeout(Duration::from_secs(5))
.request_timeout(Duration::from_secs(600))
.build()?;
.build() may be called once per process — across both builder
kinds. A second call (embedded or remote) panics with
A ProverClient already exists. Only one instance is allowed per process.
Build the client once at startup and share it via Arc<…>, or for
the embedded client by cloning it directly.
EmbeddedClientBuilder
Builds an EmbeddedClient that runs the prover in your process.
Executor selection
Controls how the guest ELF is re-executed to build the witness.
| Method | Effect |
|---|---|
.emulator() | Use the software emulator. Default. Works on every platform. |
.assembly() | Use the native ASM execution engine. Linux x86_64 only (panics elsewhere, see Build). Faster. |
.executor(ExecutorKind) | Set the executor explicitly. ExecutorKind::Emulator (default) or ExecutorKind::Assembly. |
Device selection
| Method | Effect |
|---|---|
.gpu() | Enable GPU acceleration. Needs a ZisK prover library built with CUDA support. Otherwise .build() returns an error; there is no CPU fallback. |
.gpu() takes no argument — it is a flag setter. CPU is the default
whenever .gpu() is not chained; there is no explicit .cpu() method.
Proving keys
| Method | Effect |
|---|---|
.proving_key(path: impl Into<PathBuf>) | Override the directory containing the STARK proving key. |
.proving_key_snark(path: impl Into<PathBuf>) | Override the directory containing the SNARK proving key. The key is set up for one final SNARK protocol. |
.proving_key_plonk(path: impl Into<PathBuf>) | Deprecated. Alias of .proving_key_snark(...). |
Final SNARK
A final SNARK (ProofKind::Snark) is enabled when the client is
built, not per request. Select its protocol with one of these
methods:
| Method | Effect |
|---|---|
.snark(protocol: SnarkProtocol) | Enable the final SNARK of protocol. |
.pilfflonk() | Same as .snark(SnarkProtocol::Pilfflonk). The release SNARK key. |
.plonk() | Same as .snark(SnarkProtocol::Plonk). Needs a self-built Poseidon key. |
pub enum SnarkProtocol {
Plonk,
Pilfflonk,
}
| Variant | Description |
|---|---|
Pilfflonk | pilfflonk. The default of setup-snark --final-snark, the only protocol a blake3 key supports, and the key ziskup setup_snark installs. |
Plonk | PLONK, of a final.zkey. Only a Poseidon key built with setup-snark --final-snark plonk supports it. |
.build() reads the SNARK proving key and checks that it is set up
for the protocol you asked for. On a mismatch it returns
SdkError::InvalidConfig before the client is created. For example,
.plonk() against the release key fails with
a PLONK final SNARK was asked for, but the SNARK proving key … is set up for pilfflonk.
These methods do not change the proof kind of a request.
ProveRequest still defaults to ProofKind::VadcopFinal, so ask for
the SNARK on every prove call with .wrap(ProofKind::Snark).
ProofKind::Snark means "the final SNARK", and the protocol comes
from the key. See
Choosing a proof format.
Other options
| Method | Effect |
|---|---|
.cpu_mops() | Run the memory-operations planner on the CPU even when proving on the GPU. Proof generation stays on the GPU. |
.execute_only() | Return an EmbeddedExecuteOnlyBuilder instead, for a client that only executes. It loads no proving keys. |
Witness-only clients
Importing the WitnessBuilderExt trait adds two more setters to the
embedded builder, for clients that never generate proofs:
| Method | Effect |
|---|---|
.no_aggregation() | Skip the aggregation setup when building. The client can run execute and verify_constraints, but not prove. |
.verify_constraints() | Configure the client for constraint verification, a witness-only workload. |
use zisk_sdk::{ProverClient, WitnessBuilderExt};
let client = ProverClient::embedded().no_aggregation().build()?;
Diagnostics
| Method | Effect |
|---|---|
.verbose(level: u8) | Set log verbosity. 0 is quiet (default); higher values emit more detail. |
Runtime options
Two options structs configure the runtime behaviour of an embedded
client. Build each one with its chainable setters and apply it with
the corresponding .with_* method:
| Method | Effect |
|---|---|
.with_embedded_opts(opts: EmbeddedOpts) | Set proving-side tuning (memory caps, thread counts, key paths, SNARK key preload). See EmbeddedOpts. |
.asm_options(opts: AsmOptions) | Pass extra options to the Assembly executor — requires .assembly(). See AsmOptions. |
If .asm_options(...) is set but the executor is not Assembly,
.build() panics. If both the builder and EmbeddedOpts set a value
for the STARK or SNARK key path, the builder-level .proving_key(...)
/ .proving_key_snark(...) win on .build().
Build
| Method | Returns |
|---|---|
.build() | Result<EmbeddedClient> |
.build() validates the configuration and returns an error for
unsupported combinations. For example, .gpu() on a library built
without CUDA returns
Err(Backend(... GPU mode requested but library was built without CUDA support)),
and a final SNARK whose protocol the SNARK proving key is not set up
for returns SdkError::InvalidConfig. It panics instead of returning
an error in these cases:
- A
ProverClientalready exists in the process. .asm_options(...)is set without the Assembly executor..assembly()on a host that is not Linux x86_64, such as macOS. The panic message isASM emulator backend is only available on Linux x86_64.
The SNARK key check runs first, so a wrong key does not use up the single client instance.
Example
use zisk_sdk::{EmbeddedOpts, ProverClient};
let opts = EmbeddedOpts::default();
let client = ProverClient::embedded()
.assembly()
.gpu()
.proving_key("/data/keys/stark")
.proving_key_snark("/data/keys/snark")
.pilfflonk()
.with_embedded_opts(opts)
.build()?;
EmbeddedOpts
Runtime tuning options applied via .with_embedded_opts(...). Every
field has a corresponding builder-style setter on EmbeddedOpts
itself, so options can be chained from EmbeddedOpts::default().
pub struct EmbeddedOpts {
pub minimal_memory: bool,
pub proving_key: Option<PathBuf>,
pub proving_key_snark: Option<PathBuf>,
pub preload_snark: bool,
pub max_witness_stored: Option<usize>,
pub number_threads_witness: Option<usize>,
pub max_streams: Option<usize>,
pub max_recursive_streams: Option<usize>,
}
| Field | Type | Description |
|---|---|---|
minimal_memory | bool | Reduce memory footprint during proving at the cost of speed. |
proving_key | Option<PathBuf> | STARK proving key directory. |
proving_key_snark | Option<PathBuf> | SNARK proving key directory, set up for one final SNARK protocol. |
preload_snark | bool | Eagerly load the SNARK proving key at startup instead of on first use. |
max_witness_stored | Option<usize> | Maximum bytes held for intermediate witness data. |
number_threads_witness | Option<usize> | Number of threads dedicated to witness generation. |
max_streams | Option<usize> | Maximum parallel streams during proving. |
max_recursive_streams | Option<usize> | Maximum per-GPU recursive (aggregation) streams during proving. |
The field preload_plonk is now preload_snark, because the key may
be of either final SNARK protocol. Struct literals that name
preload_plonk no longer compile. The .preload_plonk() setter
still exists but is deprecated.
Setters
| Method | Sets |
|---|---|
.minimal_memory() | minimal_memory = true |
.proving_key(path: impl Into<PathBuf>) | proving_key = Some(...) |
.proving_key_snark(path: impl Into<PathBuf>) | proving_key_snark = Some(...) |
.preload_snark() | preload_snark = true |
.preload_plonk() | Deprecated. Same as .preload_snark(). |
.max_witness_stored(max: usize) | max_witness_stored = Some(max) |
.number_threads_witness(threads: usize) | number_threads_witness = Some(threads) |
.max_streams(max: usize) | max_streams = Some(max) |
.max_recursive_streams(max: usize) | max_recursive_streams = Some(max) |
use zisk_sdk::EmbeddedOpts;
let opts = EmbeddedOpts::default()
.minimal_memory()
.preload_snark()
.number_threads_witness(16)
.max_streams(4);
AsmOptions
Configuration for the native ASM executor, applied via
.asm_options(...). Re-exported by zisk_sdk from the prover backend.
pub struct AsmOptions {
pub asm_path: Option<PathBuf>,
pub no_auto_setup: bool,
pub unlock_mapped_memory: bool,
pub asm_out_file: bool,
pub is_distributed: bool,
}
| Field | Type | Description |
|---|---|---|
asm_path | Option<PathBuf> | Directory where the generated ASM binaries are cached. None uses the default location. |
no_auto_setup | bool | Skip the implicit setup pass before proving. |
unlock_mapped_memory | bool | Disable mlock on memory-mapped regions used by the runner. |
asm_out_file | bool | Have the ASM runner write its output to a file instead of shared memory. |
is_distributed | bool | Mark the runner as participating in a distributed (MPI) proving session. |
Setters
| Method | Sets |
|---|---|
.asm_path(path: PathBuf) | asm_path = Some(path) |
.no_auto_setup() | no_auto_setup = true |
.unlock_mapped_memory() | unlock_mapped_memory = true |
.asm_out_file() | asm_out_file = true |
.is_distributed() | is_distributed = true |
use std::path::PathBuf;
use zisk_sdk::AsmOptions;
let asm = AsmOptions::default()
.asm_path(PathBuf::from("/data/asm-cache"))
.unlock_mapped_memory();
RemoteClientBuilder
Builds a RemoteClient that delegates proving to an external
coordinator over the network. The remote builder surface is
deliberately small: the executor, device, key paths, and ASM options
all live on the coordinator, not the client.
Constructor
// Signature
pub fn remote(url: impl Into<String>) -> RemoteClientBuilder
| Parameter | Type | Description |
|---|---|---|
url | impl Into<String> | Full base URL of the remote coordinator. |
Timeouts
| Method | Default | Description |
|---|---|---|
.connect_timeout(d: Duration) | 10 s | Timeout for establishing the underlying connection. |
.request_timeout(d: Duration) | 300 s | Timeout for each individual gRPC call to the coordinator. |
request_timeout bounds each gRPC call the client makes, such as
registering the program or submitting a job. It does not bound the
whole job, so a proof that takes longer than 300 s still completes
with the default. To limit how long a job may run, set
.timeout(Duration) on the request. See
ProverClient.
Final SNARK
The workers' SNARK proving key decides the final SNARK protocol. These methods tell the client which protocol you expect:
| Method | Effect |
|---|---|
.snark(protocol: SnarkProtocol) | Expect final SNARK proofs of protocol. |
.pilfflonk() | Same as .snark(SnarkProtocol::Pilfflonk). |
.plonk() | Same as .snark(SnarkProtocol::Plonk). |
With a protocol set, a ProofKind::Snark job asks the coordinator for
that protocol. The coordinator refuses the job with
SNARK_UNAVAILABLE (1008) when the workers' key is of another one, and
the client also checks the proof it gets back. With none set, a
ProofKind::Snark job returns whichever final SNARK the workers are
set up for. The setting has no effect on STARK jobs.
Build
| Method | Returns |
|---|---|
.build() | Result<RemoteClient> |
.build_ext() | Deprecated. Result<RemoteClientExt> |
.build() opens a connection to the coordinator. It is also subject
to the single-instance-per-process invariant — see the warning at the
top of this page.
build_ext() is deprecated.build_ext() is #[deprecated(since = "1.4.0-alpha")] and will be
removed in the first non-alpha release. RemoteClient requests now
take .metadata(key, value) directly, so build with .build(). See
Job metadata.
Example
use std::time::Duration;
use zisk_sdk::ProverClient;
let client = ProverClient::remote("https://prover.example.com")
.connect_timeout(Duration::from_secs(5))
.request_timeout(Duration::from_secs(900))
.pilfflonk()
.build()?;