feat: add getErc20Balances helper TokenBalancesControllers (#5925)

## Explanation

This change introduces a new `getErc20Balances` service function within
the `TokenBalancesController`. The goal is to provide a reusable and
isolated utility to fetch ERC-20 token balances for a given address and
token list.

The service is intended to be used internally by the controller or other
consumers needing direct access to raw ERC-20 balances, while
abstracting away Web3 calls and error handling.


<!--
Thanks for your contribution! Take a moment to answer these questions so
that reviewers have the information they need to properly understand
your changes:

* What is the current state of things and why does it need to change?
* What is the solution your changes offer and how does it work?
* Are there any changes whose purpose might not obvious to those
unfamiliar with the domain?
* If your primary goal was to update one package but you found you had
to update another one along the way, why did you do so?
* If you had to upgrade a dependency, why did you do so?
-->

## References

<!--
Are there any issues that this pull request is tied to?
Are there other links that reviewers should consult to understand these
changes better?
Are there client or consumer pull requests to adopt any breaking
changes?

For example:

* Fixes #12345
* Related to #67890
-->

## Changelog

### `@metamask/assets-controllers`

UPDATE: Created getErc20Balances function within TokenBalancesController
to support fetching ERC-20 token balances for a given address and token
list. This modular service simplifies balance retrieval logic and can be
reused across different parts of the controller.

<!--
THIS SECTION IS NO LONGER NEEDED.

The process for updating changelogs has changed. Please consult the
"Updating changelogs" section of the Contributing doc for more.
-->

## Checklist

- [ ] I've updated the test suite for new or updated code as appropriate
- [ ] I've updated documentation (JSDoc, Markdown, etc.) for new or
updated code as appropriate
- [ ] I've communicated my changes to consumers by [updating changelogs
for packages I've
changed](https://github.com/MetaMask/core/tree/main/docs/contributing.md#updating-changelogs),
highlighting breaking changes as necessary
- [ ] I've prepared draft pull requests for clients and consumer
packages to resolve any breaking changes

Author: salimtb

packages/assets-controllers/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+
+- Bump `@metamask/controller-utils` to `^11.10.0` ([#5935](https://github.com/MetaMask/core/pull/5935))
+- Add `getErc20Balances` function within `TokenBalancesController` to support fetching ERC-20 token balances for a given address and token list ([#5925](https://github.com/MetaMask/core/pull/5925))
+  - This modular service simplifies balance retrieval logic and can be reused across different parts of the controller
+
 ### Fixed
 
 - Prevented `AccountTrackerController` from updating state with empty or unchanged account balance data during refresh ([#5942](https://github.com/MetaMask/core/pull/5942))
@@ -24,6 +30,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Changed
 
 - Bump `@metamask/controller-utils` to `^11.10.0` ([#5935](https://github.com/MetaMask/core/pull/5935))
+- Add `getErc20Balances` function within `TokenBalancesController` to support fetching ERC-20 token balances for a given address and token list ([#5925](https://github.com/MetaMask/core/pull/5925))
+  - This modular service simplifies balance retrieval logic and can be reused across different parts of the controller
 
 ## [68.0.0]
 

packages/assets-controllers/src/TokenBalancesController.test.ts

@@ -832,4 +832,70 @@ describe('TokenBalancesController', () => {
       });
     });
   });
+
+  describe('getErc20Balances', () => {
+    const chainId = '0x1';
+    const account = '0x0000000000000000000000000000000000000000';
+    const tokenA = '0x00000000000000000000000000000000000000a1';
+    const tokenB = '0x00000000000000000000000000000000000000b2';
+
+    afterEach(() => {
+      // make sure spies do not leak between tests
+      jest.restoreAllMocks();
+    });
+
+    it('returns an **empty object** if no token addresses are provided', async () => {
+      const { controller } = setupController();
+      const balances = await controller.getErc20Balances({
+        chainId,
+        accountAddress: account,
+        tokenAddresses: [],
+      });
+
+      expect(balances).toStrictEqual({});
+    });
+
+    it('maps **each address to a hex balance** on success', async () => {
+      const bal1 = 42;
+      const bal2 = 0;
+
+      jest.spyOn(multicall, 'multicallOrFallback').mockResolvedValueOnce([
+        { success: true, value: new BN(bal1) },
+        { success: true, value: new BN(bal2) },
+      ]);
+
+      const { controller } = setupController();
+
+      const balances = await controller.getErc20Balances({
+        chainId,
+        accountAddress: account,
+        tokenAddresses: [tokenA, tokenB],
+      });
+
+      expect(balances).toStrictEqual({
+        [tokenA]: toHex(bal1),
+        [tokenB]: toHex(bal2), // zero balance is still a success
+      });
+    });
+
+    it('returns **null** for tokens whose `balanceOf` call failed', async () => {
+      jest.spyOn(multicall, 'multicallOrFallback').mockResolvedValueOnce([
+        { success: false, value: null },
+        { success: true, value: new BN(7) },
+      ]);
+
+      const { controller } = setupController();
+
+      const balances = await controller.getErc20Balances({
+        chainId,
+        accountAddress: account,
+        tokenAddresses: [tokenA, tokenB],
+      });
+
+      expect(balances).toStrictEqual({
+        [tokenA]: null, // failed call
+        [tokenB]: toHex(7), // succeeded call
+      });
+    });
+  });
 });

packages/assets-controllers/src/TokenBalancesController.ts

@@ -411,6 +411,86 @@ export class TokenBalancesController extends StaticIntervalPollingController<Tok
     }
   }
 
+  /**
+   * Get an Ethers.js Web3Provider for the requested chain.
+   *
+   * @param chainId - The chain id to get the provider for.
+   * @returns The provider for the given chain id.
+   */
+  #getProvider(chainId: Hex): Web3Provider {
+    return new Web3Provider(this.#getNetworkClient(chainId).provider);
+  }
+
+  /**
+   * Internal util: run `balanceOf` for an arbitrary set of account/token pairs.
+   *
+   * @param params - The parameters for the balance fetch.
+   * @param params.chainId - The chain id to fetch balances on.
+   * @param params.pairs - The account/token pairs to fetch balances for.
+   * @returns The balances for the given token addresses.
+   */
+  async #batchBalanceOf({
+    chainId,
+    pairs,
+  }: {
+    chainId: Hex;
+    pairs: { accountAddress: Hex; tokenAddress: Hex }[];
+  }): Promise<MulticallResult[]> {
+    if (!pairs.length) {
+      return [];
+    }
+
+    const provider = this.#getProvider(chainId);
+
+    const calls = pairs.map(({ accountAddress, tokenAddress }) => ({
+      contract: new Contract(tokenAddress, abiERC20, provider),
+      functionSignature: 'balanceOf(address)',
+      arguments: [accountAddress],
+    }));
+
+    return multicallOrFallback(calls, chainId, provider);
+  }
+
+  /**
+   * Returns ERC-20 balances for a single account on a single chain.
+   *
+   * @param params - The parameters for the balance fetch.
+   * @param params.chainId - The chain id to fetch balances on.
+   * @param params.accountAddress - The account address to fetch balances for.
+   * @param params.tokenAddresses - The token addresses to fetch balances for.
+   * @returns A mapping from token address to balance (hex) | null.
+   */
+  async getErc20Balances({
+    chainId,
+    accountAddress,
+    tokenAddresses,
+  }: {
+    chainId: Hex;
+    accountAddress: Hex;
+    tokenAddresses: Hex[];
+  }): Promise<Record<Hex, Hex | null>> {
+    // Return early if no token addresses provided
+    if (tokenAddresses.length === 0) {
+      return {};
+    }
+
+    const pairs = tokenAddresses.map((tokenAddress) => ({
+      accountAddress,
+      tokenAddress,
+    }));
+
+    const results = await this.#batchBalanceOf({ chainId, pairs });
+
+    const balances: Record<Hex, Hex | null> = {};
+    tokenAddresses.forEach((tokenAddress, i) => {
+      balances[tokenAddress] = results[i]?.success
+        ? toHex(results[i].value as BN)
+        : null;
+    });
+
+    return balances;
+  }
+
   /**
    * Updates token balances for the given chain id.
    * @param input - The input for the update.
@@ -448,19 +528,10 @@ export class TokenBalancesController extends StaticIntervalPollingController<Tok
     );
 
     if (accountTokenPairs.length > 0) {
-      const provider = new Web3Provider(
-        this.#getNetworkClient(chainId).provider,
-      );
-
-      const calls = accountTokenPairs.map(
-        ({ accountAddress, tokenAddress }) => ({
-          contract: new Contract(tokenAddress, abiERC20, provider),
-          functionSignature: 'balanceOf(address)',
-          arguments: [accountAddress],
-        }),
-      );
-
-      results = await multicallOrFallback(calls, chainId, provider);
+      results = await this.#batchBalanceOf({
+        chainId,
+        pairs: accountTokenPairs,
+      });
     }
 
     const updatedResults: (MulticallResult & {