Concepts
Notes and the private balance
Your private balance is a set of notes. A note is one amount of one asset, held in Solana Privacy Rings, that only you can spend. Your balance of an asset is the sum of your unspent notes of that asset.
What a note is
A note is an unspent output in the Solana Privacy Program's state tree. The chain stores a hash of it. The note itself holds:
| Part | What it is |
|---|---|
| Asset | The mint. SOL is the all-zero address. |
| Amount | In the asset's smallest unit. |
| Owner | A hash of two things: Pook's authority and a one-time key that only you can derive. |
| Blinding | Random bytes that make two notes of the same amount hash differently. |
A note is created by entering, by a run's result, or as change from a spend. It is spent whole. A run that needs less than a note holds gets the rest back as a new change note.
Who can spend a note
Spending a note takes two things at once.
- Pook's authority has to sign. The authority is an address derived from the Pook program, with no private key. The program signs for it, and only inside
run,leave,open_seatandclose_seat, after it has verified a proof. - The proof has to show the note's one-time key. Each of those proofs shows that whoever made it knows the secret behind the note's owner hash.
So the program alone cannot move a note, because it has no secret. A person who knew your secrets could not move one either without going through the program, because the authority would not sign.
Where the proofs are made
A run, a leave and every seat action carry two proofs. The Pook proof, which fixes the hook, the call, the amounts and the expiry, is made on your device with the circuits the SDK loads. The Rings proof, which spends the notes in the Solana Privacy Program, is made by the Rings prover. On mainnet the SDK encrypts each request to the Rings prover's attested enclave before it leaves your device, so Pook's API and prover pass on only ciphertext, your one-time keys included.
Your keys come from one signature
When you press Unlock in the app, or call unlock() in the SDK, your wallet signs one message, the text POOK/derive/v1. The signature never leaves your device. Every key Pook uses for you is derived from it:
| Key | Derived as | Used for |
|---|---|---|
| Viewing key | SHA-256 of POOK/view/v1 and the signature | Decrypting your notes. |
| One-time key for note number i | SHA-256 of POOK/nf/v1, the signature and i | Owning and spending the note at that number. |
| Secret for seat number s | SHA-256 of POOK/seat/v1, the signature and s | Commanding that seat. |
Wallets sign the same message the same way every time, so the same wallet always gives the same keys. There is nothing separate to back up: the wallet that entered is the wallet that unlocks.
Each note you receive gets the next number, and so a fresh one-time key. Two of your notes do not share an owner hash.
Every note carries the same tag
Rings tags each output so its owner can find it. On the default Ring that tag is normally the owner's wallet address, which would tie a note to a wallet.
Pook's notes are all tagged with Pook's authority address. Every holder's notes carry that one tag, and no note carries a wallet.
How the browser finds your balance
The scan happens on your device. The API hands over encrypted records and never sees a key.
Fetch
The browser asks for the outputs tagged with Pook's authority. These are every holder's notes, all encrypted.
Decrypt
It tries your viewing key and one-time keys against them. The ones that open are yours.
Check what is spent
For each note that opened, it computes the nullifier, which only the key holder can compute, and asks whether that nullifier is on chain. A note whose nullifier is on chain is spent.
Add up
Unspent notes are summed by asset. That is the balance on Balance.
In the SDK this is pook.balance(). It returns the total for each asset and the notes behind it. Activity is built from the same scan: each note records the transaction that made it.
Spending leaves no trail to the note
When a note is spent, the chain records its nullifier. A nullifier is a hash of the note, its blinding and your one-time key. Without the key, nobody can match a nullifier to the note it spends, so an observer sees that some Pook note was spent and cannot say which.