API
The public API of zisk-verifier: the verify and decode functions,
the Verified and SavedProof types, the VerifyError and
DecodeError variants, and the constants and release keys.
Functions
| Function | Returns | Description |
|---|---|---|
verify_saved(bytes: &[u8], expected_program_vk: Option<&[u64; 4]>) | Result<Verified, VerifyError> | Verify a saved proof under this release's key for its family and stage. Ignores a seed trailer. |
verify(proof: &VadcopFinalProof, vadcop_vk: &[u64; 4]) | Result<Verified, VerifyError> | Verify a decoded proof under a key you trust. Use it for custom setups and aggregates. |
verify_saved_words(words: &[u64], vadcop_vk: &[u64; 4], expected_program_vk: Option<&[u64; 4]>) | Result<Verified, VerifyError> | Verify the flat layout in place, without copying the proof. Refuses a seed trailer. For guests. |
verify_vadcop_final(proof: &VadcopFinalProof, vk: &[u64]) | bool | verify as a bool. It does not tell you which program the proof is for. |
decode_saved(bytes: &[u8]) | Result<SavedProof, DecodeError> | Decode a saved proof, splitting off a seed trailer. |
decode_saved_words(words: &[u64]) | Result<SavedProof, DecodeError> | decode_saved over words already in memory. |
decode_vk(bytes: &[u8]) | Result<[u64; 4], DecodeError> | Decode a key from its verkey.bin: 4 little-endian u64 words. |
vadcop_vk(hash: &str, compressed: bool) | Option<[u64; 4]> | This release's vadcop_final key for a family and stage. |
pilfflonk_vkey_digest(hash: &str) | Option<&'static str> | The digest of this release's pilfflonk.vkey.json for a family. |
proof_size(hash: &str, minimal: bool) | Option<ProofSize> | The length a stage's proofs have: Exact(n) or AtMost(n) bytes. |
program_publics(publics_full: &[u64]) | &[u64] | [program_vk | outputs], with the leaf flag stripped when present. |
publics_are_canonical(publics: &[u64]) | bool | Whether every word is a canonical Goldilocks element. |
hash_tag(hash_id: &str) / hash_id_from_tag(tag: u64) | Option<u64> / Option<&'static str> | Map a hash family to its tag in the file format and back. |
seed_trailer(seed: [u64; 4]) | [u64; 5] | The seed trailer that appends seed to a flat proof. |
The family names are "Poseidon1", "Poseidon2" and "blake3".
Verified
What a verified proof proves.
pub struct Verified {
pub program_vk: [u64; 4],
pub outputs: [u64; 64],
pub is_aggregate: Option<bool>,
}
| Field | Description |
|---|---|
program_vk | The program identity: the ROM root for a leaf, the recursion domain for an aggregate. |
outputs | The 64 public outputs, as canonical field elements. |
is_aggregate | Some(true) for a recurser fold, Some(false) for a leaf, None for a compressed proof, whose stage strips the flag. |
outputs_u32() -> Option<[u32; 64]> returns the outputs as the guest
committed them. It is None for an aggregate, whose outputs are its
recurser's and may exceed 32 bits.
SavedProof
A proof decoded from the flat layout.
pub struct SavedProof {
pub proof: VadcopFinalProof,
pub claimed_vadcop_vk: [u64; 4],
pub random_seed: Option<[u64; 4]>,
}
claimed_vadcop_vk is the key the producer says it proved under. It
is untrusted: use it to pick among keys you already trust, or to
explain a mismatch, never as the key to verify against.
random_seed holds the seed trailer's words, if the file has one.
VadcopFinalProof is re-exported from proofman-verifier.
Errors
VerifyError says why a proof was rejected:
| Variant | Meaning |
|---|---|
UnsupportedStage { hash, compressed } | No verifier for this family and stage. |
PublicCount { expected, got } | The publics are not the width the stage carries (69, or 68 when compressed). |
NonCanonicalPublic { index } | A public is not a canonical Goldilocks element. |
InvalidLeafFlag(u64) | The leaf/fold flag is neither 1 (leaf) nor 0 (fold). |
ProofLength { expected, got_bytes } | The STARK payload is not a length this stage's proofs have. |
OutputNotU32 { index } | A leaf output does not fit in u32, which a guest cannot commit. |
AggregateDomainMismatch { declared } | An aggregate declares a recursion domain other than the key it verifies under. |
ProgramMismatch { committed } | The proof is for a different program than the caller expects. |
InvalidProof | The STARK does not verify against the given key. |
Malformed(DecodeError) | The bytes are not a well-formed flat proof. |
DecodeError covers the byte layout: Truncated, NotWordAligned,
InvalidMinimal, UnknownHashTag, PublicCount,
NonCanonicalPublic, InvalidLeafFlag and KeyLength.
Constants
| Constant | Value / meaning |
|---|---|
PROGRAM_VK_LEN, VADCOP_VK_LEN_WORDS | 4: words in a program VK and in a vadcop_final key. |
ZISK_PUBLICS | 64: public outputs. |
PROGRAM_N_PUBLICS | 68: program VK plus outputs. |
IS_VADCOP_FINAL_PROOF | 1: the leaf flag value. |
GOLDILOCKS_ORDER | 0xFFFF_FFFF_0000_0001. |
SEED_TRAILER_TAG | u64::from_le_bytes(*b"ZISKSEED"). |
SEED_LEN_WORDS | 4: words in a seed. |
keys::VADCOP_FINAL_VK_{POSEIDON1,POSEIDON2,BLAKE3} | The release vadcop_final key of each family. |
keys::VADCOP_FINAL_COMPRESSED_VK_{POSEIDON1,POSEIDON2,BLAKE3} | The release vadcop_final_compressed key of each family. |
keys::PILFFLONK_VKEY_DIGEST_{POSEIDON1,POSEIDON2,BLAKE3} | The digest of each family's release pilfflonk.vkey.json. |
verify_vadcop_final_proof, committed_program_vk,
committed_is_aggregate and expected_proof_bytes were removed. Use
verify_saved_words (or decode_saved and verify), read
Verified::program_vk and Verified::is_aggregate, and call
proof_size.