Concepts

Grants

The note an agent spends: its terms, the two keys that spend it, the credential, and its states.

A grant is a note an agent can spend inside terms the owner set. It is the one thing an owner gives an agent: the agent never holds the owner's key and never holds a wallet.

The terms#

The owner sets five things when creating a grant.

TermTypeMeaning
amountrequiredu64What the grant holds when it is created, in raw units of the mint.
caprequiredu64The most one payment may send to a seller, in raw units. Fees are charged on top of it.
expiryrequiredu64The last second the agent may pay, as Unix seconds (UTC).
sellersrequiredstring[]The addresses the grant may pay: up to 32, each a wallet address or an Alba address. An empty list means any seller.
labelrequiredstringThe owner's name for the grant, up to 256 bytes. It is kept in the grant's encrypted record, which opens with the grant's seed, and never appears on chain.

The cap, the expiry and the seller list are hashed into the note itself as its termsHash. A seller list is committed as the root of a small Merkle tree of the sellers in the order given.

How the terms are enforced#

A grant note can be spent by two keys.

The agent's key spends it only through a payment proof. The proof shows, without revealing the grant, that:

  • the amount paid is above zero and at most the cap
  • the deadline the payment names is no later than the expiry, and the program checks that deadline against the chain's clock
  • the pay-to address is on the seller list, or the list is open
  • everything left over goes into the grant's next note, with the same owner, the same agent key, the same terms and the same seed

The last point is what makes the terms hold for the life of the grant. Each payment replaces the grant's note with a smaller one carrying identical terms, so an agent cannot pay itself the remainder, loosen a limit or move the grant elsewhere. A payment outside the terms has no valid proof, and the program accepts nothing without one.

The owner's key spends the note with no limits. That is how a grant is topped up and revoked, and it is the only key that spends a grant after its expiry.

The grant credential#

The credential is the string the agent holds. It starts with alba_grant_ and is at most 8192 characters. It encodes:

FieldMeaning
version1
seedthe grant's seed, from which its notes and spend tags follow
agent keythe secret key that proves payments
owner public keywho the remainder returns to
owner encryption keythe public key memos are encrypted to
cap, expiry, sellersthe terms
mintthe pool the grant lives in
facilitator URLwhere the agent sends proofs
starting amountwhat the grant held when created

The seed and the agent key are derived from the owner's key and the grant's index, a number that starts at zero and goes up by one per grant. So the owner can show a grant's credential again at any time, from any device, and nothing has to be saved when it is first shown.

With a credential, a holder can pay inside the terms and read the grant's status: its label, its terms, what it has spent and what it has left. A credential cannot open the owner's balance, cannot spend any other grant, and cannot decrypt the memos in the ledger.

Give the agent its credential as the ALBA_GRANT environment variable, or pass it in code:

ts
import { alba } from '@alba/sdk'

const agent = alba.with(process.env.RESEARCH_GRANT!)
const res = await agent.fetch('https://api.example/v1/search?q=lithium')

What a payment does to a grant#

Each payment spends the grant's current note and creates the next one:

text
next amount = current amount - price - fees
next counter = current counter + 1

The price is the seller's. The fees are the protocol fee and the relay fee, described in Fees and the ALBA token. A payment the grant cannot cover with its fees has no valid proof, and alba.fetch refuses it with INSUFFICIENT_GRANT_BALANCE before proving.

States#

StateMeaningWhat the agent can do
activeThe grant holds value and its expiry is ahead.Pay inside the terms.
expiredThe expiry has passed. What is left stays in the grant until the owner revokes it.Nothing.
spentThe grant has paid out its whole amount.Nothing.
revokedThe owner took the remainder back.Nothing.

Top up#

A top-up adds value to a grant that still holds some. The owner spends the grant's current note together with one of their own notes into the grant's next note, with the same terms and a larger amount. That one note has to cover the added amount and the relay fee. The credential does not change, and the agent's next payment finds the new note by itself.

A grant that is spent or revoked is not topped up: create a new grant, which has a new credential. Topping up an expired grant adds value and leaves its expiry where it was.

Revoke#

To revoke, the owner spends the grant's current note back into their balance, less the relay fee. From that moment the agent's next proof names a note that is already spent, and the program refuses it. alba.fetch reads the grant before it proves and throws GRANT_REVOKED. If a payment and a revoke are sent at the same moment, the chain accepts exactly one of them.

Expiry#

Expiry needs no transaction. The program compares the deadline in every payment with the chain's clock, and the proof requires that deadline to be no later than the grant's expiry, so once the expiry has passed no payment from the agent can be accepted. The owner revokes an expired grant to return what is left to the balance.

Changing the terms#

Terms are fixed when the grant is created. To give an agent different terms, revoke the grant and create a new one.