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

FieldTypeMeaning
amountu64, lamportsWhat the note is worth.
ownerfieldPoseidon(spending key).
blindingfieldRandom, so two notes of the same amount and owner never share a commitment.
leafIndexu64Its position in the tree, known once the note is inserted.

The commitment published for it is:

Text
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 is Poseidon(zero, zero) of the level below.
  • Inserts: every shield, pay and unshield inserts 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

Text
input amount 0 + input amount 1 + public amount = output amount 0 + output amount 1

in the BN254 scalar field. The program sets the public amount itself from the instruction's arguments:

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

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

BytesContent
0 to 24A random 24-byte nonce
24 to 80XChaCha20-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:

  1. Read every leaf and memo, and every spent nullifier, from GET /tree.
  2. Try each memo with the view key. A memo that does not open belongs to another holder.
  3. For each memo that opens, recompute the commitment and check it against the leaf.
  4. 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.