Your first capped call
Control Mode is the full protocol with no money anywhere: the funding backend is a ledger, and every other layer (caps, rate envelopes, instant revocation, EIP-712 vouchers signed by each stream's session key, checkpoints, reconciliation) is the same machinery the money modes run. It is the mode every core starts in, and the right first stop for every integration. Status: Live.
Prerequisites
- A clone of the repository, Node 22.12 or later and pnpm 9.11.0 (the
repository's packageManager; corepack enable provides it).
DYNAMO_REPOset to the path of your clone:
export DYNAMO_REPO=/path/to/your/clone.
Boot a local core
The command stays in the foreground. A successful boot prints a line naming owner-api/1.11.0 + plugin wire on http://127.0.0.1:8500; 8500 on loopback is the default port and address.
cd "$DYNAMO_REPO"
pwd
pnpm install --frozen-lockfile
pnpm --filter @dynamo/core-host... --filter @dynamo/sdk-open... -r build
export DYNAMO_OWNER_TOKEN="dp-local-owner-$(openssl rand -hex 16)"
[ -s .dynamo-local.key ] || (umask 077 && openssl rand -hex 32 > .dynamo-local.key)
export CORE_KEY_ENCRYPTION_KEY="$(cat .dynamo-local.key)"
OWNER_API_TOKEN="$DYNAMO_OWNER_TOKEN" PLUGIN_WIRE_TOKEN="dp-local-wire-$(openssl rand -hex 16)" \
CORE_DB="$PWD/.dynamo-local/core" node deploy/image/entry.mjs
The core refuses to boot without PLUGIN_WIRE_TOKEN, without CORE_KEY_ENCRYPTION_KEY (32 bytes, hex or base64), or with an OWNER_API_TOKEN shorter than 16 characters, and names what is wrong. Reuse the same key for the same .dynamo-local/ database: a boot with another key refuses with KeyEncryptionError: key check value mismatch (wrong key-encryption key). To start over, stop the core and run rm -rf .dynamo-local .dynamo-local.key (that deletes the local budgets). More on running a core: Run your instance.
Using a hosted instance instead? Skip the boot and set DYNAMO_CORE_URL and OWNER_API_TOKEN to the URL and owner token you were given.
The flagship sample
This is the complete program: one budget, two capped streams, a mid-run revoke, and a session reconciled to the unit, all over the wire against your core. CI executes exactly these bytes against a live core.
// SPDX-License-Identifier: Apache-2.0
// Dynamo in 20 lines, over the wire: one budget, two capped streams, a
// mid-run revoke, and a to-the-unit reconciled session — against a running
// dynamo-core (Control Mode). Env: DYNAMO_CORE_URL, OWNER_API_TOKEN.
import { Dynamo, units, usd } from "@dynamo/sdk";
const coreUrl = process.env.DYNAMO_CORE_URL ?? "http://127.0.0.1:8500";
const token = process.env.OWNER_API_TOKEN ?? "";
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
const dynamo = await Dynamo.open({ coreUrl, token });
const budget = await dynamo.openBudget({ funding: "none", cap: usd("20") });
const alice = "0x00000000000000000000000000000000000000A1";
const bob = "0x00000000000000000000000000000000000000B2";
const research = await budget.stream({ to: alice, rate: units(500_000n), cap: units(6_000_000n) });
const writing = await budget.stream({ to: bob, rate: units(500_000n), cap: units(9_000_000n) });
await sleep(1_200);
await research.tick(units(300_000n)); // metered work — voucher signed by the stream's scoped key
await writing.tick(units(400_000n));
await sleep(1_100);
await budget.revoke(research); // instant; anything stamped later is unsettleable
await writing.tick(units(200_000n));
await sleep(1_100);
await writing.revoke();
const session = await budget.close().then(() => budget.aggregate());
console.log(`[${session.funding}] billed=${session.totals.billedAmount}µ settled=${session.totals.settledAmount}µ (${session.settlement.layer}) reconciled=${session.reconciled}`);
process.exit(session.reconciled ? 0 : 1);
Run it
In the repository the client's source is packages/sdk-open, and the sample imports it as @dynamo/sdk (the published package renames that specifier to @dynamoprotocol/sdk). Run it from a scratch folder whose @dynamo/sdk points at the clone, in a second terminal with the same DYNAMO_OWNER_TOKEN exported:
cd "$DYNAMO_REPO"
pwd
mkdir -p /tmp/dynamo-quickstart/node_modules/@dynamo
ln -sfn "$PWD/packages/sdk-open" /tmp/dynamo-quickstart/node_modules/@dynamo/sdk
cp packages/sdk-open/artifact/examples/quickstart.mjs /tmp/dynamo-quickstart/
DYNAMO_CORE_URL=http://127.0.0.1:8500 OWNER_API_TOKEN="$DYNAMO_OWNER_TOKEN" \
node /tmp/dynamo-quickstart/quickstart.mjs
The final line prints the session's billed total, the settled total reported by the settlement layer, and reconciled=true; against a fresh local core it reads [none] billed=900000µ settled=900000µ (control-ledger) reconciled=true. If the two totals disagree the process exits non-zero.
What just happened
Dynamo.open({ coreUrl, token })connected the thin wire client to your
core's owner API. The engine and every enforcement decision live in the core; the client re-implements nothing.
openBudgetfunded a ceiling: in Control Mode a ledger entry. Amounts are
integer micro-USD (usd("20") is 20 USD).
budget.stream(...)opened two allowances, each with a hardcapand a
per-second rate envelope. A tick that outruns the envelope fails closed and bills nothing.
- Every
tickposted a unit count to the core, which signed a monotonic
EIP-712 voucher with that stream's session key. Billing truth is the last signed voucher.
revokecut one stream mid-session. Work signed before the revocation
settles; a voucher stamped after the revocation second is unsettleable.
closesettled the last funded vouchers and released the remainder; it
refuses while any stream is still live, which is why both streams are revoked first. aggregate returned the reconciled session.
Witness the Spending Cap
Spend a stream to its cap and tick once more: the call throws HaltError with code: "cap", nothing is billed, and the owner API answers 409 halted. Gateway plugins answer the same refusal as an x402-shaped HTTP
- The rate envelope still applies on the way there: a tick that gets ahead
of rate × the seconds since the stream opened throws HaltError with code: "rate" instead, so give the stream time (or a higher rate) before spending it to the cap. A refusal's exact reason is e.code; e.reason is the older name, and a freeze or a stop shows reason as revoked. Streams shows every refusal path; each one fails closed and bills zero.
Next: put a hard cap in front of a real tool with the guard, add Dynamo to an agent framework, or go straight to the SDK guides.