Skip to main content

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()?;
Single instance per process

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

MethodEffect
.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​

MethodEffect
.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​

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

MethodEffect
.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,
}
VariantDescription
Pilfflonkpilfflonk. The default of setup-snark --final-snark, the only protocol a blake3 key supports, and the key ziskup setup_snark installs.
PlonkPLONK, 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​

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

MethodEffect
.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​

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

MethodEffect
.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​

MethodReturns
.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 ProverClient already 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 is ASM 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>,
}
FieldTypeDescription
minimal_memoryboolReduce memory footprint during proving at the cost of speed.
proving_keyOption<PathBuf>STARK proving key directory.
proving_key_snarkOption<PathBuf>SNARK proving key directory, set up for one final SNARK protocol.
preload_snarkboolEagerly load the SNARK proving key at startup instead of on first use.
max_witness_storedOption<usize>Maximum bytes held for intermediate witness data.
number_threads_witnessOption<usize>Number of threads dedicated to witness generation.
max_streamsOption<usize>Maximum parallel streams during proving.
max_recursive_streamsOption<usize>Maximum per-GPU recursive (aggregation) streams during proving.
Renamed in 1.4.0-alpha

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​

MethodSets
.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,
}
FieldTypeDescription
asm_pathOption<PathBuf>Directory where the generated ASM binaries are cached. None uses the default location.
no_auto_setupboolSkip the implicit setup pass before proving.
unlock_mapped_memoryboolDisable mlock on memory-mapped regions used by the runner.
asm_out_fileboolHave the ASM runner write its output to a file instead of shared memory.
is_distributedboolMark the runner as participating in a distributed (MPI) proving session.

Setters​

MethodSets
.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
ParameterTypeDescription
urlimpl Into<String>Full base URL of the remote coordinator.

Timeouts​

MethodDefaultDescription
.connect_timeout(d: Duration)10 sTimeout for establishing the underlying connection.
.request_timeout(d: Duration)300 sTimeout 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:

MethodEffect
.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​

MethodReturns
.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()?;