> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fluton.io/llms.txt
> Use this file to discover all available pages before exploring further.

# TOKEN and eTOKEN

> The two formats for crossing the pool boundary, the Fhenix wrappers behind them, token-first deposits, obligations, and the backing invariant.

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](https://docs.fluton.io/concepts/multi-token.md)), 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:

| | in (deposit) | out (withdrawal) |
| - | - | - |
| **TOKEN** (public ERC-20) | one step: the pool pulls `units × rate` TOKEN and calls the wrapper's `shield` | burn eTOKEN into a wrapper **claim** for the recipient → `claimUnshielded` pays TOKEN |
| **eTOKEN** (encrypted balances) | token-first: `requestDeposit` → `verifyDeposit` → `finalizeDeposit` | confidential transfer to the recipient |

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](https://docs.fluton.io/concepts/deposit-screening.md)).

**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.

| Function | Who may call it |
| - | - |
| `deposit` (TOKEN, one step) | the depositor, with a screening |
| `requestDeposit` | the depositor, with a screening |
| `verifyDeposit` | anyone |
| `finalizeDeposit` | the depositor only, on a `Verified` receipt |
| `cancelDeposit` | the depositor only, while the receipt is not closed |
| `confirmAttempt` | anyone |
| `retryObligation` | anyone, after an authenticated failure |
| `claimUnshielded` (the wrapper) | anyone, by exact claim id |

## 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:

```text theme={null}
eX balance(pool)  ≥  noteLiability[X] + protocolFees[X] + depositLiability[X] + payoutLiability[X]
```

* `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](https://docs.fluton.io/concepts/fees.md)).
* `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:

| Step | eX balance | noteLiability\[X] | protocolFees\[X] | depositLiability\[X] | payoutLiability\[X] |
| - | - | - | - | - | - |
| `addAsset` (X) | 0 | 0 | 0 | 0 | 0 |
| TOKEN deposit of `e` units | +e (exact) | +e | | | |
| `requestDeposit(X, r)` | +received | | | +received | |
| `finalizeDeposit` | | +r | | −received | |
| `cancelDeposit` | | | | −received | +received |
| withdrawal of `w` units, fee `f` | | −w | +f | | +(w − f) |
| `collectFees(X, c)` | | | −c | | +c |
| `claimReferral(X, c)` | | | −c | | +c |
| payout attempt that moves `s` | −s | | | | −s |
| private transfer | | | | | |

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.