Skip to main content
The pool is one Solidity contract, PrivacyPool, plus the tree it inherits, two generated Groth16 verifiers, and one confidential wrapper per listed token. Everything below comes from the Solidity sources and from the ABIs the SDK ships. The pool is deployed behind a proxy, so the address every client talks to is a TransparentUpgradeableProxy. See deployments for the addresses and what stays public for what upgradeability means.

PrivacyPool

PrivacyPool.sol is a multi-asset shielded pool: one Merkle tree and one nullifier set for every asset. Each asset is a plain ERC-20 (TOKEN) paired with its ConfidentialWrapper (eTOKEN), which holds the reserve. Notes are denominated in eTOKEN units.
Value enters only through deposit (TOKEN) and requestDeposit (eTOKEN), and each takes a signed screening of the depositor. Every outbound movement of eTOKEN is an obligation settled by an authenticated decryption, because an FHERC20 transfer moves 0 instead of reverting when the balance is short. Read TOKEN and eTOKEN for why.

Roles

The owner and the upgrader are separate roles: transferring one does not transfer the other. Renouncing ownership freezes the asset list and the fee rates, but only until an upgrade.

Initialization

initialize runs once, from the proxy’s constructor, so nobody can initialize the pool before the deployer. The implementation’s constructor calls _disableInitializers(), so it stays ownerless and inert.
_screeningSigner is required: the zero address reverts with InvalidScreeningSigner, so a pool cannot be deployed without deposit screening.

ExtData

Every public side effect of a transaction lives in one struct, which the circuit sees only as a hash. The pool recomputes keccak256(abi.encode(extData)) % FIELD_SIZE and requires it to equal the proof’s extDataHash.
address
Where a withdrawal pays out. Must be zero unless extAmount is negative.
int256
Note units entering (positive) or leaving (negative) the pool. Zero is a private transfer.
uint64
withdrawFeeOf(-extAmount) at the rate in force. Must be zero unless extAmount is negative.
bytes[3]
One ciphertext per output commitment, each exactly CIPHERTEXT_LENGTH (168) bytes.
uint256
Must equal block.chainid.
address
Must equal the pool’s own address.
uint32
The asset crossing the boundary, and the circuit’s publicAsset. Must be 0 when extAmount is 0.
uint8
FORMAT_CONFIDENTIAL (0) or FORMAT_PUBLIC (1).
bytes32
Set only by finalizeDeposit; transact and deposit reject a non-zero value.
address
A deposit’s referrer. Must be zero unless extAmount is positive, and may not be the pool.

User functions

Finalize and cancel are mutually exclusive. A failed proof leaves the receipt Verified, so you re-prove without the tokens being pulled again. DepositStatus runs None, Pending, Verified, Failed, Finalized, Cancelled. The proof struct picks its verifier by the number of nullifiers: N_INS (2) uses verifier, N_INS_LARGE (16) uses verifier16, anything else reverts with InvalidInputCount.

Obligation functions

Both are permissionless, and the relayer’s keeper calls them for you. confirmAttempt accepts a signed decryption for the obligation’s current, in-flight attempt only: anything stale or replayed reverts with StaleConfirmation. A success settles the obligation; a failure moves it to RetryAllowed, which is the only status retryObligation accepts. A retry pays only the encrypted residual, through a new attempt, and flips the status to in-flight before any external call, so concurrent retries revert. ObligationKind is Withdraw, Refund or Burn (an unshield into a TOKEN claim); ObligationStatus is None, InFlight, RetryAllowed or Settled; AttemptStatus is None, InFlight, Succeeded or Failed. A Burn attempt records the wrapper claim id it created, read from ConfidentialWrapper.lastClaimId() in the same transaction, and reverts with MissingClaimId if that is zero.

Fee and referral functions

collectFees pays out kept withdrawal fees, except the part reserved for referrers: the owner may take only protocolFees[asset] above referralLiability[asset]. claimReferral pays the caller’s own referralCredit[msg.sender][asset] out of the same kept fees, which is why it reverts with InsufficientFees until withdrawals have kept enough of that token, and with InsufficientCredit when you ask for more than you earned. Both are paid through an obligation, as eTOKEN (FORMAT_CONFIDENTIAL) or TOKEN (FORMAT_PUBLIC). setReferralBonus is permissionless: anyone may submit a referrer’s attestation. The pool checks the EIP-712 signature against bonusSigner, refuses a total above MAX_REFERRAL_BONUS_BPS, and accepts only an _issuedAt strictly later than the stored one (StaleBonus otherwise), so a replay can never roll a bonus back. revokeReferralBonus clears a bonus and stamps it with the current time, which also makes every attestation issued so far stale. The reasoning behind the rates is on Fees and referrals. Four pure or view helpers give the arithmetic:
withdrawFeeOf rounds up, at the rate in force now: (amount * withdrawFeeBps + FEE_DENOMINATOR - 1) / FEE_DENOMINATOR. referralShareOf adds the stored bonus to referralShareBps, counts the expiring part only while block.timestamp < expiresAt, and caps the result at MAX_REFERRAL_SHARE_BPS. referralRewardOf rounds down, and takes the fee at the lowest rate a withdrawal can pay from now on: the rate in force, or a lower one that is already scheduled or still within its grace.

Owner functions

addAsset appends one asset and is the only way to list a token. It accepts a wrapper only if its runtime code hash is the pinned wrapperCodehash, its underlying is a separate contract that is not itself a wrapper, neither address is already listed in either role, and its rate is non-zero. Listing is append-only up to MAX_ASSETS: there is no delist, pause or edit. setWithdrawFeeBps schedules a rate rather than applying it. The new rate takes effect WITHDRAW_FEE_DELAY (two days) after the call, which emits WithdrawFeeChanged(oldBps, newBps, effectiveAt); until then withdrawFeeBps() keeps returning the rate in force, and nextWithdrawFeeBps() and withdrawFeeChangesAt() announce the change. For WITHDRAW_FEE_GRACE (one hour) after a rate takes effect, the pool still accepts a withdrawal that bound the rate before it. A rate that is not yet in force can be replaced, which restarts the delay; one that is in force can be replaced only once its grace is over, and an earlier call reverts with WithdrawFeeChangeTooSoon. The pool therefore never accepts more than two rates at once. setReferralShareBps changes the share for deposits that land after it; credits already given never change. setBonusSigner with the zero address disables setReferralBonus while leaving bonuses already set in place. setScreeningSigner names the address whose screenings the pool takes. Screening cannot be switched off: the signer may never be the zero address, and a new signer refuses every screening the old one signed. Deposit screening explains what the pool checks.

Views

checkBacking(uint32 asset) is the one check that is a transaction rather than a view: it sums that asset’s four liabilities under encryption (in 128 bits), compares them with the pool’s encrypted reserve, makes the resulting ebool publicly decryptable and emits BackingChecked. It exists for monitors; see the backing invariant.

Parameters and caps

The mutable parameters are the withdrawal fee rate (0 to MAX_WITHDRAW_FEE_BPS), referralShareBps (0 to MAX_REFERRAL_SHARE_BPS), bonusSigner and screeningSigner. initialize sets both rates at deployment; the live values are the withdrawFeeBps() and referralShareBps() views.

Errors

Every revert the pool raises is a custom error, and the SDK’s poolAbi lists them so a failed call decodes. Five are absent from that ABI: initialize’s own InvalidWrapperCodehash, and the tree’s InvalidLevels, NodeOutOfField, NoLeaves and TreeIsFull. It carries the errors the pool’s bases raise instead: OwnableUnauthorizedAccount and ReentrancyGuardReentrantCall.

Routing and ExtData

Proof and tree

Deposits and obligations

Fees, referrals and configuration

A deposit that reverts after its screening passed leaves the nonce unspent, so the same screening can be used again.

MerkleTreeWithHistory

MerkleTreeWithHistory.sol holds the append-only Poseidon trees the pool inherits.
_insertLeaves appends a batch and records one root per batch, which is why one transaction’s three leaves produce exactly one root. isKnownRoot answers for every root any tree has ever had: none expires, because the trees are append-only, so an old root only proves leaves that are still there, and the nullifiers alone stop a note from being spent twice. getLastRoot() is the latest root. When the current tree cannot take a whole batch, the next tree starts at index 0, and the leaves of the full one stay provable against its final root. treeNumber() is the current tree and nextIndex() the next free index in it. A leaf’s position, the index that NewCommitment logs, is its tree’s number above the low levels bits and its index in that tree below them, so the positions of the first tree are plain leaf indices. TreeIsFull is left for the case that positions run out of 32 bits. ZERO_VALUE is keccak256("fluton") reduced into the field. Reading a root of zero always returns false. More on the tree in notes and proofs.

Verifier and Verifier16

The pool keeps one snarkjs Groth16 verifier per circuit, in the verifier and verifier16 variables initialize sets, and reaches them through two interfaces in interfaces.sol that differ only in the length of the public input array. The verifier contracts themselves are generated from the circuits: see circuits.
The same file declares IHasher, a single poseidon(bytes32[2]) function implemented by bytecode generated from circomlib so the on-chain hash matches the circuit. The input order is fixed by the circuit: see circuits.

ConfidentialWrapper

ConfidentialWrapper.sol is the eTOKEN: an FHERC20 wrapper over one ERC-20, built on fhenix-confidential-contracts. It keeps min(decimals, 6) decimals and a rate of 10 to the power of decimals - 6, or 1. Name, symbol, underlying and rate live in storage, so every instance linked to the same ERC20ConfidentialLib has identical runtime code, which is what lets the pool pin a single wrapperCodehash. Its one deviation from the stock wrapper is lastClaimId:
The library keys claims by keccak256(abi.encode(to, nonce, burnedHandle)), the per-claimant nonce has no getter, and getUserClaims(to) is an unbounded list anyone can grow by unshielding dust to to. A caller that must track its exact claim reads lastClaimId() in the same transaction instead; it is transient storage, so it is meaningful only there. A claim lives in the wrapper that created it, which is why an attempt records only the id: its obligation’s asset names the wrapper. IConfidentialWrapper is what the pool uses: shield, unshield, confidentialTransfer, confidentialTransferFrom, confidentialBalanceOf, lastClaimId, rate and underlying. Every returned amount is what actually moved. The claim itself is paid out by the wrapper:
Only what was actually burned becomes claimable, and the wrapper’s claimed flag stops double payment. The keeper calls claimUnshielded by exact claim id on the obligation’s own wrapper. Never display an FHERC20 balanceOf: it is an indicator value, not a balance.

Deposit screening

The pool checks screenings itself; no other contract is involved.
signature is screeningSigner’s EIP-712 signature of DepositScreening(address depositor,bytes32 nonce,uint64 expiresAt) in the pool’s domain (PrivacyPool, version 1, this chain id, the pool’s address — the domain referral bonuses use, under another type), with msg.sender as the depositor. deposit and requestDeposit check it before the proof is checked or anything is pulled, spend the nonce and emit DepositScreened(depositor, nonce). Deposit screening explains the flow.