@swapkit/wallet-hardware 5.0.0 → 6.0.0

package/src/ledger/index.ts

@@ -1,4 +1,5 @@
 import type Transport from "@ledgerhq/hw-transport";
+import { hex } from "@scure/base";
 import {
   type AssetValue,
   Chain,
@@ -6,8 +7,7 @@ import {
   derivationPathToString,
   FeeOption,
   filterSupportedChains,
-  type GenericTransferParams,
-  getRPCUrl,
+  getUTXOScriptTypeForPath,
   NetworkDerivationPath,
   SwapKitError,
   type UTXOChain,
@@ -27,34 +27,143 @@ import {
   getUtxoApi,
   type UTXOBuildTxParams,
   type UTXOForMultiAddressTransfer,
+  type UTXOTransferParams,
+  type UTXOType,
 } from "@swapkit/toolboxes/utxo";
-import type { Transaction } from "@swapkit/utxo-signer";
+import type { Transaction, ZcashTransaction } from "@swapkit/utxo-signer";
 import { createWallet, getWalletSupportedChains, type HardwareExtendedPublicKeyInfo } from "@swapkit/wallet-core";
-import { getLedgerAddress, getLedgerClient } from "./helpers";
+import { match, P } from "ts-pattern";
+import {
+  getLedgerAddress,
+  getLedgerClient,
+  type LedgerDeviceActionStateHandler,
+  type LedgerDMKSession,
+} from "./helpers";
+import { createCachedRawTxResolver } from "./helpers/rawTx";
+
+type BitcoinLedgerClient = ReturnType<typeof import("./clients/bitcoin")["BitcoinLedger"]>;
+type LegacyUTXOLedgerClient = ReturnType<typeof import("./clients/utxo")["BitcoinCashLedger"]>;
+type ZcashLedgerClient = ReturnType<typeof import("./clients/zcash")["ZcashLedger"]>;
+type UTXOLedgerClient = BitcoinLedgerClient | LegacyUTXOLedgerClient | ZcashLedgerClient;
 
 /**
  * Options passed to `connectLedger` at call time.
  *
- * When `transport` is supplied, the consumer opens and owns its lifecycle —
- * wallet-hardware will use that exact instance for every per-chain Ledger
- * client and will NOT recreate it on `forceReconnect`. When omitted, the
- * default browser flow (WebHID / WebUSB via `navigator.usb`) is used.
+ * When `dmkSession` is omitted, the default browser WebHID flow discovers a
+ * device and reuses one session across chains. Lazy-loaded apps can call
+ * `preloadLedgerDMK` before the user gesture that starts connection.
  */
-export type ConnectLedgerOptions = { address?: string; transport?: Transport };
+export interface ConnectLedgerOptions {
+  address?: string;
+  /** Caller-owned DMK session used by every supported chain. */
+  dmkSession?: LedgerDMKSession;
+  /** Receives DMK progress and device-interaction states. */
+  onDeviceActionState?: LedgerDeviceActionStateHandler;
+  /** Ledger-provided token required for Transaction Checks. */
+  originToken?: string;
+  /** @deprecated Temporary non-EVM fallback. Cannot be combined with `dmkSession`. */
+  transport?: Transport;
+}
+
+interface WalletMethodsParams<C extends Chain = Chain> extends ConnectLedgerOptions {
+  chain: C;
+  derivationPath?: DerivationPathArray;
+}
+
+interface LedgerAccountXpubParams {
+  chain: UTXOChain;
+  path: string;
+  signer: UTXOLedgerClient;
+  xpubVersion: number;
+}
+
+interface SignLedgerTransactionParams {
+  inputUtxos?: UTXOType[];
+  transaction: Transaction | ZcashTransaction;
+}
+
+const LEDGER_SUPPORTED_CHAINS_CONFIG = [
+  Chain.Arbitrum,
+  Chain.Arc,
+  Chain.Aurora,
+  Chain.Avalanche,
+  Chain.Base,
+  Chain.Berachain,
+  Chain.BinanceSmartChain,
+  Chain.Bitcoin,
+  Chain.BitcoinCash,
+  Chain.Cosmos,
+  Chain.Dash,
+  Chain.Dogecoin,
+  Chain.Ethereum,
+  Chain.Gnosis,
+  Chain.Litecoin,
+  Chain.Monad,
+  Chain.Near,
+  Chain.Optimism,
+  Chain.Polygon,
+  Chain.Ripple,
+  Chain.Sui,
+  Chain.THORChain,
+  Chain.XLayer,
+  Chain.Tron,
+  Chain.Zcash,
+] as const;
+
+type LedgerSupportedChain = (typeof LEDGER_SUPPORTED_CHAINS_CONFIG)[number];
+
+const LEDGER_UTXO_CHAINS = [
+  Chain.BitcoinCash,
+  Chain.Bitcoin,
+  Chain.Dash,
+  Chain.Dogecoin,
+  Chain.Litecoin,
+  Chain.Zcash,
+] as const satisfies readonly UTXOChain[];
+
+const LEDGER_EVM_CHAINS = [
+  Chain.Ethereum,
+  Chain.Avalanche,
+  Chain.Arbitrum,
+  Chain.Arc,
+  Chain.Berachain,
+  Chain.Optimism,
+  Chain.Polygon,
+  Chain.BinanceSmartChain,
+  Chain.Base,
+  Chain.Aurora,
+  Chain.Gnosis,
+  Chain.Monad,
+  Chain.XLayer,
+] as const satisfies readonly LedgerSupportedChain[];
+
+type LedgerEVMChain = (typeof LEDGER_EVM_CHAINS)[number];
+
+function isLedgerSupportedChain(chain: Chain): chain is LedgerSupportedChain {
+  return LEDGER_SUPPORTED_CHAINS_CONFIG.includes(chain as LedgerSupportedChain);
+}
 
 export const ledgerWallet = createWallet({
   connect: ({ addChain, supportedChains, walletType }) =>
     async function connectLedger(
       chains: Chain[],
       derivationPath?: DerivationPathArray,
-      { address, transport }: ConnectLedgerOptions = {},
+      { address, dmkSession, onDeviceActionState, originToken, transport }: ConnectLedgerOptions = {},
     ) {
       const [chain] = filterSupportedChains({ chains, supportedChains, walletType });
 
       if (!chain) return false;
 
       const resolvedPath = derivationPath ?? (NetworkDerivationPath[chain] as DerivationPathArray | undefined);
-      const walletMethods = await getWalletMethods({ address, chain, derivationPath: resolvedPath, transport });
+      const walletMethods = await getWalletMethods({
+        address,
+        chain,
+        derivationPath: resolvedPath,
+        dmkSession,
+        onDeviceActionState,
+        originToken,
+        transport,
+      });
 
       addChain({ ...walletMethods, chain, walletType: WalletOption.LEDGER });
 
@@ -85,436 +194,522 @@ export const ledgerWallet = createWallet({
     [Chain.THORChain]: true,
     [Chain.Tron]: true,
     [Chain.XLayer]: true,
-    // ZEC: still on bespoke signPCZT path
+    // ZEC transparent transfers use DSK, but route-level PCZT signing remains unsupported.
   },
   getExtendedPublicKey: getLedgerExtendedPublicKey,
   name: "connectLedger",
-  supportedChains: [
-    Chain.Arbitrum,
-    Chain.Arc,
-    Chain.Aurora,
-    Chain.Avalanche,
-    Chain.Base,
-    Chain.Berachain,
-    Chain.BinanceSmartChain,
-    Chain.Bitcoin,
-    Chain.BitcoinCash,
-    Chain.Cosmos,
-    Chain.Dash,
-    Chain.Dogecoin,
-    Chain.Ethereum,
-    Chain.Gnosis,
-    Chain.Litecoin,
-    Chain.Monad,
-    Chain.Near,
-    Chain.Optimism,
-    Chain.Polygon,
-    Chain.Ripple,
-    Chain.Sui,
-    Chain.THORChain,
-    Chain.XLayer,
-    Chain.Tron,
-    Chain.Zcash,
-  ],
+  supportedChains: [...LEDGER_SUPPORTED_CHAINS_CONFIG],
   walletType: WalletOption.LEDGER,
 });
 
 export const LEDGER_SUPPORTED_CHAINS = getWalletSupportedChains(ledgerWallet);
 
-// reduce memo length by removing trade limit
-function reduceMemo(memo?: string, affiliateAddress = "t") {
-  if (!memo?.includes("=:")) return memo;
+function getLedgerAccountXpub({ chain, path, signer, xpubVersion }: LedgerAccountXpubParams) {
+  const ledgerPath = match(chain)
+    .with(Chain.Bitcoin, Chain.Litecoin, () => path)
+    .with(Chain.BitcoinCash, Chain.Dash, Chain.Dogecoin, Chain.Zcash, () => path.replace(/^m\//, ""))
+    .exhaustive();
+
+  return match(chain)
+    .with(Chain.Bitcoin, () => (signer as BitcoinLedgerClient).getExtendedPublicKey({ path: ledgerPath }))
+    .with(Chain.Zcash, () => (signer as ZcashLedgerClient).getExtendedPublicKey({ path: ledgerPath, xpubVersion }))
+    .with(Chain.BitcoinCash, Chain.Dash, Chain.Dogecoin, Chain.Litecoin, () =>
+      (signer as LegacyUTXOLedgerClient).getExtendedPublicKey(ledgerPath, xpubVersion),
+    )
+    .exhaustive();
+}
 
-  const removedAffiliate = memo.includes(`:${affiliateAddress}:`) ? memo.split(`:${affiliateAddress}:`)[0] : memo;
+// Toolbox-built transactions keep input txids in display order, the order the UTXO API looks transactions up by,
+// while ZcashTransaction.fromBytes (raw API route transactions) keeps them in wire order, so try both. A txid and its
+// byte reversal cannot both name real transactions, so the fallback cannot fetch an unrelated one.
+function resolveZcashInputUtxos(transaction: ZcashTransaction): Promise<UTXOType[]> {
+  const zcashApi = getUtxoApi(Chain.Zcash);
+  const getRawTx = createCachedRawTxResolver((txid) => zcashApi.getRawTx(txid));
+
+  return Promise.all(
+    Array.from({ length: transaction.inputsLength }, async (_, inputIndex) => {
+      const input = transaction.getInput(inputIndex);
+      const txid = hex.encode(input.txid);
+      const reversedTxid = hex.encode(input.txid.slice().reverse());
+      const directTxHex = await getRawTx(txid);
+      const [hash, txHex] = directTxHex ? [txid, directTxHex] : [reversedTxid, await getRawTx(reversedTxid)];
+      if (!txHex) {
+        throw new SwapKitError("wallet_ledger_invalid_params", {
+          inputIndex,
+          outputIndex: input.index,
+          reason: "Unable to resolve previous transaction hex for Ledger signing in either txid byte order",
+          reversedTxid,
+          txid,
+        });
+      }
 
-  return removedAffiliate?.substring(0, removedAffiliate.lastIndexOf(":"));
+      // The Zcash client takes amounts from the device's trusted inputs; fromBytes leaves input values at zero.
+      return { hash, index: input.index, txHex, value: Number(input.value) };
+    }),
+  );
 }
 
 export async function getLedgerExtendedPublicKey(
   chain: Chain,
   derivationPath?: DerivationPathArray,
-  { accountIndex }: { accountIndex?: number } = {},
+  {
+    accountIndex,
+    dmkSession,
+    onDeviceActionState,
+    transport,
+  }: {
+    accountIndex?: number;
+    dmkSession?: LedgerDMKSession;
+    onDeviceActionState?: LedgerDeviceActionStateHandler;
+    transport?: Transport;
+  } = {},
 ): Promise<HardwareExtendedPublicKeyInfo | undefined> {
   if (![Chain.BitcoinCash, Chain.Bitcoin, Chain.Dash, Chain.Dogecoin, Chain.Litecoin, Chain.Zcash].includes(chain)) {
     throw new SwapKitError("wallet_chain_not_supported", { chain, wallet: WalletOption.LEDGER });
   }
 
   const utxoChain = chain as UTXOChain;
-  const signer = await getLedgerClient({ chain: utxoChain, derivationPath });
+  const signer = await getLedgerClient({
+    chain: utxoChain,
+    derivationPath,
+    dmkSession,
+    onDeviceActionState,
+    transport,
+  });
   if (!signer.getExtendedPublicKey) return undefined;
 
   const accountPath = getUTXOAccountPath({ accountIndex, chain: utxoChain, derivationPath });
   const path = derivationPathToString(accountPath);
-  const ledgerPath = chain === Chain.Bitcoin || chain === Chain.Litecoin ? path : path.replace(/^m\//, "");
   const xpubVersion = getNetworkForChain(utxoChain).bip32.public;
   try {
-    const xpub = await signer.getExtendedPublicKey(ledgerPath, xpubVersion);
+    const xpub = await getLedgerAccountXpub({ chain: utxoChain, path, signer, xpubVersion });
     return { accountIndex: getUTXOAccountIndexFromPath(accountPath), path, xpub };
   } finally {
     await (signer as { disconnect?: () => Promise<void> }).disconnect?.();
   }
 }
 
-async function getWalletMethods({
+async function getUTXOWalletMethods({
   address: providedAddress,
   chain,
+  dmkSession,
   derivationPath,
+  onDeviceActionState,
   transport,
-}: ConnectLedgerOptions & { chain: Chain; derivationPath?: DerivationPathArray }) {
-  switch (chain) {
-    case Chain.BitcoinCash:
-    case Chain.Bitcoin:
-    case Chain.Dash:
-    case Chain.Dogecoin:
-    case Chain.Litecoin:
-    case Chain.Zcash: {
-      const { getUtxoToolbox } = await import("@swapkit/toolboxes/utxo");
-      const utxoChain = chain as UTXOChain;
-
-      const signer = await getLedgerClient({ chain, derivationPath, transport });
-
-      const address = providedAddress ?? (await getLedgerAddress({ chain, ledgerClient: signer }));
-      const scriptType = getScriptTypeForAddress(address, utxoChain);
-
-      // V3 toolbox signer:
-      //  - BTC uses the modern `ledger-bitcoin` AppClient with native PSBT signing.
-      //  - LTC/BCH/DOGE/DASH use the legacy `hw-app-btc` adapter that pulls
-      //    `nonWitnessUtxo` (full prev-tx hex) out of the API PSBT.
-      //    The Litecoin Ledger app does not support the `ledger-bitcoin`
-      //    policy APDUs and returns CLA_NOT_SUPPORTED.
-      //  - ZEC stays on the bespoke `signPCZT` flow for now.
-      let toolboxSigner:
-        | {
-            getAddress: () => Promise<string>;
-            publicKey?: Uint8Array;
-            signTransaction: (tx: Transaction) => Promise<Transaction>;
+}: WalletMethodsParams<UTXOChain>) {
+  const { getUtxoToolbox } = await import("@swapkit/toolboxes/utxo");
+  const utxoChain = chain;
+
+  const signer = await getLedgerClient({ chain, derivationPath, dmkSession, onDeviceActionState, transport });
+
+  const address = providedAddress ?? (await getLedgerAddress({ chain, ledgerClient: signer }));
+  // On Bitcoin the account's path states its encoding (BIP44/49/84/86). The other apps sign for the address format
+  // the client derives (an 86' Litecoin account is ltc1q), so they, like a custom purpose, follow the address form.
+  const scriptType =
+    (chain === Chain.Bitcoin ? getUTXOScriptTypeForPath(derivationPath) : undefined) ??
+    getScriptTypeForAddress(address, utxoChain);
+
+  const { publicKey, signLedgerTransaction, toolboxSigner } = await match(chain)
+    .with(Chain.Bitcoin, async () => {
+      const bitcoinSigner = signer as BitcoinLedgerClient;
+      // Nested SegWit and taproot inputs need the key behind them (redeemScript, tapInternalKey).
+      const needsPublicKey = scriptType === UTXOScriptType.P2SH_P2WPKH || scriptType === UTXOScriptType.P2TR;
+      const publicKey = needsPublicKey ? await bitcoinSigner.getPublicKey() : undefined;
+      return {
+        publicKey,
+        signLedgerTransaction: ({ inputUtxos, transaction }: SignLedgerTransactionParams) =>
+          bitcoinSigner.signTransactionHex({ inputUtxos, tx: transaction as Transaction }),
+        toolboxSigner: {
+          getAddress: bitcoinSigner.getAddress,
+          publicKey,
+          signTransaction: bitcoinSigner.signTransaction,
+        },
+      };
+    })
+    .with(Chain.BitcoinCash, Chain.Dogecoin, Chain.Dash, Chain.Litecoin, async () => {
+      const { createLegacyPsbtSigner, signLegacyPsbtTransaction } = await import("./clients/utxo-legacy-adapter");
+      const legacySigner = signer as LegacyUTXOLedgerClient;
+      return {
+        publicKey: undefined,
+        signLedgerTransaction: ({ inputUtxos, transaction }: SignLedgerTransactionParams) =>
+          signLegacyPsbtTransaction({
+            chain: utxoChain,
+            inputUtxos,
+            legacyClient: legacySigner,
+            tx: transaction as Transaction,
+          }),
+        toolboxSigner: createLegacyPsbtSigner({ address, chain: utxoChain, legacyClient: legacySigner }),
+      };
+    })
+    .with(Chain.Zcash, () => {
+      const zcashSigner = signer as ZcashLedgerClient;
+      return {
+        publicKey: undefined,
+        signLedgerTransaction: async ({ inputUtxos, transaction }: SignLedgerTransactionParams) => {
+          if (!("consensusBranchId" in transaction)) {
+            throw new SwapKitError("wallet_ledger_method_not_supported", {
+              method: "signPCZT",
+              wallet: WalletOption.LEDGER,
+            });
           }
-        | undefined;
-      let publicKey: Uint8Array | undefined;
-      let signAndBroadcastLegacyPsbtTransaction: ((tx: Transaction) => Promise<string>) | undefined;
-      if (chain === Chain.Bitcoin) {
-        const { BitcoinPsbtLedger } = await import("./clients/utxo-psbt");
-        const psbtClient = BitcoinPsbtLedger(derivationPath, transport);
-        publicKey = scriptType === UTXOScriptType.P2SH_P2WPKH ? await psbtClient.getPublicKey() : undefined;
-        toolboxSigner = { getAddress: psbtClient.getAddress, publicKey, signTransaction: psbtClient.signTransaction };
-      } else if (
-        chain === Chain.BitcoinCash ||
-        chain === Chain.Dogecoin ||
-        chain === Chain.Dash ||
-        chain === Chain.Litecoin
-      ) {
-        const { createLegacyPsbtSigner, signLegacyPsbtTransaction } = await import("./clients/utxo-legacy-adapter");
-        toolboxSigner = createLegacyPsbtSigner({ address, chain: utxoChain, legacyClient: signer });
-        signAndBroadcastLegacyPsbtTransaction = async (tx) => {
-          const signedTxHex = await signLegacyPsbtTransaction({ chain: utxoChain, legacyClient: signer, tx });
-          return toolbox.broadcastTx(signedTxHex);
-        };
-      }
 
-      const toolbox = toolboxSigner
-        ? await getUtxoToolbox(utxoChain, { scriptType, signer: toolboxSigner })
-        : getUtxoToolbox(utxoChain, { scriptType });
-      const signAndBroadcastTransaction = signAndBroadcastLegacyPsbtTransaction ?? toolbox.signAndBroadcastTransaction;
-
-      const transfer = async (params: UTXOBuildTxParams) => {
-        const feeRate = params.feeRate || (await toolbox.getFeeRates())[FeeOption.Average];
-        const memo = [Chain.Bitcoin].includes(chain as typeof Chain.Bitcoin) ? params.memo : reduceMemo(params.memo);
-
-        const { tx, inputs } = await toolbox.createTransaction({
-          ...params,
-          feeRate,
-          fetchTxHex: true,
-          memo,
-          publicKey: params.publicKey ?? publicKey,
-          sender: address,
-        });
+          const resolvedInputUtxos = inputUtxos ?? (await resolveZcashInputUtxos(transaction));
+          return zcashSigner.signTransaction({ inputUtxos: resolvedInputUtxos, tx: transaction });
+        },
+        toolboxSigner: undefined,
+      };
+    })
+    .exhaustive();
 
-        // Legacy Ledger UTXO signing returns finalized raw tx hex, so transfer
-        // broadcasts directly instead of routing through toolbox finalization.
-        const txHex = await signer.signTransaction(tx as Transaction, inputs);
-        const txHash = await toolbox.broadcastTx(txHex);
+  const toolbox = toolboxSigner
+    ? await getUtxoToolbox(utxoChain, { scriptType, signer: toolboxSigner })
+    : getUtxoToolbox(utxoChain, { scriptType });
+  const signAndBroadcastTransaction = async (transaction: Transaction | ZcashTransaction) =>
+    toolbox.broadcastTx(await signLedgerTransaction({ transaction }));
 
-        return txHash;
-      };
+  // The toolbox's transfer parameters plus a public key override; the sender is always the Ledger account.
+  const transfer = async (params: UTXOTransferParams & Pick<UTXOBuildTxParams, "enableRBF" | "publicKey">) => {
+    const feeRate = params.feeRate || (await toolbox.getFeeRates())[params.feeOptionKey || FeeOption.Fast];
 
-      async function getExtendedPublicKeyInfo({ accountIndex }: { accountIndex?: number } = {}) {
-        if (!signer.getExtendedPublicKey) return undefined;
+    const { tx, inputs } = await toolbox.createTransaction({
+      ...params,
+      feeRate,
+      fetchTxHex: true,
+      publicKey: params.publicKey ?? publicKey,
+      sender: address,
+    });
 
-        const accountPath = getUTXOAccountPath({ accountIndex, chain: utxoChain, derivationPath });
-        const path = derivationPathToString(accountPath);
-        const ledgerPath = chain === Chain.Bitcoin || chain === Chain.Litecoin ? path : path.replace(/^m\//, "");
-        const xpubVersion = getNetworkForChain(utxoChain).bip32.public;
-        const xpub = await signer.getExtendedPublicKey(ledgerPath, xpubVersion);
+    const txHex = await signLedgerTransaction({ inputUtxos: inputs, transaction: tx });
+    const txHash = await toolbox.broadcastTx(txHex);
 
-        return { accountIndex: getUTXOAccountIndexFromPath(accountPath), path, xpub };
-      }
+    return txHash;
+  };
 
-      function getExtendedPublicKey(params: { accountIndex?: number } = {}) {
-        return getExtendedPublicKeyInfo(params);
-      }
+  async function getExtendedPublicKeyInfo({ accountIndex }: { accountIndex?: number } = {}) {
+    if (!signer.getExtendedPublicKey) return undefined;
 
-      async function deriveAddressAtIndex({
-        accountIndex,
-        index,
-        change = false,
-      }: {
-        accountIndex?: number;
-        index: number;
-        change?: boolean;
-      }) {
-        try {
-          const fullPath = getUTXOAddressPath({ accountIndex, chain: utxoChain, change, derivationPath, index });
-
-          const indexedSigner = await getLedgerClient({ chain: utxoChain, derivationPath: fullPath, transport });
-          const derivedAddress = await getLedgerAddress({ chain: utxoChain, ledgerClient: indexedSigner });
-
-          return {
-            accountIndex: getUTXOAccountIndexFromPath(fullPath),
-            address: derivedAddress,
-            change,
-            index,
-            path: derivationPathToString(fullPath),
-            pubkey: "",
-          };
-        } catch {
-          return undefined;
-        }
-      }
+    const accountPath = getUTXOAccountPath({ accountIndex, chain: utxoChain, derivationPath });
+    const path = derivationPathToString(accountPath);
+    const xpubVersion = getNetworkForChain(utxoChain).bip32.public;
+    const xpub = await getLedgerAccountXpub({ chain, path, signer, xpubVersion });
 
-      async function deriveAddresses({
-        accountIndex,
-        count,
-        startIndex = 0,
-        change = false,
-      }: {
-        accountIndex?: number;
-        count: number;
-        startIndex?: number;
-        change?: boolean;
-      }) {
-        assertDerivationIndex("count", count);
-        assertDerivationIndex("startIndex", startIndex);
-
-        const addresses = await Promise.all(
-          Array.from({ length: count }, (_, i) =>
-            deriveAddressAtIndex({ accountIndex, change, index: startIndex + i }),
-          ),
-        );
-
-        return addresses.filter((address) => !!address);
-      }
+    return { accountIndex: getUTXOAccountIndexFromPath(accountPath), path, xpub };
+  }
 
-      const hdHelpers = createHDWalletHelpers({
+  function getExtendedPublicKey(params: { accountIndex?: number } = {}) {
+    return getExtendedPublicKeyInfo(params);
+  }
+
+  async function deriveAddressAtIndex({
+    accountIndex,
+    index,
+    change = false,
+  }: {
+    accountIndex?: number;
+    index: number;
+    change?: boolean;
+  }) {
+    try {
+      const fullPath = getUTXOAddressPath({ accountIndex, chain: utxoChain, change, derivationPath, index });
+
+      const indexedSigner = await getLedgerClient({
         chain: utxoChain,
-        deriveAddress: deriveAddressAtIndex,
-        getBalance: toolbox.getBalance,
-        getUtxos: (addr: string) => getUtxoApi(utxoChain).getUtxos({ address: addr, fetchTxHex: true }),
+        derivationPath: fullPath,
+        dmkSession,
+        onDeviceActionState,
+        transport,
       });
+      const derivedAddress = await getLedgerAddress({ chain: utxoChain, ledgerClient: indexedSigner });
 
-      async function transferFromMultipleAddresses({
-        utxos,
-        recipient,
-        assetValue,
-        memo,
-        feeRate,
-        feeOptionKey,
-        changeAddress,
-      }: {
-        utxos: UTXOForMultiAddressTransfer[];
-        recipient: string;
-        assetValue: AssetValue;
-        memo?: string;
-        feeRate?: number;
-        feeOptionKey?: FeeOption;
-        changeAddress?: string;
-      }) {
-        if (!utxos.length) {
-          throw new SwapKitError("wallet_ledger_invalid_params", {
-            message: "No UTXOs provided for multi-address transfer",
-          });
-        }
-
-        const txFeeRate = feeRate || (await toolbox.getFeeRates())[feeOptionKey || FeeOption.Fast];
-        const memoScript = memo ? compileMemo(memo) : null;
-
-        const targetOutputs: Array<{ address: string; value: number } | { script: Uint8Array; value: number }> = [
-          { address: recipient, value: assetValue.getBaseValue("number") },
-        ];
-        if (memoScript) {
-          targetOutputs.push({ script: memoScript, value: 0 });
-        }
-
-        const basicUtxos = utxos.map(({ hash, index, value, txHex, witnessUtxo }) => ({
-          hash,
-          index,
-          txHex,
-          value,
-          witnessUtxo,
-        }));
-
-        const { inputs: selectedInputs, outputs } = toolbox.accumulative({
-          chain: utxoChain,
-          feeRate: txFeeRate,
-          inputs: basicUtxos,
-          outputs: targetOutputs,
-        });
+      return {
+        accountIndex: getUTXOAccountIndexFromPath(fullPath),
+        address: derivedAddress,
+        change,
+        index,
+        path: derivationPathToString(fullPath),
+        pubkey: "",
+      };
+    } catch {
+      return undefined;
+    }
+  }
 
-        if (!(selectedInputs && outputs)) {
-          throw new SwapKitError("wallet_ledger_connection_error", {
-            message: "Insufficient balance for multi-address transfer",
-          });
-        }
-
-        const { Transaction } = await import("@swapkit/utxo-signer");
-        const tx = new Transaction({ allowLegacyWitnessUtxo: true, version: 1 });
-        const senderAddress = changeAddress || utxos[0]?.address || recipient;
-
-        addInputsAndOutputs({
-          chain: utxoChain,
-          compiledMemo: memoScript,
-          inputs: selectedInputs,
-          outputs,
-          sender: senderAddress,
-          tx,
-        });
+  async function deriveAddresses({
+    accountIndex,
+    count,
+    startIndex = 0,
+    change = false,
+  }: {
+    accountIndex?: number;
+    count: number;
+    startIndex?: number;
+    change?: boolean;
+  }) {
+    assertDerivationIndex("count", count);
+    assertDerivationIndex("startIndex", startIndex);
+
+    const addresses = await Promise.all(
+      Array.from({ length: count }, (_, i) => deriveAddressAtIndex({ accountIndex, change, index: startIndex + i })),
+    );
+
+    return addresses.filter((address) => !!address);
+  }
 
-        const basePath = getUTXOAccountPath({ chain: utxoChain, derivationPath });
-        const inputDerivationPaths = selectedInputs.map((input: { hash: string; index: number }) => {
-          const utxoInfo = utxos.find((u) => u.hash === input.hash && u.index === input.index);
-          const derivationIndex = utxoInfo?.derivationIndex ?? 0;
-          const isChange = utxoInfo?.isChange ?? false;
-          const fullPath = [...basePath, Number(isChange), derivationIndex] as unknown as DerivationPathArray;
-          return derivationPathToString(fullPath);
-        });
+  const hdHelpers = createHDWalletHelpers({
+    chain: utxoChain,
+    deriveAddress: deriveAddressAtIndex,
+    getBalance: toolbox.getBalance,
+    getUtxos: (addr: string) => getUtxoApi(utxoChain).getUtxos({ address: addr, fetchTxHex: true }),
+  });
+
+  async function transferFromMultipleAddresses({
+    utxos,
+    recipient,
+    assetValue,
+    memo,
+    feeRate,
+    feeOptionKey,
+    changeAddress,
+  }: {
+    utxos: UTXOForMultiAddressTransfer[];
+    recipient: string;
+    assetValue: AssetValue;
+    memo?: string;
+    feeRate?: number;
+    feeOptionKey?: FeeOption;
+    changeAddress?: string;
+  }) {
+    if (chain === Chain.Zcash) {
+      throw new SwapKitError("wallet_ledger_method_not_supported", {
+        method: "transferFromMultipleAddresses",
+        wallet: WalletOption.LEDGER,
+      });
+    }
 
-        if (!signer.signTransactionWithMultiplePaths) {
-          throw new SwapKitError("wallet_ledger_method_not_supported", { method: "signTransactionWithMultiplePaths" });
-        }
+    if (!utxos.length) {
+      throw new SwapKitError("wallet_ledger_invalid_params", {
+        message: "No UTXOs provided for multi-address transfer",
+      });
+    }
 
-        const txHex = await signer.signTransactionWithMultiplePaths(tx, selectedInputs, inputDerivationPaths);
-        return toolbox.broadcastTx(txHex);
-      }
+    const txFeeRate = feeRate || (await toolbox.getFeeRates())[feeOptionKey || FeeOption.Fast];
+    const memoScript = memo ? compileMemo(memo) : null;
 
-      return {
-        ...toolbox,
-        ...hdHelpers,
-        address,
-        deriveAddressAtIndex,
-        deriveAddresses,
-        getExtendedPublicKey,
-        getExtendedPublicKeyInfo,
-        signAndBroadcastTransaction,
-        transfer,
-        transferFromMultipleAddresses,
-      };
+    const targetOutputs: Array<{ address: string; value: number } | { script: Uint8Array; value: number }> = [
+      { address: recipient, value: assetValue.getBaseValue("number") },
+    ];
+    if (memoScript) {
+      targetOutputs.push({ script: memoScript, value: 0 });
     }
 
-    case Chain.Ethereum:
-    case Chain.Avalanche:
-    case Chain.Arbitrum:
-    case Chain.Arc:
-    case Chain.Berachain:
-    case Chain.Optimism:
-    case Chain.Polygon:
-    case Chain.BinanceSmartChain:
-    case Chain.Base:
-    case Chain.Aurora:
-    case Chain.Gnosis:
-    case Chain.Monad:
-    case Chain.XLayer: {
-      const { getEvmToolboxAsync } = await import("@swapkit/toolboxes/evm");
-      const signer = await getLedgerClient({ chain, derivationPath, transport });
-      const address = await getLedgerAddress({ chain, ledgerClient: signer });
-      const toolbox = await getEvmToolboxAsync(chain, { signer });
-
-      return { ...toolbox, address };
+    const basicUtxos = utxos.map(({ hash, index, value, txHex, witnessUtxo }) => ({
+      hash,
+      index,
+      txHex,
+      value,
+      witnessUtxo,
+    }));
+
+    const { inputs: selectedInputs, outputs } = toolbox.accumulative({
+      chain: utxoChain,
+      feeRate: txFeeRate,
+      inputs: basicUtxos,
+      outputs: targetOutputs,
+    });
+
+    if (!(selectedInputs && outputs)) {
+      throw new SwapKitError("wallet_ledger_connection_error", {
+        message: "Insufficient balance for multi-address transfer",
+      });
     }
 
-    case Chain.Cosmos: {
-      const { createSigningStargateClient, getDefaultChainFee, getMsgSendDenom, getCosmosToolbox } = await import(
-        "@swapkit/toolboxes/cosmos"
-      );
-      const signer = await getLedgerClient({ chain, derivationPath, transport });
-      const address = await getLedgerAddress({ chain, ledgerClient: signer });
-      const toolbox = await getCosmosToolbox(Chain.Cosmos, { signer });
-
-      const transfer = async ({ assetValue, recipient, memo }: GenericTransferParams) => {
-        if (!assetValue) throw new SwapKitError("wallet_ledger_invalid_asset");
-
-        const sendCoinsMessage = {
-          amount: [
-            {
-              amount: assetValue.getBaseValue("string"),
-              denom: getMsgSendDenom(`u${assetValue.symbol}`).toLowerCase(),
-            },
-          ],
-          fromAddress: address,
-          toAddress: recipient,
-        };
-
-        const rpcUrl = await getRPCUrl(chain);
-        const signingClient = await createSigningStargateClient(rpcUrl, signer, "0.007uatom");
-
-        const { transactionHash } = await signingClient.signAndBroadcast(
-          address,
-          [{ typeUrl: "/cosmos.bank.v1beta1.MsgSend", value: sendCoinsMessage }],
-          getDefaultChainFee(Chain.Cosmos),
-          memo,
-        );
-
-        return transactionHash;
-      };
+    const { Transaction } = await import("@swapkit/utxo-signer");
+    const tx = new Transaction({ allowLegacyWitnessUtxo: true, allowUnknownOutputs: !!memoScript, version: 1 });
+    const senderAddress = changeAddress || utxos[0]?.address || recipient;
+
+    addInputsAndOutputs({
+      chain: utxoChain,
+      compiledMemo: memoScript,
+      inputs: selectedInputs,
+      outputs,
+      sender: senderAddress,
+      tx,
+    });
+
+    const inputDerivationPaths = selectedInputs.map((input: { hash: string; index: number }) => {
+      const utxoInfo = utxos.find((u) => u.hash === input.hash && u.index === input.index);
+      const fullPath = getUTXOAddressPath({
+        chain: utxoChain,
+        change: utxoInfo?.isChange ?? false,
+        derivationPath,
+        index: utxoInfo?.derivationIndex ?? 0,
+      });
+      return derivationPathToString(fullPath);
+    });
 
-      return { ...toolbox, address, transfer };
+    if (!signer.signTransactionWithMultiplePaths) {
+      throw new SwapKitError("wallet_ledger_method_not_supported", { method: "signTransactionWithMultiplePaths" });
     }
 
-    case Chain.THORChain: {
-      const signer = await getLedgerClient({ chain, derivationPath, transport });
-      const { getCosmosToolbox } = await import("@swapkit/toolboxes/cosmos");
-      const toolbox = getCosmosToolbox(chain, { signer });
-      const address = await getLedgerAddress({ chain, ledgerClient: signer });
-      const { sign: signMessage } = signer;
+    const txHex = await match(chain)
+      .with(Chain.Bitcoin, () =>
+        (signer as BitcoinLedgerClient).signTransactionWithMultiplePaths({
+          derivationPaths: inputDerivationPaths,
+          inputUtxos: selectedInputs,
+          tx,
+        }),
+      )
+      .with(Chain.BitcoinCash, Chain.Dash, Chain.Dogecoin, Chain.Litecoin, () =>
+        (signer as LegacyUTXOLedgerClient).signTransactionWithMultiplePaths(tx, selectedInputs, inputDerivationPaths),
+      )
+      .exhaustive();
+    return toolbox.broadcastTx(txHex);
+  }
 
-      return { ...toolbox, address, signMessage };
-    }
+  return {
+    ...toolbox,
+    ...hdHelpers,
+    address,
+    deriveAddressAtIndex,
+    deriveAddresses,
+    getExtendedPublicKey,
+    getExtendedPublicKeyInfo,
+    signAndBroadcastTransaction,
+    transfer,
+    transferFromMultipleAddresses,
+  };
+}
 
-    case Chain.Near: {
-      const { getNearToolbox } = await import("@swapkit/toolboxes/near");
-      const signer = await getLedgerClient({ chain, derivationPath, transport });
-      const accountId = await signer.getAddress();
-      const toolbox = getNearToolbox({ signer });
+async function getEVMWalletMethods({
+  chain,
+  derivationPath,
+  dmkSession,
+  onDeviceActionState,
+  originToken,
+  transport,
+}: WalletMethodsParams<LedgerEVMChain>) {
+  const signer = await getLedgerClient({
+    chain,
+    derivationPath,
+    dmkSession,
+    onDeviceActionState,
+    originToken,
+    transport,
+  });
+  const { getEvmToolboxAsync } = await import("@swapkit/toolboxes/evm");
+  const address = await getLedgerAddress({ chain, ledgerClient: signer });
+  const toolbox = await getEvmToolboxAsync(chain, { signer });
+
+  return { ...toolbox, address };
+}
 
-      return { ...toolbox, address: accountId };
-    }
+async function getCosmosWalletMethods({
+  chain,
+  derivationPath,
+  dmkSession,
+  onDeviceActionState,
+  transport,
+}: WalletMethodsParams<Chain.Cosmos>) {
+  const signer = await getLedgerClient({ chain, derivationPath, dmkSession, onDeviceActionState, transport });
+  const { getCosmosToolbox } = await import("@swapkit/toolboxes/cosmos");
+  const toolbox = getCosmosToolbox(chain, { signer });
+  const address = await getLedgerAddress({ chain, ledgerClient: signer });
 
-    case Chain.Ripple: {
-      const { getRippleToolbox } = await import("@swapkit/toolboxes/ripple");
-      const signer = await getLedgerClient({ chain, derivationPath, transport });
-      const address = signer.getAddress();
-      const toolbox = getRippleToolbox({ signer });
+  return { ...toolbox, address };
+}
 
-      return { ...toolbox, address };
-    }
+async function getTHORChainWalletMethods({
+  chain,
+  derivationPath,
+  dmkSession,
+  onDeviceActionState,
+  transport,
+}: WalletMethodsParams<Chain.THORChain>) {
+  const signer = await getLedgerClient({ chain, derivationPath, dmkSession, onDeviceActionState, transport });
+  const { getCosmosToolbox } = await import("@swapkit/toolboxes/cosmos");
+  const toolbox = getCosmosToolbox(chain, { signer });
+  const address = await getLedgerAddress({ chain, ledgerClient: signer });
+  const { sign: signMessage } = signer;
+
+  return { ...toolbox, address, signMessage };
+}
 
-    case Chain.Tron: {
-      const { getTronToolbox } = await import("@swapkit/toolboxes/tron");
-      const signer = await getLedgerClient({ chain, derivationPath, transport });
-      const address = await getLedgerAddress({ chain, ledgerClient: signer });
-      const toolbox = getTronToolbox({ signer });
+async function getNearWalletMethods({
+  chain,
+  derivationPath,
+  dmkSession,
+  onDeviceActionState,
+  transport,
+}: WalletMethodsParams<Chain.Near>) {
+  const { getNearToolbox } = await import("@swapkit/toolboxes/near");
+  const signer = await getLedgerClient({ chain, derivationPath, dmkSession, onDeviceActionState, transport });
+  const accountId = await signer.getAddress();
+  const toolbox = getNearToolbox({ signer });
 
-      return { ...toolbox, address };
-    }
+  return { ...toolbox, address: accountId };
+}
+
+async function getRippleWalletMethods({
+  chain,
+  derivationPath,
+  dmkSession,
+  onDeviceActionState,
+  transport,
+}: WalletMethodsParams<Chain.Ripple>) {
+  const { getRippleToolbox } = await import("@swapkit/toolboxes/ripple");
+  const signer = await getLedgerClient({ chain, derivationPath, dmkSession, onDeviceActionState, transport });
+  const address = signer.getAddress();
+  const toolbox = getRippleToolbox({ signer });
 
-    case Chain.Sui: {
-      const { getSuiToolbox } = await import("@swapkit/toolboxes/sui");
-      const signer = await getLedgerClient({ chain, derivationPath, transport });
-      const address = await getLedgerAddress({ chain, ledgerClient: signer });
-      const toolbox = getSuiToolbox({ signer });
+  return { ...toolbox, address };
+}
 
-      return { ...toolbox, address };
-    }
+async function getTronWalletMethods({
+  chain,
+  derivationPath,
+  dmkSession,
+  onDeviceActionState,
+  transport,
+}: WalletMethodsParams<Chain.Tron>) {
+  const { getTronToolbox } = await import("@swapkit/toolboxes/tron");
+  const signer = await getLedgerClient({ chain, derivationPath, dmkSession, onDeviceActionState, transport });
+  const address = await getLedgerAddress({ chain, ledgerClient: signer });
+  const toolbox = getTronToolbox({ signer });
+
+  return { ...toolbox, address };
+}
+
+async function getSuiWalletMethods({
+  chain,
+  derivationPath,
+  dmkSession,
+  onDeviceActionState,
+  transport,
+}: WalletMethodsParams<Chain.Sui>) {
+  const { getSuiToolbox } = await import("@swapkit/toolboxes/sui");
+  const signer = await getLedgerClient({ chain, derivationPath, dmkSession, onDeviceActionState, transport });
+  const address = await getLedgerAddress({ chain, ledgerClient: signer });
+  const toolbox = getSuiToolbox({ signer });
+
+  return { ...toolbox, address };
+}
 
-    default:
-      throw new SwapKitError("wallet_ledger_chain_not_supported", { chain });
+function getWalletMethods(params: WalletMethodsParams) {
+  if (!isLedgerSupportedChain(params.chain)) {
+    throw new SwapKitError("wallet_ledger_chain_not_supported", { chain: params.chain });
   }
+
+  return match(params.chain)
+    .with(P.union(...LEDGER_UTXO_CHAINS), (chain) => getUTXOWalletMethods({ ...params, chain }))
+    .with(P.union(...LEDGER_EVM_CHAINS), (chain) => getEVMWalletMethods({ ...params, chain }))
+    .with(Chain.Cosmos, (chain) => getCosmosWalletMethods({ ...params, chain }))
+    .with(Chain.THORChain, (chain) => getTHORChainWalletMethods({ ...params, chain }))
+    .with(Chain.Near, (chain) => getNearWalletMethods({ ...params, chain }))
+    .with(Chain.Ripple, (chain) => getRippleWalletMethods({ ...params, chain }))
+    .with(Chain.Tron, (chain) => getTronWalletMethods({ ...params, chain }))
+    .with(Chain.Sui, (chain) => getSuiWalletMethods({ ...params, chain }))
+    .exhaustive();
 }
+
+export type { LedgerDeviceActionState, LedgerDeviceActionStateHandler, LedgerDMKSession } from "./helpers";
+export { disconnectLedgerDMKSession, getLedgerDMKSession, preloadLedgerDMK } from "./helpers";