Concepts

The ledger and the owner's view

How an owner rebuilds a grant's payments from its seed, and who can read what.

A grant's ledger is its payments as the owner reads them: every payment the agent made, in order, with what it was for. No server keeps a copy. The owner's app rebuilds the ledger from the chain each time it is opened.

What a row holds#

ColumnTypeMeaning
attimestampWhen the payment settled, in UTC.
sellerstringThe pay-to address. A payment to a wallet shows the wallet address. A payment to an Alba address shows that address, which the agent wrote into the memo.
amountu64The seller's price, in raw units of the mint.
protocolFeeu64The protocol fee charged on the payment.
relayFeeu64The relay fee charged on the payment.
memo{ method, url } | nullThe request the agent paid for: its HTTP method and URL. null when the memo does not decrypt with the owner's key.
signaturestringThe transaction, to look up on an explorer.

Under the rows the ledger gives two totals: totalPaid, the sum of the prices, and totalFees. Its state is ready when it has rows and empty when the grant has made no payment.

How the ledger is rebuilt#

Every spend of a grant publishes a spend tag, and a grant's tags follow from its seed:

text
tag = Poseidon(seed, counter)

The counter starts at 0 and goes up by one with each spend, so the grant's spends form a chain. The owner's app derives the grant's seed from the owner's key, computes the tags in order, 100 at a time, and asks the facilitator for the spends that published them. Each spend carries its amount, its fees, its recipient and its block time in public, and those fill the row.

To anyone without the seed, two tags of the same grant are two unrelated numbers. The chain that the owner follows does not exist for anyone else.

A spend with a price is a payment and makes a row. The owner's own top-up and revoke publish tags in the same chain, which is how the app follows a grant past them.

The memo#

The seller, the amount and the time are on chain. What the payment was for is not, so the agent writes it down for the owner. With each payment the SDK encrypts a memo to the owner's encryption key: the request's method and URL, and the seller's Alba address when the payment went to one, which the grant credential carries in its public half. The encryption is X25519 with a fresh key per memo, HKDF-SHA256 and XChaCha20-Poly1305. An encrypted memo is at most 240 bytes. A memo holds a GET URL of up to 158 bytes for a wallet pay-to and 93 bytes for an Alba address pay-to. A longer URL is stored cut short and ending in an ellipsis. The memo rides in the same transaction as the payment and is bound into the proof, so it cannot be replaced on the way.

Only the owner's secret key decrypts it. The agent that wrote a memo cannot read it back from the chain, and neither can anyone holding the credential.

A memo is the agent's own record of what it asked for.

Who can read what#

Amounts, sellers and times of this grantMemos
The ownerYesYes
A holder of the grant credentialYes, by following the same tags, with the grant's label and termsNo
Anyone elseIndividual pool payments, with nothing linking them to the grant or to each otherNo

Reading it#

In the app, open a grant from Grants. In code, the owner's handle reads the same ledger:

ts
const ledger = await owner.readLedger(grantId)

for (const row of ledger.rows) {
  console.log(row.at, row.seller, row.amount, row.memo?.url)
}

The owner's grants themselves are found the same way on any device. For each grant the app keeps a small encrypted record with the facilitator, holding the label and the terms, under a locator derived from the grant's seed. The record is written before the grant is funded, so every index the owner has used has one. Opening the balance walks the owner's grant indexes from zero until an index has no record, decrypts each record and rebuilds each grant from the chain.