@onekeyfe/hd-core 1.2.3-alpha.1 → 1.2.3-alpha.11

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,
@@ -83,7 +84,8 @@ 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 PRE_PENDING_CALL_TIMEOUT_MS = 5 * 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.
@@ -181,6 +183,7 @@ export const callAPI = async (context: CoreContext, message: CoreMessage) => {
       }
     };
     method.setContext?.(context);
+    method.context = context;
 
     method.requestContext = createRequestContext(method.responseID, method.name, {
       sdkInstanceId: context.sdkInstanceId,
@@ -201,7 +204,12 @@ export const callAPI = async (context: CoreContext, message: CoreMessage) => {
   if (!method.useDevice) {
     updateMethodRequestContext(method, { status: 'running' });
     try {
-      const response = await method.run();
+      const env = DataManager.getSettings('env');
+      const response =
+        method.name === 'searchDevices' &&
+        (DataManager.isBrowserWebUsb(env) || DataManager.isDesktopWebUsb(env))
+          ? await context.methodSynchronize(() => method.run(), 'webusb-discovery')
+          : await method.run();
       completeMethodRequestContext(method);
       return createResponseMessage(method.responseID, true, response);
     } catch (error) {
@@ -314,6 +322,7 @@ const waitForPendingPromise = async (
     Log.debug('pre pending call promise before call method, wait for it');
     let timer: ReturnType<typeof setTimeout> | undefined;
     let timedOut = false;
+    let completed = false;
     try {
       await Promise.race([
         pendingPromise,
@@ -324,11 +333,12 @@ const waitForPendingPromise = async (
           }, PRE_PENDING_CALL_TIMEOUT_MS);
         }),
       ]);
-    } catch (error) {
-      // Cancellation is best-effort; the transport teardown owns recovery.
+      completed = !timedOut;
     } finally {
       if (timer) clearTimeout(timer);
-      removePrePendingCallPromise?.(connectId, pendingPromise);
+      // Keep a rejected cleanup barrier for the next caller's safety check;
+      // only a completed cleanup or a timeout may clear it.
+      if (timedOut || completed) removePrePendingCallPromise?.(connectId, pendingPromise);
     }
     if (timedOut) {
       Log.warn('pre pending call promise timed out before call method', { connectId });
@@ -337,6 +347,20 @@ const waitForPendingPromise = async (
   }
 };
 
+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 +391,57 @@ 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
-    );
+    const env = DataManager.getSettings('env');
+    const connect = () =>
+      ensureConnected(context, method, connectId, pollingId, method.abortSignal);
+    // Discovery may acquire USB endpoints. Finish it before initializing a public
+    // request; once registered, that request makes discovery use cached state only.
+    if (DataManager.isBrowserWebUsb(env) || DataManager.isDesktopWebUsb(env)) {
+      // Synchronization can keep the connect action queued after the caller is
+      // cancelled. Observe that promise so a late device-not-found error does
+      // not become an unhandled rejection.
+      const connectPromise = context.methodSynchronize(async () => {
+        if (method.abortSignal?.aborted) {
+          throw ERRORS.TypedError(HardwareErrorCode.CallQueueActionCancelled);
+        }
+        return connect();
+      }, 'webusb-discovery');
+      connectPromise.catch(() => undefined);
+      device = await requestQueue.waitForTask(task, () => connectPromise);
+    } else {
+      device = await connect();
+    }
+    if (method.abortSignal?.aborted) {
+      throw ERRORS.TypedError(HardwareErrorCode.CallQueueActionCancelled);
+    }
   } catch (e) {
     preWarmCallbackTask?.resolve();
     Log.debug('ensureConnected error: ', e);
@@ -478,14 +517,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 +734,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 +752,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 +784,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 +807,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 +1105,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 +1174,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
@@ -1163,6 +1227,7 @@ const ensureConnected = async (
   const POLL_INTERVAL_TIME = (method.payload && method.payload.pollIntervalTime) || 1000;
   const TIME_OUT = (method.payload && method.payload.timeout) || 10000;
   let timer: ReturnType<typeof setTimeout> | null = null;
+  let lastInitializeError: any;
   Log.debug(
     `EnsureConnected function start, MAX_RETRY_COUNT=${MAX_RETRY_COUNT}, POLL_INTERVAL_TIME=${POLL_INTERVAL_TIME}  `
   );
@@ -1203,7 +1268,9 @@ const ensureConnected = async (
       Log.debug('EnsureConnected function try count: ', tryCount, ' poll interval time: ', time);
       try {
         await initDeviceList(method);
+        lastInitializeError = undefined;
       } catch (error) {
+        lastInitializeError = error;
         Log.debug('device list error: ', error);
         if (
           [
@@ -1218,6 +1285,7 @@ const ensureConnected = async (
         }
         if (error.errorCode === HardwareErrorCode.TransportNotConfigured) {
           await TransportManager.configure();
+          lastInitializeError = undefined;
         }
       }
 
@@ -1286,6 +1354,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 +1366,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)
         ) {
@@ -1309,14 +1383,22 @@ const ensureConnected = async (
           clearTimeout(timer);
         }
         Log.debug('EnsureConnected get to max try count, will return: ', tryCount);
-        // Browser WebUSB needs permission prompt, desktop WebUSB doesn't
-        // skipWebDevicePrompt can override this behavior for special cases
-        if (DataManager.isBrowserWebUsb(env) && !method.payload?.skipWebDevicePrompt) {
+        const preserveWebUsbInitError =
+          DataManager.isBrowserWebUsb(env) || DataManager.isDesktopWebUsb(env);
+        const needsPermissionPrompt =
+          DataManager.isBrowserWebUsb(env) && !method.payload?.skipWebDevicePrompt;
+        const fallbackError = needsPermissionPrompt
+          ? ERRORS.TypedError(HardwareErrorCode.WebDeviceNotFoundOrNeedsPermission)
+          : ERRORS.TypedError(HardwareErrorCode.DeviceNotFound);
+        const errorToReject =
+          preserveWebUsbInitError && lastInitializeError ? lastInitializeError : fallbackError;
+        // Only ask the host for a WebUSB grant when the failure is actually
+        // "not found / needs permission". A preserved initialize error must
+        // not fire that prompt with a different public code.
+        if (needsPermissionPrompt && errorToReject === fallbackError) {
           postMessage(createUiMessage(UI_REQUEST.WEB_DEVICE_PROMPT_ACCESS_PERMISSION));
-          reject(ERRORS.TypedError(HardwareErrorCode.WebDeviceNotFoundOrNeedsPermission));
-        } else {
-          reject(ERRORS.TypedError(HardwareErrorCode.DeviceNotFound));
         }
+        reject(errorToReject);
         return;
       }
 
@@ -1774,7 +1856,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/data-manager/TransportManager.ts

@@ -33,6 +33,8 @@ export default class TransportManager {
 
   static reactNativeInit = false;
 
+  static webUsbInit = false;
+
   static protocolV1MessageSchema: ProtocolV1MessageSchema = 'v1CurrentSchema';
 
   static plugin: LowlevelTransportSharedPlugin | null = null;
@@ -42,6 +44,17 @@ export default class TransportManager {
     this.defaultMessages = DataManager.getProtobufMessages();
     this.currentMessages = this.defaultMessages;
     this.protocolV1MessageSchema = 'v1CurrentSchema';
+    this.webUsbInit = false;
+  }
+
+  static async ensureInitialized() {
+    const env = DataManager.getSettings('env');
+    if (env !== 'webusb' && env !== 'desktop-webusb') return;
+    if (this.webUsbInit) return;
+    // The emitter registers USB disconnect events; this must happen even when
+    // schema configuration is intentionally deferred during discovery.
+    await this.transport.init(WebUsbLogger, DevicePool.emitter);
+    this.webUsbInit = true;
   }
 
   static async configure() {
@@ -69,9 +82,7 @@ export default class TransportManager {
       } else if (env === 'desktop-web-ble') {
         await this.transport.init(WebBleLogger, DevicePool.emitter);
       } else if (env === 'webusb' || env === 'desktop-webusb') {
-        // The emitter is what turns a navigator.usb 'disconnect' into a
-        // DEVICE.DISCONNECT; without it WebUSB never reports device removal.
-        await this.transport.init(WebUsbLogger, DevicePool.emitter);
+        await this.ensureInitialized();
       } else {
         await this.transport.init(HttpLogger);
       }

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,70 @@ 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) {
+            // The connector drops the link silently, so without this line a
+            // user-cancel teardown is indistinguishable in field logs from an
+            // idle keep-alive release or a device that left on its own.
+            Log.debug(
+              'interruptionFromUser: disconnecting device without acquire, mainId:',
+              mainId
+            );
+            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/protocols/protocol-v2/walletSession.ts

@@ -268,6 +268,7 @@ export async function getProtocolV2WalletSession(
       ? device.getInternalState()
       : undefined;
   let response;
+  let walletSelectionRequested = false;
   let resumed = false;
   let walletStatusRefreshed = false;
   const markWalletStatusRefreshed = () => {
@@ -482,6 +483,7 @@ export async function getProtocolV2WalletSession(
       throw ERRORS.TypedError(HardwareErrorCode.WalletSessionInvalid);
     }
     await lockAttachPinBeforePassphraseSelection();
+    walletSelectionRequested = true;
     response = await selectDeviceSession(
       device,
       expectedPassphraseState,
@@ -508,6 +510,11 @@ export async function getProtocolV2WalletSession(
       device.clearInternalState();
       throw ERRORS.TypedError(HardwareErrorCode.WalletSessionInvalid);
     }
+    // Report a fresh selection mismatch before asking for input again.
+    if (walletSelectionRequested) {
+      clearCurrentWalletSession();
+      throw ERRORS.TypedError(HardwareErrorCode.DeviceCheckPassphraseStateError);
+    }
     if (options?.onlyMainPin) {
       device.clearStandardInternalState?.();
       await selectStandardWallet(true);

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