Opertus

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:

CircuitInput notesOutput notesMerkle depth
transfer_1x31320
transfer_2x32320
transfer_4x34320
transfer_8x38320

The three outputs are represented internally with one additional zero-value slot.

The central conservation constraint is:

sum(inputs) = sum(outputs) + publicAmount

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

ConstraintWhat it proves
Commitment openingThe commitment opens to the declared token, value, one-time owner key, randomness, and blind
BlindThe blind opens from the nullifier image and private blinding
Spend secretThe one-time spend secret derives the owner public key, so the prover owns the note
NullifierThe nullifier derives from the private nullifier key and the commitment
Merkle pathThe 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:

OrderSignalPurpose
1RootSelects the Merkle-tree state used by the proof
2Public amountDeclares the gross value leaving private notes
3TokenBinds every input and output to one asset
4External-data hashBinds the proof to its chain, pool, ciphertexts, and settlement data
5Input nullifiersMarks each consumed note as spent
6Three output commitmentsInserts the newly created private notes
7Clone saltSelects the shared path or a persistent clone

The external-data hash binds a transfer to:

chain ID, pool address, three encrypted output notes

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

AreaCheck
TreeThe root is known and nonzero
NullifiersNo nullifier is already marked spent
CommitmentsNo commitment is zero, out of field, repeated, or previously inserted
FeesProtocol fees come from the live configuration
Token flowDeposits 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.

On this page