fix: prevent false token unavailable errors with RampsController status tracking

[georgeweiler]

Description

Rehosting #26962

This PR fixes false positive "Token Not Available" errors in the Buy flow by leveraging the new status field from RampsController ResourceState. Previously, the component used refs to track loading cycles because the controller's default state ({ data: [], isLoading: false }) was indistinguishable from a completed fetch returning no data.

With the controller now exposing explicit status ('idle' | 'loading' | 'success' | 'error'), we can directly check paymentMethodsStatus === 'success' && paymentMethods.length === 0 to accurately determine token unavailability.

Changelog

CHANGELOG entry: Fixed false "Token Not Available" errors during Buy flow when payment methods are still loading

Related issues

Fixes: (original issue reference)
Depends on:
MetaMask/core#8158

Manual testing steps

Feature: Buy flow token availability detection

  Scenario: user selects token with no payment methods
    Given user is on the Buy quote screen
    And payment methods fetch is in progress

    When user has selected a provider and token
    Then user should not see "Token Not Available" error
    And should see loading state instead

  Scenario: user selects unavailable token after fetch completes
    Given user is on the Buy quote screen
    And payment methods fetch has completed successfully
    And payment methods array is empty

    When user views the screen
    Then user should see "Token Not Available" modal

Screenshots/Recordings

Before

False positive "Token Not Available" error appeared immediately when payment methods were still loading.

After

"Token Not Available" only appears after payment methods fetch completes with empty results.

Simulator.Screen.Recording.-.iPhone.16.Pro.-.2026-03-05.at.10.41.16.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.

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
Modifies Buy flow navigation conditions and adds a persisted-state migration for RampsController resources, so mistakes could cause incorrect modals or migration edge-case regressions on upgrade.

Overview
Prevents premature navigation to RampTokenNotAvailableModal in BuildQuote by introducing tokenStateIsSettled gating and checking paymentMethodsStatus === RequestStatus.SUCCESS && paymentMethods.length === 0 (in addition to the provider’s supportedCryptoCurrencies metadata).

Plumbs a new status field through ramps hooks (useRampsPaymentMethods/useRampsController) and updates ramps selectors to default/tolerate missing status while preserving referential equality when status is present.

Adds migration 125 to backfill missing status: 'idle' on persisted RampsController ResourceStates (including Transak sub-states), updates initial background state fixtures, and expands/adjusts unit tests to cover the new status-based behavior.

^{Written by Cursor Bugbot for commit 0b31108. This will update automatically on new commits. 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]

🔍 Smart E2E Test Selection

• Selected E2E tags: SmokeRamps
• Selected Performance tags: None (no tests recommended)
• Risk Level: medium
• AI Confidence: 80%

click to see 🤖 AI reasoning details

E2E Test Selection:
The changes are concentrated in the Ramp (fiat on-ramp/off-ramp) feature: updates to useRampsController, ramps selectors, payment methods hook, BuildQuote view, and related tests. There is also a new store migration (125) and updates to initial background state, which may affect how the ramps controller state is initialized or persisted.

No other core controllers (e.g., NetworkController, AccountController), navigation, confirmations system, or shared wallet platform components were modified. The changes appear scoped to ramp flows (amount input, provider/payment method selection, quote building, region selection) and ramps controller state handling.

Given this scope, running SmokeRamps is necessary to validate:

• Off-ramp amount input (direct entry, percentage buttons, delete behavior)
• Region-aware on-ramp flows
• Deep link navigation into buy flows
• Network/limit validation handling in ramp flows

No evidence of changes to wallet home entry points, account management, confirmations, multi-chain permissions, or other platform-wide components, so additional tags (e.g., SmokeWalletPlatform, SmokeConfirmations, SmokeAccounts) are not required.

The migration introduces some additional risk related to state shape changes, but still within the ramps domain, keeping overall risk medium and scoped to SmokeRamps.

Performance Test Selection:
The changes are limited to ramps UI logic, selectors, and state initialization. No modifications to global rendering paths (account list, onboarding, login, swaps, launch, asset loading) or performance-critical shared components were identified. There are no changes to performance test infrastructure or high-impact rendering lists. Therefore, no dedicated performance tests are required.

View GitHub Actions results

[github-actions]

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