feat: MUSD-108 Pre-select payment token for mUSD conversion flow (MetaMask#23225)

<!--
Please submit this PR as a draft initially.
Do not mark it as "Ready for review" until the template has been
completely filled out, and PR status checks have passed at least once.
-->

## **Description**
Adds payment token pre-selection support in
`useAutomaticTransactionPayToken` hook. mUSD conversion flow uses this
to preselect based on the asset CTA clicked.
<!--
Write a short description of the changes included in this pull request,
also include relevant motivation and context. Have in mind the following
questions:
1. What is the reason for the change?
2. What is the improvement/solution?
-->

## **Changelog**

<!--
If this PR is not End-User-Facing and should not show up in the
CHANGELOG, you can choose to either:
1. Write `CHANGELOG entry: null`
2. Label with `no-changelog`

If this PR is End-User-Facing, please write a short User-Facing
description in the past tense like:
`CHANGELOG entry: Added a new tab for users to see their NFTs`
`CHANGELOG entry: Fixed a bug that was causing some NFTs to flicker`

(This helps the Release Engineer do their job more quickly and
accurately)
-->

CHANGELOG entry: added payment token preselection in mUSD conversion
flow

## **Related issues**

Fixes: [MUSD-108: Bring back mUSD confirmations
enhancements](https://consensyssoftware.atlassian.net/browse/MUSD-108)

## **Manual testing steps**

```gherkin
Feature: mUSD Conversion

  Scenario: Payment Token Preselection
    Given user has non-zero asset balance

    When user user clicks "Convert" CTA next to supported token (e.g. USDC)
    Then user is redirected to the mUSD conversion confirmation page with the correct asset preselected as the payment token.
```

## **Screenshots/Recordings**

<!-- If applicable, add screenshots and/or recordings to visualize the
before and after of your change. -->

### **Before**

<!-- [screenshots/recordings] -->
Asset is not preselected
### **After**

<!-- [screenshots/recordings] -->


https://github.com/user-attachments/assets/fc056a92-2f26-425f-84aa-5e1623a37b88

## **Pre-merge author checklist**

- [x] I’ve followed [MetaMask Contributor
Docs](https://github.com/MetaMask/contributor-docs) and [MetaMask Mobile
Coding
Standards](https://github.com/MetaMask/metamask-mobile/blob/main/.github/guidelines/CODING_GUIDELINES.md).
- [x] I've completed the PR template to the best of my ability
- [x] I’ve included tests if applicable
- [x] I’ve documented my code using [JSDoc](https://jsdoc.app/) format
if applicable
- [x] I’ve applied the right labels on the PR (see [labeling
guidelines](https://github.com/MetaMask/metamask-mobile/blob/main/.github/guidelines/LABELING_GUIDELINES.md)).
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.

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> Adds preferred payment token selection to
`useAutomaticTransactionPayToken` and wires mUSD conversion to preselect
it; updates tests and docs.
> 
> - **Payments/Confirmations**:
>   - **`useAutomaticTransactionPayToken`**:
>     - Adds `SetPayTokenRequest` and optional `preferredToken` param.
> - Selection prefers `preferredToken` when available; ignores it for
hardware wallets; otherwise falls back to first available or target
required token.
> - **Tests**: Extend to cover preferred token availability, hardware
wallet fallback, empty tokens, and non-matching cases.
> - **mUSD Conversion Flow**:
> - **`musd-conversion-info` → `CustomAmountInfo`**: Pass
`preferredPaymentToken` param down as `preferredToken` to the hook.
> - **`useMusdConversion`**: JSDoc example updated; clarifies async gas
estimation; navigates with `preferredPaymentToken` and `outputChainId`.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
0c3c367. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: Matt561

app/components/UI/Earn/hooks/useMusdConversion.ts

@@ -49,10 +49,9 @@ export interface MusdConversionConfig {
  * await initiateConversion({
  *   outputChainId: CHAIN_IDS.MAINNET,
  *   preferredPaymentToken: {
- *     address: USDC_ADDRESS_ARBITRUM,
+ *     address: USDC_ADDRESS_MAINNET,
  *     chainId: CHAIN_IDS.MAINNET,
  *   },
- *   allowedPaymentTokens: musdConversionPaymentTokensAllowlist,
  *   navigationStack: Routes.EARN.ROOT,
  * });
  */
@@ -67,8 +66,8 @@ export const useMusdConversion = () => {
   const selectedAddress = selectedAccount?.address;
 
   /**
-   * Creates a placeholder transaction and navigating to confirmation.
-   * Navigation happens immediately, then transaction creation happens in background.
+   * Creates a placeholder transaction and navigates to confirmation.
+   * Navigation happens immediately. Transaction creation and gas estimation happen asynchronously.
    */
   const initiateConversion = useCallback(
     async (config: MusdConversionConfig): Promise<string> => {

app/components/Views/confirmations/components/info/custom-amount-info/custom-amount-info.tsx

@@ -14,7 +14,10 @@ import styleSheet from './custom-amount-info.styles';
 import { useTransactionCustomAmount } from '../../../hooks/transactions/useTransactionCustomAmount';
 import { useTransactionCustomAmountAlerts } from '../../../hooks/transactions/useTransactionCustomAmountAlerts';
 import useClearConfirmationOnBackSwipe from '../../../hooks/ui/useClearConfirmationOnBackSwipe';
-import { useAutomaticTransactionPayToken } from '../../../hooks/pay/useAutomaticTransactionPayToken';
+import {
+  SetPayTokenRequest,
+  useAutomaticTransactionPayToken,
+} from '../../../hooks/pay/useAutomaticTransactionPayToken';
 import { AlertMessage } from '../../alerts/alert-message';
 import {
   CustomAmount,
@@ -55,12 +58,16 @@ export interface CustomAmountInfoProps {
   currency?: string;
   disablePay?: boolean;
   hasMax?: boolean;
+  preferredToken?: SetPayTokenRequest;
 }
 
 export const CustomAmountInfo: React.FC<CustomAmountInfoProps> = memo(
-  ({ children, currency, disablePay, hasMax }) => {
+  ({ children, currency, disablePay, hasMax, preferredToken }) => {
     useClearConfirmationOnBackSwipe();
-    useAutomaticTransactionPayToken({ disable: disablePay });
+    useAutomaticTransactionPayToken({
+      disable: disablePay,
+      preferredToken,
+    });
     useTransactionPayMetrics();
 
     const { styles } = useStyles(styleSheet, {});

app/components/Views/confirmations/components/info/musd-conversion-info/musd-conversion-info.tsx

@@ -8,15 +8,14 @@ import {
 } from '../../../../../UI/Earn/constants/musd';
 import { useAddToken } from '../../../hooks/tokens/useAddToken';
 import { MusdConversionConfig } from '../../../../../UI/Earn/hooks/useMusdConversion';
-import { CHAIN_IDS } from '@metamask/transaction-controller';
 import { useParams } from '../../../../../../util/navigation/navUtils';
+import { CHAIN_IDS } from '@metamask/transaction-controller';
 
 export const MusdConversionInfo = () => {
-  // TEMP: Will be brought back in subsequent PR.
-  // const preferredPaymentToken = route.params?.preferredPaymentToken;
-  const { outputChainId } = useParams<MusdConversionConfig>({
-    outputChainId: CHAIN_IDS.MAINNET,
-  });
+  const { outputChainId, preferredPaymentToken } =
+    useParams<MusdConversionConfig>({
+      outputChainId: CHAIN_IDS.MAINNET,
+    });
 
   useNavbar(strings('earn.musd_conversion.earn_rewards_with'));
 
@@ -38,5 +37,5 @@ export const MusdConversionInfo = () => {
     tokenAddress: tokenToAddAddress,
   });
 
-  return <CustomAmountInfo />;
+  return <CustomAmountInfo preferredToken={preferredPaymentToken} />;
 };

app/components/Views/confirmations/hooks/pay/useAutomaticTransactionPayToken.test.ts

@@ -1,6 +1,9 @@
 import { merge } from 'lodash';
 import { renderHookWithProvider } from '../../../../../util/test/renderWithProvider';
-import { useAutomaticTransactionPayToken } from './useAutomaticTransactionPayToken';
+import {
+  useAutomaticTransactionPayToken,
+  SetPayTokenRequest,
+} from './useAutomaticTransactionPayToken';
 import { useTransactionPayToken } from './useTransactionPayToken';
 import { simpleSendTransactionControllerMock } from '../../__mocks__/controllers/transaction-controller-mock';
 import { transactionApprovalControllerMock } from '../../__mocks__/controllers/approval-controller-mock';
@@ -21,8 +24,11 @@ jest.mock('./useTransactionPayAvailableTokens');
 const TOKEN_ADDRESS_1_MOCK = '0x1234567890abcdef1234567890abcdef12345678';
 const TOKEN_ADDRESS_2_MOCK = '0xabcdefabcdefabcdefabcdefabcdefabcdefabcd';
 const TOKEN_ADDRESS_3_MOCK = '0xabc1234567890abcdef1234567890abcdef12345678';
+const PREFERRED_TOKEN_ADDRESS_MOCK =
+  '0x9999999999999999999999999999999999999999';
 const CHAIN_ID_1_MOCK = '0x1';
 const CHAIN_ID_2_MOCK = '0x2';
+const PREFERRED_CHAIN_ID_MOCK = '0x3';
 
 const STATE_MOCK = merge(
   {},
@@ -43,9 +49,15 @@ const STATE_MOCK = merge(
   },
 );
 
-function runHook({ disable = false } = {}) {
+function runHook({
+  disable = false,
+  preferredToken,
+}: {
+  disable?: boolean;
+  preferredToken?: SetPayTokenRequest;
+} = {}) {
   return renderHookWithProvider(
-    () => useAutomaticTransactionPayToken({ disable }),
+    () => useAutomaticTransactionPayToken({ disable, preferredToken }),
     {
       state: STATE_MOCK,
     },
@@ -166,4 +178,101 @@ describe('useAutomaticTransactionPayToken', () => {
 
     expect(setPayTokenMock).not.toHaveBeenCalled();
   });
+
+  it('selects preferred payment token when provided with available tokens', () => {
+    useTransactionPayAvailableTokensMock.mockReturnValue([
+      {
+        address: TOKEN_ADDRESS_1_MOCK,
+        chainId: CHAIN_ID_1_MOCK,
+      },
+      {
+        address: PREFERRED_TOKEN_ADDRESS_MOCK,
+        chainId: PREFERRED_CHAIN_ID_MOCK,
+      },
+      {
+        address: TOKEN_ADDRESS_2_MOCK,
+        chainId: CHAIN_ID_2_MOCK,
+      },
+    ] as AssetType[]);
+
+    runHook({
+      preferredToken: {
+        address: PREFERRED_TOKEN_ADDRESS_MOCK as Hex,
+        chainId: PREFERRED_CHAIN_ID_MOCK as Hex,
+      },
+    });
+
+    expect(setPayTokenMock).toHaveBeenCalledWith({
+      address: PREFERRED_TOKEN_ADDRESS_MOCK,
+      chainId: PREFERRED_CHAIN_ID_MOCK,
+    });
+  });
+
+  it('ignores preferred payment token when using hardware wallet', () => {
+    useTransactionPayAvailableTokensMock.mockReturnValue([
+      {
+        address: TOKEN_ADDRESS_2_MOCK,
+        chainId: CHAIN_ID_2_MOCK,
+      },
+      {
+        address: TOKEN_ADDRESS_3_MOCK,
+        chainId: CHAIN_ID_1_MOCK,
+      },
+    ] as AssetType[]);
+
+    isHardwareAccountMock.mockReturnValue(true);
+
+    runHook({
+      preferredToken: {
+        address: PREFERRED_TOKEN_ADDRESS_MOCK as Hex,
+        chainId: PREFERRED_CHAIN_ID_MOCK as Hex,
+      },
+    });
+
+    expect(setPayTokenMock).toHaveBeenCalledWith({
+      address: TOKEN_ADDRESS_1_MOCK,
+      chainId: CHAIN_ID_1_MOCK,
+    });
+  });
+
+  it('selects target token when preferred payment token provided but no tokens available', () => {
+    useTransactionPayAvailableTokensMock.mockReturnValue([] as AssetType[]);
+
+    runHook({
+      preferredToken: {
+        address: PREFERRED_TOKEN_ADDRESS_MOCK as Hex,
+        chainId: PREFERRED_CHAIN_ID_MOCK as Hex,
+      },
+    });
+
+    expect(setPayTokenMock).toHaveBeenCalledWith({
+      address: TOKEN_ADDRESS_1_MOCK,
+      chainId: CHAIN_ID_1_MOCK,
+    });
+  });
+
+  it('selects first available token when preferred token not in available tokens', () => {
+    useTransactionPayAvailableTokensMock.mockReturnValue([
+      {
+        address: TOKEN_ADDRESS_1_MOCK,
+        chainId: CHAIN_ID_1_MOCK,
+      },
+      {
+        address: TOKEN_ADDRESS_2_MOCK,
+        chainId: CHAIN_ID_2_MOCK,
+      },
+    ] as AssetType[]);
+
+    runHook({
+      preferredToken: {
+        address: PREFERRED_TOKEN_ADDRESS_MOCK as Hex,
+        chainId: PREFERRED_CHAIN_ID_MOCK as Hex,
+      },
+    });
+
+    expect(setPayTokenMock).toHaveBeenCalledWith({
+      address: TOKEN_ADDRESS_1_MOCK,
+      chainId: CHAIN_ID_1_MOCK,
+    });
+  });
 });

app/components/Views/confirmations/hooks/pay/useAutomaticTransactionPayToken.ts

@@ -9,12 +9,19 @@ import { useTransactionPayRequiredTokens } from './useTransactionPayData';
 import { useTransactionPayAvailableTokens } from './useTransactionPayAvailableTokens';
 import { AssetType } from '../../types/token';
 
+export interface SetPayTokenRequest {
+  address: Hex;
+  chainId: Hex;
+}
+
 const log = createProjectLogger('transaction-pay');
 
 export function useAutomaticTransactionPayToken({
   disable = false,
+  preferredToken,
 }: {
   disable?: boolean;
+  preferredToken?: SetPayTokenRequest;
 } = {}) {
   const isUpdated = useRef(false);
   const { setPayToken } = useTransactionPayToken();
@@ -52,6 +59,7 @@ export function useAutomaticTransactionPayToken({
       isHardwareWallet,
       targetToken,
       tokens: tokensWithBalance,
+      preferredToken,
     });
 
     if (!automaticToken) {
@@ -70,6 +78,7 @@ export function useAutomaticTransactionPayToken({
   }, [
     disable,
     isHardwareWallet,
+    preferredToken,
     requiredTokens,
     setPayToken,
     targetToken,
@@ -79,10 +88,12 @@ export function useAutomaticTransactionPayToken({
 
 function getBestToken({
   isHardwareWallet,
+  preferredToken,
   targetToken,
   tokens,
 }: {
   isHardwareWallet: boolean;
+  preferredToken?: SetPayTokenRequest;
   targetToken?: { address: Hex; chainId: Hex };
   tokens: AssetType[];
 }): { address: Hex; chainId: Hex } | undefined {
@@ -97,6 +108,18 @@ function getBestToken({
     return targetTokenFallback;
   }
 
+  if (preferredToken) {
+    const preferredTokenAvailable = tokens.some(
+      (token) =>
+        token.address.toLowerCase() === preferredToken.address.toLowerCase() &&
+        token.chainId?.toLowerCase() === preferredToken.chainId.toLowerCase(),
+    );
+
+    if (preferredTokenAvailable) {
+      return preferredToken;
+    }
+  }
+
   if (tokens?.length) {
     return {
       address: tokens[0].address as Hex,