[chcmedeiros]

Why

Ledger deprecated LedgerJS (@ledgerhq/hw-transport) in favour of the Device Management Kit, ahead of a September 2026 cutoff.

OasisApp only ever calls send and decorateAppAPIMethods on the transport, so DMK support is a type change, not a rewrite.

What

• LedgerTransport (new) describes those two methods structurally. A hw-transport Transport satisfies it, and so does a DMKTransport from @zondax/ledger-js v2 — or any object implementing the two.
• @ledgerhq/hw-transport leaves dependencies. The emitted dist/*.d.ts contains no hw-transport import at all. hw-transport-node-hid / hw-transport-webusb stay as devDependencies for tests and the type-only example.
• Transport stays exported as a @deprecated alias of LedgerTransport, so import type { Transport } keeps resolving and passing a hw-transport is unaffected.
• OasisApp and App are generic in the transport. This is what keeps the common case working — see below.
• Non-DMK transports are deprecated (new in this revision), which brings in @zondax/ledger-js as a runtime dependency and moves CI to Node 22 — see the next three sections.

Non-DMK transports are deprecated

Accepting both keeps existing wallets working, but DMKTransport is the path forward. This mirrors @zondax/ledger-js 2.1.0, which does the same on its BaseApp; OasisApp doesn't extend BaseApp, so it carries its own copy.

Constructor overloads (JSDoc @overload, emitted to dist/index.d.ts as ordinary TypeScript):

constructor(transport: T extends DMKTransport ? T : never, scrambleKey?: string);
/** @deprecated Pass a `DMKTransport` from `@zondax/ledger-js` instead. ... removed in the next major version. */
constructor(transport: T, scrambleKey?: string);

DMKTransport has private members, so only a real instance matches the first overload. A hw-transport Transport or a plain object implementing the two methods lands on the deprecated one, which editors render as a strikethrough. The first overload is a conditional rather than T & DMKTransport on purpose: inference skips the identical DMKTransport constituent of an intersection, which would leave T at its default and cost app.transport its members.

One-time runtime warning. Constructing over anything that isn't instanceof DMKTransport logs once per process:

[@oasisprotocol/ledger] Passing a transport other than DMKTransport to OasisApp is deprecated and will be rejected in the next major version. Ledger deprecated @ledgerhq/hw-transport in favour of the Device Management Kit: wrap a DMK session instead, e.g. new OasisApp(new DMKTransport(dmk, sessionId)), with DMKTransport from @zondax/ledger-js.

tsc never reports deprecations, so this was checked with the TypeScript language service (getSuggestionDiagnostics, what editors use) against the emitted dist/index.d.ts, TypeScript 5.6.2:

call	deprecated	app.transport keeps its members
new OasisApp(new DMKTransport(dmk, id))	no	setScrambleKey() compiles
new OasisApp(transportWebUSB)	yes	close() compiles
new OasisApp(transportWebUSB, scrambleKey)	yes
new OasisApp({ send, decorateAppAPIMethods })	yes

Things to know:

• This is steering, not a security check. instanceof is spoofable and the transport runs in the caller's own process; the device screen is what protects against a lying host.
• Duplicate package copies. A consumer with two copies of @zondax/ledger-js would see the warning for a genuine DMKTransport, and its type would land on the deprecated overload too.
• In-repo type example. Against the JS source (not the emitted .d.ts), TypeScript does not carry the class template into construct signatures built from JSDoc @overload, so typeOnlyTest in src/types.ts now passes its transport as any. That check is about the methods' response types, which don't depend on T; consumers read dist/index.d.ts, which infers normally (table above).

New runtime dependency: @zondax/ledger-js ^2.1.0

Naming DMKTransport, for the overload and the instanceof, needs the real class, so @zondax/ledger-js (Apache-2.0, maintained by Zondax) becomes a dependency. It has no dependencies of its own, so it adds exactly one package to the graph. Flagging it explicitly since it puts a Zondax package in this repo's runtime tree; the alternative was a structural heuristic (flag transports that have exchange/close), which can't tell a hand-rolled transport from a DMK one.

CI moves to Node 22

@zondax/ledger-js declares engines.node >=20, and yarn classic enforces engines on install. Verified locally with the CI command (yarn install --frozen-lockfile):

Node	result
18.20.8	error @zondax/ledger-js@2.1.0: The engine "node" is incompatible with this module. Expected version ">=20". Got "18.20.8"
22	installs

So ci-tests.yml and release.yml move from Node 18 (end-of-life since April 2025) to 22. The same applies to consumers: a project still on Node 18 installing this package with yarn classic will hit that error (npm and pnpm only warn). That lands in the same major as the type change below.

This is a breaking change (1.0.0 → 2.0.0)

src/types.ts has re-exported hw-transport's Transport since long before this work, so it is part of the published API. Removing the dependency means that type cannot be re-exported, and the name necessarily narrows. Rather than let that happen silently, it is scoped and asserted.

Still compiles — verified against this branch:

case	why it survives
const app = new OasisApp(await TransportWebUSB.create()); await app.transport.close()	T is inferred as TransportWebUSB, so the class's own members are intact
const t: Transport = realHwTransport	a hw-transport Transport still satisfies the alias
a DMK transport, reading a member only it has	same inference, from the other side
a bare App annotation calling send	send is on the structural type

No longer compiles — each asserted with @ts-expect-error in a throwaway probe, so neither can regress unnoticed:

case	fix
reaching through the exported Transport type for close() / exchange() / on()	import Transport from @ledgerhq/hw-transport directly
the same through a bare OasisApp / App annotation	annotate OasisApp<TransportWebUSB>, or let inference do it

The generic is doing the load-bearing work here: without it, app.transport would collapse to the structural type and every consumer reaching through it would break, not just those who annotate explicitly.

Also breaking, see above: yarn-classic installs on Node < 20.

Verification

check	result
yarn build (Babel + tsc types)	pass, no hw-transport import in emitted .d.ts
yarn test:unit	7/7 pass (3 existing + 4 deprecation)
eslint src/ tests/deprecation.spec.js	clean
yarn install --frozen-lockfile on Node 18 / 22	fails / passes (table above)
deprecation diagnostics on dist/index.d.ts (language service)	table above
compatibility probe (4 surviving + 2 breaking cases)	from the previous revision; the overloads don't change the bare-annotation default

yarn.lock loses hw-transport as a direct dependency (it remains for devDependencies) and gains @zondax/ledger-js.

Integration tests were not run here (they need a physical device).

Note for maintainers

I have not bumped version in package.json — releases here are driven by pushing a v* tag, so the bump is yours to make. It needs to be a major.

[matevz]

We're using @ledgerhq/hw-transport-webusb heavily in https://github.com/oasisprotocol/wallet, so merging this and releasing a new 2.0.0 breaking version of @oasisprotocol/ledger will also require some work on that front. I would appreciate some migration hints (see below).