The holdback dial

Settlement finality and refundability trade against each other: the moment a settlement is final, the payee can withdraw it — and a refund can no longer be executed from held funds. The holdback dial sets, per stream, how many seconds a settlement stays reachable for refunds before it becomes final.

Default: 300 seconds, or the SLA window where SLA terms exist.
Provider-policy acceptance range: 0–86,400 seconds. Zero holdback is

legal (instant finality); an out-of-range dial is refused at open — fail closed, never silently clamped.

Fee finality rides unit finality: no Dynamo fee is earned before its

units are final.

The dial is honored by cores running verified mode (hosted instances run it by default). A core that cannot honor the dial refuses the open — never a silently dropped setting.

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));

const budget = await dynamo.openBudget({ funding: "none", cap: usd("10") });

// This stream's settlements stay refund-reachable for 10 minutes.
const stream = await budget.stream({
  to: alice,
  rate: units(1_000_000n),
  cap: units(3_000_000n),
  holdbackSeconds: 600,
});

await sleep(1_100);
await stream.tick(units(500_000n));
await stream.revoke();
await budget.close();
const session = await budget.aggregate();
if (!session.reconciled) throw new Error("engine and settlement layer disagree");

Choosing a window

You are	Dial toward
A buyer of long, SLA-bound work	The SLA window — degraded units stay refundable until the window closes
A payee wanting fast working capital	Shorter holdback — funds finalize sooner; refunds after finality fall to your published terms plus the evidence export
Both sides of a new relationship	The default — a bounded, symmetric refund window neither side has to negotiate

What happens inside the window

If an SLA breakpoint is attested (signed, objective facts only) while units are inside the holdback window, the refund executes against reachable funds: buyer made 100% whole first from held funds, the Dynamo fee on refunded units reversed and netted against the payee. Refunds attested after finality are refused at the protocol level — the protocol never claws back final settlements; recourse is the payee's published terms plus the evidence bundle. Full doctrine: holdback & refunds.