Skip to main content
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:
  • 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 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.
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:
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.

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

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.

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

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.
A deposit and a withdrawal publish their amount and token because value visibly crosses the boundary; a private transfer publishes neither. What stays public lists this operation by operation.
For the contract functions and errors see Contracts, and for the circuit files, public-input order and trusted setup see Circuits.