chore: back-merge main → dev (2026-06-07)

.verify-content-baseline

@@ -1 +1 @@
-726
+745

src/app/(mobile-ui)/card-recovery/page.tsx

@@ -0,0 +1,215 @@
+'use client'
+
+import { useCallback, useEffect, useState } from 'react'
+import { useRouter } from 'next/navigation'
+import type { Address, Hex } from 'viem'
+import { Button } from '@/components/0_Bruddle/Button'
+import { Card } from '@/components/0_Bruddle/Card'
+import ErrorAlert from '@/components/Global/ErrorAlert'
+import NavHeader from '@/components/Global/NavHeader'
+import PeanutLoading from '@/components/Global/PeanutLoading'
+import { useKernelClient } from '@/context/kernelClient.context'
+import {
+    RAIN_WITHDRAW_EIP712_DOMAIN_NAME,
+    RAIN_WITHDRAW_EIP712_DOMAIN_VERSION,
+    rainWithdrawEip712Types,
+} from '@/constants/rain.consts'
+import { PEANUT_WALLET_CHAIN } from '@/constants/zerodev.consts'
+import { rainApi, type RecoverFundsPreviewResponse } from '@/services/rain'
+import { getExplorerUrl } from '@/utils/general.utils'
+
+type Step = 'preview' | 'confirm' | 'signing' | 'submitting' | 'done'
+
+/**
+ * Card collateral recovery flow.
+ *
+ * For the deleted-Rain-user case: a user's collateral USDC is sitting on-chain
+ * in the Rain coordinator's proxy, but Rain's balance endpoint won't return it
+ * because their Rain user record was deleted. The normal /withdraw flow can't
+ * see the balance, so we have a dedicated recovery endpoint pair on the
+ * backend that reads the on-chain balance directly and asks Rain for a
+ * signature for that exact amount, paid to the user's own smart wallet.
+ *
+ * This page wires that flow: preview → confirm → kernel-sign EIP-712 →
+ * submit. The destination address is decided by the backend and shown here
+ * for transparency; the FE cannot influence it.
+ *
+ * Not linked from anywhere in the main app — accessed by URL only. It's safe
+ * to share the URL with a user who needs to recover funds: the JWT cookie is
+ * the only auth, the recipient is server-locked, and the signing step still
+ * requires the user's passkey.
+ */
+export default function CardRecoveryPage() {
+    const router = useRouter()
+    const { getClientForChain } = useKernelClient()
+
+    const [step, setStep] = useState<Step>('preview')
+    const [preview, setPreview] = useState<RecoverFundsPreviewResponse | null>(null)
+    const [error, setError] = useState<string | null>(null)
+    const [txHash, setTxHash] = useState<Hex | null>(null)
+
+    useEffect(() => {
+        let cancelled = false
+        ;(async () => {
+            try {
+                const data = await rainApi.getRecoverFundsPreview()
+                if (!cancelled) setPreview(data)
+            } catch (e) {
+                if (!cancelled) setError((e as Error).message || 'Could not load recovery preview')
+            }
+        })()
+        return () => {
+            cancelled = true
+        }
+    }, [])
+
+    const handleRecover = useCallback(async () => {
+        setError(null)
+        setStep('signing')
+        try {
+            // Prepare locks in the amount + recipient server-side. Even if the
+            // page were tampered with at runtime, the backend signs over the
+            // values it computed itself.
+            const prep = await rainApi.prepareRecoverFunds()
+
+            const chainIdStr = String(PEANUT_WALLET_CHAIN.id)
+            const chainIdNum = Number(prep.chainId)
+            const kernelClient = getClientForChain(chainIdStr)
+
+            const adminSignature = (await kernelClient.account!.signTypedData({
+                domain: {
+                    name: RAIN_WITHDRAW_EIP712_DOMAIN_NAME,
+                    version: RAIN_WITHDRAW_EIP712_DOMAIN_VERSION,
+                    chainId: chainIdNum,
+                    verifyingContract: prep.collateralProxy as Address,
+                    salt: prep.adminSalt as Hex,
+                },
+                types: rainWithdrawEip712Types,
+                primaryType: 'Withdraw',
+                message: {
+                    user: prep.adminAddress as Address,
+                    asset: prep.tokenAddress as Address,
+                    amount: BigInt(prep.amount),
+                    recipient: prep.recipientAddress as Address,
+                    nonce: BigInt(prep.adminNonce),
+                },
+            })) as Hex
+
+            setStep('submitting')
+            const { txHash: hash } = await rainApi.submitWithdrawal({
+                preparationId: prep.preparationId,
+                amount: prep.amount,
+                recipientAddress: prep.recipientAddress,
+                directTransfer: prep.directTransfer,
+                adminSalt: prep.adminSalt,
+                adminNonce: prep.adminNonce,
+                adminSignature,
+                executorSignature: prep.executorSignature,
+                executorSalt: prep.executorSalt,
+                expiresAt: prep.expiresAt,
+            })
+            setTxHash(hash as Hex)
+            setStep('done')
+        } catch (e) {
+            setError((e as Error).message || 'Recovery failed — please try again')
+            setStep('preview')
+        }
+    }, [getClientForChain])
+
+    if (!preview && !error) return <PeanutLoading />
+
+    return (
+        <div className="flex min-h-[inherit] flex-col gap-8">
+            <NavHeader title="Recover card funds" onPrev={() => router.push('/home')} />
+            <div className="my-auto flex flex-col gap-6">
+                {error && <ErrorAlert description={error} />}
+
+                {step === 'done' && txHash ? (
+                    <Card className="flex flex-col gap-3 p-6">
+                        <h2 className="text-h7 font-bold">Funds sent to your wallet.</h2>
+                        <p className="text-sm text-grey-1">
+                            ${formatCents(preview!.amountCents)} USDC has been returned to your peanut wallet.
+                        </p>
+                        <a
+                            className="text-black underline"
+                            target="_blank"
+                            rel="noreferrer"
+                            href={`${getExplorerUrl(String(PEANUT_WALLET_CHAIN.id)) ?? ''}/tx/${txHash}`}
+                        >
+                            View transaction
+                        </a>
+                    </Card>
+                ) : (
+                    preview && (
+                        <>
+                            <Card className="flex flex-col gap-3 p-6">
+                                <h2 className="text-h7 font-bold">
+                                    {preview.hasRecoverableCard ? 'Recover your card collateral' : 'No card on file'}
+                                </h2>
+                                <p className="text-sm text-grey-1">
+                                    This pulls every USDC currently held in your card collateral contract back to your
+                                    peanut wallet. Auto-balance is turned off as part of recovery so the rebalancer
+                                    can't top up between now and the transfer.
+                                </p>
+
+                                <Row label="Recoverable" value={`$${formatCents(preview.amountCents)} USDC`} />
+                                <Row label="Destination" value={shorten(preview.recipient)} />
+                                {BigInt(preview.dustWei) > 0n && (
+                                    <Row label="Dust left in contract" value={`${preview.dustWei} wei (< $0.01)`} />
+                                )}
+                                <Row
+                                    label="Auto-balance"
+                                    value={preview.autoBalanceEnabled ? 'on — will be turned off' : 'off'}
+                                />
+                            </Card>
+
+                            <Button
+                                variant="purple"
+                                shadowSize="4"
+                                className="w-full"
+                                disabled={
+                                    step === 'signing' ||
+                                    step === 'submitting' ||
+                                    BigInt(preview.amountCents) <= 0n ||
+                                    !preview.hasRecoverableCard
+                                }
+                                loading={step === 'signing' || step === 'submitting'}
+                                onClick={handleRecover}
+                            >
+                                {step === 'signing'
+                                    ? 'Sign with passkey…'
+                                    : step === 'submitting'
+                                      ? 'Submitting…'
+                                      : 'Recover funds'}
+                            </Button>
+                        </>
+                    )
+                )}
+            </div>
+        </div>
+    )
+}
+
+function Row({ label, value }: { label: string; value: string }) {
+    return (
+        <div className="flex items-center justify-between">
+            <span className="text-sm text-grey-1">{label}</span>
+            <span className="text-sm font-medium text-n-1">{value}</span>
+        </div>
+    )
+}
+
+// Render Rain cents (2 dp) as a fixed-precision USD amount with thousand
+// separators. Cents are bigint-string from the wire — never Number() them
+// directly; > 2^53 risks lossy display on whales.
+function formatCents(centsStr: string): string {
+    const cents = BigInt(centsStr)
+    const dollars = cents / 100n
+    const remainder = (cents % 100n).toString().padStart(2, '0')
+    return `${dollars.toLocaleString('en-US')}.${remainder}`
+}
+
+function shorten(addr: string): string {
+    if (addr.length <= 12) return addr
+    return `${addr.slice(0, 6)}…${addr.slice(-4)}`
+}

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

@@ -8,7 +8,7 @@ import { cardApi, type CardInfoResponse } from '@/services/card'
 import { useAuth } from '@/context/authContext'
 import { RAIN_CARD_OVERVIEW_QUERY_KEY, useRainCardOverview } from '@/hooks/useRainCardOverview'
 import { computeCardState, findActiveCard, type CardTopLevelState } from '@/components/Card/cardState.utils'
-import { pollUntilApplyAdvances } from '@/components/Card/cardApply.utils'
+import { pollUntilApplyAdvances, pollUntilReady } from '@/components/Card/cardApply.utils'
 import AddCardEntryScreen from '@/components/Card/AddCardEntryScreen'
 import ApplicationStatusScreen from '@/components/Card/ApplicationStatusScreen'
 import CardTermsScreen from '@/components/Card/CardTermsScreen'
@@ -360,10 +360,36 @@ const CardPage: FC = () => {
         pollAbortRef.current = controller
 
         try {
+            // Two-stage poll. First wait for the webhook-stamped readiness flag
+            // (cheap, DB-only, safe at 1s cadence). Once Sumsub has reviewed
+            // rain-requirements GREEN, fall through to the existing apply poll.
+            //
+            // Previous behaviour: single-stage `pollUntilApplyAdvances` against
+            // POST /rain/cards — every iteration hit Sumsub for `moveToLevel` +
+            // `getApplicant` + `getQuestionnaireAnswers`. ~75 Sumsub round-trips
+            // per stuck user, AND the WebSDK got re-opened on every `incomplete`
+            // in the race window, showing the user "verification is taking
+            // longer than expected" (Barbara F-M's 2026-06-02 Crisp escalation).
+            const readyResult = await pollUntilReady({
+                fetchReadiness: () => rainApi.getCardApplyReadiness(),
+                intervalMs: 1000,
+                timeoutMs: 30000,
+                signal: controller.signal,
+            })
+            if (controller.signal.aborted) return
+            if (readyResult === false) {
+                setApplyError('Verification is taking longer than expected. Please try again.')
+                return
+            }
+
+            // Sumsub is GREEN — single apply call should now advance past
+            // `incomplete`. Keep `pollUntilApplyAdvances` as a thin safety net
+            // for the rare case where the webhook flag landed but the
+            // applicant state hasn't fully propagated (e.g. read-replica lag).
             const res = await pollUntilApplyAdvances({
                 fetchApply: () => rainApi.applyForCard({ termsAccepted: false }),
                 intervalMs: 1000,
-                timeoutMs: 15000,
+                timeoutMs: 5000,
                 signal: controller.signal,
             })
             if (controller.signal.aborted) return

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

@@ -48,7 +48,7 @@
     default: (props: any) => {
         // next/image uses 'fill' boolean; strip non-DOM props
         const { priority, layout, objectFit, fill, ...rest } = props
         return <img {...rest} />
     },
 }))
 
@@ -129,7 +129,7 @@
 }))
 
 jest.mock('@/utils/balance.utils', () => ({
-    rainSpendingPowerToWei: jest.fn(() => 0n),
+    rainCentsToUsdcUnits: jest.fn(() => 0n),
 }))
 
 const mockUseTransactionDetailsDrawer = jest.fn()

src/app/(mobile-ui)/qr-pay/page.tsx

@@ -21,7 +21,7 @@
 import { InsufficientSpendableError, SessionKeyGrantRequiredError } from '@/hooks/wallet/useSpendBundle'
 import { rainCollateralErrorMessage } from '@/utils/friendly-error.utils'
 import { useRainCardOverview } from '@/hooks/useRainCardOverview'
-import { rainSpendingPowerToWei } from '@/utils/balance.utils'
+import { rainCentsToUsdcUnits } from '@/utils/balance.utils'
 import { isTxReverted, saveRedirectUrl, formatNumberForDisplay } from '@/utils/general.utils'
 import { getShakeClass, type ShakeIntensity } from '@/utils/perk.utils'
 import {
@@ -229,7 +229,7 @@
         if (sumsubFlow.showWrapper || sumsubFlow.isModalOpen) {
             sumsubFlow.completeFlow()
         }
     }, [kycGateState, sumsubFlow.showWrapper, sumsubFlow.isModalOpen, sumsubFlow.completeFlow])
 
     const queryClient = useQueryClient()
     const [isShaking, setIsShaking] = useState(false)
@@ -342,7 +342,7 @@
         if (isSuccess || !!errorMessage) {
             setLoadingState('Idle')
         }
     }, [isSuccess, errorMessage])
 
     // First fetch for qrcode info — only after KYC gating allows proceeding
     useEffect(() => {
@@ -354,7 +354,7 @@
         }
 
         setIsFirstLoad(false)
     }, [timestamp, paymentProcessor, qrCode])
 
     // Get amount from payment lock (Manteca)
     useEffect(() => {
@@ -369,7 +369,7 @@
             setAmount(paymentLock.paymentAgainstAmount)
             setCurrencyAmount(paymentLock.paymentAssetAmount)
         }
     }, [paymentLock?.code, paymentProcessor])
 
     // Get currency object from payment lock (Manteca)
     useEffect(() => {
@@ -391,7 +391,7 @@
             }
         }
         getCurrencyObject().then(setCurrency)
     }, [paymentLock?.code, paymentProcessor])
 
     const isBlockingError = useMemo(() => {
         return !!errorMessage && errorMessage !== 'Please confirm the transaction.'
@@ -407,7 +407,7 @@
             // For dynamic QR codes, backend provides the USD amount
             return paymentLock.paymentAgainstAmount
         }
     }, [paymentLock?.code, paymentLock?.paymentAgainstAmount, amount])
 
     // Live card-vs-local-rail markup, driven by Manteca's rate + (for ARS)
     // BCRA's official rate. Used by both the confirm-screen "Save vs card"
@@ -600,7 +600,7 @@
                 requiredUsdcAmount,
                 recipient: MANTECA_DEPOSIT_ADDRESS,
                 smartBalance: balance ?? 0n,
-                rainSpendingPower: rainSpendingPowerToWei(rainCardOverview?.balance?.spendingPower),
+                rainSpendingPower: rainCentsToUsdcUnits(rainCardOverview?.balance?.spendingPower),
                 kind: 'QR_PAY',
             })
         } catch (error) {

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

@@ -4,7 +4,7 @@ import { useWallet } from '@/hooks/wallet/useWallet'
 import { useSignSpendBundle } from '@/hooks/wallet/useSignSpendBundle'
 import { InsufficientSpendableError, SessionKeyGrantRequiredError } from '@/hooks/wallet/useSpendBundle'
 import { rainCollateralErrorMessage } from '@/utils/friendly-error.utils'
-import { rainSpendingPowerToWei } from '@/utils/balance.utils'
+import { rainCentsToUsdcUnits } from '@/utils/balance.utils'
 import { useRainCardOverview } from '@/hooks/useRainCardOverview'
 import { useState, useMemo, useContext, useEffect, useCallback, useId } from 'react'
 import { useRouter, useSearchParams } from 'next/navigation'
@@ -341,7 +341,7 @@ export default function MantecaWithdrawFlow() {
                     requiredUsdcAmount,
                     recipient: MANTECA_DEPOSIT_ADDRESS,
                     smartBalance: smartBalance ?? 0n,
-                    rainSpendingPower: rainSpendingPowerToWei(rainCardOverview?.balance?.spendingPower),
+                    rainSpendingPower: rainCentsToUsdcUnits(rainCardOverview?.balance?.spendingPower),
                     kind: 'FIAT_OFFRAMP',
                 })
             } catch (error) {

src/components/Card/CancelCardModal.tsx

@@ -12,7 +12,7 @@ import { RAIN_CARD_OVERVIEW_QUERY_KEY, useRainCardOverview } from '@/hooks/useRa
 import { useSignSpendBundle } from '@/hooks/wallet/useSignSpendBundle'
 import { InsufficientSpendableError, SessionKeyGrantRequiredError } from '@/hooks/wallet/useSpendBundle'
 import { useWallet } from '@/hooks/wallet/useWallet'
-import { rainSpendingPowerToWei } from '@/utils/balance.utils'
+import { rainCentsToUsdcUnits } from '@/utils/balance.utils'
 
 type Phase = 'confirm' | 'canceling' | 'feedback' | 'submitting-feedback' | 'thanks'
 
@@ -60,18 +60,18 @@ const CancelCardModal: FC<Props> = ({ cardId, isOpen, onClose }) => {
             // Cancel can be terminal on Rain's side (collateral contract may
             // become unreachable), so we MUST drain it BEFORE the cancel.
             // Backend enforces order — this just delivers the signed body.
-            const spendingPowerWei = rainSpendingPowerToWei(overview?.balance?.spendingPower)
+            const spendingPowerUnits = rainCentsToUsdcUnits(overview?.balance?.spendingPower)
             let verifiedWithdrawal: import('@/hooks/wallet/useSignSpendBundle').SignedRainWithdrawal | undefined
-            if (spendingPowerWei > 0n) {
+            if (spendingPowerUnits > 0n) {
                 if (!smartWalletAddress) {
                     throw new Error('Wallet not ready — please retry in a moment')
                 }
                 // Force collateral-only routing — same pattern as LockCardModal.
                 const artifact = await signSpend({
-                    requiredUsdcAmount: spendingPowerWei,
+                    requiredUsdcAmount: spendingPowerUnits,
                     recipient: smartWalletAddress as `0x${string}`,
                     smartBalance: 0n,
-                    rainSpendingPower: spendingPowerWei,
+                    rainSpendingPower: spendingPowerUnits,
                     kind: 'CRYPTO_WITHDRAW',
                 })
                 if (artifact.strategy !== 'collateral-only') {

src/components/Card/LockCardModal.tsx

@@ -12,7 +12,7 @@ import { RAIN_CARD_OVERVIEW_QUERY_KEY, useRainCardOverview } from '@/hooks/useRa
 import { useSignSpendBundle } from '@/hooks/wallet/useSignSpendBundle'
 import { InsufficientSpendableError, SessionKeyGrantRequiredError } from '@/hooks/wallet/useSpendBundle'
 import { useWallet } from '@/hooks/wallet/useWallet'
-import { rainSpendingPowerToWei } from '@/utils/balance.utils'
+import { rainCentsToUsdcUnits } from '@/utils/balance.utils'
 
 type Mode = 'lock' | 'unlock'
 type Phase = 'prompt' | 'loading' | 'success' | 'error'
@@ -67,9 +67,9 @@ const LockCardModal: FC<Props> = ({ cardId, mode, isOpen, onClose }) => {
                 // smart wallet BEFORE locking so funds stay liquid. The
                 // backend gates the lock on a successful withdrawal — order
                 // is handled there. We only need to deliver the signed body.
-                const spendingPowerWei = rainSpendingPowerToWei(overview?.balance?.spendingPower)
+                const spendingPowerUnits = rainCentsToUsdcUnits(overview?.balance?.spendingPower)
                 let verifiedWithdrawal: import('@/hooks/wallet/useSignSpendBundle').SignedRainWithdrawal | undefined
-                if (spendingPowerWei > 0n) {
+                if (spendingPowerUnits > 0n) {
                     if (!smartWalletAddress) {
                         throw new Error('Wallet not ready — please retry in a moment')
                     }
@@ -78,10 +78,10 @@ const LockCardModal: FC<Props> = ({ cardId, mode, isOpen, onClose }) => {
                     // picks 'collateral-only' and signs a Rain withdrawal
                     // straight to the user's smart wallet (1 passkey tap).
                     const artifact = await signSpend({
-                        requiredUsdcAmount: spendingPowerWei,
+                        requiredUsdcAmount: spendingPowerUnits,
                         recipient: smartWalletAddress as `0x${string}`,
                         smartBalance: 0n,
-                        rainSpendingPower: spendingPowerWei,
+                        rainSpendingPower: spendingPowerUnits,
                         kind: 'CRYPTO_WITHDRAW',
                     })
                     if (artifact.strategy !== 'collateral-only') {