chore(runway): cherry-pick feat(perps): force unified account (#29673)

- feat(perps): force unified account (#29492)

## **Description**

HyperLiquid is deprecating DEX Abstraction mode (~May 9). This PR forces
every Perps user onto **Unified Account** mode on app open and fixes the
withdraw + balance-display flows that were broken in the target state.

### 1. Forced migration to Unified Account

Migration paths by current abstraction mode:
- `default` / `disabled` → silently migrated via `agentSetAbstraction({
abstraction: 'u' })` — no signing prompt
- `dexAbstraction` → one-time EIP-712 prompt via `userSetAbstraction({
user, abstraction: 'unifiedAccount' })` — agent-key path is blocked by
HL for this transition
- `unifiedAccount` → no-op, cached immediately

Key details:
- Replaces deprecated `agentEnableDexAbstraction` / `userDexAbstraction`
with `agentSetAbstraction` / `userSetAbstraction` / `userAbstraction`
- Runs on perps section open (`#ensureReady()`) so users are set up
before trading
- `TradingReadinessCache` prevents repeated prompts (critical for
hardware/QR wallets); `KEYRING_LOCKED` skips the cache so it retries on
unlock
- In-flight deduplication blocks concurrent signing attempts across
provider instances
- Segment analytics: `Perp Account Setup` event tracks mode distribution
+ outcome (`already_enabled` / `migration_required` / `success` /
`failed`)

### 2. Withdraw + balance display fix (folded in from #29537)

In Unified mode, USDC collateral lives in the spot clearinghouse, so
`clearinghouseState.withdrawable` is $0 — pre-fix the withdraw screen
showed $0 max with the button disabled, and the confirm-flow alert
blocked submission.

- `accountUtils.addSpotBalanceToAccountState` folds free spot USDC into
`availableToTradeBalance` for Unified / Portfolio Margin;
`dexAbstraction` / Standard keep spot separate (fold gated on resolved
abstraction mode)
- `HyperLiquidSubscriptionService.invalidateUserAbstractionCache(addr)`
evicts stale pre-migration mode and re-aggregates immediately. Called by
`HyperLiquidProvider` after both successful migration paths so the
WS-driven aggregator doesn't serve a $0 balance for ~60s after migration
completes.
- Withdraw screen, withdraw validation, confirm-flow
insufficient-balance alert, and percentage buttons all read
`availableToTradeBalance ?? availableBalance` — fallback keeps Standard
/ legacy callers correct.

## **Changelog**

CHANGELOG entry: Fixed Hyperliquid withdraw showing $0 and being blocked
for users on Unified Account mode.

## **Related issues**

Fixes: TAT-3112 (Unified Account migration), withdrawal break tracked in
[TAT-3047](https://consensyssoftware.atlassian.net/browse/TAT-3047)

## **Manual testing steps**

```gherkin
Feature: Unified Account migration + withdraw

  Scenario: First-time migration (default/disabled mode)
    Given the user has never used Perps
    When they open the Perps section
    Then migration runs silently (no prompt)
    And HIP-3 markets are visible

  Scenario: dexAbstraction → unifiedAccount migration
    Given the user has DEX Abstraction enabled
    When they open the Perps section
    Then a one-time EIP-712 signing prompt appears
    When they sign
    Then HIP-3 markets are visible and trades succeed
    And reopening Perps does not prompt again

  Scenario: Unified Account user withdraws spot-funded balance
    Given the user is in Unified Mode with $0 perps withdrawable and >$0 spot USDC
    When they open the Withdraw screen
    Then "Available Perps balance" shows the unified value (perps + free spot USDC)
    And Max enables and submission proceeds via withdraw3
    And spot USDC drops by amount + fee
```

### Live validation evidence

Validated on dev1 mainnet (`0x8dc6…9003`) in the exact bug-class state:
- HL mode: `unifiedAccount` / perps `withdrawable`: $0 / spot USDC free:
$26.41
- App: `availableBalance` = $0 / `availableToTradeBalance` = $26.41
- Withdraw screen renders **"Available Perps balance: $26.41"** + Max
enabled (pre-fix would show $0 / disabled)

## **Screenshots/Recordings**

### **Before**

<!-- $0 max + disabled Max button on dev1 mainnet pre-fix -->

### **After**

<!-- $26.41 max + Max enabled + successful withdraw on dev1 mainnet -->

## **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)).

#### Performance checks (if applicable)

- [ ] I've tested on Android
- [ ] I've tested with a power user scenario
- [ ] I've instrumented key operations with Sentry traces for production
performance metrics

## **Pre-merge reviewer checklist**

- [ ] I've manually tested the PR (e.g. pull and build branch, run the
app, test code being changed).
- [ ] 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.


[TAT-3047]:

https://consensyssoftware.atlassian.net/browse/TAT-3047?atlOrigin=eyJpIjoiNWRkNTljNzYxNjVmNDY3MDlhMDU5Y2ZhYzA5YTRkZjUiLCJwIjoiZ2l0aHViLWNvbS1KU1cifQ

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **High Risk**
> High risk because it changes Perps account-mode migration/signing flow
(including hardware-wallet behavior) and alters withdraw/payment balance
calculations that gate user funds and transaction validation.
> 
> **Overview**
> Forces Perps users onto HyperLiquid **Unified Account** by replacing
deprecated DEX-abstraction checks/calls with `userAbstraction` +
`agentSetAbstraction`/`userSetAbstraction`, adding global
in-flight/cached gating, retry semantics, and new `Perp Account Setup`
analytics.
> 
> Updates withdraw, confirmation, and pay-with flows to prefer
`availableToTradeBalance ?? availableBalance`, and changes spot→perps
folding to be **mode-gated** (fail-closed when abstraction mode is
unknown) so Unified/Portfolio Margin users see spendable USDC while
Standard/dexAbstraction users don’t over-report withdrawable funds.
> 
> Renames cache-clearing APIs from DEX abstraction to Unified Account,
adds hardware-wallet detection to defer user-sign prompts on browse, and
expands tests/docs to cover unified-mode folding, migration paths, and
race conditions in spot/account aggregation.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
e5495f9. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

---------

Co-authored-by: geositta <matthew.denton@consensys.net>
Co-authored-by: Nick Gambino <nicholas.gambino@consensys.net>
Co-authored-by: Arthur Breton <arthur.breton@consensys.net>
Co-authored-by: abretonc7s
<107169956+abretonc7s@users.noreply.github.com>
[cc44460](cc44460)

[TAT-3047]:
https://consensyssoftware.atlassian.net/browse/TAT-3047?atlOrigin=eyJpIjoiNWRkNTljNzYxNjVmNDY3MDlhMDU5Y2ZhYzA5YTRkZjUiLCJwIjoiZ2l0aHViLWNvbS1KU1cifQ

Co-authored-by: Alejandro Garcia Anglada <aganglada@gmail.com>

Author: runway-github[bot]

app/components/UI/Perps/Views/PerpsWithdrawView/PerpsWithdrawView.test.tsx

@@ -277,6 +277,18 @@ describe('PerpsWithdrawView', () => {
   beforeEach(() => {
     jest.clearAllMocks();
     (useNavigation as jest.Mock).mockReturnValue(mockNavigation);
+    const mockUsePerpsLiveAccount =
+      jest.requireMock('../../hooks/stream').usePerpsLiveAccount;
+    mockUsePerpsLiveAccount.mockReturnValue({
+      account: {
+        availableBalance: '1000.00',
+        marginUsed: '0.00',
+        unrealizedPnl: '0.00',
+        returnOnEquity: '0.00',
+        totalBalance: '1000.00',
+      },
+      isInitialLoading: false,
+    });
   });
 
   describe('Component Rendering', () => {
@@ -296,6 +308,32 @@ describe('PerpsWithdrawView', () => {
       ).toBeOnTheScreen();
     });
 
+    it('uses availableToTradeBalance for the displayed Unified Account balance', () => {
+      const mockUsePerpsLiveAccount =
+        jest.requireMock('../../hooks/stream').usePerpsLiveAccount;
+      mockUsePerpsLiveAccount.mockReturnValue({
+        account: {
+          availableBalance: '0.00',
+          availableToTradeBalance: '2500.00',
+          marginUsed: '0.00',
+          unrealizedPnl: '0.00',
+          returnOnEquity: '0.00',
+          totalBalance: '2500.00',
+        },
+        isInitialLoading: false,
+      });
+
+      renderWithProviders(<PerpsWithdrawView />);
+
+      expect(
+        screen.getByText(
+          strings('perps.withdrawal.available_balance', {
+            amount: '$2,500',
+          }),
+        ),
+      ).toBeOnTheScreen();
+    });
+
     it('renders percentage buttons when focused', () => {
       renderWithProviders(<PerpsWithdrawView />);
 

app/components/UI/Perps/Views/PerpsWithdrawView/PerpsWithdrawView.tsx

@@ -108,11 +108,16 @@ const PerpsWithdrawView: React.FC = () => {
   // Get withdrawal tokens from hook
   const { destToken } = useWithdrawTokens();
 
-  // Truncate to 2 decimals so the user can withdraw exactly what they see.
+  // Release-branch bridge for Unified Account: availableToTradeBalance includes
+  // collateral HL can use in target mode. The full balance contract will replace
+  // this with an explicit withdrawableBalance field. Truncate so users can
+  // withdraw exactly the amount they see.
   const availableBalance = useMemo(() => {
-    if (!account?.availableBalance) return 0;
-    return truncateToTwoDecimals(parseCurrencyString(account.availableBalance));
-  }, [account?.availableBalance]);
+    const balance =
+      account?.availableToTradeBalance ?? account?.availableBalance;
+    if (!balance) return 0;
+    return truncateToTwoDecimals(parseCurrencyString(balance));
+  }, [account?.availableBalance, account?.availableToTradeBalance]);
 
   const formattedBalance = useMemo(
     () => formatPerpsFiat(availableBalance),
@@ -154,7 +159,7 @@ const PerpsWithdrawView: React.FC = () => {
   usePerpsMeasurement({
     traceName: TraceName.PerpsWithdrawView,
     conditions: [
-      !!account?.availableBalance,
+      !!(account?.availableToTradeBalance ?? account?.availableBalance),
       !!destToken,
       availableBalance !== undefined,
     ],

app/components/UI/Perps/hooks/usePerpsBalanceTokenFilter.test.ts

@@ -207,6 +207,28 @@ describe('usePerpsBalanceTokenFilter', () => {
       }
     });
 
+    it('prefers availableToTradeBalance for Unified Account users', () => {
+      // Unified Account / Portfolio Margin: collateral lives in spot, so
+      // HL's `clearinghouseState.withdrawable` (mirrored as availableBalance)
+      // is $0. The synthetic Perps balance row in the Pay-with sheet must
+      // read the unified-aware `availableToTradeBalance` instead.
+      mockUseSelector.mockReturnValue({
+        availableBalance: '0.00',
+        availableToTradeBalance: '2500.00',
+      });
+      const inputTokens: AssetType[] = [];
+
+      const { result } = renderHook(() => usePerpsBalanceTokenFilter());
+      const output = result.current(inputTokens);
+
+      expect(output).toHaveLength(1);
+      expect(isHighlightedItemOutsideAssetList(output[0])).toBe(true);
+      if (isHighlightedItemOutsideAssetList(output[0])) {
+        expect(output[0].name_description).toBe('$2500.00');
+        expect(output[0].fiat).toBe('$2500.00');
+      }
+    });
+
     it('uses zero balance when perps account is null', () => {
       mockUseSelector.mockImplementation(
         (selector: (state: unknown) => unknown) => {

app/components/UI/Perps/hooks/usePerpsBalanceTokenFilter.ts

@@ -83,7 +83,14 @@ export function usePerpsBalanceTokenFilter(): (
         return tokens;
       }
 
-      const availableBalance = perpsAccount?.availableBalance || '0';
+      // Prefer `availableToTradeBalance` so Unified Account / Portfolio
+      // Margin users see their real spendable balance in the Pay-with
+      // header — `availableBalance` mirrors HL's perps-only
+      // `clearinghouseState.withdrawable`, which is $0 in unified mode.
+      const availableBalance =
+        perpsAccount?.availableToTradeBalance ??
+        perpsAccount?.availableBalance ??
+        '0';
       const balanceInSelectedCurrency = formatFiat(
         new BigNumber(availableBalance),
       );
@@ -135,6 +142,7 @@ export function usePerpsBalanceTokenFilter(): (
       onPerpsPaymentTokenChange,
       isPerpsBalanceSelected,
       perpsAccount?.availableBalance,
+      perpsAccount?.availableToTradeBalance,
       transactionMeta,
     ],
   );

app/components/UI/Perps/hooks/usePerpsPaymentTokens.test.ts

@@ -294,6 +294,26 @@ describe('usePerpsPaymentTokens', () => {
       expect(hyperliquidUsdc.balanceFiat).toBe('$0.00');
     });
 
+    it('uses availableToTradeBalance for Unified Account users', () => {
+      // Unified Account / Portfolio Margin: collateral lives in spot, so HL's
+      // `clearinghouseState.withdrawable` is $0. The Pay-with sheet must read
+      // `availableToTradeBalance` (perps + folded spot USDC) instead.
+      mockUsePerpsLiveAccount.mockReturnValue({
+        account: {
+          ...mockAccountState,
+          availableBalance: '0',
+          availableToTradeBalance: '2500.00',
+        },
+        isInitialLoading: false,
+      });
+
+      const { result } = renderHook(() => usePerpsPaymentTokens());
+
+      const hyperliquidUsdc = result.current[0];
+      expect(hyperliquidUsdc.balance).toBe('2500000000');
+      expect(hyperliquidUsdc.balanceFiat).toBe('$2500.00');
+    });
+
     it('handles null account state', () => {
       mockUsePerpsLiveAccount.mockReturnValue({
         account: null,

app/components/UI/Perps/hooks/usePerpsPaymentTokens.ts

@@ -34,11 +34,16 @@ export function usePerpsPaymentTokens(): PerpsToken[] {
   // Use ref to store previous token array
   const previousTokensRef = useRef<PerpsToken[]>([]);
 
-  // Get Hyperliquid account balance
+  // Get Hyperliquid account balance. Prefer `availableToTradeBalance` so
+  // Unified Account / Portfolio Margin users see their real spendable balance
+  // in the Pay-with sheet — `availableBalance` mirrors HL's perps-only
+  // `clearinghouseState.withdrawable`, which is $0 in unified mode.
   const { account } = usePerpsLiveAccount();
   const currentNetwork = usePerpsNetwork();
   const hyperliquidBalance = Number.parseFloat(
-    account?.availableBalance?.toString() || '0',
+    (
+      account?.availableToTradeBalance ?? account?.availableBalance
+    )?.toString() || '0',
   );
 
   // Get all chain IDs to search for tokens (exclude Hyperliquid chains)

app/components/UI/Perps/hooks/useWithdrawValidation.test.ts

@@ -81,6 +81,23 @@ describe('useWithdrawValidation', () => {
     expect(result.current.availableBalance).toBe('1000');
   });
 
+  it('prefers availableToTradeBalance for Unified Account target state', () => {
+    (usePerpsLiveAccount as jest.Mock).mockReturnValue({
+      account: {
+        availableBalance: '$0.00',
+        availableToTradeBalance: '$2500.00',
+      },
+      isInitialLoading: false,
+    });
+
+    const { result } = renderHook(() =>
+      useWithdrawValidation({ withdrawAmount: '100' }),
+    );
+
+    expect(result.current.availableBalance).toBe('2500');
+    expect(result.current.hasInsufficientBalance).toBe(false);
+  });
+
   it('should handle empty balance', () => {
     (usePerpsLiveAccount as jest.Mock).mockReturnValue({
       account: {

app/components/UI/Perps/hooks/useWithdrawValidation.ts

@@ -28,9 +28,12 @@ export const useWithdrawValidation = ({
   const perpsNetwork = usePerpsNetwork();
   const isTestnet = perpsNetwork === 'testnet';
 
-  // Truncate to 2 decimal places so validation matches the displayed balance.
+  // Release-branch bridge for Unified Account: availableToTradeBalance includes
+  // collateral HL can use in target mode. The full balance contract will replace
+  // this with an explicit withdrawableBalance field.
   const availableBalance = useMemo(() => {
-    const balance = account?.availableBalance || '0';
+    const balance =
+      account?.availableToTradeBalance ?? account?.availableBalance ?? '0';
     return truncateToTwoDecimals(parseCurrencyString(balance)).toString();
   }, [account]);
 

app/components/UI/Perps/services/PerpsConnectionManager.test.ts

@@ -7,7 +7,7 @@ jest.mock('@metamask/perps-controller', () => {
     TradingReadinessCache: {
       clear: jest.fn(),
       clearAll: jest.fn(),
-      clearDexAbstraction: jest.fn(),
+      clearUnifiedAccount: jest.fn(),
       clearBuilderFee: jest.fn(),
       clearReferral: jest.fn(),
       get: jest.fn(),
@@ -919,27 +919,27 @@ describe('PerpsConnectionManager', () => {
     });
   });
 
-  describe('DEX Abstraction Cache Clearing (PR 25334)', () => {
+  describe('Unified Account Cache Clearing (PR 25334)', () => {
     beforeEach(() => {
       jest.clearAllMocks();
     });
 
-    describe('clearDexAbstractionCache', () => {
-      it('clears only DEX abstraction for specific network and user address', () => {
+    describe('clearUnifiedAccountCache', () => {
+      it('clears only unified account for specific network and user address', () => {
         // Arrange
         const network = 'mainnet' as const;
         const userAddress = '0x1234567890123456789012345678901234567890';
 
         // Act
-        PerpsConnectionManager.clearDexAbstractionCache(network, userAddress);
+        PerpsConnectionManager.clearUnifiedAccountCache(network, userAddress);
 
-        // Assert - should call clearDexAbstraction, NOT clear (which deletes entire entry)
+        // Assert - should call clearUnifiedAccount, NOT clear (which deletes entire entry)
         expect(
-          mockTradingReadinessCache.clearDexAbstraction,
+          mockTradingReadinessCache.clearUnifiedAccount,
         ).toHaveBeenCalledWith(network, userAddress);
         expect(mockTradingReadinessCache.clear).not.toHaveBeenCalled();
         expect(mockDevLogger.log).toHaveBeenCalledWith(
-          'PerpsConnectionManager: DEX abstraction cache cleared',
+          'PerpsConnectionManager: Unified Account cache cleared',
           { network, userAddress },
         );
       });
@@ -950,11 +950,11 @@ describe('PerpsConnectionManager', () => {
         const userAddress = '0xTestnetUser12345678901234567890123456';
 
         // Act
-        PerpsConnectionManager.clearDexAbstractionCache(network, userAddress);
+        PerpsConnectionManager.clearUnifiedAccountCache(network, userAddress);
 
         // Assert
         expect(
-          mockTradingReadinessCache.clearDexAbstraction,
+          mockTradingReadinessCache.clearUnifiedAccount,
         ).toHaveBeenCalledWith(network, userAddress);
       });
     });

app/components/UI/Perps/services/PerpsConnectionManager.ts

@@ -1441,16 +1441,16 @@ class PerpsConnectionManagerClass {
   }
 
   /**
-   * Clear DEX abstraction cache for a specific address
+   * Clear unified account cache for a specific address
    * Useful for debugging or allowing user to retry after rejecting signature
-   * Note: This only clears DEX abstraction state, preserving builder fee and referral states
+   * Note: This only clears unified account state, preserving builder fee and referral states
    */
-  clearDexAbstractionCache(
+  clearUnifiedAccountCache(
     network: 'mainnet' | 'testnet',
     userAddress: string,
   ): void {
-    TradingReadinessCache.clearDexAbstraction(network, userAddress);
-    DevLogger.log('PerpsConnectionManager: DEX abstraction cache cleared', {
+    TradingReadinessCache.clearUnifiedAccount(network, userAddress);
+    DevLogger.log('PerpsConnectionManager: Unified Account cache cleared', {
       network,
       userAddress,
     });