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:
CORE_HOLDBACK_DEFAULT_SECONDS(300 unless the operator
sets it, 0 to 86400). A stream that accepts a payee's terms at open defaults instead to its longest term window plus 900 seconds, and a dial below that window is refused (terms_holdback).
- Accepted 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 the verified runtime, which an operator turns on with CORE_VERIFIED=1 (off by default). A core without it refuses an open that names holdbackSeconds - never a silently dropped setting. On contract version 2 the holdback is also fixed on chain per stream (Contract version 2).
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 work under objective terms | At least the longest term window - units after a reported breach stay refundable until the holdback ends |
| 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 a breach of the stream's terms is reported (a signed report of objective facts from a signer the payer accepted) while units are inside the holdback window, the refund executes against reachable funds: the value after the breach goes back to the buyer first from held funds, the payee keeps the value before it, and the Dynamo fee on refunded units is 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.