Protocol
Notes and the pool
What a note is, how the pool's tree holds it, how a spend nullifies it, and how a balance is rebuilt.
The shielded balance is a set of notes. A note is an amount of SOL in the pool that only one spending key can spend. The pool holds every note's commitment in one tree and every spent note's nullifier on chain; it never holds who owns which.
A note
| Field | Type | Meaning |
|---|---|---|
amount | u64, lamports | What the note is worth. |
owner | field | Poseidon(spending key). |
blinding | field | Random, so two notes of the same amount and owner never share a commitment. |
leafIndex | u64 | Its position in the tree, known once the note is inserted. |
The commitment published for it is:
commitment = Poseidon(amount, owner, blinding)The tree
- Shape: a binary Poseidon tree of depth 26, so it holds 67,108,864 leaves. An empty leaf is
0; each empty level isPoseidon(zero, zero)of the level below. - Inserts: every
shield,payandunshieldinserts exactly two commitments, the spend's two outputs, at the next two leaf indices. A zero-valued output is still a real commitment and takes its leaf. - Roots: after each pair is inserted the pool records the new root. The pool keeps the last 128 roots; a proof's root is accepted until 128 later spends have replaced it.
GET /tree serves every leaf with its commitment and memo, every spent nullifier and the current root. See GET /tree.
Spending: two in, two out
Every spend proves the same shape: two input notes, two output notes and a public amount, with
input amount 0 + input amount 1 + public amount = output amount 0 + output amount 1in the BN254 scalar field. The program sets the public amount itself from the instruction's arguments:
| Instruction | Public amount |
|---|---|
shield | +amount: SOL enters the pool. |
pay | -(price + fee + refund): SOL leaves for storage, Geode's fee and the network refund. |
unshield | -(amount + refund): SOL leaves for the recipient and the network refund. |
An input with amount 0 is a dummy note: it skips the membership check but still gets its own nullifier. A shield spends two dummies; a pay or unshield spends one or two real notes. The change goes to a new note owned by the same spending key.
The SDK picks the largest notes first, at most two per spend. A balance spread over many small notes pays only as much as its two largest cover.
Nullifiers
Spending a note reveals its nullifier:
nullifier = Poseidon(commitment, leafIndex, Poseidon(spending key, commitment, leafIndex))Only the holder of the spending key can compute it, and it does not reveal which commitment it belongs to. The program records each one as an account with the seeds ["nullifier", nullifier]. That account can be created once, so a note spends once. The two nullifiers of one spend must differ.
Memos
Each output note is published with an 80-byte memo so its holder can find it again:
| Bytes | Content |
|---|---|
| 0 to 24 | A random 24-byte nonce |
| 24 to 80 | XChaCha20-Poly1305 under the view key of amount (8 bytes, big-endian) and blinding (32 bytes), with its 16-byte tag |
The owner is not in the memo: the holder recomputes it from the spending key. The memos are bound into the proof through its binding hash, so no one can swap them. See The proof that pays.
Rebuilding a balance
A balance is never stored. The client rebuilds it:
- Read every leaf and memo, and every spent nullifier, from
GET /tree. - Try each memo with the view key. A memo that does not open belongs to another holder.
- For each memo that opens, recompute the commitment and check it against the leaf.
- Compute the note's nullifier and keep the note if that nullifier is not spent and its amount is above zero.
The sum of the notes kept is the shielded balance. The same steps on any device give the same balance.
The pool's vault
Shielded SOL sits in the pool vault, a program account no key signs for. Lamports leave it only through a verified pay (to the storage vault, the fee vault and the relayer's network refund) or unshield (to the proof's recipient and the relayer's network refund), and never below its rent-exempt minimum. See Accounts.