feat: Graceful Perps icon fallback (MetaMask#24340)

## **Description**

This PR implements a graceful degradation pattern for Perps asset icons,
allowing the app to first attempt loading icons from MetaMask's
contract-metadata repository and automatically fall back to
HyperLiquid's CDN if the primary source fails.

We want to host curated Perps icons in our own contract-metadata repo
for quality control. However, not all icons may be uploaded yet, and we
need a reliable fallback. This approach allows gradual migration while
maintaining full icon coverage

Solution:
1. Re-added `METAMASK_PERPS_ICONS_BASE_URL` constant pointing to
contract-metadata repo
2. Created `getAssetIconUrls()` function that returns both primary and
fallback URLs
3. Updated PerpsTokenLogo component to try primary URL first, then
fallback on error
4. HIP-3 assets use the hip3:dex_SYMBOL.svg format for MetaMask URLs

In cases where both primary and fallback urls fail, we fallback to the
default two letter icon.

## **Changelog**

CHANGELOG entry: Perps icon fallback url mechanism

## **Related issues**

Fixes: https://consensyssoftware.atlassian.net/browse/TAT-2329

## **Manual testing steps**

```gherkin
Feature: Perps Token Icon Fallback

  Scenario: User views Perps market list with icons from MetaMask repo
    Given the user has opened the Perps tab
    When the market list loads
    Then icons load from MetaMask contract-metadata URL first
    And if MetaMask URL fails, icons fall back to HyperLiquid URL
    And if both URLs fail, a 2-letter text fallback is displayed

  Scenario: User views HIP-3 asset icons
    Given the user has opened a HIP-3 market (e.g., xyz:AAPL)
    When the icon loads
    Then the primary URL uses format hip3:xyz_AAPL.svg
    And the fallback URL uses format xyz:AAPL.svg
```

## **Screenshots/Recordings**

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

### **Before**

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

### **After**

<!-- [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]
> Implements a two-source icon strategy for Perps, prioritizing
MetaMask’s `contract-metadata` with automatic fallback to HyperLiquid,
plus comprehensive tests.
> 
> - Adds `METAMASK_PERPS_ICONS_BASE_URL` and new `getAssetIconUrls()` in
`marketUtils` to return `{ primary, fallback }` URLs (supports HIP-3
`hip3:dex_SYMBOL.svg` and `k`-prefix handling)
> - Updates `PerpsTokenLogo` to try `primary` first, switch to
`fallback` on `onError`, reset to primary on symbol change, and show
2-letter text fallback if both fail; adjusts `key/recyclingKey` to
reflect URL state
> - Extends tests in `PerpsTokenLogo.test.tsx` and `marketUtils.test.ts`
to cover URL selection, fallback flow, HIP-3 formatting, and casing
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
03ee9c9. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: gambinish

app/components/UI/Perps/components/PerpsTokenLogo/PerpsTokenLogo.test.tsx

@@ -80,14 +80,14 @@ describe('PerpsTokenLogo', () => {
     // Empty symbol results in empty fallback text
   });
 
-  it('renders Image component with correct URI', () => {
+  it('renders Image component with primary MetaMask URL initially', () => {
     const { UNSAFE_getByType } = render(
       <PerpsTokenLogo symbol="BTC" testID="with-image" />,
     );
 
     const image = UNSAFE_getByType(Image);
     expect(image.props.source.uri).toBe(
-      'https://app.hyperliquid.xyz/coins/BTC.svg',
+      'https://raw.githubusercontent.com/MetaMask/contract-metadata/master/icons/eip155:999/BTC.svg',
     );
     expect(image.props.style).toEqual(
       expect.objectContaining({
@@ -97,23 +97,55 @@ describe('PerpsTokenLogo', () => {
     );
   });
 
-  it('handles image error by showing text fallback', async () => {
-    // Arrange
-    const { UNSAFE_getByType, getByTestId } = render(
+  it('switches to fallback HyperLiquid URL when primary fails', async () => {
+    const { UNSAFE_getByType } = render(
+      <PerpsTokenLogo symbol="BTC" testID="fallback-test" />,
+    );
+
+    const image = UNSAFE_getByType(Image);
+
+    // Verify initial URL is primary (MetaMask)
+    expect(image.props.source.uri).toContain('contract-metadata');
+
+    // Simulate primary URL error
+    await act(async () => {
+      image.props.onError();
+    });
+
+    // Get updated image after error
+    const updatedImage = UNSAFE_getByType(Image);
+
+    // Verify fallback URL is now used (HyperLiquid)
+    expect(updatedImage.props.source.uri).toBe(
+      'https://app.hyperliquid.xyz/coins/BTC.svg',
+    );
+  });
+
+  it('shows text fallback when both primary and fallback URLs fail', async () => {
+    const { UNSAFE_getByType, UNSAFE_queryByType, getByTestId } = render(
       <PerpsTokenLogo symbol="FAIL" testID="image-error" />,
     );
 
     const image = UNSAFE_getByType(Image);
 
-    // Act - Simulate image error
+    // First error - switches to fallback URL
     await act(async () => {
       image.props.onError();
     });
 
-    // Assert - Should show text fallback after error
+    // Get image with fallback URL
+    const fallbackImage = UNSAFE_getByType(Image);
+
+    // Second error - both URLs failed, show text fallback
+    await act(async () => {
+      fallbackImage.props.onError();
+    });
+
+    // Verify text fallback is shown
     const container = getByTestId('image-error');
     expect(container).toBeTruthy();
-    // Text fallback should show "FA" for "FAIL"
+    // Image component no longer rendered, text fallback shown instead
+    expect(UNSAFE_queryByType(Image)).toBeNull();
   });
 
   it('correctly applies size prop to container', () => {
@@ -180,4 +212,30 @@ describe('PerpsTokenLogo', () => {
     const image = UNSAFE_getByType(Image);
     expect(image.props.source.uri).toContain('BTC.svg');
   });
+
+  it('resets to primary URL when symbol changes', async () => {
+    const { UNSAFE_getByType, rerender } = render(
+      <PerpsTokenLogo symbol="BTC" testID="symbol-change" />,
+    );
+
+    const image = UNSAFE_getByType(Image);
+
+    // Trigger error to switch to fallback
+    await act(async () => {
+      image.props.onError();
+    });
+
+    // Verify fallback is being used
+    expect(UNSAFE_getByType(Image).props.source.uri).toContain(
+      'app.hyperliquid.xyz',
+    );
+
+    // Change symbol
+    rerender(<PerpsTokenLogo symbol="ETH" testID="symbol-change" />);
+
+    // Verify primary URL is used for new symbol
+    const newImage = UNSAFE_getByType(Image);
+    expect(newImage.props.source.uri).toContain('contract-metadata');
+    expect(newImage.props.source.uri).toContain('ETH.svg');
+  });
 });

app/components/UI/Perps/components/PerpsTokenLogo/PerpsTokenLogo.tsx

@@ -1,12 +1,12 @@
 import { Image } from 'expo-image';
-import React, { memo, useMemo } from 'react';
+import React, { memo, useCallback, useEffect, useMemo, useState } from 'react';
 import { ActivityIndicator, View } from 'react-native';
 import Text, {
   TextVariant,
 } from '../../../../../component-library/components/Texts/Text';
 import { useTokenLogo } from '../../../../hooks/useTokenLogo';
 import {
-  getAssetIconUrl,
+  getAssetIconUrls,
   getPerpsDisplaySymbol,
 } from '../../utils/marketUtils';
 import {
@@ -23,12 +23,27 @@ const PerpsTokenLogo: React.FC<PerpsTokenLogoProps> = ({
   testID,
   recyclingKey,
 }) => {
-  // SVG URL - expo-image handles SVG rendering properly
-  const imageUri = useMemo(() => {
+  // Track if we should use fallback URL (after primary fails)
+  const [useFallbackUrl, setUseFallbackUrl] = useState(false);
+
+  // Get both primary (MetaMask) and fallback (HyperLiquid) URLs
+  const iconUrls = useMemo(() => {
     if (!symbol) return null;
-    return getAssetIconUrl(symbol, K_PREFIX_ASSETS);
+    return getAssetIconUrls(symbol, K_PREFIX_ASSETS);
+  }, [symbol]);
+
+  // Reset fallback state when symbol changes
+  useEffect(() => {
+    setUseFallbackUrl(false);
   }, [symbol]);
 
+  // Select current image URL based on fallback state
+  const imageUri = iconUrls
+    ? useFallbackUrl
+      ? iconUrls.fallback
+      : iconUrls.primary
+    : null;
+
   // Extract display symbol (e.g., "TSLA" from "xyz:TSLA")
   const fallbackText = useMemo(() => {
     const displaySymbol = getPerpsDisplaySymbol(symbol || '');
@@ -53,6 +68,22 @@ const PerpsTokenLogo: React.FC<PerpsTokenLogoProps> = ({
     assetsRequiringDarkBg: ASSETS_REQUIRING_DARK_BG,
   });
 
+  // Handle image error with fallback logic:
+  // 1. If primary URL fails, try fallback URL
+  // 2. If fallback URL also fails, show text fallback
+  const handleImageError = useCallback(() => {
+    if (!useFallbackUrl && iconUrls?.fallback) {
+      // Primary failed - try fallback URL
+      setUseFallbackUrl(true);
+    } else {
+      // Both URLs failed - show text fallback
+      handleError();
+    }
+  }, [useFallbackUrl, iconUrls?.fallback, handleError]);
+
+  // Image key includes fallback state for proper re-render when switching URLs
+  const imageKey = `${recyclingKey || symbol}-${useFallbackUrl ? 'fallback' : 'primary'}`;
+
   // Show custom two-letter fallback if no symbol or error
   if (!symbol || !imageUri || hasError) {
     return (
@@ -72,15 +103,15 @@ const PerpsTokenLogo: React.FC<PerpsTokenLogoProps> = ({
         </View>
       )}
       <Image
-        key={recyclingKey || symbol} // Use recyclingKey for proper recycling
+        key={imageKey}
         source={{ uri: imageUri }}
         style={imageStyle}
         onLoadStart={handleLoadStart}
         onLoadEnd={handleLoadEnd}
-        onError={handleError}
+        onError={handleImageError}
         contentFit="contain"
         cachePolicy="memory-disk" // Persistent caching across app sessions
-        recyclingKey={recyclingKey || symbol} // For FlashList optimization
+        recyclingKey={imageKey} // For FlashList optimization
         transition={0} // Disable transition for faster rendering
         priority="high" // High priority loading
         placeholder={null} // No placeholder for cleaner loading

app/components/UI/Perps/constants/hyperLiquidConfig.ts

@@ -54,10 +54,17 @@ export const HYPERLIQUID_ENDPOINTS: HyperLiquidEndpoints = {
   testnet: 'wss://api.hyperliquid-testnet.xyz/ws',
 };
 
-// Asset icons base URL
+// Asset icons base URL (HyperLiquid CDN - fallback source)
 export const HYPERLIQUID_ASSET_ICONS_BASE_URL =
   'https://app.hyperliquid.xyz/coins/';
 
+// MetaMask-hosted Perps asset icons (primary source)
+// Assets uploaded to: https://github.com/MetaMask/contract-metadata/tree/master/icons/eip155:999
+// HIP-3 assets use format: hip3:dex_SYMBOL.svg (e.g., hip3:xyz_AAPL.svg)
+// Regular assets use format: SYMBOL.svg (e.g., BTC.svg)
+export const METAMASK_PERPS_ICONS_BASE_URL =
+  'https://raw.githubusercontent.com/MetaMask/contract-metadata/master/icons/eip155:999/';
+
 // Asset configurations for multichain abstraction
 export const HYPERLIQUID_ASSET_CONFIGS: HyperLiquidAssetConfigs = {
   USDC: {

app/components/UI/Perps/utils/marketUtils.test.ts

@@ -2,6 +2,7 @@ import {
   calculateFundingCountdown,
   calculate24hHighLow,
   getAssetIconUrl,
+  getAssetIconUrls,
   escapeRegex,
   compileMarketPattern,
   matchesMarketPattern,
@@ -16,6 +17,8 @@ import { CandlePeriod } from '../constants/chartConfig';
 
 jest.mock('../constants/hyperLiquidConfig', () => ({
   HYPERLIQUID_ASSET_ICONS_BASE_URL: 'https://app.hyperliquid.xyz/coins/',
+  METAMASK_PERPS_ICONS_BASE_URL:
+    'https://raw.githubusercontent.com/MetaMask/contract-metadata/master/icons/eip155:999/',
 }));
 
 describe('marketUtils', () => {
@@ -411,6 +414,77 @@ describe('marketUtils', () => {
     });
   });
 
+  describe('getAssetIconUrls', () => {
+    it('returns primary and fallback URLs for regular asset', () => {
+      const symbol = 'BTC';
+
+      const result = getAssetIconUrls(symbol);
+
+      expect(result).toEqual({
+        primary:
+          'https://raw.githubusercontent.com/MetaMask/contract-metadata/master/icons/eip155:999/BTC.svg',
+        fallback: 'https://app.hyperliquid.xyz/coins/BTC.svg',
+      });
+    });
+
+    it('returns primary and fallback URLs for HIP-3 asset', () => {
+      const symbol = 'xyz:TSLA';
+
+      const result = getAssetIconUrls(symbol);
+
+      expect(result).toEqual({
+        primary:
+          'https://raw.githubusercontent.com/MetaMask/contract-metadata/master/icons/eip155:999/hip3:xyz_TSLA.svg',
+        fallback: 'https://app.hyperliquid.xyz/coins/xyz:TSLA.svg',
+      });
+    });
+
+    it('returns null for empty symbol', () => {
+      const symbol = '';
+
+      const result = getAssetIconUrls(symbol);
+
+      expect(result).toBeNull();
+    });
+
+    it('removes k prefix for specified assets', () => {
+      const symbol = 'kBONK';
+      const kPrefixAssets = new Set(['KBONK']);
+
+      const result = getAssetIconUrls(symbol, kPrefixAssets);
+
+      expect(result).toEqual({
+        primary:
+          'https://raw.githubusercontent.com/MetaMask/contract-metadata/master/icons/eip155:999/BONK.svg',
+        fallback: 'https://app.hyperliquid.xyz/coins/BONK.svg',
+      });
+    });
+
+    it('uppercases lowercase symbols for regular assets', () => {
+      const symbol = 'eth';
+
+      const result = getAssetIconUrls(symbol);
+
+      expect(result).toEqual({
+        primary:
+          'https://raw.githubusercontent.com/MetaMask/contract-metadata/master/icons/eip155:999/ETH.svg',
+        fallback: 'https://app.hyperliquid.xyz/coins/ETH.svg',
+      });
+    });
+
+    it('formats HIP-3 assets with hip3 prefix and underscore separator', () => {
+      const symbol = 'ABC:xyz100';
+
+      const result = getAssetIconUrls(symbol);
+
+      expect(result).toEqual({
+        primary:
+          'https://raw.githubusercontent.com/MetaMask/contract-metadata/master/icons/eip155:999/hip3:abc_XYZ100.svg',
+        fallback: 'https://app.hyperliquid.xyz/coins/abc:XYZ100.svg',
+      });
+    });
+  });
+
   describe('Pattern Matching Utilities', () => {
     describe('escapeRegex', () => {
       it('escapes regex special characters', () => {

app/components/UI/Perps/utils/marketUtils.ts

@@ -1,7 +1,10 @@
 import type { CandleData, CandleStick } from '../types/perps-types';
 import type { PerpsMarketData } from '../controllers/types';
 import type { BadgeType } from '../components/PerpsBadge/PerpsBadge.types';
-import { HYPERLIQUID_ASSET_ICONS_BASE_URL } from '../constants/hyperLiquidConfig';
+import {
+  HYPERLIQUID_ASSET_ICONS_BASE_URL,
+  METAMASK_PERPS_ICONS_BASE_URL,
+} from '../constants/hyperLiquidConfig';
 
 /**
  * Maximum length for market filter patterns (prevents DoS attacks)
@@ -460,3 +463,67 @@ export const getAssetIconUrl = (
   // Regular asset
   return `${HYPERLIQUID_ASSET_ICONS_BASE_URL}${processedSymbol}.svg`;
 };
+
+/**
+ * Icon URLs with primary (MetaMask-hosted) and fallback (HyperLiquid) sources
+ */
+export interface AssetIconUrls {
+  /** MetaMask contract-metadata repo (preferred source) */
+  primary: string;
+  /** HyperLiquid CDN (fallback source) */
+  fallback: string;
+}
+
+/**
+ * Generate icon URLs for an asset symbol with fallback support
+ *
+ * Resolution order:
+ * 1. Primary: MetaMask contract-metadata repo (manually curated)
+ * 2. Fallback: HyperLiquid CDN (always available)
+ *
+ * @param symbol - Asset symbol (e.g., "BTC" or "xyz:TSLA")
+ * @param kPrefixAssets - Optional set of assets that have a 'k' prefix to remove
+ * @returns Object with primary and fallback URLs, or null if no symbol
+ *
+ * @example Regular asset
+ * getAssetIconUrls('BTC')
+ * // → { primary: 'https://raw.githubusercontent.com/.../BTC.svg',
+ * //     fallback: 'https://app.hyperliquid.xyz/coins/BTC.svg' }
+ *
+ * @example HIP-3 asset
+ * getAssetIconUrls('xyz:TSLA')
+ * // → { primary: 'https://raw.githubusercontent.com/.../hip3:xyz_TSLA.svg',
+ * //     fallback: 'https://app.hyperliquid.xyz/coins/xyz:TSLA.svg' }
+ */
+export const getAssetIconUrls = (
+  symbol: string,
+  kPrefixAssets?: Set<string>,
+): AssetIconUrls | null => {
+  if (!symbol) return null;
+
+  // Check for HIP-3 asset (contains colon) BEFORE uppercasing
+  if (symbol.includes(':')) {
+    const [dex, assetSymbol] = symbol.split(':');
+    // HyperLiquid uses dex:SYMBOL format
+    const hyperliquidFormat = `${dex.toLowerCase()}:${assetSymbol.toUpperCase()}`;
+    // MetaMask contract-metadata uses hip3:dex_SYMBOL format
+    const metamaskFormat = `hip3:${dex.toLowerCase()}_${assetSymbol.toUpperCase()}`;
+    return {
+      primary: `${METAMASK_PERPS_ICONS_BASE_URL}${metamaskFormat}.svg`,
+      fallback: `${HYPERLIQUID_ASSET_ICONS_BASE_URL}${hyperliquidFormat}.svg`,
+    };
+  }
+
+  // For regular assets, uppercase the entire symbol
+  let processedSymbol = symbol.toUpperCase();
+
+  // Remove 'k' prefix only for specific assets if provided
+  if (kPrefixAssets?.has(processedSymbol)) {
+    processedSymbol = processedSymbol.substring(1);
+  }
+
+  return {
+    primary: `${METAMASK_PERPS_ICONS_BASE_URL}${processedSymbol}.svg`,
+    fallback: `${HYPERLIQUID_ASSET_ICONS_BASE_URL}${processedSymbol}.svg`,
+  };
+};