Proofs and settlement
Understand the Groth16 statement, public inputs, contract checks, and deployment requirements.
Opertus uses Groth16 proofs over BN254 to authorize private note spends. The proof hides note openings, spend secrets, amounts, and Merkle paths while exposing enough information for the pool to prevent replay and settle public value.
Circuit family
The transfer circuit is instantiated at four input widths:
| Circuit | Input notes | Output notes | Merkle depth |
|---|---|---|---|
transfer_1x3 | 1 | 3 | 20 |
transfer_2x3 | 2 | 3 | 20 |
transfer_4x3 | 4 | 3 | 20 |
transfer_8x3 | 8 | 3 | 20 |
The three outputs are represented internally with one additional zero-value slot.
The central conservation constraint is:
sum(inputs) = sum(outputs) + publicAmountpublicAmount is zero for a private transfer and the gross amount for an
unshield. Individual note values are less than 2^120; the public amount is
bounded by the value of eight maximum-sized notes.
What the proof checks
For every nonzero input, the circuit checks:
| Constraint | What it proves |
|---|---|
| Commitment opening | The commitment opens to the declared token, value, one-time owner key, randomness, and blind |
| Blind | The blind opens from the nullifier image and private blinding |
| Spend secret | The one-time spend secret derives the owner public key, so the prover owns the note |
| Nullifier | The nullifier derives from the private nullifier key and the commitment |
| Merkle path | The commitment is in the tree with the public root |
Every output commitment is constrained to the same token and a bounded value. A zero-value padded input skips membership but cannot be changed into value. A zero-value output remains a real commitment.
A nonzero clone salt is additionally constrained as:
cloneSalt = Poseidon(spendScalar, diversifier)Salt zero is accepted without a preimage and is used by ordinary transfers, plain unshields, and shared-call flows.
Public signals and domain binding
The exact public-signal order is part of verifier compatibility:
| Order | Signal | Purpose |
|---|---|---|
| 1 | Root | Selects the Merkle-tree state used by the proof |
| 2 | Public amount | Declares the gross value leaving private notes |
| 3 | Token | Binds every input and output to one asset |
| 4 | External-data hash | Binds the proof to its chain, pool, ciphertexts, and settlement data |
| 5 | Input nullifiers | Marks each consumed note as spent |
| 6 | Three output commitments | Inserts the newly created private notes |
| 7 | Clone salt | Selects the shared path or a persistent clone |
The external-data hash binds a transfer to:
chain ID, pool address, three encrypted output notesFor an unshield it also binds the target, calldata, protocol fee, return list, and clone salt. The pool supplies its own chain ID, address, and current fee while rebuilding this hash. A proof prepared for another pool, another chain, another fee rate, or modified transaction data fails.
Contract settlement
A valid proof is necessary but not sufficient for settlement. The pool also checks:
| Area | Check |
|---|---|
| Tree | The root is known and nonzero |
| Nullifiers | No nullifier is already marked spent |
| Commitments | No commitment is zero, out of field, repeated, or previously inserted |
| Fees | Protocol fees come from the live configuration |
| Token flow | Deposits and external-call returns are measured from actual balance changes; return count, uniqueness, and minimum values are enforced; the spendable token balance changes consistently with the gross |
These checks cover public state and arbitrary external-call behavior that the circuit cannot observe. If any check fails, Solidity reverts the entire call, including nullifier writes and leaf insertions.
Contract accounting does not compensate for a compromised verifier. A forged proof can invent authorization for a public withdrawal while still satisfying the pool's balance movement checks.
Replay and privacy
Historical roots remain valid indefinitely. Replay protection comes from the permanent nullifier registry, not root expiration. The same proof bytes may be resubmitted, but after one successful settlement its nullifiers are already spent.
The proof hides input values, output values, note owners, Merkle siblings, and private key material. Everything in the public signals and the external-data payload is visible onchain; the privacy model lists it in full.
Deployment requirements
A deployed verifier must correspond exactly to the reviewed circuit and its securely generated parameters. Follow the deployment integrity checklist before trusting any deployment.
Read architecture for the surrounding contract flow, the contract reference for entry points and errors, or transactions for integration steps.