@onekeyfe/hd-core 1.2.2-alpha.104 → 1.2.2-alpha.106

package/src/api/allnetwork/AllNetworkGetAddressBase.ts

@@ -1,5 +1,6 @@
 import semver from 'semver';
 import {
+  EDeviceType,
   ERRORS,
   HardwareError,
   HardwareErrorCode,
@@ -15,6 +16,7 @@ import { DEVICE, IFRAME, createUiMessage } from '../../events';
 import { UI_REQUEST } from '../../constants/ui-request';
 import { onDeviceButtonHandler } from '../../core';
 import { runMethodWithUnlockPolicy } from '../../protocols/protocol-v2/unlockPolicyRunner';
+import { supportsProtocolV2Message } from '../../protocols/protocol-v2/features';
 import {
   completeRequestContext,
   createRequestContext,
@@ -22,6 +24,7 @@ import {
 } from '../../utils/tracing';
 
 import type { Device, DeviceEvents } from '../../device/Device';
+import type { DeviceCommands } from '../../device/DeviceCommands';
 import type { CoreApi } from '../../types';
 import type {
   AllNetworkAddress,
@@ -266,6 +269,10 @@ export default abstract class AllNetworkGetAddressBase extends BaseMethod<
 
   abortController: AbortController | null = null;
 
+  protected loadingCleanupInBackground = false;
+
+  private loadingCommands?: DeviceCommands;
+
   init() {
     this.checkDeviceId = true;
     this.allowDeviceMode = [...this.allowDeviceMode, UI_REQUEST.NOT_INITIALIZE];
@@ -457,30 +464,64 @@ export default abstract class AllNetworkGetAddressBase extends BaseMethod<
 
   abstract getAllNetworkAddress(rootFingerprint: number): Promise<AllNetworkAddress[]>;
 
+  protected async stopAllNetworkLoading(canSend = true) {
+    const commands = this.loadingCommands;
+    this.loadingCommands = undefined;
+    // Never send cleanup through a replacement or disposed connection.
+    if (!canSend || !commands || commands.disposed || commands !== this.device.commands) return;
+    try {
+      await commands.typedCall('DeviceAnimationControl', 'Success', {
+        action: PROTO.DeviceAnimationAction.AnimationAction_Stop,
+      });
+    } catch {
+      // Cleanup must not mask the operation result. Firmware also has an idle timeout.
+    }
+  }
+
   async run() {
-    const res = await this.device.commands.typedCall('GetPublicKey', 'PublicKey', {
-      address_n: [toHardened(44), toHardened(1), toHardened(0)],
-      coin_name: 'Testnet',
-      script_type: 'SPENDADDRESS',
-      show_display: false,
-    });
+    this.loadingCleanupInBackground = false;
+    try {
+      if (this.device.isProtocolV2() && this.device.getCurrentDeviceType() === EDeviceType.Pro2) {
+        const protocolInfo = await this.device.ensureProtocolV2RuntimeContext();
+        if (supportsProtocolV2Message(protocolInfo, 60461)) {
+          const { commands } = this.device;
+          await commands.typedCall('DeviceAnimationControl', 'Success', {
+            action: PROTO.DeviceAnimationAction.AnimationAction_Start,
+          });
+          this.loadingCommands = commands;
+        }
+      }
 
-    if (!this.device.isProtocolV2()) {
-      this.postMessage(createUiMessage(UI_REQUEST.CLOSE_UI_PIN_WINDOW));
-    }
+      const res = await this.device.commands.typedCall('GetPublicKey', 'PublicKey', {
+        address_n: [toHardened(44), toHardened(1), toHardened(0)],
+        coin_name: 'Testnet',
+        script_type: 'SPENDADDRESS',
+        show_display: false,
+      });
 
-    if (res.message.root_fingerprint == null) {
-      throw ERRORS.TypedError(HardwareErrorCode.CallMethodInvalidParameter);
-    }
+      if (!this.device.isProtocolV2()) {
+        this.postMessage(createUiMessage(UI_REQUEST.CLOSE_UI_PIN_WINDOW));
+      }
 
-    this.abortController = new AbortController();
+      if (res.message.root_fingerprint == null) {
+        throw ERRORS.TypedError(HardwareErrorCode.CallMethodInvalidParameter);
+      }
 
-    return this.getAllNetworkAddress(res.message.root_fingerprint).catch(e => {
+      this.abortController = new AbortController();
+
+      return await this.getAllNetworkAddress(res.message.root_fingerprint);
+    } catch (e) {
+      // A failed call may have invalidated the transport link without disposing
+      // DeviceCommands. Let firmware time out instead of reconnecting for Stop.
+      await this.stopAllNetworkLoading(false);
       if (e instanceof HardwareError && e.errorCode === HardwareErrorCode.RepeatUnlocking) {
         throw ERRORS.TypedError(HardwareErrorCode.RepeatUnlocking, e.message);
       }
       throw e;
-    });
+    } finally {
+      // The callback API returns before its chain requests finish.
+      if (!this.loadingCleanupInBackground) await this.stopAllNetworkLoading();
+    }
   }
 }
 

package/src/api/allnetwork/AllNetworkGetAddressByLoop.ts

@@ -28,6 +28,7 @@ export default class AllNetworkGetAddressByLoop extends AllNetworkGetAddressBase
     const bundle = this.payload.bundle || [this.payload];
 
     // process callbacks in background
+    this.loadingCleanupInBackground = true;
     const callbackPromise = this.processCallbacksInBackground(
       bundle,
       rootFingerprint,
@@ -95,6 +96,7 @@ export default class AllNetworkGetAddressByLoop extends AllNetworkGetAddressBase
         data: allResults,
       });
     } catch (error: any) {
+      await this.stopAllNetworkLoading(false);
       let errorCode = error.errorCode || error.code;
       let errorMessage = error.message;
 
@@ -121,6 +123,7 @@ export default class AllNetworkGetAddressByLoop extends AllNetworkGetAddressBase
         },
       });
     } finally {
+      await this.stopAllNetworkLoading();
       this.context?.cancelCallbackTasks(this.payload.connectId);
       this.abortController = null;
     }

package/src/core/RequestQueue.ts

@@ -1,3 +1,5 @@
+import { ERRORS, HardwareErrorCode } from '@onekeyfe/hd-shared';
+
 import { LoggerNames, getLogger } from '../utils';
 
 import type { Deferred } from '@onekeyfe/hd-shared';
@@ -40,6 +42,24 @@ export default class RequestQueue {
     return this.requestQueue.get(requestId);
   }
 
+  public async waitForTask<T>(task: RequestTask, pending: () => Promise<T>): Promise<T> {
+    const signal = task.method.abortSignal;
+    const cancellationError = () => ERRORS.TypedError(HardwareErrorCode.CallQueueActionCancelled);
+    if (signal?.aborted) throw cancellationError();
+    let onAbort: (() => void) | undefined;
+    try {
+      const cancelled = new Promise<never>((_, reject) => {
+        onAbort = () => reject(cancellationError());
+        signal?.addEventListener('abort', onAbort, { once: true });
+      });
+      const result = await Promise.race([pending(), cancelled]);
+      if (signal?.aborted) throw cancellationError();
+      return result;
+    } finally {
+      if (onAbort) signal?.removeEventListener('abort', onAbort);
+    }
+  }
+
   // 获取请求的AbortController
   public getAbortController(requestId: number) {
     return this.requestQueue.get(requestId)?.abortController;

package/src/core/index.ts

@@ -10,6 +10,7 @@ import {
   isProtocolV2LinkDisabledError,
 } from '@onekeyfe/hd-transport';
 import {
+  EDeviceType,
   ERRORS,
   ERROR_CODES_REQUIRE_DISCONNECT,
   ERROR_CODES_REQUIRE_RELEASE,
@@ -84,6 +85,7 @@ import type { BaseMethod } from '../api/BaseMethod';
 const Log = getLogger(LoggerNames.Core);
 const PRE_INITIALIZE_TTL_MS = 60 * 1000;
 const PRE_PENDING_CALL_TIMEOUT_MS = 15 * 1000;
+const PRO2_USB_SIGNING_COOLDOWN_MS = 1000;
 
 // Dedup/coalesce state for "pre-warm signal" methods (isPreWarmSignal),
 // keyed by getPreWarmKey(): coalesce in-flight, skip if warmed within TTL.
@@ -313,30 +315,44 @@ const waitForPendingPromise = async (
   if (pendingPromise) {
     Log.debug('pre pending call promise before call method, wait for it');
     let timer: ReturnType<typeof setTimeout> | undefined;
-    let timedOut = false;
     try {
       await Promise.race([
         pendingPromise,
-        new Promise<void>(resolve => {
+        new Promise<void>((_, reject) => {
           timer = setTimeout(() => {
-            timedOut = true;
-            resolve();
+            reject(
+              ERRORS.TypedError(
+                HardwareErrorCode.DeviceBusy,
+                'Previous device cancellation is still draining'
+              )
+            );
           }, PRE_PENDING_CALL_TIMEOUT_MS);
         }),
       ]);
-    } catch (error) {
-      // Cancellation is best-effort; the transport teardown owns recovery.
+      // A deadline is not evidence that old I/O is safe to reuse. Keep the
+      // barrier on failure; a later call may proceed only after cleanup settles.
+      removePrePendingCallPromise?.(connectId, pendingPromise);
     } finally {
       if (timer) clearTimeout(timer);
-      removePrePendingCallPromise?.(connectId, pendingPromise);
-    }
-    if (timedOut) {
-      Log.warn('pre pending call promise timed out before call method', { connectId });
     }
     Log.debug('pre pending call promise before call method done');
   }
 };
 
+export function getPostCallPendingPromise(method: BaseMethod, device: Device): Promise<void> {
+  const cleanupPromise = device.waitForRunCleanup();
+  const env = DataManager.getSettings('env');
+  const deviceType = device.getCurrentDeviceType();
+  const requiresSigningCooldown =
+    method.name.includes('Sign') &&
+    (deviceType === EDeviceType.Pro2 || deviceType === EDeviceType.Neo) &&
+    (DataManager.isBrowserWebUsb(env) || DataManager.isDesktopWebUsb(env) || env === 'node-usb');
+
+  return requiresSigningCooldown
+    ? cleanupPromise.then(() => wait(PRO2_USB_SIGNING_COOLDOWN_MS)).then(() => undefined)
+    : cleanupPromise;
+}
+
 const onCallDevice = async (
   context: CoreContext,
   message: CoreMessage,
@@ -367,42 +383,38 @@ const onCallDevice = async (
     DevicePool.clearDeviceCache(method.payload.connectId);
   }
 
-  // wait for previous callback tasks to complete (ensure device does not call concurrently)
-  if (method.connectId) {
-    await context.waitForCallbackTasks(method.connectId);
-  }
-
-  await waitForPendingPromise(
-    method.connectId ?? '',
-    getPrePendingCallPromise,
-    removePrePendingCallPromise
-  );
-
+  // Register before waiting so cancellation also covers queued requests.
   const task = requestQueue.createTask(method);
 
   // Pre-warm holds the device as a per-connectId callback task so a concurrent
   // real call waits (before ensureConnected) instead of racing its Initialize.
   // Only covers pre-warm -> real-call ordering; the reverse is fail-closed.
   let preWarmCallbackTask: Deferred<void> | undefined;
-  if (method.isPreWarmSignal && method.connectId) {
-    preWarmCallbackTask = createDeferred<void>();
-    context.registerCallbackTask(method.connectId, preWarmCallbackTask);
-  }
-
   let device: Device;
   try {
+    const connectId = method.connectId ?? '';
+    if (connectId) {
+      await requestQueue.waitForTask(task, () => context.waitForCallbackTasks(connectId));
+    }
+    await requestQueue.waitForTask(task, () =>
+      waitForPendingPromise(
+        method.connectId ?? '',
+        getPrePendingCallPromise,
+        removePrePendingCallPromise
+      )
+    );
+    if (method.isPreWarmSignal && method.connectId) {
+      preWarmCallbackTask = createDeferred<void>();
+      context.registerCallbackTask(method.connectId, preWarmCallbackTask);
+    }
     /**
      * Polling to ensure successful connection
      */
-    const connectId = method.connectId ?? '';
     const pollingId = pollingManager.start(connectId);
-    device = await ensureConnected(
-      context,
-      method,
-      connectId,
-      pollingId,
-      task.abortController?.signal
-    );
+    device = await ensureConnected(context, method, connectId, pollingId, method.abortSignal);
+    if (method.abortSignal?.aborted) {
+      throw ERRORS.TypedError(HardwareErrorCode.CallQueueActionCancelled);
+    }
   } catch (e) {
     preWarmCallbackTask?.resolve();
     Log.debug('ensureConnected error: ', e);
@@ -478,14 +490,19 @@ const onCallDevice = async (
 
   try {
     // Wait for any pending task except our own (self-wait would deadlock).
-    if (method.connectId) {
-      await context.waitForCallbackTasks(method.connectId, preWarmCallbackTask);
+    const { connectId } = method;
+    if (connectId) {
+      await requestQueue.waitForTask(task, () =>
+        context.waitForCallbackTasks(connectId, preWarmCallbackTask)
+      );
     }
 
-    await waitForPendingPromise(
-      method.connectId ?? '',
-      getPrePendingCallPromise,
-      removePrePendingCallPromise
+    await requestQueue.waitForTask(task, () =>
+      waitForPendingPromise(
+        method.connectId ?? '',
+        getPrePendingCallPromise,
+        removePrePendingCallPromise
+      )
     );
 
     const inner = async (): Promise<void> => {
@@ -690,6 +707,13 @@ const onCallDevice = async (
           },
         });
         messageResponse = createResponseMessage(method.responseID, true, response);
+        // Preserve the acknowledged result while the next call waits for cleanup and cooldown.
+        if (method.connectId) {
+          context.setPrePendingCallPromise(
+            method.connectId,
+            getPostCallPendingPromise(method, device)
+          );
+        }
         requestQueue.resolveRequest(method.responseID, messageResponse);
         completeMethodRequestContext(method);
       } catch (error) {
@@ -701,6 +725,12 @@ const onCallDevice = async (
         }
         Log.debug(`Call API - Inner Method Run Error`, error);
         messageResponse = createResponseMessage(method.responseID, false, { error });
+        if (method.connectId) {
+          context.setPrePendingCallPromise(
+            method.connectId,
+            getPostCallPendingPromise(method, device)
+          );
+        }
         requestQueue.resolveRequest(method.responseID, messageResponse);
         completeMethodRequestContext(method, error);
 
@@ -727,6 +757,9 @@ const onCallDevice = async (
       skipInitialize: canSkipInitialize(method, device),
       ...parseInitOptions(method),
     };
+    if (method.abortSignal?.aborted) {
+      throw ERRORS.TypedError(HardwareErrorCode.CallQueueActionCancelled);
+    }
     const deviceRun = () => device.run(inner, runOptions);
     task.callPromise = createDeferred<any>(deviceRun);
 
@@ -747,6 +780,7 @@ const onCallDevice = async (
     );
     Log.debug('Call API - Run Error: ', error);
     completeMethodRequestContext(method, error);
+    return messageResponse;
   } finally {
     // Release the pre-warm callback task so the next real call can proceed.
     preWarmCallbackTask?.resolve();
@@ -1044,7 +1078,7 @@ async function connectDeviceForBle(
   retryCount = 0
 ) {
   try {
-    if (device.wasInterruptedByUser()) {
+    if (abortSignal?.aborted || device.wasInterruptedByUser()) {
       throw ERRORS.TypedError(HardwareErrorCode.DeviceInterruptedFromUser);
     }
     if (method.payload.forceProtocolDetection && device.hasDeviceAcquire()) {
@@ -1113,6 +1147,9 @@ async function connectDeviceForBle(
       DevicePool.emitter.emit(DEVICE.CONNECT, device);
     }
   } catch (err) {
+    if (abortSignal?.aborted || device.wasInterruptedByUser()) {
+      throw ERRORS.TypedError(HardwareErrorCode.DeviceInterruptedFromUser);
+    }
     const requiresColdReconnect = isMissingDetectedProtocolV2Error(method, err);
     // Device.run()'s REQUIRE_DISCONNECT handling never sees acquire/initialize
     // failures, so with keep-alive a wedged link would be reused by every retry
@@ -1286,6 +1323,8 @@ const ensureConnected = async (
             HardwareErrorCode.BleDeviceBondedCanceled,
             HardwareErrorCode.BleCharacteristicNotifyError,
             HardwareErrorCode.BleTimeoutError,
+            // A transport setup reset must also stop this outer poll.
+            HardwareErrorCode.PollingTimeout,
             HardwareErrorCode.BleWriteCharacteristicError,
             HardwareErrorCode.BleAlreadyConnected,
             HardwareErrorCode.FirmwareUpdateLimitOneDevice,
@@ -1296,6 +1335,10 @@ const ensureConnected = async (
             HardwareErrorCode.DeviceInterruptedFromUser,
             HardwareErrorCode.CallQueueActionCancelled,
           ].includes(error.errorCode) ||
+          (env === 'react-native' &&
+            [HardwareErrorCode.BleDeviceDisconnected, HardwareErrorCode.PollingTimeout].includes(
+              error.errorCode
+            )) ||
           isTerminalBleStaleBondError(error) ||
           isDeviceIdentityMismatchError(error)
         ) {
@@ -1774,7 +1817,17 @@ export default class Core extends EventEmitter {
           this.prePendingCallPromises.delete(connectId);
           return;
         }
-        this.prePendingCallPromises.set(connectId, promise);
+        const previous = this.prePendingCallPromises.get(connectId);
+        const cleanupPromise =
+          previous && previous !== promise
+            ? Promise.all([previous, promise]).then(() => undefined)
+            : promise;
+        this.prePendingCallPromises.set(connectId, cleanupPromise);
+        // cancel() is fire-and-forget. Observe failures immediately, while
+        // preserving the rejected barrier for the next caller's safety check.
+        cleanupPromise.catch(error => {
+          Log.warn('Device cancellation cleanup failed', { errorCode: error?.errorCode });
+        });
       },
       removePrePendingCallPromise: (connectId: string, promise: Promise<void>) => {
         if (this.prePendingCallPromises.get(connectId) === promise) {

package/src/data/messages/messages-protocol-v2.json

@@ -11483,6 +11483,7 @@
         "MessageType_DeviceFindMyTokenState": 60450,
         "MessageType_DeviceFindMyTokenUpdate": 60451,
         "MessageType_DeviceFindMyTokenStateGet": 60452,
+        "MessageType_DeviceAnimationControl": 60461,
         "MessageType_DeviceInfoGet": 60600,
         "MessageType_DeviceInfo": 60601,
         "MessageType_DeviceStatusGet": 60602,
@@ -11806,6 +11807,26 @@
         }
       }
     },
+    "DeviceAnimationAction": {
+      "values": {
+        "AnimationAction_Unknown": 0,
+        "AnimationAction_Start": 1,
+        "AnimationAction_Stop": 2
+      }
+    },
+    "DeviceAnimationControl": {
+      "fields": {
+        "action": {
+          "rule": "required",
+          "type": "DeviceAnimationAction",
+          "id": 1
+        },
+        "timeout_ms": {
+          "type": "uint32",
+          "id": 2
+        }
+      }
+    },
     "DeviceFactoryAck": {
       "values": {
         "FACTORY_ACK_SUCCESS": 0,

package/src/device/Device.ts

@@ -297,6 +297,8 @@ export class Device extends EventEmitter {
   /** Resolves only after the active run has completed its release path. */
   private runCleanupPromise?: Promise<void>;
 
+  private userInterruption?: { attempt: number; promise: Promise<void> };
+
   externalState: string[] = [];
 
   unavailableCapabilities: UnavailableCapabilities = {};
@@ -1462,6 +1464,10 @@ export class Device extends EventEmitter {
     this.invalidateProtocolV2RuntimeState();
   }
 
+  waitForRunCleanup(): Promise<void> {
+    return this.runCleanupPromise ?? Promise.resolve();
+  }
+
   async run(fn?: () => Promise<void>, options?: RunOptions) {
     if (this.runPromise) {
       await this.interruptionFromOutside();
@@ -1596,45 +1602,63 @@ export class Device extends EventEmitter {
     }
   }
 
-  async interruptionFromUser() {
+  interruptionFromUser(): Promise<void> {
+    const attempt = this.connectionAttempt;
+    if (this.userInterruption?.attempt === attempt) {
+      return this.userInterruption.promise;
+    }
     const error = ERRORS.TypedError(HardwareErrorCode.DeviceInterruptedFromUser);
-    this.interruptedAttempt = this.connectionAttempt;
+    this.interruptedAttempt = attempt;
     const cleanupPromise = this.runCleanupPromise;
-    const { cancelableAction } = this;
-    if (cancelableAction) {
-      await cancelableAction(error);
-    } else if (this.shouldSendFallbackProtocolCancel()) {
-      await this.commands?.cancelDevice?.().catch(cancelError => {
-        Log.debug('Protocol V2 fallback cancel error', cancelError);
-      });
-    } else if (!this.hasDeviceAcquire()) {
-      // Pairing / connect-native / probe: drop the physical link only.
-      // Never acquire or send protocol Cancel just to abort setup.
-      if (this.mainId && this.deviceConnector?.disconnect) {
-        await this.deviceConnector.disconnect(this.mainId).catch(disconnectError => {
-          Log.debug('Ignored disconnect during user cancel without acquire', disconnectError);
-        });
+    const { cancelableAction, commands, runPromise, deviceConnector, mainId } = this;
+    const sendFallbackCancel = this.shouldSendFallbackProtocolCancel();
+    const acquired = this.hasDeviceAcquire();
+    const promise = (async () => {
+      try {
+        if (cancelableAction) {
+          await cancelableAction(error);
+        } else if (sendFallbackCancel) {
+          await commands?.cancelDevice?.().catch(cancelError => {
+            Log.debug('Protocol V2 fallback cancel error', cancelError);
+          });
+        } else if (!acquired) {
+          // Abort setup without acquiring a session just to send Cancel.
+          if (mainId && deviceConnector?.disconnect) {
+            await deviceConnector.disconnect(mainId);
+          }
+          if (this.connectionAttempt === attempt) this.markTransportDisconnected();
+        }
+        await commands?.cancel();
+      } catch (cleanupError) {
+        Log.warn('User cancellation cleanup failed; disconnecting device', cleanupError);
+        if (mainId && deviceConnector?.disconnect) {
+          await deviceConnector.disconnect(mainId).catch(disconnectError => {
+            Log.debug('User cancellation fallback disconnect failed', disconnectError);
+          });
+        }
+        if (this.connectionAttempt === attempt) this.markTransportDisconnected();
+      } finally {
+        runPromise?.reject(error);
+        if (this.runPromise === runPromise) this.runPromise = null;
+        await cleanupPromise?.catch(() => undefined);
       }
-      this.markTransportDisconnected();
-    }
-    await this.commands?.cancel();
-
-    if (this.runPromise) {
-      this.runPromise.reject(error);
-      this.runPromise = null;
-    }
-    await cleanupPromise?.catch(() => undefined);
+    })();
+    // Keep the settled promise for this attempt so a duplicate close/finally
+    // cannot send a second wire Cancel. A new attempt gets its own cleanup.
+    this.userInterruption = { attempt, promise };
+    return promise;
   }
 
   setCancelableAction(callback: (err?: Error) => Promise<unknown>) {
-    this.cancelableAction = (e?: Error) =>
+    const action = (e?: Error) =>
       callback(e)
         .catch(e2 => {
           Log.debug('cancelableAction error', e2);
         })
         .finally(() => {
-          this.clearCancelableAction();
+          if (this.cancelableAction === action) this.clearCancelableAction();
         });
+    this.cancelableAction = action;
   }
 
   clearCancelableAction() {

package/src/types/api/getFeatures.ts

@@ -2,6 +2,7 @@ import type { CommonParams, Response } from '../params';
 import type { Features } from '../device';
 
 /**
- * @deprecated Use `getDeviceState` for both Protocol V1 and Protocol V2 devices.
+ * @deprecated Use `getDeviceState` for both Protocol V1 and Protocol V2.
+ * Existing calls still work. Read `payload.identity.deviceId` from `getDeviceState`.
  */
 export declare function getFeatures(connectId?: string, params?: CommonParams): Response<Features>;

package/src/types/api/getPassphraseState.ts

@@ -3,11 +3,8 @@ import type { CommonParams, Response } from '../params';
 export type GetPassphraseStateParams = CommonParams;
 
 /**
- * Compatibility wallet-state API for existing App integrations.
- *
- * Protocol V1 keeps its parameterless firmware flow. Protocol V2 maps the existing
- * `useEmptyPassphrase` and `initSession` intent to the device-only wallet-session flow.
- * New integrations should prefer `openWalletSession` for explicit wallet intent.
+ * @deprecated Use `openWalletSession` for both Protocol V1 and Protocol V2.
+ * Existing calls still work. Persist `deviceId + passphraseState`; do not persist firmware `session_id`.
  */
 export declare function getPassphraseState(
   connectId?: string,

package/src/types/api/openWalletSession.ts

@@ -3,28 +3,16 @@ import type { CommonParams, Response } from '../params';
 export const OpenWalletSessionMode = {
   Standard: 'standard',
   SelectHidden: 'select-hidden',
-  ResumeHidden: 'resume-hidden',
 } as const;
 
 export type OpenWalletSessionModeValue =
   (typeof OpenWalletSessionMode)[keyof typeof OpenWalletSessionMode];
 
-export type OpenWalletSessionParams =
-  | {
-      mode: typeof OpenWalletSessionMode.Standard;
-      deviceId?: never;
-      passphraseState?: never;
-    }
-  | {
-      mode: typeof OpenWalletSessionMode.SelectHidden;
-      deviceId?: never;
-      passphraseState?: never;
-    }
-  | {
-      mode: typeof OpenWalletSessionMode.ResumeHidden;
-      deviceId: string;
-      passphraseState: string;
-    };
+export type OpenWalletSessionParams = {
+  mode: OpenWalletSessionModeValue;
+  deviceId?: never;
+  passphraseState?: never;
+};
 
 type OpenWalletSessionPayloadBase = {
   protocol: 'V1' | 'V2';
@@ -45,8 +33,8 @@ export type OpenWalletSessionPayload = OpenWalletSessionPayloadBase &
   );
 
 /**
- * Opens the standard, hidden, or Attach-to-PIN wallet flow through a unified
- * Protocol V1/V2 API.
+ * Opens the standard or hidden wallet through a unified Protocol V1/V2 API.
+ * Resume a bound hidden wallet by passing passphraseState on later methods.
  */
 export declare function openWalletSession(
   connectId: string,

package/src/types/params.ts

@@ -1,6 +1,13 @@
 import type { HardwareConnectProtocol } from '@onekeyfe/hd-shared';
 
 export interface CommonParams {
+  /**
+   * Keep the transport session after this call instead of releasing it.
+   * This is a Device.run() hold flag, not a wallet identity. It does not replace
+   * `useEmptyPassphrase`, `passphraseState`, or `openWalletSession`.
+   * USB multi-step flows and Electron BLE firmware windows still need this to
+   * avoid dropping the link between calls.
+   */
   keepSession?: boolean;
   /**
    * polling connect max retry count