On-Chain Verification
ZisK's final SNARK proofs are pilfflonk proofs: constant-size, and verifiable by a smart contract on any EVM-compatible chain. This guide walks through the verifier contracts, the four values a verification takes, how to produce them from a proof, deploying the contract, and calling it safely from your own Solidity code.
Prerequisites
Before starting, make sure you have:
- A pilfflonk SNARK proof, from
cargo-zisk prove --pilfflonkor a client built with.pilfflonk(). See Choosing a proof format for how to generate one. - The ZisK repository, for the contracts and the
cargo-zisk-devtool:git clone https://github.com/0xPolygonHermez/zisk.git. - Foundry or Hardhat for contract deployment.
- An RPC endpoint and a funded account on your target chain.
The verifier contracts
The contracts live in
zisk-contracts/,
one directory per hash family:
zisk-contracts/
├── blake3/
├── poseidon1/
└── poseidon2/
├── IZiskVerifier.sol # the interface your contracts call
├── ZiskVerifier.sol # the implementation
└── PilfflonkVerifier.sol # the generated pilfflonk verifier
Deploy the contract of the family your proof was made with, which is
the hash family of your proving key. A default ziskup install uses
blake3; ziskup --poseidon1 installs a Poseidon1 key. A proof of
one family does not verify on another family's contract.
ZiskVerifier.VERSION() returns "v1.4.0-alpha". The contracts are
generated by the release setup and verify proofs of the release's
pilfflonk key only. There is no PLONK verifier contract: ZisK ships
none, and PlonkVerifier.sol was removed.
The entry point is verifySnarkProof. It either returns silently or
reverts with InvalidProof():
interface IZiskVerifier {
function verifySnarkProof(
bytes32 programVK,
bytes32 rootCVadcopFinal,
bytes calldata publicValues,
bytes calldata proofBytes
) external view;
}
ZiskVerifier also has getRootCVadcopFinal() and
hashPublicValues(bytes32, bytes32, bytes), which are not part of the
interface. It also inherits verifyProof, the raw pilfflonk check,
which proves only that some proof satisfies some digest. Always call
verifySnarkProof.
Parameters:
| Parameter | Size | Description |
|---|---|---|
programVK | 32 bytes | The program identity the proof commits to: the ROM root of the guest ELF, or the recurser's key for an aggregate. |
rootCVadcopFinal | 32 bytes | The recursion root the proof was wrapped under: the release's vadcop_final key for a plain proof, the recurser's key for an aggregate. |
publicValues | 512 bytes | The 64 public outputs the guest committed. |
proofBytes | 6,752 bytes (blake3) / 2,208 bytes (Poseidon) | The pilfflonk proof, decoded as bytes32[211] (blake3) or bytes32[69] (Poseidon1, Poseidon2). |
How verification works
verifySnarkProof rebuilds the single public input the pilfflonk
proof commits to, then checks the proof against it:
uint256 publicValuesDigest = hashPublicValues(programVK, rootCVadcopFinal, publicValues);
// = uint256(sha256(abi.encodePacked(programVK, publicValues, rootCVadcopFinal))) % BN254_r
The preimage is, in this exact order:
programVK (32 bytes) | publicValues (512 bytes) | rootCVadcopFinal (32 bytes)
| Field | Encoding |
|---|---|
programVK | The 4 u64 limbs of the key, each big-endian, concatenated. |
publicValues | The 64 outputs, each as a u64 in little-endian, concatenated. A leaf's output is the u32 the guest committed, zero-extended. |
rootCVadcopFinal | The 4 u64 limbs of the key, each big-endian, concatenated. |
Because the proof commits to all three, a proof verifies only with
the exact programVK, rootCVadcopFinal and outputs it was made
for.
Producing the calldata
Export the four fields of a proof as JSON with cargo-zisk-dev export-solidity-calldata. Build the tool from the ZisK repository
first:
cargo build --release -p cargo-zisk --bin cargo-zisk-dev
cargo-zisk prove -e "$ELF" -i input.bin --pilfflonk -o proof.bin
./target/release/cargo-zisk-dev export-solidity-calldata -p proof.bin -o calldata.json
{
"programVK": "0x…",
"rootCVadcopFinal": "0x…",
"publicValues": "0x…",
"proofBytes": "0x…"
}
The command refuses a proof wrapped under a pilfflonk key other than this release's, since the release contract would reject it.
publicValues and proofBytes come from the proofThe exporter reads programVK and rootCVadcopFinal out of the
proof, which is fine for a test. In production, your contract holds
both as constants and the prover submits only publicValues and
proofBytes. See Security.
The SDK has no helper for the pilfflonk proofBytes encoding yet, so
cargo-zisk-dev export-solidity-calldata is the way to produce them.
For the other fields, PublicValues::hash_solidity(&program_vk, &root_c) returns the digest hashPublicValues computes, and
PublicValues::bytes_solidity returns its preimage, for a leaf
proof.
Getting programVK
programVK is derived from the guest ELF, so compute it from the
ELF you audited, not from a proof:
let vk = PROGRAM.vk()?; // under the local proving key's hash family
let program_vk: String = vk.vk.iter().map(|w| format!("{w:016x}")).collect();
println!("bytes32 constant PROGRAM_VK = 0x{program_vk};");
Getting rootCVadcopFinal
For a plain (leaf) proof, rootCVadcopFinal is the release's
vadcop_final key of the proof's family. It is what
ZiskVerifier.getRootCVadcopFinal() returns:
| Family | rootCVadcopFinal |
|---|---|
| blake3 | 0xedf3a1f810d95764e99c0db7affc52918f3bbc7444f222891d1675897a63cb2d |
| Poseidon1 | 0xe9414e134bb6945a148a79d44c8e850e5ef582a2b0e8dbfb2428ff0a515a6e66 |
| Poseidon2 | 0x646a1cf48f878ff644e4b7505066f0dedd448aa980b565c57f3383a1077ae41c |
For an aggregate, it is the recurser's own
key, AGG.vk()?.vk encoded the same way as programVK. An aggregate
also declares that key as its programVK, so pass the recurser's key
for both parameters.
Deploying the verifier
The verifier is stateless and immutable. Deploy it once per family
and reuse it for every guest program. From zisk-contracts/, with
Foundry:
cd zisk-contracts
forge create --root . \
--optimize --optimizer-runs 200 \
--rpc-url $RPC_URL \
--private-key $PRIVATE_KEY \
--broadcast \
blake3/ZiskVerifier.sol:ZiskVerifier
zisk-contracts/ has no foundry.toml, so --root . keeps Forge from
resolving the project root elsewhere. Without the optimizer the
verifier exceeds the contract size limit (CreateContractSizeLimit),
and recent Forge versions only simulate the deployment unless you pass
--broadcast.
Save the deployed address. You will pass it to your application contract in the next step.
The repository also has a Hardhat test that deploys the blake3 verifier and submits a proof:
cd zisk-contracts
../target/release/cargo-zisk-dev export-solidity-calldata \
-p test/blake3_pilfflonk.bin -o fixtures/blake3.json
npm install
ZISK_SOLIDITY_FIXTURE=fixtures/blake3.json \
ZISK_SOLIDITY_CONTRACT=blake3/ZiskVerifier.sol:ZiskVerifier npx hardhat test
Calling the verifier from your contract
Your contract pins the program and the recursion root as constants, and accepts only the outputs and the proof from the caller:
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;
interface IZiskVerifier {
function verifySnarkProof(
bytes32 programVK,
bytes32 rootCVadcopFinal,
bytes calldata publicValues,
bytes calldata proofBytes
) external view;
}
contract MyVerifiedApp {
IZiskVerifier public immutable verifier;
/// The ROM root of the guest ELF this app trusts.
bytes32 public constant PROGRAM_VK = 0x0000000000000000000000000000000000000000000000000000000000000000; // your guest's
/// The release vadcop_final key of the blake3 family.
bytes32 public constant ROOT_C_VADCOP_FINAL =
0xedf3a1f810d95764e99c0db7affc52918f3bbc7444f222891d1675897a63cb2d;
event ComputationVerified(uint64 result);
constructor(address _verifier) {
verifier = IZiskVerifier(_verifier);
}
function submitProof(bytes calldata publicValues, bytes calldata proofBytes) external {
// Reverts with InvalidProof() unless the proof is valid for these constants.
verifier.verifySnarkProof(PROGRAM_VK, ROOT_C_VADCOP_FINAL, publicValues, proofBytes);
// Read the result from the verified outputs, never from a separate argument.
emit ComputationVerified(outputAt(publicValues, 0));
}
/// Output slot `i`: 8 little-endian bytes.
function outputAt(bytes calldata publicValues, uint256 i) internal pure returns (uint64 v) {
for (uint256 j = 0; j < 8; j++) {
v |= uint64(uint8(publicValues[i * 8 + j])) << uint64(8 * j);
}
}
}
verifySnarkProof reverts with InvalidProof() if the proof is
invalid, so the rest of the function only runs when the proof is
accepted. The guest commits its outputs as 32-bit slots, so a value
the guest wrote with ziskos::io::commit(&x) for a u64 x spans
slots 0 and 1.
Security
programVK and rootCVadcopFinal must be constantsBoth keys MUST be constants of the calling contract, never values
taken from the caller or read off the submitted proof. If the caller
chooses programVK, they can submit a valid proof of any program,
for example one that simply commits the outputs it was given. If the
caller chooses rootCVadcopFinal, the verification is self-keyed and
authenticates nothing.
For an aggregate, both constants are the recurser's key. Pinning them together is what extends the recurser's leaf allow-list over the whole fold tree.
Also check the outputs themselves: a valid proof of the right program
for an irrelevant input is still useless to your application. Read
every value you act on from the verified publicValues, as above,
and validate it against your application's state.
Gas costs
Gas cost is dominated by the elliptic-curve operations inside the pilfflonk verifier. The cost is constant regardless of guest program complexity or input size. A blake3 proof's calldata is about three times larger than a Poseidon proof's (211 against 69 words), which costs more calldata gas.
Next steps
- Choosing a proof format: understand when to use the pilfflonk SNARK versus a STARK or Minimal STARK.
- Aggregating proofs: fold many proofs into one before verifying it on-chain.
- Managing guest I/O: read the public values the guest committed before passing them to the contract.