An owner changes a grant in two ways after creating it: adding value, and taking the remainder back. Both start from the grant's page, where its ledger is.
Open the grant#
In the app, go to Grants and choose the grant. The page shows what remains of the starting amount, what has been spent, the terms, the state and the ledger.
In code:
const grants = await owner.listGrants()
const grant = grants.find((g) => g.label === 'research-agent')Each grant has remaining, spent and feesPaid in raw units, its terms, and a state of active, expired, spent or revoked. grant.id identifies it in every call below.
Read the ledger#
The Ledger on the grant's page lists each payment: the time in UTC, the seller, the memo with the method and URL the agent asked for, the amount, and a link to the transaction.
const ledger = await owner.readLedger(grant.id)
for (const row of ledger.rows) {
console.log(row.at, row.seller, row.amount, row.memo?.method, row.memo?.url)
}
ledger.totalPaid // raw units
ledger.totalFeesThe ledger and the owner's view explains how the rows are rebuilt.
Top up#
On the grant's page, enter an amount under Top up and press the button. The browser proves the spend and the facilitator relays it. The agent keeps the same credential, and its next payment draws on the larger amount.
await owner.topUp({ grantId: grant.id, amount: '2000000' })A top-up moves the amount from your balance into the grant and pays one relay fee from your balance. It draws on a single note, which must cover the amount and the fee. If no one note is large enough, topUp throws INSUFFICIENT_BALANCE. To join two notes into one, send any amount to your own Alba address: the change returns as a single note.
await owner.transfer({ mint, amount: '1', recipient: owner.address })A grant in the state spent or revoked is not topped up. Create a new grant and give the agent the new credential.
Revoke#
Press Revoke on the grant's page. What is left in the grant returns to your balance, less one relay fee, and the agent stops being able to pay.
await owner.revoke(grant.id)Revoking spends the grant's current note with your key. From then on:
- the agent's
alba.fetchthrowsGRANT_REVOKEDbefore proving anything - a payment already proved and on its way to the facilitator is refused with
spent_tag - a payment that settled before the revoke stands, and is in the ledger
A revoke and a payment sent in the same moment cannot both succeed. Whichever the chain accepts first is the one that happened.
An expired grant#
After its expiry a grant's state is expired and the agent can no longer pay. What is left stays in the grant until you press Revoke, which returns it to your balance the same way.
After a grant ends#
A revoked or spent grant stays in your list with its ledger, so the record of what the agent paid for remains readable for as long as you hold the wallet.