@onekeyfe/hd-core 1.2.0-alpha.2 → 1.2.0-alpha.21

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, []);
   }
 }

package/src/api/kaspa/helpers/TransferSerialize.ts

@@ -1,4 +1,6 @@
 /* eslint-disable @typescript-eslint/no-non-null-assertion */
+import { ERRORS, HardwareErrorCode } from '@onekeyfe/hd-shared';
+
 import { SignatureType } from './SignatureType';
 import { HashWriter } from './HashWriter';
 
@@ -76,6 +78,12 @@ function getSigOpCountsHash(transaction: KaspaSignTransactionParams, sighashType
 function hashTxOut(hashWriter: HashWriter, output: KaspaSignOutputParams) {
   hashWriter.writeUInt64LE(output.satoshis);
   hashWriter.writeUInt16LE(0); // TODO: USE REAL SCRIPT VERSION
+  if (output.script === undefined) {
+    throw ERRORS.TypedError(
+      HardwareErrorCode.CallMethodInvalidParameter,
+      'Kaspa legacy sighash requires output.script'
+    );
+  }
   hashWriter.writeVarBytes(Buffer.from(output.script, 'hex'));
 }
 
@@ -126,6 +134,12 @@ export function serialize(transaction: KaspaSignTransactionParams, inputNumber:
   const input = transaction.inputs[inputNumber];
   hashOutpoint(hashWriter, input);
   hashWriter.writeUInt16LE(0); // TODO: USE REAL SCRIPT VERSION
+  if (input.output.script === undefined) {
+    throw ERRORS.TypedError(
+      HardwareErrorCode.CallMethodInvalidParameter,
+      'Kaspa legacy sighash requires input.output.script'
+    );
+  }
   hashWriter.writeVarBytes(Buffer.from(input.output.script, 'hex'));
   hashWriter.writeUInt64LE(input.output.satoshis);
   hashWriter.writeUInt64LE(input.sequenceNumber);

package/src/api/nervos/NervosSignTransaction.ts

@@ -67,8 +67,8 @@ export default class NervosSignTransaction extends BaseMethod<NervosSignTx> {
     res: TypedResponseMessage<'NervosSignedTx'> | TypedResponseMessage<'NervosTxRequest'>,
     data: Buffer,
     offset = 0
-    // 设备可能在最后一个 NervosTxRequest（无 data_length）里返回签名，
-    // 该消息没有 address 字段，返回类型如实声明为联合类型
+    // The final NervosTxRequest may return a signature without data_length or address,
+    // so the result accurately uses a union type.
   ): Promise<NervosSignedTx | (NervosTxRequest & { path: string })> => {
     if (res.type === 'NervosSignedTx') {
       if (!res?.message?.signature) {

package/src/api/nexa/NexaSignTransaction.ts

@@ -73,7 +73,7 @@ export default class NexaSignTransaction extends BaseMethod<NexaSignTransactionP
       const nextIndex = res.message.request_index;
       const input = this.params.inputs[nextIndex];
       const response = await typedCall('NexaTxInputAck', ['NexaTxInputRequest', 'NexaSignedTx'], {
-        // path 为字符串形式，归一为 address_n 数组（与 run() 中首个 input 的处理一致）
+        // Normalize a string path to address_n, matching the first input handled by run().
         address_n: validatePath(input.path, 3),
         raw_message: input.message,
       });

package/src/api/protocol-v2/{FactoryGetDeviceInfo.ts → DeviceFactoryInfoGet.ts}

@@ -1,8 +1,8 @@
 import { BaseMethod } from '../BaseMethod';
 
-export default class FactoryGetDeviceInfo extends BaseMethod {
+export default class DeviceFactoryInfoGet extends BaseMethod {
   init() {
-    // Protocol V2 (Pro2) 专属方法，core 调度层统一做非 V2 设备守卫
+    // Protocol V2 (Pro2) only; Core rejects non-V2 devices.
     this.requireProtocolV2 = true;
     this.skipForceUpdateCheck = true;
     this.useDevicePassphraseState = false;
@@ -11,8 +11,8 @@ export default class FactoryGetDeviceInfo extends BaseMethod {
 
   async run() {
     const res = await this.device.commands.typedCall(
-      'FactoryGetDeviceInfo',
-      'FactoryDeviceInfo',
+      'DeviceFactoryInfoGet',
+      'DeviceFactoryInfo',
       {}
     );
     return Promise.resolve(res.message);

package/src/api/protocol-v2/DeviceFactoryInfoSet.ts

@@ -0,0 +1,32 @@
+import { BaseMethod } from '../BaseMethod';
+
+import type { DeviceFactoryInfoSetParams } from './helpers';
+
+export default class DeviceFactoryInfoSet extends BaseMethod<DeviceFactoryInfoSetParams> {
+  init() {
+    // Protocol V2 (Pro2) only; Core rejects non-V2 devices.
+    this.requireProtocolV2 = true;
+    this.skipForceUpdateCheck = true;
+    this.useDevicePassphraseState = false;
+    this.params = {
+      version: this.payload.version,
+      serial_number: this.payload.serial_number,
+      burn_in_completed: this.payload.burn_in_completed,
+      factory_test_completed: this.payload.factory_test_completed,
+      manufacture_time: this.payload.manufacture_time,
+    };
+  }
+
+  async run() {
+    const res = await this.device.commands.typedCall('DeviceFactoryInfoSet', 'Success', {
+      info: {
+        version: this.params.version,
+        serial_number: this.params.serial_number,
+        burn_in_completed: this.params.burn_in_completed,
+        factory_test_completed: this.params.factory_test_completed,
+        manufacture_time: this.params.manufacture_time,
+      },
+    });
+    return Promise.resolve(res.message);
+  }
+}

package/src/api/protocol-v2/DeviceFirmwareUpdate.ts

@@ -13,7 +13,7 @@ import type { DeviceFirmwareUpdateParams } from './helpers';
 
 export default class DeviceFirmwareUpdate extends BaseMethod<DeviceFirmwareUpdateParams> {
   init() {
-    // Protocol V2 (Pro2) 专属方法，core 调度层统一做非 V2 设备守卫
+    // Protocol V2 (Pro2) only; Core rejects non-V2 devices.
     this.requireProtocolV2 = true;
     this.skipForceUpdateCheck = true;
     this.useDevicePassphraseState = false;
@@ -29,7 +29,7 @@ export default class DeviceFirmwareUpdate extends BaseMethod<DeviceFirmwareUpdat
     const targets = normalizeFirmwareTargets(this.params);
     try {
       const res = await this.device.commands.typedCall(
-        'DevFirmwareUpdate',
+        'DeviceFirmwareUpdateRequest',
         PROTOCOL_V2_FIRMWARE_UPDATE_RESPONSE_TYPES,
         {
           targets,
@@ -37,25 +37,23 @@ export default class DeviceFirmwareUpdate extends BaseMethod<DeviceFirmwareUpdat
         {
           ...PROTOCOL_V2_FIRMWARE_UPDATE_OPTIONS,
           onIntermediateResponse: (response: MessageFromOneKey) => {
-            if (response.type !== 'DevFirmwareInstallProgress') return;
-            const progress = Number(response.message?.progress);
-            if (!Number.isFinite(progress)) return;
+            if (response.type !== 'DeviceFirmwareUpdateStatus') return;
             this.postMessage(
               createUiMessage(UI_REQUEST.FIRMWARE_PROGRESS, {
                 device: this.device.toMessageObject() as KnownDevice,
-                progress: Math.min(Math.max(progress, 0), 100),
+                progress: 99,
                 progressType: 'installingFirmware',
               })
             );
           },
         }
       );
-      return Promise.resolve(res.message);
+      return res.message;
     } catch (error) {
       if (isProtocolV2DeviceDisconnectedError(error)) {
-        return Promise.resolve({
+        return {
           message: 'Device firmware update started',
-        });
+        };
       }
       throw error;
     }

package/src/api/protocol-v2/DeviceGetFirmwareUpdateStatus.ts

@@ -1,19 +1,54 @@
 import { BaseMethod } from '../BaseMethod';
+import { invalidParameter } from '../helpers/filesystemValidation';
 
-export default class DeviceGetFirmwareUpdateStatus extends BaseMethod {
+import type { DeviceFirmwareUpdateStatusGetParams } from './helpers';
+import type { DeviceFirmwareUpdateRecordFields } from '@onekeyfe/hd-transport';
+
+const DEVICE_FIRMWARE_UPDATE_STATUS_FIELDS = ['status', 'payload_version', 'path'] as const;
+
+function normalizeStatusFields(
+  fields: DeviceFirmwareUpdateStatusGetParams['fields']
+): DeviceFirmwareUpdateRecordFields | undefined {
+  if (fields === undefined || fields === null) return undefined;
+  if (typeof fields !== 'object' || Array.isArray(fields)) {
+    throw invalidParameter('Parameter [fields] must be an object.');
+  }
+
+  const unknownField = Object.keys(fields).find(
+    field => !DEVICE_FIRMWARE_UPDATE_STATUS_FIELDS.includes(field as any)
+  );
+  if (unknownField) {
+    throw invalidParameter(`Unsupported firmware update status field: ${unknownField}`);
+  }
+
+  const normalized: DeviceFirmwareUpdateRecordFields = {};
+  for (const field of DEVICE_FIRMWARE_UPDATE_STATUS_FIELDS) {
+    const value = fields[field];
+    if (value !== undefined) {
+      if (typeof value !== 'boolean') {
+        throw invalidParameter(`Parameter [fields.${field}] must be a boolean.`);
+      }
+      normalized[field] = value;
+    }
+  }
+  return normalized;
+}
+
+export default class DeviceGetFirmwareUpdateStatus extends BaseMethod<DeviceFirmwareUpdateStatusGetParams> {
   init() {
-    // Protocol V2 (Pro2) 专属方法，core 调度层统一做非 V2 设备守卫
+    // Protocol V2 (Pro2) only; Core rejects non-V2 devices.
     this.requireProtocolV2 = true;
     this.skipForceUpdateCheck = true;
     this.useDevicePassphraseState = false;
-    this.params = undefined;
+    const fields = normalizeStatusFields(this.payload.fields);
+    this.params = fields ? { fields } : {};
   }
 
   async run() {
     const res = await this.device.commands.typedCall(
-      'DevGetFirmwareUpdateStatus',
-      'DevFirmwareUpdateStatus',
-      {}
+      'DeviceFirmwareUpdateStatusGet',
+      'DeviceFirmwareUpdateStatus',
+      this.params
     );
     return Promise.resolve(res.message);
   }