feat: enable MM Pay provider fallback routing and Across strategy support on mobile

[pedronfigueiredo]

Description

This PR enables MM Pay provider fallback routing and Across strategy support on mobile, so MM Pay flows can resolve an ordered provider list from confirmations_pay instead of being hardwired to Relay. It also updates mobile MM Pay consumers to recognize the new Across child transaction types used by Perps and Predict flows across activity, confirmation, history, notifications, and metrics surfaces.

The generic route-based confirmations_pay strategy resolution has now been standardized upstream in MetaMask/core#8282. On the mobile side, this PR narrows the routing API to MM Pay-specific wrappers that derive route context from transaction metadata and consume the shared routing behavior, while keeping compatibility with the currently published @metamask/transaction-pay-controller version until the newer core package is available in mobile.

Feature flag consumption remains mobile-driven through confirmations_pay and confirmations_pay_post_quote. Mobile continues to own the MM Pay route-context derivation, selector wiring, controller-init integration, and the transaction-type grouping needed to support Across-based Perps and Predict deposit flows without broadening unrelated UI behavior.

To enable provider fallback, confirmations_pay should define the global strategy order, per-strategy enablement, and any transaction-specific overrides. The schema looks like this:

  strategyOrder?: string[];

  strategyOverrides?: {
    default?: {
      default?: string[];
      chains?: Record<Hex, string[]>;
      tokens?: Record<Hex, Record<Hex, string[]>>;
    };
    transactionTypes?: Record<string, {
      default?: string[];
      chains?: Record<Hex, string[]>;
      tokens?: Record<Hex, Record<Hex, string[]>>;
    }>;
  };

  payStrategies?: {
    across?: {
      apiBase?: string;
      enabled?: boolean;
      fallbackGas?: {
        estimate?: number;
        max?: number;
      };
    };
    relay?: {
      enabled?: boolean;
      executeEnabled?: boolean;
      originGasOverhead?: string;
      pollingInterval?: number;
      pollingTimeout?: number;
    };

Changelog

CHANGELOG entry: null

Related issues

Fixes:

Refs: MetaMask/core#8282

Manual testing steps

Feature: MM Pay provider fallback routing

  Scenario: MM Pay uses the configured global strategy order
    Given `confirmations_pay.strategyOrder` is set to `["across", "relay"]`
    And `confirmations_pay.payStrategies.across.enabled` is true
    And `confirmations_pay.payStrategies.relay.enabled` is true
    When the user opens a supported MM Pay confirmation flow
    Then mobile should resolve Across before Relay

  Scenario: MM Pay honors route-specific overrides
    Given `confirmations_pay.routingOverrides.overrides.perpsDeposit` contains a chain or token override for Relay
    When the user opens a matching Perps deposit confirmation
    Then mobile should resolve the overridden strategy order for that route

  Scenario: MM Pay post-quote routing uses destination context
    Given `confirmations_pay_post_quote` enables a supported withdraw flow
    When the user opens a post-quote withdrawal confirmation
    Then mobile should resolve MM Pay strategy selection using the destination chain and destination token

  Scenario: Across child transactions render correctly in mobile UI
    Given the user completes a Perps or Predict flow that creates an Across child transaction
    When the user views activity, progress, or transaction details
    Then the Across child transaction should be classified and rendered as the correct MM Pay flow step

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.

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
Introduces new strategy-routing logic driven by remote feature flags and expands MM Pay transaction-type classification across UI, notifications, and metrics; incorrect routing or type grouping could impact payment flows and analytics attribution.

Overview
Enables MM Pay provider fallback routing on mobile by switching TransactionPayControllerInit from a hardcoded single getStrategy to a feature-flag-driven getStrategies, backed by new route/transaction helpers in util/transactions/transaction-pay-routing.

Unifies MM Pay transaction-type handling via a new util/transactions/metamask-pay module (use-case mapping, route type grouping, deposit/positive-transfer/detail type lists), and updates activity/history UI, notifications, gas-update logic, and analytics/metrics to recognize Across variants (e.g., perpsAcrossDeposit, predictAcrossDeposit) and to avoid misleading predictClaim amount display.

Adds metrics support for the Across strategy (mm_pay_strategy: 'across') and records optional execution latency (mm_pay_execution_latency), plus refactors token-transfer decoding into a shared transaction-pay-token-transfer utility; accompanying unit tests are expanded throughout.

^{Written by Cursor Bugbot for commit 1e212ba. 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.

[matthewwalsh0]

If this is generic based on transactionType, why is all this exposed to the client and not handled in the controller?

[pedronfigueiredo]

The idea was to based this off the original transaction pay controller API, in which TransactionPayController only knows about strategies and exposes getStrategies (previously getStrategy) specifically so the embedding client can decide the configuration. The transactionType usage is entirely optional, for defining transactionType level overrides.

Is there a chance we might want to configure the strategy selection and ordering on a client basis in the future? Or would you prefer we move the configuration to the controller?

[matthewwalsh0]

I think we should support the clients overriding with custom logic.

But if we're just using our generic feature flags in our own confirmations_pay flag, that can all be standardised in the controller?

[pedronfigueiredo]

Extracted into this PR

[matthewwalsh0]

Ideally we avoid any code-owner changes in the initial PR, plus this is specific to the top level intent types, and not the nested deposit types.

[pedronfigueiredo]

Separated into this PR

[matthewwalsh0]

Also here, good to move the constant, but should we defer to a separate PR for smaller code-owner PR?

[pedronfigueiredo]

Separated into this PR

[github-actions]

🔍 Smart E2E Test Selection

• Selected E2E tags: SmokePerps, SmokePredictions, SmokeWalletPlatform, SmokeConfirmations
• Selected Performance tags: @PerformancePreps, @PerformancePredict
• Risk Level: medium
• AI Confidence: 82%

click to see 🤖 AI reasoning details

E2E Test Selection:
The PR introduces significant changes to MetaMask Pay transaction routing and strategy selection for Perps and Predictions flows:

1. SmokePerps (primary): The TransactionPayController now uses feature-flag-driven strategy routing instead of always returning Relay. New perpsAcrossDeposit and perpsRelayDeposit transaction types are added. The getTransactionActionKey now handles all perps deposit types. Transaction details UI (hero, summary, details) updated to use centralized type helpers. NotificationManager now skips notifications for relay/across deposit types. These changes directly affect the Perps Add Funds flow.

2. SmokePredictions (primary): Same routing changes apply to Predict deposit/withdraw flows. New predictAcrossDeposit and predictRelayDeposit types added. getTransactionActionKey updated for predict types. Transaction details UI updated. These changes directly affect Predictions position opening/closing flows.

3. SmokeWalletPlatform (required by SmokePerps/SmokePredictions): Per tag descriptions, SmokePerps and SmokePredictions require SmokeWalletPlatform (Trending section). Also, transaction history display changes (TransactionElement/utils.js now uses MM_PAY_POSITIVE_TRANSFER_TRANSACTION_TYPES which includes relay/across types) affect the Activities tab.

4. SmokeConfirmations (required by SmokePerps/SmokePredictions): Per tag descriptions, SmokePerps and SmokePredictions require SmokeConfirmations since deposits are on-chain transactions. The confirmation flow is also affected by the strategy routing changes in TransactionPayController.

The changes are medium risk - they refactor existing logic and add new transaction types for Across strategy support, but the core flows remain the same. The feature flag gating means Across strategy won't activate unless explicitly enabled, reducing regression risk for existing flows.

Performance Test Selection:
The TransactionPayController strategy routing changes and new transaction type handling could affect the performance of Perps and Predictions flows. The controller now makes additional calls to RemoteFeatureFlagController to determine strategies, and the new routing logic adds computation for each transaction. The @PerformancePreps tag covers perps market loading and add funds flow, while @PerformancePredict covers prediction market flows - both directly affected by the strategy routing changes.

View GitHub Actions results

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

There are 2 total unresolved issues (including 1 from previous review).

^{Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

[github-actions]

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

[sonarqubecloud]

Quality Gate passed

Issues
3 New issues
0 Accepted issues

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

See analysis details on SonarQube Cloud