Alba has one circuit, spend. A proof from it says that up to two notes in a pool's tree are being spent by someone entitled to spend them, that up to two new notes are created, and that the value going in equals the value coming out. When the spender is an agent, it also says the payment is inside the grant's terms and the remainder went back into the same grant. Every deposit, grant, payment and withdrawal is one such proof, verified by the program.
The circuit is written in circom 2 and proved with Groth16 over BN254.
| Constraints | 16,197 |
| Public inputs | 14 |
| Inputs and outputs | 2 notes in, 2 notes out |
| Note tree depth | 20 |
| Seller tree depth | 5 |
| Proving time | about 2.1 seconds in Node, single thread |
Primitives#
The field. Every value in the circuit is an element of the BN254 scalar field, with modulus
21888242871839275222246405745257275088548364400416034343698204186575808495617On the wire a field element is 32 big-endian bytes and is always below the modulus. A value at or above it is refused, never reduced.
Poseidon. P(x0, …, xn) is circomlib's Poseidon over that field: exponent 5, eight full rounds, initial state zero, the first state element as output. The circuit uses it with 1, 2, 3 and 6 inputs. The SDK uses poseidon-lite, and the program uses Solana's Poseidon syscall with the BN254 parameters and big-endian bytes.
SHA-256. Used outside the circuit, for key derivation and for the hash of the attached data. HF(bytes) is the SHA-256 digest read as a big-endian integer and reduced modulo the field.
Addresses. A Solana address is 32 bytes and does not fit one field element, so it enters the circuit as two 128-bit limbs: the first 16 bytes and the last 16 bytes, each read big-endian.
Notes#
A note's opening is six field elements, in this order:
| Position | Value | Bounds |
|---|---|---|
| 0 | amount | 64 bits |
| 1 | ownerPk | nonzero in a real note |
| 2 | agentPk | 0 in a plain note, the agent's public key in a grant |
| 3 | termsHash | 0 in a plain note |
| 4 | seed | nonzero in a real note |
| 5 | counter | 64 bits, 0 in a plain note |
commitment = P(amount, ownerPk, agentPk, termsHash, seed, counter)
termsHash = P(cap, expiry, sellerRoot)
plainSpendTag = P(nk, commitment) nk = P(sk, 1)
grantSpendTag = P(seed, counter)
ownerPk = P(sk)
agentPk = P(agentSk)A note with agentPk = 0 is a plain note, and any other is a grant. A plain note's seed is a fresh random field element. A grant's seed is derived from the owner's key and the grant's index, and its counter goes up by one with each spend, which is what lets the owner list a grant's tags in order.
The dummy note is all six values zero. Its commitment is P(0, 0, 0, 0, 0, 0) and its spend tag is 0. An input with amount zero is a dummy and needs no place in the tree. A dummy output still takes a leaf.
The note tree#
A pool's tree has depth 20 and holds 1,048,576 leaves, filled in order from index 0. A parent is P(left, right). An empty leaf is 0, so an empty subtree at level d + 1 is P(zero[d], zero[d]) with zero[0] = 0.
A membership path is 20 siblings from the leaf upward and 20 direction bits, the leaf index's bits from least significant. A bit of 0 puts the running node on the left, 1 on the right.
Each instruction inserts its two outputs, out0 then out1, and the root after both joins the pool's ring of 64 recent roots. A proof names one root from the ring.
The seller list#
A seller is identified in the circuit by one field element:
sellerId = P(recipientHi, recipientLo) for a wallet address
sellerId = recipientPk for an Alba addressA grant's seller list is a tree of depth 5: the sellerId values in the order the owner listed them, followed by zeros up to 32 leaves, hashed like the note tree. sellerRoot is its root. A grant open to any seller has sellerRoot = 0, and the circuit skips the membership check for it.
Public inputs#
The verifier takes fourteen field elements in this order:
0 root
1 tag0
2 tag1
3 out0
4 out1
5 publicIn
6 publicOut
7 fee
8 payAmount
9 recipientHi
10 recipientLo
11 payTag
12 expiryBound
13 extDataHash| Input | Meaning | Bounds |
|---|---|---|
root | A recent root of the pool's note tree. | field element |
tag0, tag1 | The spend tags of the two inputs. 0 for a dummy input. | field element |
out0, out1 | The commitments of the two new notes, in insertion order. | field element |
publicIn | The amount entering the vault, in a deposit. | 64 bits |
publicOut | The amount leaving the vault to a token account. | 64 bits |
fee | The protocol fee plus the relay fee. | 64 bits |
payAmount | The seller's price. 0 in an owner's spend. | 64 bits |
recipientHi, recipientLo | The two limbs of the wallet address that is paid. Both 0 when publicOut is 0. | 128 bits each |
payTag | P(recipientPk, nonce) in a payment to an Alba address. 0 otherwise. | field element |
expiryBound | The last Unix second at which the program accepts the proof. | 64 bits |
extDataHash | The hash of the attached data. | field element |
Private inputs#
| Witness | Meaning |
|---|---|
isAgent | 1 when the agent's key spends, 0 when the owner's does. |
isPrivatePayment | 1 in an agent's payment to an Alba address. Requires isAgent = 1. |
sk | The owner's spending key. |
agentSk | The agent's key, from the grant credential. |
inputs[2][6], outputs[2][6] | The openings of the two spent notes and the two new notes. |
siblings[2][20], directions[2][20] | The membership path of each input. |
cap, expiry, sellerRoot | The grant's terms. 64 bits each for cap and expiry. |
sellerSiblings[5], sellerDirections[5] | The seller's membership path in the grant's seller tree. |
recipientPk, nonce | The key inside the seller's Alba address, and the nonce from its payment requirements. |
Constraints#
Every proof#
- Conservation.
in0.amount + in1.amount + publicIn = out0.amount + out1.amount + publicOut + fee. Every term is range-checked to 64 bits, so the sum cannot wrap the field. - Flags.
isAgentandisPrivatePaymentare bits, andisPrivatePaymentimpliesisAgent. - Attached data.
extDataHashis bound into the constraint system, so a proof is valid for one exact set of attached data. - Commitments.
out0andout1equal the commitments of the two output openings.
Each input#
- An input with amount zero is a dummy: its other five values are zero and its tag is
0. - A real input has a nonzero
ownerPkand a nonzeroseed. - A plain note has
termsHash = 0andcounter = 0. - A real input's commitment hashes up to
rootalong its path, and every direction is a bit. tag0andtag1equal the inputs' spend tags:P(nk, commitment)for a plain note,P(seed, counter)for a grant.- A real input's tag is nonzero, and two real inputs have different tags.
Each output#
- An output that has an amount, or is a grant, has a nonzero
ownerPkand a nonzeroseed. - Any other output is the dummy note, all zeros.
- Amount and counter are 64 bits.
The owner's branch#
With isAgent = 0:
P(sk)equals theownerPkof every real input. The owner spends plain notes and grants alike, whatever a grant's terms or expiry.payAmount = 0andpayTag = 0.- The outputs are free within the rules above. This is how an owner creates a grant, tops one up, revokes one, sends to an Alba address and withdraws.
A deposit is the owner's branch with publicIn above zero. It may have no real input.
The agent's branch#
With isAgent = 1:
- Input 0 is a real grant, input 1 is a dummy, and
publicIn = 0. P(agentSk)equals the grant'sagentPk.P(cap, expiry, sellerRoot)equals the grant'stermsHash.payAmountis above zero and at mostcap.expiryBoundis at mostexpiry. The program requires the cluster clock to be at mostexpiryBound, so no agent proof executes after the grant's expiry.sellerRootis0, or the seller'ssellerIdis a leaf of the seller tree.- Output 0 is the grant's next note: the same
ownerPk,agentPk,termsHashandseed,counter + 1, andamount = input amount − payAmount − fee.
For a payment to a wallet address, isPrivatePayment = 0:
publicOut = payAmount, and the two limbs name the wallet.- Output 1 is the dummy note, and
payTag = 0.
For a payment to an Alba address, isPrivatePayment = 1:
publicOut = 0and both limbs are0.- Output 1 is a plain note with
amount = payAmountandownerPk = recipientPk. nonceis nonzero andpayTag = P(recipientPk, nonce).
An agent's proof has exactly one place for value to go beside the seller and the fees, and that place is the same grant with its counter advanced.
The attached data#
Data the circuit does not parse is bound through its hash:
extDataHash = HF(
"alba:v1:ext-data" || 0x00 || u8(1)
|| mint[32] || relayer[32]
|| recipientTokenAccount[32] (32 zero bytes when there is none)
|| u64le(relayFee)
|| u8(output0.mode) || u32le(length) || output0.ciphertext
|| u8(output1.mode) || u32le(length) || output1.ciphertext
|| u32le(length) || memo
)Mode bytes are 0 for none, 1 for x25519 and 2 for grant. The program rebuilds the same bytes from the transaction's own accounts and instruction data, so the mint, the relayer, the paid token account, the relay fee, both ciphertexts and the memo are fixed by the proof. The scheme reference gives the same data as JSON.
The proof#
A proof is 256 bytes: the three Groth16 points laid out for Solana's pairing syscall, with A negated. The scheme reference has the byte table. encodeProof and decodeProof convert between that layout and snarkjs's.
The verifying key has fifteen input points, one constant and one per public input, and is compiled into the program.
Encryption#
Openings and memos are encrypted outside the circuit with X25519, HKDF-SHA256 and XChaCha20-Poly1305. Every message uses a fresh ephemeral key and a random 24-byte nonce.
To a public key#
For a note sent to its owner, and for a memo:
shared = X25519(ephemeralSecret, recipientEncryptionPublicKey)
key = HKDF-SHA256(ikm = shared, salt = "Alba/v1", info = "x25519-note" or "x25519-memo", 32 bytes)
envelope = u8(1) || ephemeralPublicKey[32] || nonce[24] || ciphertext || tag[16]An all-zero shared secret is refused.
Under a grant's key#
For a grant's opening when the grant is created or topped up, so that the owner and the agent can both open it:
grantKey = HKDF-SHA256(ikm = seed as 32 bytes, salt = "Alba/v1", info = "grant-encryption", 32 bytes)
envelope = u8(1) || nonce[24] || ciphertext || tag[16]Plaintexts#
note = u8(1) || u64le(amount) || ownerPk[32] || agentPk[32] || termsHash[32] || seed[32] || u64le(counter) 145 bytes
aad = "alba:v1:note" || 0x00 || mint[32] || commitment[32]
memo = u8(2) || u16le(length) || method || u8(n) || payTo[n] || u16le(length) || url
aad = "alba:v1:memo" || 0x00 || mint[32] || tag0[32] || tag1[32] || out0[32] || out1[32]The method is upper case. payTo is the 65 decoded bytes of the seller's Alba address in a payment to one, and empty with n = 0 otherwise. A URL that would take the encrypted memo past its limit is cut and ended with U+2026. A reader also accepts version 1, u8(1) || u16le(length) || method || u16le(length) || url. A decrypted note is accepted only when its commitment equals the leaf it came with, so a ciphertext that opens to anything else is ignored.
Which output carries which mode:
| Output | Mode |
|---|---|
| A deposit's note, an owner's change, a note sent to an Alba address | x25519, to the note owner's key |
| A new or topped-up grant | grant |
| A grant's next note after a payment | none: the owner and the agent derive it from the note before it, the price and the fee |
| A dummy | none |
An encrypted opening is at most 218 bytes and an encrypted memo at most 240, which leaves 158 bytes for the URL of a GET request to a wallet pay-to and 93 for one to an Alba address.
Artifacts#
A prover loads two files and a verifier one. The facilitator serves them and lists them in a manifest at GET /v1/artifacts.
| Name | Content |
|---|---|
spend.wasm | The witness generator |
spend.zkey | The proving key |
verification-key.json | The verifying key, for checking a proof off chain |
Each manifest entry carries the file's sha256 and length. proveSpend downloads the two prover files from the URLs in the manifest and refuses a file whose digest differs. The same two files run in Node and in a browser.
Building proofs yourself#
@alba/sdk/protocol exports the pieces the SDK itself is made of, for a prover or a scanner of your own.
import { noteCommitment, spendTag, proveSpend } from '@alba/sdk/protocol'| Export | Signature | What it does |
|---|---|---|
Note | type | The six values of an opening, as bigint. |
LocatedNote | type | A Note with its leaf index, mint and commitment. |
WitnessInput | type | A spend's private side: inputs, outputs, paths, and either ownerKeys or credential with seller and nonce. |
dummyNote | () => Note | The all-zero note. |
plainNote | (amount, ownerPk) => Note | A plain note with a fresh random seed. The dummy note when amount is 0n. |
grantNote | (credential) => Note | A grant's first note, rebuilt from its credential. |
noteFields | (note) => bigint[] | The six values in circuit order. |
noteCommitment | (note) => bigint | The note's commitment. |
spendTag | (note, nk) => bigint | The note's spend tag: by nk for a plain note, by seed and counter for a grant, 0n for a dummy. |
randomField | () => bigint | A uniformly random nonzero field element. |
recipientLimbs | (address) => [bigint, bigint] | A wallet address as its two 128-bit limbs. |
sellerId | (address) => bigint | A seller's identifier, for a wallet address or an Alba address. |
sellerTree | (sellers) => { root, tree, ids } | The depth-5 seller tree. root is 0n for an empty list. |
MerkleTree | new MerkleTree(depth = 20) | A Poseidon tree with insert(leaf), path(index) and root. |
grantEncryptionKey | (seed) => Uint8Array | A grant's key. |
encodeNote, decodeNote | (note) => Uint8Array, (bytes) => Note | The 145-byte note plaintext. |
seal, unseal | (bytes, key, aad, kind) => Uint8Array | The X25519 envelope. unseal throws when authentication fails. |
encryptNote | (note, mint, key, grant = false) => { mode, ciphertext } | An output's encrypted opening, to a public key or under a grant's key. |
decryptNote | (output, mint, commitment, key) => Note or null | Tries one output. null when it is not yours. |
encryptMemo | (method, url, publicKey, mint, publicInputs, payTo?, maxBytes?) => string | The memo, base64. With maxBytes, the URL is cut to fit. |
decryptMemo | (memo, secretKey, mint, publicInputs) => { method, url, payTo? } or null | Opens a memo with the owner's encryption secret key. |
extDataHash | (extData) => bigint | The hash of the attached data. |
sealGrantRecord, openGrantRecord | (data, seed, locator, revision) | A grant record's ciphertext, bound to its locator and revision. |
encodeProof, decodeProof | (snarkjsProof) => string, (base64) => snarkjsProof | The 256-byte proof layout. |
proveSpend | (publicInputs, extData, witness, options?) => Promise<SpendRequest> | Loads the artifacts, computes the witness, proves, and returns { proof, publicInputs, extData } with extDataHash filled in. |
proveSpend takes the SDK's usual options: facilitatorUrl or artifactBaseUrl for where the artifacts are, fetch, signal, and onProgress, which reports the stages loading_artifacts, witness and proving. Its result is the body of POST /v1/spends/relay and the payload of an alba payment.