@swapkit/wallet-hardware 6.1.1 → 6.3.0

package/src/ledger/clients/cardano.ts

@@ -0,0 +1,204 @@
+import type {
+  Ada,
+  AssetGroup,
+  BIP32Path,
+  ExtendedPublicKey,
+  SignedTransactionData,
+  SignTransactionRequest,
+  TxOutput,
+  TxOutputDestination,
+} from "@cardano-foundation/ledgerjs-hw-app-cardano";
+import type { UserInteractionRequired } from "@ledgerhq/device-management-kit";
+import type Transport from "@ledgerhq/hw-transport";
+import { hex } from "@scure/base";
+import { Chain, type DerivationPathArray, NetworkDerivationPath, SwapKitError } from "@swapkit/helpers";
+
+import { type CardanoOutputFields, readCardanoBody } from "../../helpers/cardano";
+import {
+  LEDGER_USER_INTERACTION_REQUIRED,
+  type LedgerJsClientParams,
+  normalizeLedgerJsClientParams,
+  runLedgerJsOperation,
+} from "../helpers/ledgerJsDmkBridge";
+
+export type CardanoLedgerModule = typeof import("@cardano-foundation/ledgerjs-hw-app-cardano");
+export type CardanoLedgerAddressParams = { address: string; paymentPath: BIP32Path; stakingPath: BIP32Path };
+
+type CardanoLedgerParams = LedgerJsClientParams<DerivationPathArray>;
+
+function notSupported(reason: string) {
+  return new SwapKitError("wallet_ledger_method_not_supported", { chain: Chain.Cardano, reason });
+}
+
+async function toLedgerOutput(
+  { address, amount, format, tokenGroups }: CardanoOutputFields,
+  own: CardanoLedgerAddressParams,
+  { AddressType, TxOutputDestinationType, TxOutputFormat }: CardanoLedgerModule,
+): Promise<TxOutput> {
+  const { getCardanoAddressFromBytes } = await import("@swapkit/toolboxes/cardano");
+  const outputAddress = await getCardanoAddressFromBytes(address);
+  const destination: TxOutputDestination =
+    outputAddress === own.address
+      ? {
+          params: {
+            params: { spendingPath: own.paymentPath, stakingPath: own.stakingPath },
+            type: AddressType.BASE_PAYMENT_KEY_STAKE_KEY,
+          },
+          type: TxOutputDestinationType.DEVICE_OWNED,
+        }
+      : { params: { addressHex: hex.encode(address) }, type: TxOutputDestinationType.THIRD_PARTY };
+  const tokenBundle: AssetGroup[] | undefined = tokenGroups?.map(({ policyId, tokens }) => ({
+    policyIdHex: hex.encode(policyId),
+    tokens: tokens.map(({ amount, assetName }) => ({ amount, assetNameHex: hex.encode(assetName) })),
+  }));
+
+  return {
+    amount,
+    destination,
+    format: format === "legacy" ? TxOutputFormat.ARRAY_LEGACY : TxOutputFormat.MAP_BABBAGE,
+    ...(tokenBundle === undefined ? {} : { tokenBundle }),
+  } as TxOutput;
+}
+
+export async function toLedgerCardanoTransaction(
+  txHex: string,
+  own: CardanoLedgerAddressParams,
+  ledgerModule: CardanoLedgerModule,
+): Promise<SignTransactionRequest> {
+  const { decodeCardanoTransaction } = await import("@swapkit/toolboxes/cardano");
+  const { Networks, TransactionSigningMode, TxAuxiliaryDataType } = ledgerModule;
+  const { body } = await decodeCardanoTransaction(txHex);
+  const { auxiliaryDataHash, fee, inputs, outputs, tagCborSets, ttl, validityIntervalStart } = readCardanoBody(
+    body,
+    "Ledger",
+    notSupported,
+  );
+
+  return {
+    additionalWitnessPaths: [],
+    options: { tagCborSets },
+    signingMode: TransactionSigningMode.ORDINARY_TRANSACTION,
+    tx: {
+      fee,
+      inputs: inputs.map(({ index, txHash }) => ({
+        outputIndex: index,
+        path: own.paymentPath,
+        txHashHex: hex.encode(txHash),
+      })),
+      network: Networks.Mainnet,
+      outputs: await Promise.all(outputs.map((output) => toLedgerOutput(output, own, ledgerModule))),
+      ...(auxiliaryDataHash
+        ? {
+            auxiliaryData: {
+              params: { hashHex: hex.encode(auxiliaryDataHash) },
+              type: TxAuxiliaryDataType.ARBITRARY_HASH,
+            },
+          }
+        : {}),
+      ...(ttl === undefined ? {} : { ttl }),
+      ...(validityIntervalStart === undefined ? {} : { validityIntervalStart }),
+    },
+  };
+}
+
+export async function addLedgerWitnesses(
+  txHex: string,
+  { txHashHex, witnesses }: Pick<SignedTransactionData, "txHashHex" | "witnesses">,
+  { paymentPath, publicKey }: { paymentPath: BIP32Path; publicKey: Uint8Array },
+) {
+  const { addCardanoVkeyWitnesses, decodeCardanoTransaction } = await import("@swapkit/toolboxes/cardano");
+  const { bodyHash } = await decodeCardanoTransaction(txHex);
+
+  if (txHashHex.toLowerCase() !== bodyHash) {
+    throw new SwapKitError("wallet_ledger_invalid_signature", {
+      chain: Chain.Cardano,
+      error: "Ledger signed a different transaction body",
+    });
+  }
+  if (witnesses.length === 0) {
+    throw new SwapKitError("wallet_ledger_signing_error", {
+      chain: Chain.Cardano,
+      error: "Ledger returned no witness",
+    });
+  }
+
+  const vkeyWitnesses = witnesses.map(({ path, witnessSignatureHex }) => {
+    if (path.length !== paymentPath.length || path.some((level, i) => level !== paymentPath[i])) {
+      throw new SwapKitError("wallet_ledger_signing_error", {
+        chain: Chain.Cardano,
+        error: "Ledger returned a witness for an unexpected key",
+      });
+    }
+    return { publicKey, signature: hex.decode(witnessSignatureHex) };
+  });
+
+  return addCardanoVkeyWitnesses(txHex, vkeyWitnesses);
+}
+
+export async function CardanoLedger(paramsOrPath?: CardanoLedgerParams | DerivationPathArray, transport?: Transport) {
+  const { derivationPath, ...connection } = normalizeLedgerJsClientParams({ paramsOrPath, transport });
+  const path = derivationPath || NetworkDerivationPath[Chain.Cardano];
+  const [purpose, coinType, account, role, index] = path;
+  if (path.length !== 5 || role !== 0 || index === undefined) {
+    throw new SwapKitError("wallet_ledger_derivation_path_error", { chain: Chain.Cardano, derivationPath: path });
+  }
+
+  const ledgerModule = await import("@cardano-foundation/ledgerjs-hw-app-cardano");
+  const { getCardanoAddressFromBytes, getCardanoPublicKeyHash } = await import("@swapkit/toolboxes/cardano");
+  const { HARDENED, Networks } = ledgerModule;
+  const accountPath = [purpose + HARDENED, coinType + HARDENED, account + HARDENED];
+  const paymentPath = [...accountPath, 0, index];
+  const stakingPath = [...accountPath, 2, 0];
+
+  function runCardanoOperation<Output>({
+    operation,
+    requiredUserInteraction,
+  }: {
+    operation: (app: Ada) => Promise<Output>;
+    requiredUserInteraction?: UserInteractionRequired;
+  }) {
+    return runLedgerJsOperation({
+      appName: "Cardano ADA",
+      connection,
+      // Named export: the package is CommonJS only, so `default` is `module.exports` under Node ESM.
+      createApp: (ledgerTransport) => new ledgerModule.Ada(ledgerTransport),
+      operation,
+      requiredUserInteraction,
+    });
+  }
+
+  function toPublicKey(key: ExtendedPublicKey | undefined) {
+    const publicKey = Buffer.from(key?.publicKeyHex ?? "", "hex");
+    if (publicKey.length !== 32) {
+      throw new SwapKitError("wallet_ledger_failed_to_get_address", { chain: Chain.Cardano, derivationPath: path });
+    }
+    return publicKey;
+  }
+
+  const keys = await runCardanoOperation({
+    operation: (app) => app.getExtendedPublicKeys({ paths: [paymentPath, stakingPath] }),
+  });
+  const paymentKey = toPublicKey(keys[0]);
+  const stakingKey = toPublicKey(keys[1]);
+
+  const publicKeyHash = await getCardanoPublicKeyHash(paymentKey);
+  const address = await getCardanoAddressFromBytes(
+    Buffer.concat([
+      Buffer.from([Networks.Mainnet.networkId]),
+      publicKeyHash,
+      await getCardanoPublicKeyHash(stakingKey),
+    ]),
+  );
+
+  async function signTransaction(txHex: string) {
+    const request = await toLedgerCardanoTransaction(txHex, { address, paymentPath, stakingPath }, ledgerModule);
+    const result = await runCardanoOperation({
+      operation: (app) => app.signTransaction(request),
+      requiredUserInteraction: LEDGER_USER_INTERACTION_REQUIRED.SignTransaction,
+    });
+
+    return addLedgerWitnesses(txHex, result, { paymentPath, publicKey: paymentKey });
+  }
+
+  return { getAddress: () => address, publicKey: paymentKey, publicKeyHash, signTransaction };
+}

package/src/ledger/clients/evm.ts

@@ -316,6 +316,10 @@ export function PolygonLedger(params: LedgerParams) {
   return new EVMLedgerInterface({ ...params, chainId: ChainId.Polygon });
 }
 
+export function RobinhoodLedger(params: LedgerParams) {
+  return new EVMLedgerInterface({ ...params, chainId: ChainId.Robinhood });
+}
+
 export function BinanceSmartChainLedger(params: LedgerParams) {
   return new EVMLedgerInterface({ ...params, chainId: ChainId.BinanceSmartChain });
 }

package/src/ledger/clients/stellar.ts

@@ -0,0 +1,83 @@
+import type { UserInteractionRequired } from "@ledgerhq/device-management-kit";
+import type Str from "@ledgerhq/hw-app-str";
+import type Transport from "@ledgerhq/hw-transport";
+import {
+  Chain,
+  type DerivationPathArray,
+  derivationPathToString,
+  NetworkDerivationPath,
+  SwapKitError,
+} from "@swapkit/helpers";
+import type { StellarSigner, StellarTransaction } from "@swapkit/toolboxes/stellar";
+
+import {
+  LEDGER_USER_INTERACTION_REQUIRED,
+  type LedgerJsClientParams,
+  normalizeLedgerJsClientParams,
+  runLedgerJsOperation,
+} from "../helpers/ledgerJsDmkBridge";
+
+type StellarLedgerParams = LedgerJsClientParams<DerivationPathArray>;
+
+// The Stellar app derives accounts from m/44'/148'/x' only, like Trezor and the SwapKit keystore.
+export function getStellarLedgerPath(derivationPath: DerivationPathArray) {
+  const [purpose, coinType, account, change, index] = derivationPath;
+  if (purpose !== 44 || coinType !== 148 || account === undefined || change || index) {
+    throw new SwapKitError("wallet_ledger_derivation_path_error", {
+      chain: Chain.Stellar,
+      derivationPath,
+      reason: "Stellar only uses m/44'/148'/x'",
+    });
+  }
+
+  // hw-app-str hardens every segment, so a leading "m" would become "m'" and fail to parse.
+  return derivationPathToString([purpose, coinType, account]).replace(/^m\//, "");
+}
+
+export async function StellarLedger(paramsOrPath?: StellarLedgerParams | DerivationPathArray, transport?: Transport) {
+  const { derivationPath, ...connection } = normalizeLedgerJsClientParams({ paramsOrPath, transport });
+  const path = getStellarLedgerPath(derivationPath || NetworkDerivationPath[Chain.Stellar]);
+
+  async function runStellarOperation<Output>({
+    operation,
+    requiredUserInteraction,
+  }: {
+    operation: (app: Str) => Promise<Output>;
+    requiredUserInteraction?: UserInteractionRequired;
+  }) {
+    const StrApp = (await import("@ledgerhq/hw-app-str")).default;
+    return runLedgerJsOperation({
+      appName: "Stellar",
+      connection,
+      createApp: (ledgerTransport) => new StrApp(ledgerTransport),
+      operation,
+      requiredUserInteraction,
+    });
+  }
+
+  const [{ rawPublicKey }, { StrKey }] = await Promise.all([
+    runStellarOperation({ operation: (app) => app.getPublicKey(path) }),
+    import("@stellar/stellar-sdk"),
+  ]);
+  const address = StrKey.encodeEd25519PublicKey(rawPublicKey);
+
+  // The device parses the signature base itself, so it displays and signs the transaction exactly as received.
+  async function signTransaction(transaction: StellarTransaction) {
+    const { signature } = await runStellarOperation({
+      operation: (app) => app.signTransaction(path, transaction.signatureBase()),
+      requiredUserInteraction: LEDGER_USER_INTERACTION_REQUIRED.SignTransaction,
+    });
+
+    try {
+      transaction.addSignature(address, signature.toString("base64"));
+    } catch (error) {
+      throw new SwapKitError("wallet_ledger_invalid_signature", { chain: Chain.Stellar, error });
+    }
+
+    return transaction;
+  }
+
+  return { getAddress: () => address, publicKey: rawPublicKey, signTransaction } satisfies StellarSigner & {
+    publicKey: Buffer;
+  };
+}

package/src/ledger/clients/ton.ts

@@ -0,0 +1,282 @@
+import type { UserInteractionRequired } from "@ledgerhq/device-management-kit";
+import type Transport from "@ledgerhq/hw-transport";
+import {
+  Chain,
+  type DerivationPathArray,
+  getRPCUrl,
+  NetworkDerivationPath,
+  SwapKitError,
+  WalletOption,
+} from "@swapkit/helpers";
+import type { TONTransactionInput, TONTransactionMessage } from "@swapkit/toolboxes/ton";
+import type { Address, Cell, MessageRelaxed, StateInit } from "@ton/core";
+import type { TonClient } from "@ton/ton";
+import type { TonPayloadFormat, TonTransport } from "@ton-community/ton-ledger";
+
+import {
+  LEDGER_USER_INTERACTION_REQUIRED,
+  type LedgerJsClientParams,
+  normalizeLedgerJsClientParams,
+  runLedgerJsOperation,
+} from "../helpers/ledgerJsDmkBridge";
+
+// SendMode.PAY_GAS_SEPARATELY + SendMode.IGNORE_ERRORS, the TON toolbox default.
+const DEFAULT_SEND_MODE = 3;
+const TRANSACTION_VALID_SECONDS = 300;
+const TON_WORKCHAIN = 0;
+
+type TONLedgerParams = LedgerJsClientParams<DerivationPathArray>;
+
+interface TONLedgerOrder {
+  amount: bigint;
+  bounce: boolean;
+  payload?: Cell;
+  payloadFormat?: TonPayloadFormat;
+  stateInit?: StateInit;
+  to: Address;
+}
+
+interface SignedTransferExpectation extends TONLedgerOrder {
+  sendMode: number;
+  seqno: number;
+  timeout: number;
+  walletId: number;
+}
+
+function toLedgerPath(derivationPath: DerivationPathArray) {
+  const [purpose, coinType, network, workchain, account, ...rest] = derivationPath;
+  const isTonPath =
+    purpose === 44 &&
+    coinType === 607 &&
+    network === 0 &&
+    workchain === 0 &&
+    typeof account === "number" &&
+    Number.isInteger(account) &&
+    account >= 0 &&
+    rest.length === 0;
+
+  if (!isTonPath) {
+    throw new SwapKitError({
+      errorKey: "wallet_ledger_derivation_path_error",
+      info: { derivationPath, reason: "Ledger TON accounts derive from m/44'/607'/0'/0'/{account}'" },
+    });
+  }
+
+  return [44, 607, 0, 0, account, 0];
+}
+
+function invalidParams(reason: string, info: Record<string, unknown> = {}) {
+  return new SwapKitError({
+    errorKey: "wallet_ledger_invalid_params",
+    info: { ...info, reason, wallet: WalletOption.LEDGER },
+  });
+}
+
+function resolveSingleMessage(input: TONTransactionInput) {
+  const messages = Array.isArray(input) ? input : input.messages;
+  const [message] = messages;
+
+  if (!message) throw invalidParams("A TON transaction needs one message");
+  if (messages.length > 1) {
+    throw new SwapKitError({
+      errorKey: "wallet_ledger_method_not_supported",
+      info: {
+        messageCount: messages.length,
+        method: "signTransaction",
+        reason: "Ledger signs one TON message per transaction",
+        wallet: WalletOption.LEDGER,
+      },
+    });
+  }
+
+  const sendMode =
+    (Array.isArray(input) ? message.sendMode : (input.sendMode ?? message.sendMode)) ?? DEFAULT_SEND_MODE;
+  if (!Array.isArray(input) && message.sendMode !== undefined && message.sendMode !== sendMode) {
+    throw invalidParams("The message send mode differs from the transaction send mode", {
+      messageSendMode: message.sendMode,
+      sendMode,
+    });
+  }
+
+  if (!Number.isInteger(sendMode) || sendMode < 0 || sendMode > 255) {
+    throw invalidParams("The TON send mode must be an integer between 0 and 255", { sendMode });
+  }
+
+  return { message, sendMode };
+}
+
+async function toLedgerOrder(message: TONTransactionMessage): Promise<TONLedgerOrder> {
+  const [{ Address, Cell, loadStateInit }, { parseMessage }] = await Promise.all([
+    import("@ton/core"),
+    import("@ton-community/ton-ledger"),
+  ]);
+
+  if (!/^\d+$/.test(message.amount)) {
+    throw invalidParams("The TON amount must be an integer number of nanotons", { amount: message.amount });
+  }
+  const amount = BigInt(message.amount);
+
+  let to: Address;
+  try {
+    to = Address.parse(message.address);
+  } catch {
+    throw invalidParams("Invalid TON destination address", { address: message.address });
+  }
+  // Raw `0:<hex>` destinations default to bounceable, the toolbox convention; friendly ones carry their own flag.
+  const bounce = Address.isFriendly(message.address) ? Address.parseFriendly(message.address).isBounceable : true;
+
+  let stateInit: StateInit | undefined;
+  if (message.stateInit !== undefined) {
+    try {
+      stateInit = loadStateInit(Cell.fromBase64(message.stateInit).beginParse());
+    } catch {
+      throw invalidParams("The TON state init is not a valid BOC", { stateInit: message.stateInit });
+    }
+  }
+
+  let payload: Cell | undefined;
+  if (message.payload !== undefined) {
+    try {
+      payload = Cell.fromBase64(message.payload);
+    } catch {
+      throw invalidParams("The TON payload is not a valid BOC", { payload: message.payload });
+    }
+  }
+
+  // A payload the app cannot display is kept as the untouched `unsafe` cell, which the device signs blind or refuses.
+  const payloadFormat = payload ? parseMessage(payload, { disallowModification: true }) : undefined;
+
+  return { amount, bounce, payload, payloadFormat, stateInit, to };
+}
+
+function sameCell(a: Cell | null | undefined, b: Cell | null | undefined) {
+  return a && b ? a.hash().equals(b.hash()) : a == null && b == null;
+}
+
+function sameStateInit(signed: StateInit | null | undefined, requested: StateInit | undefined) {
+  if (!(signed && requested)) return signed == null && requested == null;
+  return sameCell(signed.code, requested.code) && sameCell(signed.data, requested.data);
+}
+
+// The library re-encodes structured payloads before the device signs them, so the body it returns is only
+// broadcast when the signed order is the requested one.
+async function assertSignedTransfer(body: Cell, expected: SignedTransferExpectation) {
+  const { Cell, loadMessageRelaxed } = await import("@ton/core");
+
+  let signed: { walletId: number; timeout: number; seqno: number; sendMode: number; order: MessageRelaxed };
+  try {
+    const transfer = body.beginParse().skip(512);
+    const walletId = transfer.loadUint(32);
+    const timeout = transfer.loadUint(32);
+    const seqno = transfer.loadUint(32);
+    transfer.skip(8);
+    const sendMode = transfer.loadUint(8);
+    const order = loadMessageRelaxed(transfer.loadRef().beginParse());
+    transfer.endParse();
+    signed = { order, sendMode, seqno, timeout, walletId };
+  } catch (error) {
+    throw new SwapKitError(
+      { errorKey: "wallet_ledger_signing_error", info: { reason: "Unreadable signed TON transfer" } },
+      error,
+    );
+  }
+
+  const { order } = signed;
+  const matches =
+    signed.walletId === expected.walletId &&
+    signed.timeout === expected.timeout &&
+    signed.seqno === expected.seqno &&
+    signed.sendMode === expected.sendMode &&
+    order.info.type === "internal" &&
+    order.info.dest.equals(expected.to) &&
+    order.info.value.coins === expected.amount &&
+    order.info.bounce === expected.bounce &&
+    order.body.hash().equals((expected.payload ?? Cell.EMPTY).hash()) &&
+    sameStateInit(order.init, expected.stateInit);
+  if (!matches) {
+    throw new SwapKitError({
+      errorKey: "wallet_ledger_signing_error",
+      info: { reason: "The signed TON transfer does not match the requested message" },
+    });
+  }
+}
+
+export async function TONLedger(paramsOrPath?: TONLedgerParams | DerivationPathArray, transport?: Transport) {
+  const { derivationPath, ...connection } = normalizeLedgerJsClientParams({ paramsOrPath, transport });
+  const path = toLedgerPath(derivationPath || NetworkDerivationPath[Chain.Ton]);
+
+  async function runTonOperation<Output>({
+    operation,
+    requiredUserInteraction,
+  }: {
+    operation: (app: TonTransport) => Promise<Output>;
+    requiredUserInteraction?: UserInteractionRequired;
+  }) {
+    const { TonTransport } = await import("@ton-community/ton-ledger");
+    return runLedgerJsOperation({
+      appName: "TON",
+      connection,
+      createApp: (ledgerTransport) => new TonTransport(ledgerTransport),
+      operation,
+      requiredUserInteraction,
+    });
+  }
+
+  const [{ Address }, { WalletContractV4 }] = await Promise.all([import("@ton/core"), import("@ton/ton")]);
+  const { address: deviceAddress, publicKey } = await runTonOperation({
+    operation: (app) =>
+      app.getAddress(path, { bounceable: false, chain: TON_WORKCHAIN, testOnly: false, walletVersion: "v4" }),
+  });
+
+  const wallet = WalletContractV4.create({ publicKey, workchain: TON_WORKCHAIN });
+  if (!wallet.address.equals(Address.parse(deviceAddress))) {
+    throw new SwapKitError({
+      errorKey: "wallet_ledger_failed_to_get_address",
+      info: { deviceAddress, reason: "The Ledger TON address is not the wallet v4 address of its public key" },
+    });
+  }
+  const address = wallet.address.toString({ bounceable: false, urlSafe: true });
+
+  let client: TonClient | undefined;
+  async function getWalletState() {
+    if (!client) {
+      const { TonClient } = await import("@ton/ton");
+      client = new TonClient({ endpoint: await getRPCUrl(Chain.Ton) });
+    }
+    const { state } = await client.getContractState(wallet.address);
+    const deployed = state === "active";
+    const seqno = deployed ? await client.open(wallet).getSeqno() : 0;
+
+    return { deployed, seqno };
+  }
+
+  async function signTransaction(input: TONTransactionInput): Promise<Cell> {
+    const { message, sendMode } = resolveSingleMessage(input);
+    const order = await toLedgerOrder(message);
+    const { deployed, seqno } = await getWalletState();
+    const timeout = Math.floor(Date.now() / 1000) + TRANSACTION_VALID_SECONDS;
+
+    const body = await runTonOperation({
+      operation: (app) =>
+        app.signTransaction(path, {
+          amount: order.amount,
+          bounce: order.bounce,
+          payload: order.payloadFormat,
+          sendMode,
+          seqno,
+          stateInit: order.stateInit,
+          timeout,
+          to: order.to,
+        }),
+      requiredUserInteraction: LEDGER_USER_INTERACTION_REQUIRED.SignTransaction,
+    });
+    await assertSignedTransfer(body, { ...order, sendMode, seqno, timeout, walletId: wallet.walletId });
+
+    const { beginCell, external, storeMessage } = await import("@ton/core");
+    return beginCell()
+      .store(storeMessage(external({ body, init: deployed ? undefined : wallet.init, to: wallet.address })))
+      .endCell();
+  }
+
+  return { getAddress: () => address, publicKey, signTransaction };
+}

package/src/ledger/clients/zcash.ts

@@ -22,7 +22,7 @@ import { executeLedgerDeviceAction, type LedgerDeviceActionStateHandler } from "
 import { runLedgerJsOperation } from "../helpers/ledgerJsDmkBridge";
 import { ZcashLedger as LegacyZcashLedger } from "./utxo";
 
-// @swapkit/utxo-signer 3.1.0 exports only the Ironwood activation height.
+// @swapkit/utxo-signer exports no NU6.2 activation height.
 const NU6_2_ACTIVATION_HEIGHT = 3_364_600;
 
 interface ZcashLedgerParams {
@@ -74,6 +74,11 @@ function parseZcashPath(path: DerivationPathArray | string): ParsedZcashPath {
   return { account, accountPath, fullPath: `${accountPath}/${match[2] ?? 0}/${match[3] ?? 0}` };
 }
 
+function deviceChangePath(path: DerivationPathArray | string) {
+  const { fullPath } = parseZcashPath(path);
+  return fullPath.split("/")[3] === "1" ? fullPath : undefined;
+}
+
 function uint32LE(value: number) {
   const bytes = new Uint8Array(4);
   new DataView(bytes.buffer).setUint32(0, value >>> 0, true);
@@ -161,8 +166,7 @@ function parsePreviousTransaction({ bytes, version }: { bytes: Uint8Array; versi
   return { ...transparentFields, extraData: reader.rest(), locktime, nExpiryHeight };
 }
 
-// Either byte order binds a txid equally: toolbox-built transactions keep display-order txids, while
-// ZcashTransaction.fromBytes keeps them in wire order.
+// Either byte order binds a txid equally: utxo-signer below 3.2 parsed raw transactions with wire-order txids.
 function matchesTxid({ hash, txid }: { hash: string; txid: Uint8Array }) {
   const normalized = hash.toLowerCase();
   return normalized === hex.encode(txid) || normalized === hex.encode(txid.slice().reverse());
@@ -178,17 +182,21 @@ async function serializeOutputs(tx: ZcashTransaction) {
 }
 
 async function activationHeight(consensusBranchId: number) {
-  const { ZCASH_IRONWOOD_ACTIVATION_HEIGHT, ZcashConsensusBranchId } = await import("@swapkit/utxo-signer");
+  const { ZCASH_IRONWOOD_ACTIVATION_HEIGHT, ZCASH_NU7_ACTIVATION_HEIGHT, ZcashConsensusBranchId } = await import(
+    "@swapkit/utxo-signer"
+  );
 
   switch (consensusBranchId) {
     case ZcashConsensusBranchId.NU6_2:
       return NU6_2_ACTIVATION_HEIGHT;
     case ZcashConsensusBranchId.IRONWOOD:
       return ZCASH_IRONWOOD_ACTIVATION_HEIGHT;
+    case ZcashConsensusBranchId.NU7:
+      return ZCASH_NU7_ACTIVATION_HEIGHT;
     default:
       throw new SwapKitError("wallet_ledger_invalid_params", {
         consensusBranchId,
-        reason: "Ledger Zcash DSK signing supports NU6.2 and Ironwood target branches",
+        reason: "Ledger Zcash DSK signing supports NU6.2, Ironwood and NU7 target branches",
       });
   }
 }
@@ -394,6 +402,8 @@ export function ZcashLedger({
           utxo.index,
           null,
           tx.getInput(inputIndex).sequence ?? 0xffffffff,
+          // Frames a v4 previous transaction with this branch id; unset, the kit assumes the latest upgrade
+          blockHeight,
         ],
       ),
     );
@@ -401,7 +411,7 @@ export function ZcashLedger({
       additionals: ["zcash", "sapling"],
       associatedKeysets: paths,
       blockHeight,
-      changePath: changePath ? parseZcashPath(changePath).fullPath : configuredPath.fullPath,
+      changePath: deviceChangePath(changePath ?? configuredPath.fullPath),
       expiryHeight: uint32LE(tx.expiryHeight),
       inputs,
       lockTime: tx.lockTime,