feat: fetch asset metadata on search (#31258)

<!--
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**

<!--
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?
-->

This changes adds a `useAssetMetadata` hook that fetches asset details
if it is not found in existing token lists. I've also added more unit
test coverage for the asset-picker token filtering

See [Copilot summary for more
details](#31258 (review))

[![Open in GitHub
Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/MetaMask/metamask-extension/pull/31258?quickstart=1)

## **Related issues**

Fixes: https://consensyssoftware.atlassian.net/browse/MMS-2094

## **Manual testing steps**

1. Select solana as active network
2. Go to Bridge page
3. Get the address of a new pump.fun coin
4. Paste address into the asset picker's search bar
5. The token should appear on the list and be selectable
6. After filling out quote params, quotes should be fetched

## **Screenshots/Recordings**

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

### **Before**
No asset is shown
<!-- [screenshots/recordings] -->

### **After**


https://github.com/user-attachments/assets/e1cf7185-49f3-4b64-a31f-1232a19a995d


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

## **Pre-merge author checklist**

- [ ] I've followed [MetaMask Contributor
Docs](https://github.com/MetaMask/contributor-docs) and [MetaMask
Extension Coding
Standards](https://github.com/MetaMask/metamask-extension/blob/main/.github/guidelines/CODING_GUIDELINES.md).
- [ ] 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](https://jsdoc.app/) format
if applicable
- [ ] I’ve applied the right labels on the PR (see [labeling
guidelines](https://github.com/MetaMask/metamask-extension/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.

Author: micaelae

shared/lib/asset-utils.test.ts

@@ -0,0 +1,297 @@
+import {
+  CaipAssetType,
+  CaipAssetTypeStruct,
+  CaipChainId,
+  Hex,
+} from '@metamask/utils';
+import { toEvmCaipChainId } from '@metamask/multichain-network-controller';
+import { MultichainNetwork } from '@metamask/multichain-transactions-controller';
+import { toHex } from '@metamask/controller-utils';
+import { MINUTE } from '../constants/time';
+import { MultichainNetworks } from '../constants/multichain/networks';
+import fetchWithCache from './fetch-with-cache';
+import { getAssetImageUrl, fetchAssetMetadata, toAssetId } from './asset-utils';
+
+jest.mock('./fetch-with-cache');
+jest.mock('@metamask/multichain-network-controller');
+jest.mock('@metamask/controller-utils');
+
+describe('asset-utils', () => {
+  const STATIC_METAMASK_BASE_URL = 'https://static.cx.metamask.io';
+  const TOKEN_API_V3_BASE_URL = 'https://tokens.api.cx.metamask.io/v3';
+
+  describe('toAssetId', () => {
+    it('should return the same asset ID if input is already a CAIP asset type', () => {
+      const caipAssetId = CaipAssetTypeStruct.create('eip155:1/erc20:0x123');
+      const chainId = 'eip155:1' as CaipChainId;
+
+      const result = toAssetId(caipAssetId, chainId);
+      expect(result).toBe(caipAssetId);
+    });
+
+    it('should create Solana token asset ID correctly', () => {
+      const address = 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v';
+      const chainId = MultichainNetwork.Solana as CaipChainId;
+
+      const result = toAssetId(address, chainId);
+      expect(result).toBe(`${MultichainNetwork.Solana}/token:${address}`);
+    });
+
+    it('should create EVM token asset ID correctly', () => {
+      const address = '0x1f9840a85d5af5bf1d1762f925bdaddc4201f984';
+      const chainId = 'eip155:1' as CaipChainId;
+
+      const result = toAssetId(address, chainId);
+      expect(result).toBe(`eip155:1/erc20:${address}`);
+    });
+
+    it('should return undefined for non-hex address on EVM chains', () => {
+      const address = 'not-a-hex-address';
+      const chainId = 'eip155:1' as CaipChainId;
+
+      const result = toAssetId(address, chainId);
+      expect(result).toBeUndefined();
+    });
+
+    it('should handle different EVM chain IDs', () => {
+      const address = '0x1f9840a85d5af5bf1d1762f925bdaddc4201f984';
+      const chainId = 'eip155:137' as CaipChainId;
+
+      const result = toAssetId(address, chainId);
+      expect(result).toBe(`eip155:137/erc20:${address}`);
+    });
+
+    it('should handle checksummed addresses', () => {
+      const address = '0x1F9840a85d5aF5bf1D1762F925BDADdC4201F984';
+      const chainId = 'eip155:1' as CaipChainId;
+
+      const result = toAssetId(address, chainId);
+      expect(result).toBe(`eip155:1/erc20:${address}`);
+    });
+  });
+
+  describe('getAssetImageUrl', () => {
+    it('should return correct image URL for a CAIP asset ID', () => {
+      const assetId = 'eip155:1/erc20:0x123' as CaipAssetType;
+      const expectedUrl = `${STATIC_METAMASK_BASE_URL}/api/v2/tokenIcons/assets/eip155/1/erc20/0x123.png`;
+
+      expect(getAssetImageUrl(assetId, 'eip155:1')).toBe(expectedUrl);
+    });
+
+    it('should return correct image URL for non-hex CAIP asset ID', () => {
+      const assetId =
+        `${MultichainNetworks.SOLANA}/token:aBCD` as CaipAssetType;
+      const expectedUrl = `${STATIC_METAMASK_BASE_URL}/api/v2/tokenIcons/assets/solana/5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp/token/aBCD.png`;
+
+      expect(getAssetImageUrl(assetId, 'eip155:1')).toBe(expectedUrl);
+    });
+
+    it('should handle asset IDs with multiple colons', () => {
+      const assetId = 'test:chain:1/token:0x123' as CaipAssetType;
+
+      expect(getAssetImageUrl(assetId, 'eip155:1')).toBe(undefined);
+    });
+  });
+
+  describe('fetchAssetMetadata', () => {
+    const mockAddress = '0x123' as Hex;
+    const mockChainId = 'eip155:1' as CaipChainId;
+    const mockHexChainId = '0x1' as Hex;
+    const mockAssetId = 'eip155:1/erc20:0x123' as CaipAssetType;
+
+    beforeEach(() => {
+      jest.clearAllMocks();
+      (toEvmCaipChainId as jest.Mock).mockReturnValue(mockChainId);
+      (toHex as jest.Mock).mockImplementation((val) => val as Hex);
+    });
+
+    it('should fetch EVM token metadata successfully', async () => {
+      const mockMetadata = {
+        assetId: mockAssetId,
+        symbol: 'TEST',
+        name: 'Test Token',
+        decimals: 18,
+      };
+
+      (fetchWithCache as jest.Mock).mockResolvedValueOnce([mockMetadata]);
+
+      const result = await fetchAssetMetadata(mockAddress, mockHexChainId);
+
+      expect(fetchWithCache).toHaveBeenCalledWith({
+        url: `${TOKEN_API_V3_BASE_URL}/assets?assetIds=${mockAssetId}`,
+        fetchOptions: {
+          method: 'GET',
+          headers: { 'X-Client-Id': 'extension' },
+        },
+        cacheOptions: {
+          cacheRefreshTime: MINUTE,
+        },
+        functionName: 'fetchAssetMetadata',
+      });
+
+      expect(result).toStrictEqual({
+        symbol: 'TEST',
+        decimals: 18,
+        image:
+          'https://static.cx.metamask.io/api/v2/tokenIcons/assets/eip155/1/erc20/0x123.png',
+        assetId: mockAssetId,
+        address: mockAddress,
+        chainId: mockHexChainId,
+      });
+    });
+
+    it('should fetch Solana token metadata successfully', async () => {
+      const solanaChainId = MultichainNetwork.Solana;
+      const solanaAddress = 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v';
+      const solanaAssetId = `${solanaChainId}/token:${solanaAddress}`;
+
+      const mockMetadata = {
+        assetId: solanaAssetId,
+        symbol: 'SOL',
+        name: 'Solana Token',
+        decimals: 9,
+      };
+
+      (fetchWithCache as jest.Mock).mockResolvedValueOnce([mockMetadata]);
+
+      const result = await fetchAssetMetadata(solanaAddress, solanaChainId);
+
+      expect(result).toStrictEqual({
+        symbol: 'SOL',
+        decimals: 9,
+        image:
+          'https://static.cx.metamask.io/api/v2/tokenIcons/assets/solana/5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp/token/EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v.png',
+        assetId: solanaAssetId,
+        address: solanaAddress,
+        chainId: solanaChainId,
+      });
+    });
+
+    it('should handle CAIP chain IDs', async () => {
+      const mockMetadata = {
+        assetId: mockAssetId,
+        symbol: 'TEST',
+        name: 'Test Token',
+        decimals: 18,
+      };
+
+      (fetchWithCache as jest.Mock).mockResolvedValueOnce([mockMetadata]);
+
+      const result = await fetchAssetMetadata(mockAddress, mockChainId);
+
+      expect(toEvmCaipChainId).not.toHaveBeenCalled();
+
+      expect(fetchWithCache).toHaveBeenCalledWith({
+        url: `${TOKEN_API_V3_BASE_URL}/assets?assetIds=${mockAssetId}`,
+        fetchOptions: {
+          method: 'GET',
+          headers: { 'X-Client-Id': 'extension' },
+        },
+        cacheOptions: {
+          cacheRefreshTime: MINUTE,
+        },
+        functionName: 'fetchAssetMetadata',
+      });
+
+      expect(result).toStrictEqual({
+        symbol: 'TEST',
+        decimals: 18,
+        image:
+          'https://static.cx.metamask.io/api/v2/tokenIcons/assets/eip155/1/erc20/0x123.png',
+        assetId: mockAssetId,
+        address: mockAddress,
+        chainId: mockHexChainId,
+      });
+    });
+
+    it('should handle hex chain IDs', async () => {
+      const mockMetadata = {
+        assetId: mockAssetId,
+        symbol: 'TEST',
+        name: 'Test Token',
+        decimals: 18,
+      };
+
+      (fetchWithCache as jest.Mock).mockResolvedValueOnce([mockMetadata]);
+
+      const result = await fetchAssetMetadata(mockAddress, mockHexChainId);
+
+      expect(toEvmCaipChainId).toHaveBeenCalledWith(mockHexChainId);
+
+      expect(fetchWithCache).toHaveBeenCalledWith({
+        url: `${TOKEN_API_V3_BASE_URL}/assets?assetIds=${mockAssetId}`,
+        fetchOptions: {
+          method: 'GET',
+          headers: { 'X-Client-Id': 'extension' },
+        },
+        cacheOptions: {
+          cacheRefreshTime: MINUTE,
+        },
+        functionName: 'fetchAssetMetadata',
+      });
+
+      expect(result).toStrictEqual({
+        symbol: 'TEST',
+        decimals: 18,
+        image:
+          'https://static.cx.metamask.io/api/v2/tokenIcons/assets/eip155/1/erc20/0x123.png',
+        assetId: mockAssetId,
+        address: mockAddress,
+        chainId: mockHexChainId,
+      });
+    });
+
+    it('should return undefined when API call fails', async () => {
+      (fetchWithCache as jest.Mock).mockRejectedValueOnce(
+        new Error('API Error'),
+      );
+
+      const result = await fetchAssetMetadata(mockAddress, mockHexChainId);
+
+      expect(result).toBeUndefined();
+    });
+
+    it('should return undefined when metadata processing fails', async () => {
+      (fetchWithCache as jest.Mock).mockResolvedValueOnce([null]);
+
+      const result = await fetchAssetMetadata(mockAddress, mockHexChainId);
+
+      expect(result).toBeUndefined();
+    });
+
+    it('should return undefined when EVM address is not valid', async () => {
+      const mockMetadata = {
+        assetId: 'hjk',
+        symbol: 'TEST',
+        name: 'Test Token',
+        decimals: 18,
+      };
+
+      (fetchWithCache as jest.Mock).mockResolvedValueOnce([mockMetadata]);
+
+      const result = await fetchAssetMetadata(mockAddress, mockHexChainId);
+
+      expect(fetchWithCache).toHaveBeenCalledWith({
+        url: `${TOKEN_API_V3_BASE_URL}/assets?assetIds=${mockAssetId}`,
+        fetchOptions: {
+          method: 'GET',
+          headers: { 'X-Client-Id': 'extension' },
+        },
+        cacheOptions: {
+          cacheRefreshTime: MINUTE,
+        },
+        functionName: 'fetchAssetMetadata',
+      });
+
+      expect(result).toStrictEqual({
+        symbol: 'TEST',
+        decimals: 18,
+        image:
+          'https://static.cx.metamask.io/api/v2/tokenIcons/assets/eip155/1/erc20/0x123.png',
+        assetId: mockAssetId,
+        address: mockAddress,
+        chainId: mockHexChainId,
+      });
+    });
+  });
+});