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:

chain.

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.

InterfaceCurrentOlder versions still servedStatus
Owner API (the core's HTTP interface for budget owners)1.11.01.2.0 to 1.10.0, by pinLive
Merchant API (for service nodes)1.0.0noneLive (off in the the preview edge allow-list)
Webhook eventsevent schema 1.6.0; catalogue editions 1.4.0, 1.5.0 and 1.6.0every earlier schema versionLive
Evidence filesevidence/1.5.1 (also 1.5.0, 1.4.x by pin)evidence/1.0.0 to evidence/1.4.1Live
TypeScript SDK @dynamoprotocol/sdk4.2.0 (not published; the preview tarball)noneLive
Python SDK dynamoprotocol1.0.0 (not published; the preview wheel)noneLive
Escrow contractscontract v2 alone on preview money cores; sealed v1 still in-repov1Live on a local test chain or testnet; real money Release-gated
Hop intent (a delegator's signed hop)dynamo-hop-intent-v2dynamo-hop-intent-v1Live
dynamo-guard (the one-command capped proxy)4.2.0noneLive (Control Mode; Not in the preview yet on hosted preview cores)
litellm-dynamo (the LiteLLM plugin)1.7.0, on LiteLLM 1.104.0noneLive (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

never upgrades it. A new owner-api version is served next to the earlier ones from the same deployment.

evidence fields. It never changes an existing answer for a client that did not opt in.

entry in its package. A breaking change carries a written deprecation note.

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.

EventRule
A new minor versionAdditive. Earlier versions keep being served unchanged.
Deprecating an API versionA deprecation note in the package CHANGELOG and in the docs, with a stated end date.
After a newer version shipsEarlier 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 behaviourShipped 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.

GuideFrom → toWho acts
Owner APIowner-api 1.2.0 → 1.8.0anyone calling the owner API over HTTP
TypeScript SDK@dynamoprotocol/sdk 2.x → 3.xapps on the 2.x SDK
Evidence filesevidence 1.0.0 → 1.4.0anyone storing or verifying evidence
Contract v2contract v1 → v2operators of stablecoin deployments, payers and payees on them
Hop intent v2dynamo-hop-intent-v1 → -v2agents that sign their own hops
dynamo-guard and litellm-dynamoguard 3.x → 4.2.0; LiteLLM 1.91.4 → 1.104.0guard 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
PackageAt f2edf6cNow
@dynamoprotocol/agents0.2.00.3.0
@dynamo/conformance-vectors1.2.01.5.0
@dynamoprotocol/connector0.2.00.3.0
@dynamo/console1.2.01.3.0
@dynamo/evidence1.3.11.4.0
@dynamoprotocol/gateway-envoy0.1.00.3.0
@dynamo/mcp1.1.01.2.0
@dynamoprotocol/n8n-nodes-dynamonew0.1.0
@dynamoprotocol/payee-kit0.1.00.2.0
dynamoprotocol-adk0.2.00.3.0
@dynamoprotocol/ai-sdk0.1.00.2.0
@dynamoprotocol/claude-agent-sdk0.1.00.3.0
dynamoprotocol-claude-agent-sdk0.2.10.3.0
dynamoprotocol-crewai0.2.00.3.0
dynamoprotocol-langchain0.2.00.3.0
@dynamoprotocol/langgraph0.1.00.2.0
litellm-dynamo1.6.01.7.0
dynamoprotocol-llamaindexnew0.1.0
@dynamoprotocol/mastra0.1.00.2.0
dynamoprotocol-msaf0.1.00.2.0
dynamoprotocol-nemo0.1.10.2.0
@dynamoprotocol/openai-agents0.1.00.2.0
dynamoprotocol-openai-agents0.5.00.6.0
dynamoprotocol-pydantic-ai0.1.00.2.0
dynamoprotocol-strands0.1.00.2.0
@dynamo/protocol-mocks0.2.00.3.0
@dynamo/rails0.1.00.2.0
@dynamo/sdk-open (to be published as @dynamoprotocol/sdk)3.2.03.3.0
dynamoprotocol0.5.00.6.0
@dynamo/sdk (internal, never published)1.7.01.8.0
@dynamo/shared0.1.00.2.0
@dynamoprotocol/wallet-policies0.1.00.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.