Budgets
A Budget is one funded ceiling. In Control Mode that is a ledger record; in escrow mode an on-chain deposit; in card mode a card authorization-backed budget. Everything downstream - streams, vouchers, settlement - is identical across the three, and your instance enforces all of it server-side; the client only speaks the wire.
Lifecycle
import { Dynamo, usd, units } from "@dynamoprotocol/sdk";
const dynamo = await Dynamo.open({
coreUrl: process.env.DYNAMO_CORE_URL!,
token: process.env.OWNER_API_TOKEN!,
});
const alice = "0x00000000000000000000000000000000000000A1";
const sleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));
// 1. Fund a ceiling. The cap is the most this session can ever settle.
const budget = await dynamo.openBudget({ funding: "none", cap: usd("10") });
// 2. Fan out. Each stream gets its own hard cap and per-second rate envelope.
const worker = await budget.stream({
to: alice,
rate: units(1_000_000n),
cap: units(3_000_000n),
});
// 3. Meter. Every tick emits a voucher signed by the stream's scoped key
// (held by the core); allowance accrues per second.
await sleep(1_100);
const receipt = await worker.tick(units(800_000n));
if (receipt.voucherSeq < 1) throw new Error("expected a signed voucher");
// 4. Close. Live streams must be revoked first - closing never silently
// kills allowances (fail closed).
await worker.revoke();
const { releasedAmount } = await budget.close();
// 5. Reconcile. The session's billed total must equal settlement-layer truth.
const session = await budget.aggregate();
if (!session.reconciled) throw new Error("engine and settlement layer disagree");
if ((releasedAmount as bigint) + session.totals.settledAmount > 10_000_000n) {
throw new Error("released + settled exceeded the funded ceiling");
}
The rules a budget enforces
- The cap is structural. The sum of child settlements can never exceed
the funded ceiling - that inequality (the Σ proof) is checked by the engine, re-derivable from the session view, and carried into evidence bundles.
- Closing is explicit and safe.
close()refuses while streams are
live; after settlement of the last funded vouchers, the remainder is released to the owner (escrow: on-chain; card: authorization release).
aggregate()is the receipt. One reconciled object: per-stream
settled totals, the settlement layer's own record, and reconciled: true only when the two agree to the unit.
Meta, not state
openBudget({ meta }) carries client-side annotation only - it never crosses the wire into settlement, vouchers, or fees. Anything that moves money lives in the typed fields.