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 readIt is
50000.005 USDC
20150002.015 USDC
5000000050 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

AccountHolds
The budget accountThe balance, and the allowance still approved to the agent key. The token program changes both on every payment.
The budgetThe 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.

EventRemainingSpent this period
The budget opens50.0000.000
A payment of 2.01547.9852.015
A payment of 30.00017.98532.015
Change: limit 8047.98532.015
A payment of 47.9850.00080.000
Reset80.00080.000
A payment of 5.00075.00085.000
The roll80.0000.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.

FieldIs
startThe period’s start. Periods sit on a grid fixed to the moment the budget opened.
endThe period’s end, or the expiry if that came first.
spentEverything 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.

FigureComes from
AmountThe transfer’s amount.
Paid toThe owner of the token account the transfer went to.
ServiceThe origin of the URL the agent called, from the SDK’s report. Without one, the payment shows by its destination.
TransactionThe 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