feat(withdraw): tap the balance to withdraw everything

src/app/(mobile-ui)/withdraw/__tests__/withdraw-states.test.tsx

@@ -61,10 +61,13 @@ const mockSetUsdAmount = jest.fn()
 const mockSetSelectedBankAccount = jest.fn()
 const mockSetSelectedMethod = jest.fn()
 const mockSetShowAllWithdrawMethods = jest.fn()
+const mockSetIsMaxWithdrawal = jest.fn()
 
 const mockWithdrawFlow = {
     amountToWithdraw: '',
     setAmountToWithdraw: mockSetAmountToWithdraw,
+    isMaxWithdrawal: false,
+    setIsMaxWithdrawal: mockSetIsMaxWithdrawal,
     setError: mockSetError,
     error: { showError: false, errorMessage: '' },
     setUsdAmount: mockSetUsdAmount,
@@ -155,6 +158,20 @@ jest.mock('@/components/Global/AmountInput', () => ({
                 disabled={props.disabled}
             />
             {props.walletBalance && <span data-testid="wallet-balance">{props.walletBalance}</span>}
+            {!!props.balanceFillAmount && (
+                <button
+                    data-testid="use-full-balance"
+                    data-fill={String(props.balanceFillAmount)}
+                    onClick={() => {
+                        // real component floors to cents, then reports both ways
+                        const filled = (Math.floor(props.balanceFillAmount * 100) / 100).toString()
+                        props.onBalanceFilled?.(filled)
+                        props.setPrimaryAmount?.(filled)
+                    }}
+                >
+                    Use full balance
+                </button>
+            )}
         </div>
     ),
 }))
@@ -472,6 +489,92 @@ describe('GROUP 3: Amount Validation', () => {
         )
     })
 
+    test('Marks the amount as a max withdrawal, and unmarks it on any edit', () => {
+        // The flag is what lets the crypto path settle the sub-cent remainder
+        // the displayed 2 decimals leave behind (TASK-21899).
+        mockWithdrawFlow.selectedMethod = { type: 'crypto' }
+        mockUseWallet.mockReturnValue({
+            spendableBalance: parseUnits('12.345678', 6),
+            formattedSpendableBalance: '12.34',
+            hasSufficientSpendableBalance: (amt: string | number) => Number(amt) <= 12.345678,
+        })
+
+        renderWithdraw()
+
+        fireEvent.click(screen.getByTestId('use-full-balance'))
+        expect(mockSetIsMaxWithdrawal).toHaveBeenLastCalledWith(true)
+
+        fireEvent.change(screen.getByTestId('amount-field'), { target: { value: '5' } })
+        expect(mockSetIsMaxWithdrawal).toHaveBeenLastCalledWith(false)
+    })
+
+    test('Hands down the full-precision balance while the field shows cents', () => {
+        // The page passes the number its own validation compares against, not
+        // the rounded label; the input is what floors it for display, and the
+        // crypto path recovers the remainder from the flag (TASK-21899).
+        mockWithdrawFlow.selectedMethod = { type: 'crypto' }
+        mockUseWallet.mockReturnValue({
+            spendableBalance: parseUnits('12.345678', 6),
+            formattedSpendableBalance: '12.34',
+            hasSufficientSpendableBalance: (amt: string | number) => Number(amt) <= 12.345678,
+        })
+
+        renderWithdraw()
+        expect(screen.getByTestId('use-full-balance')).toHaveAttribute('data-fill', '12.345678')
+
+        fireEvent.click(screen.getByTestId('use-full-balance'))
+
+        expect(screen.getByTestId('amount-field')).toHaveValue('12.34')
+        expect(screen.getByText('Continue')).not.toBeDisabled()
+    })
+
+    test('Full balance passes validation and continues with that amount', () => {
+        mockWithdrawFlow.selectedMethod = { type: 'crypto' }
+
+        renderWithdraw()
+        fireEvent.click(screen.getByTestId('use-full-balance'))
+
+        const continueBtn = screen.getByText('Continue')
+        expect(continueBtn).not.toBeDisabled()
+
+        fireEvent.click(continueBtn)
+        expect(mockSetAmountToWithdraw).toHaveBeenCalledWith('100')
+    })
+
+    test('Full balance below the method minimum keeps Continue disabled', async () => {
+        mockWithdrawFlow.selectedMethod = { type: 'bridge', countryPath: 'us' }
+        mockUseWallet.mockReturnValue({
+            spendableBalance: parseUnits('0.5', 6),
+            formattedSpendableBalance: '0.50',
+            hasSufficientSpendableBalance: (amt: string | number) => Number(amt) <= 0.5,
+        })
+
+        renderWithdraw()
+        fireEvent.click(screen.getByTestId('use-full-balance'))
+
+        expect(screen.getByText('Continue')).toBeDisabled()
+        await waitFor(() =>
+            expect(mockSetError).toHaveBeenCalledWith({
+                showError: true,
+                errorMessage: 'Minimum withdrawal is $1.',
+            })
+        )
+    })
+
+    test('No fill action while the balance is still loading', () => {
+        mockWithdrawFlow.selectedMethod = { type: 'crypto' }
+        mockUseWallet.mockReturnValue({
+            spendableBalance: undefined,
+            formattedSpendableBalance: '0.00',
+            hasSufficientSpendableBalance: () => false,
+        })
+
+        renderWithdraw()
+
+        expect(screen.queryByTestId('use-full-balance')).not.toBeInTheDocument()
+        expect(screen.getByText('Continue')).toBeDisabled()
+    })
+
     test('Stale bank method entering via ?method=crypto keeps the bank minimum', () => {
         // Regression: the crypto exemption must follow selectedMethod (the
         // routing source of truth), not the URL param. A leftover bank method

src/app/(mobile-ui)/withdraw/crypto/__tests__/crypto-withdraw-confirm.test.tsx

@@ -84,6 +84,9 @@ jest.mock('@/utils/balance.utils', () => ({
 
 jest.mock('@/utils/withdraw.utils', () => ({
     isBelowRhinoMinDeposit: () => false,
+    // real behaviour, covered by src/utils/__tests__/withdraw.utils.test.ts —
+    // these suites drive the non-max path, where it returns the amount as-is
+    resolveWithdrawAmount: jest.requireActual('@/utils/withdraw.utils').resolveWithdrawAmount,
 }))
 
 jest.mock('@/utils/general.utils', () => ({

src/app/(mobile-ui)/withdraw/crypto/page.tsx

@@ -20,7 +20,7 @@ import type {
 import { NATIVE_TOKEN_ADDRESS } from '@/utils/token.utils'
 import { isWithdrawFeeDisproportionate, getMinWithdrawUsdForChain } from '@/utils/cross-chain-fee.utils'
 import { isAmountWithinBalance } from '@/utils/balance.utils'
-import { isBelowRhinoMinDeposit } from '@/utils/withdraw.utils'
+import { isBelowRhinoMinDeposit, resolveWithdrawAmount } from '@/utils/withdraw.utils'
 import * as peanutInterfaces from '@/interfaces/peanut-sdk-types'
 import { useRouter } from 'next/navigation'
 import { useCallback, useContext, useEffect, useMemo, useRef, useState } from 'react'
@@ -64,6 +64,7 @@ export default function WithdrawCryptoPage() {
     const { resetTokenContextProvider } = useContext(tokenSelectorContext)
     const {
         amountToWithdraw,
+        isMaxWithdrawal,
         usdAmount,
         currentView,
         setCurrentView,
@@ -148,6 +149,14 @@ export default function WithdrawCryptoPage() {
         resetPaymentRecorder()
     }, [setChargeDetails, setTransactionHash, setPaymentDetails, resetRouteCalculation, resetPaymentRecorder])
 
+    // What the withdrawal actually moves: the amount on screen, plus the
+    // sub-cent remainder when the user tapped "use full balance" and did not
+    // edit it. See resolveWithdrawAmount for the guard rails (TASK-21899).
+    const effectiveAmount = useMemo(
+        () => resolveWithdrawAmount(amountToWithdraw, spendableBalance, isMaxWithdrawal, PEANUT_WALLET_TOKEN_DECIMALS),
+        [amountToWithdraw, spendableBalance, isMaxWithdrawal]
+    )
+
     // clear errors when amount changes
     useEffect(() => {
         if (amountToWithdraw) {
@@ -172,9 +181,9 @@ export default function WithdrawCryptoPage() {
                     address: address as Address,
                     tokenAddress: PEANUT_WALLET_TOKEN as Address,
                     chainId: PEANUT_WALLET_CHAIN.id.toString(),
-                    // amountToWithdraw is USD-denominated; source token is USDC (1:1).
+                    // effectiveAmount is USD-denominated; source token is USDC (1:1).
                     // Required for the bridge path's 'pay' mode (cross-chain ETH/etc).
-                    tokenAmount: amountToWithdraw,
+                    tokenAmount: effectiveAmount,
                 },
                 destination: {
                     recipientAddress: chargeDetails.requestLink.recipientAddress as Address,
@@ -190,7 +199,7 @@ export default function WithdrawCryptoPage() {
                 skipGasEstimate: true, // peanut wallet handles gas
             })
         }
-    }, [currentView, chargeDetails, withdrawData, calculateRoute, address, amountToWithdraw])
+    }, [currentView, chargeDetails, withdrawData, calculateRoute, address, effectiveAmount])
 
     const handleSetupReview = useCallback(
         async (data: Omit<WithdrawData, 'amount'>) => {
@@ -209,7 +218,7 @@ export default function WithdrawCryptoPage() {
                 data.chain.chainId.toString() === PEANUT_WALLET_CHAIN.id.toString() &&
                 data.token.address.toLowerCase() === PEANUT_WALLET_TOKEN.toLowerCase()
             if (!isSameChainUsdc) {
-                const usdToWithdraw = parseFloat(amountToWithdraw)
+                const usdToWithdraw = parseFloat(effectiveAmount)
                 const minUsd = getMinWithdrawUsdForChain(data.chain.chainId)
                 if (!Number.isFinite(usdToWithdraw) || usdToWithdraw < minUsd) {
                     const minDisplay = minUsd % 1 === 0 ? `$${minUsd}` : `$${minUsd.toFixed(2)}`
@@ -230,10 +239,10 @@ export default function WithdrawCryptoPage() {
                 // units before persisting the request/charge — otherwise meta
                 // ends up with `tokenAmount: "1"` + `tokenSymbol: "ETH"` and
                 // history renders "1 ETH" for what was actually a $1 withdraw.
-                const usdValue = parseFloat(amountToWithdraw)
+                const usdValue = parseFloat(effectiveAmount)
                 const tokenPrice = data.token.price ?? 0
                 const destinationTokenAmount =
-                    tokenPrice > 0 ? (usdValue / tokenPrice).toFixed(Number(data.token.decimals)) : amountToWithdraw
+                    tokenPrice > 0 ? (usdValue / tokenPrice).toFixed(Number(data.token.decimals)) : effectiveAmount
 
                 const completeWithdrawData = { ...data, amount: destinationTokenAmount }
                 setWithdrawData(completeWithdrawData)
@@ -299,6 +308,7 @@ export default function WithdrawCryptoPage() {
         },
         [
             amountToWithdraw,
+            effectiveAmount,
             clearErrors,
             setChargeDetails,
             setIsPreparingReview,
@@ -385,7 +395,7 @@ export default function WithdrawCryptoPage() {
                     txHash,
                     receipt: r,
                     strategy: s,
-                } = await sendMoney(withdrawData.address as Address, amountToWithdraw, {
+                } = await sendMoney(withdrawData.address as Address, effectiveAmount, {
                     kind: 'CRYPTO_WITHDRAW',
                     // Lets the backend settle the charge directly when the spend
                     // routes through Rain card collateral (collateral-only): the
@@ -527,6 +537,7 @@ export default function WithdrawCryptoPage() {
         chargeDetails,
         withdrawData,
         amountToWithdraw,
+        effectiveAmount,
         address,
         transactions,
         payAmount,
@@ -580,21 +591,19 @@ export default function WithdrawCryptoPage() {
         [isCrossChainWithdrawal, networkFee, usdAmount]
     )
 
-    // Pre-sign affordability gate for cross-chain. The input-time gate only
-    // checked the principal, but the kernel must spend principal + bridge fee
-    // (`payAmount`), so a withdraw that fit the balance at input can fall short
-    // here once the fee is known — and the send would surface the misleading
-    // "balance isn't fully available yet" (settling) error instead of an honest
-    // "not enough balance". Block it here with the right message. Only once the
-    // quote has resolved `payAmount` (skipped while calculating; CTA is disabled
-    // by isCalculating anyway).
-    const insufficientForFee = useMemo<boolean>(
+    // Pre-sign affordability gate on every path: the kernel spend (`payAmount`
+    // — the quote's pay side cross-chain, the principal same-chain) must fit
+    // the LIVE balance. The input-time gate saw the balance at input; a card
+    // spend settling, another withdrawal landing first, or a quoted fee can
+    // leave it short here — and the send would surface the misleading
+    // "balance isn't fully available yet" (settling) error instead of an
+    // honest "not enough balance". Only once the route has resolved
+    // `payAmount` (skipped while calculating; CTA is disabled by isCalculating
+    // anyway).
+    const insufficientBalance = useMemo<boolean>(
         () =>
-            isCrossChainWithdrawal &&
-            payAmount != null &&
-            spendableBalance !== undefined &&
-            !isAmountWithinBalance(payAmount, spendableBalance),
-        [isCrossChainWithdrawal, payAmount, spendableBalance]
+            payAmount != null && spendableBalance !== undefined && !isAmountWithinBalance(payAmount, spendableBalance),
+        [payAmount, spendableBalance]
     )
 
     // Rhino accepts SDA deposits below the route minimum on-chain but never
@@ -651,7 +660,7 @@ export default function WithdrawCryptoPage() {
                     receiveAmount={receiveAmount}
                     payAmount={payAmount}
                     showHighFeeWarning={showHighFeeWarning}
-                    insufficientBalance={insufficientForFee}
+                    insufficientBalance={insufficientBalance}
                     belowMinimumMessage={belowMinimumMessage}
                     isFromSendFlow={isFromSendFlow}
                 />

src/app/(mobile-ui)/withdraw/page.tsx

@@ -58,6 +58,7 @@
     const {
         amountToWithdraw: amountFromContext,
         setAmountToWithdraw,
+        setIsMaxWithdrawal,
         setError,
         error,
         setUsdAmount,
@@ -201,7 +202,7 @@
         if (amountFromContext) {
             setShowAllWithdrawMethods(true)
         }
     }, [])
 
     const validateAmount = useCallback(
         (amountStr: string): boolean => {
@@ -245,9 +246,21 @@
             setError({ showError: true, errorMessage: message })
             return false
         },
         [balance, maxDecimalAmount, setError, selectedTokenData?.price, isFromSendFlow, minUsdAmount, t, tErrors]
     )
 
+    // The exact string the balance tap last filled. Any other value reaching
+    // handleTokenAmountChange is the user typing, which retires the max intent.
+    const filledFromBalanceRef = useRef<string | null>(null)
+
+    const handleBalanceFilled = useCallback(
+        (value: string) => {
+            filledFromBalanceRef.current = value
+            setIsMaxWithdrawal(true)
+        },
+        [setIsMaxWithdrawal]
+    )
+
     const handleTokenAmountChange = useCallback(
         (value: string | undefined) => {
             let newValue = value || ''
@@ -257,6 +270,11 @@
             }
             setRawTokenAmount(newValue)
 
+            if (newValue !== filledFromBalanceRef.current) {
+                filledFromBalanceRef.current = null
+                setIsMaxWithdrawal(false)
+            }
+
             // ignore programmatically injected tiny residual amounts (<1) before user interaction
             const numericVal = parseFloat(newValue)
             if (!userTypedRef.current && numericVal > 0 && numericVal < 1) {
@@ -273,7 +291,7 @@
                 setError({ showError: false, errorMessage: '' })
             }
         },
         [setRawTokenAmount, error.showError, setError]
     )
 
     // only validate when rawTokenAmount changes and we're in inputAmount step
@@ -439,6 +457,8 @@
                             decimals: 6, // we want USDC decimals to be able to pay exactly
                         }}
                         walletBalance={peanutWalletBalance}
+                        balanceFillAmount={maxDecimalAmount}
+                        onBalanceFilled={handleBalanceFilled}
                         hideCurrencyToggle
                     />