@onekeyfe/hd-core 1.2.0-alpha.2 → 1.2.0-alpha.21

package/src/device/Device.ts

@@ -1,6 +1,6 @@
 import EventEmitter from 'events';
 import semver from 'semver';
-import { Enum_Capability } from '@onekeyfe/hd-transport';
+import { DeviceRebootType, Enum_Capability } from '@onekeyfe/hd-transport';
 import {
   EDeviceType,
   ERRORS,
@@ -9,16 +9,18 @@ import {
   HardwareError,
   HardwareErrorCode,
   createDeferred,
+  createDeviceNotSupportMethodError,
 } from '@onekeyfe/hd-shared';
 
 import {
   LoggerNames,
   getDeviceBLEFirmwareVersion,
   getDeviceBleName,
+  getDeviceBootloaderVersion,
   getDeviceFirmwareVersion,
   getDeviceLabel,
+  getDeviceSerialNo,
   getDeviceType,
-  getDeviceUUID,
   getFirmwareType,
   getLogger,
 } from '../utils';
@@ -31,9 +33,24 @@ import {
 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,
@@ -50,12 +67,18 @@ 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_FEATURES_DEVICE_INFO_REQUEST,
+  PROTOCOL_V2_FULL_DEVICE_INFO_REQUEST,
+  PROTOCOL_V2_VERSIONS_DEVICE_INFO_REQUEST,
+  type ProtocolV2RuntimeMode,
+  getProtocolV2RuntimeMode,
   requestProtocolV2DeviceInfo,
+  requestProtocolV2DeviceStatus,
 } from '../protocols/protocol-v2/features';
-import { buildProtocolV1FeaturesPayload, buildProtocolV2FeaturesPayload } from '../deviceProfile';
+import { buildProtocolV1FeaturesPayload } from '../deviceProfile';
 
 import type { PROTO } from '../constants';
+import type { DeviceStateReadOptions } from '../types/api/getDeviceState';
 import type {
   DeviceButtonRequestPayload,
   DeviceFeaturesPayload,
@@ -65,6 +88,7 @@ import type { PassphrasePromptResponse } from './DeviceCommands';
 import type { Deferred, HardwareConnectProtocol } from '@onekeyfe/hd-shared';
 import type {
   OneKeyDeviceInfo as DeviceDescriptor,
+  DeviceStatus,
   ProtocolV2DeviceInfo,
   Success,
 } from '@onekeyfe/hd-transport';
@@ -76,6 +100,9 @@ export type InitOptions = {
   passphraseState?: string;
   deriveCardano?: boolean;
   connectProtocol?: HardwareConnectProtocol;
+  protocolV2DeviceInfoTimeoutMs?: number;
+  /** Refresh Protocol V2 runtime state before returning discovery results. */
+  refreshRuntimeState?: boolean;
 };
 
 export type RunOptions = {
@@ -92,9 +119,11 @@ const Log = getLogger(LoggerNames.Device);
 
 export interface DeviceEvents {
   [DEVICE.PIN]: [Device, PROTO.PinMatrixRequestType | undefined, (err: any, pin: string) => void];
-  [DEVICE.PASSPHRASE_ON_DEVICE]: [Device, ((response: any) => void)?];
+  [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,
@@ -118,8 +147,6 @@ 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.
  *
@@ -137,8 +164,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 {
@@ -184,22 +210,51 @@ export class Device extends EventEmitter {
    */
   private deviceAcquired = false;
 
-  /**
-   * 唯一设备状态缓存。
-   *
-   * V1 直接保存原生 Features；V2 保存由 DevGetDeviceInfo 映射出的
-   * Features 视图。Device 不再保存 profile，结构化 DeviceProfile 只作为
-   * getDeviceInfo() 的 API 返回值存在。
-   */
-  features: Features | undefined = undefined;
-
-  /**
-   * 是否需要更新设备信息。
-   *
-   * 历史名称保留用于兼容现有调用语义；对 V2 表示 features 需要由
-   * DevGetDeviceInfo 刷新。
-   */
-  featuresNeedsReload = false;
+  /** Canonical device-state cache; legacy Features is a compatibility projection. */
+  private stateStore = new DeviceStateStore();
+
+  /** Force the next initialization to reload DeviceInfo after reconnect or reboot. */
+  private protocolV2StateNeedsReload = false;
+
+  get state() {
+    return this.stateStore.getState();
+  }
+
+  get features(): Features | undefined {
+    if (!this.state) return undefined;
+    const features = projectFeatures(this.state);
+    const sessionCacheDeviceKey =
+      this.state.identity.deviceId ||
+      (this.isProtocolV2()
+        ? this.originalDescriptor.path || this.originalDescriptor.id
+        : undefined);
+    const sessionId =
+      sessionCacheDeviceKey && this.passphraseState
+        ? deviceWalletSessionStore.get(sessionCacheDeviceKey, this.passphraseState)
+        : undefined;
+    return sessionId
+      ? {
+          ...features,
+          sessionId,
+          session_id: sessionId,
+          passphraseState: this.passphraseState,
+        }
+      : features;
+  }
+
+  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;
 
@@ -261,14 +316,18 @@ export class Device extends EventEmitter {
     const bleName = this.getCurrentBleName();
     const label = this.getCurrentLabel();
     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  */
-      connectId: DataManager.isBleConnect(env) ? this.mainId || null : serialNo,
-      /** Hardware ID, will not change at any time */
+      /** Android uses a MAC address, while iOS and USB use transport-specific identifiers. */
+      connectId: DataManager.isBleConnect(env) ? this.mainId || null : connectId,
+      /** Stable physical-device identity. */
+      serialNo,
+      /** @deprecated Use serialNo instead. */
       uuid: serialNo,
       commType: this.originalDescriptor.commType,
       sdkInstanceId: this.sdkInstanceId,
@@ -283,7 +342,7 @@ export class Device extends EventEmitter {
       label: label || 'OneKey',
       mode: this.getMode(),
       features,
-      sessionId: this.features?.sessionId ?? null,
+      state,
       firmwareVersion: this.getFirmwareVersion(),
       bleFirmwareVersion: this.getBLEFirmwareVersion(),
       unavailableCapabilities: this.unavailableCapabilities,
@@ -325,18 +384,20 @@ export class Device extends EventEmitter {
     });
   }
 
-  async acquire(connectProtocol?: HardwareConnectProtocol) {
+  async acquire(
+    connectProtocol?: HardwareConnectProtocol,
+    options?: { throwOnRunPromiseError?: boolean }
+  ) {
     const env = DataManager.getSettings('env');
     const mainIdKey = DataManager.isBleConnect(env) ? 'id' : 'session';
     const expectedProtocol = connectProtocol ?? 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,
@@ -374,6 +435,9 @@ export class Device extends EventEmitter {
 
       this.commands = new DeviceCommands(this, this.mainId ?? '');
     } catch (error) {
+      if (options?.throwOnRunPromiseError) {
+        throw error;
+      }
       if (this.runPromise) {
         this.runPromise.reject(error);
       } else {
@@ -474,12 +538,11 @@ export class Device extends EventEmitter {
   }
 
   /**
-   * 唯一协议判别器。
+   * Canonical protocol discriminator.
    *
-   * descriptor.protocolType 是协议探测后的结果；V2 features 由 DevGetDeviceInfo
-   * 映射产生。
-   * 全 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,7 +561,16 @@ export class Device extends EventEmitter {
   }
 
   getCurrentSerialNo() {
-    return this.features ? getDeviceUUID(this.features) : '';
+    return getDeviceSerialNo(this.features);
+  }
+
+  getConnectId() {
+    const serialNo = this.getCurrentSerialNo();
+    if (serialNo) return serialNo;
+
+    // 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() {
@@ -526,6 +598,11 @@ export class Device extends EventEmitter {
     return getDeviceBLEFirmwareVersion(this.features).join('.');
   }
 
+  getCurrentBootloaderVersionString() {
+    if (!this.features) return undefined;
+    return getDeviceBootloaderVersion(this.features).join('.');
+  }
+
   getCurrentSafetyChecks() {
     return this.features?.safetyChecks;
   }
@@ -591,9 +668,8 @@ 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 };
     }
@@ -611,13 +687,6 @@ 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;
@@ -627,13 +696,22 @@ export class Device extends EventEmitter {
     return undefined;
   }
 
+  private reconcileSessionCacheDeviceIdentity(previousDeviceId?: string) {
+    deviceWalletSessionStore.reconcileDeviceIdentity({
+      temporaryKey: this.isProtocolV2()
+        ? this.originalDescriptor.path || this.originalDescriptor.id
+        : 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}`
+      `hasPassphraseState: ${Boolean(this.passphraseState)}`
     );
 
     const deviceId = this.getSessionCacheDeviceKey(_deviceId);
@@ -646,8 +724,7 @@ 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);
   }
 
   // attach to pin to fix internal state
@@ -662,40 +739,30 @@ export class Device extends EventEmitter {
       '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;
-      }
-    }
-
-    // delete the old sessionId
-    const oldKey = `${cacheDeviceKey}`;
-    if (deviceSessionCache[oldKey]) {
-      delete deviceSessionCache[oldKey];
+      const walletSessionId =
+        sessionId || featuresSessionId || deviceWalletSessionStore.getPending(cacheDeviceKey);
+      deviceWalletSessionStore.set(cacheDeviceKey, passphraseState, walletSessionId ?? undefined);
     }
 
-    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}`
+      `hasPassphraseState: ${Boolean(this.passphraseState)}`
     );
 
     if (!this.passphraseState && !initSession) return;
@@ -703,12 +770,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) {
@@ -716,27 +782,27 @@ 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);
     }
   }
 
   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) {
-        // 不能直接信任缓存 features：设备端 wipe / 完成初始化 / 改 label 后
-        // features 会永久陈旧。每次 run 做一次轻量 status 刷新（不含 fw/SE），
-        // 用字段级合并保留已有版本和 SE 信息。
-        await this._refreshProtocolV2Status();
+      if (this.state && !options?.initSession && !this.protocolV2StateNeedsReload) {
+        if (this.features?.bootloaderMode) {
+          return;
+        }
+        // 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();
+      await this._initializeProtocolV2(options);
+      this.protocolV2StateNeedsReload = false;
       return;
     }
 
@@ -786,57 +852,38 @@ export class Device extends EventEmitter {
   /**
    * Device initialization over Protocol V2.
    *
-   * Protocol V2 不走传统 Initialize/GetFeatures；直接用 DevGetDeviceInfo
-   * 生成唯一的 features 状态。
+   * Protocol V2 bypasses legacy Initialize/GetFeatures and builds its canonical
+   * features state directly from DeviceInfoGet.
    */
-  private async _initializeProtocolV2() {
+  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 + bt + status（不含 fw/SE target）：status 提供 init_states / label /
-   * passphrase_protection 等会在设备端变化的字段；hw/bt 提供 serialNo / bleName。
-   * versions 为空时按字段级合并保留旧值，verify 数据不会被降级。
-   */
-  private async _refreshProtocolV2Status() {
-    try {
-      const deviceInfo = await requestProtocolV2DeviceInfo({
-        commands: this.commands,
-        request: PROTOCOL_V2_STATUS_DEVICE_INFO_REQUEST,
-      });
-      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', {});
@@ -844,7 +891,82 @@ 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();
+    }
+
+    if (!this.isProtocolV2() && refresh.has('verification')) {
+      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) {
+        const deviceInfo =
+          refreshedDeviceInfo ??
+          (await requestProtocolV2DeviceInfo({
+            commands: this.commands,
+            request: getProtocolV2DeviceInfoRequest(),
+          }));
+        await this.probeProtocolV2RuntimeState(deviceInfo);
+      }
+
+      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
@@ -854,26 +976,151 @@ export class Device extends EventEmitter {
     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;
   }
 
-  updateProtocolV2Features(deviceInfo?: ProtocolV2DeviceInfo) {
-    const features = fixFeaturesFirmwareVersion(
-      buildProtocolV2FeaturesPayload(deviceInfo, this.features)
+  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 probeProtocolV2RuntimeState(deviceInfo: ProtocolV2DeviceInfo, timeoutMs?: number) {
+    let deviceStatus: DeviceStatus;
+    try {
+      deviceStatus = await requestProtocolV2DeviceStatus({
+        commands: this.commands,
+        timeoutMs,
+      });
+    } catch (error) {
+      const runtimeMode = getProtocolV2RuntimeMode({
+        deviceInfo,
+        deviceStatusAvailable: false,
+      });
+      Log.debug('Protocol V2 DeviceStatusGet unavailable; use temporary loader fallback', {
+        runtimeMode,
+        error: error instanceof Error ? error.message : String(error),
+      });
+      return this.updateProtocolV2Features(deviceInfo, null, runtimeMode);
+    }
+    return this.updateProtocolV2Features(deviceInfo, deviceStatus, 'normal');
+  }
+
+  updateProtocolV2Features(
+    deviceInfo?: ProtocolV2DeviceInfo,
+    deviceStatus?: DeviceStatus | null,
+    runtimeMode?: ProtocolV2RuntimeMode
+  ) {
+    const previousDeviceId = this.getCurrentDeviceId();
+    const resolvedMode =
+      runtimeMode ??
+      (deviceStatus
+        ? getProtocolV2RuntimeMode({ deviceInfo, deviceStatusAvailable: true })
+        : this.state?.status.mode);
+    if (deviceInfo) {
+      this.updateState(mapProtocolV2DeviceInfoToState(deviceInfo, resolvedMode), 'device-info');
+    }
+    if (deviceStatus) {
+      this.updateState(mapProtocolV2DeviceStatusToState(deviceStatus), 'device-status');
+    }
+    this.reconcileSessionCacheDeviceIdentity(previousDeviceId);
+    return this.features as Features;
+  }
+
+  updateProtocolV2Status(status: DeviceStatus) {
+    const previousDeviceInfo = this.state?.raw?.protocolV2DeviceInfo;
+    const previousStatus = this.state?.raw?.protocolV2DeviceStatus;
+    return this.updateProtocolV2Features(previousDeviceInfo, {
+      ...previousStatus,
+      ...status,
+    });
+  }
+
+  markTransportDisconnected() {
+    if (!this.isProtocolV2()) return;
+    this.protocolV2StateNeedsReload = true;
+    this.clearPreInitialized();
+  }
+
+  markProtocolV2Reboot(rebootType: DeviceRebootType) {
+    if (!this.isProtocolV2()) return;
+
+    this.protocolV2StateNeedsReload = true;
+    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: { protocolV2DeviceStatus: null },
+        },
+        'transport-reconnect'
+      );
+      return;
+    }
+
+    this.updateState(
+      {
+        status: { mode: 'normal', unlocked: null },
+        raw: { protocolV2DeviceStatus: null },
+      },
+      'transport-reconnect'
     );
-    this.features = features;
-    this.featuresNeedsReload = false;
-    this.emit(DEVICE.FEATURES, this, features);
-    return features;
   }
 
   /**
@@ -894,8 +1141,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,
@@ -920,19 +1166,37 @@ 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) {
+  async _runInner<T>(
+    fn: (() => Promise<T>) | undefined,
+    options: RunOptions,
+    runPromise: Deferred<void>
+  ) {
+    const clearRunPromise = () => {
+      if (this.runPromise === runPromise) {
+        this.runPromise = null;
+      }
+    };
+
     if (!this.isUsedHere() || this.commands.disposed) {
       const env = DataManager.getSettings('env');
       if (env !== 'react-native') {
         try {
           await this.acquire(options.connectProtocol);
         } catch (error) {
-          this.runPromise = null;
-          return Promise.reject(error);
+          clearRunPromise();
+          runPromise.reject(error);
+          return;
         }
 
         try {
@@ -942,16 +1206,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
@@ -970,9 +1237,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 &&
@@ -985,7 +1250,7 @@ export class Device extends EventEmitter {
           Log.debug(`error code ${e.errorCode} release device, mainId: ${this.mainId}`);
         }
 
-        this.runPromise = null;
+        clearRunPromise();
         return;
       }
     }
@@ -999,11 +1264,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() {
@@ -1042,22 +1304,23 @@ 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
+    if (this.features?.bootloaderMode) return EOneKeyDeviceMode.bootloader;
+    if (this.features?.initialized === false) return EOneKeyDeviceMode.notInitialized;
+    if (this.features?.noBackup) return EOneKeyDeviceMode.backupMode;
     return EOneKeyDeviceMode.normal;
   }
 
@@ -1115,7 +1378,7 @@ export class Device extends EventEmitter {
     // 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)) {
@@ -1152,12 +1415,12 @@ 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;
   }
 
   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',
@@ -1166,6 +1429,26 @@ export class Device extends EventEmitter {
   }
 
   async unlockDevice() {
+    if (this.isProtocolV2()) {
+      try {
+        await this.commands.typedCall('DeviceSessionAskPin', 'Success', undefined, {
+          timeoutMs: 120_000,
+        });
+      } 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 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]
@@ -1175,9 +1458,7 @@ export class Device extends EventEmitter {
       this.features,
       Enum_Capability.Capability_AttachToPin
     );
-    // Pro2 (Protocol V2) 版本线独立于 Pro 系列，固件从首个版本即支持 UnLockDevice
     const supportUnlock =
-      this.isProtocolV2() ||
       supportAttachPinCapability ||
       (versionRange &&
         semver.valid(firmwareVersion) &&
@@ -1186,11 +1467,20 @@ 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;
+        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);
       }
@@ -1199,14 +1489,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',
@@ -1229,21 +1511,27 @@ export class Device extends EventEmitter {
   ) {
     if (this.isUnacquired()) return false;
 
+    const expectedPassphraseState = useEmptyPassphrase ? undefined : passphraseState;
     const { passphraseState: newPassphraseState, unlockedAttachPin } =
       await getPassphraseStateWithRefreshDeviceInfo(this, {
-        expectPassphraseState: passphraseState,
+        expectPassphraseState: expectedPassphraseState,
         onlyMainPin: useEmptyPassphrase,
       });
 
     // 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,
     });