fix: Withdrawal broken for Hyperliquid Unified Account Mode users by gambinish · Pull Request #29537 · MetaMask/metamask-mobile

gambinish · 2026-04-30T03:55:03Z

Description

Users who had enabled Unified Account Mode in Hyperliquid were seeing $0 available balance in the withdrawal flow, with the withdraw button disabled due to "Insufficient funds." This made it impossible to withdraw.

The root cause: in Unified Account Mode, USDC collateral lives in the spot clearinghouse rather than the perps clearinghouse. Our existing balance fields only read the perps-side withdrawable (which is $0 in unified mode), leaving the real balance invisible.

This PR fixes it across the full withdrawal stack:

Balance aggregation (accountUtils.ts) — folds free spot USDC into availableToTradeBalance when unified mode is active. Adds a fallback for accounts where USDC is held as perps equity rather than explicit spot (common after migrating from Standard mode).
Cache correctness (HyperLiquidSubscriptionService) — adds invalidateUserAbstractionCache so stale pre-migration mode data can't block the fold from applying.
Migration wiring (HyperLiquidProvider) — calls the invalidation after both the "already unified" and "just migrated" success paths, ensuring the WebSocket re-aggregates immediately.
Confirmation flow (useInsufficientPerpsBalanceAlert, useTransactionCustomAmount) — alert and percentage-button calculations now use availableToTradeBalance ?? availableBalance instead of reading only the perps-side balance.

Changelog

CHANGELOG entry: Fix withdrawable balance for unified account

Related issues

Fixes:

Manual testing steps

Feature: my feature name

  Scenario: user [verb for user action]
    Given [describe expected initial app state]

    When user [verb for user action]
    Then [describe expected outcome]

Screenshots/Recordings

Screen.Recording.2026-04-29.at.5.48.21.PM.mov

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). 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 to import wallets with many accounts and tokens
I've instrumented key operations with Sentry traces for production performance metrics
- See trace() for usage and addToken for an example

For performance guidelines and tooling, see the Performance Guide.

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.

Note

Medium Risk
Touches perps withdrawal balance computation/validation and subscription cache behavior; a mistake could incorrectly block withdrawals or overstate withdrawable funds, but the change is localized and covered by new tests.

Overview
Fixes HyperLiquid perps withdrawal UX for Unified Account/Portfolio Margin users by consistently using availableToTradeBalance ?? availableBalance for the displayed withdrawable balance, insufficient-funds blocking alert, and percentage-based amount calculations.

Adds HyperLiquidSubscriptionService.invalidateUserAbstractionCache() and wires HyperLiquidProvider to call it on successful “already enabled” and “migrated to unified” paths so the streamed account aggregation immediately re-computes with the correct fold behavior instead of serving stale pre-migration balances.

Tightens spot-folding semantics in addSpotBalanceToAccountState so folding into availableToTradeBalance is strictly gated by abstraction mode (preventing Standard/DEX-abstraction users from seeing spot USDC as perps-withdrawable), with expanded unit tests covering cache invalidation and standard-mode balance separation.

^{Reviewed by Cursor Bugbot for commit 06e3561. Bugbot is set up for automated code reviews on this repo. Configure here.}

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 8589c97. Configure here.}

github-actions · 2026-04-30T05:45:16Z

CLA Signature Action: All authors have signed the CLA. You may need to manually re-run the blocking PR check if it doesn't pass in a few minutes.

github-actions · 2026-04-30T05:47:02Z

🔍 Smart E2E Test Selection

Selected E2E tags: SmokePerps, SmokeConfirmations, SmokeWalletPlatform
Selected Performance tags: None (no tests recommended)
Risk Level: medium
AI Confidence: 90%

click to see 🤖 AI reasoning details

E2E Test Selection:
The PR changes are focused on the Perps feature, specifically fixing balance display for Unified Account Mode / Portfolio Margin users:

perps-withdraw-balance.tsx: UI component now prefers availableToTradeBalance over availableBalance for Unified Account Mode users - directly affects the Perps withdrawal confirmation screen.
useInsufficientPerpsBalanceAlert.ts: Alert hook updated to use the correct balance field for Unified Account Mode - affects the insufficient balance alert shown during perps withdrawal confirmations.
useTransactionCustomAmount.ts: Transaction amount hook updated to use correct balance for percentage buttons (25%, 50%, 75%, Max) in perps withdrawal - affects the confirmation flow.
HyperLiquidProvider.ts: Calls new invalidateUserAbstractionCache() after successful Unified Account migration to ensure correct balance is shown immediately.
HyperLiquidSubscriptionService.ts: New invalidateUserAbstractionCache() method that evicts stale cached abstraction mode and triggers re-aggregation.
accountUtils.ts: Comment clarification ensuring Standard/DEX-abstraction users don't have spot balance incorrectly folded into perps withdrawable balance.

Tag selection rationale:

SmokePerps: Primary tag - all changes directly affect the Perps withdrawal flow, balance display, and HyperLiquid backend services. The PerpsWithdrawView and balance calculation are core to this tag.
SmokeConfirmations: Required by SmokePerps description ("Add Funds deposits are on-chain transactions"). Also directly relevant because useInsufficientPerpsBalanceAlert and useTransactionCustomAmount are confirmation hooks that affect the transaction confirmation UI.
SmokeWalletPlatform: Required by SmokePerps description ("Perps is also a section inside the Trending tab"). Changes to Perps views affect Trending.

The changes are medium risk - they fix a balance calculation bug for a specific user mode (Unified Account), but the logic change (preferring availableToTradeBalance ?? availableBalance) could potentially affect other users if the fallback behavior changes unexpectedly.

Performance Test Selection:
The changes are logic fixes for balance field selection (availableToTradeBalance vs availableBalance) and cache invalidation. These are not rendering, list performance, or UI animation changes. No performance tests are warranted.

View GitHub Actions results

github-actions · 2026-04-30T06:03:18Z

✅ E2E Fixture Validation — Schema is up to date
12 value mismatches detected (expected — fixture represents an existing user).
View details

codecov-commenter · 2026-04-30T06:03:29Z

Codecov Report

❌ Patch coverage is 87.50000% with 1 line in your changes missing coverage. Please review.
⚠️ Please upload report for BASE (feat/unified-account@9349410). Learn more about missing BASE report.

Files with missing lines	Patch %	Lines
...s/perps/services/HyperLiquidSubscriptionService.ts	66.66%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@                   Coverage Diff                   @@
##             feat/unified-account   #29537   +/-   ##
=======================================================
  Coverage                        ?   82.18%           
=======================================================
  Files                           ?     5177           
  Lines                           ?   137318           
  Branches                        ?    31046           
=======================================================
  Hits                            ?   112859           
  Misses                          ?    16818           
  Partials                        ?     7641

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

sonarqubecloud · 2026-04-30T06:04:54Z

Quality Gate passed

Issues
1 New issue
0 Accepted issues

Measures
0 Security Hotspots
92.3% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

abretonc7s

LGTM. fixed a small bugbot

gambinish added 6 commits April 29, 2026 20:53

fix: withdrawable balance with spot

2fc2bbf

chore: cleanup

93e2468

fix: revert unintended removal

a946aa9

fix: more gracefully handle both cases

2aaa6fd

fix: unit test

4eaef9d

fix: unit test

8589c97

metamaskbotv2 Bot added the team-perps Perps team label Apr 30, 2026

gambinish changed the title ~~Feat/unified account withdraw~~ fix: Withdrawal broken for Hyperliquid Unified Account Mode users Apr 30, 2026

gambinish marked this pull request as ready for review April 30, 2026 03:55

gambinish requested review from a team as code owners April 30, 2026 03:55

gambinish mentioned this pull request Apr 30, 2026

fix: Withdrawal broken for Hyperliquid Unified Account Mode users #29534

Closed

10 tasks

github-actions Bot added the size-M label Apr 30, 2026

cursor Bot reviewed Apr 30, 2026

View reviewed changes

Comment thread ...nfirmations/components/perps-confirmations/perps-withdraw-balance/perps-withdraw-balance.tsx Outdated

fix: address bugbot comments

06e3561

abretonc7s approved these changes Apr 30, 2026

View reviewed changes

abretonc7s merged commit c7752ea into feat/unified-account Apr 30, 2026
90 of 93 checks passed

abretonc7s deleted the feat/unified-account-withdraw branch April 30, 2026 06:25

github-actions Bot locked and limited conversation to collaborators Apr 30, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

fix: Withdrawal broken for Hyperliquid Unified Account Mode users#29537

fix: Withdrawal broken for Hyperliquid Unified Account Mode users#29537
abretonc7s merged 7 commits into
feat/unified-accountfrom
feat/unified-account-withdraw

gambinish commented Apr 30, 2026 •

edited by cursor Bot

Loading

Uh oh!

cursor Bot left a comment

Uh oh!

Uh oh!

github-actions Bot commented Apr 30, 2026

Uh oh!

github-actions Bot commented Apr 30, 2026

Uh oh!

github-actions Bot commented Apr 30, 2026

Uh oh!

codecov-commenter commented Apr 30, 2026

Uh oh!

sonarqubecloud Bot commented Apr 30, 2026

Uh oh!

abretonc7s left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

gambinish commented Apr 30, 2026 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Changelog

Related issues

Manual testing steps

Screenshots/Recordings

Pre-merge author checklist

Performance checks (if applicable)

Pre-merge reviewer checklist

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

github-actions Bot commented Apr 30, 2026

Uh oh!

github-actions Bot commented Apr 30, 2026

🔍 Smart E2E Test Selection

Uh oh!

github-actions Bot commented Apr 30, 2026

Uh oh!

codecov-commenter commented Apr 30, 2026

Codecov Report

Uh oh!

sonarqubecloud Bot commented Apr 30, 2026

Quality Gate passed

Uh oh!

abretonc7s left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

gambinish commented Apr 30, 2026 •

edited by cursor Bot

Loading