@onekeyfe/hd-transport 1.2.0-alpha.19 → 1.2.0-alpha.20

package/messages-protocol-v2.json

@@ -482,7 +482,7 @@
         "MessageType_DeviceStatus": 60603,
         "MessageType_DevGetOnboardingStatus": 60604,
         "MessageType_DevOnboardingStatus": 60605,
-        "MessageType_DeviceSessionOpen": 60606,
+        "MessageType_DeviceSessionGet": 60606,
         "MessageType_DeviceSession": 60607,
         "MessageType_DeviceSessionAskPin": 60608,
         "MessageType_FilesystemPermissionFix": 60800,
@@ -11849,61 +11849,49 @@
     },
     "DeviceSettings": {
       "fields": {
-        "label": {
-          "type": "string",
-          "id": 1
-        },
         "bt_enable": {
           "type": "bool",
-          "id": 2
+          "id": 1
         },
         "language": {
           "type": "string",
-          "id": 3
+          "id": 2
         },
         "wallpaper_path": {
           "type": "string",
-          "id": 4
+          "id": 3
         },
         "brightness": {
           "type": "uint32",
-          "id": 7
-        },
-        "autolock_delay_ms": {
-          "type": "uint32",
-          "id": 8
-        },
-        "autoshutdown_delay_ms": {
-          "type": "uint32",
-          "id": 9
+          "id": 4
         },
         "animation_enable": {
           "type": "bool",
-          "id": 10
+          "id": 5
         },
         "tap_to_wake": {
           "type": "bool",
-          "id": 11
+          "id": 6
         },
         "haptic_feedback": {
           "type": "bool",
-          "id": 12
+          "id": 7
         },
         "device_name_display_enabled": {
           "type": "bool",
-          "id": 13
+          "id": 8
         },
         "airgap_mode": {
           "type": "bool",
-          "id": 14
+          "id": 9
         },
         "usb_lock_enable": {
           "type": "bool",
-          "id": 17
+          "id": 10
         },
         "random_keypad": {
           "type": "bool",
-          "id": 18
+          "id": 11
         },
         "passphrase_enable": {
           "type": "bool",
@@ -11912,6 +11900,18 @@
         "fido_enabled": {
           "type": "bool",
           "id": 101
+        },
+        "autolock_delay_ms": {
+          "type": "uint32",
+          "id": 102
+        },
+        "autoshutdown_delay_ms": {
+          "type": "uint32",
+          "id": 103
+        },
+        "label": {
+          "type": "string",
+          "id": 104
         }
       }
     },
@@ -12427,68 +12427,14 @@
         }
       }
     },
-    "DeviceSessionResume": {
+    "DeviceSessionGet": {
       "fields": {
         "session_id": {
-          "rule": "required",
           "type": "bytes",
           "id": 1
         }
       }
     },
-    "DeviceHostPassphrase": {
-      "fields": {
-        "passphrase": {
-          "rule": "required",
-          "type": "string",
-          "id": 1
-        }
-      }
-    },
-    "DevicePassphraseOnDevice": {
-      "fields": {}
-    },
-    "DeviceAttachPinOnDevice": {
-      "fields": {}
-    },
-    "DeviceWalletSelect": {
-      "oneofs": {
-        "access": {
-          "oneof": ["host_passphrase", "passphrase_on_device", "attach_pin_on_device"]
-        }
-      },
-      "fields": {
-        "host_passphrase": {
-          "type": "DeviceHostPassphrase",
-          "id": 1
-        },
-        "passphrase_on_device": {
-          "type": "DevicePassphraseOnDevice",
-          "id": 2
-        },
-        "attach_pin_on_device": {
-          "type": "DeviceAttachPinOnDevice",
-          "id": 3
-        }
-      }
-    },
-    "DeviceSessionOpen": {
-      "oneofs": {
-        "mode": {
-          "oneof": ["resume", "select"]
-        }
-      },
-      "fields": {
-        "resume": {
-          "type": "DeviceSessionResume",
-          "id": 1
-        },
-        "select": {
-          "type": "DeviceWalletSelect",
-          "id": 2
-        }
-      }
-    },
     "DeviceSession": {
       "fields": {
         "session_id": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onekeyfe/hd-transport",
-  "version": "1.2.0-alpha.19",
+  "version": "1.2.0-alpha.20",
   "description": "Transport layer abstractions and utilities for OneKey hardware SDK.",
   "author": "OneKey",
   "homepage": "https://github.com/OneKeyHQ/hardware-js-sdk#readme",
@@ -28,5 +28,5 @@
     "long": "^4.0.0",
     "protobufjs": "^6.11.2"
   },
-  "gitHead": "4e79f6a400463f342285b9a761b6b84523f1d6b9"
+  "gitHead": "5fbc1ada90fd3cfda7e5ef08be368cb452018733"
 }

package/src/constants.ts

@@ -1,50 +1,50 @@
 // ---- Protocol V1 (Pro1 / Touch / Mini / Classic) ----
 
-/** Protocol V1 USB report 标记，ASCII '?'。 */
+/** Protocol V1 USB report marker, ASCII `?`. */
 export const PROTOCOL_V1_REPORT_ID = 0x3f;
 
-/** Protocol V1 envelope 头部标记，ASCII '#'。 */
+/** Protocol V1 envelope marker, ASCII `#`. */
 export const PROTOCOL_V1_HEADER_BYTE = 0x23;
 
-/** Protocol V1 单个 chunk 去掉 report 标记后的可用 payload 长度。 */
+/** Protocol V1 payload bytes per chunk after the report marker. */
 export const PROTOCOL_V1_CHUNK_PAYLOAD_SIZE = 63;
 
-/** Protocol V1 USB packet 长度：report 标记 + chunk payload。 */
+/** Protocol V1 USB packet length: report marker plus chunk payload. */
 export const PROTOCOL_V1_USB_PACKET_SIZE = PROTOCOL_V1_CHUNK_PAYLOAD_SIZE + 1;
 
-/** Protocol V1 message metadata：message type 2 字节 + payload length 4 字节。 */
+/** Protocol V1 message metadata: two-byte type plus four-byte payload length. */
 export const PROTOCOL_V1_MESSAGE_HEADER_SIZE = 2 + 4;
 
-/** Protocol V1 envelope metadata：## + message type + payload length。 */
+/** Protocol V1 envelope metadata: `##`, message type, and payload length. */
 export const PROTOCOL_V1_ENVELOPE_HEADER_SIZE = 1 + 1 + PROTOCOL_V1_MESSAGE_HEADER_SIZE;
 
 // ---- Protocol V2 (Pro2 USB / BLE transports) ----
 
-/** Protocol V2 单帧最大长度，包含 header、payload 和 CRC；需容纳 4000 数据块及 protobuf 开销。 */
-export const PROTOCOL_V2_FRAME_MAX_BYTES = 4608;
+/** Firmware Proto Link runtime limit for a complete V2 frame, including header and CRC. */
+export const PROTOCOL_V2_FRAME_MAX_BYTES = 4200;
 
-/** WebUSB 下 FilesystemFileWrite 的文件数据分块大小。 */
+/** FilesystemFileWrite chunk size over WebUSB. */
 export const PROTOCOL_V2_WEBUSB_FILE_CHUNK_SIZE = 4000;
 
-/** BLE 下 FilesystemFileWrite 的文件数据分块大小。 */
+/** FilesystemFileWrite chunk size over BLE. */
 export const PROTOCOL_V2_BLE_FILE_CHUNK_SIZE = 1800;
 
-/** BLE 下 FilesystemFileRead 的文件数据分块大小，受 Pro2 UART 1024B TX 缓冲限制。 */
+/** BLE FilesystemFileRead chunk size, limited by the Pro2 1024-byte UART TX buffer. */
 export const PROTOCOL_V2_BLE_FILE_READ_CHUNK_SIZE = 900;
 
-/** Pro2 BLE/UART 接收 FIFO 必须容纳完整 Proto Link 帧。 */
+/** Pro2 BLE/UART RX FIFO must hold a complete Proto Link frame. */
 export const PROTOCOL_V2_BLE_FRAME_MAX_BYTES = 2048;
 
-/** @deprecated 使用按传输区分的 PROTOCOL_V2_WEBUSB_FILE_CHUNK_SIZE / PROTOCOL_V2_BLE_FILE_CHUNK_SIZE。 */
+/** @deprecated Use the transport-specific WebUSB or BLE file chunk constant. */
 export const PROTOCOL_V2_FILE_CHUNK_SIZE = PROTOCOL_V2_WEBUSB_FILE_CHUNK_SIZE;
 
 /**
- * Protocol V2 路由 channel。
- * USB 端点直接到主 MCU，不需要 proto-link 路由；BLE 需要经过 BLE 协处理器 UART bridge。
+ * Protocol V2 routing channel. USB reaches the main MCU directly, while BLE routes
+ * through the BLE coprocessor UART bridge.
  */
 export const PROTOCOL_V2_CHANNEL_USB = 0;
 export const PROTOCOL_V2_CHANNEL_BLE_UART = 1;
 export const PROTOCOL_V2_CHANNEL_SOCKET = 2;
 
-/** protobuf 命令流的 packet_src，固件侧会把 0 路由到 protobuf dispatcher。 */
+/** packet_src for protobuf commands; firmware routes zero to the protobuf dispatcher. */
 export const PROTOCOL_V2_PACKET_SRC_COMMAND = 0;

package/src/protocols/index.ts

@@ -6,7 +6,12 @@ import { decodeMessage as decodeV1Message } from './v1/receive';
 import { createMessageFromName, createMessageFromType } from '../serialization/protobuf/messages';
 import { encode as encodeProtobuf } from '../serialization/protobuf/encode';
 import { decode as decodeProtobuf } from '../serialization/protobuf/decode';
-import { decodeFrame as decodeV2Frame, encodeProtobufFrame, isAckFrame } from './v2';
+import {
+  decodeFrame as decodeV2Frame,
+  encodeProtobufFrame,
+  getAckSequence,
+  isAckFrame,
+} from './v2';
 
 import type { Root } from 'protobufjs/light';
 
@@ -71,6 +76,7 @@ export const ProtocolV1 = {
 
 export const ProtocolV2 = {
   isAckFrame,
+  getAckSequence,
 
   inspectFrame(schemas: ProtocolV2Schemas, frame: Uint8Array) {
     const { messageTypeId, pbPayload, seq } = decodeV2Frame(frame);

package/src/protocols/v2/crc8.ts

@@ -22,7 +22,7 @@ export const CRC8_TABLE = new Uint8Array([
 ]);
 
 /**
- * 计算 data 前 len 个字节的 CRC-8，使用与固件侧一致的初始值。
+ * Compute CRC-8 over the first len bytes using the firmware-compatible initial value.
  */
 export function crc8(data: Uint8Array, len: number): number {
   let crc = CRC8_INIT;

package/src/protocols/v2/decode.ts

@@ -61,6 +61,13 @@ export function isAckFrame(data: Uint8Array): boolean {
   return true;
 }
 
+export function getAckSequence(data: Uint8Array): number | undefined {
+  if (!isAckFrame(data)) {
+    return undefined;
+  }
+  return data[6];
+}
+
 /**
  * Parse and validate a Protocol V2 response frame.
  *

package/src/protocols/v2/encode.ts

@@ -43,7 +43,7 @@ export function encodeFrame(
   const payloadLen = payload ? payload.length : 0;
   const frameLen = payloadLen + PROTO_HEAD_CRC_SIZE;
   if (frameLen > PROTOCOL_V2_FRAME_MAX_BYTES) {
-    throw new Error(`Protocol V2 frame too large: ${frameLen}`);
+    throw new Error(`Protocol V2 frame too large: ${frameLen} > ${PROTOCOL_V2_FRAME_MAX_BYTES}`);
   }
   const frame = new Uint8Array(frameLen);
 

package/src/protocols/v2/link-manager.ts

@@ -17,6 +17,7 @@ export interface ProtocolV2LinkAdapter {
   logger?: ProtocolV2SessionOptions['logger'];
   logPrefix?: string;
   createTimeoutError?: ProtocolV2SessionOptions['createTimeoutError'];
+  writeTimeoutMs?: number;
 }
 
 export type ProtocolV2LinkManagerOptions<Key> = {
@@ -128,6 +129,7 @@ export class ProtocolV2LinkManager<Key> {
       logger: adapter.logger,
       logPrefix: adapter.logPrefix,
       createTimeoutError: adapter.createTimeoutError,
+      writeTimeoutMs: adapter.writeTimeoutMs,
     });
     const link = { adapter, session, state };
     this.links.set(key, link);

package/src/protocols/v2/session.ts

@@ -38,6 +38,8 @@ export type ProtocolV2SessionOptions = {
   createTimeoutError?: (name: string, timeoutMs: number) => Error;
   sequenceCursor?: ProtocolV2SequenceCursor;
   generation?: number;
+  writeTimeoutMs?: number;
+  deliveryTimeoutMs?: number;
 };
 
 export type ProtocolV2CallOptions = {
@@ -136,10 +138,11 @@ export async function withProtocolTimeout<T>(
   }
 }
 
-// Write completion is owned by the concrete transport. A Promise.race watchdog
-// here can return while libusb/WebUSB is still flushing a large Protocol V2
-// frame, which desynchronizes later request/response pairs.
-export const PROTOCOL_V2_WRITE_WATCHDOG_TIMEOUT_MS = 0;
+// A transport write must never keep the serialized device queue pending forever.
+// Callers must classify a timeout as link-fatal and reset the physical adapter so
+// the losing Promise cannot continue on the next connection generation.
+export const PROTOCOL_V2_WRITE_WATCHDOG_TIMEOUT_MS = 30_000;
+export const PROTOCOL_V2_DELIVERY_WATCHDOG_TIMEOUT_MS = 5_000;
 
 export class ProtocolV2Session {
   private readonly options: ProtocolV2SessionOptions;
@@ -185,6 +188,8 @@ export class ProtocolV2Session {
       logPrefix = 'ProtocolV2',
       createTimeoutError,
       generation = 0,
+      writeTimeoutMs = PROTOCOL_V2_WRITE_WATCHDOG_TIMEOUT_MS,
+      deliveryTimeoutMs = PROTOCOL_V2_DELIVERY_WATCHDOG_TIMEOUT_MS,
     } = this.options;
 
     const shouldReduceDebug = shouldReduceProtocolV2Debug(name);
@@ -201,7 +206,7 @@ export class ProtocolV2Session {
       router,
       seq: protoSeq,
     });
-    // 暂停输出 Protocol V2 TX 帧日志，避免传输层产生大量调试信息。
+    // Suppress Protocol V2 TX frame logs to avoid excessive transport diagnostics.
     /*
     const txMetadata = ProtocolV2.inspectFrame(schemas, frame);
 
@@ -222,15 +227,10 @@ export class ProtocolV2Session {
       );
     }
 
-    // Lenient watchdog on the write phase only — see
-    // PROTOCOL_V2_WRITE_WATCHDOG_TIMEOUT_MS for the rationale.
     await withProtocolTimeout(
       writeFrame(frame, callContext),
-      PROTOCOL_V2_WRITE_WATCHDOG_TIMEOUT_MS,
-      () =>
-        new Error(
-          `Protocol V2 write timeout after ${PROTOCOL_V2_WRITE_WATCHDOG_TIMEOUT_MS}ms for ${name}`
-        )
+      writeTimeoutMs,
+      () => new Error(`Protocol V2 write timeout after ${writeTimeoutMs}ms for ${name}`)
     );
 
     // Cancellation flag for the read loop: when the response timeout fires,
@@ -238,6 +238,15 @@ export class ProtocolV2Session {
     // consuming frames meant for the next call. The timeout callback flips the
     // flag so the loop exits and discards any late frame.
     const cancellation = { cancelled: false };
+    let resolveDelivery: () => void = () => undefined;
+    let deliveryConfirmed = false;
+    const deliveryPromise = new Promise<void>(resolve => {
+      resolveDelivery = () => {
+        if (deliveryConfirmed) return;
+        deliveryConfirmed = true;
+        resolve();
+      };
+    });
 
     const readResponse = async (): Promise<MessageFromOneKey> => {
       // Some Protocol V2 operations emit progress notifications before the
@@ -249,9 +258,16 @@ export class ProtocolV2Session {
           // Timed out while waiting: drop the late frame and stop reading.
           break;
         }
-        const isAck = ProtocolV2.isAckFrame(rxFrame);
-        if (!isAck) {
-          // 暂停输出 Protocol V2 RX 帧日志，避免传输层产生大量调试信息。
+        const ackSequence = ProtocolV2.getAckSequence(rxFrame);
+        if (ackSequence !== undefined) {
+          if (ackSequence === protoSeq) {
+            resolveDelivery();
+          }
+        } else {
+          // Some firmware versions return the protobuf response without a separate
+          // ACK. Receiving any valid response frame proves that the request arrived.
+          resolveDelivery();
+          // Suppress Protocol V2 RX frame logs to avoid excessive transport diagnostics.
           /*
           const rxMetadata = ProtocolV2.inspectFrame(schemas, rxFrame);
 
@@ -287,7 +303,7 @@ export class ProtocolV2Session {
       throw new Error(`Protocol V2 read loop cancelled after timeout for ${name}`);
     };
 
-    return withProtocolTimeout(
+    const responsePromise = withProtocolTimeout(
       readResponse(),
       callOptions.timeoutMs,
       () =>
@@ -298,6 +314,31 @@ export class ProtocolV2Session {
         cancellation.cancelled = true;
       }
     );
+    const deliverySignal = Promise.race([deliveryPromise, responsePromise.then(() => undefined)]);
+    const deliveryWatchdog = withProtocolTimeout(
+      deliverySignal,
+      deliveryTimeoutMs,
+      () => new Error(`Protocol V2 delivery timeout after ${deliveryTimeoutMs}ms for ${name}`),
+      () => {
+        cancellation.cancelled = true;
+      }
+    );
+
+    try {
+      const firstResult = await Promise.race([
+        deliveryWatchdog.then(() => ({ kind: 'delivered' as const })),
+        responsePromise.then(response => ({ kind: 'response' as const, response })),
+      ]);
+      if (firstResult.kind === 'response') {
+        return firstResult.response;
+      }
+      return await responsePromise;
+    } catch (error) {
+      cancellation.cancelled = true;
+      deliveryWatchdog.catch(() => undefined);
+      responsePromise.catch(() => undefined);
+      throw error;
+    }
   }
 }
 

package/src/protocols/v2/usb-transport-base.ts

@@ -61,7 +61,7 @@ export abstract class ProtocolV2UsbTransportBase<Key> {
   protected abstract createProtocolV2UsbTimeoutError(name: string, timeoutMs: number): Error;
 
   protected onProtocolV2UsbLinkInvalidated(_key: Key, _reason: string): Promise<void> | void {
-    // 子类按需清理协议缓存或记录平台日志。
+    // Subclasses may clear protocol caches or emit platform-specific diagnostics.
   }
 
   protected async rotateProtocolV2UsbGeneration(key: Key, reason: string): Promise<number> {

package/src/types/messages.ts

@@ -4779,13 +4779,10 @@ export type DeviceReboot = {
 
 // DeviceSettings
 export type DeviceSettings = {
-  label?: string;
   bt_enable?: boolean;
   language?: string;
   wallpaper_path?: string;
   brightness?: number;
-  autolock_delay_ms?: number;
-  autoshutdown_delay_ms?: number;
   animation_enable?: boolean;
   tap_to_wake?: boolean;
   haptic_feedback?: boolean;
@@ -4795,6 +4792,9 @@ export type DeviceSettings = {
   random_keypad?: boolean;
   passphrase_enable?: boolean;
   fido_enabled?: boolean;
+  autolock_delay_ms?: number;
+  autoshutdown_delay_ms?: number;
+  label?: string;
 };
 
 // DeviceSettingsGet
@@ -5049,33 +5049,9 @@ export type ProtocolV2DeviceInfo = {
   status?: DeviceStatus;
 };
 
-// DeviceSessionResume
-export type DeviceSessionResume = {
-  session_id: string;
-};
-
-// DeviceHostPassphrase
-export type DeviceHostPassphrase = {
-  passphrase: string;
-};
-
-// DevicePassphraseOnDevice
-export type DevicePassphraseOnDevice = {};
-
-// DeviceAttachPinOnDevice
-export type DeviceAttachPinOnDevice = {};
-
-// DeviceWalletSelect
-export type DeviceWalletSelect = {
-  host_passphrase?: DeviceHostPassphrase;
-  passphrase_on_device?: DevicePassphraseOnDevice;
-  attach_pin_on_device?: DeviceAttachPinOnDevice;
-};
-
-// DeviceSessionOpen
-export type DeviceSessionOpen = {
-  resume?: DeviceSessionResume;
-  select?: DeviceWalletSelect;
+// DeviceSessionGet
+export type DeviceSessionGet = {
+  session_id?: string;
 };
 
 // DeviceSession
@@ -5905,12 +5881,7 @@ export type MessageType = {
   DeviceInfoTargets: DeviceInfoTargets;
   DeviceInfoTypes: DeviceInfoTypes;
   DeviceInfoGet: DeviceInfoGet;
-  DeviceSessionResume: DeviceSessionResume;
-  DeviceHostPassphrase: DeviceHostPassphrase;
-  DevicePassphraseOnDevice: DevicePassphraseOnDevice;
-  DeviceAttachPinOnDevice: DeviceAttachPinOnDevice;
-  DeviceWalletSelect: DeviceWalletSelect;
-  DeviceSessionOpen: DeviceSessionOpen;
+  DeviceSessionGet: DeviceSessionGet;
   DeviceSession: DeviceSession;
   DeviceSessionAskPin: DeviceSessionAskPin;
   DeviceStatus: DeviceStatus;

package/src/types/transport.ts

@@ -92,7 +92,7 @@ export type Transport = {
 
   // resolves when the transport can be used; rejects when it cannot
   init: ITransportInitFn;
-  stop(): void;
+  stop(): void | Promise<void>;
 
   configured: boolean;
   version: string;
@@ -105,11 +105,7 @@ export type Transport = {
 export type LowLevelDevice = OneKeyDeviceInfoBase & { id: string; name: string };
 export type LowlevelTransportSharedPlugin = {
   enumerate: () => Promise<LowLevelDevice[]>;
-  send: (
-    uuid: string,
-    data: string,
-    options?: { withoutResponse?: boolean }
-  ) => Promise<void>;
+  send: (uuid: string, data: string, options?: { withoutResponse?: boolean }) => Promise<void>;
   receive: (uuid?: string) => Promise<string>;
   connect: (uuid: string) => Promise<void>;
   disconnect: (uuid: string) => Promise<void>;