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.

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.

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").

DynamoError carrying the raw code. 2.x turned an unknown enforcement reason into a HaltError with reason "cap"; 3.x never does.

ApprovalRequiredError and CheckpointPendingError extend HaltError. instanceof checks written for 2.x still match; checks on err.name see the new names.

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.

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.

VersionNewest owner-api it knowsAdded
3.1.01.6.0The main switch, economic accounts, minPayeeAssurance, and handles on an existing budget or stream by id (dynamo.budget(id), dynamo.stream(id)).
3.2.01.7.0Own hops (hopIntent, signHopIntent, payeeOffer, signPayeeOffer), requestRef on stream opens, the payment authority and consume rows, and the terms catalogue with breach reports.
3.3.01.8.0Hop intent v2 (hopIntentV2, childMandateHash, resolveChildMandate) and the optional minAgentVerification mandate field.
4.0.01.10.0Owner-api 1.9.0-1.10.0 surfaces the client knows (MAX_OWNER_API_VERSION 1.10.0).
4.1.01.11.0MAX_OWNER_API_VERSION 1.11.0; further additive client methods for the preview.
4.2.01.11.0x402 paying and getting paid for the v2.2.0 preview (see x402 and the v2.2.0 release notes).

Who has to act

dynamo.serverVersion().

or switch to instanceof.

plain DynamoError and read its code.

checkpointWaitMs: 0.

path if you already left 2.x.

Steps

  1. Build 4.2.0 from a clone (see the SDK page) and point your app at it.
  2. Search for WireError, err.name and HaltError in your code and apply the changes above.
  3. Branch on err.code for precise reasons. Keep HaltError.reason only where you need the 2.x

reason.

  1. Run your tests against a core serving owner-api 1.11.0, and against the oldest core you support.

Compatibility guarantees

that adds a field never breaks it. The core refuses request fields it does not know.

needs a newer owner-api runs. A core that is too old raises UnsupportedByServer naming the version needed, and nothing is sent.

speak). MAX_OWNER_API_VERSION ("1.11.0" in 4.2.0) is the newest the client knows.

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/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).