@onekeyfe/hd-core 1.2.0-alpha.4 → 1.2.0-alpha.41

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

@@ -0,0 +1,210 @@
+import { UI_REQUEST, createUiMessage } from '../../events';
+
+import type { CoreMessage, ProtocolV2UiCompletion } from '../../events';
+import type { Device } from '../../device/Device';
+import type { KnownDevice } from '../../types';
+
+export type ProtocolV2InteractionDescriptor = {
+  request: 'button' | 'pin';
+  source: 'method-lifecycle';
+  reason:
+    | 'change-pin'
+    | 'device-unlock'
+    | 'settings-page'
+    | 'address-confirmation'
+    | 'public-key-confirmation'
+    | 'signing-confirmation'
+    | 'device-management';
+  completion: ProtocolV2UiCompletion;
+  deviceOnly: true;
+  page?: string | number;
+  operation?: string;
+};
+
+type ProtocolV2InteractionMethod = {
+  name?: string;
+  params?: unknown;
+  payload?: unknown;
+  protocolV2UiInteraction?: ProtocolV2InteractionDescriptor;
+};
+
+type InteractionDevice = Pick<Device, 'isProtocolV2' | 'toMessageObject'>;
+type PostMessage = (message: CoreMessage) => void;
+
+export const isProtocolV2UiEnabled = (method: { protocolV2UiMode?: 'auto' | 'none' }) =>
+  method.protocolV2UiMode !== 'none';
+
+const getDisplayState = (value: unknown) => {
+  const visited = new Set<object>();
+  let seen = false;
+  let enabled = false;
+
+  const visit = (current: unknown) => {
+    if (current == null || typeof current !== 'object') return;
+    if (visited.has(current)) return;
+    visited.add(current);
+
+    if (Array.isArray(current)) {
+      current.forEach(visit);
+      return;
+    }
+
+    Object.entries(current).forEach(([key, item]) => {
+      if ((key === 'show_display' || key === 'showOnOneKey') && typeof item === 'boolean') {
+        seen = true;
+        enabled ||= item;
+        return;
+      }
+      visit(item);
+    });
+  };
+
+  visit(value);
+  return { seen, enabled };
+};
+
+const createMethodInteraction = (
+  reason: 'address-confirmation' | 'public-key-confirmation' | 'signing-confirmation',
+  operation: string
+): ProtocolV2InteractionDescriptor => ({
+  request: 'button',
+  source: 'method-lifecycle',
+  reason,
+  completion: 'operation-completed',
+  deviceOnly: true,
+  operation,
+});
+
+const hasCipherConfirmation = (value: unknown): boolean => {
+  if (Array.isArray(value)) return value.some(hasCipherConfirmation);
+  if (value == null || typeof value !== 'object') return false;
+
+  const params = value as {
+    encrypt?: boolean;
+    ask_on_encrypt?: boolean;
+    ask_on_decrypt?: boolean;
+  };
+  return params.encrypt === true ? params.ask_on_encrypt === true : params.ask_on_decrypt === true;
+};
+
+/**
+ * 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
+): ProtocolV2InteractionDescriptor | undefined => {
+  if (method.protocolV2UiInteraction) return method.protocolV2UiInteraction;
+
+  const operation = method.name;
+  if (!operation) return undefined;
+
+  const isAddress = /getAddress(?:ByLoop)?$/i.test(operation);
+  const isPublicKey = /getPublicKey$/i.test(operation);
+  if (isAddress || isPublicKey) {
+    const paramsDisplay = getDisplayState(method.params);
+    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;
+
+    return createMethodInteraction(
+      isAddress ? 'address-confirmation' : 'public-key-confirmation',
+      operation
+    );
+  }
+
+  if (/sign/i.test(operation) || /verifyMessage$/i.test(operation) || operation === 'lnurlAuth') {
+    return createMethodInteraction('signing-confirmation', operation);
+  }
+
+  if (operation === 'nostrEncryptMessage' || operation === 'nostrDecryptMessage') {
+    const display = getDisplayState(method.params);
+    if (!display.enabled) return undefined;
+    return createMethodInteraction('signing-confirmation', operation);
+  }
+
+  if (operation === 'cipherKeyValue' && hasCipherConfirmation(method.params)) {
+    return createMethodInteraction('signing-confirmation', operation);
+  }
+
+  return undefined;
+};
+
+export class ProtocolV2UiInteractionCoordinator {
+  private readonly device: InteractionDevice;
+
+  private readonly postMessage: PostMessage;
+
+  private methodInteraction?: ProtocolV2InteractionDescriptor;
+
+  private currentPhase?: string;
+
+  private opened = false;
+
+  private closed = false;
+
+  constructor(device: InteractionDevice, postMessage: PostMessage) {
+    this.device = device;
+    this.postMessage = postMessage;
+  }
+
+  enterMethodInteraction(interaction?: ProtocolV2InteractionDescriptor) {
+    this.methodInteraction = interaction;
+    if (!interaction) return;
+    const { request, ...metadata } = interaction;
+
+    this.emit(
+      request === 'pin' ? UI_REQUEST.REQUEST_PIN : UI_REQUEST.REQUEST_BUTTON,
+      {
+        device: this.device.toMessageObject() as KnownDevice,
+        ...metadata,
+      },
+      `method:${request}:${interaction.reason}:${interaction.page ?? ''}:${
+        interaction.operation ?? ''
+      }`
+    );
+  }
+
+  enterUnlockInteraction(method?: string) {
+    this.emit(
+      UI_REQUEST.REQUEST_PIN,
+      {
+        device: this.device.toMessageObject() as KnownDevice,
+        source: 'unlock-coordinator',
+        reason: 'device-locked',
+        deviceOnly: true,
+        method,
+      },
+      `unlock:${method ?? ''}`
+    );
+  }
+
+  resumeMethodInteraction() {
+    this.enterMethodInteraction(this.methodInteraction);
+  }
+
+  close() {
+    if (!this.device.isProtocolV2() || !this.opened || this.closed) return;
+    this.closed = true;
+    this.postMessage(createUiMessage(UI_REQUEST.CLOSE_UI_WINDOW));
+  }
+
+  private emit(
+    type: typeof UI_REQUEST.REQUEST_BUTTON | typeof UI_REQUEST.REQUEST_PIN,
+    payload: any,
+    phase: string
+  ) {
+    if (!this.device.isProtocolV2() || this.closed || this.currentPhase === phase) return;
+    this.currentPhase = phase;
+    this.opened = true;
+    const message =
+      type === UI_REQUEST.REQUEST_BUTTON
+        ? createUiMessage(UI_REQUEST.REQUEST_BUTTON, payload)
+        : createUiMessage(UI_REQUEST.REQUEST_PIN, payload);
+    this.postMessage(message);
+  }
+}

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

@@ -0,0 +1,105 @@
+export type UnlockPolicy = 'none' | 'unlock-before-run' | 'retry-on-locked';
+
+/**
+ * Protocol V2 methods that are safe to replay after a locked response.
+ *
+ * Keep this as an exact allowlist. Name-pattern matching can silently make a new
+ * state-changing method replayable when it happens to share a suffix.
+ */
+export const PROTOCOL_V2_RETRY_ON_LOCKED_METHODS = [
+  'cipherKeyValue',
+  'allNetworkGetAddress',
+  'allNetworkGetAddressByLoop',
+  'btcGetAddress',
+  'btcGetPublicKey',
+  'btcSignMessage',
+  'btcSignPsbt',
+  'btcSignTransaction',
+  'btcVerifyMessage',
+  'confluxGetAddress',
+  'confluxSignMessage',
+  'confluxSignTransaction',
+  'evmGetAddress',
+  'evmGetPublicKey',
+  'evmSignMessage',
+  'evmSignTransaction',
+  'evmSignTypedData',
+  'evmVerifyMessage',
+  'starcoinGetAddress',
+  'starcoinGetPublicKey',
+  'starcoinSignMessage',
+  'starcoinSignTransaction',
+  'starcoinVerifyMessage',
+  'nemGetAddress',
+  'nemSignTransaction',
+  'solGetAddress',
+  'solSignTransaction',
+  'solSignOffchainMessage',
+  'solSignMessage',
+  'stellarGetAddress',
+  'stellarSignTransaction',
+  'tronGetAddress',
+  'tronSignMessage',
+  'tronSignTransaction',
+  'nearGetAddress',
+  'nearSignTransaction',
+  'aptosGetAddress',
+  'aptosGetPublicKey',
+  'aptosSignTransaction',
+  'aptosSignMessage',
+  'aptosSignInMessage',
+  'algoGetAddress',
+  'algoSignTransaction',
+  'cosmosGetAddress',
+  'cosmosGetPublicKey',
+  'cosmosSignTransaction',
+  'xrpGetAddress',
+  'xrpSignTransaction',
+  'suiGetAddress',
+  'suiGetPublicKey',
+  'suiSignMessage',
+  'suiSignTransaction',
+  'cardanoGetAddress',
+  'cardanoGetPublicKey',
+  'cardanoSignTransaction',
+  'cardanoSignMessage',
+  'filecoinGetAddress',
+  'filecoinSignTransaction',
+  'polkadotGetAddress',
+  'polkadotSignTransaction',
+  'kaspaGetAddress',
+  'kaspaSignTransaction',
+  'nexaGetAddress',
+  'nexaSignTransaction',
+  'nostrGetPublicKey',
+  'nostrSignEvent',
+  'nostrEncryptMessage',
+  'nostrDecryptMessage',
+  'nostrSignSchnorr',
+  'lnurlAuth',
+  'nervosGetAddress',
+  'nervosSignTransaction',
+  'dnxGetAddress',
+  'dnxSignTransaction',
+  'tonGetAddress',
+  'tonSignMessage',
+  'tonSignProof',
+  'tonSignData',
+  'scdoGetAddress',
+  'scdoSignTransaction',
+  'scdoSignMessage',
+  'alephiumGetAddress',
+  'alephiumSignTransaction',
+  'alephiumSignMessage',
+  'benfenGetAddress',
+  'benfenGetPublicKey',
+  'benfenSignMessage',
+  'benfenSignTransaction',
+  'neoGetAddress',
+  'neoSignTransaction',
+] as const;
+
+const retryOnLockedMethods = new Set<string>(PROTOCOL_V2_RETRY_ON_LOCKED_METHODS);
+
+export const getProtocolV2UnlockPolicy = (methodName: string): UnlockPolicy =>
+  retryOnLockedMethods.has(methodName) ? 'retry-on-locked' : 'none';

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

@@ -0,0 +1,109 @@
+import { LoggerNames, getLogger } from '../../utils';
+import { isDeviceLockedError } from './lockedError';
+import { isProtocolV2UiEnabled, resolveProtocolV2UiInteraction } from './uiInteraction';
+import { refreshProtocolV2DeviceStatus, restoreProtocolV2WalletSession } from './walletSession';
+
+import type { BaseMethod } from '../../api/BaseMethod';
+import type { Device } from '../../device/Device';
+import type { ProtocolV2UiInteractionCoordinator } from './uiInteraction';
+
+const Log = getLogger(LoggerNames.Core);
+
+type RunnableMethod = Pick<
+  BaseMethod,
+  | 'run'
+  | 'unlockPolicy'
+  | 'protocolV2UiInteraction'
+  | 'protocolV2UiMode'
+  | 'params'
+  | 'payload'
+  | 'useDevicePassphraseState'
+> & { name?: string };
+type UiInteractionCoordinator = Pick<
+  ProtocolV2UiInteractionCoordinator,
+  'enterMethodInteraction' | 'enterUnlockInteraction' | 'resumeMethodInteraction'
+>;
+
+const restoreExpectedWalletSessionAfterUnlock = async (method: RunnableMethod, device: Device) => {
+  const expectedPassphraseState = method.payload?.useEmptyPassphrase
+    ? undefined
+    : method.payload?.passphraseState ?? device.passphraseState;
+  if (
+    !method.useDevicePassphraseState ||
+    typeof expectedPassphraseState !== 'string' ||
+    expectedPassphraseState.length === 0
+  ) {
+    return;
+  }
+
+  await restoreProtocolV2WalletSession(device, expectedPassphraseState);
+  Log.debug('Protocol V2 wallet session restored after unlock', { method: method.name });
+};
+
+export async function runMethodWithUnlockRetry(
+  method: RunnableMethod,
+  device: Device,
+  uiCoordinator?: UiInteractionCoordinator
+) {
+  const shouldEmitUi = isProtocolV2UiEnabled(method);
+  const isProtocolV2 = device.isProtocolV2();
+  const requiresFreshStatus =
+    isProtocolV2 &&
+    method.unlockPolicy === 'unlock-before-run' &&
+    !device.isBootloader?.() &&
+    !device.isRomloader?.();
+
+  if (requiresFreshStatus) {
+    await refreshProtocolV2DeviceStatus(device);
+  }
+
+  const shouldUnlockBeforeRun =
+    isProtocolV2 &&
+    method.unlockPolicy !== 'none' &&
+    !device.isBootloader?.() &&
+    !device.isRomloader?.() &&
+    device.features?.unlocked === false;
+
+  if (shouldUnlockBeforeRun) {
+    if (shouldEmitUi) {
+      uiCoordinator?.enterUnlockInteraction(method.name);
+    }
+    await device.unlockDevice();
+    Log.debug('Protocol V2 pre-unlock completed', { method: method.name });
+    await restoreExpectedWalletSessionAfterUnlock(method, device);
+    if (shouldEmitUi) {
+      uiCoordinator?.enterMethodInteraction(resolveProtocolV2UiInteraction(method));
+    }
+    return method.run();
+  }
+
+  if (shouldEmitUi) {
+    uiCoordinator?.enterMethodInteraction(resolveProtocolV2UiInteraction(method));
+  }
+  try {
+    return await method.run();
+  } catch (error) {
+    if (!isProtocolV2 || method.unlockPolicy !== 'retry-on-locked' || !isDeviceLockedError(error)) {
+      throw error;
+    }
+
+    Log.debug('Protocol V2 unlock retry triggered', { method: method.name });
+    if (shouldEmitUi) {
+      uiCoordinator?.enterUnlockInteraction(method.name);
+    }
+    await device.unlockDevice();
+    Log.debug('Protocol V2 unlock completed', { method: method.name });
+    await restoreExpectedWalletSessionAfterUnlock(method, device);
+    if (shouldEmitUi) {
+      uiCoordinator?.resumeMethodInteraction();
+    }
+    try {
+      const response = await method.run();
+      Log.debug('Protocol V2 method retry completed', { method: method.name, success: true });
+      return response;
+    } catch (retryError) {
+      Log.debug('Protocol V2 method retry completed', { method: method.name, success: false });
+      throw retryError;
+    }
+  }
+}

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

@@ -0,0 +1,285 @@
+import { ERRORS, HardwareErrorCode } from '@onekeyfe/hd-shared';
+import { DeviceSessionPinType } from '@onekeyfe/hd-transport';
+
+import { DEVICE } from '../../events';
+import { assertCompleteDeviceSession } from './deviceSession';
+
+import type { DeviceSessionAskPassphrase, DeviceSessionGet } from '@onekeyfe/hd-transport';
+import type { Device } from '../../device/Device';
+
+const HOST_PASSPHRASE_MAX_BYTES = 50;
+
+const isWalletSessionInvalidError = (error: unknown) =>
+  typeof error === 'object' &&
+  error !== null &&
+  'errorCode' in error &&
+  (error as { errorCode?: unknown }).errorCode === HardwareErrorCode.WalletSessionInvalid;
+
+const utf8ByteLength = (value: string): number | undefined => {
+  let length = 0;
+  for (const character of value) {
+    const codePoint = character.codePointAt(0) ?? 0;
+    if (codePoint >= 0xd800 && codePoint <= 0xdfff) return undefined;
+    if (codePoint <= 0x7f) length += 1;
+    else if (codePoint <= 0x7ff) length += 2;
+    else if (codePoint <= 0xffff) length += 3;
+    else length += 4;
+  }
+  return length;
+};
+
+export async function requestProtocolV2DeviceStatus(device: Device) {
+  const { message } = await device.commands.typedCall('DeviceStatusGet', 'DeviceStatus', {});
+  return message;
+}
+
+export async function refreshProtocolV2DeviceStatus(device: Device) {
+  const status = await requestProtocolV2DeviceStatus(device);
+  return device.updateProtocolV2Status(status);
+}
+
+const negotiateEventlessWalletSession = async (device: Device) => {
+  await device.commands.typedCall('ProtocolInfoRequest', 'ProtocolInfo', {
+    eventless_wallet_session: true,
+  });
+};
+
+const getDeviceSession = async (device: Device, request: DeviceSessionGet) =>
+  device.commands.typedCall('DeviceSessionGet', 'DeviceSession', request);
+
+const askDevicePassphrase = async (device: Device, requestPayload: DeviceSessionAskPassphrase) => {
+  await device.commands.typedCall('DeviceSessionAskPassphrase', 'Success', requestPayload);
+  await refreshProtocolV2DeviceStatus(device);
+};
+
+const selectDeviceSession = async (device: Device, expectedPassphraseState?: string) => {
+  const existsAttachPinUser = device.features?.attachToPinEnabled === true;
+  const metadata = {
+    source: 'wallet-session-coordinator' as const,
+    reason: expectedPassphraseState ? ('session-recovery' as const) : ('open-wallet' as const),
+    ...(expectedPassphraseState ? { expectedPassphraseState } : {}),
+  };
+  const response = await device.commands.promptPassphrase(
+    {
+      existsAttachPinUser,
+      deviceOnly: false,
+      ...metadata,
+    },
+    { cancelDeviceOnReject: false }
+  );
+  const hostPassphrase =
+    typeof response.passphrase === 'string' ? response.passphrase.normalize('NFKD') : undefined;
+  const hasHostPassphrase = typeof hostPassphrase === 'string' && hostPassphrase.length > 0;
+  const hostPassphraseByteLength = hasHostPassphrase ? utf8ByteLength(hostPassphrase) : undefined;
+  if (
+    hasHostPassphrase &&
+    (hostPassphrase.includes('\0') ||
+      hostPassphraseByteLength === undefined ||
+      hostPassphraseByteLength > HOST_PASSPHRASE_MAX_BYTES)
+  ) {
+    throw ERRORS.TypedError(
+      HardwareErrorCode.RuntimeError,
+      `Host passphrase must contain 1 to ${HOST_PASSPHRASE_MAX_BYTES} valid UTF-8 bytes without NUL.`
+    );
+  }
+  const selections = [
+    hasHostPassphrase,
+    response.passphraseOnDevice === true,
+    response.attachPinOnDevice === true,
+  ].filter(Boolean).length;
+
+  if (selections !== 1) {
+    throw ERRORS.TypedError(
+      HardwareErrorCode.RuntimeError,
+      'Wallet selection must contain exactly one passphrase access mode.'
+    );
+  }
+
+  if (response.attachPinOnDevice) {
+    if (!existsAttachPinUser) {
+      throw ERRORS.TypedError(
+        HardwareErrorCode.RuntimeError,
+        'Attach PIN wallet selection is unavailable on this device.'
+      );
+    }
+    device.emit(DEVICE.ATTACH_PIN_ON_DEVICE, device, metadata);
+    await device.unlockDevice(DeviceSessionPinType.AttachToPin);
+    return getDeviceSession(device, {});
+  }
+
+  if (hasHostPassphrase) {
+    await askDevicePassphrase(device, {
+      passphrase: hostPassphrase,
+      on_device: false,
+    });
+    return getDeviceSession(device, {});
+  }
+
+  device.emit(DEVICE.PASSPHRASE_ON_DEVICE, device, metadata);
+  await askDevicePassphrase(device, { on_device: true });
+  return getDeviceSession(device, {});
+};
+
+export async function getProtocolV2WalletSession(
+  device: Device,
+  options?: {
+    forceWalletSelection?: boolean;
+    /** @deprecated 兼容旧 getPassphraseState；新流程使用 forceWalletSelection。 */
+    initSession?: boolean;
+    expectedPassphraseState?: string;
+    onlyMainPin?: boolean;
+    resumeOnly?: boolean;
+  }
+) {
+  const forceWalletSelection =
+    options?.forceWalletSelection === true || options?.initSession === true;
+
+  if (forceWalletSelection) {
+    if (options.onlyMainPin) {
+      device.clearStandardInternalState?.();
+    } else {
+      device.clearInternalState();
+    }
+    device.passphraseState = undefined;
+  }
+
+  await negotiateEventlessWalletSession(device);
+
+  if (options?.onlyMainPin) {
+    device.passphraseState = undefined;
+  }
+  let expectedPassphraseState = options?.onlyMainPin
+    ? undefined
+    : options?.expectedPassphraseState ?? device.passphraseState;
+
+  const cachedStandardSession = options?.onlyMainPin
+    ? device.getStandardInternalState?.()
+    : undefined;
+  const cachedSessionId =
+    !options?.onlyMainPin && typeof device.getInternalState === 'function'
+      ? device.getInternalState()
+      : undefined;
+  let response;
+  let resumed = false;
+
+  if (options?.onlyMainPin) {
+    expectedPassphraseState = cachedStandardSession?.passphraseState;
+    if (cachedStandardSession) {
+      try {
+        if (device.features?.unlockedAttachPin === true) {
+          await device.unlockDevice(DeviceSessionPinType.Main);
+        }
+        response = await getDeviceSession(device, {
+          session_id: cachedStandardSession.sessionId,
+        });
+        resumed = true;
+      } catch (error) {
+        device.clearStandardInternalState?.();
+        if (!isWalletSessionInvalidError(error)) {
+          throw error;
+        }
+        resumed = false;
+      }
+    }
+
+    if (!response) {
+      await device.unlockDevice(DeviceSessionPinType.Main);
+      response = await getDeviceSession(device, {});
+    }
+  } else if (cachedSessionId && expectedPassphraseState) {
+    try {
+      response = await getDeviceSession(device, { session_id: cachedSessionId });
+      resumed = true;
+    } catch (error) {
+      device.clearInternalState();
+      if (options?.resumeOnly || !isWalletSessionInvalidError(error)) {
+        throw error;
+      }
+      resumed = false;
+    }
+  }
+
+  if (!response) {
+    if (options?.resumeOnly) {
+      device.clearInternalState();
+      throw ERRORS.TypedError(HardwareErrorCode.WalletSessionInvalid);
+    }
+    response = await selectDeviceSession(device, expectedPassphraseState);
+  }
+
+  let { message } = response;
+  try {
+    assertCompleteDeviceSession(message);
+  } catch (error) {
+    if (options?.onlyMainPin) {
+      device.clearStandardInternalState?.();
+    } else {
+      device.clearInternalState();
+    }
+    throw error;
+  }
+  if (expectedPassphraseState && expectedPassphraseState !== message.btc_test_address) {
+    resumed = false;
+    if (options?.resumeOnly) {
+      device.clearInternalState();
+      throw ERRORS.TypedError(HardwareErrorCode.WalletSessionInvalid);
+    }
+    if (options?.onlyMainPin) {
+      device.clearStandardInternalState?.();
+      await device.unlockDevice(DeviceSessionPinType.Main);
+      response = await getDeviceSession(device, {});
+    } else {
+      device.clearInternalState();
+      response = await selectDeviceSession(device, expectedPassphraseState);
+    }
+    message = response.message;
+    try {
+      assertCompleteDeviceSession(message);
+    } catch (error) {
+      if (options?.onlyMainPin) {
+        device.clearStandardInternalState?.();
+      } else {
+        device.clearInternalState();
+      }
+      throw error;
+    }
+    if (expectedPassphraseState !== message.btc_test_address) {
+      if (options?.onlyMainPin) {
+        device.clearStandardInternalState?.();
+      } else {
+        device.clearInternalState();
+      }
+      throw ERRORS.TypedError(HardwareErrorCode.DeviceCheckPassphraseStateError);
+    }
+  }
+
+  const internalStateArgs = [
+    true,
+    message.btc_test_address,
+    device.getCurrentDeviceId(),
+    message.session_id,
+    forceWalletSelection ? null : cachedSessionId ?? null,
+  ] as const;
+  if (options?.onlyMainPin) {
+    device.updateInternalState(...internalStateArgs, 'standard');
+  } else {
+    device.updateInternalState(...internalStateArgs);
+  }
+
+  return {
+    passphraseState: message.btc_test_address,
+    newSession: message.session_id,
+    unlockedAttachPin: device.features?.unlockedAttachPin ?? undefined,
+    resumed,
+  };
+}
+
+export async function restoreProtocolV2WalletSession(
+  device: Device,
+  expectedPassphraseState: string
+) {
+  return getProtocolV2WalletSession(device, {
+    expectedPassphraseState,
+    resumeOnly: true,
+  });
+}