A balance is what one owner holds inside a pool. The pool is public and its total is public. Which part of it belongs to whom is known only to each owner.
Pools#
The program keeps one pool per mint. A pool is a vault, a token account that holds every deposit of that mint, and a note tree, a Merkle tree of note commitments with depth 20. Beside them the program records every spend tag it has accepted, so no note is spent twice.
The first pool holds USDC, since x402 sellers price in USDC. The program's authority opens a pool for a mint of the SPL Token program.
Notes#
A note is one private amount in a pool. It is six values, called its opening:
| Value | In a plain note | In a grant |
|---|---|---|
amount | the amount, in raw units of the mint | the amount the grant has left |
ownerPk | the owner's public key | the owner's public key |
agentPk | 0 | the agent's public key |
termsHash | 0 | the hash of the grant's terms |
seed | a fresh random value | the grant's seed |
counter | 0 | the number of spends the grant has made |
The tree stores only the note's commitment, the Poseidon hash of the six values. A commitment says nothing about the amount or the owner. The opening travels beside it in the same transaction, encrypted to the owner's X25519 key with XChaCha20-Poly1305.
Spending a note publishes its spend tag. For a plain note the tag is a hash of the commitment and a key only the owner has, so nobody else can tell which commitment a tag belongs to. Grants explains how a grant's notes differ.
The Alba key#
The owner's keys come from one wallet signature. The app asks the wallet to sign this exact message:
Alba private balance
Sign this message to open your private balance.
This signature moves no funds.From the 64-byte signature the SDK derives four values:
| Key | What it does |
|---|---|
sk | the spending key: proves ownership of a note |
pk | the public key a note is addressed to |
nk | the key that makes the spend tags of the owner's plain notes |
| the encryption key pair | an X25519 pair: others encrypt openings and memos to the public half, the owner decrypts with the secret half |
A wallet returns the same signature for the same message, so the same wallet opens the same balance in any browser, with nothing stored and no second secret to back up. The keys stay in memory and are never sent to the facilitator.
In code, opening the balance is one call. signMessage is the wallet's own method:
import { connectBalance } from '@alba/sdk'
const owner = await connectBalance((message) => wallet.signMessage(message))
owner.address // 'alba:…'The Alba address#
An Alba address is a private receiving address: alba: followed by the base58 encoding of a version byte, pk and the X25519 public key, 65 bytes in all. Give it to anyone who pays you inside a pool. A seller uses one as its pay-to address to receive privately.
Scanning#
The owner's notes are found by scanning. The facilitator publishes three append-only feeds per pool: the tree's leaves, the encrypted openings that came with them, and the spend tags. The SDK reads them, tries to decrypt each opening with the owner's key, keeps the ones that open and match their commitment, and drops a note once its tag appears in the tag feed. All of that runs in the browser. The facilitator serves the same public feeds to everyone and has no way to tell which entries are yours.
A scan reports its progress as it goes, so the app shows notes as they are found. The balance of each asset has three figures:
| Figure | Meaning |
|---|---|
available | the owner's plain notes |
granted | what the owner's active grants have left |
total | the two together |
Each note the scan finds has a kind: plain for a deposit or change, received for a payment that arrived at the owner's Alba address, and grant for the current note of one of the owner's grants.
Deposit and withdrawal#
A balance touches the public chain in two places.
A deposit is a token transfer from the owner's wallet into the pool's vault. The wallet signs the transaction and pays its network fee, and Alba charges nothing on it. It adds a note for the amount. The chain shows the wallet, the amount and the pool.
A withdrawal pays an amount from the vault to a public token account. The owner proves they can spend notes covering it, and the facilitator relays the transaction. The chain shows the pool, the amount and the receiving account.
Everything between those two is private: creating a grant, topping it up, revoking it, and sending to another Alba address all move value from notes to notes inside the pool.
One spend takes at most two notes as inputs and makes at most two. An amount that no two of the owner's notes cover is refused in the SDK with INSUFFICIENT_BALANCE.
| Anyone | The owner | |
|---|---|---|
| Deposit | wallet, amount | wallet, amount |
| Balance | sealed | every note |
| Grants | sealed | each grant and its terms |
| Withdrawal | account, amount | account, amount |