@onekeyfe/hd-core 1.2.0-alpha.51 → 1.2.0-alpha.53

package/src/device/Device.ts

@@ -74,7 +74,9 @@ 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';
@@ -93,14 +95,10 @@ 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 = {
@@ -137,6 +135,8 @@ const isProtocolV2DeviceStatusUnsupportedError = (error: unknown) => {
 
 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];
@@ -235,6 +235,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();
   }
@@ -360,7 +378,10 @@ 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) => {
@@ -370,7 +391,7 @@ export class Device extends EventEmitter {
           return;
         }
         try {
-          await this.acquire(connectProtocol);
+          await this.acquire(connectProtocol, options);
           resolve(true);
         } catch (error) {
           reject(error);
@@ -380,7 +401,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);
@@ -397,11 +418,16 @@ export class Device extends EventEmitter {
 
   async acquire(
     expectedProtocol?: HardwareConnectProtocol,
-    options?: { throwOnRunPromiseError?: boolean }
+    options?: { throwOnRunPromiseError?: boolean; forceProtocolDetection?: boolean }
   ) {
     const env = DataManager.getSettings('env');
     const mainIdKey = DataManager.isBleConnect(env) ? 'id' : 'session';
-    const protocolHint = expectedProtocol ? undefined : 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)) {
@@ -413,8 +439,8 @@ export class Device extends EventEmitter {
           this.originalDescriptor.id,
           undefined,
           true,
-          expectedProtocol,
-          protocolHint
+          strictProtocol,
+          undefined
         );
         this.mainId = (acquireResult as any)?.uuid ?? '';
         Log.debug('Expected uuid:', this.mainId);
@@ -423,24 +449,31 @@ export class Device extends EventEmitter {
           this.originalDescriptor.path,
           this.originalDescriptor.session,
           undefined,
-          expectedProtocol,
-          protocolHint
+          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);
@@ -448,6 +481,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;
       }
@@ -856,7 +905,7 @@ export class Device extends EventEmitter {
         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,
+          timeoutMs: 25 * 1000,
         });
         this.setLastInitializeDuration(Date.now() - initStartAt);
         this._updateFeatures(message, initSession);
@@ -969,7 +1018,10 @@ export class Device extends EventEmitter {
       await this.getFeatures();
     }
 
-    if (!this.isProtocolV2() && refresh.has('verification')) {
+    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');
     }
@@ -992,13 +1044,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') {
@@ -1069,15 +1115,58 @@ export class Device extends EventEmitter {
     return this.features;
   }
 
-  async probeProtocolV2RuntimeState(deviceInfo: ProtocolV2DeviceInfo, timeoutMs?: number) {
-    const protocolInfo = await requestProtocolV2ProtocolInfo({
-      commands: this.commands,
-      timeoutMs,
-    });
+  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 protocolV2DeviceType = resolveProtocolV2DeviceIdentity(
-      deviceInfo.hw?.Device_type
-    ).deviceType;
+    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,
@@ -1152,6 +1241,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();
   }
 
@@ -1160,9 +1252,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;
@@ -1175,6 +1272,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) {
@@ -1281,11 +1381,17 @@ export class Device extends EventEmitter {
       }
     };
 
-    if (!this.isUsedHere() || this.commands.disposed) {
-      const env = DataManager.getSettings('env');
+    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) {
           clearRunPromise();
           runPromise.reject(error);
@@ -1527,6 +1633,85 @@ 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'],
+    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 {
     // This range applies to Protocol V1 Pro devices; Pro2 has a dedicated unlock flow.
     return {
@@ -1536,10 +1721,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
@@ -1551,6 +1759,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);
     }
@@ -1612,7 +1825,8 @@ export class Device extends EventEmitter {
   async checkPassphraseStateSafety(
     passphraseState?: string,
     useEmptyPassphrase?: boolean,
-    skipPassphraseCheck?: boolean
+    skipPassphraseCheck?: boolean,
+    deriveCardano?: boolean
   ) {
     if (this.isUnacquired()) return false;
 
@@ -1621,6 +1835,8 @@ export class Device extends EventEmitter {
       await getPassphraseStateWithRefreshDeviceInfo(this, {
         expectPassphraseState: expectedPassphraseState,
         onlyMainPin: useEmptyPassphrase,
+        deriveCardano,
+        rejectAttachPinForMainWallet: useEmptyPassphrase === true,
       });
 
     // Main wallet and unlock Attach Pin, throw safe error

package/src/device/DeviceCommands.ts

@@ -435,7 +435,13 @@ export class DeviceCommands {
       if (!shouldReduceDebugForCall(callType)) {
         Log.debug('_filterCommonTypes: ', {
           request: callType,
-          response: res.type,
+          response:
+            callType === 'DeviceFirmwareUpdateStatusGet'
+              ? {
+                  type: res.type,
+                  message: getSafeTransportLogPayload(res.message, res.type),
+                }
+              : res.type,
         });
       }
     } catch (error) {

package/src/device/DevicePool.ts

@@ -156,7 +156,9 @@ export class DevicePool extends EventEmitter {
     if (!device) {
       device = Device.fromDescriptor(descriptor);
       device.deviceConnector = this.connector;
-      await device.connect(initOptions?.connectProtocol);
+      await device.connect(initOptions?.connectProtocol, {
+        forceProtocolDetection: initOptions?.forceProtocolDetection,
+      });
       try {
         await device.initialize(initOptions);
         if (initOptions?.refreshRuntimeState && device.isProtocolV2()) {
@@ -181,7 +183,10 @@ export class DevicePool extends EventEmitter {
           refreshError = error;
         }
       },
-      { connectProtocol: initOptions.connectProtocol }
+      {
+        connectProtocol: initOptions.connectProtocol,
+        forceProtocolDetection: initOptions.forceProtocolDetection,
+      }
     );
     if (refreshError instanceof Error) throw refreshError;
     if (refreshError) throw new Error(String(refreshError));

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/logBlockEvent.ts

@@ -10,6 +10,7 @@ export const LogBlockEvent: Set<string> = new Set([
 
 const LogLabelMethod: Set<string> = new Set([
   'openWalletSession',
+  'deviceUploadNft',
   'deviceUploadWallpaper',
   'uploadPortfolio',
   'fileWrite',

package/src/events/ui-promise.ts

@@ -1,7 +1,7 @@
 import type { Deferred } from '@onekeyfe/hd-shared';
 import type { DEVICE } from './device';
 import type { Device } from '../device/Device';
-import type { UiResponseEvent } from './ui-response';
+import type { UiResponseCorrelation, UiResponseEvent } from './ui-response';
 
 export type UiPromiseResponse =
   | UiResponseEvent
@@ -11,4 +11,6 @@ export type UiPromise<T extends UiPromiseResponse['type']> = Deferred<
   Extract<UiPromiseResponse, { type: T }>,
   T,
   Device
->;
+> & {
+  responseCorrelation?: UiResponseCorrelation;
+};

package/src/events/ui-request.ts

@@ -1,6 +1,7 @@
 import type { PROTO } from '../constants';
 import type { Device } from '../types';
 import type { DeviceButtonRequest } from './device';
+import type { UiResponseCorrelation } from './ui-response';
 import type { MessageFactoryFn } from './utils';
 
 export const UI_EVENT = 'UI_EVENT';
@@ -56,6 +57,17 @@ 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';
+  device?: Device;
+};
+
 export type ProtocolV2UiEventMetadata = {
   source?: ProtocolV2UiEventSource;
   reason?: string;
@@ -64,12 +76,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
@@ -93,6 +122,7 @@ export type UiRequestDeviceAction = {
   payload: ProtocolV2UiEventMetadata & {
     device: Device;
     type?: PROTO.PinMatrixRequestType | 'ButtonRequest_PinEntry' | 'ButtonRequest_AttachPin';
+    responseCorrelation?: UiResponseCorrelation;
   };
 };
 
@@ -111,6 +141,8 @@ export interface UiRequestPassphrase {
     source?: 'wallet-session-coordinator';
     reason?: 'open-wallet' | 'session-recovery';
     expectedPassphraseState?: string;
+    interaction?: HardwareUiInteractionMeta;
+    responseCorrelation?: UiResponseCorrelation;
   };
 }
 
@@ -121,6 +153,7 @@ export interface UiRequestPassphraseOnDevice {
     passphraseState?: string;
     source?: 'wallet-session-coordinator';
     reason?: 'open-wallet' | 'session-recovery';
+    interaction?: HardwareUiInteractionMeta;
   };
 }
 
@@ -191,6 +224,7 @@ export interface PreviousAddressResult {
 
 export type UiEvent =
   | UiRequestWithoutPayload
+  | UiRequestWindowClose
   | UiRequestDeviceAction
   | UiRequestButton
   | UiRequestPassphraseOnDevice

package/src/events/ui-response.ts

@@ -11,12 +11,22 @@ export const UI_RESPONSE = {
     'ui-receive_select-device-for-switch-firmware-web-device',
 } as const;
 
-export interface UiResponsePin {
+export interface UiResponseCorrelation {
+  interactionId: string;
+  deviceId: string;
+}
+
+export interface UiResponseCorrelationFields {
+  interactionId?: string;
+  deviceId?: string;
+}
+
+export interface UiResponsePin extends UiResponseCorrelationFields {
   type: typeof UI_RESPONSE.RECEIVE_PIN;
   payload: string;
 }
 
-export interface UiResponsePassphrase {
+export interface UiResponsePassphrase extends UiResponseCorrelationFields {
   type: typeof UI_RESPONSE.RECEIVE_PASSPHRASE;
   payload: {
     value: string;