Skip to main content

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​

FunctionReturnsDescription
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])boolverify 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])boolWhether 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>,
}
FieldDescription
program_vkThe program identity: the ROM root for a leaf, the recursion domain for an aggregate.
outputsThe 64 public outputs, as canonical field elements.
is_aggregateSome(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:

VariantMeaning
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.
InvalidProofThe 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​

ConstantValue / meaning
PROGRAM_VK_LEN, VADCOP_VK_LEN_WORDS4: words in a program VK and in a vadcop_final key.
ZISK_PUBLICS64: public outputs.
PROGRAM_N_PUBLICS68: program VK plus outputs.
IS_VADCOP_FINAL_PROOF1: the leaf flag value.
GOLDILOCKS_ORDER0xFFFF_FFFF_0000_0001.
SEED_TRAILER_TAGu64::from_le_bytes(*b"ZISKSEED").
SEED_LEN_WORDS4: 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.
Removed in 1.4.0-alpha

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.