Skip to main content

Aggregate

Folds two proofs into one recurser proof under an aggregation definition (a TOML file plus circom circuits). Covers the aggregation TOML, setting up a recurser with setup --aggregation, the local cargo-zisk aggregate command, its remote counterpart, and how to verify the result.

Fold two proofs into one recurser proof. A recurser is a recursive circuit built from an aggregation definition: it checks both input proofs and combines their public values with your own AggregatePublics circuit. Each input can be a leaf proof from cargo-zisk prove or the output of an earlier aggregate, so proofs can be folded into a tree. For the concepts and an end-to-end walkthrough, see Aggregating proofs.

cargo-zisk aggregate --aggregation <TOML> --proof-a <PROOF> --proof-b <PROOF> [OPTIONS]

The aggregation definition​

An aggregation is defined by a TOML file that must live at <programs>/aggregations/<name>.toml, where <programs> is the guest workspace (the directory with the guests' Cargo.toml). The file name <name> must be a valid identifier ([A-Za-z0-9_]+). Circuit paths are relative to the TOML file.

programs = ["recurser_hash_guest"]
aggregate-publics = "circuits/aggregate.circom"
normalize-publics = "circuits/normalize.circom"
n-publics-agg = 4
free-inputs = 12
KeyRequiredDefaultDescription
programsyes, unless any-programAllow-list of guest program names whose leaf proofs the recurser accepts. The order fixes each program's index. Mutually exclusive with any-program.
any-programfalseAccept leaf proofs of any guest program instead of an allow-list.
aggregate-publicsyesCircom file that defines template AggregatePublics(...) exactly once. It combines the two sides' publics into the folded publics.
normalize-publicsCircom file that defines template NormalizePublics(...) exactly once. It transforms a leaf's publics before folding.
free-inputs0Number of free (host-supplied, non-public) u64 inputs each side carries into the fold, shared by both circuits.
n-publics-aggyesNumber of public slots the aggregation populates, in 1..=64. The rest of the publics buffer is zero-filled.

Unknown keys are rejected. When the definition has a programs allow-list, the listed guests must already be built (release or debug profile), because their verification keys are derived from the ELFs. The recurser ID is content-addressed: the same definition always resolves to the same ID, both from the CLI and from the SDK's load_aggregation_program!.

Setting up a recurser​

Before folding, set up the recurser:

Recurser setup prerequisites

setup --aggregation needs:

  1. cargo-zisk setup --elf <guest ELF> already run for every guest in the definition's programs allow-list (otherwise it fails with ROM merkle setup has not been performed yet).
  2. Node.js and npm on PATH. npm installs the PIL compiler on the first setup (otherwise Cannot find pil2com…); Node.js runs it on every setup.

See Set up the recurser.

cargo-zisk setup --aggregation <programs>/aggregations/<name>.toml

The setup prints the Recurser ID and writes its artifacts under ~/.zisk/recurser/. The recurser's verification key is ~/.zisk/recurser/provingKey/recurser/<recurser-id>/recurser_aggregator.verkey.json. --aggregation accepts only --proving-key and --verbose; see Setup.

The recurser folds STARK proofs, so it needs the recursive stages of the proving key. If they are missing, setup fails with Global info file not found: ... Run setup --recursive first.

For a coordinator, use cargo-zisk remote setup --aggregation <TOML> instead. See Remote.

Flags​

FlagShortDefaultDescription
--aggregation <TOML>-arequiredAggregation definition: <programs>/aggregations/<name>.toml.
--proof-a <PATH>requiredFirst input proof (a cargo-zisk prove or aggregate output file).
--proof-b <PATH>requiredSecond input proof.
--free-inputs-a <U64,...>Comma-separated u64s: proof_a's free array. Must be exactly free-inputs values; omit only when the recurser declares none.
--free-inputs-b <U64,...>Comma-separated u64s: proof_b's free array, under the same rule.
--root-c-recurser-agg <LIMBS>recurser verkeyrootCRecurserAgg as 4 comma-separated decimal limbs. Omit to use the recurser's own verkey.
--output <OUTPUT>-o<unix-ts>-proof.binSave the recurser proof to this path. The default name uses the current Unix time in seconds.
--proving-key <PROVING_KEY>-kcached keyPath to a precomputed proving key.
--gpu-gfalseUse GPU acceleration.
--verbose-voffIncrease output verbosity. Pass -v for info, -vv for debug-level detail.

If the recurser's setup artifacts are missing, aggregate generates them first, so an explicit setup --aggregation is optional locally. The prerequisites apply either way.

On a leaf proof, the free array is passed through NormalizePublics; on an aggregated proof it is used directly.

Remote aggregation​

cargo-zisk remote aggregate takes the same --aggregation, --proof-a, --proof-b, --free-inputs-a, --free-inputs-b, --root-c-recurser-agg and --output flags, plus --metadata and --timeout. The recurser must already be set up on the cluster with remote setup --aggregation. Its --output default is <unix-ts>-<job_id>-proof.bin. See Remote.

Examples​

Set up the guest and the recurser, prove two leaves, then fold them (with Node.js and npm on PATH, as above):

cargo-zisk setup -e "$ELF"
cargo-zisk setup --aggregation guest/aggregations/hash.toml

cargo-zisk prove -e "$ELF" -i a.bin -o a.proof
cargo-zisk prove -e "$ELF" -i b.bin -o b.proof

cargo-zisk aggregate --aggregation guest/aggregations/hash.toml \
--proof-a a.proof --proof-b b.proof --output ab.proof \
--free-inputs-a "1,2,3,4,5,6,7,8,9,10,11,12" \
--free-inputs-b "100,101,102,103,104,105,106,107,108,109,110,111"

Fold an aggregated proof with another leaf:

cargo-zisk aggregate --aggregation guest/aggregations/hash.toml \
--proof-a ab.proof --proof-b c.proof --output abc.proof \
--free-inputs-a "101,103,105,107,109,111,113,115,117,119,121,123" \
--free-inputs-b "1000,1001,1002,1003,1004,1005,1006,1007,1008,1009,1010,1011"

The full example, with its circuits, is in examples/recurser/hash in the ZisK repository.

Outputs​

The command prints the Recurser ID, then:

--- AGGREGATE SUMMARY ---------
Recurser proof saved to ab.proof

No release publishes a recurser's key, so verify an aggregated proof under the recurser you trust with --setup-vk:

cargo-zisk verify --proof ab.proof \
--setup-vk ~/.zisk/recurser/provingKey/recurser/<recurser-id>/recurser_aggregator.verkey.json

See Verify.