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
| Key | Required | Default | Description |
|---|---|---|---|
programs | yes, unless any-program | Allow-list of guest program names whose leaf proofs the recurser accepts. The order fixes each program's index. Mutually exclusive with any-program. | |
any-program | false | Accept leaf proofs of any guest program instead of an allow-list. | |
aggregate-publics | yes | Circom file that defines template AggregatePublics(...) exactly once. It combines the two sides' publics into the folded publics. | |
normalize-publics | Circom file that defines template NormalizePublics(...) exactly once. It transforms a leaf's publics before folding. | ||
free-inputs | 0 | Number of free (host-supplied, non-public) u64 inputs each side carries into the fold, shared by both circuits. | |
n-publics-agg | yes | Number 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:
setup --aggregation needs:
cargo-zisk setup --elf <guest ELF>already run for every guest in the definition'sprogramsallow-list (otherwise it fails withROM merkle setup has not been performed yet).- Node.js and npm on
PATH. npm installs the PIL compiler on the first setup (otherwiseCannot 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
| Flag | Short | Default | Description |
|---|---|---|---|
--aggregation <TOML> | -a | required | Aggregation definition: <programs>/aggregations/<name>.toml. |
--proof-a <PATH> | required | First input proof (a cargo-zisk prove or aggregate output file). | |
--proof-b <PATH> | required | Second 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 verkey | rootCRecurserAgg as 4 comma-separated decimal limbs. Omit to use the recurser's own verkey. | |
--output <OUTPUT> | -o | <unix-ts>-proof.bin | Save the recurser proof to this path. The default name uses the current Unix time in seconds. |
--proving-key <PROVING_KEY> | -k | cached key | Path to a precomputed proving key. |
--gpu | -g | false | Use GPU acceleration. |
--verbose | -v | off | Increase 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.