Reference

Program

Accounts, instructions, events, errors and measured figures of the alba program.

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.

Program id
49hapF2ZzcSCmVDqT56QTFb3UDW28HaSDqaLSjqW5YvV

The IDL ships with the SDK as plain data:

ts
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"].

FieldTypeMeaning
authoritypubkeyThe key that signs open_pool, set_fees and set_fee_recipient.
fee_recipientpubkeyThe wallet whose token account receives the protocol fee: the ALBA launch wallet.
protocol_fee_bpsu16The protocol fee rate in basis points of a payment's price, 0 to 10000.
relay_feeu64The flat relay fee per spend, in raw units.

Pool#

One per mint, at the PDA with seeds ["pool", mint].

FieldTypeMeaning
mintpubkeyThe pool's mint.
vaultpubkeyThe pool's token account: the associated token account of the pool PDA for the mint.
token_programpubkeyThe token program the vault lives under.
bumpu8The pool PDA's bump.
next_leaf_indexu32The 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.
rootsVec<[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_cursoru8The ring position of the newest root.
root_countu8How 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.

BytesContent
0 to 7Anchor account discriminator
8 to 39pool
40 to 41prefix, u16
42 to 45count, u32: the number of tags in the page
46bump
47 onwardcount 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.

ArgumentTypeMeaning
fee_recipientrequiredpubkeyThe wallet that receives the protocol fee.
protocol_fee_bpsrequiredu160 to 10000, or the instruction fails with InvalidFees.
relay_feerequiredu64The flat relay fee in raw units.
AccountSignerWritableWhat it is
authorityyesyesThe program's upgrade authority. Pays for Config.
configyesThe Config PDA, created here.
program_dataThe program's ProgramData account under the upgradeable loader.
system_programThe 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.

AccountSignerWritableWhat it is
authorityyesyesConfig.authority. Pays for the two accounts.
configThe Config PDA.
mintThe mint to open a pool for.
poolyesThe Pool PDA, created here.
vaultyesThe pool's associated token account, created here.
token_programThe SPL Token program.
associated_token_programThe Associated Token program.
system_programThe System program.

set_fees#

Replaces both fee values in Config. Config.authority signs.

ArgumentTypeMeaning
protocol_fee_bpsrequiredu160 to 10000, or the instruction fails with InvalidFees.
relay_feerequiredu64The 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_in is above zero and pay_amount is absent, or the instruction fails with InvalidDeposit.
  • source is owned by the signer, or it fails with InvalidAccount.
  • The relay fee is 0 and fee is 0, or it fails with InvalidFees.

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.

FieldTypeMeaning
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_inrequiredOption<u64>The amount deposited.
public_outrequiredOption<u64>The amount paid out of the vault to recipient.
feerequiredu64The protocol fee plus the relay fee.
pay_amountrequiredOption<u64>The seller's price, in an agent's payment.
recipientrequiredOption<[u8; 32]>The wallet address the payout goes to.
pay_tagrequiredOption<[u8; 32]>The pay tag of a payment to an Alba address.
expiry_boundrequiredu64The 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.
memorequiredOption<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#

AccountSignerWritableWhat it is
payeryesyesThe depositor in deposit, the relayer in spend. Pays the network fee and tag-page rent.
configThe Config PDA.
poolyesThe Pool PDA of mint.
vaultyesThe pool's vault.
mintThe pool's mint.
sourceyesA token account of the mint. In deposit, the depositor's account the tokens leave.
recipientyesA token account of the mint. When public_out is above zero, the account that is paid.
protocol_feesyesA token account of the mint owned by Config.fee_recipient.
relay_feesyesA token account of the mint owned by payer.
token_programThe SPL Token program.
system_programThe System program.
tag_page0yesThe TagPage of tags[0].
tag_page1yesThe TagPage of tags[1]. When both tags share a prefix, the same page is passed twice.
event_authorityThe event authority PDA.
programThe alba program itself.

What deposit and spend check#

Both instructions run the same steps in this order, and any failure reverts the whole transaction.

  1. The deadline

    The cluster clock's Unix time is at most expiry_bound. Otherwise GrantExpired.

  2. The root

    root is one of the pool's recent roots. Otherwise UnknownRoot.

  3. Distinct tags

    Two real tags differ. Otherwise SpentTag.

  4. The fees

    The program computes the protocol fee from pay_amount and Config.protocol_fee_bps, adds the relay fee, and requires the sum to equal fee. Otherwise InvalidFees.

  5. The recipient

    When public_out is above zero, the recipient token account is owned by the wallet in data.recipient. When it is zero, data.recipient is absent. Otherwise InvalidAccount.

  6. 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 with InvalidCiphertext, an oversized memo with MemoTooLarge.

  7. The proof

    The Groth16 proof verifies against the fourteen public inputs and the program's verifying key. Otherwise ProofRefused.

  8. The spend tags

    Each real tag is appended to its page. A tag the page already holds fails with SpentTag.

  9. The transfers

    public_in moves from source to the vault, signed by the payer. public_out moves from the vault to recipient, the protocol fee to protocol_fees, and the relay fee to relay_fees, each signed by the pool PDA.

  10. The notes

    Both commitments are inserted into the tree, commitments[0] first, and the new root joins the ring. A full tree fails with TreeFull.

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#

text
protocolFee = floor(pay_amount × protocol_fee_bps / 10000)
fee         = protocolFee + relayFee

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

FieldTypeMeaning
versionu81.
mintpubkeyThe pool's mint.
relayerpubkeyThe transaction's payer.
recipient_token_accountpubkeyThe 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_inu64The amount deposited.
public_outu64The amount paid out of the vault.
feeu64The protocol fee plus the relay fee.
pay_amountu64The 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_boundu64The deadline the proof named.
ext_data_hash[u8; 32]The hash of the attached data.
relay_feeu64The relay fee. The protocol fee is fee minus this.
encrypted_outputs[Ciphertext; 2]The encrypted openings of the two new notes.
memoVec<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#

ErrorTypeMeaning
ProofRefused6000Proof refused.
UnknownRoot6001Unknown root.
SpentTag6002Spend tag already spent.
GrantExpired6003Expiry bound passed.
InvalidFees6004Fee mismatch or overflow.
InvalidAccount6005Invalid token account or PDA.
InvalidDeposit6006Invalid deposit.
InvalidField6007Invalid field element.
TreeFull6008Merkle tree is full.
TagPageFull6009Tag page is full.
InvalidCiphertext6010Invalid encrypted output.
MemoTooLarge6011Memo exceeds the transaction envelope.
ErrorRaised when
ProofRefusedThe proof does not verify, or one of its three points is all zeros.
UnknownRootroot is not in the pool's ring of 64 roots.
SpentTagA tag is already in its page, or both tags of one instruction are the same.
GrantExpiredThe cluster clock is past expiry_bound.
InvalidFeesfee differs from the fee computed from Config, a rate is above 10000, or the sum overflows.
InvalidAccountA 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.
InvalidDepositdeposit without public_in or with pay_amount, or spend with public_in.
InvalidFieldAn optional amount or tag is present and zero.
TreeFullThe pool's tree has no free leaf.
TagPageFullA tag page has reached the largest size an account can have.
InvalidCiphertextAn encrypted output has an unknown mode, more than 218 bytes, or bytes under mode 0.
MemoTooLargeThe 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.

FlowInstructionCompute unitsTransaction bytes
Depositdeposit271,409860
Create a grantspend289,4291,134
Payment to a wallet addressspend281,183877
Payment to an Alba addressspend283,1391,108
Payment to an Alba address, 240-byte memospend280,6181,232
Top upspend290,5531,198
Revokespend278,896916
Withdrawspend285,306957

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.