Aggregating proofs
A recurser folds two ZisK proofs into one, and the result can be
folded again, so any number of proofs collapse into a single proof.
You decide how the two proofs' public values combine with a small
Circom circuit. This guide builds an aggregation for the l2 example
in examples/recurser,
folds three proofs from the SDK and from cargo-zisk, and verifies
the result.
How aggregation works
Each fold takes two proofs, A and B, and produces one recurser proof
whose 64 public outputs are computed from theirs by your
AggregatePublics circuit. The circuit can also check the two
proofs agree, for example that two block ranges are contiguous. A
fold whose check fails has no proof.
[100,200) [200,300) [300,400) leaf proofs, one per range
\ / |
(A + B) ------------ (AB + C) folds, checking A.end == B.start
|
[100, 400) one proof for the whole range
The two inputs of a fold can be leaves (ordinary VadcopFinal proofs
of a guest) or earlier folds. A recurser is identified by its
recurser_id, a content hash of its definition and of the local
proving key, so the same definition always gives the same recurser.
Prove every leaf with ProofKind::VadcopFinal (the default). A
VadcopFinalMinimal proof cannot be folded: compression strips the
leaf flag the recurser reads. The SDK refuses it.
Prerequisites
Setting up a recurser compiles its circuits. The ziskup bundle ships
the circom compiler and the recurser circuits, so the only extra tool
it needs is Node.js with npm on PATH:
- The first setup installs the PIL compiler (
pil2com) withnpm installinto~/.cache/pil2-proofman/node-deps. Without npm it fails withCannot find pil2com. - Every later setup runs
pil2comwith Node.js. Without Node.js it fails withpil2com exited with status 127.
Only the recurser setup needs Node.js: cargo-zisk aggregate and
verifying an aggregated proof do not.
Every program on the allow-list must also have been set up before the
recurser (client.setup(&LEAF) or cargo-zisk setup -e <guest ELF>),
or the recurser setup fails with
ROM merkle setup has not been performed yet.
Define the aggregation
An aggregation is a TOML file in an aggregations/ directory next to
the guest program, plus its circuits:
guest/
├── src/main.rs
└── aggregations/
├── l2.toml
└── circuits/
└── aggregate.circom
programs = ["recurser_l2_guest"]
aggregate-publics = "circuits/aggregate.circom"
n-publics-agg = 64
| Key | Required | Description |
|---|---|---|
programs | yes¹ | The leaf allow-list: guest programs whose proofs the recurser accepts as leaves. Order matters and is part of the recurser_id. |
any-program | yes¹ | true to accept leaves of any program instead of an allow-list. |
aggregate-publics | yes | The AggregatePublics circuit, relative to the TOML. |
n-publics-agg | yes | How many of the 64 output slots the aggregation writes (1–64). The rest are zero-filled. |
normalize-publics | no | An optional NormalizePublics circuit, run on every input proof before AggregatePublics. |
free-inputs | no | How many private u64 values the prover supplies per side at each fold. Default 0. |
¹ Set exactly one of programs or any-program = true. With neither,
the build fails.
any-program accepts anyone's proofsWith any-program = true, anyone can fold in a proof of a program
they wrote. The folded outputs are then only as trustworthy as the
checks in your circuits.
The aggregation circuit
AggregatePublics receives the 64 public slots of each side and
writes n-publics-agg output slots. Here it checks the two ranges
chain and merges them:
template AggregatePublics(nPublicsAgg) {
signal output aggregated_publics[nPublicsAgg];
signal input a_publics[ZISK_PUBLICS()];
signal input b_publics[ZISK_PUBLICS()];
var START_BLOCK = 0;
var END_BLOCK = 8;
var WORD = 8; // slots per 32-byte ABI field
// Check: A's range ends where B's begins.
for (var i = 0; i < WORD; i++) {
a_publics[END_BLOCK + i] === b_publics[START_BLOCK + i];
}
// Merge: start from A, end from B.
for (var i = 0; i < WORD; i++) {
aggregated_publics[START_BLOCK + i] <== a_publics[START_BLOCK + i];
aggregated_publics[END_BLOCK + i] <== b_publics[END_BLOCK + i];
}
// ... the other fields of the struct
}
With free-inputs = N, the template takes (nFreeInputs, nPublicsAgg)
and two more inputs, free_inputs_a[nFreeInputs] and
free_inputs_b[nFreeInputs]. Free inputs are supplied by the prover,
so the circuit must bind them to the proofs' publics. The hash
example binds a secret vector to the digest each proof commits:
BLAKE3(free_inputs_a) === a.digest.
The normalize circuit
NormalizePublics reshapes a leaf's outputs before folding. The
hash example uses it to reassemble 32-bit limbs into field
elements:
template NormalizePublics(nFreeInputs) {
signal input publics[ZISK_PUBLICS()];
signal input free_inputs[nFreeInputs];
signal output recurser_publics[ZISK_PUBLICS()];
signal output free_outputs[nFreeInputs];
// ...
}
It runs on every input, leaves and folds alike, though only a leaf's
output is used, so it must be satisfiable for any input. With an
allow-list of two or more programs, a NormalizePublics circuit must
declare signal input programIndex, which receives the leaf
program's position in programs (0 on a fold).
Set up the recurser
build_program in the host's build.rs builds the guest and resolves
every aggregations/*.toml next to it:
fn main() {
zisk_sdk::build_program("../guest");
}
Declare the guest and the aggregation in the host, the same way:
use zisk_sdk::{load_aggregation_program, load_program, AggregationProgram, GuestProgram};
static LEAF: GuestProgram = load_program!("recurser_l2_guest");
static AGG_L2: AggregationProgram = load_aggregation_program!("l2");
AggregationProgram derefs to a Recurser. It is built on first use,
and reads the local proving key under ~/.zisk/provingKey, even when
you prove on a remote coordinator: its recurser_id depends on it.
If you create aggregations/ after the first build, trigger one
rebuild (for example touch build.rs).
When the circuits are only known at runtime, build the recurser with
AggregationProgramBuilder instead:
use zisk_sdk::{load_circuit, AggregationProgramBuilder};
let recurser = AggregationProgramBuilder::new(load_circuit!("aggregate.circom"), 64)
.programs(&[&LEAF]) // or .any_program()
.build()?;
| Method | Description |
|---|---|
new(aggregate, n_publics_agg) | The AggregatePublics circuit and the number of output slots it writes. |
.programs(&[&GuestProgram]) | The leaf allow-list. Required unless .any_program() is set. |
.any_program() | Accept leaves of any program. Exclusive with .programs(..). |
.normalize(circuit) | Attach a NormalizePublics circuit. |
.free_inputs(n) | Free inputs per side. Default 0. |
.build() | Result<Recurser>. Fails with SdkError::Recurser when neither or both of .programs(..) and .any_program() are set. |
Then set the recurser up once, as you would a program:
client.setup(&*AGG_L2).run()?.await?;
On a RemoteClient, upload it first with client.upload(&*AGG_L2).run()?.
Fold proofs with zisk-sdk
Prove the leaves as VadcopFinal, then fold them with
aggregate_proofs:
use alloy_sol_types::SolValue;
use recurser_l2_common::{segment, BlocksInfoStruct};
use zisk_sdk::{
load_aggregation_program, load_program, AggregationProgram, GuestProgram, Proof, ProofKind,
ProverClient, ZiskStdin,
};
static LEAF: GuestProgram = load_program!("recurser_l2_guest");
static AGG_L2: AggregationProgram = load_aggregation_program!("l2");
async fn prove_segment(
client: &zisk_sdk::EmbeddedClient,
seg: &BlocksInfoStruct,
) -> Result<Proof, Box<dyn std::error::Error>> {
let stdin = ZiskStdin::new();
stdin.write_slice(&seg.abi_encode());
// Uncompressed: a minimal proof cannot be folded.
let result = client.prove(&LEAF, stdin).wrap(ProofKind::VadcopFinal).run()?.await?;
Ok(result.get_proof().clone())
}
#[tokio::main(flavor = "multi_thread")]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let client = ProverClient::embedded().build()?;
client.setup(&LEAF).run()?.await?;
client.setup(&*AGG_L2).run()?.await?;
let pa = prove_segment(&client, &segment(100, 200)).await?;
let pb = prove_segment(&client, &segment(200, 300)).await?;
let pc = prove_segment(&client, &segment(300, 400)).await?;
// Fold (A + B), then (AB + C).
let ab = client.aggregate_proofs(&AGG_L2, &pa, &pb).run()?.await?.get_proof().clone();
let abc = client.aggregate_proofs(&AGG_L2, &ab, &pc).run()?.await?.get_proof().clone();
// An aggregate verifies under its recurser's key.
let agg_vk = AGG_L2.vk()?.vk;
abc.with_setup_vk(&agg_vk).verify()?;
let folded: BlocksInfoStruct = abc.get_publics().read_abi()?;
println!("Folded three ranges into [{}, {}).", folded.startBlock, folded.endBlock);
Ok(())
}
A fold whose circuit check fails, such as folding A and C directly,
returns an error from .await. So does a leaf whose program is not
on the allow-list.
When the recurser declares free inputs, attach exactly n_free
values to each side with ProofExt::with_free_inputs. On a leaf they
are the leaf's free inputs; on an earlier fold they are its free
outputs:
use zisk_sdk::ProofExt;
let ab = client
.aggregate_proofs(&AGG_HASH, pa.with_free_inputs(va.to_vec()), pb.with_free_inputs(vb.to_vec()))
.run()?
.await?;
aggregate_proofs has no .run_sync(). Use .run() and .await.
See ProverClient › aggregate_proofs
for every setter, including .metadata(..) on a remote client.
Reading folded outputs
A fold's outputs are full field elements and may exceed 32 bits.
get_publics() truncates each slot to 32 bits. When your aggregation
writes wider values, read publics_full() instead, which returns
[program_vk(4) | outputs(64)]:
let full = abc.publics_full().expect("a Vadcop proof");
let first_output: u64 = full[4];
Fold proofs with cargo-zisk
The CLI reads the same TOML, so it derives the same recurser_id and
finds a setup made either way:
cd examples/recurser/l2
# Build the guest through the host's build.rs, and write the leaf inputs a.bin/b.bin/c.bin
cargo build --release -p recurser-l2-host
cargo run --release -p recurser-l2-host --bin gen-inputs-l2
ELF=guest/target/elf/riscv64ima-zisk-zkvm-elf/release/recurser_l2_guest
# Set up the leaf guest, then the recurser
cargo-zisk setup -e "$ELF"
cargo-zisk setup --aggregation guest/aggregations/l2.toml
# Prove each leaf (uncompressed, the default)
cargo-zisk prove -e "$ELF" -i a.bin -o a.proof
cargo-zisk prove -e "$ELF" -i b.bin -o b.proof
cargo-zisk prove -e "$ELF" -i c.bin -o c.proof
# Fold A + B, then AB + C
cargo-zisk aggregate --aggregation guest/aggregations/l2.toml \
--proof-a a.proof --proof-b b.proof --output ab.proof
cargo-zisk aggregate --aggregation guest/aggregations/l2.toml \
--proof-a ab.proof --proof-b c.proof --output abc.proof
With free inputs, pass --free-inputs-a and --free-inputs-b as
comma-separated u64 values. See
cargo-zisk aggregate for every
flag, and cargo-zisk remote aggregate for a coordinator.
Verify an aggregate
An aggregate verifies only under its recurser's key. No release
publishes one, so a bare verify() fails. Pass the key you trust:
| Where | How |
|---|---|
SDK, a Proof | proof.with_setup_vk(&AGG.vk()?.vk).verify()? |
SDK, a ProveResult | result.with_setup_vk(AGG.vk()?.vk).verify()? |
| CLI | cargo-zisk verify -p abc.proof --setup-vk ~/.zisk/recurser/provingKey/recurser/<recurser_id>/recurser_aggregator.verkey.json |
zisk-verifier, or a guest | verify(&saved.proof, &agg_key), with the key from recurser_aggregator.verkey.bin. See zisk-verifier. |
An aggregate must also declare the recurser's key as its program VK (its recursion domain), and verification refuses one that does not. The allow-list is checked only on leaves, so this is what stops a subtree folded by a different recurser from riding through: pinning the recurser's key makes its allow-list reach every leaf of the tree.
Wrap an aggregate into a SNARK
A folded proof can be wrapped into the final SNARK for on-chain
verification, on a client built with .pilfflonk():
let client = ProverClient::embedded().pilfflonk().build()?;
// ... fold as above ...
let wrapped = client.wrap_proof(&abc, ProofKind::Snark).run()?.await?;
wrapped.with_setup_vk(agg_vk).verify()?;
On-chain, pass the recurser's key as both programVK and
rootCVadcopFinal, as constants of your contract. See
On-chain verification.
Next steps
- Verifying a proof: the trust model for leaf proofs and custom setups.
- On-chain verification: verify a wrapped aggregate from Solidity.
- zisk-verifier: verify aggregates natively or inside a guest.