@swapkit/wallet-hardware 5.0.1 → 6.0.0

package/src/ledger/helpers/executeDeviceAction.ts

@@ -0,0 +1,201 @@
+import type {
+  DeviceActionIntermediateValue,
+  DeviceActionState,
+  DeviceActionStatus,
+  ExecuteDeviceActionReturnType,
+  UserInteractionRequired,
+} from "@ledgerhq/device-management-kit";
+import { SwapKitError } from "@swapkit/helpers";
+import { match } from "ts-pattern";
+
+const DEVICE_ACTION_STATUS = {
+  Completed: "completed" as DeviceActionStatus.Completed,
+  Error: "error" as DeviceActionStatus.Error,
+  Stopped: "stopped" as DeviceActionStatus.Stopped,
+} as const;
+
+export const LEDGER_USER_INTERACTION_REQUIRED = {
+  None: "none" as UserInteractionRequired.None,
+  SignTransaction: "sign-transaction" as UserInteractionRequired.SignTransaction,
+  VerifyAddress: "verify-address" as UserInteractionRequired.VerifyAddress,
+} as const;
+
+export type LedgerDeviceActionState = DeviceActionState<unknown, unknown, DeviceActionIntermediateValue>;
+export type LedgerDeviceActionStateHandler = (state: LedgerDeviceActionState) => void;
+
+const USER_REFUSED_STATUS_WORDS = new Set(["6985", "5501"]);
+/**
+ * Zondax-built apps (Cosmos, THORChain) reject a request on the device with COMMAND_NOT_ALLOWED. The Zcash app uses
+ * the same word to refuse a request, so only the clients for the Zondax apps treat it as a user rejection.
+ */
+export const ZONDAX_USER_REFUSED_STATUS_WORDS: readonly string[] = ["6986"];
+const LOCKED_STATUS_WORDS = new Set(["5515"]);
+const WRONG_APP_STATUS_WORDS = new Set(["6511", "6807", "6d00", "6e00"]);
+const DISCONNECTED_ERROR_TAGS = new Set([
+  "DeviceDisconnectedBeforeSendingApdu",
+  "DeviceDisconnectedWhileSendingError",
+  "DeviceNotRecognizedError",
+  "DeviceSessionNotFound",
+  "NoAccessibleDeviceError",
+  "ReconnectionFailedError",
+]);
+// LedgerJS transports (hw-transport-webhid, -webusb) reject an exchange cut off by an unplug with these errors. The
+// @ledgerhq packages advise matching on `name`, which also holds across duplicate copies of @ledgerhq/errors.
+const DISCONNECTED_ERROR_NAMES = new Set(["DisconnectedDevice", "DisconnectedDeviceDuringOperation"]);
+// hw-app-cosmos turns the app's final 0x6986 on a signature into this @ledgerhq/errors class, which carries no word.
+const USER_REFUSED_ERROR_NAMES = new Set(["UserRefusedOnDevice"]);
+// DMK nests causes in `originalError` and the LedgerJS bridge wraps once more, so real chains are two or three
+// levels deep; the bound stops a malformed or cyclic chain.
+const MAX_NESTED_ERROR_DEPTH = 4;
+const STATUS_WORD_PATTERN = /^(?:0x)?([0-9a-f]{4})$/i;
+
+type DeviceErrorLike = {
+  _tag?: unknown;
+  errorCode?: unknown;
+  message?: unknown;
+  name?: unknown;
+  originalError?: unknown;
+  statusCode?: unknown;
+};
+
+export interface LedgerDeviceErrorOptions {
+  /** App-specific status words that also mean the user rejected the request on the device. */
+  userRefusedStatusWords?: readonly string[];
+}
+
+function errorChainOf(error: unknown) {
+  const errors: DeviceErrorLike[] = [];
+  let current = error;
+
+  while (errors.length < MAX_NESTED_ERROR_DEPTH && typeof current === "object" && current !== null) {
+    const deviceError: DeviceErrorLike = current;
+    errors.push(deviceError);
+    current = deviceError.originalError;
+  }
+
+  return errors;
+}
+
+// DMK command errors carry the word as an `errorCode` string (the Cosmos signer kit keys its own table "0x6986");
+// hw-transport status errors carry it as a numeric `statusCode`.
+function statusWordOf({ errorCode, statusCode }: DeviceErrorLike) {
+  const fromErrorCode = typeof errorCode === "string" ? STATUS_WORD_PATTERN.exec(errorCode)?.[1] : undefined;
+  if (fromErrorCode) return fromErrorCode.toLowerCase();
+  return typeof statusCode === "number" ? statusCode.toString(16).padStart(4, "0") : undefined;
+}
+
+/**
+ * DMK rejects with plain tagged objects (and the LedgerJS bridge nests hw-app status errors inside
+ * them), so callers could not tell a user rejection from a wrong app or a disconnected device.
+ */
+export function toLedgerDeviceError(error: unknown, { userRefusedStatusWords = [] }: LedgerDeviceErrorOptions = {}) {
+  const errorChain = errorChainOf(error);
+  // A SwapKitError thrown inside a bridged LedgerJS operation (input validation) already says what failed.
+  const swapKitError = errorChain.find((nested): nested is SwapKitError => nested instanceof SwapKitError);
+  if (swapKitError) return swapKitError;
+
+  const errorTags = errorChain.flatMap(({ _tag }) => (typeof _tag === "string" ? [_tag] : []));
+  const errorNames = errorChain.flatMap(({ name }) => (typeof name === "string" ? [name] : []));
+  const statusWord = errorChain.map(statusWordOf).find((word) => word !== undefined);
+  // The innermost cause says what failed; DMK and the bridge wrap it in generic "device exchange" messages.
+  const message = errorChain
+    .map((nested) => nested.message)
+    .filter((value): value is string => typeof value === "string" && value.length > 0)
+    .at(-1);
+  const refusedStatusWords = new Set([...USER_REFUSED_STATUS_WORDS, ...userRefusedStatusWords]);
+
+  const errorKey = match({ errorNames, errorTags, statusWord })
+    .when(
+      ({ errorNames, errorTags, statusWord }) =>
+        errorTags.includes("RefusedByUserDAError") ||
+        errorNames.some((name) => USER_REFUSED_ERROR_NAMES.has(name)) ||
+        (!!statusWord && refusedStatusWords.has(statusWord)),
+      () => "wallet_connection_rejected_by_user" as const,
+    )
+    .when(
+      ({ errorTags, statusWord }) =>
+        errorTags.includes("DeviceLockedError") || (!!statusWord && LOCKED_STATUS_WORDS.has(statusWord)),
+      () => "wallet_ledger_device_locked" as const,
+    )
+    .when(
+      ({ errorTags, statusWord }) =>
+        errorTags.includes("UnsupportedApplicationDAError") || (!!statusWord && WRONG_APP_STATUS_WORDS.has(statusWord)),
+      () => "wallet_ledger_app_not_open" as const,
+    )
+    .when(
+      ({ errorNames, errorTags }) =>
+        errorTags.some((errorTag) => DISCONNECTED_ERROR_TAGS.has(errorTag)) ||
+        errorNames.some((name) => DISCONNECTED_ERROR_NAMES.has(name)),
+      () => "wallet_ledger_connection_error" as const,
+    )
+    .otherwise(() => "wallet_ledger_transport_error" as const);
+
+  return new SwapKitError({ errorKey, info: { errorTag: errorTags[0], message, statusWord } }, error);
+}
+
+/**
+ * `action` is a thunk because DMK throws, instead of returning an action, when it cannot start one (e.g.
+ * DeviceSessionNotFound for a session it has dropped), and the signer kits call DMK synchronously. Calling it here
+ * maps that throw like any other device error. Put only the device call inside it, or a plain error from building
+ * the request is reported as a transport error.
+ */
+export function executeLedgerDeviceAction<
+  Output,
+  ActionError,
+  IntermediateValue extends DeviceActionIntermediateValue,
+>({
+  action,
+  onDeviceActionState,
+  userRefusedStatusWords,
+}: {
+  action: () => ExecuteDeviceActionReturnType<Output, ActionError, IntermediateValue>;
+  onDeviceActionState?: LedgerDeviceActionStateHandler;
+} & LedgerDeviceErrorOptions) {
+  return new Promise<Output>((resolve, reject) => {
+    let observable: ExecuteDeviceActionReturnType<Output, ActionError, IntermediateValue>["observable"];
+    try {
+      observable = action().observable;
+    } catch (error) {
+      reject(toLedgerDeviceError(error, { userRefusedStatusWords }));
+      return;
+    }
+
+    let settled = false;
+    let subscription: { unsubscribe: () => void } | undefined;
+
+    function settle(callback: () => void) {
+      if (settled) return;
+      settled = true;
+      subscription?.unsubscribe();
+      callback();
+    }
+
+    subscription = observable.subscribe({
+      complete: () => {
+        settle(() => reject(new SwapKitError("wallet_ledger_invalid_response")));
+      },
+      error: (error) => {
+        settle(() => reject(toLedgerDeviceError(error, { userRefusedStatusWords })));
+      },
+      next: (state) => {
+        try {
+          onDeviceActionState?.(state);
+        } catch (error) {
+          void error;
+        }
+
+        match(state)
+          .with({ status: DEVICE_ACTION_STATUS.Completed }, ({ output }) => settle(() => resolve(output)))
+          .with({ status: DEVICE_ACTION_STATUS.Error }, ({ error }) =>
+            settle(() => reject(toLedgerDeviceError(error, { userRefusedStatusWords }))),
+          )
+          .with({ status: DEVICE_ACTION_STATUS.Stopped }, () =>
+            settle(() => reject(new SwapKitError("wallet_ledger_connection_error"))),
+          )
+          .otherwise(() => undefined);
+      },
+    });
+
+    if (settled) subscription.unsubscribe();
+  });
+}

package/src/ledger/helpers/getLedgerClient.ts

@@ -1,6 +1,14 @@
 import type Transport from "@ledgerhq/hw-transport";
-import { Chain, type DerivationPathArray, type EVMChain, SwapKitError, WalletOption } from "@swapkit/helpers";
-
+import {
+  Chain,
+  type DerivationPathArray,
+  type EVMChain,
+  EVMChains,
+  NetworkDerivationPath,
+  SwapKitError,
+  WalletOption,
+} from "@swapkit/helpers";
+import { BitcoinLedger } from "../clients/bitcoin";
 import { CosmosLedger } from "../clients/cosmos";
 import {
   ArbitrumLedger,
@@ -21,15 +29,11 @@ import { getNearLedgerClient } from "../clients/near";
 import { SuiLedger } from "../clients/sui";
 import { THORChainLedger } from "../clients/thorchain";
 import { TronLedger } from "../clients/tron";
-import {
-  BitcoinCashLedger,
-  BitcoinLedger,
-  DashLedger,
-  DogecoinLedger,
-  LitecoinLedger,
-  ZcashLedger,
-} from "../clients/utxo";
+import { BitcoinCashLedger, DashLedger, DogecoinLedger, LitecoinLedger } from "../clients/utxo";
 import { XRPLedger } from "../clients/xrp";
+import { ZcashLedger } from "../clients/zcash";
+import type { LedgerDMKSession } from "./dmk";
+import type { LedgerDeviceActionStateHandler } from "./executeDeviceAction";
 
 type LedgerSignerMap = {
   [Chain.Arbitrum]: ReturnType<typeof ArbitrumLedger>;
@@ -61,75 +65,100 @@ type LedgerSignerMap = {
 
 type LedgerSupportedChain = keyof LedgerSignerMap;
 
-export const getLedgerClient = async <T extends LedgerSupportedChain>({
+export async function getLedgerClient<T extends LedgerSupportedChain>({
   chain,
+  dmkSession,
   derivationPath,
+  onDeviceActionState,
+  originToken,
   transport,
 }: {
   chain: T;
+  dmkSession?: LedgerDMKSession;
   derivationPath?: DerivationPathArray;
+  onDeviceActionState?: LedgerDeviceActionStateHandler;
+  originToken?: string;
   transport?: Transport;
-}): Promise<LedgerSignerMap[T]> => {
+}): Promise<LedgerSignerMap[T]> {
+  const isEVMChain = EVMChains.includes(chain as EVMChain);
+
+  if (dmkSession && transport) {
+    throw new SwapKitError("wallet_ledger_invalid_params", {
+      message: "Provide either a Ledger DMK session or a LedgerJS transport, not both",
+    });
+  }
+
+  if (isEVMChain && transport) {
+    throw new SwapKitError("wallet_ledger_invalid_params", {
+      message: "Ledger EVM clients require a DMK session instead of a LedgerJS transport",
+    });
+  }
+
+  // The default session is resolved per operation by each client, so a reconnected device is picked up.
+  const clientParams = {
+    derivationPath: derivationPath ?? NetworkDerivationPath[chain],
+    dmkSession,
+    onDeviceActionState,
+    transport,
+  };
   const { match } = await import("ts-pattern");
 
-  return (
-    match(chain as LedgerSupportedChain)
-      .returnType<Promise<LedgerSignerMap[T]>>()
-      .with(Chain.THORChain, () =>
-        Promise.resolve(new THORChainLedger(derivationPath, transport) as LedgerSignerMap[T]),
-      )
-      .with(Chain.Cosmos, () => Promise.resolve(new CosmosLedger(derivationPath, transport) as LedgerSignerMap[T]))
-      .with(Chain.Bitcoin, () => Promise.resolve(BitcoinLedger(derivationPath, transport) as LedgerSignerMap[T]))
-      .with(Chain.BitcoinCash, () =>
-        Promise.resolve(BitcoinCashLedger(derivationPath, transport) as LedgerSignerMap[T]),
-      )
-      .with(Chain.Dash, () => Promise.resolve(DashLedger(derivationPath, transport) as LedgerSignerMap[T]))
-      .with(Chain.Dogecoin, () => Promise.resolve(DogecoinLedger(derivationPath, transport) as LedgerSignerMap[T]))
-      .with(Chain.Litecoin, () => Promise.resolve(LitecoinLedger(derivationPath, transport) as LedgerSignerMap[T]))
-      .with(Chain.Zcash, () => Promise.resolve(ZcashLedger(derivationPath, transport) as LedgerSignerMap[T]))
-      .with(Chain.Ripple, () => Promise.resolve(XRPLedger(derivationPath, transport) as LedgerSignerMap[T]))
-      .with(Chain.Tron, () => Promise.resolve(TronLedger(derivationPath, transport) as LedgerSignerMap[T]))
-      .with(Chain.Sui, () => Promise.resolve(SuiLedger(derivationPath, transport) as LedgerSignerMap[T]))
-      // @ts-expect-error
-      .with(Chain.Near, () => {
-        return Promise.resolve(getNearLedgerClient(derivationPath, transport));
-      })
-      .with(
-        Chain.Arbitrum,
-        Chain.Arc,
-        Chain.Aurora,
-        Chain.Avalanche,
-        Chain.Berachain,
-        Chain.BinanceSmartChain,
-        Chain.Ethereum,
-        Chain.Gnosis,
-        Chain.Monad,
-        Chain.Optimism,
-        Chain.Polygon,
-        Chain.Base,
-        Chain.XLayer,
-        async () => {
-          const { getProvider } = await import("@swapkit/toolboxes/evm");
-          const params = { derivationPath, provider: await getProvider(chain as EVMChain), transport };
+  return match(chain as LedgerSupportedChain)
+    .returnType<Promise<LedgerSignerMap[T]>>()
+    .with(Chain.THORChain, () => Promise.resolve(new THORChainLedger(clientParams) as LedgerSignerMap[T]))
+    .with(Chain.Cosmos, () => Promise.resolve(new CosmosLedger(clientParams) as LedgerSignerMap[T]))
+    .with(Chain.Bitcoin, () => Promise.resolve(BitcoinLedger(clientParams) as LedgerSignerMap[T]))
+    .with(Chain.BitcoinCash, () => Promise.resolve(BitcoinCashLedger(clientParams) as LedgerSignerMap[T]))
+    .with(Chain.Dash, () => Promise.resolve(DashLedger(clientParams) as LedgerSignerMap[T]))
+    .with(Chain.Dogecoin, () => Promise.resolve(DogecoinLedger(clientParams) as LedgerSignerMap[T]))
+    .with(Chain.Litecoin, () => Promise.resolve(LitecoinLedger(clientParams) as LedgerSignerMap[T]))
+    .with(Chain.Zcash, () => Promise.resolve(ZcashLedger(clientParams) as LedgerSignerMap[T]))
+    .with(Chain.Ripple, () => Promise.resolve(XRPLedger(clientParams) as LedgerSignerMap[T]))
+    .with(Chain.Tron, () => Promise.resolve(TronLedger(clientParams) as LedgerSignerMap[T]))
+    .with(Chain.Sui, () => Promise.resolve(SuiLedger(clientParams) as LedgerSignerMap[T]))
+    .with(Chain.Near, () => Promise.resolve(getNearLedgerClient(clientParams) as LedgerSignerMap[T]))
+    .with(
+      Chain.Arbitrum,
+      Chain.Arc,
+      Chain.Aurora,
+      Chain.Avalanche,
+      Chain.Berachain,
+      Chain.BinanceSmartChain,
+      Chain.Ethereum,
+      Chain.Gnosis,
+      Chain.Monad,
+      Chain.Optimism,
+      Chain.Polygon,
+      Chain.Base,
+      Chain.XLayer,
+      async () => {
+        const { getProvider } = await import("@swapkit/toolboxes/evm");
 
-          return match(chain as Chain)
-            .with(Chain.BinanceSmartChain, () => BinanceSmartChainLedger(params) as LedgerSignerMap[T])
-            .with(Chain.Avalanche, () => AvalancheLedger(params) as LedgerSignerMap[T])
-            .with(Chain.Arbitrum, () => ArbitrumLedger(params) as LedgerSignerMap[T])
-            .with(Chain.Arc, () => ArcLedger(params) as LedgerSignerMap[T])
-            .with(Chain.Berachain, () => BerachainLedger(params) as LedgerSignerMap[T])
-            .with(Chain.Optimism, () => OptimismLedger(params) as LedgerSignerMap[T])
-            .with(Chain.Polygon, () => PolygonLedger(params) as LedgerSignerMap[T])
-            .with(Chain.Base, () => BaseLedger(params) as LedgerSignerMap[T])
-            .with(Chain.Aurora, () => AuroraLedger(params) as LedgerSignerMap[T])
-            .with(Chain.Gnosis, () => GnosisLedger(params) as LedgerSignerMap[T])
-            .with(Chain.Monad, () => MonadLedger(params) as LedgerSignerMap[T])
-            .with(Chain.XLayer, () => XLayerLedger(params) as LedgerSignerMap[T])
-            .otherwise(() => EthereumLedger(params) as LedgerSignerMap[T]);
-        },
-      )
-      .otherwise(() => {
-        throw new SwapKitError("wallet_chain_not_supported", { chain, wallet: WalletOption.LEDGER });
-      })
-  );
-};
+        const params = {
+          derivationPath,
+          dmkSession,
+          onDeviceActionState,
+          originToken,
+          provider: await getProvider(chain as EVMChain),
+        };
+
+        return match(chain as Chain)
+          .with(Chain.BinanceSmartChain, () => BinanceSmartChainLedger(params) as LedgerSignerMap[T])
+          .with(Chain.Avalanche, () => AvalancheLedger(params) as LedgerSignerMap[T])
+          .with(Chain.Arbitrum, () => ArbitrumLedger(params) as LedgerSignerMap[T])
+          .with(Chain.Arc, () => ArcLedger(params) as LedgerSignerMap[T])
+          .with(Chain.Berachain, () => BerachainLedger(params) as LedgerSignerMap[T])
+          .with(Chain.Optimism, () => OptimismLedger(params) as LedgerSignerMap[T])
+          .with(Chain.Polygon, () => PolygonLedger(params) as LedgerSignerMap[T])
+          .with(Chain.Base, () => BaseLedger(params) as LedgerSignerMap[T])
+          .with(Chain.Aurora, () => AuroraLedger(params) as LedgerSignerMap[T])
+          .with(Chain.Gnosis, () => GnosisLedger(params) as LedgerSignerMap[T])
+          .with(Chain.Monad, () => MonadLedger(params) as LedgerSignerMap[T])
+          .with(Chain.XLayer, () => XLayerLedger(params) as LedgerSignerMap[T])
+          .otherwise(() => EthereumLedger(params) as LedgerSignerMap[T]);
+      },
+    )
+    .otherwise(() => {
+      throw new SwapKitError("wallet_chain_not_supported", { chain, wallet: WalletOption.LEDGER });
+    });
+}

package/src/ledger/helpers/index.ts

@@ -1,3 +1,8 @@
+export { disconnectLedgerDMKSession, getLedgerDMKSession, type LedgerDMKSession, preloadLedgerDMK } from "./dmk";
+export {
+  executeLedgerDeviceAction,
+  type LedgerDeviceActionState,
+  type LedgerDeviceActionStateHandler,
+} from "./executeDeviceAction";
 export { getLedgerAddress } from "./getLedgerAddress";
 export { getLedgerClient } from "./getLedgerClient";
-export { getLedgerTransport } from "./getLedgerTransport";

package/src/ledger/helpers/ledgerJsDmkBridge.ts

@@ -0,0 +1,109 @@
+import type { UnknownDeviceExchangeError, UserInteractionRequired } from "@ledgerhq/device-management-kit";
+import type Transport from "@ledgerhq/hw-transport";
+import { type DerivationPathArray, SwapKitError } from "@swapkit/helpers";
+
+import { getLedgerDMKSession, type LedgerDMKSession } from "./dmk";
+import {
+  executeLedgerDeviceAction,
+  LEDGER_USER_INTERACTION_REQUIRED,
+  type LedgerDeviceActionStateHandler,
+  toLedgerDeviceError,
+} from "./executeDeviceAction";
+
+export { LEDGER_USER_INTERACTION_REQUIRED };
+
+export interface LedgerJsClientConnection {
+  dmkSession?: LedgerDMKSession;
+  onDeviceActionState?: LedgerDeviceActionStateHandler;
+  transport?: Transport;
+}
+
+export interface LedgerJsClientParams<Path extends DerivationPathArray | string = DerivationPathArray | string>
+  extends LedgerJsClientConnection {
+  derivationPath?: Path;
+}
+
+// `Array.isArray` does not narrow the readonly `DerivationPathArray` tuples out of the union.
+function isLedgerJsClientParams<Path extends DerivationPathArray | string>(
+  value: LedgerJsClientParams<Path> | Path | undefined,
+): value is LedgerJsClientParams<Path> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function normalizeLedgerJsClientParams<Path extends DerivationPathArray | string>({
+  paramsOrPath,
+  transport,
+}: {
+  paramsOrPath?: LedgerJsClientParams<Path> | Path;
+  transport?: Transport;
+}): LedgerJsClientParams<Path> {
+  if (isLedgerJsClientParams(paramsOrPath)) return paramsOrPath;
+  return { derivationPath: paramsOrPath as Path | undefined, transport };
+}
+
+export async function runLedgerJsOperation<App, Output>({
+  appName,
+  connection,
+  createApp,
+  operation,
+  requiredUserInteraction = LEDGER_USER_INTERACTION_REQUIRED.None,
+}: {
+  appName: string;
+  connection: LedgerJsClientConnection;
+  createApp: (transport: Transport) => App;
+  operation: (app: App) => Promise<Output> | Output;
+  requiredUserInteraction?: UserInteractionRequired;
+}) {
+  const { dmkSession, onDeviceActionState, transport } = connection;
+
+  if (dmkSession && transport) {
+    throw new SwapKitError("wallet_ledger_invalid_params", {
+      message: "Provide either a Ledger DMK session or a LedgerJS transport, not both",
+    });
+  }
+
+  if (transport) {
+    try {
+      return await operation(createApp(transport));
+    } catch (error) {
+      // hw-transport rejects with status errors; map them as the DMK path below does.
+      throw toLedgerDeviceError(error);
+    }
+  }
+
+  const session = dmkSession ?? (await getLedgerDMKSession());
+
+  // Loaded before the action is built, so a chunk that fails to load rejects before the app opens. The bridge
+  // transport stays lazy because its hw-transport base class does not load under Node ESM (see its module).
+  const [{ CallTaskInAppDeviceAction, DmkResultFactory, UnknownDeviceExchangeError }, { LedgerJsDmkTransport }] =
+    await Promise.all([import("@ledgerhq/device-management-kit"), import("./ledgerJsDmkTransport")]);
+
+  const deviceAction = new CallTaskInAppDeviceAction<
+    { output: Output },
+    UnknownDeviceExchangeError,
+    UserInteractionRequired
+  >({
+    input: {
+      appName,
+      requiredUserInteraction,
+      skipOpenApp: false,
+      task: async (internalApi) => {
+        try {
+          const output = await operation(createApp(new LedgerJsDmkTransport(internalApi)));
+          return DmkResultFactory<{ output: Output }, UnknownDeviceExchangeError>({ data: { output } });
+        } catch (error) {
+          return DmkResultFactory<{ output: Output }, UnknownDeviceExchangeError>({
+            error: new UnknownDeviceExchangeError(error),
+          });
+        }
+      },
+    },
+  });
+
+  const result = await executeLedgerDeviceAction({
+    action: () => session.dmk.executeDeviceAction({ deviceAction, sessionId: session.sessionId }),
+    onDeviceActionState,
+  });
+
+  return result.output;
+}

package/src/ledger/helpers/ledgerJsDmkTransport.ts

@@ -0,0 +1,88 @@
+import {
+  Apdu,
+  type ApduResponse,
+  type Command,
+  CommandResultFactory,
+  type InternalApi,
+  isSuccessCommandResult,
+  UnknownDeviceExchangeError,
+} from "@ledgerhq/device-management-kit";
+import Transport, { TransportError } from "@ledgerhq/hw-transport";
+
+// Only ever loaded through `import()` from ledgerJsDmkBridge: subclassing needs hw-transport at runtime, and its
+// lib-es build pulls in @ledgerhq/errors with extensionless relative imports that Node ESM cannot resolve, so a
+// static import from a package entry would break `import "@swapkit/wallet-hardware/ledger"` outside a bundler.
+
+const STATUS_CODE_LENGTH = 2;
+const TransportBase =
+  typeof Transport === "function" ? Transport : (Transport as unknown as { default: typeof Transport }).default;
+
+interface RawApduResponse {
+  response: Uint8Array;
+}
+
+class RawApduCommand implements Command<RawApduResponse> {
+  readonly name = "ledgerJsRawApdu";
+
+  constructor(private readonly apdu: Apdu) {}
+
+  getApdu() {
+    return this.apdu;
+  }
+
+  parseResponse({ data, statusCode }: ApduResponse) {
+    if (statusCode.length !== STATUS_CODE_LENGTH) {
+      return CommandResultFactory<RawApduResponse>({
+        error: new UnknownDeviceExchangeError(new Error("Ledger returned an invalid APDU status code")),
+      });
+    }
+
+    const response = new Uint8Array(data.length + statusCode.length);
+    response.set(data);
+    response.set(statusCode, data.length);
+
+    return CommandResultFactory<RawApduResponse>({ data: { response } });
+  }
+}
+
+function parseShortApdu(apdu: Buffer) {
+  if (apdu.length < 5) {
+    throw new TransportError("Ledger APDU must contain a five-byte short-APDU header", "InvalidAPDU");
+  }
+
+  const dataLength = apdu[4];
+  if (dataLength === undefined || apdu.length !== dataLength + 5) {
+    throw new TransportError("Ledger APDU payload length does not match its short-APDU header", "InvalidAPDU");
+  }
+
+  const cla = apdu[0];
+  const ins = apdu[1];
+  const p1 = apdu[2];
+  const p2 = apdu[3];
+  if (cla === undefined || ins === undefined || p1 === undefined || p2 === undefined) {
+    throw new TransportError("Ledger APDU header is incomplete", "InvalidAPDU");
+  }
+
+  return { cla, data: apdu.subarray(5), ins, p1, p2 };
+}
+
+export class LedgerJsDmkTransport extends TransportBase {
+  constructor(private readonly internalApi: InternalApi) {
+    super();
+  }
+
+  async exchange(apdu: Buffer, { abortTimeoutMs }: { abortTimeoutMs?: number } = {}) {
+    const { cla, data, ins, p1, p2 } = parseShortApdu(apdu);
+    const command = new RawApduCommand(new Apdu(cla, ins, p1, p2, data));
+    // Forward only an explicit timeout: hw-transport's 30 s default would cut off a user still confirming
+    // on the device once DMK honours the argument.
+    const result = await this.internalApi.sendCommand(command, abortTimeoutMs);
+
+    if (!isSuccessCommandResult(result)) throw result.error;
+    return Buffer.from(result.data.response);
+  }
+
+  close() {
+    return Promise.resolve();
+  }
+}

package/src/ledger/helpers/lowS.ts

@@ -0,0 +1,30 @@
+const SECP256K1_ORDER = 0xfffffffffffffffffffffffffffffffebaaedce6af48a03bbfd25e8cd0364141n;
+const HALF_ORDER = SECP256K1_ORDER >> 1n;
+
+function bytesToBigInt(bytes: Uint8Array) {
+  return bytes.reduce((value, byte) => (value << 8n) | BigInt(byte), 0n);
+}
+
+function bigIntTo32Bytes(value: bigint) {
+  const bytes = new Uint8Array(32);
+  let remaining = value;
+  for (let index = 31; index >= 0; index -= 1) {
+    bytes[index] = Number(remaining & 0xffn);
+    remaining >>= 8n;
+  }
+  return bytes;
+}
+
+/**
+ * Cosmos SDK rejects high-S secp256k1 signatures. Ledger firmware should already return low-S, but
+ * normalising a fixed-length `r || s` signature here removes the dependency on it.
+ */
+export function toLowSSignature(signature: Uint8Array) {
+  const s = bytesToBigInt(signature.subarray(32, 64));
+  if (s <= HALF_ORDER) return signature;
+
+  const normalized = new Uint8Array(64);
+  normalized.set(signature.subarray(0, 32), 0);
+  normalized.set(bigIntTo32Bytes(SECP256K1_ORDER - s), 32);
+  return normalized;
+}

package/src/ledger/helpers/rawTx.ts

@@ -0,0 +1,12 @@
+export function createCachedRawTxResolver(getRawTx: (txid: string) => Promise<string>) {
+  const requests = new Map<string, Promise<string>>();
+
+  return function resolveRawTx(txid: string) {
+    const cachedRequest = requests.get(txid);
+    if (cachedRequest) return cachedRequest;
+
+    const request = getRawTx(txid);
+    requests.set(txid, request);
+    return request;
+  };
+}