Skip to main content

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.

Fold uncompressed proofs

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) with npm install into ~/.cache/pil2-proofman/node-deps. Without npm it fails with Cannot find pil2com.
  • Every later setup runs pil2com with Node.js. Without Node.js it fails with pil2com 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
guest/aggregations/l2.toml
programs = ["recurser_l2_guest"]
aggregate-publics = "circuits/aggregate.circom"
n-publics-agg = 64
KeyRequiredDescription
programsyes¹The leaf allow-list: guest programs whose proofs the recurser accepts as leaves. Order matters and is part of the recurser_id.
any-programyes¹true to accept leaves of any program instead of an allow-list.
aggregate-publicsyesThe AggregatePublics circuit, relative to the TOML.
n-publics-aggyesHow many of the 64 output slots the aggregation writes (1–64). The rest are zero-filled.
normalize-publicsnoAn optional NormalizePublics circuit, run on every input proof before AggregatePublics.
free-inputsnoHow 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 proofs

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

guest/aggregations/circuits/aggregate.circom
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:

host/build.rs
fn main() {
zisk_sdk::build_program("../guest");
}

Declare the guest and the aggregation in the host, the same way:

host/src/main.rs
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()?;
MethodDescription
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:

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

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

WhereHow
SDK, a Proofproof.with_setup_vk(&AGG.vk()?.vk).verify()?
SDK, a ProveResultresult.with_setup_vk(AGG.vk()?.vk).verify()?
CLIcargo-zisk verify -p abc.proof --setup-vk ~/.zisk/recurser/provingKey/recurser/<recurser_id>/recurser_aggregator.verkey.json
zisk-verifier, or a guestverify(&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​