Opertus

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

ComponentResponsibility
WalletDerives independent view and spend keys, creates encrypted notes, scans events, and derives one-time spend secrets
CryptographyImplements BabyJubJub stealth ownership and Poseidon note, nullifier, blind, and clone-salt hashes
Client and proverReconstructs Merkle trees, selects notes, builds witnesses, generates proofs, and prepares pool calls
CircuitsConstrains note openings, ownership, nullifiers, membership, outputs, clone salts, and value conservation
PoolHolds assets, verifies proofs, rejects spent nullifiers, appends leaves, accounts for fees, and moves public value
Executor and callerIsolates 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

FeeCalculated fromRecipient and settlement
Deposit feeMeasured token arrivalAccrues in the pool for the treasury; the note receives the net
Unshield feeGross public amountAccrues in the pool for the treasury; the recipient or call receives the net
Relayer feeOffchain wallet-relayer policyBecomes 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.

On this page