Migrating the TypeScript SDK 2.x → 3.x
@dynamoprotocol/sdk 3.0.0 is a major version; 3.1.0-3.3.0 are additive on top of it, then 4.0.0-4.2.0 continue additively for the v2.2.0 preview. The current version is 4.2.0. It is not published: build it from a clone as the SDK page shows. In the repository it is the workspace package @dynamo/sdk-open.
Back to Changelog, versioning, deprecation and migration.
What changed in 3.0.0 (Live)
Every 2.x method keeps its name, arguments and result type, and keeps working against a core serving owner-api 1.2.0 or later. What changes is how answers and refusals are read.
- Tolerant parsing. 2.x refused any response key it did not know with a
WireError, so a
newer core that added a field broke it. 3.x checks every key it knows by type and shape (a wrong type or a missing required key is still a WireError) and drops keys it does not know. They never appear in typed results.
- Typed errors. Every request sends
Dynamo-Error-Detail: 1. Every error the client raises is
a DynamoError (a subclass of SdkError) with type, code, message, param, docUrl and status, plus headroom, fix and retryAfterMs when the core sends them. The 2.x classes keep their fields: HaltError.reason is still a 2.x reason, and the precise reason is code (for example reason is "revoked" and code is "frozen").
- Unknown codes keep their raw code. A refusal this client does not know becomes a plain
DynamoError carrying the raw code. 2.x turned an unknown enforcement reason into a HaltError with reason "cap"; 3.x never does.
- New subclasses with their own
name.MandateErrorextendsStateError;
ApprovalRequiredError and CheckpointPendingError extend HaltError. instanceof checks written for 2.x still match; checks on err.name see the new names.
- Checkpoint wait. A
checkpoint_pendingrefusal is waited out and the same request retried,
for up to 30 seconds in total; then CheckpointPendingError is thrown. No other refusal is ever retried. Dynamo.open({ checkpointWaitMs: 0 }) restores the 2.x behaviour of throwing at once.
stream.tick()without arequestRefnow creates one in the client (tick-<nonce>), so a
waited-out retry repeats the same request and bills once.
3.0.0 also added mandates and categories, reservations, the budget tree, the authority chain, records and head, freeze, thaw, amend and stop, approvals and the evidence export, each available when the core is new enough.
What 3.1.0 to 3.3.0 added (Live)
All additive; every earlier method keeps its name, arguments and result type.
| Version | Newest owner-api it knows | Added |
|---|---|---|
| 3.1.0 | 1.6.0 | The main switch, economic accounts, minPayeeAssurance, and handles on an existing budget or stream by id (dynamo.budget(id), dynamo.stream(id)). |
| 3.2.0 | 1.7.0 | Own hops (hopIntent, signHopIntent, payeeOffer, signPayeeOffer), requestRef on stream opens, the payment authority and consume rows, and the terms catalogue with breach reports. |
| 3.3.0 | 1.8.0 | Hop intent v2 (hopIntentV2, childMandateHash, resolveChildMandate) and the optional minAgentVerification mandate field. |
| 4.0.0 | 1.10.0 | Owner-api 1.9.0-1.10.0 surfaces the client knows (MAX_OWNER_API_VERSION 1.10.0). |
| 4.1.0 | 1.11.0 | MAX_OWNER_API_VERSION 1.11.0; further additive client methods for the preview. |
| 4.2.0 | 1.11.0 | x402 paying and getting paid for the v2.2.0 preview (see x402 and the v2.2.0 release notes). |
Who has to act
- Your 2.x code catches
WireErrorto detect a newer core: replace that with
dynamo.serverVersion().
- Your code checks
err.namefor mandate, approval or checkpoint refusals: update the names,
or switch to instanceof.
- Your code relied on an unknown refusal arriving as
HaltErrorwith reason"cap": handle a
plain DynamoError and read its code.
- Your code expects a
checkpoint_pendingrefusal to be thrown at once: pass
checkpointWaitMs: 0.
- Everyone else: rebuild against 4.2.0; no code change is needed for the 3.x → 4.x additive
path if you already left 2.x.
Steps
- Build 4.2.0 from a clone (see the SDK page) and point your app at it.
- Search for
WireError,err.nameandHaltErrorin your code and apply the changes above. - Branch on
err.codefor precise reasons. KeepHaltError.reasononly where you need the 2.x
reason.
- Run your tests against a core serving owner-api 1.11.0, and against the oldest core you support.
Compatibility guarantees
- Tolerant client, strict server. The SDK ignores response keys it does not know, so a core
that adds a field never breaks it. The core refuses request fields it does not know.
- Version handshake. The SDK asks
/owner/v1/versiononce, and only when the first method that
needs a newer owner-api runs. A core that is too old raises UnsupportedByServer naming the version needed, and nothing is sent.
OWNER_API_VERSIONkeeps its 2.x meaning ("1.1.0", the oldest contract the 2.x methods
speak). MAX_OWNER_API_VERSION ("1.11.0" in 4.2.0) is the newest the client knows.
- No
Dynamo-Versionheader. The SDK does not pin a version. On the multi-tenant tier the
tenant's default version applies to its requests. On a single-tenant instance, a field accepted only from a request pinned at a later version, such as minAgentVerification at 1.8.0, is refused unless that pin is in effect for the request path.
- Evidence export.
budget.exportEvidence()asks for the default evidence schema
(evidence/1.1.0). The core refuses the default for a top-up budget, a human payment's consent root and a contract v2 budget. For a later schema, call the owner API with ?schema= (see evidence).