@onekeyfe/hd-core 1.2.0-alpha.34 → 1.2.0-alpha.36

package/src/device/Device.ts

@@ -55,6 +55,7 @@ import { DataManager } from '../data-manager';
 import TransportManager from '../data-manager/TransportManager';
 import { toHardened } from '../api/helpers/pathUtils';
 import {
+  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,
@@ -62,21 +63,27 @@ import {
   getProtocolV2RuntimeMode,
   requestProtocolV2DeviceInfo,
   requestProtocolV2DeviceStatus,
+  requestProtocolV2ProtocolInfo,
+  supportsProtocolV2Message,
 } from '../protocols/protocol-v2/features';
 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';
@@ -105,8 +112,30 @@ 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.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];
@@ -205,6 +234,24 @@ export class Device extends EventEmitter {
   /** 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();
   }
@@ -835,8 +882,8 @@ export class Device extends EventEmitter {
 
       const expectedDeviceId = options?.deviceId;
       if (expectedDeviceId) {
-        // Verify the physical device with a read-only Features request. An
-        // empty-context Initialize would invalidate a cached V1 hidden-wallet session.
+        // 先只读校验物理设备身份；钱包上下文仍由下方携带完整参数的
+        // Initialize 选择，避免标准钱包请求复用此前的隐藏钱包上下文。
         this.passphraseState = undefined;
         const { message } = await this.commands.typedCall('GetFeatures', 'Features', {});
         this._updateFeatures(message);
@@ -864,15 +911,7 @@ export class Device extends EventEmitter {
         payload.derive_cardano = true;
       }
 
-      const requiresWalletInitialize =
-        !expectedDeviceId ||
-        Boolean(internalState) ||
-        Boolean(options?.passphraseState) ||
-        options?.deriveCardano === true ||
-        options?.initSession === true;
-      if (requiresWalletInitialize) {
-        await callInitialize(payload, options?.initSession);
-      }
+      await callInitialize(payload, options?.initSession);
     } catch (error) {
       Log.error('Initialization failed:', error);
       throw error;
@@ -970,13 +1009,7 @@ export class Device extends EventEmitter {
       }
 
       if (refresh.has('status') && !initializedWithDeviceInfo) {
-        const deviceInfo =
-          refreshedDeviceInfo ??
-          (await requestProtocolV2DeviceInfo({
-            commands: this.commands,
-            request: getProtocolV2DeviceInfoRequest(),
-          }));
-        await this.probeProtocolV2RuntimeState(deviceInfo);
+        await this.probeProtocolV2RuntimeState(refreshedDeviceInfo);
       }
 
       if (refresh.has('settings') && this.state?.status.mode === 'normal') {
@@ -1047,7 +1080,83 @@ export class Device extends EventEmitter {
     return this.features;
   }
 
-  async probeProtocolV2RuntimeState(deviceInfo: ProtocolV2DeviceInfo, timeoutMs?: number) {
+  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) {
+      throw ERRORS.TypedError(
+        HardwareErrorCode.DeviceInitializeFailed,
+        'Protocol V2 romloader mode is only supported for Pro2.'
+      );
+    }
+    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({
@@ -1055,33 +1164,28 @@ export class Device extends EventEmitter {
         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);
+      if (runtimeMode === undefined && isProtocolV2DeviceStatusUnsupportedError(error)) {
+        return this.updateProtocolV2Features(deviceInfo, null, 'bootloader', protocolInfo);
+      }
+      throw error;
     }
-    return this.updateProtocolV2Features(deviceInfo, deviceStatus, 'normal');
+    return this.updateProtocolV2Features(deviceInfo, deviceStatus, 'normal', protocolInfo);
   }
 
   updateProtocolV2Features(
     deviceInfo?: ProtocolV2DeviceInfo,
     deviceStatus?: DeviceStatus | null,
-    runtimeMode?: ProtocolV2RuntimeMode
+    runtimeMode?: ProtocolV2RuntimeMode,
+    protocolInfo?: ProtocolInfo
   ) {
     const previousDeviceId = this.getCurrentDeviceId();
-    const resolvedMode =
-      runtimeMode ??
-      (deviceStatus
-        ? getProtocolV2RuntimeMode({ deviceInfo, deviceStatusAvailable: true })
-        : this.state?.status.mode);
+    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');
     }
@@ -1102,6 +1206,9 @@ export class Device extends EventEmitter {
     this.deviceAcquired = false;
     if (!this.isProtocolV2()) return;
     this.protocolV2StateNeedsReload = true;
+    this.protocolV2RuntimeContext = undefined;
+    this.protocolV2RuntimeContextPromise = undefined;
+    this.protocolV2RuntimeContextRequestToken = undefined;
     this.clearPreInitialized();
   }
 
@@ -1110,9 +1217,14 @@ export class Device extends EventEmitter {
     if (deviceId) {
       deviceWalletSessionStore.deleteDevice(deviceId);
     }
-    if (this.isProtocolV2() && this.originalDescriptor.path !== deviceId) {
-      deviceWalletSessionStore.deleteDevice(this.originalDescriptor.path);
+    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;
@@ -1125,6 +1237,9 @@ export class Device extends EventEmitter {
     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) {
@@ -1150,7 +1265,7 @@ export class Device extends EventEmitter {
             attachToPinEnabled: null,
             unlockedAttachPin: null,
           },
-          raw: { protocolV2DeviceStatus: null },
+          raw: { protocolV2ProtocolInfo: null, protocolV2DeviceStatus: null },
         },
         'transport-reconnect'
       );
@@ -1160,7 +1275,7 @@ export class Device extends EventEmitter {
     this.updateState(
       {
         status: { mode: 'normal', unlocked: null },
-        raw: { protocolV2DeviceStatus: null },
+        raw: { protocolV2ProtocolInfo: null, protocolV2DeviceStatus: null },
       },
       'transport-reconnect'
     );
@@ -1406,7 +1521,16 @@ export class Device extends EventEmitter {
 
   isBootloader() {
     if (!this.state) return undefined;
-    return this.state.status.mode === 'bootloader' || this.state.status.mode === 'romloader';
+    return this.state.status.mode === 'bootloader';
+  }
+
+  isRomloader() {
+    if (!this.state) return undefined;
+    return (
+      this.isProtocolV2() &&
+      this.getCurrentDeviceType() === EDeviceType.Pro2 &&
+      this.state.status.mode === 'romloader'
+    );
   }
 
   isInitialized() {
@@ -1468,6 +1592,75 @@ export class Device extends EventEmitter {
     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'] = 'succeeded') {
+    const interaction = this.protocolV2UiInteraction;
+    if (!interaction?.opened) {
+      this.protocolV2UiInteraction = undefined;
+      return undefined;
+    }
+
+    const phaseId = `${interaction.interactionId}:phase-${Math.max(interaction.phaseCounter, 1)}`;
+    const metadata = this.createProtocolV2UiPhaseMetadata('processing', 'finish', {
+      phaseId,
+      outcome,
+    });
+    this.protocolV2UiInteraction = undefined;
+    return metadata;
+  }
+
+  hasOpenProtocolV2UiInteraction() {
+    return this.protocolV2UiInteraction?.opened === true;
+  }
+
   supportUnlockVersionRange(): DeviceFirmwareRange {
     // This range applies to Protocol V1 Pro devices; Pro2 has a dedicated unlock flow.
     return {
@@ -1477,10 +1670,33 @@ export class Device extends EventEmitter {
     };
   }
 
-  async unlockDevice(pinType: DeviceSessionPinType = DeviceSessionPinType.Main) {
+  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: pinType });
+        await this.commands.typedCall('DeviceSessionAskPin', 'Success', {
+          type: requestedPinType,
+        });
       } catch (error) {
         const errorText =
           error instanceof Error
@@ -1492,6 +1708,11 @@ export class Device extends EventEmitter {
         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);
     }
@@ -1553,7 +1774,8 @@ export class Device extends EventEmitter {
   async checkPassphraseStateSafety(
     passphraseState?: string,
     useEmptyPassphrase?: boolean,
-    skipPassphraseCheck?: boolean
+    skipPassphraseCheck?: boolean,
+    deriveCardano?: boolean
   ) {
     if (this.isUnacquired()) return false;
 
@@ -1562,6 +1784,7 @@ export class Device extends EventEmitter {
       await getPassphraseStateWithRefreshDeviceInfo(this, {
         expectPassphraseState: expectedPassphraseState,
         onlyMainPin: useEmptyPassphrase,
+        deriveCardano,
       });
 
     // Main wallet and unlock Attach Pin, throw safe error

package/src/device/DeviceCommands.ts

@@ -6,6 +6,7 @@ import {
   type Messages,
   type Transport,
   type TransportCallOptions,
+  getSafeTransportLogPayload,
 } from '@onekeyfe/hd-transport';
 
 import TransportManager from '../data-manager/TransportManager';
@@ -282,7 +283,11 @@ export class DeviceCommands {
   ): Promise<DefaultMessageResponse> {
     const shouldReduceDebug = shouldReduceDebugForCall(type);
     if (!shouldReduceDebug) {
-      Log.debug('[DeviceCommands] [call] Sending', type);
+      Log.debug(
+        '[DeviceCommands] [call] Sending',
+        type,
+        getSafeTransportLogPayload(msg ?? {}, type)
+      );
     }
 
     try {
@@ -290,13 +295,18 @@ export class DeviceCommands {
       this.callPromise = promise;
       const res = await promise;
       if (!shouldReduceDebug) {
-        LogCore.debug('[DeviceCommands] [call] Received', res.type);
+        LogCore.debug(
+          '[DeviceCommands] [call] Received',
+          res.type,
+          getSafeTransportLogPayload(res.message, res.type)
+        );
       }
       return res;
     } catch (error) {
       LogCore.debug('[DeviceCommands] [call] Received error', {
         request: type,
         errorCode: error?.errorCode,
+        response: getSafeTransportLogPayload(error?.response?.data, type),
       });
       if (error.errorCode === HardwareErrorCode.BleDeviceBondError) {
         return {

package/src/device/DeviceWalletSessionStore.ts

@@ -1,6 +1,4 @@
 export class DeviceWalletSessionStore {
-  private static readonly MAX_SESSIONS_PER_DEVICE = 3;
-
   private readonly walletSessions = new Map<string, Map<string, string>>();
 
   private readonly standardWalletSessions = new Map<
@@ -22,18 +20,6 @@ export class DeviceWalletSessionStore {
       deviceSessions = new Map<string, string>();
       this.walletSessions.set(deviceKey, deviceSessions);
     }
-    if (
-      !deviceSessions.has(passphraseState) &&
-      deviceSessions.size >= DeviceWalletSessionStore.MAX_SESSIONS_PER_DEVICE
-    ) {
-      const oldestPassphraseState = deviceSessions.keys().next().value as string | undefined;
-      if (oldestPassphraseState) {
-        deviceSessions.delete(oldestPassphraseState);
-        if (this.standardWalletSessions.get(deviceKey)?.passphraseState === oldestPassphraseState) {
-          this.standardWalletSessions.delete(deviceKey);
-        }
-      }
-    }
     deviceSessions.set(passphraseState, sessionId);
   }
 

package/src/deviceProfile/buildDeviceFeatures.ts

@@ -260,7 +260,7 @@ 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 bootloaderMode = runtimeMode === 'bootloader';
+  const bootloaderMode = runtimeMode === 'bootloader' || runtimeMode === 'romloader';
   let mode: DeviceFeaturesMode = 'unknown';
   if (runtimeMode) {
     mode = runtimeMode;

package/src/events/device.ts

@@ -1,4 +1,5 @@
 import type { MessageFactoryFn } from './utils';
+import type { HardwareUiInteractionMeta } from './ui-request';
 import type { PROTO } from '../constants';
 import type {
   KnownDevice as Device,
@@ -26,6 +27,8 @@ export const DEVICE = {
   // onekey-transport events in protobuf format
   BUTTON: 'button',
   PIN: 'pin',
+  PIN_ON_DEVICE: 'pin_on_device',
+  PIN_ON_DEVICE_COMPLETE: 'pin_on_device_complete',
   PASSPHRASE: 'passphrase',
   PASSPHRASE_ON_DEVICE: 'passphrase_on_device',
   ATTACH_PIN_ON_DEVICE: 'attach_pin_on_device',
@@ -58,6 +61,7 @@ export type PassphraseRequestPayload = {
   source?: 'wallet-session-coordinator';
   reason?: 'open-wallet' | 'session-recovery';
   expectedPassphraseState?: string;
+  interaction?: HardwareUiInteractionMeta;
 };
 
 export interface DeviceButtonRequest {

package/src/events/ui-request.ts

@@ -56,6 +56,16 @@ export type ProtocolV2UiEventSource =
 
 export type ProtocolV2UiCompletion = 'page-accepted' | 'operation-completed';
 
+export type HardwareUiInteractionMeta = {
+  interactionId: string;
+  phaseId: string;
+  sequence: number;
+  phase: 'pin' | 'passphrase' | 'passphrase-on-device' | 'button' | 'processing';
+  transition: 'start' | 'complete' | 'finish';
+  outcome?: 'submitted' | 'succeeded' | 'failed' | 'cancelled' | 'disconnected';
+  protocol: 'V2';
+};
+
 export type ProtocolV2UiEventMetadata = {
   source?: ProtocolV2UiEventSource;
   reason?: string;
@@ -64,12 +74,29 @@ export type ProtocolV2UiEventMetadata = {
   method?: string;
   page?: string | number;
   operation?: string;
+  interaction?: HardwareUiInteractionMeta;
 };
 
+export type UiRequestWindowClose =
+  | {
+      type: typeof UI_REQUEST.CLOSE_UI_WINDOW;
+      payload: HardwareUiInteractionMeta;
+    }
+  | {
+      type: typeof UI_REQUEST.CLOSE_UI_PIN_WINDOW;
+      payload: HardwareUiInteractionMeta;
+    }
+  | {
+      type: typeof UI_REQUEST.CLOSE_UI_WINDOW;
+      payload?: undefined;
+    }
+  | {
+      type: typeof UI_REQUEST.CLOSE_UI_PIN_WINDOW;
+      payload?: undefined;
+    };
+
 export interface UiRequestWithoutPayload {
   type:
-    | typeof UI_REQUEST.CLOSE_UI_WINDOW
-    | typeof UI_REQUEST.CLOSE_UI_PIN_WINDOW
     | typeof UI_REQUEST.BLUETOOTH_PERMISSION
     | typeof UI_REQUEST.BLUETOOTH_UNSUPPORTED
     | typeof UI_REQUEST.BLUETOOTH_POWERED_OFF
@@ -111,6 +138,7 @@ export interface UiRequestPassphrase {
     source?: 'wallet-session-coordinator';
     reason?: 'open-wallet' | 'session-recovery';
     expectedPassphraseState?: string;
+    interaction?: HardwareUiInteractionMeta;
   };
 }
 
@@ -121,6 +149,7 @@ export interface UiRequestPassphraseOnDevice {
     passphraseState?: string;
     source?: 'wallet-session-coordinator';
     reason?: 'open-wallet' | 'session-recovery';
+    interaction?: HardwareUiInteractionMeta;
   };
 }
 
@@ -191,6 +220,7 @@ export interface PreviousAddressResult {
 
 export type UiEvent =
   | UiRequestWithoutPayload
+  | UiRequestWindowClose
   | UiRequestDeviceAction
   | UiRequestButton
   | UiRequestPassphraseOnDevice