Skip to main content
The pool does not hold plain ERC-20 reserves. For each listed asset it holds the reserve in a Fhenix confidential token: an FHERC20 wrapper whose balances are encrypted, running on Fhenix CoFHE. There is still only one pool: one tree, one nullifier set, one anonymity set for every token (Many tokens, one pool), and the pool’s notes are denominated in wrapper units whichever format you used to get in.

TOKEN and eTOKEN

Each listed asset pairs two contracts: the plain ERC-20, the TOKEN (for example USDC), and its FHERC20 wrapper, the eTOKEN (for example eUSDC), which is the pool’s reserve for that asset. TOKEN and eTOKEN are not two pools and not two balances. They are formats for crossing the boundary, chosen per transaction: Deposit in one format and withdraw in the other: the notes in between are the same notes. Which format a boundary transaction uses is public, because value visibly moves; ExtData.format carries it, and a private transfer must always be the confidential format.

Units and rate

A wrapper keeps min(decimals, 6) decimals, and one note unit is its rate in TOKEN base units: 10^(decimals − 6), so 1e12 for 18-decimal WETH and 1 for 6-decimal USDC. A TOKEN deposit of units therefore pulls units × rate TOKEN wei, and a TOKEN claim pays the burned amount times the same rate. An amount crossing the boundary stays within uint64, which is also the cap each wrapper puts on its total supply.

Domain-bound ExtData

Every public side effect of a transaction lives in ExtData, which the circuit treats as one opaque hash. Its domain fields (chainId, pool, asset, format, and depositId for a finalization) are inside extDataHash, so a proof cannot be replayed on another chain, pool, token, format or deposit receipt. A finalization must also name its own receipt’s asset.

Why “just swap the token” fails

Here is the fact the whole design turns on: an FHERC20 transfer or burn that exceeds the sender’s balance does not revert. It silently moves 0, and returns the amount it actually moved as an encrypted handle. A successful transaction receipt therefore proves nothing at all about how much value changed hands. So the pool never credits or settles anything on a receipt alone. It reads the returned handle, compares it with what it asked for, and waits for CoFHE’s signed decryption before it calls anything done. Two consequences follow.

Token-first eTOKEN deposits

An eTOKEN deposit pulls the tokens before any notes exist, and creates the notes only once the pull is authenticated:
1

requestDeposit(asset, amount, screening)

The depositor’s call. The pool pulls eTOKEN from the depositor, who has made the pool an operator of that wrapper, and records a depositor-owned receipt in that asset, storing the encrypted amount actually received plus a publicly decryptable ok bit for received == amount. No proof and no nullifiers yet. The pull needs a signed screening of the depositor (Deposit screening).
2

verifyDeposit(depositId, success, signature)

Anyone (the relayer’s keeper, or the user’s own browser) submits CoFHE’s signed decryption of that bit, moving the receipt Pending → Verified | Failed. The call does nothing once the receipt has left Pending, so a replayed signature can never resurrect a cancelled or finalized receipt.
3

finalizeDeposit(proof, extData) or cancelDeposit(depositId)

Only the depositor can close the receipt: finalizeDeposit proves a join-split that creates the notes and binds the depositId, while cancelDeposit abandons it and refunds what was actually received. The two are mutually exclusive.
A failed proof leaves the receipt Verified, so you simply prove again; the tokens are not pulled twice. Receipt statuses are Pending, Verified, Failed, Finalized and Cancelled, and an open receipt is readable on-chain by its id, which is how a wallet can offer to resume or cancel it later. Deposits are never relayed, so they never pay a relayer fee. A TOKEN deposit needs none of this: deposit takes the depositor’s screening, proves the join-split, pulls the ERC-20 and calls the wrapper’s shield in one step, with both legs checked against balance deltas, so a fee-on-transfer token’s short delivery reverts.

Obligations and attempts

Every outbound movement of eTOKEN is an obligation: a withdrawal payout, a deposit refund, or a TOKEN burn. Its asset is fixed when it is created, and it is paid only from that asset’s wrapper, through one or more attempts. Each attempt records what was requested, what actually moved, and a public bit for sent == requested:
  • confirmAttempt(attemptId, success, signature) is permissionless, and accepts a signed decryption for the obligation’s current, in-flight attempt only. A stale or replayed confirmation reverts.
  • Only an authenticated failure enables retryObligation(obligationId), which pays just the encrypted residual through a new attempt. It flips the obligation to in-flight before any external call, so concurrent retries revert.
  • Obligation statuses run InFlight → Settled or InFlight → RetryAllowed → InFlight …; an attempt is InFlight, Succeeded or Failed.
A TOKEN withdrawal has an extra leg. The pool burns eTOKEN into a wrapper claim and records that attempt’s exact claim id, read back from ConfidentialWrapper.lastClaimId() in the same transaction. Only what was actually burned becomes claimable, any unburned residual stays owed by the pool, and the wrapper’s claimed flag stops double payment. Claim ids are unique per wrapper only, so the keeper, the indexer and the web app all key a claim by its asset’s wrapper plus the claim id, and claimUnshielded must be called on that wrapper.

Backing invariant

For every listed asset X the pool maintains:
  • noteLiability (plaintext): the value of unspent notes. Every accepted join-split moves it by extAmount; a relayer’s fee note stays inside it. An eTOKEN deposit adds to it only at finalization.
  • protocolFees (plaintext): withdrawal fees kept and not yet collected (Fees and referrals).
  • depositLiability (encrypted): the received amounts of receipts that are still open.
  • payoutLiability (encrypted): the residuals of unsettled obligations.
Anyone can ask the pool to check it. checkBacking(asset) is a transaction, not a view: it adds the four terms under encryption, compares the sum with the pool’s encrypted eTOKEN balance, makes the resulting bit publicly decryptable and emits BackingChecked. A monitor can therefore confirm that the reserve covers the liabilities without learning any of the encrypted terms. Each step changes one asset’s row, and moves only that asset’s wrapper. A private transfer, relayed or not, and a rate change move nothing: Why a withdrawal can never exceed the backing, in short: conservation makes a join-split lower note value by exactly what leaves, which is the obligation it creates plus the fee it keeps; nullifiers stop a note being spent twice; notes are credited only after value provably arrived (an exact mint for TOKEN, an authenticated received == amount for eTOKEN); a refund comes out of received, which never became note value; a relayer’s fee is a note, so it adds no payout; an obligation shrinks only by what actually moved, and a retry sends only the residual; and a fee collection or referral claim is at most what was kept. noteLiability uses checked arithmetic, so an underflow reverts, and the encrypted sums cannot wrap because the wrapper caps its supply at uint64.