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.
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 recomputeskeccak256(abi.encode(extData)) % FIELD_SIZE and requires it to equal
the proof’s extDataHash.
The asset crossing the boundary, and the circuit’s
publicAsset. Must be 0 when extAmount is 0.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
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’spoolAbi 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 theverifier 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.
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:
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:
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.