@onekeyfe/hd-core 1.2.0-alpha.16 → 1.2.0-alpha.18

package/src/api/GetPassphraseState.ts

@@ -19,10 +19,13 @@ export default class GetPassphraseState extends BaseMethod {
 
     const passphraseProtection = this.device.getCurrentPassphraseProtection();
     const deviceType = this.device.getCurrentDeviceType();
-    const isProSeries = deviceType === EDeviceType.Pro || deviceType === EDeviceType.Pro2;
+
+    if (deviceType === EDeviceType.Pro2) {
+      return Promise.resolve(passphraseProtection === true ? passphraseState : undefined);
+    }
 
     return Promise.resolve(
-      isProSeries || passphraseProtection === true ? passphraseState : undefined
+      deviceType === EDeviceType.Pro || passphraseProtection === true ? passphraseState : undefined
     );
   }
 }

package/src/api/UploadPortfolio.ts

@@ -25,6 +25,8 @@ export default class UploadPortfolio extends FileWrite {
     };
     super.init();
     this.unlockPolicy = 'retry-on-locked';
+    // Portfolio 是后台数据写入与应用流程，设备不需要用户确认；包括自动解锁阶段在内均不合成 UI Event。
+    this.protocolV2UiMode = 'none';
   }
 
   async run() {

package/src/api/device/DeviceCancel.ts

@@ -5,6 +5,7 @@ import type { Cancel } from '@onekeyfe/hd-transport';
 export default class DeviceCancel extends BaseMethod<Cancel> {
   init() {
     this.useDevicePassphraseState = false;
+    this.unlockPolicy = 'none';
   }
 
   async run() {

package/src/api/device/DeviceChangePin.ts

@@ -1,5 +1,8 @@
+import { DeviceSettingsPage } from '@onekeyfe/hd-transport';
+
 import { BaseMethod } from '../BaseMethod';
 import { validateParams } from '../helpers/paramsValidator';
+import { invalidParameter } from '../helpers/filesystemValidation';
 
 import type { ChangePin } from '@onekeyfe/hd-transport';
 
@@ -13,9 +16,29 @@ export default class DeviceChangePin extends BaseMethod<ChangePin> {
     this.params = {
       remove: this.payload.remove,
     };
+    this.protocolV2UiInteraction = {
+      request: 'button',
+      source: 'method-lifecycle',
+      reason: 'change-pin',
+      completion: 'operation-completed',
+      deviceOnly: true,
+      page: DeviceSettingsPage.DevicePinChange,
+    };
   }
 
   async run() {
+    if (this.device.isProtocolV2()) {
+      if (this.params.remove) {
+        throw invalidParameter(
+          'Parameter [remove=true] is not supported by the Pro2 device PIN page.'
+        );
+      }
+      const res = await this.device.commands.typedCall('DeviceSettingsPageShow', 'Success', {
+        page: DeviceSettingsPage.DevicePinChange,
+      });
+      return Promise.resolve(res.message);
+    }
+
     const res = await this.device.commands.typedCall('ChangePin', 'Success', {
       ...this.params,
     });

package/src/api/device/DeviceLock.ts

@@ -5,6 +5,7 @@ import type { LockDevice } from '@onekeyfe/hd-transport';
 export default class DeviceLock extends BaseMethod<LockDevice> {
   init() {
     this.useDevicePassphraseState = false;
+    this.unlockPolicy = 'none';
   }
 
   async run() {

package/src/api/device/DeviceUnlock.ts

@@ -5,6 +5,15 @@ import type { LockDevice } from '@onekeyfe/hd-transport';
 export default class DeviceUnlock extends BaseMethod<LockDevice> {
   init() {
     this.useDevicePassphraseState = false;
+    this.unlockPolicy = 'none';
+    this.protocolV2UiInteraction = {
+      request: 'pin',
+      source: 'method-lifecycle',
+      reason: 'device-unlock',
+      completion: 'operation-completed',
+      deviceOnly: true,
+      operation: 'unlock-device',
+    };
   }
 
   async run() {

package/src/api/device/DeviceWipe.ts

@@ -1,3 +1,5 @@
+import { DeviceSettingsPage } from '@onekeyfe/hd-transport';
+
 import { BaseMethod } from '../BaseMethod';
 
 import type { WipeDevice } from '@onekeyfe/hd-transport';
@@ -5,9 +7,25 @@ import type { WipeDevice } from '@onekeyfe/hd-transport';
 export default class DeviceWipe extends BaseMethod<WipeDevice> {
   init() {
     this.useDevicePassphraseState = false;
+    this.protocolV2UiInteraction = {
+      request: 'button',
+      source: 'method-lifecycle',
+      reason: 'device-management',
+      completion: 'operation-completed',
+      deviceOnly: true,
+      page: DeviceSettingsPage.DeviceReset,
+      operation: 'wipe-device',
+    };
   }
 
   async run() {
+    if (this.device.isProtocolV2()) {
+      const res = await this.device.commands.typedCall('DeviceSettingsPageShow', 'Success', {
+        page: DeviceSettingsPage.DeviceReset,
+      });
+      return Promise.resolve(res.message);
+    }
+
     const res = await this.device.commands.typedCall('WipeDevice', 'Success');
 
     return Promise.resolve(res.message);

package/src/api/helpers/protocolV2FileWrite.ts

@@ -30,12 +30,23 @@ export type ProtocolV2FileWriteOptions = {
   append?: boolean;
   uiPercentage?: number;
   timeoutMs?: number;
+  maxChunkRetries?: number;
   throwIfAborted?: () => void;
   onProgress?: (progress: ProtocolV2FileWriteProgress) => void;
 };
 
 const MIN_FILE_CHUNK_SIZE = 64;
 
+function isRetryableFileWriteTimeout(error: unknown) {
+  if (!error || typeof error !== 'object') return false;
+  const candidate = error as { errorCode?: number; code?: number; message?: string };
+  const code = candidate.errorCode ?? candidate.code;
+  return (
+    code === HardwareErrorCode.BleTimeoutError ||
+    /Lowlevel response timeout/i.test(candidate.message ?? '')
+  );
+}
+
 function getProtocolV2FileChunkLimit() {
   const env = DataManager.getSettings('env');
   return env && DataManager.isBleConnect(env)
@@ -116,17 +127,30 @@ export async function writeProtocolV2File(options: ProtocolV2FileWriteOptions) {
     const progress =
       options.uiPercentage ??
       getDeviceTransferProgress(offset, offset + chunk.byteLength, totalSize);
-    const response = await options.commands.typedCall(
-      'FilesystemFileWrite',
-      'FilesystemFile',
-      {
-        file: { path: options.path, offset, total_size: totalSize, data: chunk },
-        overwrite: chunks === 0 ? options.overwrite ?? false : false,
-        append: options.append ?? false,
-        ui_percentage: progress,
-      },
-      { timeoutMs: options.timeoutMs }
-    );
+    const request = {
+      file: { path: options.path, offset, total_size: totalSize, data: chunk },
+      overwrite: chunks === 0 ? options.overwrite ?? false : false,
+      append: options.append ?? false,
+      ui_percentage: progress,
+    };
+    const maxChunkRetries = Math.max(Math.floor(options.maxChunkRetries ?? 0), 0);
+    let retryCount = 0;
+    let response;
+    while (true) {
+      try {
+        response = await options.commands.typedCall(
+          'FilesystemFileWrite',
+          'FilesystemFile',
+          request,
+          { timeoutMs: options.timeoutMs }
+        );
+        break;
+      } catch (error) {
+        if (retryCount >= maxChunkRetries || !isRetryableFileWriteTimeout(error)) throw error;
+        retryCount += 1;
+        options.throwIfAborted?.();
+      }
+    }
     options.throwIfAborted?.();
     lastMessage = response.message;
     const rawProcessedByte = response.message?.processed_byte;

package/src/api/index.ts

@@ -50,7 +50,7 @@ export { default as deviceReboot } from './protocol-v2/DeviceReboot';
 export { default as deviceInfoGet } from './protocol-v2/DeviceInfoGet';
 export { default as deviceStatusGet } from './protocol-v2/DeviceStatusGet';
 export { default as deviceGetOnboardingStatus } from './protocol-v2/DeviceGetOnboardingStatus';
-export { default as deviceSessionGet } from './protocol-v2/DeviceSessionGet';
+export { default as deviceSessionOpen } from './protocol-v2/DeviceSessionOpen';
 export { default as deviceFirmwareUpdate } from './protocol-v2/DeviceFirmwareUpdate';
 export { default as deviceGetFirmwareUpdateStatus } from './protocol-v2/DeviceGetFirmwareUpdateStatus';
 export { default as deviceFactoryInfoSet } from './protocol-v2/DeviceFactoryInfoSet';

package/src/api/kaspa/KaspaSignTransaction.ts

@@ -1,4 +1,5 @@
 import { bytesToHex } from '@noble/hashes/utils';
+import { ERRORS, HardwareError, HardwareErrorCode } from '@onekeyfe/hd-shared';
 
 import { UI_REQUEST } from '../../constants/ui-request';
 import { validatePath } from '../helpers/pathUtils';
@@ -14,11 +15,27 @@ import type {
   KaspaSignTransactionParams,
   KaspaSignature,
 } from '../../types';
-import type { TypedCall } from '@onekeyfe/hd-transport';
+import type {
+  KaspaInputScriptType,
+  KaspaTxRequest,
+  KaspaTxRequestSignature,
+  TypedCall,
+} from '@onekeyfe/hd-transport';
+
+// Streaming only handles plain P2PK scripts; anything else (e.g. KRC20 P2SH)
+// must blind-sign. Absent script means a streaming-only caller.
+const P2PK_SCRIPT = /^(20[0-9a-f]{64}ac|21[0-9a-f]{66}ab)$/i;
+
+const isStreamableScript = (script?: string) => !script || P2PK_SCRIPT.test(script);
 
 export default class KaspaSignTransaction extends BaseMethod<KaspaSignTransactionParams> {
   hasBundle = false;
 
+  // Protocols this tx can be signed with; the device picks via its first response.
+  supportsLegacy = false;
+
+  supportsStreaming = false;
+
   init() {
     this.checkDeviceId = true;
     this.allowDeviceMode = [...this.allowDeviceMode, UI_REQUEST.NOT_INITIALIZE];
@@ -29,17 +46,17 @@ export default class KaspaSignTransaction extends BaseMethod<KaspaSignTransactio
     // check payload
     validateParams(payload, [
       { name: 'version', type: 'number' },
-      { name: 'sigHashType', type: 'number', required: true },
+      { name: 'sigHashType', type: 'number' },
       { name: 'inputs', type: 'array', required: true },
       { name: 'outputs', type: 'array', required: true },
       { name: 'lockTime', required: true },
       { name: 'sigOpCount', type: 'number' },
       { name: 'subNetworkID', type: 'string' },
+      { name: 'payload', type: 'hexString' },
+      { name: 'refTxs', type: 'array', allowEmpty: true },
       { name: 'useTweak', type: 'boolean' },
     ]);
 
-    // if(!payload.inputs.length) throw
-
     const inputs: KaspaSignInputParams[] = payload.inputs.map(input => {
       validateParams(input, [
         { name: 'path', type: 'string', required: true },
@@ -47,6 +64,7 @@ export default class KaspaSignTransaction extends BaseMethod<KaspaSignTransactio
         { name: 'outputIndex', type: 'number', required: true },
         { name: 'sequenceNumber', required: true },
       ]);
+      validateParams(input.output, [{ name: 'satoshis', required: true }]);
 
       const addressN = validatePath(input.path, 3);
 
@@ -57,15 +75,28 @@ export default class KaspaSignTransaction extends BaseMethod<KaspaSignTransactio
       };
     });
 
+    payload.refTxs?.forEach(refTx => {
+      validateParams(refTx, [
+        { name: 'txId', type: 'string', required: true },
+        { name: 'version', type: 'number', required: true },
+        // Coinbase transactions legitimately have zero inputs.
+        { name: 'inputs', type: 'array', required: true, allowEmpty: true },
+        { name: 'outputs', type: 'array', required: true, allowEmpty: true },
+        { name: 'payload', type: 'hexString' },
+      ]);
+    });
+
     const outputs: KaspaSignOutputParams[] = payload.outputs.map(output => {
       validateParams(output, [
         { name: 'satoshis', required: true },
-        { name: 'script', type: 'string', required: true },
+        { name: 'address', type: 'string' },
+        { name: 'script', type: 'string' },
         { name: 'scriptVersion', type: 'number' },
       ]);
 
       return {
         ...output,
+        addressN: output.addressN ? validatePath(output.addressN, 3) : undefined,
         scriptVersion: output.scriptVersion ?? 0,
       };
     });
@@ -80,8 +111,37 @@ export default class KaspaSignTransaction extends BaseMethod<KaspaSignTransactio
       sigHashType: payload.sigHashType ?? SignatureType.SIGHASH_ALL | SignatureType.SIGHASH_FORKID,
       sigOpCount: payload.sigOpCount ?? 1,
       subNetworkID: payload.subNetworkID ?? bytesToHex(zeroSubnetworkID()),
+      gas: payload.gas ?? 0,
       useTweak: payload.useTweak,
     };
+
+    // Legacy prehashes on the host with payload/gas/subnetworkID hardcoded to
+    // zero (TransferSerialize), so those rule it out.
+    this.supportsLegacy =
+      this.params.outputs.every(output => !!output.script) &&
+      this.params.inputs.every(input => !!input.output.script) &&
+      !this.params.payload &&
+      Number(this.params.gas ?? 0) === 0 &&
+      /^0*$/.test(this.params.subNetworkID ?? '');
+
+    // The streaming protocol has no sighash-type field (device signs SIGHASH_ALL).
+    const isDefaultSigHashType =
+      this.params.sigHashType === SignatureType.SIGHASH_ALL ||
+      // eslint-disable-next-line no-bitwise
+      this.params.sigHashType === (SignatureType.SIGHASH_ALL | SignatureType.SIGHASH_FORKID);
+
+    this.supportsStreaming =
+      isDefaultSigHashType &&
+      this.params.outputs.every(output => !!output.address || !!output.addressN) &&
+      this.params.inputs.every(input => isStreamableScript(input.output.script)) &&
+      this.params.outputs.every(output => isStreamableScript(output.script));
+
+    if (!this.supportsLegacy && !this.supportsStreaming) {
+      throw ERRORS.TypedError(
+        HardwareErrorCode.CallMethodInvalidParameter,
+        'KaspaSignTransaction: outputs require either address/addressN (streaming protocol) or script (legacy protocol)'
+      );
+    }
   }
 
   getVersionRange() {
@@ -106,6 +166,10 @@ export default class KaspaSignTransaction extends BaseMethod<KaspaSignTransactio
     };
   }
 
+  /**
+   * Legacy blind-sign flow: run() sent input 0's prehash in raw_message; feed
+   * each next prehash via KaspaTxInputAck until KaspaSignedTx.
+   */
   async processTxRequest(
     typedCall: TypedCall,
     res: TypedResponseMessage<'KaspaTxInputRequest'> | TypedResponseMessage<'KaspaSignedTx'>,
@@ -136,7 +200,6 @@ export default class KaspaSignTransaction extends BaseMethod<KaspaSignTransactio
         'KaspaTxInputAck',
         ['KaspaTxInputRequest', 'KaspaSignedTx'],
         {
-          // params.inputs 的 path 可能是字符串或已解析数组，统一归一为 address_n 数组
           address_n: validatePath(input.path, 3),
           raw_message: bytesToHex(rawMessage),
         }
@@ -148,6 +211,190 @@ export default class KaspaSignTransaction extends BaseMethod<KaspaSignTransactio
     return signature;
   }
 
+  /**
+   * Answer a previous-transaction request (selected by prev_tx_id) from
+   * refTxs; the device uses them to verify input amounts.
+   */
+  async ackPrevRequest(typedCall: TypedCall, request: KaspaTxRequest, requestIndex: number) {
+    const prevTxId = (request.prev_tx_id ?? '').toLowerCase();
+    const refTx = (this.params.refTxs ?? []).find(tx => tx.txId.toLowerCase() === prevTxId);
+    if (!refTx) {
+      throw ERRORS.TypedError(
+        HardwareErrorCode.CallMethodInvalidParameter,
+        `KaspaSignTransaction: device requested previous transaction ${
+          prevTxId || '(unknown)'
+        }; provide it via refTxs`
+      );
+    }
+
+    const requestType = request.request_type;
+
+    if (requestType === 'KASPA_TX_PREV_META') {
+      return typedCall('KaspaTxAckPrevMeta', 'KaspaTxRequest', {
+        version: refTx.version,
+        input_count: refTx.inputs.length,
+        output_count: refTx.outputs.length,
+        lock_time: (refTx.lockTime ?? 0) as number,
+        subnetwork_id: refTx.subNetworkID ?? bytesToHex(zeroSubnetworkID()),
+        gas: (refTx.gas ?? 0) as number,
+        payload_length: (refTx.payload ?? '').length / 2,
+      });
+    }
+
+    if (requestType === 'KASPA_TX_INPUT') {
+      const input = refTx.inputs[requestIndex];
+      if (!input) {
+        throw ERRORS.TypedError(
+          HardwareErrorCode.RuntimeError,
+          `KaspaSignTransaction: device requested input ${requestIndex} of previous tx out of range`
+        );
+      }
+      return typedCall('KaspaTxAckPrevInput', 'KaspaTxRequest', {
+        previous_outpoint: {
+          tx_id: input.prevTxId,
+          index: input.outputIndex,
+        },
+        sequence: input.sequenceNumber as number,
+      });
+    }
+
+    if (requestType === 'KASPA_TX_OUTPUT') {
+      const output = refTx.outputs[requestIndex];
+      if (!output) {
+        throw ERRORS.TypedError(
+          HardwareErrorCode.RuntimeError,
+          `KaspaSignTransaction: device requested output ${requestIndex} of previous tx out of range`
+        );
+      }
+      return typedCall('KaspaTxAckPrevOutput', 'KaspaTxRequest', {
+        amount: output.satoshis,
+        script_version: output.scriptVersion ?? 0,
+        script_public_key: output.script,
+      });
+    }
+
+    if (requestType === 'KASPA_TX_PAYLOAD') {
+      const payloadHex = refTx.payload ?? '';
+      const payloadLength = payloadHex.length / 2;
+      const length = request.request_payload_length ?? payloadLength - requestIndex;
+      return typedCall('KaspaTxAckPayloadChunk', 'KaspaTxRequest', {
+        payload_chunk: payloadHex.substring(requestIndex * 2, (requestIndex + length) * 2),
+      });
+    }
+
+    throw ERRORS.TypedError(
+      HardwareErrorCode.RuntimeError,
+      `KaspaSignTransaction: unknown previous-tx request type ${requestType ?? 'undefined'}`
+    );
+  }
+
+  /**
+   * Streaming flow (device computes the sighash): the device drives via
+   * KaspaTxRequest, asking for inputs/outputs/payload chunks and carrying
+   * finished signatures back, until FINISHED. Mirrors BTC signtx.
+   */
+  async signTxStream(
+    typedCall: TypedCall,
+    firstResponse: TypedResponseMessage<'KaspaTxRequest'>
+  ): Promise<KaspaSignature[]> {
+    const { params } = this;
+    const signatures: KaspaSignature[] = [];
+
+    const inputScriptType: KaspaInputScriptType =
+      params.scheme === 'ecdsa' ? 'KASPA_SPEND_P2PK_ECDSA' : 'KASPA_SPEND_P2PK_SCHNORR';
+
+    const saveSignature = (signature?: KaspaTxRequestSignature) => {
+      if (signature && typeof signature.signature_index === 'number' && signature.signature) {
+        signatures[signature.signature_index] = {
+          index: signature.signature_index,
+          signature: signature.signature,
+        };
+      }
+    };
+
+    const payloadHex = params.payload ?? '';
+    const payloadLength = payloadHex.length / 2;
+
+    let response = firstResponse;
+
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+      const request = response.message;
+      // Save first so the last input's signature (carried on the FINISHED request) is captured.
+      saveSignature(request.signature);
+
+      const requestType = request.request_type;
+      if (requestType === 'KASPA_TX_FINISHED') {
+        break;
+      }
+
+      const requestIndex = request.request_index ?? 0;
+
+      // prev_tx_id selects a previous-transaction request; answer from refTxs.
+      if (request.prev_tx_id || requestType === 'KASPA_TX_PREV_META') {
+        response = await this.ackPrevRequest(typedCall, request, requestIndex);
+      } else if (requestType === 'KASPA_TX_INPUT') {
+        const input = params.inputs[requestIndex];
+        if (!input) {
+          throw ERRORS.TypedError(
+            HardwareErrorCode.RuntimeError,
+            `KaspaSignTransaction: device requested input ${requestIndex} out of range`
+          );
+        }
+        response = await typedCall('KaspaTxAckInput', 'KaspaTxRequest', {
+          address_n: input.path as number[],
+          previous_outpoint: {
+            tx_id: input.prevTxId,
+            index: input.outputIndex,
+          },
+          amount: input.output.satoshis,
+          sequence: input.sequenceNumber as number,
+          sig_op_count: input.sigOpCount ?? 1,
+          script_type: inputScriptType,
+          use_tweak: params.useTweak,
+        });
+      } else if (requestType === 'KASPA_TX_OUTPUT') {
+        const output = params.outputs[requestIndex];
+        if (!output) {
+          throw ERRORS.TypedError(
+            HardwareErrorCode.RuntimeError,
+            `KaspaSignTransaction: device requested output ${requestIndex} out of range`
+          );
+        }
+        const isChange = !!output.addressN;
+        response = await typedCall('KaspaTxAckOutput', 'KaspaTxRequest', {
+          script_type: isChange ? 'KASPA_PAYTOCHANGE' : 'KASPA_PAYTOADDRESS',
+          amount: output.satoshis,
+          address_n: (output.addressN as number[]) ?? [],
+          address: output.address,
+          scheme: params.scheme,
+          use_tweak: params.useTweak,
+        });
+      } else if (requestType === 'KASPA_TX_PAYLOAD') {
+        const offset = requestIndex;
+        const length = request.request_payload_length ?? payloadLength - offset;
+        const chunk = payloadHex.substring(offset * 2, (offset + length) * 2);
+        response = await typedCall('KaspaTxAckPayloadChunk', 'KaspaTxRequest', {
+          payload_chunk: chunk,
+        });
+      } else {
+        throw ERRORS.TypedError(
+          HardwareErrorCode.RuntimeError,
+          `KaspaSignTransaction: unknown request type ${requestType ?? 'undefined'}`
+        );
+      }
+    }
+
+    const collected = signatures.filter(Boolean);
+    if (collected.length !== params.inputs.length) {
+      throw ERRORS.TypedError(
+        HardwareErrorCode.RuntimeError,
+        `KaspaSignTransaction: expected ${params.inputs.length} signatures, received ${collected.length}`
+      );
+    }
+    return collected;
+  }
+
   async run() {
     this.checkFeatureVersionLimit(
       // exists use_tweak is false check firmware version
@@ -158,25 +405,97 @@ export default class KaspaSignTransaction extends BaseMethod<KaspaSignTransactio
       }
     );
 
-    const { raw: rawMessage } = serialize(this.params, 0);
-    const input = this.params.inputs[0];
-
     const { device, params } = this;
+    const payloadHex = params.payload ?? '';
 
-    const response = await device.commands.typedCall(
-      'KaspaSignTx',
-      ['KaspaTxInputRequest', 'KaspaSignedTx'],
-      {
-        // init() 已把 path 归一为数组，这里再过一遍 validatePath 收窄类型
-        address_n: validatePath(input.path, 3),
-        raw_message: bytesToHex(rawMessage),
-        scheme: params.scheme,
-        prefix: params.prefix,
-        input_count: params.inputs.length,
-        use_tweak: params.useTweak,
+    // output_count is the protocol discriminator: attach streaming fields only
+    // when the tx can stream. Streaming verification needs refTxs, so without
+    // them prefer blind signing when available; a streaming-only tx still
+    // streams and fails clearly if the device requests previous txs.
+    const hasRefTxs = (params.refTxs?.length ?? 0) > 0;
+    const streamingReady = this.supportsStreaming && (hasRefTxs || !this.supportsLegacy);
+
+    const streamingFields = streamingReady
+      ? {
+          output_count: params.outputs.length,
+          version: params.version,
+          lock_time: params.lockTime as number,
+          subnetwork_id: params.subNetworkID,
+          gas: params.gas as number,
+          payload_length: payloadHex.length / 2,
+        }
+      : {};
+
+    // raw_message (input 0's prehash) is only computable/correct when legacy-signable.
+    const legacyFields = this.supportsLegacy
+      ? { raw_message: bytesToHex(serialize(params, 0).raw) }
+      : {};
+
+    // Legacy firmware reads raw_message and skips unknown streaming fields;
+    // new firmware streams iff output_count is present.
+    let response;
+    try {
+      response = await device.commands.typedCall(
+        'KaspaSignTx',
+        ['KaspaTxRequest', 'KaspaTxInputRequest', 'KaspaSignedTx'],
+        {
+          address_n: params.inputs[0].path as number[],
+          scheme: params.scheme,
+          prefix: params.prefix,
+          input_count: params.inputs.length,
+          use_tweak: params.useTweak,
+          ...streamingFields,
+          ...legacyFields,
+        }
+      );
+    } catch (error) {
+      // Old firmware cannot decode a packet without raw_message
+      // (Failure_DataError); map it to an actionable upgrade error.
+      if (
+        !this.supportsLegacy &&
+        error instanceof HardwareError &&
+        error.errorCode === HardwareErrorCode.RuntimeError &&
+        String(error.message).includes('Failure_DataError')
+      ) {
+        throw ERRORS.TypedError(
+          HardwareErrorCode.CallMethodNeedUpgradeFirmware,
+          'KaspaSignTransaction: this transaction requires firmware with Kaspa streaming support'
+        );
       }
-    );
+      throw error;
+    }
+
+    const typedCall = device.commands.typedCall.bind(device.commands);
+
+    if (response.type === 'KaspaTxRequest') {
+      if (!this.supportsStreaming) {
+        throw ERRORS.TypedError(
+          HardwareErrorCode.CallMethodInvalidParameter,
+          'KaspaSignTransaction: device firmware uses the streaming protocol; every output requires address or addressN'
+        );
+      }
+      try {
+        return await this.signTxStream(typedCall, response);
+      } catch (error) {
+        // Device rejected our refTxs; the caller decides whether to sign without them.
+        if (
+          error instanceof HardwareError &&
+          String(error.message).toLowerCase().includes('previous transaction id mismatch')
+        ) {
+          throw ERRORS.TypedError(HardwareErrorCode.KaspaPrevTxIdMismatch, String(error.message));
+        }
+        throw error;
+      }
+    }
+
+    // Legacy answer to a streaming-only packet: no prehash material exists.
+    if (!this.supportsLegacy) {
+      throw ERRORS.TypedError(
+        HardwareErrorCode.RuntimeError,
+        'KaspaSignTransaction: device chose the legacy protocol but the transaction is not legacy-signable'
+      );
+    }
 
-    return this.processTxRequest(device.commands.typedCall.bind(device.commands), response, 0, []);
+    return this.processTxRequest(typedCall, response, 0, []);
   }
 }