Skip to main content

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>,
}
FieldTypeDescription
bodyProofBodyKind-tagged proof payload, including the publics.
program_vkProgramVKStored copy of the program verification key. Untrusted: get_program_vk() derives the key from the committed publics instead.
random_seedOption<RandomSeed>Host randomness seed of the execution the proof attests to. Unauthenticated metadata that verification ignores. None for aggregates.
New field in 1.4.0-alpha

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.

note

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,
}
VariantDescription
VadcopFinalDefault STARK output. Largest proof, fastest to generate.
VadcopFinalMinimalSmaller STARK obtained by wrapping VadcopFinal. Off-chain friendly.
SnarkThe 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.

note

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>,
},
}
New variant in 1.4.0-alpha

Pilfflonk is new, so an exhaustive match on ProofBody must handle it.

Vadcop — produced by VadcopFinal and VadcopFinalMinimal.

FieldTypeDescription
proofVec<u64>Proof, as a flat vector of field elements.
zisk_vkVec<u64>ZisK verification key.
kindVadcopKindWhich vadcop flavor this is, and the is_vadcop_final_proof flag value it implies.
hashStringHash family the proof was generated with.
publics_fullVec<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.

FieldTypeDescription
proof_bytesVec<u8>Serialized SNARK proof bytes.
plonk_vkBox<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.
publicsPublicValuesu32 view of the publics, matching the Solidity calldata layout.
publics_fullVec<u64>Full-width publics. The SNARK's publicsHash is computed over these, not the u32 view.
rootcVec<u64>The stamped rootCVadcopFinal committed into publicsHash.

Pilfflonk — produced by ProofKind::Snark with a pilfflonk SNARK key, the release's final SNARK.

FieldTypeDescription
proof_bytesVec<u8>Serialized pilfflonk proof bytes.
vkey_jsonStringThe 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.
publicsPublicValuesu32 view of the publics.
publics_fullVec<u64>Full-width publics. The SNARK's public digest is computed over these.
rootcVec<u64>The stamped rootCVadcopFinal committed into the digest, as in Plonk.
On-chain calldata

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,
}
VariantPublics layoutFlag at index 0Meaning
Final[flag | vk(4) | inputs(64)] (69)1Raw ZisK vadcop_final proof — a recursion leaf.
Recurser[flag | vk(4) | inputs(64)] (69)0Output of a recurser fold (an aggregated proof).
Minimal[vk(4) | inputs(64)] (68)noneMinimal proof; the compressed circuit strips it.
MethodDescription
.flag() -> Option<u64>The flag value at public index 0, or None for Minimal.
.is_minimal() -> boolWhether 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.
note

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,
}
FieldTypeDescription
vkVec<u64>The 4-limb ROM root of the program.
hash_modeHashModeThe 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>
NameTypeDescription
pathimpl 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()?;
1.3 proof files do not load

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<()>
NameTypeDescription
pathimpl 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:

ProofKey used by a bare verify()Pass instead
Leaf, release setupThe release vadcop_final key (or vadcop_final_compressed for minimal)—
Leaf, self-built setupFails 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 keyThe carried vkey, only if its digest is the release's—
pilfflonk, self-built keyFails with NotVerified.with_pilfflonk_vkey(&vkey_json)
PLONKFails 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:

ErrorMeaning
CommonError::NotVerifiedThe proof is well-formed but does not verify under the key used.
CommonError::InvalidProofThe 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>
MethodKey
with_setup_vkA recurser's 4-limb verkey, for an aggregate (AGG.vk()?.vk). The aggregate must also declare it as its recursion domain.
with_leaf_setup_vkA 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_vkA PLONK final.verkey.json, loaded with PlonkVkey::load(path)?.
with_pilfflonk_vkeyThe 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)]
FieldWordsDescription
minimal11 for a minimal (compressed) proof, 0 otherwise.
n_publics169 for an uncompressed proof, 68 for a minimal one.
publicsn_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.
proofvariableThe STARK proof.
vadcop_final_vk4The key the producer says it proved under. Untrusted: verification never uses it.
hash_tag1The 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])
NameTypeDescription
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>,

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