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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onekeyfe/hd-core",
-  "version": "1.2.2-alpha.105",
+  "version": "1.2.2-alpha.106",
   "description": "Core processes and APIs for communicating with OneKey hardware devices.",
   "author": "OneKey",
   "homepage": "https://github.com/OneKeyHQ/hardware-js-sdk#readme",
@@ -25,8 +25,8 @@
     "url": "https://github.com/OneKeyHQ/hardware-js-sdk/issues"
   },
   "dependencies": {
-    "@onekeyfe/hd-shared": "1.2.2-alpha.105",
-    "@onekeyfe/hd-transport": "1.2.2-alpha.105",
+    "@onekeyfe/hd-shared": "1.2.2-alpha.106",
+    "@onekeyfe/hd-transport": "1.2.2-alpha.106",
     "axios": "1.15.2",
     "bignumber.js": "^9.0.2",
     "buffer": "^6.0.3",
@@ -46,5 +46,5 @@
     "@types/w3c-web-usb": "^1.0.10",
     "@types/web-bluetooth": "^0.0.21"
   },
-  "gitHead": "16dcd1b1a3d6687019947f22235522feb1d79095"
+  "gitHead": "e52ad091098aaab6b2845154457ace5e2f8c9098"
 }

package/src/api/GetFeatures.ts

@@ -4,6 +4,7 @@ import { UI_REQUEST } from '../constants/ui-request';
 import { projectFeatures } from '../device/DeviceStateProjector';
 import { BaseMethod } from './BaseMethod';
 
+/** @deprecated Use GetDeviceState / HardwareSDK.getDeviceState. */
 export default class GetFeatures extends BaseMethod {
   init() {
     this.unlockPolicy = 'none';

package/src/api/GetPassphraseState.ts

@@ -6,6 +6,7 @@ import { refreshProtocolV2DeviceStatus } from '../protocols/protocol-v2/walletSe
 import { getPassphraseStateWithRefreshDeviceInfo } from '../utils/deviceFeaturesUtils';
 import { BaseMethod } from './BaseMethod';
 
+/** @deprecated Use OpenWalletSession / HardwareSDK.openWalletSession. */
 export default class GetPassphraseState extends BaseMethod {
   getSupportedProtocols() {
     return ['V1', 'V2'] as const;

package/src/api/OpenWalletSession.ts

@@ -1,7 +1,6 @@
 import { ERRORS, HardwareErrorCode } from '@onekeyfe/hd-shared';
 import { DeviceSessionPinType } from '@onekeyfe/hd-transport';
 
-import { deviceWalletSessionStore } from '../device/DeviceWalletSessionStore';
 import { getProtocolV2WalletSession } from '../protocols/protocol-v2/walletSession';
 import { getPassphraseStateWithRefreshDeviceInfo } from '../utils/deviceFeaturesUtils';
 import { BaseMethod } from './BaseMethod';
@@ -13,16 +12,6 @@ import type {
   OpenWalletSessionPayload,
 } from '../types/api/openWalletSession';
 
-const requiredString = (value: unknown, name: string) => {
-  if (value === undefined || value === null) {
-    throw invalidParameter(`Missing required parameter: ${name}`);
-  }
-  if (typeof value !== 'string' || !value.trim()) {
-    throw invalidParameter(`Parameter [${name}] must be a non-empty string.`);
-  }
-  return value.trim();
-};
-
 const wasResumed = (session: unknown) =>
   !!session &&
   typeof session === 'object' &&
@@ -53,34 +42,21 @@ const normalizeParams = (payload: Record<string, unknown>): OpenWalletSessionPar
   }
   if (
     payload.mode !== OpenWalletSessionMode.Standard &&
-    payload.mode !== OpenWalletSessionMode.SelectHidden &&
-    payload.mode !== OpenWalletSessionMode.ResumeHidden
+    payload.mode !== OpenWalletSessionMode.SelectHidden
   ) {
-    throw invalidParameter(
-      'Parameter [mode] must be one of standard, select-hidden, or resume-hidden.'
-    );
+    throw invalidParameter('Parameter [mode] must be one of standard or select-hidden.');
   }
   if (payload.useEmptyPassphrase !== undefined || payload.initSession !== undefined) {
     throw invalidParameter(
       'Legacy parameters [useEmptyPassphrase] and [initSession] are not supported by openWalletSession.'
     );
   }
-  if (
-    payload.mode === OpenWalletSessionMode.Standard ||
-    payload.mode === OpenWalletSessionMode.SelectHidden
-  ) {
-    if (payload.deviceId !== undefined || payload.passphraseState !== undefined) {
-      throw invalidParameter(
-        'Parameters [deviceId] and [passphraseState] are only allowed with mode [resume-hidden].'
-      );
-    }
-    return { mode: payload.mode };
+  if (payload.deviceId !== undefined || payload.passphraseState !== undefined) {
+    throw invalidParameter(
+      'Parameters [deviceId] and [passphraseState] are not supported by openWalletSession. Pass passphraseState on later address and signing calls.'
+    );
   }
-  return {
-    mode: OpenWalletSessionMode.ResumeHidden,
-    deviceId: requiredString(payload.deviceId, 'deviceId'),
-    passphraseState: requiredString(payload.passphraseState, 'passphraseState'),
-  };
+  return { mode: payload.mode };
 };
 
 export default class OpenWalletSession extends BaseMethod<OpenWalletSessionParams> {
@@ -196,52 +172,6 @@ export default class OpenWalletSession extends BaseMethod<OpenWalletSessionParam
       };
     }
 
-    if (this.params.mode === OpenWalletSessionMode.ResumeHidden) {
-      if (isProtocolV2) {
-        await ensureProtocolV2WalletStatus();
-        const refreshedDeviceId = requireDeviceId();
-        if (refreshedDeviceId !== this.params.deviceId) {
-          deviceWalletSessionStore.delete(this.params.deviceId, this.params.passphraseState);
-          throw ERRORS.TypedError(HardwareErrorCode.DeviceCheckDeviceIdError);
-        }
-      } else if (requireDeviceId() !== this.params.deviceId) {
-        throw ERRORS.TypedError(HardwareErrorCode.DeviceCheckDeviceIdError);
-      }
-      this.device.passphraseState = this.params.passphraseState;
-      const cachedSessionId = deviceWalletSessionStore.get(
-        this.params.deviceId,
-        this.params.passphraseState
-      );
-      if (!cachedSessionId && !isProtocolV2) {
-        throw ERRORS.TypedError(HardwareErrorCode.WalletSessionInvalid);
-      }
-      if (!isProtocolV2) {
-        await this.device.initialize({
-          deviceId: this.params.deviceId,
-          passphraseState: this.params.passphraseState,
-        });
-      }
-      const session = isProtocolV2
-        ? await getProtocolV2WalletSession(this.device, {
-            expectedPassphraseState: this.params.passphraseState,
-          })
-        : await getPassphraseStateWithRefreshDeviceInfo(this.device, {
-            expectPassphraseState: this.params.passphraseState,
-          });
-      const deviceId = requireDeviceId();
-      if (session.passphraseState !== this.params.passphraseState) {
-        this.device.clearInternalState();
-        throw ERRORS.TypedError(HardwareErrorCode.DeviceCheckPassphraseStateError);
-      }
-      return {
-        protocol,
-        walletType: 'hidden',
-        deviceId,
-        ...requireHiddenWalletResponse(session),
-        resumed: wasResumed(session) || (!isProtocolV2 && session.newSession === cachedSessionId),
-      };
-    }
-
     this.device.passphraseState = undefined;
     const walletStatus = await ensureProtocolV2WalletStatus();
     if (isProtocolV2 && walletStatus.status.passphraseProtection !== true) {

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/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