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 keepsmin(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 inExtData, 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.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 forsent == 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 → SettledorInFlight → RetryAllowed → InFlight …; an attempt isInFlight,SucceededorFailed.
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 byextAmount; 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): thereceivedamounts of receipts that are still open.payoutLiability(encrypted): the residuals of unsettled obligations.
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.