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:
data | cloneSalt | Behavior |
|---|---|---|
| Empty | 0 | Plain transfer of the net to target; returning must be empty |
| Nonempty | 0 | One call to target from the shared clone |
| Nonempty | Nonzero | One call to target from the user's persistent CREATE2 clone |
| Empty | Nonzero | Sweep: 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
| Function | Caller | Effect |
|---|---|---|
claimFees(token) | Anyone | Sends accrued fees for token to the treasury |
proposeFees(depositBps, unshieldBps, treasury) | Owner | Starts the one-day delay; each rate is capped at 1000 bps (10%) |
applyFees() | Anyone | Applies the proposal once FEE_DELAY has passed |
setExecutor(executor) | Owner | Sets the executor once; a second call reverts |
pause() / unpause() | Owner | Stops 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:
| Bytes | Field |
|---|---|
| 0–32 | View ephemeral: compressed secp256k1 public key (33 bytes) |
| 33–64 | Spend ephemeral: packed BabyJubJub point (32 bytes) |
| 65–66 | View tag (2 bytes) |
| 67–90 | XChaCha20 nonce (24 bytes) |
| 91– | Ciphertext with its Poly1305 tag: 208 bytes for a note, 176 for a return note |
| after the ciphertext | Optional 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
| View | Returns |
|---|---|
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.
| Event | Fields | Emitted when |
|---|---|---|
NoteCommitted | commitment (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 |
ReturnShielded | commitment (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 |
NullifierSpent | nullifier (indexed) | An input note is spent |
Unshielded | token (indexed), recipient (indexed), gross, protocolFee | An unshield settles; not emitted by a sweep |
ProtocolFeeAccrued | token (indexed), amount | A deposit or unshield fee is recorded |
ProtocolFeeClaimed | token (indexed), treasury (indexed), amount | claimFees pays the treasury |
FeesProposed | depositFeeBps, unshieldFeeBps, treasury, availableAt | The owner proposes new fees |
FeesUpdated | depositFeeBps, unshieldFeeBps, treasury | Fees are set at construction or applied |
ExecutorUpdated | executor (indexed) | The executor is set |
Called | clone (indexed), target (indexed) | The executor completes an external call |
Errors
Pool
| Error | Cause |
|---|---|
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
| Error | Cause |
|---|---|
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
| Error | Cause |
|---|---|
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 |