@onekeyfe/hd-core 1.2.0-alpha.19 → 1.2.0-alpha.20

package/src/deviceProfile/buildDeviceFeatures.ts

@@ -1,10 +1,15 @@
 import { EDeviceType, EFirmwareType } from '@onekeyfe/hd-shared';
-import { Enum_Capability } from '@onekeyfe/hd-transport';
 
 import {
-  isProtocolV2BootloaderDeviceInfo,
-  isProtocolV2RomloaderDeviceInfo,
-} from '../protocols/protocol-v2/features';
+  resolveDeviceBleFirmwareVersion,
+  resolveDeviceBleName,
+  resolveDeviceBoardVersion,
+  resolveDeviceBootloaderVersion,
+  resolveDeviceFirmwareType,
+  resolveDeviceFirmwareVersion,
+  resolveDeviceSerialNo,
+  resolveDeviceType,
+} from '../utils/deviceFeaturesCompat';
 
 import type {
   DeviceFirmwareImageInfo,
@@ -12,6 +17,7 @@ import type {
   ProtocolV2DeviceInfo,
 } from '@onekeyfe/hd-transport';
 import type { PROTO } from '../constants';
+import type { ProtocolV2RuntimeMode } from '../protocols/protocol-v2/features';
 import type { DeviceFeaturesMode, Features } from '../types';
 
 type ProtocolV1FeaturesCompat = PROTO.Features &
@@ -47,9 +53,6 @@ const firstValue = <T>(...values: Array<T | null | undefined>) =>
 const firstMeaningfulVersion = (...versions: Array<string | null | undefined>) =>
   versions.find(version => Boolean(version && version !== '0.0.0')) ?? null;
 
-const versionFromParts = (major?: number | null, minor?: number | null, patch?: number | null) =>
-  [major, minor, patch].map(part => Number(part) || 0).join('.');
-
 const getProtocolV1Mode = (features: ProtocolV1FeaturesCompat): Features['mode'] => {
   if (features.bootloader_mode === true) return 'bootloader';
   if (features.initialized === false) return 'notInitialized';
@@ -57,57 +60,6 @@ const getProtocolV1Mode = (features: ProtocolV1FeaturesCompat): Features['mode']
   return 'normal';
 };
 
-const getProtocolV1DeviceType = (features: ProtocolV1FeaturesCompat): Features['deviceType'] => {
-  const onekeyDeviceType = features.onekey_device_type as string | null | undefined;
-  switch (onekeyDeviceType) {
-    case 'CLASSIC':
-      return EDeviceType.Classic;
-    case 'CLASSIC1S':
-      return EDeviceType.Classic1s;
-    case 'MINI':
-      return EDeviceType.Mini;
-    case 'TOUCH':
-      return EDeviceType.Touch;
-    case 'PRO':
-      return EDeviceType.Pro;
-    case 'PRO2':
-    case 'pro2':
-      return EDeviceType.Pro2;
-    case 'PURE':
-      return EDeviceType.ClassicPure;
-    default:
-      break;
-  }
-
-  const serialNo = features.onekey_serial_no || features.onekey_serial || features.serial_no || '';
-  const prefix = serialNo.slice(0, 2).toLowerCase();
-  if (prefix === 'bi' || prefix === 'cl') return EDeviceType.Classic;
-  if (prefix === 'cp') return EDeviceType.ClassicPure;
-  if (prefix === 'mi') return EDeviceType.Mini;
-  if (prefix === 'tc') return EDeviceType.Touch;
-  if (prefix === 'pr') return EDeviceType.Pro;
-  if (prefix === 'p2') return EDeviceType.Pro2;
-  if (!serialNo && features.bootloader_mode === true && features.model === '1') {
-    return EDeviceType.Classic;
-  }
-  return EDeviceType.Unknown;
-};
-
-const getProtocolV1FirmwareType = (
-  features: ProtocolV1FeaturesCompat
-): Features['firmwareType'] => {
-  if (features.fw_vendor === 'OneKey Bitcoin-only') return EFirmwareType.BitcoinOnly;
-  const capabilities = features.capabilities as unknown as Array<number | string> | undefined;
-  if (
-    capabilities?.length &&
-    !capabilities.includes(Enum_Capability.Capability_Bitcoin_like) &&
-    !capabilities.includes('Capability_Bitcoin_like')
-  ) {
-    return EFirmwareType.BitcoinOnly;
-  }
-  return EFirmwareType.Universal;
-};
-
 const getProtocolV1Label = (features: ProtocolV1FeaturesCompat) =>
   typeof features.label === 'string' && features.label.length > 0 ? features.label : null;
 
@@ -117,32 +69,24 @@ export const buildProtocolV1FeaturesPayload = (
 ): Features => {
   const features = protocolV1Features as ProtocolV1FeaturesCompat;
   const firmwareVersion = firstMeaningfulVersion(
-    features.onekey_firmware_version,
-    features.onekey_version,
-    versionFromParts(features.major_version, features.minor_version, features.patch_version),
+    resolveDeviceFirmwareVersion(features),
     previous?.firmwareVersion
   );
   const bootloaderVersion = firstMeaningfulVersion(
-    features.onekey_boot_version,
-    features.bootloader_version,
-    features.bootloader_mode
-      ? versionFromParts(features.major_version, features.minor_version, features.patch_version)
-      : null,
+    resolveDeviceBootloaderVersion(features),
     previous?.bootloaderVersion
   );
   const boardVersion = firstMeaningfulVersion(
-    features.onekey_board_version,
-    features.boardloader_version,
+    resolveDeviceBoardVersion(features),
     previous?.boardVersion
   );
   const bleVersion = firstMeaningfulVersion(
-    features.onekey_ble_version,
-    features.ble_ver,
+    resolveDeviceBleFirmwareVersion(features),
     previous?.bleVersion
   );
-  const serialNo = features.onekey_serial_no || features.onekey_serial || features.serial_no || '';
-  const bleName = features.onekey_ble_name || features.ble_name || null;
-  const deviceType = getProtocolV1DeviceType(features);
+  const serialNo = resolveDeviceSerialNo(features);
+  const bleName = resolveDeviceBleName(features);
+  const deviceType = resolveDeviceType(features);
   const sessionId = features.session_id ?? previous?.sessionId ?? null;
 
   return {
@@ -150,7 +94,7 @@ export const buildProtocolV1FeaturesPayload = (
     protocol: 'V1',
     protocolVersion: features.protocol_version ?? previous?.protocolVersion ?? 1,
     deviceType,
-    firmwareType: getProtocolV1FirmwareType(features),
+    firmwareType: resolveDeviceFirmwareType(features),
     model: features.model ?? null,
     vendor: features.vendor ?? null,
     deviceId: features.device_id ?? null,
@@ -252,20 +196,22 @@ export const buildProtocolV1FeaturesPayload = (
 };
 
 /**
- * Protocol V2 的结构化 `Features` 构建器。
+ * Structured Protocol V2 `Features` builder.
  *
- * 这是 Device 内部唯一缓存状态。字段只来自 DeviceInfoGet 或前一次 features
- * 缓存的同名字段级合并；不存在协议等价语义的字段保持 null/空值，不再通过
- * 统一 DeviceState 或 transport path 做身份兜底。
+ * This is the only cached Device state. Fields come from DeviceInfoGet or same-name
+ * values in the previous cache. Fields without protocol-equivalent meaning remain
+ * null or empty and never fall back to DeviceState or a transport path.
  */
 export const buildProtocolV2FeaturesPayload = ({
   deviceInfo,
   deviceStatus,
   previous,
+  runtimeMode,
 }: {
   deviceInfo?: ProtocolV2DeviceInfo;
   deviceStatus?: DeviceStatus;
   previous?: Features;
+  runtimeMode?: ProtocolV2RuntimeMode;
 }): Features => {
   const info = deviceInfo;
   const fwApplication = info?.fw?.application;
@@ -293,8 +239,8 @@ export const buildProtocolV2FeaturesPayload = ({
   const label = cached?.label ?? null;
   const bleName = firstValue(info?.coprocessor?.bt_adv_name, cached?.bleName);
   const initialized = firstValue(status?.init_states, cached?.initialized) ?? null;
-  // Pro2 在锁定状态下返回的 passphrase_enabled 不是最终钱包状态。
-  // 只有完成 PIN 解锁后的 DeviceStatus 才能作为 passphrase 开关真值来源。
+  // passphrase_enabled from a locked Pro2 is not authoritative. Only DeviceStatus
+  // after PIN unlock can determine the final passphrase setting.
   let passphraseProtection = cached?.passphraseProtection ?? null;
   if (status?.unlocked === true) {
     passphraseProtection = status.passphrase_enabled ?? null;
@@ -306,21 +252,16 @@ export const buildProtocolV2FeaturesPayload = ({
   const attachToPinEnabled = status?.attach_to_pin_enabled ?? cached?.attachToPinEnabled ?? null;
   const unlockedAttachPin =
     status?.unlocked_by_attach_to_pin ?? cached?.unlockedAttachPin ?? undefined;
-  const romloaderMode = isProtocolV2RomloaderDeviceInfo(info, status);
-  const bootloaderMode = isProtocolV2BootloaderDeviceInfo(info, status);
+  const bootloaderMode = runtimeMode === 'bootloader';
   let mode: DeviceFeaturesMode = 'unknown';
-  if (romloaderMode) {
-    mode = 'romloader';
-  } else if (bootloaderMode) {
-    mode = 'bootloader';
+  if (runtimeMode) {
+    mode = runtimeMode;
   } else if (initialized === false) {
     mode = 'notInitialized';
   } else if (initialized === true) {
     mode = 'normal';
   } else if (cached?.mode === 'notInitialized' || cached?.mode === 'backupMode') {
     mode = cached.mode;
-  } else if (info) {
-    mode = 'normal';
   } else if (cached?.mode) {
     mode = cached.mode;
   }

package/src/events/logBlockEvent.ts

@@ -5,7 +5,14 @@ export const LogBlockEvent: Set<string> = new Set([
   UI_RESPONSE.RECEIVE_PASSPHRASE,
 ]);
 
-const LogBlockMethod: Set<string> = new Set(['evmSignTypedData', 'deviceSessionOpen']);
+const LogBlockMethod: Set<string> = new Set([
+  'evmSignTypedData',
+  'openWalletSession',
+  'deviceUploadWallpaper',
+  'uploadPortfolio',
+  'fileWrite',
+  'fileRead',
+]);
 
 export function getLogBlockLabel(message: unknown): string | undefined {
   if (!message || typeof message !== 'object') return undefined;

package/src/inject.ts

@@ -158,15 +158,19 @@ export const createCoreApi = (
   deviceRebootToBoardloader: connectId => call({ connectId, method: 'deviceRebootToBoardloader' }),
   deviceRebootToBootloader: connectId => call({ connectId, method: 'deviceRebootToBootloader' }),
 
-  // File system & device control API (Protocol V2 only)
-  protocolInfoRequest: (connectId, params) =>
-    call({ ...params, connectId, method: 'protocolInfoRequest' }),
-  ping: (connectId, params) => call({ ...params, connectId, method: 'ping' }),
+  // Pro2 business API
   deviceReboot: (connectId, params) => call({ ...params, connectId, method: 'deviceReboot' }),
   deviceGetOnboardingStatus: (connectId, params) =>
     call({ ...params, connectId, method: 'deviceGetOnboardingStatus' }),
-  deviceSessionOpen: (connectId, params) =>
-    call({ ...params, connectId, method: 'deviceSessionOpen' }),
+  deviceUploadWallpaper: (connectId, params) =>
+    call({ ...params, connectId, method: 'deviceUploadWallpaper' }),
+  deviceInfoGet: (connectId, params) => call({ ...params, connectId, method: 'deviceInfoGet' }),
+  deviceStatusGet: (connectId, params) => call({ ...params, connectId, method: 'deviceStatusGet' }),
+  deviceSettingsGet: (connectId, params) =>
+    call({ ...params, connectId, method: 'deviceSettingsGet' }),
+  protocolInfoRequest: (connectId, params) =>
+    call({ ...params, connectId, method: 'protocolInfoRequest' }),
+  ping: (connectId, params) => call({ ...params, connectId, method: 'ping' }),
   deviceFirmwareUpdate: (connectId, params) =>
     call({ ...params, connectId, method: 'deviceFirmwareUpdate' }),
   deviceGetFirmwareUpdateStatus: (connectId, params) =>
@@ -179,10 +183,10 @@ export const createCoreApi = (
     call({ ...params, connectId, method: 'deviceSettingsSet' }),
   deviceSettingsPageShow: (connectId, params) =>
     call({ ...params, connectId, method: 'deviceSettingsPageShow' }),
-  deviceUploadWallpaper: (connectId, params) =>
-    call({ ...params, connectId, method: 'deviceUploadWallpaper' }),
   filesystemPermissionFix: (connectId, params) =>
     call({ ...params, connectId, method: 'filesystemPermissionFix' }),
+  filesystemFormat: connectId => call({ connectId, method: 'filesystemFormat' }),
+  uploadPortfolio: (connectId, params) => call({ ...params, connectId, method: 'uploadPortfolio' }),
   fileRead: (connectId, params) => call({ ...params, connectId, method: 'fileRead' }),
   fileWrite: (connectId, params) => call({ ...params, connectId, method: 'fileWrite' }),
   fileDelete: (connectId, params) => call({ ...params, connectId, method: 'fileDelete' }),
@@ -190,22 +194,6 @@ export const createCoreApi = (
   dirMake: (connectId, params) => call({ ...params, connectId, method: 'dirMake' }),
   dirRemove: (connectId, params) => call({ ...params, connectId, method: 'dirRemove' }),
   pathInfo: (connectId, params) => call({ ...params, connectId, method: 'pathInfo' }),
-  filesystemFileRead: (connectId, params) =>
-    call({ ...params, connectId, method: 'filesystemFileRead' }),
-  filesystemFileWrite: (connectId, params) =>
-    call({ ...params, connectId, method: 'filesystemFileWrite' }),
-  uploadPortfolio: (connectId, params) => call({ ...params, connectId, method: 'uploadPortfolio' }),
-  filesystemFileDelete: (connectId, params) =>
-    call({ ...params, connectId, method: 'filesystemFileDelete' }),
-  filesystemDirList: (connectId, params) =>
-    call({ ...params, connectId, method: 'filesystemDirList' }),
-  filesystemDirMake: (connectId, params) =>
-    call({ ...params, connectId, method: 'filesystemDirMake' }),
-  filesystemDirRemove: (connectId, params) =>
-    call({ ...params, connectId, method: 'filesystemDirRemove' }),
-  filesystemPathInfoQuery: (connectId, params) =>
-    call({ ...params, connectId, method: 'filesystemPathInfoQuery' }),
-  filesystemFormat: connectId => call({ connectId, method: 'filesystemFormat' }),
   deviceRecovery: (connectId, params) => call({ ...params, connectId, method: 'deviceRecovery' }),
   deviceReset: (connectId, params) => call({ ...params, connectId, method: 'deviceReset' }),
   deviceSettings: (connectId, params) => call({ ...params, connectId, method: 'deviceSettings' }),
@@ -221,6 +209,8 @@ export const createCoreApi = (
     call({ ...params, connectId, method: 'deviceUpdateBootloader' }),
   getPassphraseState: (connectId, params) =>
     call({ ...params, connectId, method: 'getPassphraseState' }),
+  openWalletSession: (connectId, params) =>
+    call({ ...params, connectId, method: 'openWalletSession' }),
   deviceCancel: (connectId, params) => call({ ...params, connectId, method: 'deviceCancel' }),
   deviceLock: (connectId, params) => call({ ...params, connectId, method: 'deviceLock' }),
   deviceUnlock: (connectId, params) =>

package/src/protocols/protocol-v2/deviceSession.ts

@@ -0,0 +1,24 @@
+import { ERRORS, HardwareErrorCode } from '@onekeyfe/hd-shared';
+
+import type { DeviceSession } from '@onekeyfe/hd-transport';
+
+export type CompleteDeviceSession = DeviceSession & {
+  session_id: string;
+  btc_test_address: string;
+};
+
+export function assertCompleteDeviceSession(
+  message: DeviceSession
+): asserts message is CompleteDeviceSession {
+  if (
+    typeof message.session_id !== 'string' ||
+    !message.session_id ||
+    typeof message.btc_test_address !== 'string' ||
+    !message.btc_test_address
+  ) {
+    throw ERRORS.TypedError(
+      HardwareErrorCode.RuntimeError,
+      'DeviceSessionGet returned an incomplete DeviceSession response.'
+    );
+  }
+}

package/src/protocols/protocol-v2/features.ts

@@ -8,8 +8,7 @@ import type {
 } from '@onekeyfe/hd-transport';
 import type { DeviceCommands } from '../../device/DeviceCommands';
 
-// 单源类型：直接使用 hd-transport 生成的 ProtocolV2DeviceInfo / DeviceSEInfo /
-// DeviceFirmwareImageInfo（与 firmware-pro2 proto 一致），不再维护手写副本。
+// Use hd-transport generated Protocol V2 types as the single source of truth.
 export type { ProtocolV2DeviceInfo };
 export type { DeviceFirmwareImageInfo as ProtocolV2FirmwareImageInfo } from '@onekeyfe/hd-transport';
 export type { DeviceSEInfo as ProtocolV2SEInfo } from '@onekeyfe/hd-transport';
@@ -17,8 +16,8 @@ export type { DeviceSEInfo as ProtocolV2SEInfo } from '@onekeyfe/hd-transport';
 export type ProtocolV2SeStateLabel = 'BOOT' | 'APP_FACTORY' | 'APP';
 
 /**
- * 传输层沿用历史 decode 语义：单值 proto enum 输出为名称字符串。
- * 这里按 SDK decode 后的字符串语义处理，同时接受数字枚举，便于低层调用复用。
+ * The transport historically decodes scalar proto enums as name strings.
+ * Accept both that SDK representation and numeric enums for low-level callers.
  */
 const normalizeEnumValue = <T extends Record<string | number, string | number>>(
   enumObject: T,
@@ -31,8 +30,8 @@ const normalizeEnumValue = <T extends Record<string | number, string | number>>(
 };
 
 /**
- * DeviceSEInfo.state → 可读标签。SDK 内唯一的 SE 状态映射实现，
- * DeviceState Mapper 与老协议 Features 兼容投影都从这里取。
+ * Map DeviceSEInfo.state to a readable label. This is the SDK's canonical mapping
+ * used by DeviceState and the legacy Features projection.
  */
 export const getProtocolV2SeState = (se?: DeviceSEInfo): ProtocolV2SeStateLabel | null => {
   const label = normalizeEnumValue(DeviceSEState, se?.state);
@@ -49,57 +48,41 @@ export const getProtocolV2SeState = (se?: DeviceSEInfo): ProtocolV2SeStateLabel
 };
 
 /**
- * DeviceSEInfo.type → 可读标签（如 'THD89'）。DeviceState / Features
- * 的 SE 类型归一化从这里取。
+ * Map DeviceSEInfo.type to a readable label such as `THD89`.
  */
 export const getProtocolV2SeType = (se?: DeviceSEInfo): string | null =>
   normalizeEnumValue(DeviceSeType, se?.type);
 
+export type ProtocolV2RuntimeMode = 'normal' | 'bootloader';
+
 /**
- * 兼容尚未提供显式 runtime mode 的 Protocol V2 固件。
+ * TODO: Once firmware-pro2 exposes ProtocolInfo.build_fingerprint, parse the running
+ * binary name and remove the temporary DeviceStatusGet-failure heuristic. romloader
+ * is a separate recovery flow and is excluded until its contract is defined.
  *
- * 当前 romloader 只上报 hw、fw.romloader 和 fw.bootloader。普通版本读取也会
- * 返回 SE 信息，因此 SE 不能作为 bootloader 判据；在没有显式 runtime mode 的
- * 兼容固件上，只能把缺少 application/application_data 的非-romloader 形态视为
- * bootloader。
+ * The temporary contract has two states: DeviceStatusGet success means normal and
+ * failure means bootloader. Do not infer mode from application/SE/romloader fields.
  */
-export const isProtocolV2RomloaderDeviceInfo = (
-  deviceInfo?: ProtocolV2DeviceInfo | null,
-  deviceStatus?: DeviceStatus | null
-) =>
-  !!deviceInfo &&
-  deviceStatus == null &&
-  deviceInfo.fw?.romloader != null &&
-  deviceInfo.fw?.application == null &&
-  deviceInfo.fw?.application_data == null &&
-  deviceInfo.coprocessor == null &&
-  deviceInfo.se1 == null &&
-  deviceInfo.se2 == null &&
-  deviceInfo.se3 == null &&
-  deviceInfo.se4 == null;
-
-export const isProtocolV2BootloaderDeviceInfo = (
-  deviceInfo?: ProtocolV2DeviceInfo | null,
-  deviceStatus?: DeviceStatus | null
-) =>
-  !!deviceInfo &&
-  deviceStatus == null &&
-  !isProtocolV2RomloaderDeviceInfo(deviceInfo, deviceStatus) &&
-  deviceInfo.fw?.application == null &&
-  deviceInfo.fw?.application_data == null;
-
-export const isProtocolV2LoaderDeviceInfo = (
-  deviceInfo?: ProtocolV2DeviceInfo | null,
-  deviceStatus?: DeviceStatus | null
-) =>
-  isProtocolV2RomloaderDeviceInfo(deviceInfo, deviceStatus) ||
-  isProtocolV2BootloaderDeviceInfo(deviceInfo, deviceStatus);
+export const getProtocolV2RuntimeMode = ({
+  deviceInfo: _deviceInfo,
+  deviceStatusAvailable,
+}: {
+  deviceInfo?: ProtocolV2DeviceInfo | null;
+  deviceStatusAvailable: boolean;
+}): ProtocolV2RuntimeMode => {
+  if (deviceStatusAvailable) return 'normal';
+  return 'bootloader';
+};
 
 export const PROTOCOL_V2_FEATURES_DEVICE_INFO_REQUEST = {
   targets: {
     hw: true,
     fw: true,
     coprocessor: true,
+    se1: true,
+    se2: true,
+    se3: true,
+    se4: true,
   },
   types: {
     version: true,
@@ -108,8 +91,8 @@ export const PROTOCOL_V2_FEATURES_DEVICE_INFO_REQUEST = {
 };
 
 /**
- * 固件升级完成后的版本探测请求。
- * 仅读取硬件与各固件组件信息，不隐式请求 DeviceStatus。
+ * Version probe used after firmware update completion.
+ * It reads hardware and firmware component data without requesting DeviceStatus.
  */
 export const PROTOCOL_V2_VERSIONS_DEVICE_INFO_REQUEST = {
   targets: {
@@ -160,16 +143,21 @@ export async function requestProtocolV2DeviceInfo({
   const { message } = await commands.typedCall('DeviceInfoGet', 'DeviceInfo', request, {
     timeoutMs,
   });
-  // 'DeviceInfo' 在生成类型里是 V1 DeviceInfo | ProtocolV2DeviceInfo 的合并；
-  // DeviceInfoGet 是 V2-only 消息，这里收窄到 V2 形态。
+  // Generated DeviceInfo is a V1/V2 union; DeviceInfoGet narrows it to the V2 shape.
   return message as ProtocolV2DeviceInfo;
 }
 
 export async function requestProtocolV2DeviceStatus({
   commands,
+  timeoutMs,
 }: {
   commands: DeviceCommands;
+  timeoutMs?: number;
 }): Promise<DeviceStatus> {
-  const { message } = await commands.typedCall('DeviceStatusGet', 'DeviceStatus', {});
+  const response =
+    timeoutMs === undefined
+      ? await commands.typedCall('DeviceStatusGet', 'DeviceStatus', {})
+      : await commands.typedCall('DeviceStatusGet', 'DeviceStatus', {}, { timeoutMs });
+  const { message } = response;
   return message;
 }

package/src/protocols/protocol-v2/firmware.ts

@@ -1,5 +1,5 @@
 /**
- * 当前 firmware-pro2 子模块的 DeviceFirmwareTargetType。
+ * DeviceFirmwareTargetType from the current firmware-pro2 submodule.
  */
 export const ProtocolV2FirmwareTargetType = {
   FW_MGMT_TARGET_INVALID: 0,

package/src/protocols/protocol-v2/index.ts

@@ -3,9 +3,7 @@ export {
   PROTOCOL_V2_DEVICE_INFO_TIMEOUT_MS,
   PROTOCOL_V2_FEATURES_DEVICE_INFO_REQUEST,
   PROTOCOL_V2_VERSIONS_DEVICE_INFO_REQUEST,
-  isProtocolV2BootloaderDeviceInfo,
-  isProtocolV2LoaderDeviceInfo,
-  isProtocolV2RomloaderDeviceInfo,
+  getProtocolV2RuntimeMode,
   getProtocolV2SeState,
   getProtocolV2SeType,
 } from './features';
@@ -14,6 +12,7 @@ export type {
   ProtocolV2FirmwareImageInfo,
   ProtocolV2SEInfo,
   ProtocolV2SeStateLabel,
+  ProtocolV2RuntimeMode,
 } from './features';
 export * from './firmware';
 export * from './walletSession';

package/src/protocols/protocol-v2/settingsUnlockPolicy.ts

@@ -0,0 +1,61 @@
+import type { DeviceSettings, DeviceSettingsPage } from '@onekeyfe/hd-transport';
+import type { UnlockPolicy } from '../../api/BaseMethod';
+import type { ProtocolV2InteractionDescriptor } from './uiInteraction';
+
+const LOCK_FREE_DEVICE_SETTINGS = new Set<keyof DeviceSettings>([
+  'label',
+  'language',
+  'brightness',
+  'haptic_feedback',
+]);
+
+export const getProtocolV2SettingsUnlockPolicy = (settings: DeviceSettings): UnlockPolicy =>
+  Object.keys(settings).every(key => LOCK_FREE_DEVICE_SETTINGS.has(key as keyof DeviceSettings))
+    ? 'none'
+    : 'retry-on-locked';
+
+export type ProtocolV2SettingsOperation =
+  | {
+      kind: 'direct';
+      settings: DeviceSettings;
+    }
+  | {
+      kind: 'page';
+      page: DeviceSettingsPage;
+    };
+
+export const getProtocolV2SettingsBehavior = (
+  operation: ProtocolV2SettingsOperation
+): {
+  unlockPolicy: UnlockPolicy;
+  uiInteraction?: ProtocolV2InteractionDescriptor;
+} => {
+  if (operation.kind === 'page') {
+    return {
+      unlockPolicy: 'retry-on-locked',
+      uiInteraction: {
+        request: 'button',
+        source: 'method-lifecycle',
+        reason: 'settings-page',
+        completion: 'operation-completed',
+        deviceOnly: true,
+        page: operation.page,
+      },
+    };
+  }
+
+  return {
+    unlockPolicy: getProtocolV2SettingsUnlockPolicy(operation.settings),
+    uiInteraction:
+      typeof operation.settings.label === 'string'
+        ? {
+            request: 'button',
+            source: 'method-lifecycle',
+            reason: 'device-management',
+            completion: 'operation-completed',
+            deviceOnly: true,
+            operation: 'change-label',
+          }
+        : undefined,
+  };
+};

package/src/protocols/protocol-v2/uiInteraction.ts

@@ -88,8 +88,9 @@ const hasCipherConfirmation = (value: unknown): boolean => {
 };
 
 /**
- * Protocol V2 不再依赖固件 ButtonRequest，因此在统一层根据业务方法生成兼容 UI Event。
- * 显式声明始终优先；地址和公钥只在设备实际展示时提示，签名统一提示一次。
+ * Protocol V2 no longer relies on firmware ButtonRequest, so the SDK synthesizes
+ * compatible UI events. Explicit descriptors win; address/public-key prompts appear
+ * only when displayed, while signing emits one prompt.
  */
 export const resolveProtocolV2UiInteraction = (
   method: ProtocolV2InteractionMethod
@@ -106,7 +107,7 @@ export const resolveProtocolV2UiInteraction = (
     const payloadDisplay = getDisplayState(method.payload);
     const display = paramsDisplay.seen ? paramsDisplay : payloadDisplay;
 
-    // 地址接口通常默认在设备展示；公钥接口存在默认静默读取，优先依赖归一化参数。
+    // Address methods usually display by default; public-key methods may be silent.
     const shouldDisplay = display.seen ? display.enabled : isAddress;
     if (!shouldDisplay) return undefined;