chore: update cta to respect buy regions and route correctly per chain (MetaMask#24048)

## **Description**

Fixed an issue where the MUSD CTA was incorrectly displaying when a
single unsupported chain (like BSC) was selected in the network filter.

The bug occurred because when a non-buyable chain was selected, the code
was still showing the CTA if mUSD was buyable on *any* chain (e.g.,
Mainnet or Linea), rather than hiding it completely. This was confusing
for users since they couldn't actually buy mUSD on the selected chain.

**Changes:**
- When a non-buyable chain is selected (BSC, Polygon, Arbitrum, etc.),
the CTA now correctly hides
- When a buyable chain is selected but mUSD is not available in the
user's region for that specific chain, the CTA now correctly hides

## **Changelog**

CHANGELOG entry: Fixed mUSD CTA incorrectly appearing on unsupported
chains like BSC

## **Related issues**

Fixes: https://consensyssoftware.atlassian.net/browse/MUSD-124

## **Manual testing steps**

```gherkin
Feature: MUSD CTA visibility

  Scenario: user selects BSC network
    Given user is on the token list view
    And user does not have any MUSD balance
    And user does not have any token balance

    When user selects BSC as the only network filter
    Then the MUSD CTA should not be displayed

  Scenario: user selects Linea network
    Given user is on the token list view
    And user does not have any MUSD balance
    And user does not have any token balance
    And mUSD is buyable in user's region on Linea

    When user selects Linea as the only network filter
    Then the MUSD CTA should be displayed with network icon

  Scenario: user selects Mainnet network
    Given user is on the token list view
    And user does not have any MUSD balance
    And user does not have any token balance
    And mUSD is buyable in user's region on Mainnet

    When user selects Mainnet as the only network filter
    Then the MUSD CTA should be displayed with network icon

  Scenario: user selects all networks
    Given user is on the token list view
    And user does not have any MUSD balance
    And user does not have any token balance
    And mUSD is buyable in user's region

    When user has all networks selected
    Then the MUSD CTA should be displayed without network icon

  Scenario: user selects Linea network
    Given user is on the token list view
    And user does not have any MUSD balance
    And user does has token balance

    When user selects any network filter
    Then the MUSD CTA should be displayed with network icon
    Then the MUSD CTA should direct to BuyWithToken component on the chain of token being converted (soon to be constrained to that chain specifically in. separate pr)
```

## **Screenshots/Recordings**

### **Before**

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

### **After**


https://github.com/user-attachments/assets/45040e69-f737-4112-baad-36f0390c3453

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

## **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]
> Updates the mUSD CTA to show/hide and route per selected chain and
regional availability, with a new feature flag, network badge, and
supporting hooks/tests.
> 
> - **Earn UI – mUSD CTA**:
> - Integrates `useMusdCtaVisibility` to conditionally render CTA; hides
on non-buyable/unsupported chains and when mUSD isn’t buyable in-region.
> - Shows network badge for single supported selections using
`BadgeWrapper` and `getNetworkImageSource`; aligns avatar layout.
> - Adjusts buy flow to use `selectedChainId` (fallback to
`MUSD_CONVERSION_DEFAULT_CHAIN_ID`).
> - **Hooks/Logic**:
>   - Adds `useHasMusdBalance` to detect mUSD balances across chains.
> - Adds `useMusdCtaVisibility` to compute `shouldShowCta`,
`showNetworkIcon`, and `selectedChainId` based on feature flag, selected
networks, ramp token availability, and balances.
> - Introduces `MUSD_BUYABLE_CHAIN_IDS` (excludes BSC) and uses
`MUSD_TOKEN_ASSET_ID_BY_CHAIN` for routing.
> - **Feature Flags/Config**:
> - Adds env flag `MM_MUSD_CTA_ENABLED` and selector
`selectIsMusdCtaEnabledFlag`.
> - **Tests**:
> - Extensive new tests for `useHasMusdBalance`, `useMusdCtaVisibility`,
and updated CTA tests for visibility, routing, and network badge
behavior.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
cd04745. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: nickewansmith

.js.env.example

@@ -111,7 +111,7 @@ export MM_MUSD_CONVERSION_FLOW_ENABLED="false"
 # IMPORTANT: Must use SINGLE QUOTES to preserve JSON format
 # Example: MM_MUSD_CONVERTIBLE_TOKENS_ALLOWLIST='{"0x1":["USDC","USDT"],"0xa4b1":["USDC","DAI"]}'
 export MM_MUSD_CONVERTIBLE_TOKENS_ALLOWLIST=''
-
+export MM_MUSD_CTA_ENABLED="false"
 # Activates remote feature flag override mode.
 # Remote feature flag values won't be updated,
 # and selectors should return their fallback values

app/components/UI/Earn/components/Musd/MusdConversionAssetListCta/MusdConversionAssetListCta.styles.ts

@@ -11,11 +11,15 @@ const styleSheet = () =>
     assetInfo: {
       flexDirection: 'row',
       gap: 20,
+      alignItems: 'center',
     },
     button: {
       alignSelf: 'center',
       height: 32,
     },
+    badge: {
+      alignSelf: 'center',
+    },
   });
 
 export default styleSheet;

app/components/UI/Earn/components/Musd/MusdConversionAssetListCta/MusdConversionAssetListCta.test.tsx

@@ -4,6 +4,7 @@ import { Hex } from '@metamask/utils';
 
 jest.mock('../../../hooks/useMusdConversionTokens');
 jest.mock('../../../hooks/useMusdConversion');
+jest.mock('../../../hooks/useMusdCtaVisibility');
 jest.mock('../../../../Ramp/hooks/useRampNavigation');
 jest.mock('../../../../../../util/Logger');
 
@@ -22,6 +23,7 @@ import renderWithProvider from '../../../../../../util/test/renderWithProvider';
 import MusdConversionAssetListCta from '.';
 import { useMusdConversionTokens } from '../../../hooks/useMusdConversionTokens';
 import { useMusdConversion } from '../../../hooks/useMusdConversion';
+import { useMusdCtaVisibility } from '../../../hooks/useMusdCtaVisibility';
 import { useRampNavigation } from '../../../../Ramp/hooks/useRampNavigation';
 import {
   MUSD_CONVERSION_DEFAULT_CHAIN_ID,
@@ -30,6 +32,8 @@ import {
 import { EARN_TEST_IDS } from '../../../constants/testIds';
 import initialRootState from '../../../../../../util/test/initial-root-state';
 import Logger from '../../../../../../util/Logger';
+import { CHAIN_IDS } from '@metamask/transaction-controller';
+import { BADGE_WRAPPER_BADGE_TEST_ID } from '../../../../../../component-library/components/Badges/BadgeWrapper/BadgeWrapper.constants';
 
 const mockToken = {
   address: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
@@ -68,6 +72,15 @@ describe('MusdConversionAssetListCta', () => {
       error: null,
       hasSeenConversionEducationScreen: true,
     });
+
+    // Default mock for visibility - show CTA without network icon
+    (
+      useMusdCtaVisibility as jest.MockedFunction<typeof useMusdCtaVisibility>
+    ).mockReturnValue({
+      shouldShowCta: true,
+      showNetworkIcon: false,
+      selectedChainId: null,
+    });
   });
 
   afterEach(() => {
@@ -373,4 +386,152 @@ describe('MusdConversionAssetListCta', () => {
       });
     });
   });
+
+  describe('visibility behavior', () => {
+    beforeEach(() => {
+      (
+        useMusdConversionTokens as jest.MockedFunction<
+          typeof useMusdConversionTokens
+        >
+      ).mockReturnValue({
+        tokens: [],
+        tokenFilter: jest.fn(),
+        isConversionToken: jest.fn(),
+        isMusdSupportedOnChain: jest.fn().mockReturnValue(true),
+        getMusdOutputChainId: jest.fn((chainId) => (chainId ?? '0x1') as Hex),
+      });
+    });
+
+    it('renders null when shouldShowCta is false', () => {
+      (
+        useMusdCtaVisibility as jest.MockedFunction<typeof useMusdCtaVisibility>
+      ).mockReturnValue({
+        shouldShowCta: false,
+        showNetworkIcon: false,
+        selectedChainId: null,
+      });
+
+      const { queryByTestId } = renderWithProvider(
+        <MusdConversionAssetListCta />,
+        { state: initialRootState },
+      );
+
+      expect(
+        queryByTestId(EARN_TEST_IDS.MUSD.ASSET_LIST_CONVERSION_CTA),
+      ).toBeNull();
+    });
+
+    it('renders component when shouldShowCta is true', () => {
+      (
+        useMusdCtaVisibility as jest.MockedFunction<typeof useMusdCtaVisibility>
+      ).mockReturnValue({
+        shouldShowCta: true,
+        showNetworkIcon: false,
+        selectedChainId: null,
+      });
+
+      const { getByTestId } = renderWithProvider(
+        <MusdConversionAssetListCta />,
+        { state: initialRootState },
+      );
+
+      expect(
+        getByTestId(EARN_TEST_IDS.MUSD.ASSET_LIST_CONVERSION_CTA),
+      ).toBeOnTheScreen();
+    });
+  });
+
+  describe('network badge', () => {
+    beforeEach(() => {
+      (
+        useMusdConversionTokens as jest.MockedFunction<
+          typeof useMusdConversionTokens
+        >
+      ).mockReturnValue({
+        tokens: [],
+        tokenFilter: jest.fn(),
+        isConversionToken: jest.fn(),
+        isMusdSupportedOnChain: jest.fn().mockReturnValue(true),
+        getMusdOutputChainId: jest.fn((chainId) => (chainId ?? '0x1') as Hex),
+      });
+    });
+
+    it('renders without network badge when showNetworkIcon is false', () => {
+      (
+        useMusdCtaVisibility as jest.MockedFunction<typeof useMusdCtaVisibility>
+      ).mockReturnValue({
+        shouldShowCta: true,
+        showNetworkIcon: false,
+        selectedChainId: null,
+      });
+
+      const { getByTestId, queryByTestId } = renderWithProvider(
+        <MusdConversionAssetListCta />,
+        { state: initialRootState },
+      );
+
+      expect(
+        getByTestId(EARN_TEST_IDS.MUSD.ASSET_LIST_CONVERSION_CTA),
+      ).toBeOnTheScreen();
+      // Badge wrapper is not rendered when showNetworkIcon is false
+      expect(queryByTestId(BADGE_WRAPPER_BADGE_TEST_ID)).toBeNull();
+    });
+
+    it('renders with network badge when showNetworkIcon is true and mainnet selected', () => {
+      (
+        useMusdCtaVisibility as jest.MockedFunction<typeof useMusdCtaVisibility>
+      ).mockReturnValue({
+        shouldShowCta: true,
+        showNetworkIcon: true,
+        selectedChainId: CHAIN_IDS.MAINNET,
+      });
+
+      const { getByTestId } = renderWithProvider(
+        <MusdConversionAssetListCta />,
+        { state: initialRootState },
+      );
+
+      expect(
+        getByTestId(EARN_TEST_IDS.MUSD.ASSET_LIST_CONVERSION_CTA),
+      ).toBeOnTheScreen();
+    });
+
+    it('renders with network badge when showNetworkIcon is true and Linea selected', () => {
+      (
+        useMusdCtaVisibility as jest.MockedFunction<typeof useMusdCtaVisibility>
+      ).mockReturnValue({
+        shouldShowCta: true,
+        showNetworkIcon: true,
+        selectedChainId: CHAIN_IDS.LINEA_MAINNET,
+      });
+
+      const { getByTestId } = renderWithProvider(
+        <MusdConversionAssetListCta />,
+        { state: initialRootState },
+      );
+
+      expect(
+        getByTestId(EARN_TEST_IDS.MUSD.ASSET_LIST_CONVERSION_CTA),
+      ).toBeOnTheScreen();
+    });
+
+    it('renders with network badge when showNetworkIcon is true and BSC selected', () => {
+      (
+        useMusdCtaVisibility as jest.MockedFunction<typeof useMusdCtaVisibility>
+      ).mockReturnValue({
+        shouldShowCta: true,
+        showNetworkIcon: true,
+        selectedChainId: CHAIN_IDS.BSC,
+      });
+
+      const { getByTestId } = renderWithProvider(
+        <MusdConversionAssetListCta />,
+        { state: initialRootState },
+      );
+
+      expect(
+        getByTestId(EARN_TEST_IDS.MUSD.ASSET_LIST_CONVERSION_CTA),
+      ).toBeOnTheScreen();
+    });
+  });
 });

app/components/UI/Earn/components/Musd/MusdConversionAssetListCta/index.tsx

@@ -24,9 +24,17 @@ import Logger from '../../../../../../util/Logger';
 import { useStyles } from '../../../../../hooks/useStyles';
 import { useMusdConversionTokens } from '../../../hooks/useMusdConversionTokens';
 import { useMusdConversion } from '../../../hooks/useMusdConversion';
+import { useMusdCtaVisibility } from '../../../hooks/useMusdCtaVisibility';
 import AvatarToken from '../../../../../../component-library/components/Avatars/Avatar/variants/AvatarToken';
 import { AvatarSize } from '../../../../../../component-library/components/Avatars/Avatar';
 import { toChecksumAddress } from '../../../../../../util/address';
+import Badge, {
+  BadgeVariant,
+} from '../../../../../../component-library/components/Badges/Badge';
+import BadgeWrapper, {
+  BadgePosition,
+} from '../../../../../../component-library/components/Badges/BadgeWrapper';
+import { getNetworkImageSource } from '../../../../../../util/networks';
 
 const MusdConversionAssetListCta = () => {
   const { styles } = useStyles(styleSheet, {});
@@ -37,6 +45,9 @@ const MusdConversionAssetListCta = () => {
 
   const { initiateConversion } = useMusdConversion();
 
+  const { shouldShowCta, showNetworkIcon, selectedChainId } =
+    useMusdCtaVisibility();
+
   const canConvert = useMemo(
     () => Boolean(tokens.length > 0 && tokens?.[0]?.chainId !== undefined),
     [tokens],
@@ -54,7 +65,10 @@ const MusdConversionAssetListCta = () => {
     // Redirect users to deposit flow if they don't have any stablecoins to convert.
     if (!canConvert) {
       const rampIntent: RampIntent = {
-        assetId: MUSD_TOKEN_ASSET_ID_BY_CHAIN[MUSD_CONVERSION_DEFAULT_CHAIN_ID],
+        assetId:
+          MUSD_TOKEN_ASSET_ID_BY_CHAIN[
+            selectedChainId || MUSD_CONVERSION_DEFAULT_CHAIN_ID
+          ],
       };
       goToBuy(rampIntent);
       return;
@@ -84,17 +98,43 @@ const MusdConversionAssetListCta = () => {
     }
   };
 
+  // Don't render if visibility conditions are not met
+  if (!shouldShowCta) {
+    return null;
+  }
+
+  const renderTokenAvatar = () => (
+    <AvatarToken
+      name={MUSD_TOKEN.symbol}
+      imageSource={MUSD_TOKEN.imageSource}
+      size={AvatarSize.Lg}
+    />
+  );
+
   return (
     <View
       style={styles.container}
       testID={EARN_TEST_IDS.MUSD.ASSET_LIST_CONVERSION_CTA}
     >
       <View style={styles.assetInfo}>
-        <AvatarToken
-          name={MUSD_TOKEN.symbol}
-          imageSource={MUSD_TOKEN.imageSource}
-          size={AvatarSize.Lg}
-        />
+        {showNetworkIcon && selectedChainId ? (
+          <BadgeWrapper
+            style={styles.badge}
+            badgePosition={BadgePosition.BottomRight}
+            badgeElement={
+              <Badge
+                variant={BadgeVariant.Network}
+                imageSource={getNetworkImageSource({
+                  chainId: selectedChainId,
+                })}
+              />
+            }
+          >
+            {renderTokenAvatar()}
+          </BadgeWrapper>
+        ) : (
+          renderTokenAvatar()
+        )}
         <View>
           <Text variant={TextVariant.BodyMDMedium} color={TextColor.Default}>
             MetaMask USD

app/components/UI/Earn/constants/musd.ts

@@ -22,6 +22,16 @@ export const MUSD_TOKEN_ADDRESS_BY_CHAIN: Record<Hex, Hex> = {
   [CHAIN_IDS.BSC]: '0xaca92e438df0b2401ff60da7e4337b687a2435da',
 };
 
+/**
+ * Chains where mUSD CTA should show (buy routes available).
+ * BSC is excluded as buy routes are not yet available.
+ */
+export const MUSD_BUYABLE_CHAIN_IDS: Hex[] = [
+  CHAIN_IDS.MAINNET,
+  CHAIN_IDS.LINEA_MAINNET,
+  // CHAIN_IDS.BSC, // TODO: Uncomment once buy routes are available
+];
+
 export const MUSD_TOKEN_ASSET_ID_BY_CHAIN: Record<Hex, string> = {
   [CHAIN_IDS.MAINNET]:
     'eip155:1/erc20:0xacA92E438df0B2401fF60dA7E4337B687a2435DA',