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

# Notes and proofs

> The UTXO model behind Fluton: what a note is, how commitments and nullifiers are formed, and what one join-split proof proves.

Fluton holds no account balances. It holds **notes**, in the UTXO style, and a single append-only Merkle tree of their public commitments. Every state change, whether a deposit, a withdrawal or a private transfer, is one **join-split** proof that destroys some notes and creates exactly three new ones. Nothing about a note is public except its commitment, the ciphertext that delivers it to its owner, and, when it is spent, its nullifier; the only amount the chain ever sees is the net amount crossing the pool boundary.

## A note

A note is the tuple `(amount, keypair, blinding, asset)`. Four **Poseidon** hashes derive everything the protocol needs from it:

```text theme={null}
publicKey    = Poseidon(privateKey)
commitment   = Poseidon(amount, publicKey, blinding, asset)
nullifierKey = Poseidon(privateKey, NULLIFIER_KEY_DOMAIN)
nullifier    = Poseidon(commitment, leafIndex, nullifierKey)
```

* The **commitment** is the public tree leaf. It hides the amount, the owner and the token behind the random `blinding`.
* The **nullifier** is what spending reveals. The leaf's index in its tree is hashed into it, so one leaf has exactly one nullifier, and the pool can mark it spent without learning which leaf it was.
* `nullifierKey` is a one-way derivation from the private key, with the domain tag `NULLIFIER_KEY_DOMAIN`, the ASCII bytes of `fluton-nullifier-key` as a 20-byte integer, the same constant in the circuit and in the SDK. Routing the key through it is the split that makes a read-only [view key](https://docs.fluton.io/concepts/keys-and-view-keys.md) possible: a holder of `nullifierKey` can tell which notes are spent but cannot produce a proof.
* `asset` is the pool's asset id for the token, so a note can only ever be spent as that token. See [Many tokens, one pool](https://docs.fluton.io/concepts/multi-token.md).

Poseidon reduces its inputs modulo the field prime, so an opening taken from untrusted bytes is believed only after a canonical check: the amount below 2^248, the blinding below the field size, the asset a uint32. Without it, someone could commit to 0 and hand you an opening of `p`, and your wallet would show a balance it does not have.

## The join-split

One proof spends up to 2 notes (`transaction.circom`, `Transaction(20, 2, 3)`) or up to 16 (`transaction16.circom`, `Transaction(20, 16, 3)`), and creates **exactly 3** new notes in both cases. Both instantiate the same template, in `joinSplit.circom`.

The core constraint is **value conservation**:

```text theme={null}
sumIns + publicAmount === sumOuts
```

`publicAmount` is the net amount crossing the pool boundary, encoded in the field: positive is a deposit, and a withdrawal of `x` is the field element `p - x`. A private transfer has `publicAmount = 0`, so nothing enters or leaves. The contract recomputes the value from `ExtData.extAmount` and refuses a proof that does not match it.

Unused input slots carry zero-amount **dummy** notes. The circuit computes each input's Merkle root but only forces it to equal the published root when the input's amount is non-zero, so a freshly generated dummy needs no leaf in the tree. Every output is range-checked to 248 bits, which keeps sums of note amounts from ever wrapping the field: even 16 inputs sum to under 2^252.

One more rule closes the obvious gap inside one proof: no two inputs of one transaction may share a nullifier, and the circuit compares every pair to enforce it. Across transactions it is the nullifier itself that catches a note already spent. What the pool checks before it accepts a proof is on [Contracts](https://docs.fluton.io/reference/contracts.md).

### Which verifier runs

The pool keeps one verifier per circuit and picks it by the **number of nullifiers** in the payload: 2 for the everyday circuit (9 public signals) and 16 for the consolidation circuit (23 public signals). Any other count is refused. That number is public; how many of those inputs are real notes rather than dummies is not. The 16-input circuit is for spending many notes at once, such as a relayer collecting its fee notes.

### What the three output slots are for

| Slot | Owner |
| - | - |
| 0 | the user: the payment, the withdrawal's change, or a dummy |
| 1 | the user: change, or a dummy |
| 2 | the relayer's fee note when a relayer submits, otherwise a zero-amount dummy |

The circuit does not distinguish the slots; the layout is a convention of the SDK and the relayer. On-chain, a fee note and a dummy look the same. See [Fees and referrals](https://docs.fluton.io/concepts/fees.md).

## The Merkle tree

`MerkleTreeWithHistory` is an append-only Poseidon tree whose depth is fixed when the pool initializes; 20, to match the circuits. A node is `Poseidon(left, right)`, the same hash as in the circuit and in the client, and empty subtrees start from `ZERO_VALUE`, which is `keccak256("fluton")` reduced into the field. Everything it hashes, the three new leaves included, has to be below `FIELD_SIZE`: a commitment that is not reverts with `NodeOutOfField` instead of being silently reduced.

Each accepted transaction appends its three leaves as **one batch** and records **one root**. The batch append hashes at most two nodes per level, no more than two single-leaf appends would.

No root ever expires. The pool remembers every root its tree has had, and a proof may use any of them: the tree only grows, so an old root proves nothing but leaves that are still there, and the nullifiers alone stop a note from being spent twice. A proof built against a stale tree therefore still lands, however many transactions arrived in between. Clients rebuild the tree from the pool's commitment events; `getLastRoot()` and `nextIndex()` are the pool's own answers to check a rebuilt tree against (see [Keys, notes and scanning](https://docs.fluton.io/sdk/keys-and-scanning.md)).

A tree of depth 20 has room for 349,525 transactions of three leaves each. When it cannot take a whole batch, the pool starts another tree, and the leaves of the full one stay provable against its final root, so the pool does not run out of room. [Contracts](https://docs.fluton.io/reference/contracts.md#merkletreewithhistory) describes how a leaf's position names its tree.

## What extDataHash binds

Every public side effect of a transaction lives in one `ExtData` struct: the recipient, `extAmount`, the withdrawal fee, all three note ciphertexts, and domain fields; among them the asset, the note format and a deposit's referrer. The circuit sees it as one opaque public input, **extDataHash**, the keccak hash of the encoded struct reduced into the field, which the pool recomputes from the calldata it was given. [Contracts](https://docs.fluton.io/reference/contracts.md) has the struct field by field.

So a transaction cannot be re-targeted. Change the recipient, the amount, the fee, a ciphertext or the token, and the hash no longer matches the proof, which the verifier then rejects. An observer watching the mempool can refuse to submit a transaction, but cannot redirect it or overcharge it.

## Deposit and withdrawal, side by side

```text theme={null}
  Deposit 13.37                          Withdraw 4 (partial, through a relayer)
  ─────────────                          ───────────────────────────────────────
  ins:  (dummies)                        ins:  the 13.37 note  (nullifier revealed)
  outs: note(13.37), dummy, dummy        outs: change(9.36), dummy,           <- all stay
                                               fee note(0.01 → relayer)          shielded
  publicAmount: +13.37                   publicAmount: -4
                                         extData(recipient, amount, 3 ciphertexts) hash-bound in proof
```

A deposit spends nothing and creates a note for the depositor. A withdrawal spends one note, keeps the change inside the pool, pays the relayer with slot 2, and names only the recipient, the token and the public amount.

> [!NOTE]
>
> A deposit and a withdrawal publish their amount and token because value visibly crosses the
> boundary; a [private transfer](https://docs.fluton.io/concepts/private-transfers.md) publishes neither. [What stays
> public](https://docs.fluton.io/concepts/privacy-model.md) lists this operation by operation.

For the contract functions and errors see [Contracts](https://docs.fluton.io/reference/contracts.md), and for the circuit files, public-input order and trusted setup see [Circuits](https://docs.fluton.io/reference/circuits.md).


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