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

package/src/api/OpenWalletSession.ts

@@ -1,4 +1,5 @@
 import { ERRORS, HardwareErrorCode } from '@onekeyfe/hd-shared';
+import { DeviceSessionPinType } from '@onekeyfe/hd-transport';
 
 import { deviceWalletSessionStore } from '../device/DeviceWalletSessionStore';
 import { getProtocolV2WalletSession } from '../protocols/protocol-v2/walletSession';
@@ -105,7 +106,12 @@ export default class OpenWalletSession extends BaseMethod<OpenWalletSessionParam
     };
     const unlockProtocolV2IfLocked = async () => {
       if (isProtocolV2 && state.status.unlocked === false) {
-        await this.device.unlockDevice();
+        await this.device.unlockDevice(DeviceSessionPinType.Main, {
+          source: 'unlock-coordinator',
+          reason: 'device-locked',
+          deviceOnly: true,
+          method: 'openWalletSession',
+        });
       }
     };
 
@@ -114,7 +120,12 @@ export default class OpenWalletSession extends BaseMethod<OpenWalletSessionParam
     if (this.params.mode === OpenWalletSessionMode.Standard) {
       this.device.passphraseState = undefined;
       const session = isProtocolV2
-        ? await getProtocolV2WalletSession(this.device, { onlyMainPin: true })
+        ? await getProtocolV2WalletSession(this.device, {
+            onlyMainPin: true,
+            deriveCardano: this.payload.deriveCardano,
+            selectMainWalletBeforeRestore:
+              state.status.unlocked === false || state.status.unlockedAttachPin === true,
+          })
         : await getPassphraseStateWithRefreshDeviceInfo(this.device, {
             onlyMainPin: true,
             initSession: this.payload.initSession,
@@ -166,6 +177,7 @@ export default class OpenWalletSession extends BaseMethod<OpenWalletSessionParam
       const session = isProtocolV2
         ? await getProtocolV2WalletSession(this.device, {
             expectedPassphraseState: this.params.passphraseState,
+            deriveCardano: this.payload.deriveCardano,
           })
         : await getPassphraseStateWithRefreshDeviceInfo(this.device, {
             expectPassphraseState: this.params.passphraseState,
@@ -187,7 +199,10 @@ export default class OpenWalletSession extends BaseMethod<OpenWalletSessionParam
     this.device.passphraseState = undefined;
     await unlockProtocolV2IfLocked();
     const session = isProtocolV2
-      ? await getProtocolV2WalletSession(this.device, { forceWalletSelection: true })
+      ? await getProtocolV2WalletSession(this.device, {
+          forceWalletSelection: true,
+          deriveCardano: this.payload.deriveCardano,
+        })
       : await getPassphraseStateWithRefreshDeviceInfo(this.device, { initSession: true });
     const deviceId = isProtocolV2 ? await refreshProtocolV2DeviceId() : requireDeviceId();
     if (isProtocolV2 && this.device.getCurrentPassphraseProtection() !== true) {

package/src/api/allnetwork/AllNetworkGetAddressBase.ts

@@ -14,6 +14,8 @@ import { findMethod } from '../utils';
 import { DEVICE, IFRAME, createUiMessage } from '../../events';
 import { UI_REQUEST } from '../../constants/ui-request';
 import { onDeviceButtonHandler } from '../../core';
+import { runMethodWithUnlockRetry } from '../../protocols/protocol-v2/unlockRetry';
+import { ensureProtocolV2WalletSessionUnlocked } from '../../protocols/protocol-v2/walletSession';
 import {
   completeRequestContext,
   createRequestContext,
@@ -384,7 +386,25 @@ export default abstract class AllNetworkGetAddressBase extends BaseMethod<
         }
       }
 
-      const response = await method.run();
+      // Protocol V2 hands a wallet session to exactly one blockchain request.
+      // The parent all-network call consumes its first handoff while fetching
+      // the root fingerprint, so each nested chain method must resume the
+      // requested hidden wallet before it sends its own device command.
+      if (this.device.isProtocolV2() && this.payload.passphraseState) {
+        await ensureProtocolV2WalletSessionUnlocked(this.device);
+        const passphraseStateSafety = await this.device.checkPassphraseStateSafety(
+          this.payload.passphraseState,
+          false,
+          this.payload.skipPassphraseCheck
+        );
+        if (!passphraseStateSafety) {
+          throw ERRORS.TypedError(HardwareErrorCode.DeviceCheckPassphraseStateError);
+        }
+      }
+
+      const response = this.device.isProtocolV2()
+        ? await runMethodWithUnlockRetry(method, this.device)
+        : await method.run();
 
       if (!Array.isArray(response) || response.length === 0) {
         throw new Error('No response');
@@ -439,7 +459,9 @@ export default abstract class AllNetworkGetAddressBase extends BaseMethod<
       show_display: false,
     });
 
-    this.postMessage(createUiMessage(UI_REQUEST.CLOSE_UI_PIN_WINDOW));
+    if (!this.device.isProtocolV2()) {
+      this.postMessage(createUiMessage(UI_REQUEST.CLOSE_UI_PIN_WINDOW));
+    }
 
     if (res.message.root_fingerprint == null) {
       throw ERRORS.TypedError(HardwareErrorCode.CallMethodInvalidParameter);

package/src/api/device/DeviceUnlock.ts

@@ -21,6 +21,6 @@ export default class DeviceUnlock extends BaseMethod<LockDevice> {
   }
 
   async run() {
-    return this.device.unlockDevice();
+    return this.device.unlockDevice(undefined, { emitUiEvent: false });
   }
 }

package/src/api/protocol-v2/ProtocolInfoRequest.ts

@@ -13,7 +13,9 @@ export default class ProtocolInfoRequest extends BaseMethod {
   }
 
   async run() {
-    const res = await this.device.commands.typedCall('ProtocolInfoRequest', 'ProtocolInfo', {});
+    const res = await this.device.commands.typedCall('ProtocolInfoRequest', 'ProtocolInfo', {
+      eventless_wallet_session: true,
+    });
     return Promise.resolve(res.message);
   }
 }

package/src/core/deviceEventRegistration.ts

@@ -4,6 +4,8 @@ import type { Device, DeviceEvents } from '../device/Device';
 
 export type HardwareUiEventHandlers = {
   pin: (...event: DeviceEvents[typeof DEVICE.PIN]) => void;
+  pinOnDevice: (...event: DeviceEvents[typeof DEVICE.PIN_ON_DEVICE]) => void;
+  pinOnDeviceComplete: (...event: DeviceEvents[typeof DEVICE.PIN_ON_DEVICE_COMPLETE]) => void;
   button: (...event: DeviceEvents[typeof DEVICE.BUTTON]) => void;
   passphrase: (...event: DeviceEvents[typeof DEVICE.PASSPHRASE]) => void;
   passphraseOnDevice: (...event: DeviceEvents[typeof DEVICE.PASSPHRASE_ON_DEVICE]) => void;
@@ -15,6 +17,8 @@ export function registerHardwareUiEventListeners(
   handlers: HardwareUiEventHandlers
 ) {
   device.on(DEVICE.PIN, handlers.pin);
+  device.on(DEVICE.PIN_ON_DEVICE, handlers.pinOnDevice);
+  device.on(DEVICE.PIN_ON_DEVICE_COMPLETE, handlers.pinOnDeviceComplete);
   device.on(DEVICE.BUTTON, handlers.button);
   device.on(DEVICE.PASSPHRASE, handlers.passphrase);
   device.on(DEVICE.PASSPHRASE_ON_DEVICE, handlers.passphraseOnDevice);

package/src/core/index.ts

@@ -1,6 +1,6 @@
 import semver from 'semver';
 import EventEmitter from 'events';
-import { TRANSPORT_EVENT } from '@onekeyfe/hd-transport';
+import { DeviceSessionPinType, TRANSPORT_EVENT } from '@onekeyfe/hd-transport';
 import {
   ERRORS,
   ERROR_CODES_REQUIRE_RELEASE,
@@ -56,6 +56,7 @@ import RequestQueue from './RequestQueue';
 import { registerHardwareUiEventListeners } from './deviceEventRegistration';
 import { getSynchronize } from '../utils/getSynchronize';
 import { runMethodWithUnlockRetry } from '../protocols/protocol-v2/unlockRetry';
+import { ensureProtocolV2WalletSessionUnlocked } from '../protocols/protocol-v2/walletSession';
 import {
   ProtocolV2UiInteractionCoordinator,
   isProtocolV2UiEnabled,
@@ -406,6 +407,8 @@ const onCallDevice = async (
 
   registerHardwareUiEventListeners(device, {
     pin: onDevicePinHandler,
+    pinOnDevice: onEnterPinOnDeviceHandler,
+    pinOnDeviceComplete: onPinOnDeviceCompleteHandler,
     button: onDeviceButtonHandler,
     passphrase: message.payload.useEmptyPassphrase
       ? onEmptyPassphraseHandler
@@ -421,6 +424,7 @@ const onCallDevice = async (
   );
 
   const protocolV2UiCoordinator = new ProtocolV2UiInteractionCoordinator(device, postMessage);
+  device.beginProtocolV2UiInteraction();
   device.on(
     DEVICE.SELECT_DEVICE_FOR_SWITCH_FIRMWARE_WEB_DEVICE,
     onSelectDeviceForSwitchFirmwareWebDeviceHandler
@@ -587,11 +591,15 @@ const onCallDevice = async (
           );
         }
 
+        // Wallet-session recovery is part of the protected business call, not onboarding.
+        await ensureProtocolV2WalletSessionUnlocked(device);
+
         // Check Device passphrase State
         const passphraseStateSafety = await device.checkPassphraseStateSafety(
           method.payload?.passphraseState,
           method.payload?.useEmptyPassphrase,
-          method.payload?.skipPassphraseCheck
+          method.payload?.skipPassphraseCheck,
+          hasDeriveCardano(method)
         );
 
         // Double check, handles the special case of Touch/Pro
@@ -604,8 +612,11 @@ const onCallDevice = async (
           );
         }
 
-        // close pin popup window
-        postMessage(createUiMessage(UI_REQUEST.CLOSE_UI_PIN_WINDOW));
+        // Protocol V2 emits the PIN phase completion from DeviceSessionAskPin.
+        // Keep the legacy compatibility close for Protocol V1 only.
+        if (!device.isProtocolV2()) {
+          postMessage(createUiMessage(UI_REQUEST.CLOSE_UI_PIN_WINDOW));
+        }
       }
 
       // Automatic check safety_check level for Kovan, Ropsten, Rinkeby, Goerli test networks.
@@ -1279,6 +1290,7 @@ const onDevicePassphraseHandler = async (
       source: requestPayload.source,
       reason: requestPayload.reason,
       expectedPassphraseState: requestPayload.expectedPassphraseState,
+      ...(requestPayload.interaction ? { interaction: requestPayload.interaction } : {}),
     })
   );
   // wait for passphrase
@@ -1308,6 +1320,7 @@ const onEnterPassphraseOnDeviceHandler = (
       passphraseState: device.passphraseState,
       source: requestPayload?.source,
       reason: requestPayload?.reason,
+      ...(requestPayload?.interaction ? { interaction: requestPayload.interaction } : {}),
     })
   );
 };
@@ -1321,10 +1334,39 @@ const onEnterAttachPinOnDeviceHandler = (
       type: 'ButtonRequest_AttachPin',
       source: requestPayload?.source,
       reason: requestPayload?.reason,
+      ...(requestPayload?.interaction ? { interaction: requestPayload.interaction } : {}),
     })
   );
 };
 
+const onEnterPinOnDeviceHandler = (
+  ...[device, pinType, metadata]: [...DeviceEvents['pin_on_device']]
+) => {
+  postMessage(
+    createUiMessage(UI_REQUEST.REQUEST_PIN, {
+      device: device.toMessageObject() as KnownDevice,
+      type:
+        pinType === DeviceSessionPinType.AttachToPin
+          ? 'ButtonRequest_AttachPin'
+          : 'ButtonRequest_PinEntry',
+      source: metadata?.source,
+      reason: metadata?.reason,
+      deviceOnly: metadata?.deviceOnly ?? true,
+      completion: metadata?.completion,
+      method: metadata?.method,
+      page: metadata?.page,
+      operation: metadata?.operation,
+      ...(metadata?.interaction ? { interaction: metadata.interaction } : {}),
+    })
+  );
+};
+
+const onPinOnDeviceCompleteHandler = (
+  ...[_, metadata]: [...DeviceEvents['pin_on_device_complete']]
+) => {
+  postMessage(createUiMessage(UI_REQUEST.CLOSE_UI_PIN_WINDOW, metadata));
+};
+
 const onSelectDeviceInBootloaderForWebDeviceHandler = async (
   ...[device, callback]: [...DeviceEvents['select_device_in_bootloader_for_web_device']]
 ) => {

package/src/data/messages/messages-protocol-v2.json

@@ -12200,11 +12200,26 @@
         "DeviceSessionError_Busy": 5
       }
     },
+    "DeviceSessionSeedDomain": {
+      "values": {
+        "SeedDomain_Standard": 1,
+        "SeedDomain_Cardano": 2
+      }
+    },
     "DeviceSessionGet": {
       "fields": {
         "session_id": {
           "type": "bytes",
           "id": 1
+        },
+        "btc_test_address": {
+          "type": "string",
+          "id": 2
+        },
+        "seed_domains": {
+          "rule": "repeated",
+          "type": "DeviceSessionSeedDomain",
+          "id": 3
         }
       }
     },

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';
@@ -110,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];
@@ -210,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();
   }
@@ -967,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') {
@@ -1044,15 +1080,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,
@@ -1078,10 +1157,18 @@ export class Device extends EventEmitter {
       );
     }
 
-    const deviceStatus = await requestProtocolV2DeviceStatus({
-      commands: this.commands,
-      timeoutMs,
-    });
+    let deviceStatus: DeviceStatus;
+    try {
+      deviceStatus = await requestProtocolV2DeviceStatus({
+        commands: this.commands,
+        timeoutMs,
+      });
+    } catch (error) {
+      if (runtimeMode === undefined && isProtocolV2DeviceStatusUnsupportedError(error)) {
+        return this.updateProtocolV2Features(deviceInfo, null, 'bootloader', protocolInfo);
+      }
+      throw error;
+    }
     return this.updateProtocolV2Features(deviceInfo, deviceStatus, 'normal', protocolInfo);
   }
 
@@ -1119,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();
   }
 
@@ -1127,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;
@@ -1142,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) {
@@ -1494,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 {
@@ -1503,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
@@ -1518,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);
     }
@@ -1579,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;
 
@@ -1588,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/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 {