Changelog, versioning, deprecation and migration
This page says which version of each Dynamo interface and package this release contains, how versions are numbered and kept compatible, what the deprecation policy is, and how to move from an older version to the current one.
Current release: v2.2.0 the preview (gated commit ab4695a5). Anyone can request access; test mode only. See also Preview.
Nothing is published yet. Every package on these pages is prepared in the repository but is not on npm or PyPI. The SDK page explains how to build and use a package from a clone. The repository's publish pipeline still stages older versions (for example the TypeScript SDK as 2.1.0 and the guard as 3.2.0); it has to be brought up to the versions on these pages before anything is published. Nothing on these pages is a promise about real money.
Features carry one of three labels:
- Live: usable today in Control Mode (no money anywhere), with test credit cards, or on a test
chain.
- Preview: built, behind a switch that is off unless the operator turns it on.
- Release-gated: needs real money, live credit card keys or operator-run ramps. Not offered in
this release.
The interfaces and their current versions
These are the versioned interfaces you write code against. Each has its own version number, separate from the version of the package that ships it.
| Interface | Current | Older versions still served | Status |
|---|---|---|---|
| Owner API (the core's HTTP interface for budget owners) | 1.11.0 | 1.2.0 to 1.10.0, by pin | Live |
| Merchant API (for service nodes) | 1.0.0 | none | Live (off in the the preview edge allow-list) |
| Webhook events | event schema 1.6.0; catalogue editions 1.4.0, 1.5.0 and 1.6.0 | every earlier schema version | Live |
| Evidence files | evidence/1.5.1 (also 1.5.0, 1.4.x by pin) | evidence/1.0.0 to evidence/1.4.1 | Live |
TypeScript SDK @dynamoprotocol/sdk | 4.2.0 (not published; the preview tarball) | none | Live |
Python SDK dynamoprotocol | 1.0.0 (not published; the preview wheel) | none | Live |
| Escrow contracts | contract v2 alone on preview money cores; sealed v1 still in-repo | v1 | Live on a local test chain or testnet; real money Release-gated |
| Hop intent (a delegator's signed hop) | dynamo-hop-intent-v2 | dynamo-hop-intent-v1 | Live |
| dynamo-guard (the one-command capped proxy) | 4.2.0 | none | Live (Control Mode; Not in the preview yet on hosted preview cores) |
| litellm-dynamo (the LiteLLM plugin) | 1.7.0, on LiteLLM 1.104.0 | none | Live (Control Mode; Not in the preview yet on hosted preview cores) |
The owner API answers its version at /owner/v1/version. The TypeScript SDK 4.3.3 knows owner-api versions up to 1.11.0 and checks the core's version before it uses a method that needs a newer one.
Every package, with each version its CHANGELOG records, is listed on Package versions.
How versions change
- Side by side, never in place. A new contract version is deployed next to the old one and
never upgrades it. A new owner-api version is served next to the earlier ones from the same deployment.
- Additive within a major version. A minor version adds routes, response keys, event types or
evidence fields. It never changes an existing answer for a client that did not opt in.
- Written before it ships. A change to a public schema bumps its version and gets a CHANGELOG
entry in its package. A breaking change carries a written deprecation note.
- Unknown versions are refused by name on the multi-tenant tier, never guessed: an unknown
Dynamo-Version is refused with 400 version_unknown. A single-tenant instance does not refuse it; it answers as if no version was named.
Compatibility guarantees
Tolerant clients, strict servers. The TypeScript SDK from 3.0.0 on, the Python SDK and the plugins check the response keys they know, by type and shape, and ignore the keys they do not know, so a server that adds a field does not break them. (The 2.x SDK, which the publish pipeline still stages, refuses unknown keys.) A refusal code the client does not know becomes a generic typed error that keeps the raw code. Servers are the other way round: a request with a field the server does not know is refused.
Opt-in for new behaviour. Where a newer owner-api version answers differently, only a client that opts in sees the difference, either by pinning the version with the Dynamo-Version header or by asking for detailed errors with Dynamo-Error-Detail: 1. The details are in the owner API migration guide.
Recorded snapshots. The repository keeps recorded answers of earlier owner-api versions: 1.2.0, 1.3.0, 1.5.0, 1.6.0 (plus the webhook endpoints) and 1.7.0 (single-tenant and multi-tenant). Each was probed at the commit that served that version. The wire compatibility suite replays every recorded request against the current server and checks that each answer keeps its shape:
cd "$DYNAMO_REPO"
pwd
make test-wire-compat
There is no recorded snapshot for 1.4.0 or 1.8.0. The routes 1.4.0 added are replayed only as the 1.5.0 snapshot recorded them.
Support window and deprecation
The versioning policy sets the rules but not the time periods. The notice period before a deprecation, the minimum time an older version stays servable, and the notice before a major version are not set yet. Until they are, the rules below are the whole policy.
| Event | Rule |
|---|---|
| A new minor version | Additive. Earlier versions keep being served unchanged. |
| Deprecating an API version | A deprecation note in the package CHANGELOG and in the docs, with a stated end date. |
| After a newer version ships | Earlier versions stay servable by pin. |
| A major version (for example owner-api 2.0) | May remove deprecated surfaces, each named in a deprecation note first. |
| A security fix that must change behaviour | Shipped with a CHANGELOG entry naming the change. |
No version has been deprecated in this release. Every owner-api version from 1.2.0 to 1.11.0 is served.
Contract versions have their own lifecycle. A deployment of a contract version is either active (it opens new budgets) or deprecated (it opens no new budget but keeps serving the budgets it has: settle, release, refund, revoke, withdraw, finality and evidence). A budget stays on the version it was opened on for its whole life. A deprecated version is removed only when no budget on it still holds escrowed, held or claimable value, so proven work stays settleable. On a stablecoin deployment the operator sets this with CORE_ESCROW_V1_STATUS (active or deprecated) and CORE_ESCROW_DEFAULT_VERSION (v1 or v2). A deployment that deprecates its own default version refuses to start.
Migration guides
Each guide says what changed, who has to act, the steps, and what stays compatible.
| Guide | From → to | Who acts |
|---|---|---|
| Owner API | owner-api 1.2.0 → 1.8.0 | anyone calling the owner API over HTTP |
| TypeScript SDK | @dynamoprotocol/sdk 2.x → 3.x | apps on the 2.x SDK |
| Evidence files | evidence 1.0.0 → 1.4.0 | anyone storing or verifying evidence |
| Contract v2 | contract v1 → v2 | operators of stablecoin deployments, payers and payees on them |
| Hop intent v2 | dynamo-hop-intent-v1 → -v2 | agents that sign their own hops |
| dynamo-guard and litellm-dynamo | guard 3.x → 4.2.0; LiteLLM 1.91.4 → 1.104.0 | guard users and LiteLLM operators |
What moved in this release
The repository's version table lists each package manifest whose version differs between a base commit and the working tree. It was run at commit a7b9da5 (the dn7-docs branch, with only documentation changed in the working tree).
Against the v2.0.0 tag (0e047a0) no version moved:
cd "$DYNAMO_REPO"
pwd
node scripts/version-table.mjs 0e047a0 --all
| package | 0e047a0 | now | CHANGELOG |
|---|---|---|---|
| (no version moved) | | | |
Against the end of the previous stage (DN6, commit f2edf6c) these versions moved:
cd "$DYNAMO_REPO"
pwd
node scripts/version-table.mjs f2edf6c
| Package | At f2edf6c | Now |
|---|---|---|
@dynamoprotocol/agents | 0.2.0 | 0.3.0 |
@dynamo/conformance-vectors | 1.2.0 | 1.5.0 |
@dynamoprotocol/connector | 0.2.0 | 0.3.0 |
@dynamo/console | 1.2.0 | 1.3.0 |
@dynamo/evidence | 1.3.1 | 1.4.0 |
@dynamoprotocol/gateway-envoy | 0.1.0 | 0.3.0 |
@dynamo/mcp | 1.1.0 | 1.2.0 |
@dynamoprotocol/n8n-nodes-dynamo | new | 0.1.0 |
@dynamoprotocol/payee-kit | 0.1.0 | 0.2.0 |
dynamoprotocol-adk | 0.2.0 | 0.3.0 |
@dynamoprotocol/ai-sdk | 0.1.0 | 0.2.0 |
@dynamoprotocol/claude-agent-sdk | 0.1.0 | 0.3.0 |
dynamoprotocol-claude-agent-sdk | 0.2.1 | 0.3.0 |
dynamoprotocol-crewai | 0.2.0 | 0.3.0 |
dynamoprotocol-langchain | 0.2.0 | 0.3.0 |
@dynamoprotocol/langgraph | 0.1.0 | 0.2.0 |
litellm-dynamo | 1.6.0 | 1.7.0 |
dynamoprotocol-llamaindex | new | 0.1.0 |
@dynamoprotocol/mastra | 0.1.0 | 0.2.0 |
dynamoprotocol-msaf | 0.1.0 | 0.2.0 |
dynamoprotocol-nemo | 0.1.1 | 0.2.0 |
@dynamoprotocol/openai-agents | 0.1.0 | 0.2.0 |
dynamoprotocol-openai-agents | 0.5.0 | 0.6.0 |
dynamoprotocol-pydantic-ai | 0.1.0 | 0.2.0 |
dynamoprotocol-strands | 0.1.0 | 0.2.0 |
@dynamo/protocol-mocks | 0.2.0 | 0.3.0 |
@dynamo/rails | 0.1.0 | 0.2.0 |
@dynamo/sdk-open (to be published as @dynamoprotocol/sdk) | 3.2.0 | 3.3.0 |
dynamoprotocol | 0.5.0 | 0.6.0 |
@dynamo/sdk (internal, never published) | 1.7.0 | 1.8.0 |
@dynamo/shared | 0.1.0 | 0.2.0 |
@dynamoprotocol/wallet-policies | 0.1.0 | 0.2.0 |
For every row the package's CHANGELOG changed too, and its newest heading names the new version. The table reads only package.json and pyproject.toml files. It does not show the owner API (1.7.0 → 1.8.0), the event schema (1.5.0 → 1.6.0), the guard (4.1.0 → 4.2.0) or the gateway plugins, because their versions are kept elsewhere; see Package versions.