Funding modes
One object graph, three settlement layers. A budget is always the same thing
- a funded ceiling fanned out into capped, revocable streams - but the
ceiling can be funded three ways:
| Mode | The ceiling is | Settlement is | Money at risk | Status |
|---|---|---|---|---|
Control (none) | A ledger record | Ledger entries | None - no money exists anywhere | Live |
Escrow (usdc) | An on-chain deposit in the vault contract (version 1, or version 2) | On-chain, per-voucher, against escrow | The deposited amount, held by contract rules | Live on local and test chains; real-money chains Release-gated |
Credit card (card) | ONE manual-capture authorization (card authorization-backed budgets) | PSP captures + split transfers per voucher totals | The authorized amount, held by the card network | Live in Stripe TEST mode; live keys Release-gated |
A core runs only the modes its operator allows. The hosted image allows none of the money modes unless they are listed in CORE_ALLOWED_MODES.
The mode is a tag on openBudget (or one environment variable in the quickstarts); streams, vouchers, session keys, credentials and revocation run through the same engine code in every mode; only the funding backend underneath differs.
What is invariant across modes
- Caps are structural. Σ child settlements ≤ funded ceiling, enforced by
the engine and (in escrow mode) by the contract itself.
- Billing truth is the last SIGNED voucher. Never in-memory state, never
a provider's claim. Crash and recover: the ledger re-derives from signed artifacts.
- Failed work costs nothing. Refused ticks, failed deliveries, SLA-failed
units - never billed, on any rail.
- Reconciliation ends every session. The engine's totals against the
settlement layer's own records, to the unit - a mismatch is a loud failure, never a rounding note.
- Money is integers. The engine accounts in micro-USD in
bigint;
contract version 2 scales each amount to the asset's base units, rounding obligations up. Floating point never touches an amount, a rate, or a fee.
Choosing a mode
Start with Control - it is the full protocol minus money and it costs nothing to be wrong. Move to escrow when your counterparties settle on-chain; move to the credit card rail when buyers fund with cards. Try both money rails in test environments (testnet, card sandbox). Real money is release-gated: live credit card keys refuse to boot, so the credit card rail runs in Stripe TEST mode only. A stablecoin mode is not refused in code: on a real-money chain the hosted image starts it only when the operator lists it in CORE_ALLOWED_MODES and the vault's owner and fee collector are Safe multisigs (threshold 2 or more).