fix: perps withdraw token selection and balance validation (#28599)

## **Description**

Two fixes for the Perps Withdraw flow:

- **Zero-balance token selection reverts to mUSD on first try**: When
selecting a zero-balance token from the asset picker,
`TokensController.addTokens` was fire-and-forget (`.catch(noop)`), so
`setPayToken` ran before the controller could resolve the token's
metadata. The payment token was silently cleared and the UI fell back to
mUSD. Now awaits `addTokens` before calling `setPayToken`. Only
reproduced on first selection after fresh install — subsequent attempts
worked because the token was already tracked.
- **Insufficient funds when typing full available balance**: The raw
balance (e.g. `16.069`) was displayed rounded up to `$16.07` via
`formatPerpsFiat`, but validation compared against the raw value — so
typing `16.07` was rejected (`16.07 > 16.069`). Now truncates (floors)
the balance to 2 decimal places for both display and validation, so the
user sees `$16.06` and can withdraw exactly that amount.

## **Changelog**

CHANGELOG entry: Fixed perps withdraw zero-balance token selection
reverting to mUSD and insufficient funds error when typing full balance

## **Related issues**

Fixes: CONF-1160

## **Manual testing steps**

Feature: Perps Withdraw

Scenario: user selects zero-balance token on fresh install
- Given user opens perps withdraw for the first time (or cleared app
data)
- When user selects a token with zero balance from the Receive asset
picker
- Then the selected token persists and does not revert to mUSD

Scenario: user types full available balance
- Given user has a perps balance where the raw value has more than 2
decimal places
- When user looks at the displayed balance (should be truncated down,
e.g. $16.06 not $16.07)
- And user types that displayed balance amount
- Then no insufficient funds error is shown
- When user types one cent more than the displayed balance
- Then insufficient funds error is shown

## **Screenshots/Recordings**

### **Before**

### **After**

## **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
- [ ] 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.

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

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Touches withdrawal validation and token-selection flow; risk is
moderate because it changes async ordering around
`TokensController.addTokens` and alters displayed/validated balances,
but scope is limited and covered by unit tests.
> 
> **Overview**
> Fixes two Perps withdraw edge cases: **(1)** selecting a zero-balance
receive token now reliably persists by making `pay-with-modal` *await*
`TokensController.addTokens` before calling `setPayToken`, preventing
fallback to the default token.
> 
> **(2)** withdraw balance display and validation are aligned by
truncating (not rounding) available balance to 2 decimals via new
`truncateToTwoDecimals` in `formatUtils`, used in both
`PerpsWithdrawView` and `useWithdrawValidation`; adds targeted unit
tests for truncation and call ordering.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
4c6f0ef. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

---------

Signed-off-by: dan437 <80175477+dan437@users.noreply.github.com>

Author: dan437

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

@@ -54,7 +54,11 @@ import { TraceName } from '../../../../../util/trace';
 import { usePerpsLiveAccount } from '../../hooks/stream';
 import { usePerpsEventTracking } from '../../hooks/usePerpsEventTracking';
 import { useWithdrawValidation } from '../../hooks/useWithdrawValidation';
-import { formatPerpsFiat, parseCurrencyString } from '../../utils/formatUtils';
+import {
+  formatPerpsFiat,
+  parseCurrencyString,
+  truncateToTwoDecimals,
+} from '../../utils/formatUtils';
 
 import type { Hex } from '@metamask/utils';
 import { AvatarSize } from '../../../../../component-library/components/Avatars/Avatar/Avatar.types';
@@ -104,11 +108,10 @@ const PerpsWithdrawView: React.FC = () => {
   // Get withdrawal tokens from hook
   const { destToken } = useWithdrawTokens();
 
-  // Parse available balance from perps account state
+  // Truncate to 2 decimals so the user can withdraw exactly what they see.
   const availableBalance = useMemo(() => {
     if (!account?.availableBalance) return 0;
-    // Use parseCurrencyString to properly parse formatted currency
-    return parseCurrencyString(account.availableBalance);
+    return truncateToTwoDecimals(parseCurrencyString(account.availableBalance));
   }, [account?.availableBalance]);
 
   const formattedBalance = useMemo(

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

@@ -104,6 +104,37 @@ describe('useWithdrawValidation', () => {
     expect(result.current.hasInsufficientBalance).toBe(true);
   });
 
+  it('should truncate available balance to 2 decimal places for validation', () => {
+    (usePerpsLiveAccount as jest.Mock).mockReturnValue({
+      account: {
+        availableBalance: '$16.069',
+      },
+      isInitialLoading: false,
+    });
+
+    const { result } = renderHook(() =>
+      useWithdrawValidation({ withdrawAmount: '16.06' }),
+    );
+
+    expect(result.current.availableBalance).toBe('16.06');
+    expect(result.current.hasInsufficientBalance).toBe(false);
+  });
+
+  it('should show insufficient balance when typing more than truncated balance', () => {
+    (usePerpsLiveAccount as jest.Mock).mockReturnValue({
+      account: {
+        availableBalance: '$16.069',
+      },
+      isInitialLoading: false,
+    });
+
+    const { result } = renderHook(() =>
+      useWithdrawValidation({ withdrawAmount: '16.07' }),
+    );
+
+    expect(result.current.hasInsufficientBalance).toBe(true);
+  });
+
   it('should detect amount below minimum', () => {
     const { result } = renderHook(() =>
       useWithdrawValidation({ withdrawAmount: '1.5' }),

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

@@ -5,7 +5,10 @@ import {
   HYPERLIQUID_ASSET_CONFIGS,
   WITHDRAWAL_CONSTANTS,
 } from '@metamask/perps-controller';
-import { parseCurrencyString } from '../utils/formatUtils';
+import {
+  parseCurrencyString,
+  truncateToTwoDecimals,
+} from '../utils/formatUtils';
 import { usePerpsNetwork } from './index';
 import { usePerpsLiveAccount } from './stream';
 
@@ -25,12 +28,10 @@ export const useWithdrawValidation = ({
   const perpsNetwork = usePerpsNetwork();
   const isTestnet = perpsNetwork === 'testnet';
 
-  // Available balance from perps account
+  // Truncate to 2 decimal places so validation matches the displayed balance.
   const availableBalance = useMemo(() => {
     const balance = account?.availableBalance || '0';
-    // Use parseCurrencyString to properly parse formatted currency
-    // Return as string to maintain compatibility with components
-    return parseCurrencyString(balance).toString();
+    return truncateToTwoDecimals(parseCurrencyString(balance)).toString();
   }, [account]);
 
   // Get withdrawal route for constraints

app/components/UI/Perps/utils/formatUtils.test.ts

@@ -11,6 +11,7 @@ import {
   formatPositionSize,
   formatLeverage,
   parseCurrencyString,
+  truncateToTwoDecimals,
   parsePercentageString,
   formatTransactionDate,
   formatDateSection,
@@ -941,6 +942,31 @@ describe('formatUtils', () => {
     });
   });
 
+  describe('truncateToTwoDecimals', () => {
+    it('truncates without rounding up', () => {
+      expect(truncateToTwoDecimals(16.069)).toBe(16.06);
+      expect(truncateToTwoDecimals(16.999)).toBe(16.99);
+      expect(truncateToTwoDecimals(0.009)).toBe(0);
+    });
+
+    it('preserves values with 2 or fewer decimals', () => {
+      expect(truncateToTwoDecimals(16.07)).toBe(16.07);
+      expect(truncateToTwoDecimals(16)).toBe(16);
+      expect(truncateToTwoDecimals(0)).toBe(0);
+    });
+
+    it('handles IEEE 754 edge cases correctly', () => {
+      expect(truncateToTwoDecimals(10.29)).toBe(10.29);
+      expect(truncateToTwoDecimals(1.005)).toBe(1);
+      expect(truncateToTwoDecimals(0.1 + 0.2)).toBe(0.3);
+    });
+
+    it('handles negative values', () => {
+      expect(truncateToTwoDecimals(-16.069)).toBe(-16.06);
+      expect(truncateToTwoDecimals(-10.29)).toBe(-10.29);
+    });
+  });
+
   describe('parsePercentageString', () => {
     it('should parse formatted percentage strings', () => {
       expect(parsePercentageString('+2.50%')).toBe(2.5);

app/components/UI/Perps/utils/formatUtils.ts

@@ -23,6 +23,14 @@ export {
 } from '@metamask/perps-controller';
 export { formatPerpsFiat }; // re-export via local import (needed by formatPositiveFiat below)
 
+/**
+ * Truncates a number to 2 decimal places without rounding up.
+ * Uses BigNumber to avoid IEEE 754 floating-point errors
+ * (e.g. `Math.floor(10.29 * 100) / 100` = 10.28).
+ */
+export const truncateToTwoDecimals = (value: number): number =>
+  new BigNumber(value).decimalPlaces(2, BigNumber.ROUND_DOWN).toNumber();
+
 /**
  * Formats a fee value as USD currency with appropriate decimal places
  * @param fee - Raw numeric or string fee value (e.g., 1234.56, not token minimal denomination)

app/components/Views/confirmations/components/modals/pay-with-modal/pay-with-modal.test.tsx

@@ -438,7 +438,23 @@ describe('PayWithModal', () => {
       expect(getAvailableTokensMock).not.toHaveBeenCalled();
     });
 
-    it('adds zero-balance token to TokensController on withdraw selection', async () => {
+    it('awaits addTokens before calling setPayToken for zero-balance withdraw token', async () => {
+      const callOrder: string[] = [];
+
+      mockAddTokens.mockImplementation(
+        () =>
+          new Promise<void>((resolve) => {
+            setTimeout(() => {
+              callOrder.push('addTokens');
+              resolve();
+            }, 0);
+          }),
+      );
+
+      setPayTokenMock.mockImplementation(() => {
+        callOrder.push('setPayToken');
+      });
+
       const zeroBalanceToken = {
         accountType: EthAccountType.Eoa,
         address: '0xZeroBalanceToken',
@@ -461,8 +477,12 @@ describe('PayWithModal', () => {
         fireEvent.press(getByText('Zero Token'));
       });
 
+      await waitFor(() => {
+        expect(setPayTokenMock).toHaveBeenCalled();
+      });
+
       expect(mockAddTokens).toHaveBeenCalled();
-      expect(setPayTokenMock).toHaveBeenCalled();
+      expect(callOrder).toStrictEqual(['addTokens', 'setPayToken']);
     });
   });
 

app/components/Views/confirmations/components/modals/pay-with-modal/pay-with-modal.tsx

@@ -99,7 +99,7 @@ export function PayWithModal() {
 
   const handleTokenSelect = useCallback(
     (token: AssetType) => {
-      const onClosed = () => {
+      const onClosed = async () => {
         if (
           hasTransactionType(transactionMeta, [TransactionType.musdConversion])
         ) {
@@ -123,15 +123,15 @@ export function PayWithModal() {
 
         // Ensure the token is tracked by TokensController so the pay
         // controller can resolve its metadata (symbol, decimals, balance).
-        // This is needed for zero-balance tokens from the catalog.
+        // Must complete before setPayToken so the controller can find the token.
         if (isWithdraw && token.balance === '0' && !token.isNative) {
           const { TokensController, NetworkController } = Engine.context;
           try {
             const networkClientId =
               NetworkController.findNetworkClientIdByChainId(
                 token.chainId as Hex,
               );
-            TokensController.addTokens(
+            await TokensController.addTokens(
               [
                 {
                   address: token.address,
@@ -140,7 +140,7 @@ export function PayWithModal() {
                 },
               ],
               networkClientId,
-            ).catch(noop);
+            );
           } catch {
             // Network not configured — skip
           }