Docs
Accounting
Every figure in the panel, the SDK and the API comes from two accounts on chain. Here is how amounts are written and how each figure is worked out.
Amounts
Every amount is a whole number of the mint’s base units, written as a decimal string so that it survives JSON. USDC has 6 decimals, so one USDC is 1000000.
| You read | It is |
|---|---|
5000 | 0.005 USDC |
2015000 | 2.015 USDC |
50000000 | 50 USDC |
const DECIMALS = 6n
const toUnits = (usdc) => BigInt(Math.round(usdc * 1e6)) // 0.005 -> 5000n
const toText = (units) => {
const u = BigInt(units)
return `${u / 10n ** DECIMALS}.${String(u % 10n ** DECIMALS).padStart(6, '0')}`
} // '5000' -> '0.005000'
Amounts are unsigned 64-bit: the largest is 18446744073709551615. Keep them as BigInt or strings. Times are ISO 8601 strings in UTC from the SDK and the API, and Unix seconds on chain.
The two sources
| Account | Holds |
|---|---|
| The budget account | The balance, and the allowance still approved to the agent key. The token program changes both on every payment. |
| The budget | The terms, the period’s start, and the running totals as of the last time the program touched the budget. |
A payment is a plain token transfer, so the Breaker program does not run when an agent pays. The token account alone records it: the balance and the allowance both fall by the price. The next time the program touches the budget, on any control or on the roll, it reads how far the allowance fell and adds that to its totals.
What remains
What remains of this period’s limit is the allowance on the budget account, read straight from the chain. It is exact at every moment, including between two payments in the same second.
remaining = the allowance now approved to the agent key
(0 when the budget is off, expired, or the key was replaced)
Spent this period
Spend is the total the program has already counted, plus what the allowance has fallen by since.
spent this period = counted at the last touch
+ (approved at the last touch - remaining now)
lifetime spent = lifetime counted at the last touch
+ (approved at the last touch - remaining now)
A channel’s deposit is spend from the moment the channel opens: the allowance falls by it, so it is in both figures. When the channel is distributed, the part the service was not paid comes off them again, off this period’s spend only if the deposit was counted in this period. The API’s channels.held is what open deposits still hold. On a budget on lines the key holds no allowance, so what remains is the limit less this period’s spend since the last reset.
status() returns both as spentThisPeriod and lifetimeSpent, and the API returns them on every budget. The names of the fields behind them are on the Program page.
Worked through one period
A budget with a limit of 50, funded with 250.
| Event | Remaining | Spent this period |
|---|---|---|
| The budget opens | 50.000 | 0.000 |
| A payment of 2.015 | 47.985 | 2.015 |
| A payment of 30.000 | 17.985 | 32.015 |
| Change: limit 80 | 47.985 | 32.015 |
| A payment of 47.985 | 0.000 | 80.000 |
| Reset | 80.000 | 80.000 |
| A payment of 5.000 | 75.000 | 85.000 |
| The roll | 80.000 | 0.000 |
Two things to read from it. A change of limit grants the new limit less what was spent since the period started or since the last reset, so raising 50 to 80 after 32.015 leaves 47.985. A reset grants a full limit and leaves the period’s spend counting, so a period with a reset in it closes with its true total, 85.000 here.
Periods
When a period rolls, it is closed with three figures: its start, its end and what it spent. The ledger keeps every closed period, and the API returns them at /v1/budgets/:budget/periods.
| Field | Is |
|---|---|
start | The period’s start. Periods sit on a grid fixed to the moment the budget opened. |
end | The period’s end, or the expiry if that came first. |
spent | Everything the key paid in it. |
Payments
A payment in the ledger is a token transfer out of the budget account whose authority is the budget’s agent key. Breaker reads them from the chain itself, so the ledger holds every payment the key made, through the SDK or any other way.
| Figure | Comes from |
|---|---|
| Amount | The transfer’s amount. |
| Paid to | The owner of the token account the transfer went to. |
| Service | The origin of the URL the agent called, from the SDK’s report. Without one, the payment shows by its destination. |
| Transaction | The signature of the settled transaction. |
Funded and balance
The balance is what the budget account holds now. Funded is the running total of what reached the budget, after the fee, over its life.
balance = funded - withdrawn - lifetime spent