Reference

Circuit

The spend circuit: public inputs, constraints, encryption and the proving artifacts.

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.

Constraints16,197
Public inputs14
Inputs and outputs2 notes in, 2 notes out
Note tree depth20
Seller tree depth5
Proving timeabout 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

text
21888242871839275222246405745257275088548364400416034343698204186575808495617

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

PositionValueBounds
0amount64 bits
1ownerPknonzero in a real note
2agentPk0 in a plain note, the agent's public key in a grant
3termsHash0 in a plain note
4seednonzero in a real note
5counter64 bits, 0 in a plain note
text
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:

text
sellerId = P(recipientHi, recipientLo)     for a wallet address
sellerId = recipientPk                     for an Alba address

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

PUBLIC_INPUT_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
InputMeaningBounds
rootA recent root of the pool's note tree.field element
tag0, tag1The spend tags of the two inputs. 0 for a dummy input.field element
out0, out1The commitments of the two new notes, in insertion order.field element
publicInThe amount entering the vault, in a deposit.64 bits
publicOutThe amount leaving the vault to a token account.64 bits
feeThe protocol fee plus the relay fee.64 bits
payAmountThe seller's price. 0 in an owner's spend.64 bits
recipientHi, recipientLoThe two limbs of the wallet address that is paid. Both 0 when publicOut is 0.128 bits each
payTagP(recipientPk, nonce) in a payment to an Alba address. 0 otherwise.field element
expiryBoundThe last Unix second at which the program accepts the proof.64 bits
extDataHashThe hash of the attached data.field element

Private inputs#

WitnessMeaning
isAgent1 when the agent's key spends, 0 when the owner's does.
isPrivatePayment1 in an agent's payment to an Alba address. Requires isAgent = 1.
skThe owner's spending key.
agentSkThe 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, sellerRootThe 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, nonceThe 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. isAgent and isPrivatePayment are bits, and isPrivatePayment implies isAgent.
  • Attached data. extDataHash is bound into the constraint system, so a proof is valid for one exact set of attached data.
  • Commitments. out0 and out1 equal 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 ownerPk and a nonzero seed.
  • A plain note has termsHash = 0 and counter = 0.
  • A real input's commitment hashes up to root along its path, and every direction is a bit.
  • tag0 and tag1 equal 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 ownerPk and a nonzero seed.
  • 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 the ownerPk of every real input. The owner spends plain notes and grants alike, whatever a grant's terms or expiry.
  • payAmount = 0 and payTag = 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's agentPk.
  • P(cap, expiry, sellerRoot) equals the grant's termsHash.
  • payAmount is above zero and at most cap.
  • expiryBound is at most expiry. The program requires the cluster clock to be at most expiryBound, so no agent proof executes after the grant's expiry.
  • sellerRoot is 0, or the seller's sellerId is a leaf of the seller tree.
  • Output 0 is the grant's next note: the same ownerPk, agentPk, termsHash and seed, counter + 1, and amount = 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 = 0 and both limbs are 0.
  • Output 1 is a plain note with amount = payAmount and ownerPk = recipientPk.
  • nonce is nonzero and payTag = 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:

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

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

text
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#

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

OutputMode
A deposit's note, an owner's change, a note sent to an Alba addressx25519, to the note owner's key
A new or topped-up grantgrant
A grant's next note after a paymentnone: the owner and the agent derive it from the note before it, the price and the fee
A dummynone

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.

NameContent
spend.wasmThe witness generator
spend.zkeyThe proving key
verification-key.jsonThe 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.

ts
import { noteCommitment, spendTag, proveSpend } from '@alba/sdk/protocol'
ExportSignatureWhat it does
NotetypeThe six values of an opening, as bigint.
LocatedNotetypeA Note with its leaf index, mint and commitment.
WitnessInputtypeA spend's private side: inputs, outputs, paths, and either ownerKeys or credential with seller and nonce.
dummyNote() => NoteThe all-zero note.
plainNote(amount, ownerPk) => NoteA plain note with a fresh random seed. The dummy note when amount is 0n.
grantNote(credential) => NoteA grant's first note, rebuilt from its credential.
noteFields(note) => bigint[]The six values in circuit order.
noteCommitment(note) => bigintThe note's commitment.
spendTag(note, nk) => bigintThe note's spend tag: by nk for a plain note, by seed and counter for a grant, 0n for a dummy.
randomField() => bigintA uniformly random nonzero field element.
recipientLimbs(address) => [bigint, bigint]A wallet address as its two 128-bit limbs.
sellerId(address) => bigintA 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.
MerkleTreenew MerkleTree(depth = 20)A Poseidon tree with insert(leaf), path(index) and root.
grantEncryptionKey(seed) => Uint8ArrayA grant's key.
encodeNote, decodeNote(note) => Uint8Array, (bytes) => NoteThe 145-byte note plaintext.
seal, unseal(bytes, key, aad, kind) => Uint8ArrayThe 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 nullTries one output. null when it is not yours.
encryptMemo(method, url, publicKey, mint, publicInputs, payTo?, maxBytes?) => stringThe memo, base64. With maxBytes, the URL is cut to fit.
decryptMemo(memo, secretKey, mint, publicInputs) => { method, url, payTo? } or nullOpens a memo with the owner's encryption secret key.
extDataHash(extData) => bigintThe 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) => snarkjsProofThe 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.