Opertus

Contract reference

Pool entry points, views, events, and custom errors.

The pool is OpertusPool, which inherits the Merkle tree from MerkleTreeWithHistory and fee logic from ProtocolFees. External calls go through OpertusExecutor, which runs each call from an OpertusCaller clone. Most integrations should build these calls with OpertusClient rather than encoding them directly.

Entry points

All three are nonReentrant and revert while the pool is paused.

deposit

function deposit(
    address token,          // address(0) for native ETH
    uint256 transferAmount, // gross amount pulled, or msg.value for ETH
    uint256 noteValue,      // predicted net after the deposit fee
    uint256 ownerPubKey,
    uint256 randomness,
    uint256 blind,
    uint256 commitment,
    bytes calldata note     // packed note, see Types
) external payable;

Pulls transferAmount, measures what arrived, accrues the deposit fee, and inserts one leaf only if arrived - fee == noteValue and the opening hashes to commitment. No proof is required.

transfer

function transfer(
    Width width,
    Proof calldata proof,
    uint256 root,
    address token,
    uint256[] calldata nullifiers,
    uint256[3] calldata commitments,
    bytes[3] calldata notes
) external;

Verifies a proof with publicAmount = 0, marks the nullifiers spent, and inserts the three output commitments. No token moves.

unshield

function unshield(
    Width width,
    Proof calldata proof,
    uint256 root,
    address token,
    uint256 gross,
    address target,
    bytes calldata data,
    uint256[] calldata nullifiers,
    uint256[3] calldata commitments,
    bytes[3] calldata notes,
    IOpertusExecutor.ReturnNote[] calldata returning,
    uint256 cloneSalt
) external;

Verifies a proof with publicAmount = gross, accrues gross * unshieldFeeBps / 10_000, and sends the net:

datacloneSaltBehavior
Empty0Plain transfer of the net to target; returning must be empty
Nonempty0One call to target from the shared clone
NonemptyNonzeroOne call to target from the user's persistent CREATE2 clone
EmptyNonzeroSweep: gross and target must be zero, and returning lists what to shield from the clone

Up to four returning tokens are shielded as return notes after the call.

For a call, the pool sends the net straight to executor.cloneOf(cloneSalt), then asks the executor to deploy that clone if needed and run the call. The executor never holds funds. A sweep emits no Unshielded; its return notes are its record.

Fee-on-transfer tokens cannot go through a clone. The clone receives less than the net, so the call reverts with CloneUnderpaid. Unshield such a token with empty data and salt 0, which pays target directly.

Administration and fees

FunctionCallerEffect
claimFees(token)AnyoneSends accrued fees for token to the treasury
proposeFees(depositBps, unshieldBps, treasury)OwnerStarts the one-day delay; each rate is capped at 1000 bps (10%)
applyFees()AnyoneApplies the proposal once FEE_DELAY has passed
setExecutor(executor)OwnerSets the executor once; a second call reverts
pause() / unpause()OwnerStops or resumes the three entry points immediately
renounceOwnership()—Always reverts

Ownership uses OpenZeppelin Ownable2Step.

Types

enum Width { One, Two, Four, Eight } // 1, 2, 4, or 8 input notes

struct Proof {
    uint256[2] a;
    uint256[2][2] b;
    uint256[2] c;
}

struct ReturnNote { // in IOpertusExecutor
    address token;
    uint256 minValue;
    uint256 ownerPubKey;
    uint256 randomness;
    uint256 blind;
    bytes note;
}

An encrypted note is one packed bytes value, emitted exactly as it was passed:

BytesField
0–32View ephemeral: compressed secp256k1 public key (33 bytes)
33–64Spend ephemeral: packed BabyJubJub point (32 bytes)
65–66View tag (2 bytes)
67–90XChaCha20 nonce (24 bytes)
91–Ciphertext with its Poly1305 tag: 208 bytes for a note, 176 for a return note
after the ciphertextOptional outgoing record (116 bytes): the recipient meta-address sealed under the sender's outgoing key, present when the note pays someone other than the sender

The plaintext is the opening plus a 32-byte memo: 192 bytes for a note, 160 for a return note, which carries no amount. The outgoing record lets the sender's wallet rebuild its sent history from the seed, and a per-note key lets either side disclose one note. See selective disclosure. See @opertus/wallet.

The pool reads only the view tag, for tokenAndTag; a note shorter than 67 bytes gets tag 0. Build and parse notes with packEncryptedNote and unpackEncryptedNote from @opertus/core.

Views

ViewReturns
isKnownRoot(root) / knownRoots(root)Whether a root was ever recorded; roots never expire
getLastRoot()The current root; 0 while the tree is empty
nextLeafIndex() / treeDepth()The next free leaf and the current LeanIMT depth
nullifierSpent(nullifier)Whether a nullifier is spent
depositFeeBps() / unshieldFeeBps()Live fee rates in basis points
treasury() / accrued(token)Fee recipient and unclaimed fees per token
proposedDepositBps(), proposedUnshieldBps(), proposedTreasury(), proposedAt()The pending fee proposal; proposedAt is 0 when none
quote(amount, bps)amount * bps / 10_000
executor()The executor contract
executor.cloneOf(cloneSalt)The clone address for a salt, deployed or not. Reverts for a salt outside the field
verifier1x3() … verifier8x3()The verifier for each width

Constants: MAX_DEPTH = 32, MAX_NOTE_VALUE = 2^120 - 1, MAX_PUBLIC_AMOUNT = 8 * MAX_NOTE_VALUE, MAX_RETURNS = 4, MAX_FEE_BPS = 1000, FEE_DELAY = 1 days, and SNARK_FIELD.

Events

Clients reconstruct private state from the first three events, and public history from Unshielded and Called. leafIndex is consensus-relevant: the pool has one tree, and leaves are appended in index order. In an unshield, the outputs and return notes are inserted in one batch after the external call, so their events follow it.

The pool does not check that a commitment is new. A repeated commitment takes its own leaf, but both copies have the same nullifier, so only one can be spent. Within one call, the outputs and return notes must still differ. Wallets treat the first leaf as the note and ignore later copies.

EventFieldsEmitted when
NoteCommittedcommitment (indexed), leafIndex (indexed), tokenAndTag (indexed: token address shifted left 16 bits, OR the view tag), encryptedNote (the packed note)A deposit or spend output is inserted
ReturnShieldedcommitment (indexed), leafIndex (indexed), tokenAndTag (indexed, as in NoteCommitted), token, value, ownerPubKey, encryptedNote (the packed note)A return note is inserted after an external call; value is the measured amount
NullifierSpentnullifier (indexed)An input note is spent
Unshieldedtoken (indexed), recipient (indexed), gross, protocolFeeAn unshield settles; not emitted by a sweep
ProtocolFeeAccruedtoken (indexed), amountA deposit or unshield fee is recorded
ProtocolFeeClaimedtoken (indexed), treasury (indexed), amountclaimFees pays the treasury
FeesProposeddepositFeeBps, unshieldFeeBps, treasury, availableAtThe owner proposes new fees
FeesUpdateddepositFeeBps, unshieldFeeBps, treasuryFees are set at construction or applied
ExecutorUpdatedexecutor (indexed)The executor is set
Calledclone (indexed), target (indexed)The executor completes an external call

Errors

Pool

ErrorCause
UnknownRoot(root)The root was never recorded by the pool
NullifierAlreadySpent(nullifier)An input note was already spent
InvalidProof()The proof does not verify against the rebuilt public signals
InvalidPublicAmount()A zero or out-of-range amount, a deposit msg.value mismatch, a salt outside the field, or an invalid sweep or plain-unshield shape
InvalidCommitment()A commitment or opening field is out of range, the owner key is zero, or the commitment repeats within the call
ZeroCommitment()An output commitment is zero
NoteValueMismatch(retained, noteValue)A deposit's net arrival differs from the note, or the spendable balance moved inconsistently with an unshield
CommitmentMismatch()A deposit opening does not hash to its commitment
InvalidRecipient()The target is zero, the pool, or the executor
UnauthorizedExecutor()An external call was requested before an executor was set
SlippageExceeded(received, minExpected)A return arrived below its minValue
TooManyReturns(count)More than four return tokens were listed
DuplicateReturn(token)A return token was listed twice
NativeTransferFailed()An ETH payout failed
InvalidExecutor()setExecutor was given the zero address
ExecutorAlreadySet()setExecutor was called a second time
OwnershipRenounceDisabled()renounceOwnership was called
MerkleTreeFull()An insert would pass the end of a tree

Fees

ErrorCause
FeeAboveCap(bps)A proposed rate exceeds 1000 bps
ZeroTreasury()The treasury or initial owner is the zero address
FeeChangeNotReady(availableAt)applyFees was called with no proposal or before the delay ended
TreasuryPaymentFailed()A fee claim failed or the token took more than the accrued amount

Executor and caller

ErrorCause
ForbiddenTarget(target)The call target is the pool, the executor, the caller implementation, or the clone itself
CallFailed(target, reason)The external call reverted; reason is its revert data
CloneUnderpaid(token)The clone did not hold the funded net, as with a fee-on-transfer token, or a listed return token's clone balance ended below its pre-call level
UnauthorizedPool()The executor was called by something other than the pool
OnlyExecutor()A clone was called by something other than the executor
EthTransferFailed()Sweeping ETH from a clone to the pool failed

On this page