@swapkit/wallet-hardware 5.0.0 → 6.0.0

package/src/ledger/clients/thorchain/protocol.ts

@@ -0,0 +1,166 @@
+import type Transport from "@ledgerhq/hw-transport";
+import { SwapKitError } from "@swapkit/helpers";
+
+const CLA = 0x55;
+const INS_GET_ADDRESS = 0x04;
+const INS_GET_VERSION = 0x00;
+const INS_SIGN = 0x02;
+const P1_INIT = 0x00;
+const P1_ADD = 0x01;
+const P1_LAST = 0x02;
+const STATUS_OK = 0x9000;
+const SIGN_CHUNK_SIZE = 250;
+
+interface ThorCommandParams {
+  data?: Uint8Array;
+  ins: number;
+  p1?: number;
+  p2?: number;
+}
+
+interface ThorApduResponse {
+  data: Uint8Array;
+  statusCode: Uint8Array;
+}
+
+export class ThorCommand {
+  readonly name = "THORChainCommand";
+  private readonly params: ThorCommandParams;
+
+  constructor(params: ThorCommandParams) {
+    this.params = params;
+  }
+
+  getApdu() {
+    const { data = new Uint8Array(), ins, p1 = 0, p2 = 0 } = this.params;
+    return { cla: CLA, data, ins, p1, p2 };
+  }
+
+  parseResponse(response: ThorApduResponse) {
+    const status = (response.statusCode[0] ?? 0) * 0x100 + (response.statusCode[1] ?? 0);
+    if (status !== STATUS_OK) {
+      throw new Error(`THORChain app returned status 0x${status.toString(16).padStart(4, "0")}`);
+    }
+
+    return response.data;
+  }
+}
+
+export function serializeThorPath({ path }: { path: readonly (number | undefined)[] }) {
+  if (path.length !== 5) {
+    throw new SwapKitError("wallet_ledger_invalid_params", { reason: "THORChain path must contain five elements" });
+  }
+
+  const serialized = new Uint8Array(20);
+  const view = new DataView(serialized.buffer);
+
+  path.forEach((segment, index) => {
+    if (typeof segment !== "number" || !Number.isInteger(segment) || segment < 0 || segment > 0xffffffff) {
+      throw new SwapKitError("wallet_ledger_invalid_params", { reason: `Invalid THORChain path segment ${index}` });
+    }
+
+    // The app hardens purpose, coin type and account; a hardened change or index would silently derive
+    // a different key if its bit were cleared, so reject it instead.
+    if (index >= 3 && segment >= 0x80000000) {
+      throw new SwapKitError("wallet_ledger_invalid_params", {
+        reason: `THORChain path segment ${index} must not be hardened`,
+      });
+    }
+
+    const normalized = segment & 0x7fffffff;
+    const value = index < 3 ? (normalized | 0x80000000) >>> 0 : normalized;
+    view.setUint32(index * 4, value, true);
+  });
+
+  return serialized;
+}
+
+export function serializeThorAddressPayload({ hrp, path }: { hrp: string; path: readonly (number | undefined)[] }) {
+  const encodedHrp = new TextEncoder().encode(hrp);
+  if (encodedHrp.length < 1 || encodedHrp.length > 83) {
+    throw new SwapKitError("wallet_ledger_invalid_params", { reason: "Invalid THORChain address prefix" });
+  }
+
+  const serializedPath = serializeThorPath({ path });
+  return Uint8Array.from([encodedHrp.length, ...encodedHrp, ...serializedPath]);
+}
+
+export function getThorAddressCommand({
+  checkOnDevice,
+  hrp,
+  path,
+}: {
+  checkOnDevice: boolean;
+  hrp: string;
+  path: readonly (number | undefined)[];
+}) {
+  return new ThorCommand({
+    data: serializeThorAddressPayload({ hrp, path }),
+    ins: INS_GET_ADDRESS,
+    p1: checkOnDevice ? 1 : 0,
+  });
+}
+
+export function getThorSignCommands({ message, path }: { message: Uint8Array; path: readonly (number | undefined)[] }) {
+  const commands = [new ThorCommand({ data: serializeThorPath({ path }), ins: INS_SIGN, p1: P1_INIT })];
+
+  if (message.length === 0) {
+    commands.push(new ThorCommand({ data: new Uint8Array(), ins: INS_SIGN, p1: P1_LAST }));
+    return commands;
+  }
+
+  for (let offset = 0; offset < message.length; offset += SIGN_CHUNK_SIZE) {
+    const end = Math.min(offset + SIGN_CHUNK_SIZE, message.length);
+    commands.push(
+      new ThorCommand({
+        data: message.slice(offset, end),
+        ins: INS_SIGN,
+        p1: end === message.length ? P1_LAST : P1_ADD,
+      }),
+    );
+  }
+
+  return commands;
+}
+
+function parseTransportResponse({ response }: { response: Uint8Array }) {
+  if (response.length < 2) {
+    throw new SwapKitError("wallet_ledger_invalid_response", { reason: "THORChain response is missing status bytes" });
+  }
+
+  return response.slice(0, -2);
+}
+
+export async function getThorLegacyVersion({ transport }: { transport: Transport }) {
+  const response = await transport.send(CLA, INS_GET_VERSION, 0, 0, Buffer.alloc(0), [STATUS_OK]);
+  const data = parseTransportResponse({ response });
+  if (data.length < 4) {
+    throw new SwapKitError("wallet_ledger_invalid_response", { reason: "Invalid THORChain version response" });
+  }
+
+  return `${data[1]}.${data[2]}.${data[3]}`;
+}
+
+export async function sendThorLegacyCommand({ command, transport }: { command: ThorCommand; transport: Transport }) {
+  const apdu = command.getApdu();
+  const response = await transport.send(apdu.cla, apdu.ins, apdu.p1, apdu.p2, Buffer.from(apdu.data), [STATUS_OK]);
+  return parseTransportResponse({ response });
+}
+
+export function parseThorAddressResponse({ response }: { response: Uint8Array }) {
+  if (response.length < 34) {
+    throw new SwapKitError("wallet_ledger_invalid_response", { reason: "Invalid THORChain address response" });
+  }
+
+  const publicKey = response.slice(0, 33);
+  const address = new TextDecoder().decode(response.slice(33));
+  if (!address) {
+    throw new SwapKitError("wallet_ledger_invalid_response", { reason: "THORChain address is empty" });
+  }
+
+  return { address, publicKey };
+}
+
+export function invalidThorAppVersionMessage({ version }: { version?: string }) {
+  return `THORChain Ledger app major 2 is required, received ${version || "unknown"}`;
+}

package/src/ledger/clients/tron.ts

@@ -1,3 +1,4 @@
+import type { UserInteractionRequired } from "@ledgerhq/device-management-kit";
 import type TronApp from "@ledgerhq/hw-app-trx";
 import type Transport from "@ledgerhq/hw-transport";
 import {
@@ -8,79 +9,90 @@ import {
 } from "@swapkit/helpers";
 import type { TronSignedTransaction, TronSigner, TronTransaction } from "@swapkit/toolboxes/tron";
 
-import { getLedgerTransport } from "../helpers/getLedgerTransport";
+import {
+  LEDGER_USER_INTERACTION_REQUIRED,
+  type LedgerJsClientParams,
+  normalizeLedgerJsClientParams,
+  runLedgerJsOperation,
+} from "../helpers/ledgerJsDmkBridge";
+
+type TronLedgerParams = LedgerJsClientParams<DerivationPathArray | string>;
 
 export class TronLedgerInterface implements TronSigner {
-  derivationPath: string;
-  ledgerApp: InstanceType<typeof TronApp> | null = null;
-  ledgerTimeout = 50000;
-  private readonly injectedTransport?: Transport;
+  readonly derivationPath: string;
+  readonly ledgerTimeout = 50000;
+  private readonly connection: Omit<TronLedgerParams, "derivationPath">;
 
-  constructor(derivationPath?: DerivationPathArray | string, transport?: Transport) {
+  constructor(paramsOrPath?: TronLedgerParams | DerivationPathArray | string, transport?: Transport) {
+    const { derivationPath, ...connection } = normalizeLedgerJsClientParams({ paramsOrPath, transport });
     this.derivationPath =
       typeof derivationPath === "string"
         ? derivationPath
         : derivationPathToString(derivationPath || NetworkDerivationPath.TRON);
-    this.injectedTransport = transport;
+    this.connection = connection;
+  }
+
+  private async runTronOperation<Output>({
+    operation,
+    requiredUserInteraction,
+  }: {
+    operation: (app: InstanceType<typeof TronApp>) => Promise<Output>;
+    requiredUserInteraction?: UserInteractionRequired;
+  }) {
+    const TronApp = (await import("@ledgerhq/hw-app-trx")).default;
+    return runLedgerJsOperation({
+      appName: "Tron",
+      connection: this.connection,
+      createApp: (ledgerTransport) => new TronApp(ledgerTransport),
+      operation,
+      requiredUserInteraction,
+    });
   }
 
   checkOrCreateTransportAndLedger = async () => {
-    if (this.ledgerApp) return;
-    await this.createTransportAndLedger();
+    await this.runTronOperation({ operation: async () => true });
   };
 
   createTransportAndLedger = async () => {
-    const transport = this.injectedTransport ?? (await getLedgerTransport());
-    const TronApp = (await import("@ledgerhq/hw-app-trx")).default;
-
-    this.ledgerApp = new TronApp(transport);
+    await this.runTronOperation({ operation: async () => true });
   };
 
-  getAddress = async (): Promise<string> => {
+  getAddress = async () => {
     const response = await this.getAddressAndPubKey();
     if (!response) throw new SwapKitError("wallet_ledger_failed_to_get_address");
     return response.address;
   };
 
   getAddressAndPubKey = async () => {
-    await this.createTransportAndLedger();
-    const result = await this.ledgerApp?.getAddress(this.derivationPath);
-
+    const result = await this.runTronOperation({ operation: (app) => app.getAddress(this.derivationPath) });
     if (!result) throw new SwapKitError("wallet_ledger_failed_to_get_address");
 
     return { address: result.address, publicKey: result.publicKey };
   };
 
   showAddressAndPubKey = async () => {
-    await this.createTransportAndLedger();
-    return this.ledgerApp?.getAddress(this.derivationPath, true);
+    return await this.runTronOperation({
+      operation: (app) => app.getAddress(this.derivationPath, true),
+      requiredUserInteraction: LEDGER_USER_INTERACTION_REQUIRED.VerifyAddress,
+    });
   };
 
   signTransaction = async (transaction: TronTransaction): Promise<TronSignedTransaction> => {
-    await this.createTransportAndLedger();
-
-    if (!this.ledgerApp) {
-      throw new SwapKitError("wallet_ledger_transport_error");
-    }
-
     try {
-      const signature = await this.ledgerApp.signTransaction(
-        this.derivationPath,
-        transaction.raw_data_hex,
-        [], // Token signatures array - empty for native TRX transfers
-      );
-
-      if (!signature) {
-        throw new SwapKitError("wallet_ledger_signing_error");
-      }
+      const signature = await this.runTronOperation({
+        operation: (app) => app.signTransaction(this.derivationPath, transaction.raw_data_hex, []),
+        requiredUserInteraction: LEDGER_USER_INTERACTION_REQUIRED.SignTransaction,
+      });
 
-      // Return the signed transaction in Tron's expected format
+      if (!signature) throw new SwapKitError("wallet_ledger_signing_error");
       return { ...transaction, signature: [signature] };
     } catch (error) {
+      if (error instanceof SwapKitError) throw error;
       throw new SwapKitError("wallet_ledger_signing_error", { error });
     }
   };
 }
 
-export const TronLedger = (derivationPath?: DerivationPathArray, transport?: Transport) =>
-  new TronLedgerInterface(derivationPath, transport);
+export function TronLedger(paramsOrPath?: TronLedgerParams | DerivationPathArray, transport?: Transport) {
+  return new TronLedgerInterface(paramsOrPath, transport);
+}

package/src/ledger/clients/utxo-legacy-adapter.ts

@@ -2,6 +2,7 @@ import { hex } from "@scure/base";
 import { SwapKitError, type UTXOChain } from "@swapkit/helpers";
 import type { UTXOType } from "@swapkit/toolboxes/utxo";
 import type { Transaction } from "@swapkit/utxo-signer";
+import { createCachedRawTxResolver } from "../helpers/rawTx";
 
 /**
  * Extract per-input metadata from a V3 PSBT in the shape the legacy
@@ -16,50 +17,51 @@ import type { Transaction } from "@swapkit/utxo-signer";
 export async function extractInputsFromPsbt(tx: Transaction, chain: UTXOChain): Promise<UTXOType[]> {
   const { RawTx } = await import("@swapkit/utxo-signer");
   const { getUtxoApi } = await import("@swapkit/toolboxes/utxo");
-  const inputs: UTXOType[] = [];
+  const utxoApi = getUtxoApi(chain);
+  const getRawTx = createCachedRawTxResolver((txid) => utxoApi.getRawTx(txid));
 
-  for (let i = 0; i < tx.inputsLength; i++) {
-    const input = tx.getInput(i);
+  return Promise.all(
+    Array.from({ length: tx.inputsLength }, async (_, inputIndex) => {
+      const input = tx.getInput(inputIndex);
 
-    if (!input.txid || input.index === undefined) {
-      throw new Error(`PSBT input ${i} is missing txid/index`);
-    }
+      if (!input.txid || input.index === undefined) {
+        throw new Error(`PSBT input ${inputIndex} is missing txid/index`);
+      }
 
-    const txid = hex.encode(input.txid);
-    const txHex = input.nonWitnessUtxo
-      ? hex.encode(RawTx.encode(input.nonWitnessUtxo))
-      : await getUtxoApi(chain).getRawTx(txid);
-    if (!txHex) {
-      throw new SwapKitError("wallet_ledger_invalid_params", {
-        chain,
-        inputIndex: i,
-        reason: "Unable to resolve previous transaction hex for Ledger signing",
-        txid,
-      });
-    }
-    const witnessUtxo = input.witnessUtxo
-      ? { script: input.witnessUtxo.script, value: Number(input.witnessUtxo.amount) }
-      : undefined;
-    const nonWitnessPrevout = input.index !== undefined ? input.nonWitnessUtxo?.outputs?.[input.index] : undefined;
-    const value = witnessUtxo?.value ?? (nonWitnessPrevout ? Number(nonWitnessPrevout.amount) : 0);
+      const txid = hex.encode(input.txid);
+      const txHex = input.nonWitnessUtxo ? hex.encode(RawTx.encode(input.nonWitnessUtxo)) : await getRawTx(txid);
+      if (!txHex) {
+        throw new SwapKitError("wallet_ledger_invalid_params", {
+          chain,
+          inputIndex,
+          reason: "Unable to resolve previous transaction hex for Ledger signing",
+          txid,
+        });
+      }
+      const witnessUtxo = input.witnessUtxo
+        ? { script: input.witnessUtxo.script, value: Number(input.witnessUtxo.amount) }
+        : undefined;
+      const nonWitnessPrevout = input.nonWitnessUtxo?.outputs?.[input.index];
+      const value = witnessUtxo?.value ?? (nonWitnessPrevout ? Number(nonWitnessPrevout.amount) : 0);
 
-    inputs.push({ hash: txid, index: input.index, txHex, value, witnessUtxo } as UTXOType);
-  }
-
-  return inputs;
+      return { hash: txid, index: input.index, txHex, value, witnessUtxo } as UTXOType;
+    }),
+  );
 }
 
 export async function signLegacyPsbtTransaction({
-  legacyClient,
   chain,
+  inputUtxos,
+  legacyClient,
   tx,
 }: {
-  legacyClient: { signTransaction: (tx: Transaction, inputUtxos: UTXOType[]) => Promise<string> };
   chain: UTXOChain;
+  inputUtxos?: UTXOType[];
+  legacyClient: { signTransaction: (tx: Transaction, inputUtxos: UTXOType[]) => Promise<string> };
   tx: Transaction;
 }): Promise<string> {
-  const inputUtxos = await extractInputsFromPsbt(tx, chain);
-  return legacyClient.signTransaction(tx, inputUtxos);
+  const resolvedInputUtxos = inputUtxos ?? (await extractInputsFromPsbt(tx, chain));
+  return legacyClient.signTransaction(tx, resolvedInputUtxos);
 }
 
 /**
@@ -86,7 +88,8 @@ export function createLegacyPsbtSigner({
       const { Transaction: TxClass } = await import("@swapkit/utxo-signer");
       // `Transaction.fromRaw` parses a serialised tx (no PSBT envelope) — exactly
       // what `createPaymentTransaction` returns.
-      return TxClass.fromRaw(hex.decode(signedTxHex));
+      // Memo transactions carry an OP_RETURN output, which the parser treats as unknown.
+      return TxClass.fromRaw(hex.decode(signedTxHex), { allowUnknownOutputs: true });
     },
   };
 }

package/src/ledger/clients/utxo-legacy-outputs.ts

@@ -0,0 +1,122 @@
+import type Transport from "@ledgerhq/hw-transport";
+import { SwapKitError } from "@swapkit/helpers";
+
+/**
+ * lib-app-bitcoin, behind the Bitcoin Cash, Dash, Dogecoin and Litecoin apps, collects the output it is checking in a
+ * 100-byte buffer (MAX_OUTPUT_TO_CHECK) while signing the first input. It tests every HASH_INPUT_FINALIZE_FULL payload
+ * against the room left in that buffer before appending it, and rejects one that does not fit with 0x6a80 ("Output is
+ * too long to be checked"); a complete output leaves the buffer once the user has approved it.
+ */
+const LEGACY_APP_MAX_OUTPUT_LENGTH = 100;
+
+const HASH_INPUT_FINALIZE_FULL = { cla: 0xe0, ins: 0x4a } as const;
+const FINALIZE_P1_MORE = 0x00;
+const FINALIZE_P1_LAST = 0x80;
+// The app's own reply to a FINALIZE_P1_MORE APDU: a zero byte and 0x9000.
+const FINALIZE_MORE_RESPONSE = [0x00, 0x90, 0x00];
+
+// Bitcoin CompactSize. The 8-byte form describes nothing the app accepts, so it reads as malformed.
+function readCompactSize(bytes: Uint8Array, offset: number): { size: number; value: number } | undefined {
+  const marker = bytes[offset];
+  if (marker === undefined || marker === 0xff) return undefined;
+  if (marker < 0xfd) return { size: 1, value: marker };
+
+  const width = marker === 0xfd ? 2 : 4;
+  if (offset + 1 + width > bytes.length) return undefined;
+  const view = new DataView(bytes.buffer, bytes.byteOffset + offset + 1, width);
+  return { size: 1 + width, value: width === 2 ? view.getUint16(0, true) : view.getUint32(0, true) };
+}
+
+/**
+ * Splits serialised transaction outputs (the output count, then each output) into one piece per output, the first
+ * carrying the count, so that every piece the legacy app receives ends on an output boundary. Rejects a malformed
+ * stream and any piece the app cannot buffer.
+ */
+export function splitOutputsForLegacyApp(outputs: Uint8Array, chain: string): Uint8Array[] {
+  const invalidOutputs = (reason: string, info: Record<string, number> = {}) =>
+    new SwapKitError({
+      errorKey: "wallet_ledger_invalid_params",
+      info: {
+        chain,
+        maxLength: LEGACY_APP_MAX_OUTPUT_LENGTH,
+        operation: "splitOutputsForLegacyApp",
+        outputsLength: outputs.length,
+        reason,
+        ...info,
+      },
+    });
+
+  const count = readCompactSize(outputs, 0);
+  if (!count?.value) throw invalidOutputs("Transaction outputs do not start with a readable non-zero output count");
+
+  const pieces: Uint8Array[] = [];
+  let offset = count.size;
+  for (let outputIndex = 0; outputIndex < count.value; outputIndex += 1) {
+    // An output is an 8-byte amount, the script length and the script; the first piece also carries the count.
+    const pieceStart = outputIndex === 0 ? 0 : offset;
+    const scriptLength = readCompactSize(outputs, offset + 8);
+    const outputEnd = scriptLength ? offset + 8 + scriptLength.size + scriptLength.value : undefined;
+    if (!outputEnd || outputEnd > outputs.length) {
+      throw invalidOutputs("Transaction output is truncated", { outputIndex });
+    }
+
+    const pieceLength = outputEnd - pieceStart;
+    if (pieceLength > LEGACY_APP_MAX_OUTPUT_LENGTH) {
+      throw invalidOutputs("Output is longer than the Ledger app can check; shorten the memo", {
+        outputIndex,
+        pieceLength,
+      });
+    }
+
+    pieces.push(outputs.subarray(pieceStart, outputEnd));
+    offset = outputEnd;
+  }
+
+  if (offset !== outputs.length) {
+    throw invalidOutputs("Transaction outputs are followed by trailing bytes", {
+      trailingBytes: outputs.length - offset,
+    });
+  }
+
+  return pieces;
+}
+
+/**
+ * hw-app-btc streams the outputs in fixed 50-byte HASH_INPUT_FINALIZE_FULL chunks. Each chunk has to fit the app's
+ * buffer beside whatever unfinished output earlier chunks left there, which fails for longer memo outputs (in the
+ * SDK's [vault, memo, change] order, from a 56-byte memo with P2PKH outputs and a 59-byte memo on Litecoin). Collect
+ * the chunks of each stream and resend it one output per APDU: each APDU then meets an empty buffer, so any output of
+ * up to 100 bytes (the first together with the output count) fits, and the bytes, and so the hashes, stay the same.
+ * hw-app-btc ignores every response to these APDUs, so a collected chunk gets the app's own reply and the last one
+ * returns the device's. The change-path APDU (P1 0xff) and every other APDU pass straight through.
+ */
+export function withOutputAlignedFinalize(transport: Transport, chain: string): Transport {
+  let chunks: Buffer[] = [];
+
+  const send: Transport["send"] = async (cla, ins, p1, p2, data = Buffer.alloc(0), ...rest) => {
+    const isOutputChunk =
+      cla === HASH_INPUT_FINALIZE_FULL.cla &&
+      ins === HASH_INPUT_FINALIZE_FULL.ins &&
+      (p1 === FINALIZE_P1_MORE || p1 === FINALIZE_P1_LAST);
+    if (!isOutputChunk) return transport.send(cla, ins, p1, p2, data, ...rest);
+
+    chunks.push(data);
+    if (p1 === FINALIZE_P1_MORE) return Buffer.from(FINALIZE_MORE_RESPONSE);
+
+    const outputs = Buffer.concat(chunks);
+    chunks = [];
+    const pieces = splitOutputsForLegacyApp(outputs, chain);
+
+    let response: Buffer = Buffer.alloc(0);
+    for (const [index, piece] of pieces.entries()) {
+      const pieceP1 = index === pieces.length - 1 ? FINALIZE_P1_LAST : FINALIZE_P1_MORE;
+      response = await transport.send(cla, ins, pieceP1, p2, Buffer.from(piece), ...rest);
+    }
+    return response;
+  };
+
+  // A Proxy rather than a copy, so the app-API lock and every other field stay on the caller's transport.
+  return new Proxy(transport, {
+    get: (target, property, receiver) => (property === "send" ? send : Reflect.get(target, property, receiver)),
+  });
+}