@onekeyfe/hd-core 1.2.0-alpha.7 → 1.2.0-alpha.71

package/src/device/Device.ts

@@ -1,39 +1,45 @@
 import EventEmitter from 'events';
 import semver from 'semver';
-import { Enum_Capability } from '@onekeyfe/hd-transport';
+import { DeviceRebootType, DeviceSessionPinType, Enum_Capability } from '@onekeyfe/hd-transport';
 import {
   EDeviceType,
+  EFirmwareType,
   ERRORS,
   ERROR_CODES_REQUIRE_DISCONNECT,
   ERROR_CODES_REQUIRE_RELEASE,
   HardwareError,
   HardwareErrorCode,
   createDeferred,
+  createDeviceNotSupportMethodError,
 } from '@onekeyfe/hd-shared';
 
-import {
-  LoggerNames,
-  getDeviceBLEFirmwareVersion,
-  getDeviceBleName,
-  getDeviceFirmwareVersion,
-  getDeviceLabel,
-  getDeviceType,
-  getDeviceUUID,
-  getFirmwareType,
-  getLogger,
-} from '../utils';
+import { LoggerNames, getLogger } from '../utils';
 import {
   fixFeaturesFirmwareVersion,
   getPassphraseStateWithRefreshDeviceInfo,
-  supportInputPinOnSoftware,
-  supportModifyHomescreen,
 } from '../utils/deviceFeaturesUtils';
+import { parseDeviceVersion } from '../utils/deviceVersionUtils';
 import { generateInstanceId } from '../utils/tracing';
 // eslint-disable-next-line import/no-cycle
 import { DeviceCommands } from './DeviceCommands';
+import { mergeDeviceFeaturesPatch } from './DeviceFeaturesState';
+import {
+  mapDeviceSettingsToState,
+  mapFeaturesToState,
+  mapProtocolV1OnekeyFeaturesToState,
+  mapProtocolV2DeviceInfoToState,
+  mapProtocolV2DeviceStatusToState,
+} from './DeviceStateMapper';
+import { projectFeatures } from './DeviceStateProjector';
+import { DeviceStateStore, createPublicDeviceState } from './DeviceStateStore';
+import { cloneDeviceState } from './cloneDeviceState';
+import { deviceWalletSessionStore } from './DeviceWalletSessionStore';
 import {
   type DeviceFirmwareRange,
   DeviceModelToTypes,
+  type DeviceStateEvent,
+  type DeviceStatePatch,
+  type DeviceStateUpdateSource,
   DeviceTypeToModels,
   type Device as DeviceTyped,
   EOneKeyDeviceMode,
@@ -48,23 +54,36 @@ import { DEVICE, UI_REQUEST } from '../events';
 import { DataManager } from '../data-manager';
 import TransportManager from '../data-manager/TransportManager';
 import { toHardened } from '../api/helpers/pathUtils';
-import { existCapability } from '../utils/capabilitieUtils';
 import {
-  PROTOCOL_V2_STATUS_DEVICE_INFO_REQUEST,
+  PROTOCOL_V2_DEVICE_STATUS_GET_MESSAGE_TYPE,
+  PROTOCOL_V2_FEATURES_DEVICE_INFO_REQUEST,
+  PROTOCOL_V2_FULL_DEVICE_INFO_REQUEST,
+  PROTOCOL_V2_VERSIONS_DEVICE_INFO_REQUEST,
+  type ProtocolV2RuntimeMode,
+  getProtocolV2RuntimeMode,
   requestProtocolV2DeviceInfo,
+  requestProtocolV2DeviceStatus,
+  requestProtocolV2ProtocolInfo,
+  supportsProtocolV2Message,
 } from '../protocols/protocol-v2/features';
-import { buildProtocolV1FeaturesPayload, buildProtocolV2FeaturesPayload } from '../deviceProfile';
+import { buildProtocolV1FeaturesPayload } from '../deviceProfile';
+import { resolveProtocolV2DeviceIdentity } from '../deviceProfile/protocolV2DeviceIdentity';
 
 import type { PROTO } from '../constants';
+import type { DeviceStateReadOptions } from '../types/api/getDeviceState';
 import type {
   DeviceButtonRequestPayload,
   DeviceFeaturesPayload,
+  HardwareUiInteractionMeta,
   PassphraseRequestPayload,
+  ProtocolV2UiEventMetadata,
 } from '../events';
 import type { PassphrasePromptResponse } from './DeviceCommands';
 import type { Deferred, HardwareConnectProtocol } from '@onekeyfe/hd-shared';
 import type {
   OneKeyDeviceInfo as DeviceDescriptor,
+  DeviceStatus,
+  ProtocolInfo,
   ProtocolV2DeviceInfo,
   Success,
 } from '@onekeyfe/hd-transport';
@@ -76,7 +95,15 @@ export type InitOptions = {
   passphraseState?: string;
   deriveCardano?: boolean;
   connectProtocol?: HardwareConnectProtocol;
+  forceProtocolDetection?: boolean;
   protocolV2DeviceInfoTimeoutMs?: number;
+  /** Refresh Protocol V2 runtime state before returning discovery results. */
+  refreshRuntimeState?: boolean;
+  /**
+   * Protocol V1 Initialize response timeout override. Reboot-wait polling passes a
+   * short value so an unanswered probe settles before the next poll tick.
+   */
+  timeoutMs?: number;
 };
 
 export type RunOptions = {
@@ -91,11 +118,35 @@ const parseRunOptions = (options?: RunOptions): RunOptions => {
 
 const Log = getLogger(LoggerNames.Device);
 
+const isProtocolV2DeviceStatusUnsupportedError = (error: unknown) => {
+  if (error instanceof HardwareError) {
+    if (error.errorCode === HardwareErrorCode.DeviceNotSupportMethod) {
+      return true;
+    }
+    if (error.params?.failureCode === 'Failure_UnexpectedMessage') {
+      return true;
+    }
+  }
+
+  const message =
+    error instanceof Error
+      ? error.message
+      : String((error as { message?: unknown } | null)?.message ?? error ?? '');
+  return (
+    /^Failure_UnexpectedMessage(?:,|\b)/i.test(message) ||
+    /\b(?:unsupported message|handler not registered|message handler not found)\b/i.test(message)
+  );
+};
+
 export interface DeviceEvents {
   [DEVICE.PIN]: [Device, PROTO.PinMatrixRequestType | undefined, (err: any, pin: string) => void];
-  [DEVICE.PASSPHRASE_ON_DEVICE]: [Device, ((response: any) => void)?];
+  [DEVICE.PIN_ON_DEVICE]: [Device, DeviceSessionPinType, ProtocolV2UiEventMetadata?];
+  [DEVICE.PIN_ON_DEVICE_COMPLETE]: [Device, HardwareUiInteractionMeta];
+  [DEVICE.PASSPHRASE_ON_DEVICE]: [Device, PassphraseRequestPayload?];
+  [DEVICE.ATTACH_PIN_ON_DEVICE]: [Device, PassphraseRequestPayload?];
   [DEVICE.BUTTON]: [Device, DeviceButtonRequestPayload];
   [DEVICE.FEATURES]: [Device, DeviceFeaturesPayload];
+  [DEVICE.STATE]: [Device, DeviceStateEvent];
   [DEVICE.PASSPHRASE]: [
     Device,
     PassphraseRequestPayload,
@@ -119,15 +170,14 @@ export interface Device {
   emit<K extends keyof DeviceEvents>(type: K, ...args: DeviceEvents[K]): boolean;
 }
 
-const deviceSessionCache: Record<string, string> = {};
-
 /**
  * Pre-populate the device session cache with a known session ID.
  *
  * This allows short-lived processes (e.g. CLI) to restore a previously
  * obtained session, avoiding the need to re-enter passphrase on every
  * invocation. The session must have been obtained from a prior
- * getPassphraseState() call on the same device.
+ * wallet-session call on the same device. This compatibility hook is intended
+ * for a trusted CLI process restoring its own OS-keychain entry.
  *
  * @param deviceId - The device's device_id (from features)
  * @param passphraseState - The passphrase state token
@@ -138,8 +188,7 @@ export function preloadSessionCache(
   passphraseState: string,
   sessionId: string
 ): void {
-  const key = `${deviceId}@${passphraseState}`;
-  deviceSessionCache[key] = sessionId;
+  deviceWalletSessionStore.set(deviceId, passphraseState, sessionId);
 }
 
 export class Device extends EventEmitter {
@@ -185,22 +234,52 @@ export class Device extends EventEmitter {
    */
   private deviceAcquired = false;
 
-  /**
-   * 唯一设备状态缓存。
-   *
-   * V1 直接保存原生 Features；V2 保存由 DeviceInfoGet 映射出的
-   * Features 视图。Device 不再保存 profile，结构化 DeviceProfile 只作为
-   * getDeviceInfo() 的 API 返回值存在。
-   */
-  features: Features | undefined = undefined;
+  /** Canonical device-state cache; legacy Features is a compatibility projection. */
+  private stateStore = new DeviceStateStore();
 
-  /**
-   * 是否需要更新设备信息。
-   *
-   * 历史名称保留用于兼容现有调用语义；对 V2 表示 features 需要由
-   * DeviceInfoGet 刷新。
-   */
-  featuresNeedsReload = false;
+  /** Force the next initialization to reload DeviceInfo after reconnect or reboot. */
+  private protocolV2StateNeedsReload = false;
+
+  /** Runtime context negotiated once per active Protocol V2 link. */
+  private protocolV2RuntimeContext?: ProtocolInfo;
+
+  /** Coalesces concurrent first-use runtime negotiation on the same active link. */
+  private protocolV2RuntimeContextPromise?: Promise<ProtocolInfo>;
+
+  /** Invalidates an in-flight runtime-context response without adding a transport epoch. */
+  private protocolV2RuntimeContextRequestToken?: object;
+
+  private protocolV2UiInteraction?: {
+    interactionId: string;
+    phaseCounter: number;
+    sequence: number;
+    opened: boolean;
+  };
+
+  private protocolV2UiInteractionCounter = 0;
+
+  get state() {
+    return this.stateStore.getState();
+  }
+
+  get features(): Features | undefined {
+    if (!this.state) return undefined;
+    return projectFeatures(this.state);
+  }
+
+  set features(features: Features | undefined) {
+    this.stateStore = new DeviceStateStore();
+    if (features) {
+      this.stateStore.update(mapFeaturesToState(features), 'compatibility');
+      const { passphraseState } = features;
+      const sessionId = features.sessionId ?? features.session_id;
+      const deviceKey = this.getSessionCacheDeviceKey(features.deviceId ?? undefined);
+      if (passphraseState && sessionId && deviceKey) {
+        this.passphraseState = passphraseState;
+        deviceWalletSessionStore.set(deviceKey, passphraseState, sessionId);
+      }
+    }
+  }
 
   runPromise?: Deferred<void> | null;
 
@@ -254,38 +333,46 @@ export class Device extends EventEmitter {
 
   // simplified object to pass via postMessage
   toMessageObject(): DeviceTyped | null {
-    if (this.isUnacquired()) return null;
+    if (this.isUnacquired() || !this.features) return null;
 
     const env = DataManager.getSettings('env');
     const deviceType = this.getCurrentDeviceType();
 
     const bleName = this.getCurrentBleName();
-    const label = this.getCurrentLabel();
+    const displayName = this.getCurrentDisplayName();
     const serialNo = this.getCurrentSerialNo();
     const connectId = this.getConnectId();
     const deviceId = this.getCurrentDeviceId() || null;
 
-    const features = this.features;
+    const { features } = this;
+    const state = this.state ? createPublicDeviceState(this.state) : undefined;
 
     return {
-      /** Android uses Mac address, iOS uses uuid, USB uses uuid  */
+      /** Android uses a MAC address, while iOS and USB use transport-specific identifiers. */
       connectId: DataManager.isBleConnect(env) ? this.mainId || null : connectId,
-      /** Hardware ID, will not change at any time */
+      /** Persist this after the first active probe so later calls do not need to guess. */
+      connectProtocol: this.originalDescriptor.protocolType,
+      /** Stable physical-device identity. */
+      serialNo,
+      /** @deprecated Use serialNo instead. */
       uuid: serialNo,
       commType: this.originalDescriptor.commType,
       sdkInstanceId: this.sdkInstanceId,
       instanceId: this.instanceId,
       createdAt: this.createdAt,
       deviceType,
-      /** ID for current seeds, will clear after replace a new seed at device */
+      /** Wallet-lifecycle ID; changes after the device is wiped or reinitialized. */
       deviceId,
       path: this.originalDescriptor?.path,
       bleName,
-      name: bleName || label || `OneKey ${deviceType?.toUpperCase()}`,
-      label: label || 'OneKey',
+      name: bleName || displayName || `OneKey ${deviceType?.toUpperCase()}`,
+      // Keep the legacy top-level field string-compatible while preserving
+      // the canonical nullable value at state.identity.label.
+      label: displayName ?? '',
+      status: this.getStatus(),
       mode: this.getMode(),
       features,
-      sessionId: this.features?.sessionId ?? null,
+      state,
       firmwareVersion: this.getFirmwareVersion(),
       bleFirmwareVersion: this.getBLEFirmwareVersion(),
       unavailableCapabilities: this.unavailableCapabilities,
@@ -296,13 +383,20 @@ export class Device extends EventEmitter {
    * Device connect
    * @returns {Promise<boolean>}
    */
-  connect(connectProtocol?: HardwareConnectProtocol) {
+  connect(
+    connectProtocol?: HardwareConnectProtocol,
+    options?: { forceProtocolDetection?: boolean }
+  ) {
     const env = DataManager.getSettings('env');
     // eslint-disable-next-line no-async-promise-executor
     return new Promise<boolean>(async (resolve, reject) => {
       if (DataManager.isBleConnect(env)) {
+        if (this.hasDeviceAcquire() && this.commands && !this.commands.disposed) {
+          resolve(true);
+          return;
+        }
         try {
-          await this.acquire(connectProtocol);
+          await this.acquire(connectProtocol, options);
           resolve(true);
         } catch (error) {
           reject(error);
@@ -312,7 +406,7 @@ export class Device extends EventEmitter {
       // 不存在 Session ID 或存在 Session ID 但设备在别处使用，都需要 acquire 获取最新 sessionID
       if (!this.mainId || (!this.isUsedHere() && this.originalDescriptor)) {
         try {
-          await this.acquire(connectProtocol);
+          await this.acquire(connectProtocol, options);
           resolve(true);
         } catch (error) {
           reject(error);
@@ -328,25 +422,30 @@ export class Device extends EventEmitter {
   }
 
   async acquire(
-    connectProtocol?: HardwareConnectProtocol,
-    options?: { throwOnRunPromiseError?: boolean }
+    expectedProtocol?: HardwareConnectProtocol,
+    options?: { throwOnRunPromiseError?: boolean; forceProtocolDetection?: boolean }
   ) {
     const env = DataManager.getSettings('env');
     const mainIdKey = DataManager.isBleConnect(env) ? 'id' : 'session';
-    const expectedProtocol = connectProtocol ?? this.originalDescriptor.protocolType;
+    const previousProtocol = this.originalDescriptor.protocolType;
+    // A protocol stored after a successful probe is authoritative. Only the explicit
+    // first-connection/recovery path may bypass it and probe both protocols again.
+    const strictProtocol = options?.forceProtocolDetection
+      ? undefined
+      : expectedProtocol ?? this.originalDescriptor.protocolType;
     try {
       let acquireResult: unknown;
       if (DataManager.isBleConnect(env)) {
-        // forceCleanRunPromise=true（自 e21b83c6 引入，修复 Pro2 BLE 重连）：
-        // acquire 意味着开启一个全新会话，transport 里残留的上一次 runPromise
-        // 必然属于已死亡的会话（如固件升级重启、探测中断），不清理会让新会话的
-        // 调用被旧 promise 卡死。无法在 Device 层面区分“重连恢复”与普通 acquire，
-        // 因此对 BLE acquire 恒清理是有意为之。
+        // acquire starts a new BLE session. Any previous runPromise belongs to a dead
+        // session, such as an interrupted probe or firmware-update reboot, and would
+        // otherwise block the new session. Device cannot distinguish recovery from a
+        // regular acquire, so BLE always clears it intentionally.
         acquireResult = await this.deviceConnector?.acquire(
           this.originalDescriptor.id,
           undefined,
           true,
-          expectedProtocol
+          strictProtocol,
+          undefined
         );
         this.mainId = (acquireResult as any)?.uuid ?? '';
         Log.debug('Expected uuid:', this.mainId);
@@ -355,23 +454,31 @@ export class Device extends EventEmitter {
           this.originalDescriptor.path,
           this.originalDescriptor.session,
           undefined,
-          expectedProtocol
+          strictProtocol,
+          undefined
         );
         this.mainId = acquireResult as string | undefined;
         Log.debug('Expected session id:', this.mainId);
       }
-      this.deviceAcquired = true;
-      this.updateDescriptor({ [mainIdKey]: this.mainId } as unknown as DeviceDescriptor);
-
       // Propagate protocol version detected during acquire.
       const detectedProtocol =
         (acquireResult as { protocolType?: HardwareConnectProtocol } | undefined)?.protocolType ??
         TransportManager.transport?.getProtocolType?.(
           DataManager.isBleConnect(env) ? this.originalDescriptor.id : this.originalDescriptor.path
         );
+      if (options?.forceProtocolDetection && !detectedProtocol) {
+        throw ERRORS.TypedError(
+          HardwareErrorCode.RuntimeError,
+          `Active protocol detection returned no protocol for ${
+            this.originalDescriptor.path || this.originalDescriptor.id
+          }`
+        );
+      }
       if (detectedProtocol) {
         this.originalDescriptor.protocolType = detectedProtocol;
       }
+      this.deviceAcquired = true;
+      this.updateDescriptor({ [mainIdKey]: this.mainId } as unknown as DeviceDescriptor);
 
       if (this.commands) {
         await this.commands.dispose(false);
@@ -379,6 +486,22 @@ export class Device extends EventEmitter {
 
       this.commands = new DeviceCommands(this, this.mainId ?? '');
     } catch (error) {
+      if (options?.forceProtocolDetection) {
+        this.originalDescriptor.protocolType = previousProtocol;
+        const failedSession = this.mainId;
+        this.deviceAcquired = false;
+        if (failedSession) {
+          try {
+            await this.deviceConnector?.release?.(failedSession, false);
+          } catch (releaseError) {
+            Log.debug('Failed to release an unsuccessful protocol probe', releaseError);
+          }
+        }
+        if (!DataManager.isBleConnect(env)) {
+          this.mainId = null;
+          this.updateDescriptor({ session: null } as DeviceDescriptor);
+        }
+      }
       if (options?.throwOnRunPromiseError) {
         throw error;
       }
@@ -482,12 +605,11 @@ export class Device extends EventEmitter {
   }
 
   /**
-   * 唯一协议判别器。
+   * Canonical protocol discriminator.
    *
-   * descriptor.protocolType 是协议探测后的结果；V2 features 由 DeviceInfoGet
-   * 映射产生。
-   * 全 SDK 的协议分支都必须走这里，不要直接读 originalDescriptor.protocolType
-   * 或从 features 反推。
+   * descriptor.protocolType is established by active probing; V2 features are mapped
+   * from DeviceInfoGet. All protocol branches must use this method instead of reading
+   * originalDescriptor.protocolType directly or inferring a protocol from features.
    */
   getProtocol(): 'V1' | 'V2' {
     return this.originalDescriptor.protocolType === 'V2' ? 'V2' : 'V1';
@@ -498,53 +620,75 @@ export class Device extends EventEmitter {
   }
 
   getCurrentDeviceType() {
-    return getDeviceType(this.features);
+    return this.state?.identity.deviceType ?? EDeviceType.Unknown;
   }
 
   getCurrentDeviceId() {
-    return this.features?.deviceId || undefined;
+    return this.state?.identity.deviceId || undefined;
   }
 
   getCurrentSerialNo() {
-    return this.features ? getDeviceUUID(this.features) : '';
+    return this.state?.identity.serialNo ?? '';
   }
 
   getConnectId() {
     const serialNo = this.getCurrentSerialNo();
     if (serialNo) return serialNo;
 
-    // connectId 是 SDK 内部连接路由 key。这里兜底到 transport descriptor，
-    // 不改变 features.serialNo / deviceId 的业务语义。
+    // connectId is an internal routing key. Falling back to the transport descriptor
+    // does not change the business meaning of features.serialNo or deviceId.
     return this.originalDescriptor.path || this.originalDescriptor.id || '';
   }
 
   getCurrentBleName() {
-    return getDeviceBleName(this.features);
+    return this.state?.identity.bleName ?? null;
   }
 
   getCurrentLabel() {
-    return getDeviceLabel(this.features);
+    return this.state?.identity.label ?? null;
+  }
+
+  getCurrentDisplayName() {
+    if (!this.state) return null;
+
+    const label = this.getCurrentLabel();
+    if (label) return label;
+
+    const bleName = this.getCurrentBleName();
+    if (bleName) return bleName;
+
+    const deviceType = this.getCurrentDeviceType();
+    if (deviceType === EDeviceType.ClassicPure) {
+      return 'OneKey Classic 1S';
+    }
+
+    return `OneKey ${deviceType.charAt(0).toUpperCase() + deviceType.slice(1)}`;
   }
 
   getCurrentPassphraseProtection() {
-    return this.features?.passphraseProtection;
+    return this.state?.status.passphraseProtection;
   }
 
   getCurrentFirmwareType() {
-    return getFirmwareType(this.features);
+    return this.state?.identity.firmwareType ?? EFirmwareType.Universal;
   }
 
   getCurrentFirmwareVersionString() {
-    return getDeviceFirmwareVersion(this.features)?.join('.');
+    return parseDeviceVersion(this.state?.versions.firmware).join('.');
   }
 
   getCurrentBLEFirmwareVersionString() {
-    if (!this.features) return undefined;
-    return getDeviceBLEFirmwareVersion(this.features).join('.');
+    if (!this.state) return undefined;
+    return parseDeviceVersion(this.state.versions.ble).join('.');
+  }
+
+  getCurrentBootloaderVersionString() {
+    if (!this.state) return undefined;
+    return parseDeviceVersion(this.state.versions.bootloader).join('.');
   }
 
   getCurrentSafetyChecks() {
-    return this.features?.safetyChecks;
+    return this.state?.settings.safetyChecks;
   }
 
   getCurrentMethodVersionRange(
@@ -557,6 +701,7 @@ export class Device extends EventEmitter {
     // Most-specific model first; must match getMethodVersionRange in deviceInfoUtils,
     // otherwise e.g. Classic1s resolves the looser model_mini range before model_classic1s.
     const modelFallbacks: IDeviceModel[] = [
+      'model_pro2',
       'model_classic1s',
       'model_classic',
       'model_mini',
@@ -576,7 +721,8 @@ export class Device extends EventEmitter {
     if (
       deviceType === EDeviceType.Touch ||
       deviceType === EDeviceType.Pro ||
-      deviceType === EDeviceType.Pro2
+      deviceType === EDeviceType.Pro2 ||
+      deviceType === EDeviceType.Neo
     ) {
       return { support: true };
     }
@@ -589,13 +735,12 @@ export class Device extends EventEmitter {
   }
 
   supportInputPinOnSoftware(): SupportFeatureType {
-    if (this.features) return supportInputPinOnSoftware(this.features);
-
     const deviceType = this.getCurrentDeviceType();
     if (
       deviceType === EDeviceType.Touch ||
       deviceType === EDeviceType.Pro ||
-      deviceType === EDeviceType.Pro2
+      deviceType === EDeviceType.Pro2 ||
+      deviceType === EDeviceType.Neo
     ) {
       return { support: false };
     }
@@ -608,15 +753,12 @@ export class Device extends EventEmitter {
   }
 
   supportModifyHomescreen(): SupportFeatureType {
-    // Pro2 走独立 1.x 版本线，不能套用 Touch/Pro 的 3.4.0 门槛（恒 false 且未来会误判）。
-    // 依据：firmware-pro2 协议 schema（messages-protocol-v2.json）的 ApplySettings
-    // 包含 homescreen 字段，V2 固件从首个版本即支持修改主屏。
+    // Pro2 has an independent 1.x version line and must not use the Touch/Pro 3.4.0
+    // threshold. ApplySettings includes homescreen from the first V2 firmware version.
     if (this.isProtocolV2()) {
       return { support: true };
     }
 
-    if (this.features) return supportModifyHomescreen(this.features);
-
     const deviceType = this.getCurrentDeviceType();
     if (DeviceModelToTypes.model_mini.includes(deviceType)) {
       return { support: true };
@@ -628,29 +770,29 @@ export class Device extends EventEmitter {
     };
   }
 
-  private generateStateKey(deviceId: string, passphraseState?: string) {
-    if (passphraseState) {
-      return `${deviceId}@${passphraseState}`;
-    }
-    return deviceId;
-  }
-
   private getSessionCacheDeviceKey(_deviceId?: string) {
     const deviceId = _deviceId || this.getCurrentDeviceId();
     if (deviceId) return deviceId;
     if (this.isProtocolV2()) {
-      return this.originalDescriptor.path || this.originalDescriptor.id;
+      return this.originalDescriptor.path;
     }
     return undefined;
   }
 
+  private reconcileSessionCacheDeviceIdentity(previousDeviceId?: string) {
+    deviceWalletSessionStore.reconcileDeviceIdentity({
+      temporaryKey: this.isProtocolV2() ? this.originalDescriptor.path : undefined,
+      previousDeviceId,
+      nextDeviceId: this.getCurrentDeviceId(),
+    });
+  }
+
   getInternalState(_deviceId?: string) {
-    Log.debug('getInternalState session cache: ', deviceSessionCache);
     Log.debug(
       'getInternalState session param: ',
       `device_id: ${_deviceId}`,
-      `features.deviceId: ${this.features?.deviceId}`,
-      `passphraseState: ${this.passphraseState}`
+      `currentDeviceId: ${this.getCurrentDeviceId()}`,
+      `hasPassphraseState: ${Boolean(this.passphraseState)}`
     );
 
     const deviceId = this.getSessionCacheDeviceKey(_deviceId);
@@ -663,8 +805,13 @@ export class Device extends EventEmitter {
     // downstream call carries it and hits the primary lookup below.
     if (!this.passphraseState) return undefined;
 
-    const usePassKey = this.generateStateKey(deviceId, this.passphraseState);
-    return deviceSessionCache[usePassKey];
+    return deviceWalletSessionStore.get(deviceId, this.passphraseState);
+  }
+
+  getStandardInternalState(_deviceId?: string) {
+    const deviceId = this.getSessionCacheDeviceKey(_deviceId);
+    if (!deviceId) return undefined;
+    return deviceWalletSessionStore.getStandard(deviceId);
   }
 
   // attach to pin to fix internal state
@@ -673,46 +820,45 @@ export class Device extends EventEmitter {
     passphraseState: string | undefined,
     deviceId: string | undefined,
     sessionId: string | null = null,
-    featuresSessionId: string | null = null
+    featuresSessionId: string | null = null,
+    walletType: 'standard' | 'hidden' = 'hidden'
   ) {
     Log.debug(
       'updateInternalState session param: ',
       `device_id: ${deviceId}`,
       `enablePassphrase: ${enablePassphrase}`,
-      `passphraseState: ${passphraseState}`,
-      `sessionId: ${sessionId}`,
-      `featuresSessionId: ${featuresSessionId}`
+      `hasPassphraseState: ${Boolean(passphraseState)}`,
+      `hasSessionId: ${Boolean(sessionId)}`,
+      `hasFeaturesSessionId: ${Boolean(featuresSessionId)}`
     );
 
     const cacheDeviceKey = this.getSessionCacheDeviceKey(deviceId);
     if (!cacheDeviceKey) return;
 
     if (enablePassphrase) {
-      // update the sessionId
-      if (sessionId) {
-        deviceSessionCache[this.generateStateKey(cacheDeviceKey, passphraseState)] = sessionId;
-      } else if (featuresSessionId) {
-        deviceSessionCache[this.generateStateKey(cacheDeviceKey, passphraseState)] =
-          featuresSessionId;
+      const walletSessionId =
+        sessionId || featuresSessionId || deviceWalletSessionStore.getPending(cacheDeviceKey);
+      if (walletType === 'standard') {
+        deviceWalletSessionStore.setStandard(
+          cacheDeviceKey,
+          passphraseState,
+          walletSessionId ?? undefined
+        );
+      } else {
+        deviceWalletSessionStore.set(cacheDeviceKey, passphraseState, walletSessionId ?? undefined);
       }
     }
 
-    // delete the old sessionId
-    const oldKey = `${cacheDeviceKey}`;
-    if (deviceSessionCache[oldKey]) {
-      delete deviceSessionCache[oldKey];
-    }
-
-    Log.debug('updateInternalState session cache: ', deviceSessionCache);
+    deviceWalletSessionStore.deletePending(cacheDeviceKey);
   }
 
   private setInternalState(state: string, initSession?: boolean) {
     Log.debug(
       'setInternalState session param: ',
-      `state: ${state}`,
+      `hasState: ${Boolean(state)}`,
       `initSession: ${initSession}`,
-      `deviceId: ${this.features?.deviceId}`,
-      `passphraseState: ${this.passphraseState}`
+      `deviceId: ${this.getCurrentDeviceId()}`,
+      `hasPassphraseState: ${Boolean(this.passphraseState)}`
     );
 
     if (!this.passphraseState && !initSession) return;
@@ -720,12 +866,11 @@ export class Device extends EventEmitter {
     const deviceId = this.getSessionCacheDeviceKey();
     if (!deviceId) return;
 
-    const key = this.generateStateKey(deviceId, this.passphraseState);
-
-    if (state) {
-      deviceSessionCache[key] = state;
+    if (this.passphraseState) {
+      deviceWalletSessionStore.set(deviceId, this.passphraseState, state);
+    } else if (initSession) {
+      deviceWalletSessionStore.setPending(deviceId, state);
     }
-    Log.debug('setInternalState done session cache: ', deviceSessionCache);
   }
 
   clearInternalState(_deviceId?: string) {
@@ -733,70 +878,80 @@ export class Device extends EventEmitter {
 
     const deviceId = this.getSessionCacheDeviceKey(_deviceId);
     if (!deviceId) return;
-    const key = `${deviceId}`;
-    delete deviceSessionCache[key];
+    deviceWalletSessionStore.deletePending(deviceId);
 
     if (this.passphraseState) {
-      const usePassKey = this.generateStateKey(deviceId, this.passphraseState);
-      delete deviceSessionCache[usePassKey];
+      deviceWalletSessionStore.delete(deviceId, this.passphraseState);
     }
   }
 
+  clearStandardInternalState(_deviceId?: string) {
+    const deviceId = this.getSessionCacheDeviceKey(_deviceId);
+    if (!deviceId) return;
+    deviceWalletSessionStore.deleteStandard(deviceId);
+  }
+
   async initialize(options?: InitOptions) {
-    // Protocol V2 不支持传统 Initialize，直接使用协议专用初始化流程。
+    // Protocol V2 does not support legacy Initialize; use its dedicated flow.
     if (this.isProtocolV2()) {
       this.passphraseState = options?.passphraseState;
-      if (this.features && !this.featuresNeedsReload && !options?.initSession) {
-        if (this.features.bootloaderMode) {
+      if (this.state && !options?.initSession && !this.protocolV2StateNeedsReload) {
+        if (this.state.status.mode === 'bootloader' || this.state.status.mode === 'romloader') {
           return;
         }
-        // 不能直接信任缓存 features：设备端 wipe / 完成初始化 / 改 label 后
-        // features 会永久陈旧。每次 run 做一次轻量 status 刷新（不含 fw/SE），
-        // 用字段级合并保留已有版本和 SE 信息。
-        await this._refreshProtocolV2Status(options);
+        // Normal calls reuse the cache. Explicit getDeviceState refreshes, unlock flow,
+        // and device events update dynamic state without polling on every SDK call.
         return;
       }
       await this._initializeProtocolV2(options);
+      this.protocolV2StateNeedsReload = false;
       return;
     }
 
-    // Log.debug('initialize param:', options);
+    try {
+      const callInitialize = async (payload: Record<string, unknown>, initSession?: boolean) => {
+        const initStartAt = Date.now();
+        const { message } = await this.commands.typedCall('Initialize', 'Features', payload, {
+          // iOS BLE bound devices can need close to 20 seconds.
+          timeoutMs: options?.timeoutMs ?? 25 * 1000,
+        });
+        this.setLastInitializeDuration(Date.now() - initStartAt);
+        this._updateFeatures(message, initSession);
+        await TransportManager.reconfigure(this.features);
+      };
 
-    this.passphraseState = options?.passphraseState;
+      const expectedDeviceId = options?.deviceId;
+      if (expectedDeviceId) {
+        // 先只读校验物理设备身份；钱包上下文仍由下方携带完整参数的
+        // Initialize 选择，避免标准钱包请求复用此前的隐藏钱包上下文。
+        this.passphraseState = undefined;
+        const { message } = await this.commands.typedCall('GetFeatures', 'Features', {});
+        this._updateFeatures(message);
+        await TransportManager.reconfigure(this.features);
+        if (!this.checkDeviceId(expectedDeviceId)) {
+          throw ERRORS.TypedError(HardwareErrorCode.DeviceCheckDeviceIdError);
+        }
+      }
 
-    if (options?.initSession) {
-      this.clearInternalState(options?.deviceId);
-    }
+      this.passphraseState = options?.passphraseState;
 
-    const internalState = this.getInternalState(options?.deviceId);
-    const payload: any = {};
-    if (internalState) {
-      payload.session_id = internalState;
-    }
+      if (options?.initSession) {
+        this.clearInternalState(options?.deviceId);
+      }
 
-    if (options?.deriveCardano) {
-      payload.derive_cardano = true;
-    }
-    payload.passphrase_state = options?.passphraseState;
-    payload.is_contains_attach = true;
+      const internalState = this.getInternalState(options?.deviceId);
+      const payload: Record<string, unknown> = {
+        passphrase_state: options?.passphraseState,
+        is_contains_attach: true,
+      };
+      if (internalState) {
+        payload.session_id = internalState;
+      }
+      if (options?.deriveCardano) {
+        payload.derive_cardano = true;
+      }
 
-    const initStartAt = Date.now();
-    try {
-      // @ts-expect-error
-      const { message } = await Promise.race([
-        this.commands.typedCall('Initialize', 'Features', payload),
-        new Promise((_, reject) => {
-          setTimeout(() => {
-            reject(ERRORS.TypedError(HardwareErrorCode.DeviceInitializeFailed));
-            // iOS ble bound device timeout 20s
-          }, 25 * 1000);
-        }),
-      ]);
-
-      const initCostMs = Date.now() - initStartAt;
-      this.setLastInitializeDuration(initCostMs);
-      this._updateFeatures(message, options?.initSession);
-      await TransportManager.reconfigure(this.features);
+      await callInitialize(payload, options?.initSession);
     } catch (error) {
       Log.error('Initialization failed:', error);
       throw error;
@@ -806,59 +961,38 @@ export class Device extends EventEmitter {
   /**
    * Device initialization over Protocol V2.
    *
-   * Protocol V2 不走传统 Initialize/GetFeatures；直接用 DeviceInfoGet
-   * 生成唯一的 features 状态。
+   * Protocol V2 bypasses legacy Initialize/GetFeatures and builds its canonical
+   * features state directly from DeviceInfoGet.
    */
   private async _initializeProtocolV2(options?: InitOptions) {
     Log.debug('Initialize device via Protocol V2 features adapter');
 
     try {
-      // 超时由 requestProtocolV2DeviceInfo 内部的 typedCall timeoutMs（默认 10s）负责，
-      // 不再额外包一层 Promise.race：外层 race 的 timer 不会清理，
-      // 且 reject 后底层调用仍会残留。
+      // typedCall applies the request timeout. An outer Promise.race would leak its
+      // timer and leave the underlying call active after rejection.
       const deviceInfo = await requestProtocolV2DeviceInfo({
         commands: this.commands,
         timeoutMs: options?.protocolV2DeviceInfoTimeoutMs,
       });
-      // 默认请求不含 SE/hash 数据，scope 如实标注为 basic；
-      // 完整数据由 getDeviceInfo(scope:'verify'|'full') 获取。
-      const features = this.updateProtocolV2Features(deviceInfo);
+      // The default request excludes SE/hash data and therefore uses basic scope.
+      // Full version and verification data require getDeviceState({ scope: 'firmware' }).
+      const features = await this.probeProtocolV2RuntimeState(
+        deviceInfo,
+        options?.protocolV2DeviceInfoTimeoutMs
+      );
       Log.debug('Protocol V2 features:', features);
-      this.featuresNeedsReload = false;
     } catch (error) {
       Log.error('Protocol V2 initialization failed:', error);
       throw error;
     }
   }
 
-  /**
-   * Protocol V2 的轻量状态刷新（每次 run 前调用）。
-   *
-   * 请求 hw + coprocessor + status（不含 fw/SE target）：status 提供 init_states / label /
-   * passphrase_enabled 等会在设备端变化的字段；hw/coprocessor 提供 serialNo / bleName。
-   * versions 为空时按字段级合并保留旧值，verify 数据不会被降级。
-   */
-  private async _refreshProtocolV2Status(options?: InitOptions) {
-    try {
-      const deviceInfo = await requestProtocolV2DeviceInfo({
-        commands: this.commands,
-        request: PROTOCOL_V2_STATUS_DEVICE_INFO_REQUEST,
-        timeoutMs: options?.protocolV2DeviceInfoTimeoutMs,
-      });
-      const features = this.updateProtocolV2Features(deviceInfo);
-      Log.debug('Protocol V2 features (status refresh):', features);
-    } catch (error) {
-      Log.error('Protocol V2 status refresh failed:', error);
-      throw error;
-    }
-  }
-
   async getFeatures() {
     if (this.isProtocolV2()) {
       const deviceInfo = await requestProtocolV2DeviceInfo({
         commands: this.commands,
       });
-      return this.updateProtocolV2Features(deviceInfo);
+      return this.probeProtocolV2RuntimeState(deviceInfo);
     }
 
     const { message } = await this.commands.typedCall('GetFeatures', 'Features', {});
@@ -866,36 +1000,332 @@ export class Device extends EventEmitter {
     return this.features;
   }
 
+  async getDeviceState(params: DeviceStateReadOptions = {}) {
+    const refresh = new Set(params.refreshSections ?? []);
+    const getProtocolV2DeviceInfoRequest = () => {
+      if (refresh.has('verification')) return PROTOCOL_V2_FULL_DEVICE_INFO_REQUEST;
+      if (refresh.has('versions')) return PROTOCOL_V2_VERSIONS_DEVICE_INFO_REQUEST;
+      return PROTOCOL_V2_FEATURES_DEVICE_INFO_REQUEST;
+    };
+    let initializedWithDeviceInfo = false;
+    let refreshedDeviceInfo: ProtocolV2DeviceInfo | undefined;
+
+    if (!this.state) {
+      if (this.isProtocolV2()) {
+        const deviceInfo = await requestProtocolV2DeviceInfo({
+          commands: this.commands,
+          request: getProtocolV2DeviceInfoRequest(),
+        });
+        await this.probeProtocolV2RuntimeState(deviceInfo);
+        refreshedDeviceInfo = deviceInfo;
+        initializedWithDeviceInfo = true;
+      } else {
+        await this.getFeatures();
+      }
+    } else if (!this.isProtocolV2() && refresh.size > 0) {
+      await this.getFeatures();
+    }
+
+    const supportsProtocolV1OnekeyFeatures =
+      this.getCurrentDeviceType() === EDeviceType.Touch ||
+      this.getCurrentDeviceType() === EDeviceType.Pro;
+    if (!this.isProtocolV2() && refresh.has('verification') && supportsProtocolV1OnekeyFeatures) {
+      const { message } = await this.commands.typedCall('OnekeyGetFeatures', 'OnekeyFeatures');
+      this.updateState(mapProtocolV1OnekeyFeaturesToState(message), 'device-info');
+    }
+
+    if (this.isProtocolV2()) {
+      const refreshDeviceInfo =
+        refresh.has('identity') || refresh.has('versions') || refresh.has('verification');
+      if (refreshDeviceInfo && !initializedWithDeviceInfo) {
+        const deviceInfo = await requestProtocolV2DeviceInfo({
+          commands: this.commands,
+          request: getProtocolV2DeviceInfoRequest(),
+        });
+        refreshedDeviceInfo = deviceInfo;
+        if (!refresh.has('status')) {
+          this.updateState(
+            mapProtocolV2DeviceInfoToState(deviceInfo, this.state?.status.mode),
+            'device-info'
+          );
+        }
+      }
+
+      if (refresh.has('status') && !initializedWithDeviceInfo) {
+        await this.probeProtocolV2RuntimeState(refreshedDeviceInfo);
+      }
+
+      if (refresh.has('settings') && this.state?.status.mode === 'normal') {
+        const { message } = await this.commands.typedCall(
+          'DeviceSettingsGet',
+          'DeviceSettings',
+          {}
+        );
+        this.updateState(mapDeviceSettingsToState(message), 'settings-read');
+      }
+    }
+
+    if (!this.state) {
+      throw ERRORS.TypedError(HardwareErrorCode.DeviceInitializeFailed);
+    }
+    return params.includeRaw ? cloneDeviceState(this.state) : createPublicDeviceState(this.state);
+  }
+
   _updateFeatures(protoFeatures: PROTO.Features | Features, initSession?: boolean) {
+    const previousDeviceId = this.getCurrentDeviceId();
     let feat =
       'protocol' in protoFeatures
         ? protoFeatures
         : buildProtocolV1FeaturesPayload(protoFeatures, this.features);
 
-    // GetFeatures doesn't return 'session_id'
-    if (this.features?.sessionId && !feat.sessionId) {
-      feat.sessionId = this.features.sessionId;
-    }
-    if (this.getCurrentDeviceId() && feat.sessionId) {
-      this.setInternalState(feat.sessionId, initSession);
-    }
     feat.unlocked = feat.unlocked ?? true;
 
     feat = fixFeaturesFirmwareVersion(feat);
 
-    this.features = feat;
-    this.featuresNeedsReload = false;
-    this.emit(DEVICE.FEATURES, this, feat);
+    this.updateState(mapFeaturesToState(feat), 'initialize');
+    this.reconcileSessionCacheDeviceIdentity(previousDeviceId);
+    if (feat.deviceId && feat.sessionId) {
+      this.setInternalState(feat.sessionId, initSession);
+    }
+  }
+
+  updateState(patch: DeviceStatePatch, source: DeviceStateUpdateSource) {
+    const result = this.stateStore.update(patch, source);
+    if (result.changedKeys.length === 0) return result.state;
+
+    const event: DeviceStateEvent = {
+      connectId: this.getConnectId() ?? null,
+      state: createPublicDeviceState(result.state),
+      revision: result.revision,
+      source,
+      changedKeys: result.changedKeys,
+    };
+    Log.debug('Device state patch committed', {
+      source,
+      keys: result.changedKeys,
+    });
+    this.emit(DEVICE.STATE, this, event);
+    if (result.state.protocol === 'V1') {
+      this.emit(DEVICE.FEATURES, this, projectFeatures(result.state));
+    }
+    return result.state;
+  }
+
+  updateFeaturesPatch(patch: Partial<Features>, source: DeviceStateUpdateSource) {
+    const currentFeatures = this.features;
+    if (!currentFeatures) return undefined;
+
+    const features = mergeDeviceFeaturesPatch(currentFeatures, patch);
+    if (features === currentFeatures) return currentFeatures;
+
+    const normalized = fixFeaturesFirmwareVersion(features);
+    this.updateState(mapFeaturesToState(normalized), source);
+    return this.features;
+  }
+
+  async ensureProtocolV2RuntimeContext(timeoutMs?: number): Promise<ProtocolInfo> {
+    const cachedProtocolInfo =
+      this.protocolV2RuntimeContext ??
+      (!this.protocolV2StateNeedsReload
+        ? this.state?.raw?.protocolV2ProtocolInfo ?? undefined
+        : undefined);
+    if (cachedProtocolInfo) {
+      this.protocolV2RuntimeContext = cachedProtocolInfo;
+      return cachedProtocolInfo;
+    }
+
+    if (this.protocolV2RuntimeContextPromise) {
+      return this.protocolV2RuntimeContextPromise;
+    }
+
+    const requestToken = {};
+    const pendingRequest = (async () => {
+      const protocolInfo = await requestProtocolV2ProtocolInfo({
+        commands: this.commands,
+        timeoutMs,
+      });
+      if (this.protocolV2RuntimeContextRequestToken !== requestToken) {
+        throw ERRORS.TypedError(
+          HardwareErrorCode.DeviceInitializeFailed,
+          'Protocol V2 runtime context was invalidated while loading.'
+        );
+      }
+      this.protocolV2RuntimeContext = protocolInfo;
+      return protocolInfo;
+    })();
+    this.protocolV2RuntimeContextRequestToken = requestToken;
+    this.protocolV2RuntimeContextPromise = pendingRequest;
+
+    try {
+      return await pendingRequest;
+    } finally {
+      if (this.protocolV2RuntimeContextPromise === pendingRequest) {
+        this.protocolV2RuntimeContextPromise = undefined;
+      }
+      if (this.protocolV2RuntimeContextRequestToken === requestToken) {
+        this.protocolV2RuntimeContextRequestToken = undefined;
+      }
+    }
+  }
+
+  async probeProtocolV2RuntimeState(deviceInfo?: ProtocolV2DeviceInfo, timeoutMs?: number) {
+    const protocolInfo = await this.ensureProtocolV2RuntimeContext(timeoutMs);
+    const runtimeMode = getProtocolV2RuntimeMode(protocolInfo);
+    const runtimeDeviceInfo = deviceInfo ?? this.state?.raw?.protocolV2DeviceInfo;
+    const protocolV2DeviceType = runtimeDeviceInfo
+      ? resolveProtocolV2DeviceIdentity(runtimeDeviceInfo.hw?.Device_type).deviceType
+      : this.getCurrentDeviceType();
+    if (
+      runtimeMode === 'romloader' &&
+      protocolV2DeviceType !== EDeviceType.Pro2 &&
+      protocolV2DeviceType !== EDeviceType.Neo
+    ) {
+      throw ERRORS.TypedError(
+        HardwareErrorCode.DeviceInitializeFailed,
+        'Protocol V2 romloader mode is only supported for Pro2 and Neo.'
+      );
+    }
+    const deviceStatusSupported = supportsProtocolV2Message(
+      protocolInfo,
+      PROTOCOL_V2_DEVICE_STATUS_GET_MESSAGE_TYPE
+    );
+
+    if (runtimeMode === 'bootloader' || runtimeMode === 'romloader') {
+      return this.updateProtocolV2Features(deviceInfo, null, runtimeMode, protocolInfo);
+    }
+
+    if (!deviceStatusSupported) {
+      if (runtimeMode === 'normal') {
+        return this.updateProtocolV2Features(deviceInfo, null, runtimeMode, protocolInfo);
+      }
+      throw ERRORS.TypedError(
+        HardwareErrorCode.DeviceInitializeFailed,
+        `Unknown Protocol V2 build fingerprint without DeviceStatusGet capability: ${protocolInfo.build_fingerprint}`
+      );
+    }
+
+    let deviceStatus: DeviceStatus;
+    try {
+      deviceStatus = await requestProtocolV2DeviceStatus({
+        commands: this.commands,
+        timeoutMs,
+      });
+    } catch (error) {
+      if (runtimeMode === undefined && isProtocolV2DeviceStatusUnsupportedError(error)) {
+        return this.updateProtocolV2Features(deviceInfo, null, 'bootloader', protocolInfo);
+      }
+      throw error;
+    }
+    return this.updateProtocolV2Features(deviceInfo, deviceStatus, 'normal', protocolInfo);
+  }
+
+  updateProtocolV2Features(
+    deviceInfo?: ProtocolV2DeviceInfo,
+    deviceStatus?: DeviceStatus | null,
+    runtimeMode?: ProtocolV2RuntimeMode,
+    protocolInfo?: ProtocolInfo
+  ) {
+    const previousDeviceId = this.getCurrentDeviceId();
+    const resolvedMode = runtimeMode ?? (deviceStatus ? 'normal' : this.state?.status.mode);
+    if (deviceInfo) {
+      this.updateState(mapProtocolV2DeviceInfoToState(deviceInfo, resolvedMode), 'device-info');
+    }
+    if (protocolInfo) {
+      this.updateState({ raw: { protocolV2ProtocolInfo: protocolInfo } }, 'device-info');
+    }
+    if (deviceStatus) {
+      this.updateState(mapProtocolV2DeviceStatusToState(deviceStatus), 'device-status');
+    }
+    this.reconcileSessionCacheDeviceIdentity(previousDeviceId);
+    return this.features as Features;
   }
 
-  updateProtocolV2Features(deviceInfo?: ProtocolV2DeviceInfo) {
-    const features = fixFeaturesFirmwareVersion(
-      buildProtocolV2FeaturesPayload(deviceInfo, this.features)
+  updateProtocolV2Status(status: DeviceStatus) {
+    const previousDeviceInfo = this.state?.raw?.protocolV2DeviceInfo;
+    const previousStatus = this.state?.raw?.protocolV2DeviceStatus;
+    return this.updateProtocolV2Features(previousDeviceInfo, {
+      ...previousStatus,
+      ...status,
+    });
+  }
+
+  markTransportDisconnected() {
+    this.deviceAcquired = false;
+    if (!this.isProtocolV2()) return;
+    this.protocolV2StateNeedsReload = true;
+    this.protocolV2RuntimeContext = undefined;
+    this.protocolV2RuntimeContextPromise = undefined;
+    this.protocolV2RuntimeContextRequestToken = undefined;
+    this.clearPreInitialized();
+  }
+
+  invalidateAfterWipe() {
+    const deviceId = this.getCurrentDeviceId();
+    if (deviceId) {
+      deviceWalletSessionStore.deleteDevice(deviceId);
+    }
+    if (this.isProtocolV2()) {
+      if (this.originalDescriptor.path !== deviceId) {
+        deviceWalletSessionStore.deleteDevice(this.originalDescriptor.path);
+      }
+      this.protocolV2StateNeedsReload = true;
+      this.protocolV2RuntimeContext = undefined;
+      this.protocolV2RuntimeContextPromise = undefined;
+      this.protocolV2RuntimeContextRequestToken = undefined;
+    }
+
+    this.passphraseState = undefined;
+    this.stateStore = new DeviceStateStore();
+    this.clearPreInitialized();
+    this.needReloadDevice = true;
+  }
+
+  markProtocolV2Reboot(rebootType: DeviceRebootType) {
+    if (!this.isProtocolV2()) return;
+
+    this.protocolV2StateNeedsReload = true;
+    this.protocolV2RuntimeContext = undefined;
+    this.protocolV2RuntimeContextPromise = undefined;
+    this.protocolV2RuntimeContextRequestToken = undefined;
+    this.clearPreInitialized();
+    let loaderMode: 'bootloader' | 'romloader' | undefined;
+    if (rebootType === DeviceRebootType.Bootloader) {
+      loaderMode = 'bootloader';
+    } else if (rebootType === DeviceRebootType.Romloader) {
+      loaderMode = 'romloader';
+    }
+    if (loaderMode) {
+      this.updateState(
+        {
+          identity: { deviceId: null },
+          status: {
+            mode: loaderMode,
+            initialized: null,
+            unlocked: null,
+            firmwarePresent: null,
+            backupRequired: null,
+            noBackup: null,
+            unfinishedBackup: null,
+            recoveryMode: null,
+            passphraseProtection: null,
+            pinProtection: null,
+            attachToPinEnabled: null,
+            unlockedAttachPin: null,
+          },
+          raw: { protocolV2ProtocolInfo: null, protocolV2DeviceStatus: null },
+        },
+        'transport-reconnect'
+      );
+      return;
+    }
+
+    this.updateState(
+      {
+        status: { mode: 'normal', unlocked: null },
+        raw: { protocolV2ProtocolInfo: null, protocolV2DeviceStatus: null },
+      },
+      'transport-reconnect'
     );
-    this.features = features;
-    this.featuresNeedsReload = false;
-    this.emit(DEVICE.FEATURES, this, features);
-    return features;
   }
 
   /**
@@ -916,8 +1346,7 @@ export class Device extends EventEmitter {
     }
 
     if (forceUpdate) {
-      // 枚举得到的 descriptor 可能不带 protocolType（如 WebUSB enumerate），
-      // 不能让覆盖丢掉已探测的协议结果。
+      // Enumerated descriptors may omit protocolType, so preserve an actively probed value.
       this.originalDescriptor = {
         ...descriptor,
         protocolType: descriptor.protocolType ?? this.originalDescriptor.protocolType,
@@ -942,19 +1371,43 @@ export class Device extends EventEmitter {
 
     options = parseRunOptions(options);
 
-    this.runPromise = createDeferred(this._runInner.bind(this, fn, options));
-    return this.runPromise.promise;
+    const runPromise = createDeferred<void>();
+    this.runPromise = runPromise;
+    this._runInner(fn, options, runPromise).catch(error => {
+      if (this.runPromise === runPromise) {
+        this.runPromise = null;
+      }
+      runPromise.reject(error);
+    });
+    return runPromise.promise;
   }
 
-  async _runInner<T>(fn: (() => Promise<T>) | undefined, options: RunOptions) {
-    if (!this.isUsedHere() || this.commands.disposed) {
-      const env = DataManager.getSettings('env');
+  async _runInner<T>(
+    fn: (() => Promise<T>) | undefined,
+    options: RunOptions,
+    runPromise: Deferred<void>
+  ) {
+    const clearRunPromise = () => {
+      if (this.runPromise === runPromise) {
+        this.runPromise = null;
+      }
+    };
+
+    const env = DataManager.getSettings('env');
+    if (options.forceProtocolDetection && env !== 'react-native' && this.isUsedHere()) {
+      await this.release();
+    }
+
+    if (options.forceProtocolDetection || !this.isUsedHere() || this.commands.disposed) {
       if (env !== 'react-native') {
         try {
-          await this.acquire(options.connectProtocol);
+          await this.acquire(options.connectProtocol, {
+            forceProtocolDetection: options.forceProtocolDetection,
+          });
         } catch (error) {
-          this.runPromise = null;
-          return Promise.reject(error);
+          clearRunPromise();
+          runPromise.reject(error);
+          return;
         }
 
         try {
@@ -964,16 +1417,19 @@ export class Device extends EventEmitter {
             }
           }
         } catch (error) {
-          this.runPromise = null;
+          await this.release();
+          clearRunPromise();
           if (error instanceof HardwareError) {
-            return Promise.reject(error);
+            runPromise.reject(error);
+            return;
           }
-          return Promise.reject(
+          runPromise.reject(
             ERRORS.TypedError(
               HardwareErrorCode.DeviceInitializeFailed,
               `Initialize failed: ${error.message as string}, code: ${error.code as string}`
             )
           );
+          return;
         }
       } else if (env === 'react-native') {
         // TODO: implement react-native acquire
@@ -992,9 +1448,7 @@ export class Device extends EventEmitter {
       try {
         await fn();
       } catch (e) {
-        if (this.runPromise) {
-          this.runPromise.reject(e);
-        }
+        runPromise.reject(e);
 
         if (
           e instanceof HardwareError &&
@@ -1007,7 +1461,7 @@ export class Device extends EventEmitter {
           Log.debug(`error code ${e.errorCode} release device, mainId: ${this.mainId}`);
         }
 
-        this.runPromise = null;
+        clearRunPromise();
         return;
       }
     }
@@ -1021,11 +1475,8 @@ export class Device extends EventEmitter {
       Log.debug('release device, mainId: ', this.mainId);
     }
 
-    if (this.runPromise) {
-      this.runPromise.resolve();
-    }
-
-    this.runPromise = null;
+    runPromise.resolve();
+    clearRunPromise();
   }
 
   async interruptionFromOutside() {
@@ -1064,33 +1515,37 @@ export class Device extends EventEmitter {
   }
 
   getMode() {
-    if (this.features?.bootloaderMode) {
-      // bootloader mode
-      return EOneKeyDeviceMode.bootloader;
-    }
-
-    if (!this.features?.initialized) {
-      // not initialized
-      return EOneKeyDeviceMode.notInitialized;
-    }
-
-    if (this.features?.noBackup) {
-      // backup mode
-      return EOneKeyDeviceMode.backupMode;
+    switch (this.state?.status.mode) {
+      case 'bootloader':
+      case 'romloader':
+        return EOneKeyDeviceMode.bootloader;
+      case 'notInitialized':
+        return EOneKeyDeviceMode.notInitialized;
+      case 'backupMode':
+        return EOneKeyDeviceMode.backupMode;
+      case 'normal':
+        return EOneKeyDeviceMode.normal;
+      default:
+        break;
     }
 
-    // normal mode
     return EOneKeyDeviceMode.normal;
   }
 
+  getStatus() {
+    if (this.isUsedElsewhere()) return 'occupied' as const;
+    if (this.isUsedHere()) return 'used' as const;
+    return 'available' as const;
+  }
+
   getFirmwareVersion() {
-    if (!this.features) return null;
-    return getDeviceFirmwareVersion(this.features);
+    if (!this.state) return null;
+    return parseDeviceVersion(this.state.versions.firmware);
   }
 
   getBLEFirmwareVersion() {
-    if (!this.features) return null;
-    return getDeviceBLEFirmwareVersion(this.features);
+    if (!this.state) return null;
+    return parseDeviceVersion(this.state.versions.ble);
   }
 
   isUsed() {
@@ -1108,7 +1563,7 @@ export class Device extends EventEmitter {
   isUsedHere() {
     const env = DataManager.getSettings('env');
     if (DataManager.isBleConnect(env)) {
-      return false;
+      return this.deviceAcquired;
     }
     return this.isUsed() && this.originalDescriptor.session === this.mainId;
   }
@@ -1118,26 +1573,39 @@ export class Device extends EventEmitter {
   }
 
   isBootloader() {
-    return this.features && !!this.features.bootloaderMode;
+    if (!this.state) return undefined;
+    return this.state.status.mode === 'bootloader';
+  }
+
+  isRomloader() {
+    if (!this.state) return undefined;
+    return (
+      this.isProtocolV2() &&
+      (this.getCurrentDeviceType() === EDeviceType.Pro2 ||
+        this.getCurrentDeviceType() === EDeviceType.Neo) &&
+      this.state.status.mode === 'romloader'
+    );
   }
 
   isInitialized() {
-    return this.features && !!this.features.initialized;
+    if (!this.state) return undefined;
+    return this.state.status.initialized === true;
   }
 
   isSeedless() {
-    return this.features && !!this.features.noBackup;
+    if (!this.state) return undefined;
+    return this.state.status.noBackup === true;
   }
 
   isUnacquired(): boolean {
-    return this.features === undefined;
+    return this.state === undefined;
   }
 
   hasUnexpectedMode(allow: string[], require: string[]) {
     // both allow and require cases might generate single unexpected mode
     if (!this.isUnacquired()) {
       // allow cases
-      if (this.isBootloader() && !allow.includes(UI_REQUEST.BOOTLOADER)) {
+      if (this.isBootloader() && !this.isProtocolV2() && !allow.includes(UI_REQUEST.BOOTLOADER)) {
         return UI_REQUEST.BOOTLOADER;
       }
       if (!this.isInitialized() && !allow.includes(UI_REQUEST.NOT_INITIALIZE)) {
@@ -1160,8 +1628,9 @@ export class Device extends EventEmitter {
     const isModeT =
       deviceType === EDeviceType.Touch ||
       deviceType === EDeviceType.Pro ||
-      deviceType === EDeviceType.Pro2;
-    const unlocked = this.features?.unlocked;
+      deviceType === EDeviceType.Pro2 ||
+      deviceType === EDeviceType.Neo;
+    const unlocked = this.state?.status.unlocked;
     const preCheckTouch = isModeT && unlocked === false;
     const passphraseProtection = this.getCurrentPassphraseProtection();
 
@@ -1174,12 +1643,91 @@ export class Device extends EventEmitter {
 
   async lockDevice(): Promise<Success> {
     const res = await this.commands.typedCall('LockDevice', 'Success', {});
+    this.updateState({ status: { unlocked: false } }, 'lock');
     return res.message;
   }
 
+  beginProtocolV2UiInteraction() {
+    if (!this.isProtocolV2()) return;
+    this.protocolV2UiInteraction = {
+      interactionId: `${this.instanceId}:${Date.now()}:${++this.protocolV2UiInteractionCounter}`,
+      phaseCounter: 0,
+      sequence: 0,
+      opened: false,
+    };
+  }
+
+  createProtocolV2UiPhaseMetadata(
+    phase: HardwareUiInteractionMeta['phase'],
+    transition: HardwareUiInteractionMeta['transition'],
+    options?: {
+      phaseId?: string;
+      outcome?: HardwareUiInteractionMeta['outcome'];
+    }
+  ): HardwareUiInteractionMeta | undefined {
+    if (!this.isProtocolV2()) return undefined;
+    if (!this.protocolV2UiInteraction) this.beginProtocolV2UiInteraction();
+
+    const interaction = this.protocolV2UiInteraction;
+    if (!interaction) return undefined;
+    const phaseId =
+      options?.phaseId ?? `${interaction.interactionId}:phase-${++interaction.phaseCounter}`;
+    interaction.opened = true;
+    interaction.sequence += 1;
+
+    return {
+      interactionId: interaction.interactionId,
+      phaseId,
+      sequence: interaction.sequence,
+      phase,
+      transition,
+      ...(options?.outcome ? { outcome: options.outcome } : {}),
+      protocol: 'V2',
+    };
+  }
+
+  completeProtocolV2UiPhase(
+    phase: HardwareUiInteractionMeta,
+    outcome: HardwareUiInteractionMeta['outcome'] = 'succeeded'
+  ) {
+    return this.createProtocolV2UiPhaseMetadata(phase.phase, 'complete', {
+      phaseId: phase.phaseId,
+      outcome,
+    });
+  }
+
+  finishProtocolV2UiInteraction(
+    outcome?: HardwareUiInteractionMeta['outcome'],
+    options?: { ensureMetadata?: boolean }
+  ) {
+    const interaction = this.protocolV2UiInteraction;
+    if (!interaction || (!interaction.opened && !options?.ensureMetadata)) {
+      this.protocolV2UiInteraction = undefined;
+      return undefined;
+    }
+
+    const phaseId = `${interaction.interactionId}:phase-${Math.max(interaction.phaseCounter, 1)}`;
+    interaction.opened = true;
+    interaction.sequence += 1;
+    const metadata: HardwareUiInteractionMeta = {
+      interactionId: interaction.interactionId,
+      phaseId,
+      sequence: interaction.sequence,
+      phase: 'processing',
+      transition: 'finish',
+      outcome: outcome ?? 'succeeded',
+      protocol: 'V2',
+    };
+    this.protocolV2UiInteraction = undefined;
+    return metadata;
+  }
+
+  hasOpenProtocolV2UiInteraction() {
+    return this.protocolV2UiInteraction?.opened === true;
+  }
+
   supportUnlockVersionRange(): DeviceFirmwareRange {
-    // 仅适用于 Protocol V1 的 Pro 系列；Pro2 走独立版本线，
-    // 且 Protocol V2 固件从首个版本即支持 UnLockDevice（见 unlockDevice 的 isProtocolV2 短路）。
+    // This range applies to Protocol V1 Pro devices; Pro2 has a dedicated unlock flow.
     return {
       pro: {
         min: '4.15.0',
@@ -1187,19 +1735,62 @@ export class Device extends EventEmitter {
     };
   }
 
-  async unlockDevice() {
+  async unlockDevice(
+    pinType?: DeviceSessionPinType,
+    options?: ProtocolV2UiEventMetadata & { emitUiEvent?: boolean }
+  ) {
+    if (this.isProtocolV2()) {
+      const requestedPinType = pinType ?? DeviceSessionPinType.Main;
+      const interaction =
+        options?.interaction ??
+        (options?.emitUiEvent === false
+          ? undefined
+          : this.createProtocolV2UiPhaseMetadata('pin', 'start'));
+      if (options?.emitUiEvent !== false) {
+        this.emit(DEVICE.PIN_ON_DEVICE, this, requestedPinType, {
+          source: options?.source ?? 'unlock-coordinator',
+          reason: options?.reason ?? 'device-unlock',
+          deviceOnly: options?.deviceOnly ?? true,
+          completion: options?.completion,
+          method: options?.method,
+          page: options?.page,
+          operation: options?.operation,
+          interaction: options?.interaction ?? interaction,
+        });
+      }
+      try {
+        await this.commands.typedCall('DeviceSessionAskPin', 'Success', {
+          type: requestedPinType,
+        });
+      } catch (error) {
+        const errorText =
+          error instanceof Error
+            ? `${error.name} ${error.message}`
+            : String((error as { message?: unknown } | null)?.message ?? error ?? '');
+        if (errorText.includes('Failure_UnexpectedMessage')) {
+          throw createDeviceNotSupportMethodError('deviceUnlock', this.getCurrentFirmwareType());
+        }
+        throw error;
+      }
+
+      const completion = interaction ? this.completeProtocolV2UiPhase(interaction) : undefined;
+      if (completion) {
+        this.emit(DEVICE.PIN_ON_DEVICE_COMPLETE, this, completion);
+      }
+
+      const status = await requestProtocolV2DeviceStatus({ commands: this.commands });
+      return this.updateProtocolV2Status(status);
+    }
+
     const firmwareVersion = this.getCurrentFirmwareVersionString() ?? '0.0.0';
     const versionRange = this.getCurrentMethodVersionRange(
       type => this.supportUnlockVersionRange()[type]
     );
 
-    const supportAttachPinCapability = existCapability(
-      this.features,
+    const supportAttachPinCapability = this.state?.capabilities.includes(
       Enum_Capability.Capability_AttachToPin
     );
-    // Pro2 (Protocol V2) 版本线独立于 Pro 系列，固件从首个版本即支持 UnLockDevice
     const supportUnlock =
-      this.isProtocolV2() ||
       supportAttachPinCapability ||
       (versionRange &&
         semver.valid(firmwareVersion) &&
@@ -1207,12 +1798,21 @@ export class Device extends EventEmitter {
 
     if (supportUnlock) {
       const res = await this.commands.typedCall('UnLockDevice', 'UnLockDeviceResponse');
-      if (this.features) {
-        this.features.unlocked = res.message.unlocked == null ? null : res.message.unlocked;
-        this.features.unlockedAttachPin =
-          res.message.unlocked_attach_pin == null ? undefined : res.message.unlocked_attach_pin;
-        this.features.passphraseProtection =
-          res.message.passphrase_protection == null ? null : res.message.passphrase_protection;
+      if (this.state) {
+        this.updateState(
+          {
+            status: {
+              unlocked: res.message.unlocked == null ? null : res.message.unlocked,
+              unlockedAttachPin:
+                res.message.unlocked_attach_pin == null ? null : res.message.unlocked_attach_pin,
+              passphraseProtection:
+                res.message.passphrase_protection == null
+                  ? null
+                  : res.message.passphrase_protection,
+            },
+          },
+          'unlock'
+        );
 
         return Promise.resolve(this.features);
       }
@@ -1221,14 +1821,6 @@ export class Device extends EventEmitter {
       return Promise.resolve(features);
     }
 
-    // legacy 解锁探测仅适用于 Protocol V1 老固件；V2 固件必然支持 UnLockDevice
-    if (this.isProtocolV2()) {
-      throw ERRORS.TypedError(
-        HardwareErrorCode.RuntimeError,
-        'unlock device error: device firmware does not support UnLockDevice'
-      );
-    }
-
     const { type } = await this.commands.typedCall('GetAddress', 'Address', {
       address_n: [toHardened(44), toHardened(1), toHardened(0), 0, 0],
       coin_name: 'Testnet',
@@ -1247,25 +1839,34 @@ export class Device extends EventEmitter {
   async checkPassphraseStateSafety(
     passphraseState?: string,
     useEmptyPassphrase?: boolean,
-    skipPassphraseCheck?: boolean
+    skipPassphraseCheck?: boolean,
+    deriveCardano?: boolean
   ) {
     if (this.isUnacquired()) return false;
 
+    const expectedPassphraseState = useEmptyPassphrase ? undefined : passphraseState;
     const { passphraseState: newPassphraseState, unlockedAttachPin } =
       await getPassphraseStateWithRefreshDeviceInfo(this, {
-        expectPassphraseState: passphraseState,
+        expectPassphraseState: expectedPassphraseState,
         onlyMainPin: useEmptyPassphrase,
+        deriveCardano,
+        rejectAttachPinForMainWallet: useEmptyPassphrase === true,
       });
 
     // Main wallet and unlock Attach Pin, throw safe error
     const mainWalletUseAttachPin = unlockedAttachPin && useEmptyPassphrase;
     const useErrorAttachPin =
-      unlockedAttachPin && passphraseState && passphraseState !== newPassphraseState;
-    const passphraseStateMismatch = !!passphraseState && passphraseState !== newPassphraseState;
+      unlockedAttachPin &&
+      expectedPassphraseState &&
+      expectedPassphraseState !== newPassphraseState;
+    const passphraseStateMismatch =
+      !!expectedPassphraseState && expectedPassphraseState !== newPassphraseState;
 
     Log.debug('Check passphrase state safety: ', {
-      passphraseState,
-      newPassphraseState,
+      hasExpectedPassphraseState: Boolean(expectedPassphraseState),
+      hasNewPassphraseState: Boolean(newPassphraseState),
+      passphraseStateMatches:
+        Boolean(expectedPassphraseState) && expectedPassphraseState === newPassphraseState,
       unlockedAttachPin,
       useEmptyPassphrase,
     });