Proof
Proof bundles a cryptographic proof body, the public values the
guest committed, and the program verification key that pins the proof
to a specific program. Use it to verify, inspect outputs, and persist
for later use.
Overview
A Proof is what a proving run produces. It carries everything an
independent process needs to verify the run — neither the guest ELF
nor the original inputs are required. ProveResult derefs to
ProveOutput, whose get_proof() returns the &Proof. See
Results & outputs.
You usually do not construct a Proof yourself. The prover hands you
one through ProveResult, or you load a previously saved one with
Proof::load(...).
Types
Proof
The top-level proof container.
pub struct Proof {
pub body: ProofBody,
pub program_vk: ProgramVK,
pub random_seed: Option<RandomSeed>,
}
| Field | Type | Description |
|---|---|---|
body | ProofBody | Kind-tagged proof payload, including the publics. |
program_vk | ProgramVK | Stored copy of the program verification key. Untrusted: get_program_vk() derives the key from the committed publics instead. |
random_seed | Option<RandomSeed> | Host randomness seed of the execution the proof attests to. Unauthenticated metadata that verification ignores. None for aggregates. |
random_seed is new, so struct literals of Proof no longer compile.
Build a proof with Proof::new(body, program_vk) and chain
.with_random_seed(seed) when it attests to an execution.
Publics are not a field on Proof. They live inside the body at
full u64 width, and the PublicValues view is derived on demand by
publics(). This keeps the u32 view from
ever disagreeing with the elements the proof actually committed to.
ProofKind
Identifies the proof format. Derived from ProofBody via
Proof::kind(), not stored on the proof.
pub enum ProofKind {
#[default]
VadcopFinal,
VadcopFinalMinimal,
Snark,
}
| Variant | Description |
|---|---|
VadcopFinal | Default STARK output. Largest proof, fastest to generate. |
VadcopFinalMinimal | Smaller STARK obtained by wrapping VadcopFinal. Off-chain friendly. |
Snark | The final SNARK: constant size, EVM-verifiable on-chain. The SNARK proving key sets its protocol, pilfflonk or PLONK. |
ProofKind::Snark means "the final SNARK", whichever protocol it is.
It maps to a ProofBody::Pilfflonk body with the release key, or to a
ProofBody::Plonk body with a self-built PLONK key.
ProofKind::Plonk still compiles as a deprecated alias of
ProofKind::Snark.
ProofBody
The kind-tagged proof payload stored in Proof::body. Every variant
carries publics_full — the untruncated u64 field elements the proof
committed to — because a recurser proof's publics exceed 32 bits and
the recursion round-trip must use the exact committed values.
pub enum ProofBody {
Vadcop {
proof: Vec<u64>,
zisk_vk: Vec<u64>,
kind: VadcopKind,
hash: String,
publics_full: Vec<u64>,
},
Plonk {
proof_bytes: Vec<u8>,
plonk_vk: Box<PlonkVkBlob>,
publics: PublicValues,
publics_full: Vec<u64>,
rootc: Vec<u64>,
},
Pilfflonk {
proof_bytes: Vec<u8>,
vkey_json: String,
publics: PublicValues,
publics_full: Vec<u64>,
rootc: Vec<u64>,
},
}
Pilfflonk is new, so an exhaustive match on ProofBody must
handle it.
Vadcop — produced by VadcopFinal and VadcopFinalMinimal.
| Field | Type | Description |
|---|---|---|
proof | Vec<u64> | Proof, as a flat vector of field elements. |
zisk_vk | Vec<u64> | ZisK verification key. |
kind | VadcopKind | Which vadcop flavor this is, and the is_vadcop_final_proof flag value it implies. |
hash | String | Hash family the proof was generated with. |
publics_full | Vec<u64> | Flag-free program publics [program_vk(4) | inputs(64)], always 68, at full u64 width. |
Plonk — produced by ProofKind::Snark with a self-built PLONK
SNARK key.
| Field | Type | Description |
|---|---|---|
proof_bytes | Vec<u8> | Serialized SNARK proof bytes. |
plonk_vk | Box<PlonkVkBlob> | The keys the producer wrapped under. Untrusted metadata: verification uses the caller's key (with_plonk_vk). Boxed so the common Vadcop variant doesn't carry it inline. |
publics | PublicValues | u32 view of the publics, matching the Solidity calldata layout. |
publics_full | Vec<u64> | Full-width publics. The SNARK's publicsHash is computed over these, not the u32 view. |
rootc | Vec<u64> | The stamped rootCVadcopFinal committed into publicsHash. |
Pilfflonk — produced by ProofKind::Snark with a pilfflonk SNARK
key, the release's final SNARK.
| Field | Type | Description |
|---|---|---|
proof_bytes | Vec<u8> | Serialized pilfflonk proof bytes. |
vkey_json | String | The JSON of the pilfflonk.vkey.json the proof was wrapped under. Used only if its digest is the release's for the proof's family; otherwise pass a trusted key with with_pilfflonk_vkey. |
publics | PublicValues | u32 view of the publics. |
publics_full | Vec<u64> | Full-width publics. The SNARK's public digest is computed over these. |
rootc | Vec<u64> | The stamped rootCVadcopFinal committed into the digest, as in Plonk. |
rootc is what the on-chain digest commits to, and it is
not derivable from publics_full or from the verification key:
it is the vadcop_final verkey for a plain proof, but the
recurser verkey for an aggregated one. The hash preimage is
programVK (4 × u64 big-endian, 32 bytes) ++ publicValues
(snark_inputs_bytes(publics_full): the 64 outputs as u64
little-endian, 512 bytes) ++ rootCVadcopFinal (4 × u64 big-endian,
32 bytes), SHA-256'd and then reduced modulo the BN254 scalar field.
A contract must hold programVK and rootCVadcopFinal as constants.
See On-chain verification.
VadcopKind
Tags which flavor of vadcop proof a Vadcop body holds. It owns the
is_vadcop_final_proof flag value, which is deliberately not
stored in publics_full — STARK paths re-add it via
VadcopKind::stark_publics.
pub enum VadcopKind {
#[default]
Final,
Recurser,
Minimal,
}
| Variant | Publics layout | Flag at index 0 | Meaning |
|---|---|---|---|
Final | [flag | vk(4) | inputs(64)] (69) | 1 | Raw ZisK vadcop_final proof — a recursion leaf. |
Recurser | [flag | vk(4) | inputs(64)] (69) | 0 | Output of a recurser fold (an aggregated proof). |
Minimal | [vk(4) | inputs(64)] (68) | none | Minimal proof; the compressed circuit strips it. |
| Method | Description |
|---|---|
.flag() -> Option<u64> | The flag value at public index 0, or None for Minimal. |
.is_minimal() -> bool | Whether this is the minimal (compressed) proof. |
.from_publics_full(&[u64]) | Classify a raw publics vector as it arrives from the prover, before normalization. |
.stark_publics(&[u64]) -> Vec<u64> | Rebuild the STARK public vector, re-adding the flag for Final / Recurser. |
VadcopKind is defined in zisk_common and is not re-exported by
zisk_sdk. The SDK re-exports Proof, ProofBody, ProofKind,
PublicValues, ProgramVK, PlonkVkBlob, and PlonkVkey; reach for
zisk_common directly if you need to name this type. Most callers
don't — use Proof::kind(), which maps Minimal to
ProofKind::VadcopFinalMinimal and both other variants to
ProofKind::VadcopFinal.
PublicValues
Holds the public outputs the guest committed. Internally a byte
buffer plus an atomic read cursor: each read advances the cursor
by the number of bytes consumed. Reads take &self because the
cursor is atomic.
pub struct PublicValues {
/* private */
}
The encoding follows serde rules: read::<T>() uses bincode for
typed reads; read_slice operates on raw bytes; read_abi::<T>()
decodes Solidity ABI–encoded values.
ProgramVK
The program verification key. Re-exported from zisk_common. It is
derived from the guest ELF (see GuestProgram::vk)
and is what an independent verifier pins a proof to.
pub struct ProgramVK {
pub vk: Vec<u64>,
pub hash_mode: HashMode,
}
| Field | Type | Description |
|---|---|---|
vk | Vec<u64> | The 4-limb ROM root of the program. |
hash_mode | HashMode | The hash family the key was derived under. |
ProgramVK implements Clone and Debug but not PartialEq.
Compare the vk fields instead (a.vk == b.vk).
Constructors
Proof::new
Build a proof from a body and a program verification key, with no
seed. Chain with_random_seed when the proof attests to an execution.
pub fn new(body: ProofBody, program_vk: ProgramVK) -> Proof
pub fn with_random_seed(self, seed: impl Into<Option<RandomSeed>>) -> Proof
let proof = Proof::new(body, program_vk).with_random_seed(seed);
Proof::load
Load a previously saved proof from disk.
pub fn load(path: impl AsRef<Path>) -> Result<Proof>
| Name | Type | Description |
|---|---|---|
path | impl AsRef<Path> | Path to the proof file on disk. |
The file must have been written by Proof::save, cargo-zisk prove
or other tooling using the proof file format.
load reads it with from_bytes, which
checks the shape of the publics before returning.
use zisk_sdk::Proof;
let proof = Proof::load("my-path/proof.bin")?;
proof.verify()?;
The file format changed in 1.4.0-alpha. Proofs saved by ZisK 1.3 are
rejected by load. Re-prove them with 1.4.0-alpha.
Methods
save
Write the proof to disk in the proof file format.
Missing parent directories are created, and existing files are
overwritten. save first runs ensure_saveable(), which refuses a
proof whose publics are misshapen or non-canonical, or whose stored
program_vk differs from the one its publics commit to.
pub fn save(&self, path: impl AsRef<Path>) -> Result<()>
| Name | Type | Description |
|---|---|---|
path | impl AsRef<Path> | Destination path for the proof file. |
proof.save("my-path/proof.bin")?;
to_bytes / from_bytes
The bytes save writes and load reads, in memory.
pub fn to_bytes(&self) -> Result<Vec<u8>>
pub fn to_bytes_without_seed_trailer(&self) -> Result<Vec<u8>>
pub fn from_bytes(bytes: &[u8]) -> Result<Proof>
pub fn ensure_saveable(&self) -> Result<()>
to_bytes_without_seed_trailer drops a Vadcop proof's
seed trailer. Use it for the bytes you pass to
verify_zisk_proof
in a guest, which refuses the trailer. For a SNARK proof it returns
the same bytes as to_bytes.
to_bincode / from_bincode
The bincode encoding the coordinator, workers and clients exchange over the network. It is not a file format.
pub fn to_bincode(&self) -> Result<Vec<u8>>
pub fn from_bincode(bytes: &[u8]) -> Result<Proof>
from_bincode also decodes encodings from versions without
random_seed. Unlike from_bytes, it does not check the publics.
kind
Return the proof's ProofKind, derived from the body discriminant: a
Vadcop body with VadcopKind::Minimal maps to
VadcopFinalMinimal, any other Vadcop body to VadcopFinal, and a
Plonk or Pilfflonk body to Snark.
pub fn kind(&self) -> ProofKind
match proof.kind() {
ProofKind::VadcopFinal => println!("Vadcop final proof"),
ProofKind::VadcopFinalMinimal => println!("Vadcop minimal proof"),
ProofKind::Snark => println!("final SNARK proof"),
}
is_empty
Return true if the proof carries no proof body (a default /
placeholder proof).
pub fn is_empty(&self) -> bool
publics / publics_full
publics() derives the u32 PublicValues view from the body's
publics_full, for every variant, truncating each full-width public to
its low 32 bits (the guest / Solidity ABI width). The stored
publics copy of a SNARK body is never returned, so the view can
never disagree with the statement verify() checks.
publics() is meaningful only on a proof that passed load or
verify. On a misshapen body it returns zeros. When the proof's
provenance is unknown, use try_publics(), which returns
InvalidProof for such a body instead.
publics_full() returns the untruncated u64 publics
[program_vk(4) | inputs(64)] of a Vadcop proof — what the proof
actually committed to, and what the recursion round-trip needs. It
returns None for a Plonk or Pilfflonk proof.
pub fn publics(&self) -> PublicValues
pub fn try_publics(&self) -> Result<PublicValues>
pub fn publics_full(&self) -> Option<&[u64]>
// u32 view — what the guest wrote and the ABI expects
let publics = proof.publics();
// Full-width elements, when they matter (recurser proofs exceed 32 bits)
if let Some(full) = proof.publics_full() {
println!("committed {} field elements", full.len());
}
get_publics
Alias for publics(). Returns the derived
PublicValues by value — it is a fresh view, not a borrow of
something stored on the proof.
pub fn get_publics(&self) -> PublicValues
let publics = proof.get_publics();
let nonce: u64 = publics.read::<u64>()?;
let digest: [u8; 32] = {
let mut out = [0u8; 32];
publics.read_slice(&mut out);
out
};
get_program_vk
Return the program verification key this proof commits to, by
value. It is derived from the committed publics, not from the
untrusted stored program_vk field. Use it to compare against a
trusted key held out-of-band, or pin the key at verify time with
with_program_vk.
pub fn get_program_vk(&self) -> ProgramVK
let vk = proof.get_program_vk();
assert_eq!(vk.vk, trusted_vk.vk); // ProgramVK has no PartialEq
get_proof_bytes / get_proof_u64
Return a Vadcop proof in the flat file layout,
without the seed trailer, as raw bytes or as u64 words. Both error
on a SNARK proof. For the typed structure use the public body field
directly.
pub fn get_proof_bytes(&self) -> Result<Vec<u8>>
pub fn get_proof_u64(&self) -> Result<Vec<u64>>
let bytes = proof.get_proof_bytes()?;
println!("proof bytes: {}", bytes.len());
match &proof.body {
ProofBody::Vadcop { proof, .. } => println!("vadcop words: {}", proof.len()),
ProofBody::Plonk { proof_bytes, .. } | ProofBody::Pilfflonk { proof_bytes, .. } => {
println!("snark bytes: {}", proof_bytes.len())
}
}
get_vadcop_final_proof
Return the VADCOP final proof structure. Errors if the proof is a
SNARK proof rather than a VADCOP one.
get_vadcop_final_proof_to_aggregate also refuses a minimal proof,
which a recurser cannot fold: compression strips the leaf flag.
pub fn get_vadcop_final_proof(&self) -> Result<VadcopFinalProof>
pub fn get_vadcop_final_proof_to_aggregate(&self) -> Result<VadcopFinalProof>
verify
Verify the proof.
pub fn verify(&self) -> Result<()>
pub fn verify_builder(&self) -> ZiskVerifyBuilder<'_>
proof.verify()?;
println!("proof verified");
verify() never trusts a key the proof carries. With no key
passed, it checks the proof against the release keys compiled into
this ZisK version, for the proof's hash family and stage:
| Proof | Key used by a bare verify() | Pass instead |
|---|---|---|
| Leaf, release setup | The release vadcop_final key (or vadcop_final_compressed for minimal) | — |
| Leaf, self-built setup | Fails with NotVerified | .with_leaf_setup_vk(&vk) |
| Aggregate (recurser fold) | Fails with InvalidProof; no release publishes a recurser key | .with_setup_vk(&agg_vk) |
| pilfflonk, release key | The carried vkey, only if its digest is the release's | — |
| pilfflonk, self-built key | Fails with NotVerified | .with_pilfflonk_vkey(&vkey_json) |
| PLONK | Fails with InvalidProof; the release publishes no PLONK key | .with_plonk_vk(&plonk_vkey) |
verify() does not check which program produced the proof. Pin
the program with with_program_vk.
The errors are:
| Error | Meaning |
|---|---|
CommonError::NotVerified | The proof is well-formed but does not verify under the key used. |
CommonError::InvalidProof | The proof is malformed, its hash family does not match the key, or a required key is missing. |
ProveResult::verify() differs in one way: a result from an embedded
client also trusts the keys of the setup that produced it. See
Results & outputs.
with_publics / with_program_vk
Begin a verify chain that overrides the embedded public values or
program verification key. Both return a ZiskVerifyBuilder you can
keep chaining before finishing with .verify().
pub fn with_publics<'a>(&'a self, publics: &'a PublicValues) -> ZiskVerifyBuilder<'a>
pub fn with_program_vk<'a>(&'a self, program_vk: &'a ProgramVK) -> ZiskVerifyBuilder<'a>
// Pin verification to an externally-held program VK
let vk = PROGRAM.vk()?;
proof.with_program_vk(&vk).verify()?;
Trusted keys
These start (or continue) a verify chain with a key you trust. They
are also methods of ZiskVerifyBuilder, so they combine with
with_program_vk.
pub fn with_setup_vk<'a>(&'a self, setup_vk: &'a [u64]) -> ZiskVerifyBuilder<'a>
pub fn with_leaf_setup_vk<'a>(&'a self, setup_vk: &'a [u64]) -> ZiskVerifyBuilder<'a>
pub fn with_plonk_vk<'a>(&'a self, plonk_vkey: &'a PlonkVkey) -> ZiskVerifyBuilder<'a>
pub fn with_pilfflonk_vkey<'a>(&'a self, vkey_json: &'a str) -> ZiskVerifyBuilder<'a>
| Method | Key |
|---|---|
with_setup_vk | A recurser's 4-limb verkey, for an aggregate (AGG.vk()?.vk). The aggregate must also declare it as its recursion domain. |
with_leaf_setup_vk | A self-built setup's leaf key: its vadcop_final.verkey.json, or vadcop_final_compressed.verkey.json for a minimal proof. Aggregates are refused. |
with_plonk_vk | A PLONK final.verkey.json, loaded with PlonkVkey::load(path)?. |
with_pilfflonk_vkey | The JSON text of a pilfflonk.vkey.json. |
// An aggregate, pinned to the recurser and to the program domain it declares
let agg_vk = AGG.vk()?;
proof.with_setup_vk(&agg_vk.vk).with_program_vk(&agg_vk).verify()?;
// A proof from a self-built setup
let leaf: Vec<u64> = serde_json::from_str(&std::fs::read_to_string(
"/home/me/.zisk/provingKey/zisk/vadcop_final/vadcop_final.verkey.json",
)?)?;
proof.with_leaf_setup_vk(&leaf).verify()?;
cargo-zisk verify exposes the same keys as --setup-vk,
--leaf-setup-vk, --plonk-vk and --pilfflonk-vk. See
cargo-zisk verify.
Proof file format
A saved proof is one of two layouts, told apart by the first 8 bytes.
Vadcop proofs
VadcopFinal and VadcopFinalMinimal proofs are saved flat, as
little-endian u64 words. This is the layout
zisk-verifier reads:
[minimal(1)][n_publics(1)][publics(n_publics)][proof(...)][vadcop_final_vk(4)][hash_tag(1)]
| Field | Words | Description |
|---|---|---|
minimal | 1 | 1 for a minimal (compressed) proof, 0 otherwise. |
n_publics | 1 | 69 for an uncompressed proof, 68 for a minimal one. |
publics | n_publics | [flag(1) | program_vk(4) | outputs(64)]. The flag is 1 for a leaf and 0 for an aggregate. A minimal proof has no flag. |
proof | variable | The STARK proof. |
vadcop_final_vk | 4 | The key the producer says it proved under. Untrusted: verification never uses it. |
hash_tag | 1 | The hash family: 0 Poseidon1, 1 Poseidon2, 2 blake3. |
A proof with a random_seed ends with a 5-word seed trailer:
[flat proof][seed(4)][SEED_TRAILER_TAG]
SEED_TRAILER_TAG is u64::from_le_bytes(*b"ZISKSEED"). The seed is
unauthenticated metadata. Hosts read it and ignore it during
verification. Guests refuse it, so strip it with
to_bytes_without_seed_trailer() before handing a proof to a guest.
get_proof_bytes() / get_proof_u64() return the flat layout without
the trailer.
SNARK proofs
Plonk and Pilfflonk proofs are saved as the 8-byte magic
ZISKPLNK (PLONK_FILE_MAGIC) followed by the bincode encoding of the
whole Proof, seed included. A file is at most 16 MiB after the
magic. A pilfflonk file carries its vkey JSON, about 0.5 MB.
No Vadcop file starts with ZISKPLNK, because its first word, the
minimal marker, is 0 or 1.
PublicValues methods
The cursor is shared via an AtomicUsize, so reads take &self
even though they advance the cursor. Call head to rewind
before re-reading.
read
Decode the next bincode-encoded value from the buffer and advance the cursor by the bytes consumed.
pub fn read<T>(&self) -> Result<T>
where
T: serde::Serialize + serde::de::DeserializeOwned,
let count: u64 = publics.read::<u64>()?;
let digest: [u8; 32] = publics.read::<[u8; 32]>()?;
read_slice
Copy the next slice.len() bytes from the buffer into slice. The
cursor advances by slice.len().
pub fn read_slice(&self, slice: &mut [u8])
| Name | Type | Description |
|---|---|---|
slice | &mut [u8] | Destination buffer; its length is the count. |
let mut tag = [0u8; 32];
publics.read_slice(&mut tag);
read_abi
Decode the next value using Solidity ABI rules instead of bincode.
Use this when the guest committed its publics with write_abi for
on-chain consumption.
pub fn read_abi<T>(&self) -> Result<T>
where
T: alloy_sol_types::SolValue
+ From<<T::SolType as alloy_sol_types::SolType>::RustType>,
head
Reset the read cursor back to the beginning of the buffer so the next read starts from the first value again.
pub fn head(&self)
let a: u64 = publics.read()?;
publics.head(); // rewind
let a_again: u64 = publics.read()?;