feat(card): resolve Immersve spendable balance from on-chain allowance

[Brunonascdev]

Description

Immersve funding assets previously left spendableBalance / spendingCap empty because the Immersve API reports a funding-source balance of 0. Card Home therefore could not show how much a user can actually spend.

This PR:

1. Reads ERC-20 balanceOf + allowance on-chain (spender from the Immersve feature-flag config) and sets spendable balance to min(balance, allowance).
2. Resumes returning Immersve users onto their existing card program + funding source via getResumeCardInfo, instead of always creating/resolving against the default funding channel.
3. Adds Arbitrum Sepolia USDC funding token mapping for Immersve networks that use that chain.

Immersve Funding Approval continues to always submit ERC-20 approve with BAANX_MAX_LIMIT (no spending-limit selector), matching polish PR #33655.

Changelog

CHANGELOG entry: Added Immersve Card spendable balance based on on-chain wallet balance and allowance

Related issues

Refs: null

Manual testing steps

Feature: Immersve Card spendable balance

  Scenario: Card Home shows on-chain spendable balance for an Immersve card
    Given the user has completed Immersve onboarding with an active card
    And the card feature flag includes immersve.spenderAddress
    And the funding wallet has USDC balance and a non-zero allowance to the spender

    When the user opens Card Home
    Then the funding asset shows spendable balance as min(wallet balance, allowance)

  Scenario: Returning Immersve user resumes the existing card program
    Given the user previously completed Immersve onboarding on a non-default program
    And the Immersve account already has a card with funding sources

    When the user signs in again via Immersve resume onboarding
    Then the app selects the existing cardProgramId
    And the app reuses the existing funding source id without creating a new one

Screenshots/Recordings

Before

N/A

After

N/A

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 Immersve funding resolution and live RPC reads for balances; misconfigured spender or RPC could show wrong or empty spendable amounts, but changes are gated by feature flag and fail soft on errors.

Overview
Immersve Card Home can now show how much the user can actually spend by reading ERC-20 balanceOf and allowance on the funding network (spender from immersve.spenderAddress in the card feature flag) and setting spendableBalance to min(balance, allowance) with spendingCap from allowance. On-chain reads are skipped when the spender is unset; RPC failures leave balances empty.

Returning Immersve users resume via new getResumeCardInfo (card program + funding source IDs from the existing card). Resume onboarding applies the stored program and reuses the existing funding source instead of always resolving against the default funding channel.

Arbitrum Sepolia is added as an Immersve funding network (RPC, USDC address, CAIP mapping). Tests cover allowance math, resume routing, and provider behavior.

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

[github-actions]

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]

🧪 Flaky unit test detection

Run history flaky detection

View recent run history

Historical failure rate is a hint, not proof — review each suggestion in context. See the flaky-test-detection skill for the full pattern reference and manual audit workflow.

Failures / runs sampled per window:

File	7d	15d	30d
app/components/UI/Card/components/Onboarding/SignUp.test.tsx	0/163	0/273	0/288
app/core/Engine/controllers/card-controller/CardController.test.ts	0/163	0/273	0/288

AI-detected flaky patterns

app/components/UI/Card/components/Onboarding/SignUp.test.tsx

• J3 — Missing jest.clearAllMocks()/resetAllMocks() between tests (high)
  • Multiple top-level mock fns (mockImmersveSignIn, mockGetFundingSources, mockCreateFundingSource, mockGetSpendingPrerequisites, etc.) have .mockResolvedValue/.mockReturnValue and .mockRejectedValue set inside individual it() blocks (e.g. the three Immersve flow tests and error-handling tests). beforeEach only calls jest.clearAllMocks() (which preserves implementations). Without jest.resetAllMocks() in afterEach, mock state leaks across tests and can produce order-dependent failures. The PR change itself added another mockResolvedValue in beforeEach, but does not address the root isolation gap.
  • Suggested fix in app/components/UI/Card/components/Onboarding/SignUp.test.tsx:285:

    -beforeEach(() => {
    -    jest.clearAllMocks();
    -    mockUseCardPostAuthRedirect.mockReturnValue(undefined);
    -    mockNavigate = jest.fn();
    -    mockGoBack = jest.fn();
    -    // ...
    -    const cardFlagSelectors = jest.requireMock(
    -      '../../../../../selectors/featureFlagController/card',
    -    );
    -    const actualCardFlagSelectors = jest.requireActual(
    -      '../../../../../selectors/featureFlagController/card',
    -    );
    -    (
    -      cardFlagSelectors.selectImmersveOnboardingEnabled as jest.Mock
    -    // ...
    -    mockGetResumeCardInfo.mockResolvedValue(null);
    -    store = createTestStore();
    -  });
    +beforeEach(() => {
    +    jest.clearAllMocks();
    +    mockUseCardPostAuthRedirect.mockReturnValue(undefined);
    +    mockNavigate = jest.fn();
    +    mockGoBack = jest.fn();
    +    // ...
    +    const cardFlagSelectors = jest.requireMock(
    +      '../../../../../selectors/featureFlagController/card',
    +    );
    +    const actualCardFlagSelectors = jest.requireActual(
    +      '../../../../../selectors/featureFlagController/card',
    +    );
    +    (
    +      cardFlagSelectors.selectImmersveOnboardingEnabled as jest.Mock
    +    // ...
    +    mockGetResumeCardInfo.mockResolvedValue(null);
    +    store = createTestStore();
    +  });
    +
    +afterEach(() => {
    +    jest.resetAllMocks();
    +  });

• J5 — Incomplete mock store state (medium)
  • createTestStore defaults to an empty object and only populates a narrow slice of backgroundState (GeolocationController + partial CardController). Many tests rely on this default store (or pass only geoLocation/onboarding). The component, its hooks (useEmailVerificationSend, useDebouncedValue, useRegions, useImmersve*), and selectors access additional Redux slices (metamask, settings, full engine.backgroundState, feature flags, etc.). Missing slices can produce intermittent selector errors or undefined behavior under varying test order or React render timing.
  • Suggested fix in app/components/UI/Card/components/Onboarding/SignUp.test.tsx:60:

    -const createTestStore = (initialState: Record<string, unknown> = {}) => {
    -  const { geoLocation, selectedCardProgramId, ...cardState } = initialState;
    -  const engineState = {
    -    backgroundState: {
    -      GeolocationController:
    -        typeof geoLocation === 'string' ? { location: geoLocation } : undefined,
    -      CardController: {
    -    // ...
    -
    -describe('SignUp Component', () => {
    -  let store: ReturnType<typeof createTestStore>;
    -  // ...
    -  beforeEach(() => {
    -    // ...
    -    mockGetResumeCardInfo.mockResolvedValue(null);
    -    store = createTestStore();
    -  });
    +const createTestStore = (initialState: Record<string, unknown> = {}) => {
    +  const { geoLocation, selectedCardProgramId, ...cardState } = initialState;
    +  const engineState = {
    +    backgroundState: {
    +      GeolocationController:
    +        typeof geoLocation === 'string' ? { location: geoLocation } : undefined,
    +      CardController: {
    +        // ... full mock as in other Card tests
    +      },
    +      // ... other controllers
    +    },
    +  };
    +  return configureStore({
    +    reducer: rootReducer, // or the actual reducers used by the app
    +    preloadedState: {
    +      engine: engineState,
    +      metamask: mockMetamaskState,
    +      settings: settingsInitialState,
    +      onboarding: { ...defaultOnboardingState, ...cardState },
    +      ...initialState,
    +    },
    +  });
    +};

app/core/Engine/controllers/card-controller/CardController.test.ts

• J6 — Arbitrary setTimeout/sleep used as a synchronization barrier (high)
  • This helper is used throughout the test file (e.g. to poll on mock.calls.length before proceeding with auth/logout flows) as a real-timer synchronization barrier. It relies on wall-clock Date.now() for the deadline and setImmediate (real macrotask) in a busy-wait loop. Per the loaded skill (J6), arbitrary timer-based barriers are a top source of intermittent CI failures under load; the function comment even acknowledges timing sensitivity around microtask vs macrotask draining. No fake timers are used in this file. Historical data showed zero failures but the pattern is present and risky.
  • Suggested fix in app/core/Engine/controllers/card-controller/CardController.test.ts:

    -async function waitForCondition(
    -  predicate: () => boolean,
    -  timeoutMs = 1000,
    -): Promise<void> {
    -  const deadline = Date.now() + timeoutMs;
    -  while (!predicate()) {
    -    if (Date.now() > deadline) {
    -      throw new Error('waitForCondition predicate never became true');
    -    }
    -    await new Promise<void>((resolve) => {
    -      setImmediate(resolve);
    -    });
    -  }
    -}
    +async function waitForCondition(
    +  predicate: () => boolean,
    +  maxIterations = 100,
    +): Promise<void> {
    +  for (let i = 0; i < maxIterations; ++i) {
    +    if (predicate()) {
    +      return;
    +    }
    +    await new Promise<void>((resolve) => {
    +      setImmediate(resolve);
    +    });
    +  }
    +  throw new Error('waitForCondition predicate never became true');
    +}

This check is informational only and does not block merging.

[github-actions]

🔍 Smart E2E Test Selection

• Selected E2E tags: SmokeMoney, SmokeSwap, SmokeConfirmations
• Selected Performance tags: None (no tests recommended)
• Risk Level: medium
• AI Confidence: 85%

click to see 🤖 AI reasoning details

E2E Test Selection:
All changes in this PR are focused on the MetaMask Card (Immersve) functionality:

1. CardController.ts: Added getResumeCardInfo() method that fetches card program ID and funding source IDs from the Immersve provider.
2. ImmersveProvider.ts: Major additions including:
   • getResumeCardInfo() method to retrieve card details for resume flows
   • resolveOnChainSpendableBalance() to read actual ERC-20 balance and allowance on-chain (replacing the previous empty string approach)
   • createFundingNetworkProvider() for connecting to Base Mainnet, Base Sepolia, and Arbitrum Sepolia networks
   • Arbitrum Sepolia network support
3. onChainAllowance.ts: New utility file for reading ERC-20 allowance and balance on-chain using ethers.js
4. immersveFunding.ts: Added Arbitrum Sepolia network mapping
5. constants.ts: Added Arbitrum Sepolia RPC URL and USDC token address
6. useImmersveResumeOnboarding.ts: Updated to use getResumeCardInfo() to pre-populate card program ID and funding source ID during resume onboarding
7. featureFlagController/card/index.ts: Added spenderAddress field to Immersve program config (used for on-chain allowance checks)

The primary impact is on the Card (Immersve) onboarding/resume flow and funding source balance display. The SmokeMoney tag directly covers Card Home and Add Funds flows. Per the tag description, when selecting SmokeMoney for Card Add Funds flows that execute swaps, also select SmokeSwap and SmokeConfirmations. The changes to on-chain balance resolution and resume onboarding could affect the Add Funds flow which may involve swap paths.

Performance Test Selection:
The changes are focused on Card/Immersve controller logic, on-chain balance reading, and resume onboarding flows. None of these changes affect performance-sensitive paths like app launch, login, account list rendering, swap quote fetching, or asset loading. The on-chain balance reading is a new async operation but it's within the Card controller scope and not measured by any performance test scenario.

View GitHub Actions results

[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 a422e92. Configure here.}

[sonarqubecloud]

Quality Gate passed

Issues
5 New issues
0 Accepted issues

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

See analysis details on SonarQube Cloud