chore(runway): cherry-pick fix: hw account abstraction migration (#30261)

runway-github[bot] · aganglada · gambinish · web-flow · commit a8a95d8c95a9 · 2026-05-15T16:53:31.000Z
- fix: hw account abstraction migration (#30114)  ## **Description** This PR prevents Perps from triggering browsing-time signing flows for hardware wallet users while the screen is idle. Previously, Unified Account setup only deferred the `dexAbstraction` migration when user signing was not allowed. Other signing-backed HyperLiquid abstraction modes could still attempt setup during passive Perps initialization, which could surface repeated hardware wallet prompts without an explicit user action. The fix adds a shared helper for deciding when Unified Account setup must be deferred, applies it during HyperLiquid provider initialization, and expands hardware wallet detection to cover MetaMask's hardware keyring types: Ledger, Trezor, OneKey, Lattice, and QR hardware wallets. Software wallets can still complete setup during initialization so the first trade sees unified collateral, while hardware wallets defer setup until an explicit trading or withdrawal action. ## **Changelog** CHANGELOG entry: Fixed a bug that could repeatedly prompt hardware wallet users while Perps was idle. ## **Related issues** Fixes: ## **Manual testing steps** ```gherkin Feature: Perps hardware wallet idle setup Scenario: Hardware wallet user opens Perps and leaves it idle Given the user has selected a Ledger, Trezor, OneKey, Lattice, or QR hardware wallet account And Perps is enabled and available When the user opens the Perps screen And leaves the Perps screen idle without placing an order, withdrawing, or otherwise starting a signing action Then the app does not repeatedly show hardware wallet signing prompts ``` ```gherkin Feature: Perps software wallet setup Scenario: Software wallet user opens Perps Given the user has selected a software wallet account that needs Unified Account setup When the user opens the Perps screen Then Perps can complete the setup flow during initialization And the first trade can use unified collateral without an extra setup step ``` ## **Screenshots/Recordings** N/A. This is a controller behavior change with no intended UI changes. ### **Before** N/A ### **After** N/A ## **Pre-merge author checklist**  - [x] I've followed [MetaMask Contributor Docs](https://github.com/MetaMask/contributor-docs) and [MetaMask Mobile Coding Standards](https://github.com/MetaMask/metamask-mobile/blob/main/.github/guidelines/CODING_GUIDELINES.md). - [x] I've completed the PR template to the best of my ability - [x] I've included tests if applicable - [x] I've documented my code using [JSDoc](https://jsdoc.app/) format if applicable - [x] I've applied the right labels on the PR (see [labeling guidelines](https://github.com/MetaMask/metamask-mobile/blob/main/.github/guidelines/LABELING_GUIDELINES.md)). Not required for external contributors. #### Performance checks (if applicable) - [ ] I've tested on Android - Ideally on a mid-range device; emulator is acceptable - [ ] I've tested with a power user scenario - Use these [power-user SRPs](https://consensyssoftware.atlassian.net/wiki/spaces/TL1/pages/edit-v2/401401446401?draftShareId=9d77e1e1-4bdc-4be1-9ebb-ccd916988d93) to import wallets with many accounts and tokens - [ ] I've instrumented key operations with Sentry traces for production performance metrics - See [`trace()`](/app/util/trace.ts) for usage and [`addToken`](/app/components/Views/AddAsset/components/AddCustomToken/AddCustomToken.tsx#L274) for an example For performance guidelines and tooling, see the [Performance Guide](https://consensyssoftware.atlassian.net/wiki/spaces/TL1/pages/400085549067/Performance+Guide+for+Engineers). ## **Pre-merge reviewer checklist**  - [x] I've manually tested the PR (e.g. pull and build branch, run the app, test code being changed). - [x] I confirm that this PR addresses all acceptance criteria described in the ticket it closes and includes the necessary testing evidence such as recordings and or screenshots.  --- > [!NOTE] > **Medium Risk** > Changes when unified-account migration and other signing-backed setup runs, which can affect Perps initialization and migration behavior for hardware wallet users. Risk is moderated by added unit tests and a narrow decision helper, but incorrect deferral could delay required setup until action time. > > **Overview** > Prevents browsing-time hardware wallet signing prompts by deferring HyperLiquid unified-account migration during Perps initialization whenever the current abstraction mode would require a signing-backed transition and user signing is not allowed. > > Adds `shouldDeferUnifiedAccountSetup` to centralize this decision (with new unit tests), updates `HyperLiquidProvider` to use it, and expands `HyperLiquidWalletService.isSelectedHardwareWallet()` to recognize additional MetaMask hardware keyring types (Ledger, Trezor, OneKey, Lattice, QR). Also updates related tests and log/comment wording from *QR popup spam* to *hardware wallet signing prompt spam*. > > <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit 6f8cfe2. Bugbot is set up for automated code reviews on this repo. Configure [here](https://www.cursor.com/dashboard/bugbot).</sup>  [4669b3a](4669b3a) --------- Co-authored-by: Alejandro Garcia Anglada <aganglada@gmail.com> Co-authored-by: Nicholas Gambino <nicholas.gambino@consensys.net>
diff --git a/app/controllers/perps/providers/HyperLiquidProvider.test.ts b/app/controllers/perps/providers/HyperLiquidProvider.test.ts
@@ -5963,7 +5963,7 @@ describe('HyperLiquidProvider', () => {
       const result = await provider.placeOrder(orderParams);
 
       // PR #25334: Builder fee approval is now non-blocking (fire-and-forget)
-      // to prevent QR popup spam for hardware wallets.
+      // to prevent repeated signing prompts for hardware wallets.
       // Order should proceed even if builder fee approval fails.
       expect(result.success).toBe(true);
       expect(result.orderId).toBeDefined();
@@ -8957,12 +8957,12 @@ describe('HyperLiquidProvider', () => {
     });
 
     // ─────────────────────────────────────────────────
-    // dexAbstraction → unifiedAccount migration on init
+    // Signing-backed unifiedAccount migration on init
     //
-    // The transition requires an EIP-712 prompt (HL blocks the agent path),
-    // so software-wallet users migrate during initial setup to ensure the
-    // first trade sees unified collateral. Hardware wallets remain deferred
-    // to avoid QR / Ledger prompt spam while browsing.
+    // Some transitions require an EIP-712 prompt, so software-wallet users
+    // migrate during initial setup to ensure the first trade sees unified
+    // collateral. Hardware wallets remain deferred to avoid repeated signing
+    // prompts while browsing.
     // ─────────────────────────────────────────────────
 
     it('calls userSetAbstraction on init for software-wallet dexAbstraction users', async () => {
@@ -9100,33 +9100,36 @@ describe('HyperLiquidProvider', () => {
       ).toHaveBeenCalledWith(USER_ADDRESS, 'unifiedAccount');
     });
 
-    it('defers dexAbstraction migration on init for hardware wallets', async () => {
-      // Arrange
-      mockWalletService.isSelectedHardwareWallet.mockReturnValue(true);
-      const mockExchangeClient = createMockExchangeClient();
-      mockClientService.getInfoClient = jest.fn().mockReturnValue(
-        createMockInfoClient({
-          userAbstraction: jest.fn().mockResolvedValue('dexAbstraction'),
-        }),
-      );
-      mockClientService.getExchangeClient = jest
-        .fn()
-        .mockReturnValue(mockExchangeClient);
+    it.each(['dexAbstraction', 'default', 'disabled'] as const)(
+      'defers %s migration on init for hardware wallets',
+      async (currentMode) => {
+        // Arrange
+        mockWalletService.isSelectedHardwareWallet.mockReturnValue(true);
+        const mockExchangeClient = createMockExchangeClient();
+        mockClientService.getInfoClient = jest.fn().mockReturnValue(
+          createMockInfoClient({
+            userAbstraction: jest.fn().mockResolvedValue(currentMode),
+          }),
+        );
+        mockClientService.getExchangeClient = jest
+          .fn()
+          .mockReturnValue(mockExchangeClient);
 
-      // Act - init path
-      await provider.getMarketDataWithPrices();
+        // Act - init path
+        await provider.getMarketDataWithPrices();
 
-      // Assert - no browsing-time hardware prompt; action-time setup can still run.
-      expect(mockExchangeClient.userSetAbstraction).not.toHaveBeenCalled();
-      expect(mockExchangeClient.agentSetAbstraction).not.toHaveBeenCalled();
-      expect(
-        (TradingReadinessCache as jest.Mocked<typeof TradingReadinessCache>)
-          .set,
-      ).not.toHaveBeenCalled();
-      expect(
-        mockSubscriptionService.setUserAbstractionMode,
-      ).not.toHaveBeenCalled();
-    });
+        // Assert - no browsing-time hardware prompt; action-time setup can still run.
+        expect(mockExchangeClient.userSetAbstraction).not.toHaveBeenCalled();
+        expect(mockExchangeClient.agentSetAbstraction).not.toHaveBeenCalled();
+        expect(
+          (TradingReadinessCache as jest.Mocked<typeof TradingReadinessCache>)
+            .set,
+        ).not.toHaveBeenCalled();
+        expect(
+          mockSubscriptionService.setUserAbstractionMode,
+        ).not.toHaveBeenCalled();
+      },
+    );
 
     it('does NOT call setUserAbstractionMode when migration fails', async () => {
       const mockExchangeClient = createMockExchangeClient();
diff --git a/app/controllers/perps/providers/HyperLiquidProvider.ts b/app/controllers/perps/providers/HyperLiquidProvider.ts
@@ -128,7 +128,8 @@ import {
   addSpotBalanceToAccountState,
   aggregateAccountStates,
 } from '../utils/accountUtils';
-import { ensureError } from '../utils/errorUtils';
+import { ensureError, isKeyringLockedError } from '../utils/errorUtils';
+import { shouldDeferUnifiedAccountSetup } from '../utils/hyperLiquidAbstraction';
 import {
   adaptAccountStateFromSDK,
   adaptHyperLiquidLedgerUpdateToUserHistoryItem,
@@ -627,7 +628,8 @@ export class HyperLiquidProvider implements PerpsProvider {
     const network = this.#clientService.isTestnetMode() ? 'testnet' : 'mainnet';
 
     // Check global cache first to avoid repeated signing requests
-    // This is CRITICAL for hardware wallets to prevent QR popup spam
+    // This is CRITICAL for hardware wallets to prevent repeated signing prompts
+    // while browsing.
     const cachedStatus = TradingReadinessCache.get(network, userAddress);
     if (cachedStatus?.attempted) {
       this.#deps.debugLogger.log(
@@ -726,14 +728,14 @@ export class HyperLiquidProvider implements PerpsProvider {
         return;
       }
 
-      // Defer the user-signed transition until the user attempts an action.
+      // Defer signing-backed transitions until the user attempts an action.
       // Cache is intentionally left untouched so the next entry re-evaluates;
       // the read-only userAbstraction call is cheap and gated by the in-flight
       // lock, preventing concurrent prompts.
-      if (currentMode === 'dexAbstraction' && !allowUserSigning) {
+      if (shouldDeferUnifiedAccountSetup(currentMode, allowUserSigning)) {
         this.#deps.debugLogger.log(
-          'HyperLiquidProvider: Deferring dexAbstraction → unifiedAccount migration to action time',
-          { user: userAddress, network },
+          'HyperLiquidProvider: Deferring unified account migration to action time',
+          { user: userAddress, network, mode: currentMode },
         );
         completeInFlight();
         return;
@@ -815,7 +817,7 @@ export class HyperLiquidProvider implements PerpsProvider {
       completeInFlight();
     } catch (error) {
       // If keyring is locked, don't cache so it retries when unlocked
-      if (ensureError(error).message === PERPS_ERROR_CODES.KEYRING_LOCKED) {
+      if (isKeyringLockedError(error)) {
         this.#deps.debugLogger.log(
           '[ensureUnifiedAccountEnabled] Keyring locked, will retry later',
         );
@@ -927,10 +929,10 @@ export class HyperLiquidProvider implements PerpsProvider {
       }
 
       // Attempt Unified Account migration as early as possible so users aren't
-      // blocked when they try to trade. Software-wallet dexAbstraction users can
-      // complete the one-time EIP-712 migration during initial setup so the first
-      // trade sees the unified balance. Hardware wallets remain deferred to
-      // action time to avoid QR / Ledger prompt spam while browsing.
+      // blocked when they try to trade. Software wallets can complete the
+      // signing-backed migration during initial setup so the first trade sees
+      // the unified balance. Hardware wallets remain deferred to action time to
+      // avoid repeated signing prompts while browsing.
       await this.#ensureUnifiedAccountEnabled({
         allowUserSigning: !this.#walletService.isSelectedHardwareWallet(),
       });
@@ -963,7 +965,7 @@ export class HyperLiquidProvider implements PerpsProvider {
    * - Builder fee approval (required for orders)
    * - Referral code setup (attribution)
    *
-   * These operations are DEFERRED from ensureReady() to avoid QR popup spam
+   * These operations are DEFERRED from ensureReady() to avoid hardware wallet prompt spam
    * when users are just viewing the Perps section (critical for hardware wallets).
    *
    * Call this method before any trading operation (placeOrder, cancelOrder, etc.)
@@ -2542,11 +2544,12 @@ export class HyperLiquidProvider implements PerpsProvider {
     const cacheKey = this.#getCacheKey(network, userAddress);
 
     // Check GLOBAL cache first to avoid repeated signing requests across reconnections
-    // This is CRITICAL for hardware wallets to prevent QR popup spam
+    // This is CRITICAL for hardware wallets to prevent repeated signing prompts
+    // while browsing.
     const globalCached = PerpsSigningCache.getBuilderFee(network, userAddress);
     if (globalCached?.attempted) {
       this.#deps.debugLogger.log(
-        '[ensureBuilderFeeApproval] Using global cache (prevents QR popup spam)',
+        '[ensureBuilderFeeApproval] Using global cache (prevents hardware wallet prompt spam)',
         { network, success: globalCached.success },
       );
       if (globalCached.success) {
@@ -8377,7 +8380,7 @@ export class HyperLiquidProvider implements PerpsProvider {
     const globalCached = PerpsSigningCache.getReferral(network, userAddress);
     if (globalCached?.attempted) {
       this.#deps.debugLogger.log(
-        '[ensureReferralSet] Using global cache (prevents QR popup spam)',
+        '[ensureReferralSet] Using global cache (prevents hardware wallet prompt spam)',
         { network, success: globalCached.success },
       );
       return;
diff --git a/app/controllers/perps/services/HyperLiquidWalletService.test.ts b/app/controllers/perps/services/HyperLiquidWalletService.test.ts
@@ -322,7 +322,13 @@ describe('HyperLiquidWalletService', () => {
       expect(service.isSelectedHardwareWallet()).toBe(false);
     });
 
-    it('returns true for Ledger hardware wallet', () => {
+    it.each([
+      'Ledger Hardware',
+      'Trezor Hardware',
+      'OneKey Hardware',
+      'Lattice Hardware',
+      'QR Hardware Wallet Device',
+    ])('returns true for %s wallet', (keyringType) => {
       (mockMessenger.call as jest.Mock).mockImplementation((action: string) => {
         if (
           action === 'AccountTreeController:getAccountsFromSelectedAccountGroup'
@@ -332,28 +338,7 @@ describe('HyperLiquidWalletService', () => {
               ...mockEvmAccount,
               metadata: {
                 ...mockEvmAccount.metadata,
-                keyring: { type: 'Ledger Hardware' },
-              },
-            },
-          ];
-        }
-        return undefined;
-      });
-
-      expect(service.isSelectedHardwareWallet()).toBe(true);
-    });
-
-    it('returns true for QR hardware wallet', () => {
-      (mockMessenger.call as jest.Mock).mockImplementation((action: string) => {
-        if (
-          action === 'AccountTreeController:getAccountsFromSelectedAccountGroup'
-        ) {
-          return [
-            {
-              ...mockEvmAccount,
-              metadata: {
-                ...mockEvmAccount.metadata,
-                keyring: { type: 'QR Hardware Wallet Device' },
+                keyring: { type: keyringType },
               },
             },
           ];
diff --git a/app/controllers/perps/services/HyperLiquidWalletService.ts b/app/controllers/perps/services/HyperLiquidWalletService.ts
@@ -18,6 +18,9 @@ import { findEvmAccount, getSelectedEvmAccount } from '../utils/accountUtils';
 // service portable between mobile and the core monorepo.
 const HARDWARE_KEYRING_TYPES = new Set<string>([
   'Ledger Hardware',
+  'Trezor Hardware',
+  'OneKey Hardware',
+  'Lattice Hardware',
   'QR Hardware Wallet Device',
 ]);
 
@@ -55,7 +58,7 @@ export class HyperLiquidWalletService {
   /**
    * Check whether the selected EVM account is backed by hardware.
    *
-   * @returns True for Ledger / QR hardware keyrings; false for software accounts.
+   * @returns True for MetaMask hardware keyrings; false for software accounts.
    */
   public isSelectedHardwareWallet(): boolean {
     const selectedEvmAccount = findEvmAccount(
diff --git a/app/controllers/perps/services/TradingReadinessCache.ts b/app/controllers/perps/services/TradingReadinessCache.ts
@@ -2,7 +2,8 @@
  * Global singleton cache for Perps signing operations
  *
  * This cache persists across provider reconnections to prevent repeated
- * signing requests for hardware wallets. Critical for preventing QR popup spam.
+ * signing requests for hardware wallets. Critical for preventing repeated
+ * hardware wallet signing prompts.
  *
  * Cache is intentionally kept separate from provider instances because providers
  * are recreated on account/network changes, which would reset instance-level caches.
diff --git a/app/controllers/perps/utils/errorUtils.ts b/app/controllers/perps/utils/errorUtils.ts
@@ -4,6 +4,8 @@
  */
 import { hasProperty } from '@metamask/utils';
 
+import { PERPS_ERROR_CODES } from '../perpsErrorCodes';
+
 /**
  * Detects expected cancellation/abort errors that should not be reported to Sentry.
  * These occur during normal navigation or view teardown when in-flight fetch requests
@@ -23,6 +25,30 @@ export function isAbortError(error: unknown): boolean {
   return false;
 }
 
+/**
+ * Detects keyring-locked errors, including SDK-wrapped errors that preserve the
+ * original error in `cause`.
+ *
+ * @param error - The error to check.
+ * @returns True if any error in the cause chain is KEYRING_LOCKED.
+ */
+export function isKeyringLockedError(error: unknown): boolean {
+  let current: unknown = error;
+  const seen = new Set<unknown>();
+
+  while (current instanceof Error && !seen.has(current)) {
+    seen.add(current);
+
+    if (current.message === PERPS_ERROR_CODES.KEYRING_LOCKED) {
+      return true;
+    }
+
+    current = (current as { cause?: unknown }).cause;
+  }
+
+  return false;
+}
+
 /**
  * Ensures we have a proper Error object for logging.
  * Converts unknown/string errors to proper Error instances.
diff --git a/app/controllers/perps/utils/hyperLiquidAbstraction.test.ts b/app/controllers/perps/utils/hyperLiquidAbstraction.test.ts
@@ -0,0 +1,24 @@
+import { shouldDeferUnifiedAccountSetup } from './hyperLiquidAbstraction';
+
+describe('shouldDeferUnifiedAccountSetup', () => {
+  it.each(['dexAbstraction', 'default', 'disabled'] as const)(
+    'defers %s setup when signing is not allowed',
+    (currentMode) => {
+      expect(shouldDeferUnifiedAccountSetup(currentMode, false)).toBe(true);
+    },
+  );
+
+  it.each(['dexAbstraction', 'default', 'disabled'] as const)(
+    'allows %s setup when signing is allowed',
+    (currentMode) => {
+      expect(shouldDeferUnifiedAccountSetup(currentMode, true)).toBe(false);
+    },
+  );
+
+  it.each(['unifiedAccount', 'portfolioMargin', undefined] as const)(
+    'does not defer %s because no migration is required',
+    (currentMode) => {
+      expect(shouldDeferUnifiedAccountSetup(currentMode, false)).toBe(false);
+    },
+  );
+});
diff --git a/app/controllers/perps/utils/hyperLiquidAbstraction.ts b/app/controllers/perps/utils/hyperLiquidAbstraction.ts
@@ -0,0 +1,26 @@
+import type { HyperLiquidAbstractionMode } from '../types/hyperliquid-types';
+
+const MIGRATABLE_ABSTRACTION_MODES = new Set<HyperLiquidAbstractionMode>([
+  'dexAbstraction',
+  'default',
+  'disabled',
+]);
+
+/**
+ * Determine whether unified-account setup should be deferred until a user
+ * explicitly starts a trading or withdrawal action.
+ *
+ * @param currentMode - The user's current HyperLiquid abstraction mode.
+ * @param allowUserSigning - Whether the caller is allowed to trigger wallet signing.
+ * @returns True when migration would require a signing-backed mutation that should be deferred.
+ */
+export function shouldDeferUnifiedAccountSetup(
+  currentMode: HyperLiquidAbstractionMode | undefined,
+  allowUserSigning: boolean,
+): boolean {
+  return (
+    !allowUserSigning &&
+    currentMode !== undefined &&
+    MIGRATABLE_ABSTRACTION_MODES.has(currentMode)
+  );
+}

Original file line number	Diff line number	Diff line change
`@@ -2,7 +2,8 @@`
`2`	`2`	`* Global singleton cache for Perps signing operations`
`3`	`3`	`*`
`4`	`4`	`* This cache persists across provider reconnections to prevent repeated`
`5`		`- * signing requests for hardware wallets. Critical for preventing QR popup spam.`
	`5`	`+ * signing requests for hardware wallets. Critical for preventing repeated`
	`6`	`+ * hardware wallet signing prompts.`
`6`	`7`	`*`
`7`	`8`	`* Cache is intentionally kept separate from provider instances because providers`
`8`	`9`	`* are recreated on account/network changes, which would reset instance-level caches.`