Threat model
Trust assumptions, attacker capabilities, protocol limits, and deployment integrity.
Opertus is designed to protect note ownership and values while allowing public asset movement. This page describes the assumptions required for those guarantees and the boundaries they do not cover, and it is the checklist for verifying any deployment.
Assets to protect
- Tokens held by the pool.
- Spend keys and one-time spend secrets.
- View keys and decrypted note data.
- Integrity of commitments, nullifiers, Merkle roots, and public proof inputs.
- Correct accounting around deposits, withdrawals, fees, and returned assets.
- Persistent assets or positions associated with a nonzero-salt clone.
Required assumptions
The intended guarantees require all of the following:
- Trusted setup. The Groth16 proof parameters were generated using a secure setup process.
- Verifier match. The deployed verifier contracts, their bytecode, and the pool configuration correspond exactly to the reviewed circuits, proof parameters, and deployment artifacts.
- Cryptography. Poseidon, BabyJubJub, BN254 Groth16, secp256k1 ECDH, HKDF, and XChaCha20-Poly1305 retain their expected security properties.
- Wallet hygiene. Wallets protect recovery phrases, view keys, spend keys, and decrypted local state, and use secure randomness.
- Adversarial tokens. Token behavior and external targets are treated as adversarial at contract boundaries; the contract's measured balance checks remain authoritative.
Actors and capabilities
| Actor | Can | Cannot or limit |
|---|---|---|
| Public observer or searcher | Read public pool and transaction data; reorder or sandwich a public external call | Learn note plaintexts or link a nullifier to its commitment without a relevant key |
| Note sender | Construct the recipient's one-time public key and encrypted note | Derive the recipient's one-time spend secret or nullifier key |
| View-key holder | Decrypt matching notes and the account's sent notes, read token and amount data, derive nullifiers, and track spends | Satisfy the BabyJubJub ownership check, spend with the view key alone, or find the account's clones |
| Receipt holder | Open one note, read its token, value and memo, and locate its transaction | Open any other note, tell whether the note was spent, or spend it |
| Spend-key holder | Derive a one-time spend secret when given the note and spend ephemeral | Scan or decrypt the pool with the spend key alone |
| Relayer | Submit or refuse a prepared call and apply offchain policy | Change proof-bound notes or settlement data while retaining a valid proof; receive a public contract fee |
| Pool owner | Pause entry points, set the executor once, and propose fee and treasury changes | Replace a set executor, renounce ownership, sweep reserves, or set fees above 10%; changes wait one day |
| External target | Receive the proof-authorized net amount, revert, or return assets | Bypass forbidden-target and post-call accounting checks |
Immediate pausing creates an availability and governance risk. External targets
must be treated as adversarial: an unfavorable return can violate minValue,
and assets omitted from the return list can remain on a persistent clone.
Enforced protocol controls
Under the required proof-system assumptions, the circuit and contracts jointly enforce:
| Area | Control |
|---|---|
| Ownership | Note ownership, commitment openings, nullifier derivation, and Merkle membership |
| Value | Value conservation, one-token inputs, and output values below 2^120 |
| Binding | The proof is bound to the chain ID, pool address, notes, public amount, and unshield payload |
| Replay | Permanent nullifier replay protection; a repeated commitment shares its nullifier, so it is spendable once |
| Trees | Known-root checks against the pool's one Poseidon LeanIMT, at most 32 levels |
| Accounting | Measured token balances around deposits, public outflows, and up to four returned assets |
| Governance | Delayed fee changes, fee caps, clone target restrictions, and cleared token approvals after an external call |
Known limits and non-goals
- Metadata. Transaction timing, network identity, public amounts, routes, and recipients are outside the note-privacy guarantee.
- Compromised client. A malicious or compromised client can leak keys, construct harmful calldata, or misrepresent what a user is approving.
- View-key leak. A compromised view key destroys note confidentiality, received and sent, even when funds remain unspendable.
- Disclosure is client-side. The pool does not check what a note's ciphertext or outgoing record contains. A custom client can write notes its own view key never reads back, so a view key is a complete history only for wallets that follow the selective disclosure specification. A receipt itself cannot be forged.
- Spend-key leak. A compromised recovery phrase or spend key plus note data can authorize spends.
- Unusual tokens. Arbitrary tokens may have transfer taxes, callbacks, rebasing, or other unusual behavior. The pool records measured arrivals, not nominal promises.
- Clone leftovers. Tokens omitted from a return list can remain on a clone. A persistent nonzero-salt clone should be treated as an independently addressable public account.
- Permanent roots. Root history is permanent; replay resistance comes from nullifiers, not root expiry.
Deployment integrity
A deployment must preserve the correspondence between the reviewed circuits, securely generated proof parameters, verifier contracts, and configured pool. Use these steps both to produce a deployment and to evaluate someone else's:
Freeze the statement
Review and freeze the exact Circom sources and compiler toolchain.
Generate proof parameters securely
Run a secure Groth16 setup for every circuit width. The process must prevent recovery or misuse of secret material that could compromise proof soundness. Independently verify the setup output.
Generate and match verifier contracts
Generate all four Solidity verifiers from the final parameters for their reviewed circuits, and verify that each one corresponds exactly to them.
Match deployed code and configuration
Confirm that the deployed bytecode matches the reviewed source. Read the chain ID, pool address, verifier set, executor, owner, treasury, and active fee configuration from the target chain.
Validate end to end
Generate and verify real proofs against the deployment, review current test results, and obtain an independent review covering the deployed commit and configuration.
Use verified addresses
Use only contract addresses published through a verified project channel.
Artifacts must stay in lockstep
Changing circuit source does not update an existing verifying key, and passing source-level circuit tests does not show that a deployed verifier matches the circuit. Contract accounting cannot compensate for a mismatched or compromised verifier.