Architecture
Understand the pool, Merkle trees, circuits, transaction client, executor, and fee boundaries.
Opertus separates private authorization from public settlement. Wallet code creates and decrypts notes, a client reconstructs state and builds witnesses, Groth16 proves note ownership and conservation, and the pool contract enforces public accounting.
Components
| Component | Responsibility |
|---|---|
| Wallet | Derives independent view and spend keys, creates encrypted notes, scans events, and derives one-time spend secrets |
| Cryptography | Implements BabyJubJub stealth ownership and Poseidon note, nullifier, blind, and clone-salt hashes |
| Client and prover | Reconstructs Merkle trees, selects notes, builds witnesses, generates proofs, and prepares pool calls |
| Circuits | Constrains note openings, ownership, nullifiers, membership, outputs, clone salts, and value conservation |
| Pool | Holds assets, verifies proofs, rejects spent nullifiers, appends leaves, accounts for fees, and moves public value |
| Executor and caller | Isolates one public external call and returns up to four assets to the pool for shielding |
No component stores a private balance onchain. The balance is the sum of unspent notes a wallet can decrypt and authorize.
Merkle trees and events
Each commitment is one leaf in the pool's single Poseidon LeanIMT (zk-kit). A
node without a right child moves up unhashed instead of being hashed with a zero,
and the depth grows with the leaf count up to 32 levels, so the tree holds up to
2^32 leaves and never rolls over.
The pool inserts every leaf of a call in one batch: a spend's three outputs, then any return notes. Each level is hashed once for the whole batch, with the same root as inserting the leaves one at a time. The pool does not check that a commitment is new: a repeated commitment takes its own leaf, but both copies share one nullifier, so only one can be spent. The pool records only the root after the call's final leaf, and every recorded root remains known for the pool's lifetime. The empty root is 0 and is never known.
Permanent roots do not enable double-spends: each consumed note publishes a nullifier, and the pool permanently rejects a repeated nullifier.
Tree invariants
One tree for the pool's lifetime, one recorded root per call, and every recorded root remains known. Replay protection comes from the permanent nullifier registry, not root expiration.
Clients reconstruct this state from commitment, return, and nullifier events. Leaf indexes are consensus-relevant integration data: the client appends leaves in index order and stops on a gap.
Deposit path
Deposits are proofless. The pool pulls ERC-20 tokens or accepts native ETH, measures what arrived, accrues the deposit fee, and checks that the retained amount exactly equals the submitted note value. It then recomputes the note commitment and inserts one leaf.
This contract-side measurement keeps taxed tokens from creating notes larger than pool reserves. A malformed commitment, or one whose opening does not hash to it, is rejected before the root is committed.
Spend path
Transfers and unshields share one circuit family with widths 1, 2, 4, and 8. Each produces exactly three notes. The contract sequence is:
Require a known root
The spend must reference a root already recorded by the pool.
Bind the settlement request
The pool reconstructs the transaction's domain-bound external-data hash.
Verify authorization
The pool verifies the selected-width proof.
Consume the inputs
The pool rejects and marks input nullifiers.
Create the private outputs
The pool validates and inserts three distinct output commitments.
Settle public value
For an unshield, the pool accounts for fees and moves the public amount.
Commit returns and the root
The pool inserts any valid return notes and commits the final root.
Failed transactions change nothing
Any revert rolls back every step. A failed proof cannot consume a nullifier or advance the tree, so you can fix the problem and try again.
External calls and returns
An unshield with calldata sends the net amount through a caller managed by the executor. The call has one direct target; any further routing occurs within that target's calldata and remains public.
The pool snapshots return-token balances and shields each listed asset from the
amount that actually arrives. A return is capped by the measured flow and must
meet its minValue. There may be at most four distinct return tokens. Return
commitments are inserted in the same tree as the spend's three outputs.
Salt zero uses the shared call address. A nonzero salt maps to a persistent
CREATE2 address and is constrained by the proof. This is useful when an
external position depends on stable msg.sender, but it also makes verifier
integrity essential.
Fees and administration
| Fee | Calculated from | Recipient and settlement |
|---|---|---|
| Deposit fee | Measured token arrival | Accrues in the pool for the treasury; the note receives the net |
| Unshield fee | Gross public amount | Accrues in the pool for the treasury; the recipient or call receives the net |
| Relayer fee | Offchain wallet-relayer policy | Becomes one of the three private output notes; it is not a contract transfer |
The owner can pause transaction entry points, set the executor once, and propose fee and treasury changes. Fee rates are capped at 10% and wait one day before application. Ownership cannot be renounced because doing so while paused could freeze the system permanently.
Continue with keys and notes for private state, the contract reference for entry points, events, and errors, or transactions for the operational flow.