The alba program holds every pool's vault, verifies every proof and moves every token. It is an Anchor program with six instructions. Two of them, deposit and spend, carry all the value that moves, and one Groth16 verification stands behind each.
49hapF2ZzcSCmVDqT56QTFb3UDW28HaSDqaLSjqW5YvVThe IDL ships with the SDK as plain data:
import { ALBA_IDL } from '@alba/sdk/idl'Field elements are stored as 32 big-endian bytes. Integers are little-endian. Amounts are in the mint's raw units.
Accounts#
Config#
One per program, at the PDA with seeds ["config"].
| Field | Type | Meaning |
|---|---|---|
authority | pubkey | The key that signs open_pool, set_fees and set_fee_recipient. |
fee_recipient | pubkey | The wallet whose token account receives the protocol fee: the ALBA launch wallet. |
protocol_fee_bps | u16 | The protocol fee rate in basis points of a payment's price, 0 to 10000. |
relay_fee | u64 | The flat relay fee per spend, in raw units. |
Pool#
One per mint, at the PDA with seeds ["pool", mint].
| Field | Type | Meaning |
|---|---|---|
mint | pubkey | The pool's mint. |
vault | pubkey | The pool's token account: the associated token account of the pool PDA for the mint. |
token_program | pubkey | The token program the vault lives under. |
bump | u8 | The pool PDA's bump. |
next_leaf_index | u32 | The index the next note commitment takes. The tree holds 2^20 leaves. |
root | [u8; 32] | The note tree's current root. |
filled | [[u8; 32]; 20] | The left-hand node kept at each level, from which the next insertion computes the root. |
roots | Vec<[u8; 32]> | A ring of 64 roots: the empty tree's root and the root after each instruction's two insertions. A proof may name any root in the ring. |
root_cursor | u8 | The ring position of the newest root. |
root_count | u8 | How many ring positions hold a root, up to 64. |
The tree is a Poseidon Merkle tree of depth 20 with empty leaf 0. Circuit defines its hashing and path order.
TagPage#
Spend tags are recorded in pages. A tag's page is the PDA with seeds ["tags", pool, prefix], where prefix is the tag's low 12 bits (tag & 4095) as a little-endian u16. A page is created the first time a tag with its prefix is spent, and grows by 32 bytes with each tag after that. The transaction's payer funds the rent.
| Bytes | Content |
|---|---|
| 0 to 7 | Anchor account discriminator |
| 8 to 39 | pool |
| 40 to 41 | prefix, u16 |
| 42 to 45 | count, u32: the number of tags in the page |
| 46 | bump |
| 47 onward | count tags, 32 bytes each, in the order they were spent |
A tag is spent when its page contains it. The program compares the whole 32 bytes, so two tags that share a prefix sit in one page as separate entries.
Event authority#
The PDA with seeds ["__event_authority"] signs the program's event instructions. See Events.
Instructions#
init_config#
Creates Config. The signer must be the program's upgrade authority: the program reads its own ProgramData account and compares.
| Argument | Type | Meaning |
|---|---|---|
fee_recipientrequired | pubkey | The wallet that receives the protocol fee. |
protocol_fee_bpsrequired | u16 | 0 to 10000, or the instruction fails with InvalidFees. |
relay_feerequired | u64 | The flat relay fee in raw units. |
| Account | Signer | Writable | What it is |
|---|---|---|---|
authority | yes | yes | The program's upgrade authority. Pays for Config. |
config | yes | The Config PDA, created here. | |
program_data | The program's ProgramData account under the upgradeable loader. | ||
system_program | The System program. |
open_pool#
Opens the pool for one mint: creates the Pool account and its vault, and sets the tree to the empty root. It takes no arguments. The mint is an SPL Token mint, and the vault is created under the SPL Token program.
| Account | Signer | Writable | What it is |
|---|---|---|---|
authority | yes | yes | Config.authority. Pays for the two accounts. |
config | The Config PDA. | ||
mint | The mint to open a pool for. | ||
pool | yes | The Pool PDA, created here. | |
vault | yes | The pool's associated token account, created here. | |
token_program | The SPL Token program. | ||
associated_token_program | The Associated Token program. | ||
system_program | The System program. |
set_fees#
Replaces both fee values in Config. Config.authority signs.
| Argument | Type | Meaning |
|---|---|---|
protocol_fee_bpsrequired | u16 | 0 to 10000, or the instruction fails with InvalidFees. |
relay_feerequired | u64 | The flat relay fee in raw units. |
Accounts: authority (signer) and config (writable). A proof made under the old values fails with InvalidFees after the change, because the fee is one of its public inputs.
set_fee_recipient#
Replaces Config.fee_recipient. Config.authority signs. It takes one argument, fee_recipient: pubkey, and the accounts authority (signer) and config (writable). The new recipient's token account for a pool's mint has to exist before that pool's next spend.
deposit#
Moves tokens from the signer's token account into the vault and adds the notes the proof creates. The signer is the depositor, and the depositor is the transaction's fee payer.
It takes one argument, data: SpendData, and the same accounts as spend, both described below. On top of the shared checks:
public_inis above zero andpay_amountis absent, or the instruction fails withInvalidDeposit.sourceis owned by the signer, or it fails withInvalidAccount.- The relay fee is
0andfeeis0, or it fails withInvalidFees.
It emits DepositEvent.
spend#
Executes one proof with no tokens coming in. Every private action is this instruction: creating a grant, topping it up, revoking it, a transfer to an Alba address, a withdrawal, and an agent's payment. The signer is the relayer, which pays the network fee and receives the relay fee.
It requires public_in to be absent, or it fails with InvalidDeposit. It emits SpendEvent.
SpendData#
The argument of deposit and spend. It carries the proof and the public inputs in compact form: an optional field left out stands for zero, and the program rebuilds the fourteen field elements the verifier takes.
| Field | Type | Meaning |
|---|---|---|
proofrequired | [u8; 256] | The Groth16 proof, in the layout the scheme reference gives. |
rootrequired | [u8; 32] | The tree root the proof was made against. |
tagsrequired | [Option<[u8; 32]>; 2] | The spend tags. None for a dummy input. |
commitmentsrequired | [Option<[u8; 32]>; 2] | The new note commitments. None stands for the dummy commitment, the Poseidon hash of six zeros. |
public_inrequired | Option<u64> | The amount deposited. |
public_outrequired | Option<u64> | The amount paid out of the vault to recipient. |
feerequired | u64 | The protocol fee plus the relay fee. |
pay_amountrequired | Option<u64> | The seller's price, in an agent's payment. |
recipientrequired | Option<[u8; 32]> | The wallet address the payout goes to. |
pay_tagrequired | Option<[u8; 32]> | The pay tag of a payment to an Alba address. |
expiry_boundrequired | u64 | The last Unix second at which the instruction may execute. |
encrypted_outputsrequired | [Ciphertext; 2] | One { mode: u8, bytes: Vec<u8> } for each new note. mode is 0, 1 or 2, and bytes holds at most 218 bytes. |
memorequired | Option<Vec<u8>> | The encrypted memo, at most 240 bytes. |
An optional amount or tag that is present must be nonzero, or the instruction fails with InvalidField.
Accounts of deposit and spend#
| Account | Signer | Writable | What it is |
|---|---|---|---|
payer | yes | yes | The depositor in deposit, the relayer in spend. Pays the network fee and tag-page rent. |
config | The Config PDA. | ||
pool | yes | The Pool PDA of mint. | |
vault | yes | The pool's vault. | |
mint | The pool's mint. | ||
source | yes | A token account of the mint. In deposit, the depositor's account the tokens leave. | |
recipient | yes | A token account of the mint. When public_out is above zero, the account that is paid. | |
protocol_fees | yes | A token account of the mint owned by Config.fee_recipient. | |
relay_fees | yes | A token account of the mint owned by payer. | |
token_program | The SPL Token program. | ||
system_program | The System program. | ||
tag_page0 | yes | The TagPage of tags[0]. | |
tag_page1 | yes | The TagPage of tags[1]. When both tags share a prefix, the same page is passed twice. | |
event_authority | The event authority PDA. | ||
program | The alba program itself. |
What deposit and spend check#
Both instructions run the same steps in this order, and any failure reverts the whole transaction.
The deadline
The cluster clock's Unix time is at most
expiry_bound. OtherwiseGrantExpired.The root
rootis one of the pool's recent roots. OtherwiseUnknownRoot.Distinct tags
Two real tags differ. Otherwise
SpentTag.The fees
The program computes the protocol fee from
pay_amountandConfig.protocol_fee_bps, adds the relay fee, and requires the sum to equalfee. OtherwiseInvalidFees.The recipient
When
public_outis above zero, therecipienttoken account is owned by the wallet indata.recipient. When it is zero,data.recipientis absent. OtherwiseInvalidAccount.The attached data
The program hashes the mint, the payer, the recipient token account, the relay fee, both encrypted outputs and the memo into
extDataHash, the proof's fourteenth public input. An oversized or malformed output fails withInvalidCiphertext, an oversized memo withMemoTooLarge.The proof
The Groth16 proof verifies against the fourteen public inputs and the program's verifying key. Otherwise
ProofRefused.The spend tags
Each real tag is appended to its page. A tag the page already holds fails with
SpentTag.The transfers
public_inmoves fromsourceto the vault, signed by the payer.public_outmoves from the vault torecipient, the protocol fee toprotocol_fees, and the relay fee torelay_fees, each signed by the pool PDA.The notes
Both commitments are inserted into the tree,
commitments[0]first, and the new root joins the ring. A full tree fails withTreeFull.
Because the payer and both fee accounts are bound, through extDataHash and the account checks, a proof submitted by another signer or toward another fee account does not verify.
Fees#
protocolFee = floor(pay_amount × protocol_fee_bps / 10000)
fee = protocolFee + relayFeeThe multiplication runs in 128 bits. The relay fee is Config.relay_fee in spend and 0 in deposit. The protocol fee is nonzero only where pay_amount is, which is an agent's payment to a seller.
Both fees leave the vault in the same instruction as the payment: the protocol fee to the token account of Config.fee_recipient, the relay fee to the token account of the relayer that signed. The proof's conservation rule counts fee as value leaving the notes, so the vault's balance always equals the sum of unspent notes. Fees and the ALBA token says what the protocol fee is for.
Events#
deposit emits DepositEvent and spend emits SpendEvent. Both hold one SpendEventData.
The program emits events with Anchor's emit_cpi!: each event is an inner instruction the program sends to itself, signed by the event authority PDA, with the event bytes as instruction data. An indexer reads a transaction's inner instructions, keeps the ones addressed to the alba program and signed by the event authority, and decodes the data after the 8-byte event tag and the 8-byte event discriminator. Events read this way are complete whatever the transaction's logs hold.
Fields of SpendEventData, in order:
| Field | Type | Meaning |
|---|---|---|
version | u8 | 1. |
mint | pubkey | The pool's mint. |
relayer | pubkey | The transaction's payer. |
recipient_token_account | pubkey | The account paid public_out. All zeros when nothing was paid out. |
root_before | [u8; 32] | The root the proof named. |
tags | [[u8; 32]; 2] | The spend tags. Zeros for a dummy input. |
commitments | [[u8; 32]; 2] | The new note commitments. |
leaf_indexes | [u32; 2] | Where the two commitments sit in the tree. |
public_in | u64 | The amount deposited. |
public_out | u64 | The amount paid out of the vault. |
fee | u64 | The protocol fee plus the relay fee. |
pay_amount | u64 | The seller's price. Zero outside a payment. |
recipient | [u8; 32] | The wallet paid. Zeros when nothing was paid out. |
pay_tag | [u8; 32] | The pay tag of a payment to an Alba address. Zeros otherwise. |
expiry_bound | u64 | The deadline the proof named. |
ext_data_hash | [u8; 32] | The hash of the attached data. |
relay_fee | u64 | The relay fee. The protocol fee is fee minus this. |
encrypted_outputs | [Ciphertext; 2] | The encrypted openings of the two new notes. |
memo | Vec<u8> | The encrypted memo. |
root_after | [u8; 32] | The tree's root after both insertions. |
An event holds everything a scanner needs: the leaves and their positions, the openings to try, the tags that were spent and the memo. The facilitator's scanning feeds are these events, stored in order.
Errors#
| Error | Type | Meaning |
|---|---|---|
ProofRefused | 6000 | Proof refused. |
UnknownRoot | 6001 | Unknown root. |
SpentTag | 6002 | Spend tag already spent. |
GrantExpired | 6003 | Expiry bound passed. |
InvalidFees | 6004 | Fee mismatch or overflow. |
InvalidAccount | 6005 | Invalid token account or PDA. |
InvalidDeposit | 6006 | Invalid deposit. |
InvalidField | 6007 | Invalid field element. |
TreeFull | 6008 | Merkle tree is full. |
TagPageFull | 6009 | Tag page is full. |
InvalidCiphertext | 6010 | Invalid encrypted output. |
MemoTooLarge | 6011 | Memo exceeds the transaction envelope. |
| Error | Raised when |
|---|---|
ProofRefused | The proof does not verify, or one of its three points is all zeros. |
UnknownRoot | root is not in the pool's ring of 64 roots. |
SpentTag | A tag is already in its page, or both tags of one instruction are the same. |
GrantExpired | The cluster clock is past expiry_bound. |
InvalidFees | fee differs from the fee computed from Config, a rate is above 10000, or the sum overflows. |
InvalidAccount | A token account has the wrong owner, a tag page is not the PDA of its tag, the recipient does not match, or init_config is not signed by the upgrade authority. |
InvalidDeposit | deposit without public_in or with pay_amount, or spend with public_in. |
InvalidField | An optional amount or tag is present and zero. |
TreeFull | The pool's tree has no free leaf. |
TagPageFull | A tag page has reached the largest size an account can have. |
InvalidCiphertext | An encrypted output has an unknown mode, more than 218 bytes, or bytes under mode 0. |
MemoTooLarge | The memo is longer than 240 bytes. |
Anchor's own account errors (a wrong seed, a wrong mint on a token account, a missing signer) come back under Anchor's codes.
Measured figures#
Measured on a local validator, one transaction per flow. Each transaction holds one alba instruction, and the compute units are that instruction's, with its event included.
| Flow | Instruction | Compute units | Transaction bytes |
|---|---|---|---|
| Deposit | deposit | 271,409 | 860 |
| Create a grant | spend | 289,429 | 1,134 |
| Payment to a wallet address | spend | 281,183 | 877 |
| Payment to an Alba address | spend | 283,139 | 1,108 |
| Payment to an Alba address, 240-byte memo | spend | 280,618 | 1,232 |
| Top up | spend | 290,553 | 1,198 |
| Revoke | spend | 278,896 | 916 |
| Withdraw | spend | 285,306 | 957 |
The largest case, a payment to an Alba address with a full memo, is exactly the 1,232 bytes a Solana transaction may have. That is where the limits of 240 memo bytes and 218 bytes per encrypted output come from.