feat(assets-controller): add getAsset

packages/assets-controller/CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Add `getAsset(accountId, assetId)` method and `AssetsController:getAsset` messenger action that returns the combined `Asset` (balance, metadata, price) for a single account/asset pair from controller state, or `undefined` when a complete renderable asset is not available ([#9521](https://github.com/MetaMask/core/pull/9521))
+
 ### Changed
 
 - Bump `@metamask/network-enablement-controller` from `^5.5.0` to `^5.6.0` ([#9520](https://github.com/MetaMask/core/pull/9520))

packages/assets-controller/src/AssetsController-method-action-types.ts

@@ -20,6 +20,29 @@ export type AssetsControllerGetAssetMetadataAction = {
   handler: AssetsController['getAssetMetadata'];
 };
 
+/**
+ * Get a single combined asset (balance + metadata + price + computed
+ * `fiatValue`) for an account directly from controller state.
+ *
+ * Reuses the same state-composition and filtering logic as `getAssets`
+ * (balance and metadata are required, a missing price falls back to
+ * `{ price: 0, lastUpdated: 0 }` with `fiatValue: 0`, and hidden or
+ * otherwise filtered assets are excluded) so the returned shape never
+ * drifts from `getAssets`. Reads from current state only and does not
+ * trigger a data-source refresh.
+ *
+ * @param accountId - The account ID (`InternalAccount.id`, not an address).
+ * @param assetId - The CAIP-19 asset ID including chain scope
+ * (e.g. `eip155:1/erc20:0x...`).
+ * @returns The combined `Asset`, or `undefined` when no complete
+ * renderable asset (balance + metadata) exists for the account/asset pair.
+ * @throws If `accountId` is empty or `assetId` is not a valid CAIP-19 asset ID.
+ */
+export type AssetsControllerGetAssetAction = {
+  type: `AssetsController:getAsset`;
+  handler: AssetsController['getAsset'];
+};
+
 export type AssetsControllerGetAssetsPriceAction = {
   type: `AssetsController:getAssetsPrice`;
   handler: AssetsController['getAssetsPrice'];
@@ -132,6 +155,7 @@ export type AssetsControllerMethodActions =
   | AssetsControllerGetAssetsAction
   | AssetsControllerGetAssetsBalanceAction
   | AssetsControllerGetAssetMetadataAction
+  | AssetsControllerGetAssetAction
   | AssetsControllerGetAssetsPriceAction
   | AssetsControllerGetExchangeRatesForBridgeAction
   | AssetsControllerGetStateForTransactionPayAction

packages/assets-controller/src/AssetsController.test.ts

@@ -856,6 +856,154 @@ describe('AssetsController', () => {
     });
   });
 
+  describe('getAsset', () => {
+    const metadata = {
+      type: 'erc20' as const,
+      symbol: 'USDC',
+      name: 'USD Coin',
+      decimals: 6,
+    };
+
+    it('returns the combined asset with computed fiatValue', async () => {
+      const initialState: Partial<AssetsControllerState> = {
+        assetsInfo: { [MOCK_ASSET_ID]: metadata },
+        assetsBalance: {
+          [MOCK_ACCOUNT_ID]: { [MOCK_ASSET_ID]: { amount: '100' } },
+        },
+        assetsPrice: { [MOCK_ASSET_ID]: { price: 2, lastUpdated: 123 } },
+      };
+
+      await withController({ state: initialState }, ({ controller }) => {
+        const asset = controller.getAsset(MOCK_ACCOUNT_ID, MOCK_ASSET_ID);
+
+        expect(asset).toStrictEqual({
+          id: MOCK_ASSET_ID,
+          chainId: 'eip155:1',
+          balance: { amount: '100' },
+          metadata,
+          price: { price: 2, lastUpdated: 123 },
+          fiatValue: 200,
+        });
+      });
+    });
+
+    it('normalizes a lowercase EVM asset ID before lookup', async () => {
+      const initialState: Partial<AssetsControllerState> = {
+        assetsInfo: { [MOCK_ASSET_ID]: metadata },
+        assetsBalance: {
+          [MOCK_ACCOUNT_ID]: { [MOCK_ASSET_ID]: { amount: '1' } },
+        },
+        assetsPrice: { [MOCK_ASSET_ID]: { price: 1, lastUpdated: 1 } },
+      };
+
+      await withController({ state: initialState }, ({ controller }) => {
+        const asset = controller.getAsset(
+          MOCK_ACCOUNT_ID,
+          MOCK_ASSET_ID_LOWERCASE,
+        );
+
+        expect(asset?.id).toBe(MOCK_ASSET_ID);
+      });
+    });
+
+    it('returns undefined when the balance is missing', async () => {
+      const initialState: Partial<AssetsControllerState> = {
+        assetsInfo: { [MOCK_ASSET_ID]: metadata },
+      };
+
+      await withController({ state: initialState }, ({ controller }) => {
+        expect(
+          controller.getAsset(MOCK_ACCOUNT_ID, MOCK_ASSET_ID),
+        ).toBeUndefined();
+      });
+    });
+
+    it('returns undefined when the metadata is missing', async () => {
+      const initialState: Partial<AssetsControllerState> = {
+        assetsBalance: {
+          [MOCK_ACCOUNT_ID]: { [MOCK_ASSET_ID]: { amount: '100' } },
+        },
+      };
+
+      await withController({ state: initialState }, ({ controller }) => {
+        expect(
+          controller.getAsset(MOCK_ACCOUNT_ID, MOCK_ASSET_ID),
+        ).toBeUndefined();
+      });
+    });
+
+    it('falls back to a zero price and fiatValue when the price is missing', async () => {
+      const initialState: Partial<AssetsControllerState> = {
+        assetsInfo: { [MOCK_ASSET_ID]: metadata },
+        assetsBalance: {
+          [MOCK_ACCOUNT_ID]: { [MOCK_ASSET_ID]: { amount: '100' } },
+        },
+      };
+
+      await withController({ state: initialState }, ({ controller }) => {
+        const asset = controller.getAsset(MOCK_ACCOUNT_ID, MOCK_ASSET_ID);
+
+        expect(asset?.price).toStrictEqual({ price: 0, lastUpdated: 0 });
+        expect(asset?.fiatValue).toBe(0);
+      });
+    });
+
+    it('returns undefined for a hidden asset', async () => {
+      const initialState: Partial<AssetsControllerState> = {
+        assetsInfo: { [MOCK_ASSET_ID]: metadata },
+        assetsBalance: {
+          [MOCK_ACCOUNT_ID]: { [MOCK_ASSET_ID]: { amount: '100' } },
+        },
+        assetPreferences: { [MOCK_ASSET_ID]: { hidden: true } },
+      };
+
+      await withController({ state: initialState }, ({ controller }) => {
+        expect(
+          controller.getAsset(MOCK_ACCOUNT_ID, MOCK_ASSET_ID),
+        ).toBeUndefined();
+      });
+    });
+
+    it('throws when accountId is empty', async () => {
+      await withController(({ controller }) => {
+        expect(() =>
+          controller.getAsset('' as AccountId, MOCK_ASSET_ID),
+        ).toThrow('accountId must be a non-empty string');
+      });
+    });
+
+    it('throws when assetId is not a valid CAIP-19 asset ID', async () => {
+      await withController(({ controller }) => {
+        expect(() =>
+          controller.getAsset(
+            MOCK_ACCOUNT_ID,
+            'not-a-caip-19' as Caip19AssetId,
+          ),
+        ).toThrow('invalid CAIP-19 assetId');
+      });
+    });
+
+    it('is exposed as the AssetsController:getAsset messenger action', async () => {
+      const initialState: Partial<AssetsControllerState> = {
+        assetsInfo: { [MOCK_ASSET_ID]: metadata },
+        assetsBalance: {
+          [MOCK_ACCOUNT_ID]: { [MOCK_ASSET_ID]: { amount: '100' } },
+        },
+        assetsPrice: { [MOCK_ASSET_ID]: { price: 2, lastUpdated: 123 } },
+      };
+
+      await withController({ state: initialState }, ({ messenger }) => {
+        const asset = messenger.call(
+          'AssetsController:getAsset',
+          MOCK_ACCOUNT_ID,
+          MOCK_ASSET_ID,
+        );
+
+        expect(asset?.fiatValue).toBe(200);
+      });
+    });
+  });
+
   describe('getAssets', () => {
     it('returns empty object when no balances exist', async () => {
       await withController(async ({ controller }) => {

packages/assets-controller/src/AssetsController.ts

@@ -181,6 +181,7 @@
   'getAssets',
   'getAssetsBalance',
   'getAssetMetadata',
+  'getAsset',
   'getAssetsPrice',
   'getExchangeRatesForBridge',
   'getStateForTransactionPay',
@@ -1775,6 +1776,51 @@
     return this.state.assetsInfo[assetId] as AssetMetadata | undefined;
   }
 
+  /**
+   * Get a single combined asset (balance + metadata + price + computed
+   * `fiatValue`) for an account directly from controller state.
+   *
+   * Reuses the same state-composition and filtering logic as `getAssets`
+   * (balance and metadata are required, a missing price falls back to
+   * `{ price: 0, lastUpdated: 0 }` with `fiatValue: 0`, and hidden or
+   * otherwise filtered assets are excluded) so the returned shape never
+   * drifts from `getAssets`. Reads from current state only and does not
+   * trigger a data-source refresh.
+   *
+   * @param accountId - The account ID (`InternalAccount.id`, not an address).
+   * @param assetId - The CAIP-19 asset ID including chain scope
+   * (e.g. `eip155:1/erc20:0x...`).
+   * @returns The combined `Asset`, or `undefined` when no complete
+   * renderable asset (balance + metadata) exists for the account/asset pair.
+   * @throws If `accountId` is empty or `assetId` is not a valid CAIP-19 asset ID.
+   */
+  getAsset(accountId: AccountId, assetId: Caip19AssetId): Asset | undefined {
+    if (typeof accountId !== 'string' || accountId.length === 0) {
+      throw new Error(
+        'AssetsController.getAsset: accountId must be a non-empty string',
+      );
+    }
+
+    let normalizedAssetId: Caip19AssetId;
+    try {
+      normalizedAssetId = normalizeAssetId(assetId);
+    } catch {
+      throw new Error(
+        `AssetsController.getAsset: invalid CAIP-19 assetId "${assetId}"`,
+      );
+    }
+
+    const chainId = extractChainId(normalizedAssetId);
+
+    const assets = this.#getAssetsFromState(
+      [{ id: accountId }],
+      [chainId],
+      ['fungible'],
+    );
+
+    return assets[accountId]?.[normalizedAssetId];
+  }
+
   async getAssetsPrice(
     accounts: InternalAccount[],
     options?: {
@@ -2698,7 +2744,7 @@
   }
 
   #getAssetsFromState(
-    accounts: InternalAccount[],
+    accounts: Pick<InternalAccount, 'id'>[],
     chainIds: ChainId[],
     assetTypes: AssetType[],
   ): Record<AccountId, Record<Caip19AssetId, Asset>> {
@@ -2725,7 +2771,7 @@
         const metadata = metadataRaw;
 
         // Skip hidden assets (assetPreferences)
         const prefs = this.state.assetPreferences[typedAssetId];
         if (prefs?.hidden) {
           continue;
         }
@@ -3671,6 +3717,7 @@
     this.messenger.unregisterActionHandler('AssetsController:getAssets');
     this.messenger.unregisterActionHandler('AssetsController:getAssetsBalance');
     this.messenger.unregisterActionHandler('AssetsController:getAssetMetadata');
+    this.messenger.unregisterActionHandler('AssetsController:getAsset');
     this.messenger.unregisterActionHandler('AssetsController:getAssetsPrice');
     this.messenger.unregisterActionHandler(
       'AssetsController:getExchangeRatesForBridge',

packages/assets-controller/src/index.ts

@@ -31,6 +31,7 @@ export type {
   AssetsControllerGetAssetsAction,
   AssetsControllerGetAssetsBalanceAction,
   AssetsControllerGetAssetMetadataAction,
+  AssetsControllerGetAssetAction,
   AssetsControllerGetAssetsPriceAction,
   AssetsControllerAddCustomAssetAction,
   AssetsControllerRemoveCustomAssetAction,