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

# Circuits

> The Circom circuits behind Fluton: files, public inputs, the constraints that matter, the generated verifiers and the trusted setup.

Fluton proves every state change with one Groth16 join-split proof. The circuits are written in
Circom 2, with Poseidon and the helper templates coming from `circomlib`. Two instances of one template are compiled: a 2-input circuit for everyday
transactions and a 16-input circuit for consolidating many notes at once.

## Files

| File | Role |
| - | - |
| `joinSplit.circom` | The `Transaction(levels, nIns, nOuts)` template: all signals and all constraints, plus the `Keypair` and `NullifierKey` helpers |
| `transaction.circom` | The 2-input instance, `Transaction(20, 2, 3)`: every deposit, transfer and withdrawal that spends at most two notes |
| `transaction16.circom` | The 16-input instance, `Transaction(20, 16, 3)`: spends up to 16 notes of one asset in one proof, such as a relayer collecting its fee notes |
| `merkleTree.circom` | `HashLeftRight` (Poseidon of a node's two children) and `DualMux`, which orders a pair by a path bit constrained boolean |
| `merkleProof.circom` | `MerkleProof(levels)`: computes the root implied by a leaf, its packed index and its siblings, without asserting that it equals anything |

Both instances have 20 levels and exactly 3 outputs, so every accepted transaction appends three
leaves whatever its size. `merkleProof.circom` deliberately only computes a root and leaves the
comparison to the caller; that is what lets the transaction circuit skip the membership check for
dummy inputs.

A note is `(amount, publicKey, blinding, asset)` and the circuit derives the same four Poseidon
hashes the SDK does:

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

`nullifierKeyDomain()` is the ASCII bytes of `fluton-nullifier-key` read as an integer, and it must
match the SDK's own domain constant. Binding the packed leaf index into the nullifier gives each
leaf exactly one nullifier. The nullifier depends on the private key only through `nullifierKey`,
a one-way derivation, which is what makes a read-only view key possible. See
[notes and proofs](https://docs.fluton.io/concepts/notes-and-proofs.md) and
[keys and view keys](https://docs.fluton.io/concepts/keys-and-view-keys.md).

## Public inputs

Circom orders public signals by declaration, so the order in `joinSplit.circom` is the order of
`publicSignals[]` off-chain and of the verifier's `input[]` array on-chain:

1. `root`
2. `publicAmount`
3. `extDataHash`
4. `publicAsset`
5. `inputNullifier[nIns]`
6. `outputCommitment[nOuts]`

That makes 9 public inputs for the 2-input circuit (4 plus 2 plus 3) and 23 for the 16-input one
(4 plus 16 plus 3), matching the two verifier interfaces in the
[contracts](https://docs.fluton.io/reference/contracts.md). The pool assembles the array in exactly this order and always
takes `publicAsset` from `ExtData`, never from the caller.

| Signal | What it carries |
| - | - |
| `root` | A tree root the pool still accepts. The circuit compares each real input's computed root against it |
| `publicAmount` | The net amount crossing the pool boundary: positive is a deposit, negative is a withdrawal encoded as the field order minus the amount. The pool recomputes it from the amount in `extData` and requires equality ([contracts](https://docs.fluton.io/reference/contracts.md)) |
| `extDataHash` | The field-reduced keccak of the pool's `ExtData`: recipient, amount, fee, the three ciphertexts and the domain fields |
| `publicAsset` | The asset crossing the boundary, or 0 when nothing crosses |
| `inputNullifier` | One nullifier per input slot, real or dummy |
| `outputCommitment` | The three new leaves |

The private inputs are the single `asset` of the transaction, and per slot the amounts, private
keys, blindings, path indices and sibling hashes of the notes spent, plus the amounts, recipient
public keys and blindings of the notes created.

### The constraints that matter

* **Membership, skipped for dummies.** Each input's commitment is hashed, its Merkle root computed,
  and the result compared to `root` through `ForceEqualIfEnabled` with the input's own amount as the
  enable signal. An input of amount 0 therefore needs no real leaf, so unused slots carry freshly
  generated dummy notes.
* **Nullifier correctness.** Each slot's recomputed nullifier must equal the public
  `inputNullifier` for that slot, and no two nullifiers in one proof may be equal.
* **Output range check below 2^248.** Every output amount passes `Num2Bits(248)`. Inputs need no
  check, because every real input was once a range-checked output. With amounts under 2^248, even 16
  of them sum to under 2^252, well below the field order, so a sum can never wrap.
* **Value conservation.** `sumIns + publicAmount === sumOuts`, over the field. Because the public
  amount is bounded by the pool and every note amount is range-checked, this holds over the integers
  too.
* **The asset constraint.** One private `asset` signal enters all input and output commitments, so a
  transaction can only spend and create notes of a single asset. On top of that,
  `(asset - publicAsset) * publicAmount === 0`: whenever value crosses the boundary the asset is
  pinned to the public one, and when nothing crosses the asset stays private while `publicAsset`
  remains bound by the proof. Together with the range check, a note of an asset that holds no value
  is provably worth zero. [Many tokens, one pool](https://docs.fluton.io/concepts/multi-token.md) works through the argument.
* **Ext-data binding.** `extDataHash` is squared into a dummy signal, which is enough to make the
  proof depend on it. Tamper with any public field on-chain and the hash changes, so the proof no
  longer verifies and a mempool observer cannot re-target it.

The circuit does not know about output slots. Slot 0 and 1 being the user's payment and change and
slot 2 being the relayer's fee note is a convention of the SDK and the relayer, which is why a fee
note and a dummy look alike on-chain. See [Fees and referrals](https://docs.fluton.io/concepts/fees.md).

## Verifiers

Each circuit has one on-chain verifier, exported from its proving key by snarkjs: `transaction`
into `Verifier.sol` as `Groth16Verifier`, and `transaction16` into `Verifier16.sol` as
`Groth16Verifier16`. The pool holds both and picks one by the number of nullifiers in the proof
([contracts](https://docs.fluton.io/reference/contracts.md)). Both circuits are compiled with Circom 2.2.3 at `--O2`: 13,425
constraints for the 2-input circuit and 96,018 for the 16-input one, inside the 2^17 (131,072)
limit of the powers-of-tau file the setup starts from. Because the verifiers
are exported from the proving keys, proofs made with any other key are rejected by the
deployed verifier; the relayer's fee collection therefore needs the proving keys of the
ceremony below ([Running a relayer](https://docs.fluton.io/operators/relayer.md)).

## Trusted setup

Each circuit's proving and verifying keys come from a Groth16 trusted setup for that circuit. The
setup bears on proof **unforgeability** only: the hiding properties of the commitments, the
ciphertexts and the anonymity set do not depend on it.

The keys of the deployed pool come from a ceremony in two phases:

* **Phase 1** is the Perpetual Powers of Tau after its 80th contribution, prepared for 2^17
  constraints (`ppot_0080_17.ptau`).
* **Phase 2** ran once per circuit. It took **222 contributions** and was closed with a random
  beacon: the hash of Ethereum block `26408500`, hashed 2^20 times over.

A proof can be forged only by someone who knows the secrets of every contributor to a phase, so
the keys are sound as long as one contributor to each phase discarded theirs.

The ceremony publishes its results at
[coordinator.fluton.io/final](https://coordinator.fluton.io/final/): the transcript
(`transcript.json`), which lists every contribution with its hash, the two verification keys, the
two Solidity verifiers and a `verify.sh` script. The final proving keys are
[`transaction_final.zkey`](https://coordinator.fluton.io/zkeys/transaction_final.zkey) and
[`transaction16_final.zkey`](https://coordinator.fluton.io/zkeys/transaction16_final.zkey).

| Artifact | SHA-256 |
| - | - |
| `transaction_final.zkey` | `41d987aa55b19fbc987dcbac9e744ccc77be832078224ec03b1fd871f143bd6b` |
| `transaction16_final.zkey` | `afe56e1b58ece9d130c8f26a6dc7f99175172b836c71e20708be06157262cd67` |
| `Verifier.sol` (`Groth16Verifier`) | `ed6928bf776cd2df2531af69be9a55302c7e0ed42e19d28f5f919429446c59ca` |
| `Verifier16.sol` (`Groth16Verifier16`) | `fb03dd9f4fef403cc204dcde3d4c502cfc063995782efc2435c1315f07e43422` |
| `transaction` constraint system (`r1cs`) | `848a0f4c979e833e2abeffea8b895ded7bfb1572d68dcae9a557d8bac926a657` |
| `transaction16` constraint system | `af2fbd7d15bea48e98cc412fcc8a51fd66e4b9700d0fcf160f738e5d4e25dd9f` |
| `ppot_0080_17.ptau` | `f807e065fde53f72f4bf4d57140fab85b26daa6cc95bdfec7cce93622b3a367c` |

The `verifier` and `verifier16` contracts of the [deployment](https://docs.fluton.io/reference/deployments.md) are these two
verifiers, with their sources verified on Arbiscan, so anyone can compare the verification key
inside a deployed verifier with the one the ceremony published.


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