Skip to main content

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 --pilfflonk or 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-dev tool: 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():

IZiskVerifier.sol
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:

ParameterSizeDescription
programVK32 bytesThe program identity the proof commits to: the ROM root of the guest ELF, or the recurser's key for an aggregate.
rootCVadcopFinal32 bytesThe recursion root the proof was wrapped under: the release's vadcop_final key for a plain proof, the recurser's key for an aggregate.
publicValues512 bytesThe 64 public outputs the guest committed.
proofBytes6,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:

ZiskVerifier.sol
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)
FieldEncoding
programVKThe 4 u64 limbs of the key, each big-endian, concatenated.
publicValuesThe 64 outputs, each as a u64 in little-endian, concatenated. A leaf's output is the u32 the guest committed, zero-extended.
rootCVadcopFinalThe 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:

bash
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
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.

Only publicValues and proofBytes come from the proof

The 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:

host/src/main.rs
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:

FamilyrootCVadcopFinal
blake30xedf3a1f810d95764e99c0db7affc52918f3bbc7444f222891d1675897a63cb2d
Poseidon10xe9414e134bb6945a148a79d44c8e850e5ef582a2b0e8dbfb2428ff0a515a6e66
Poseidon20x646a1cf48f878ff644e4b7505066f0dedd448aa980b565c57f3383a1077ae41c

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:

bash
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:

bash
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:

MyVerifiedApp.sol
// 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 constants

Both 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​