• feat(perps): force unified account (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

Manual testing steps

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

After

Pre-merge author checklist

• I've followed MetaMask Contributor
  Docs and MetaMask Mobile
  Coding
  Standards.
• I've completed the PR template to the best of my ability
• I've included tests if applicable
• I've documented my code using JSDoc format
  if applicable
• I've applied the right labels on the PR (see labeling
  guidelines).

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.

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