Skip to content

Run a trusted setup ceremony

View Markdown

Every Groth16 circuit needs a trusted setup, and whoever knows the setup’s secret randomness (the “toxic waste”) can forge proofs. A multi-party computation (MPC) ceremony spreads that randomness across many independent contributors. The result is sound as long as at least one contributor was honest and destroyed their secret. This page walks through a ceremony with snarkjs and ZeroJ’s zeroj-ceremony tool, from circuit freeze to proving with the final key.

New to the idea? Read Trusted setup, explained first.

You need a ceremony for any real deployment of a Groth16 circuit: anything beyond local development, tests, and throwaway demos. ZeroJ’s in-process setup (Groth16Keys.setupInMemory, setupToStore, Groth16SetupBLS381.setup) is single-party by design and only runs behind the zeroj.allowInsecureTrustedSetup opt-in.

Ceremony · step 1 / 8
Coordinatorruns the ceremony
Artifacts
ownership.r1csPUBLIC0x419d…c4dc
prepared .ptauPUBLICverified
key_0000.zkeyPUBLIC0x5cf7…c4dd
key_final.zkeyPUBLIC0xc2d8…01dc
manifest SHA-256KEEP0x41e9…122e
verification keyPINNED0x1cba…829b
zeroj-ceremony export-r1cssnarkjs powersoftau verify / prepare phase2snarkjs groth16 setupsnarkjs zkey beaconzeroj-ceremony finalize --sha256 <verified hash>snarkjs zkey export verificationkey
file matches the verified hash, or it stopsevery point checked: on the curve and in the subgroupwrites a new store; the folder must not exist yet--allow-unpinned instead of --sha256: local tests only
Contributorsindependent people

Waiting for the first key.

  1. Alicekey_0000 → key_0001
  2. Bobkey_0001 → key_0002
  3. Carolkey_0002 → key_0003
  4. Alice, Bob and Carol will each add one step
each person's randomnessSECRETused once, never written, gone
Carol's public attestationreceived key_0002 0x5af7…0067produced key_0003 0x59f7…62a2contribution hash 0xd326…5475"the entropy was destroyed"
Anyoneusers, auditors
Public transcriptcircuit source commit + .r1cs hash.ptau source and verify outputkey_0000 hash, before anyone contributesevery attestation, hashes chainedbeacon: announced first, then its valuezkey verify outputfinal key and verification-key hashes

You can rebuild the .r1cs from the tagged source and compare hashes.

snarkjs zkey verify ownership.r1cs pot25_final.ptau key_final.zkeyevery contribution re-checked, ZeroJ's includedThe checking tool is never the one ZeroJ wrote.
deployed verification key matches the verified one

1. Freeze the circuit

A ceremony binds to one exact circuit. Review it, add the public inputs your validator needs to stop replays (you can't add them later), tag the commit and export the R1CS. Any later change needs a new ceremony.

2. Phase 1: powers of tau

Take a BLS12-381 powers-of-tau file from an attested public ceremony, or run your own. Verify it, prepare it for phase 2 and publish the verify output. One file serves every circuit up to its size.

3. Create the first key

snarkjs groth16 setup combines the circuit and the powers of tau into key_0000.zkey. Publish its hash and the R1CS hash before anyone contributes, so everyone can see what the chain starts from.

4. Contributions

Each person checks the hash of the key they received, mixes in fresh secret randomness with zeroj-ceremony contribute or snarkjs, and sends the new key on. Their randomness is used once and never written down. Each publishes an attestation, so the hashes chain from one key to the next.

5. Public beacon

The coordinator announces a beacon source in advance, such as a future block hash, then applies it to get key_final.zkey. Because nobody could predict it, the last contributor can't steer the result.

6. Anyone verifies

snarkjs zkey verify re-checks every contribution against the circuit and the powers of tau, including ones made with ZeroJ's tool. Anyone can run it, so nobody has to trust the coordinator. Only the key that passes gets hashed for the next step.

7. Finalize into ZeroJ

zeroj-ceremony finalize --sha256 imports only a file matching the verified hash, checks every point, and writes a new proving-key store. It prints a manifest hash: keep it somewhere trusted and pass it when you load the store. It doesn't re-check the ceremony itself; step 6 did.

8. Pin and deploy

Export the verification key, record its hash and test a proof off-chain and on-chain. On Cardano the key is a script parameter, so the script's hash pins it. Anyone can check that the deployed key matches the verified one.

PUBLIC published in the transcriptSECRET never leaves one machineKEEP not secret, but store it somewhere trustedHash values are illustrative.

Every artifact stays in the snarkjs .zkey format, and the independent check is always snarkjs zkey verify, which re-checks every contribution, including ones made with ZeroJ’s tool. The tool that checks the ceremony is never the tool ZeroJ wrote.

A ceremony binds to one exact R1CS. Any later change (a gadget, an array size, the order of public inputs, a compiler change that alters the constraint shape) needs a new ceremony. Before starting:

  • Finalize and review the circuit, including invalid-witness tests (Test your circuits).
  • Add the public inputs your validator will use for replay binding. You can’t add them later.
  • Tag the source commit and record the compiler’s constraint count.

You can rehearse the machinery on a throwaway circuit at any time (see Rehearse first).

Phase 1 is universal: one prepared .ptau serves every circuit up to its size, on the same curve. It must be BLS12-381. Two options:

Reuse an attested ceremony. ZeroJ’s runbook points to Filecoin’s BLS12-381 powers of tau (2²⁷). Whatever the source, verify it and prepare it yourself:

Terminal window
snarkjs powersoftau verify pot_imported.ptau
snarkjs powersoftau truncate pot_imported.ptau
snarkjs powersoftau prepare phase2 pot25.ptau pot25_final.ptau

Run your own. Contributors take turns, then a beacon closes it:

Terminal window
snarkjs powersoftau new bls12-381 25 pot_0000.ptau
snarkjs powersoftau contribute pot_0000.ptau pot_0001.ptau --name="<who>" -v
# ... more contributors ...
snarkjs powersoftau beacon pot_<last>.ptau pot_beacon.ptau <beaconHash> 10 -n="final beacon"
snarkjs powersoftau prepare phase2 pot_beacon.ptau pot25_final.ptau

At 2²⁵ these steps are heavy (the runbook budgets hours per phase-1 contribution and far longer for prepare phase2), but you do them once. Publish the prepared file and its verify output.

Export your frozen circuit’s R1CS with the ZeroJ tool, create the initial key with snarkjs, and publish both hashes before contributions begin:

Terminal window
zeroj-ceremony export-r1cs \
--circuit com.example.OwnershipProof \
--circuit-jar my-circuits.jar \
--out ownership.r1cs
snarkjs groth16 setup ownership.r1cs pot25_final.ptau key_0000.zkey
shasum -a 256 ownership.r1cs key_0000.zkey

--circuit takes the @ZKCircuit class or its generated *Circuit companion (any class with a static build() that returns a CircuitBuilder). export-r1cs compiles for BLS12-381 and loads the class reflectively, so run it with the fat jar on a JVM rather than the native binary. From code, R1CSSerializer.serialize(r1cs) produces the same iden3 .r1cs bytes.

Contributors need the zeroj-ceremony tool (or snarkjs; both produce compatible contributions).

Get the tool. When a ZeroJ release publishes the ceremony distributables, they’re attached to the GitHub release: a fat jar (zeroj-ceremony-<version>-all.jar, needs Java 25) and native zips for linux-x86_64, linux-arm64, macos-arm64, and windows-x86_64 (no Java needed). Or build it from a ZeroJ checkout:

Terminal window
./gradlew :zeroj-tools:fatJar # zeroj-tools/build/libs/zeroj-ceremony-<v>-all.jar
./gradlew :zeroj-tools:nativeDistZip # needs a GraalVM JDK; zeroj-tools/build/distributions/

Contribute. Check what you received against the coordinator’s published hash, contribute, and send the result back:

Terminal window
shasum -a 256 key_0007.zkey # must match the published hash
zeroj-ceremony contribute --in key_0007.zkey --out key_0008.zkey --name "Alice / Example Org"
shasum -a 256 key_0008.zkey
OptionRequiredMeaning
--in <file>yesThe .zkey you received
--out <file>yesThe .zkey you send back
--name <text>noYour name in the public transcript (default zeroj contributor)

The tool draws your secret from the OS secure random source, uses it once, and never writes it anywhere. It prints a Contribution Hash; copy it into your attestation. The equivalent snarkjs command is snarkjs zkey contribute key_0007.zkey key_0008.zkey --name="...". ZeroJ’s documentation reports its contributor at roughly 0.9 hours versus 2.5 to 3 hours for snarkjs on a 19M-constraint key (about 30 GB); budget about twice the .zkey size in free disk.

Publish an attestation, for example as a gist or a pull request to the ceremony’s transcript repository:

Ceremony: <circuit name>, contribution #8
Who: <name/org>, <date>
Received: key_0007.zkey sha256=<...>
Produced: key_0008.zkey sha256=<...>
Contribution Hash: <as printed by the tool>
Machine: <e.g. personal laptop, offline>
I confirm the entropy was generated fresh and destroyed after use.

After contributing there’s nothing left to keep secret. What matters is that nobody observed the machine during the contribution.

To embed contributions in your own service or wallet, zeroj-tools exposes the same step as a library call: ZkeyContributor.contribute(in, out, name) returns the contribution hash.

Terminal window
# 1. Beacon: announce the source BEFORE the last contribution lands,
# e.g. "the hash of Bitcoin block N" or "drand round R" for a future N or R
snarkjs zkey beacon key_0012.zkey key_final.zkey <beaconHashHex> 10 -n="final beacon"
# 2. The independent check anyone can re-run. Stop if it fails.
snarkjs zkey verify ownership.r1cs pot25_final.ptau key_final.zkey || exit 1
# 3. Hash the key only after verification succeeds
VERIFIED_ZKEY_SHA256=$(shasum -a 256 key_final.zkey | awk '{print $1}')
# 4. The verification key for your verifiers and validators
snarkjs zkey export verificationkey key_final.zkey verification_key.json
# 5. Convert to a ZeroJ proving-key store (streaming, multi-GB safe; ./ownership-pk must not exist)
zeroj-ceremony finalize --sha256 "$VERIFIED_ZKEY_SHA256" --zkey key_final.zkey --pk-store ./ownership-pk

finalize is ZkeyPkStoreImporter.importToPkStore(zkey, dir, expectedSha256) behind a CLI, and you can call that method directly instead. It refuses a file whose SHA-256 doesn’t match, checks the key’s structure and every point (curve, subgroup and canonical encoding), writes a new store and seals it. It prints the store’s manifest SHA-256: keep it outside the store, with your deployment config, and use it for every later load. --allow-unpinned replaces --sha256 for local tests only; it doesn’t authenticate the source. Add --circuit-fingerprint <exact> if you want circuit-aware checks; it has to be set here, because a sealed store can’t be bound later. finalize doesn’t re-check the transcript or that the key matches your circuit: that’s snarkjs zkey verify’s job.

The imported store works like any other key bundle. Remember that snarkjs appends one binding row per public input (plus one for the constant wire), so pass them to the prover:

int numPublic = r1cs.numPublicInputs();
try (var keys = Groth16Keys.load(Path.of("ownership-pk"), manifestSha256)) { // printed by finalize
var proof = keys.prove(witness,
ZkeyPkStoreImporter.snarkjsConstraints(r1cs.constraints(), numPublic));
}

For the packed path and Groth16Pipeline, pass numPublic + 1 as the binding-row count. See Prove with Groth16. Before going live, generate a test proof and verify it off-chain and on-chain against the exported verification key.

Treat the ceremony outputs as pinned artifacts, and check their hashes where you load them:

  • Record the SHA-256 of ownership.r1cs, key_final.zkey, verification_key.json, and the prepared .ptau in your repository or release notes.
  • The in-memory importers accept an expected hash and refuse a mismatch before parsing: ZkeyImporterBLS381.importZkeyFull(bytes, expectedSha256) (keys up to 128 MB) and PtauImporterBLS381.importPtau(input, maxPoints, expectedSha256).
  • ZkeyPkStoreImporter.importToPkStore(zkey, dir, expectedSha256) and zeroj-ceremony finalize --sha256 refuse a mismatched file too, and print the store’s manifest SHA-256. Load the store with Groth16Keys.load(dir, manifestSha256) so a changed store is refused.
  • Pin the verification key your on-chain validator is built with, and treat any change as a new deployment.

In a public repository, publish:

  • the .r1cs, its hash, and the exact circuit source commit it was built from
  • the prepared .ptau source, hash, and verify output
  • every intermediate .zkey hash and every contributor attestation
  • the beacon announcement and the beacon value
  • the snarkjs zkey verify output and the final key and verification-key hashes

Coordinator checklist, from ZeroJ’s runbook:

  • Circuit frozen (reviewed, replay-binding public inputs added) and tagged in git
  • Prepared .ptau acquired, and its verify output published
  • .r1cs and key_0000.zkey hashes published before contributions
  • At least 3 contributors from independent organizations, attestations published
  • Beacon source announced in advance, applied, and published
  • zkey verify passes; final key and verification-key hashes published
  • finalize run; a test proof verified off-chain and on-chain

If you’re a user or auditor of someone else’s deployment, you don’t have to trust the coordinator. Check:

  1. The circuit. Rebuild the .r1cs from the published source commit and compare hashes, so you know the key binds to the circuit you reviewed.
  2. The transcript. Run snarkjs zkey verify <circuit.r1cs> <prepared.ptau> <key_final.zkey> yourself.
  3. The contributors. Several independent, identifiable people or organizations, each with a published attestation whose hashes chain from one key to the next.
  4. The beacon. It was announced before the last contribution and matches the public value.
  5. The deployed key. The verification key in the validator or service matches the one exported from the verified final key.

If any link is missing, treat the setup as untrusted.

ZeroJ ships a rehearsal script that runs this whole flow on a tiny circuit, mixing ZeroJ and snarkjs contributions, a beacon, zkey verify, and finalize: docs/ceremony/rehearsal.sh. It needs snarkjs on your PATH, Java 25, and a built ZeroJ checkout.

Further reading: ceremony user guide, coordinator runbook, ADR-0031.