Docs
Keeper and indexer
Two services run beside the program. The keeper rolls every budget when its period ends. The indexer reads the chain and keeps the ledger the panel and the API serve. Neither holds a key to anyone’s money.
The keeper
A period turns over when a roll transaction lands. The keeper’s whole job is to send that transaction for every budget at the right moment.
When it rolls
deadline = the earlier of
period start + period length
the expiry, if the budget has one
The keeper compares the deadline with the chain’s own clock, the time Solana’s validators agree on, and sends the roll a quarter of a second after it. A budget opened at 14:20 with a day period rolls at 14:20 every day.
| The keeper wakes | To |
|---|---|
| At the next deadline | Roll the budget whose period just ended. |
| When any budget changes | Work out the next deadline again. A changed period or expiry moves it. |
| A second after an unconfirmed send | Send the same roll again. |
Each roll happens once
Every roll carries a key made of the budget, the period’s start and the deadline. The keeper records it before sending, so a roll that was sent is never sent as a second, different transaction. The program checks as well: roll on a period that has not ended is refused with PeriodNotEnded.
What a roll does
| Case | The roll |
|---|---|
| The period ended | Closes it with its spend, starts the next, grants the full limit if the budget is on. |
| Several periods passed | Moves straight to the current period. The grid stays fixed to the moment the budget opened. |
| The budget is off | Closes the period and grants nothing. The limit is there when you switch on. |
| The budget is past its expiry | Closes the period at the expiry and revokes the key. |
The keeper pays the network fee of every roll. A roll costs the owner and the agent nothing.
Rolling a budget yourself
roll takes no signer. Any wallet may send it for any budget once the period has ended, and pays only the network fee. It can do one thing: turn the period over on the terms the owner set.
| Account | Is |
|---|---|
panel | The budget’s panel. |
budget | The budget. Writable. |
mint | The budget’s mint. |
budget_token_account | The budget account. Writable. |
agent_key | The budget’s current agent key. |
token_program | The token program of the mint. |
The instruction, its checks and its event are on the Program page.
The indexer
The indexer follows the chain and writes what it reads into the ledger. Everything the panel shows and the API returns comes from it, and everything it holds can be read again from the chain.
| It reads | And records |
|---|---|
PanelOpened | A panel and its owner. |
BudgetChanged | The budget as it stands after each control: its terms, its state, its totals, its balance. |
BudgetChanged with a closed period | One period: its start, its end and its spend. |
| A token transfer out of a budget account, signed by its agent key | One payment: the amount, who was paid, the transaction. |
ConfigChanged | The fee rate. |
Payments carry no Breaker event, because the Breaker program does not run when an agent pays. The indexer finds them as what they are: transfers out of an account it knows, by a key it knows.
The state it shows
| State | When |
|---|---|
| Closed | The budget was closed. |
| Expired | The expiry has passed. |
| Off | The owner switched it off. |
| Tripped | Nothing remains of this period’s limit, or the agent reported a price above what remains. |
| Live | Otherwise. |
They are checked in that order, so a budget that is both off and past its expiry shows Expired.
Service names
The chain says which account a payment went to. The SDK says which URL the agent called, in a report signed by the agent key. The indexer joins the two by the transaction’s signature, and the ledger shows the service’s origin beside the payment.
From the chain to the panel
a transaction lands
-> the indexer reads it and writes the ledger
-> the API tells every open panel (the stream at /v1/panels/:panel/events)
-> the keeper works out the next deadline
A transaction the panel submitted reads submitted until the indexer has written it, so what the panel shows as done is what the ledger holds.
Health
Each service answers GET /health with its role and whether it is ready. The API’s is at /health on the API’s own address, and /v1/config reports the same status with the network and the program’s address.