feat: fetch networks with transaction activity by accounts (#5551)

## Explanation

Currently, our client manually adds networks and checks user activity
one network at a time. This is inefficient and doesn't scale well.

This PR introduces a more efficient approach by:
1. Adding a new API integration that fetches active networks for
multiple accounts in a single request
2. Managing network activity state through the controller
3. Adding type-safe methods to handle both EVM and non-EVM accounts
4. Extracting network fetching logic into a dedicated service layer

Key additions:
- `getNetworksWithTransactionActivityByAccounts`: Fetches active
networks for accounts
- `MultichainNetworkService`: New service layer handling network
activity fetching
- Enhanced state management for network configurations and activity
- Improved error handling and fallback mechanisms

The new implementation:
- Reduces API calls through batch fetching
- Improves separation of concerns with dedicated service layer
- Enhances type safety and error handling
- Provides better state management with fallbacks

PRs for Client Integration
[Extension](MetaMask/metamask-extension#31414)
[Mobile](MetaMask/metamask-mobile#14348)

## References

Related to [#4469
](MetaMask/MetaMask-planning#4469)

## Changelog

<!--
If you're making any consumer-facing changes, list those changes here as
if you were updating a changelog, using the template below as a guide.

(CATEGORY is one of BREAKING, ADDED, CHANGED, DEPRECATED, REMOVED, or
FIXED. For security-related issues, follow the Security Advisory
process.)

Please take care to name the exact pieces of the API you've added or
changed (e.g. types, interfaces, functions, or methods).

If there are any breaking changes, make sure to offer a solution for
consumers to follow once they upgrade to the changes.

Finally, if you're only making changes to development scripts or tests,
you may replace the template below with "None".
-->

### `@metamask/multichain-network-controller`

- **ADDED**: New method `getNetworksWithTransactionActivityByAccounts`
to fetch active networks for accounts
- **ADDED**: New `MultichainNetworkServiceController` for handling
network activity fetching
- **ADDED**: New types for network activity state and responses

- **CHANGED**: Enhanced error handling for network requests
- **CHANGED**: Improved type safety for messenger actions
- **CHANGED**: Updated state management for network activity

## Checklist

- [x] I've updated the test suite for new or updated code as appropriate
- [x] I've updated documentation (JSDoc, Markdown, etc.) for new or
updated code as appropriate
- [x] I've highlighted breaking changes using the "BREAKING" category
above as appropriate
- [x] I've prepared draft pull requests for clients and consumer
packages to resolve any breaking changes

---------

Co-authored-by: Charly Chevalier <[email protected]>

Author: vinnyhoward

packages/multichain-network-controller/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- New method `getNetworksWithTransactionActivityByAccounts` to fetch active networks for multiple accounts in a single request ([#5551](https://github.com/MetaMask/core/pull/5551))
+- New `MultichainNetworkService` for handling network activity fetching ([#5551](https://github.com/MetaMask/core/pull/5551))
+- New types for network activity state and responses ([#5551](https://github.com/MetaMask/core/pull/5551))
+
+### Changed
+
+- Updated state management for network activity ([#5551](https://github.com/MetaMask/core/pull/5551))
+
 ## [0.4.0]
 
 ### Added

packages/multichain-network-controller/package.json

@@ -48,7 +48,10 @@
   },
   "dependencies": {
     "@metamask/base-controller": "^8.0.0",
+    "@metamask/controller-utils": "^11.7.0",
     "@metamask/keyring-api": "^17.4.0",
+    "@metamask/keyring-internal-api": "^6.0.1",
+    "@metamask/superstruct": "^3.1.0",
     "@metamask/utils": "^11.2.0",
     "@solana/addresses": "^2.0.0"
   },

packages/multichain-network-controller/src/MultichainNetworkController.test.ts renamed to packages/multichain-network-controller/src/MultichainNetworkController/MultichainNetworkController.test.ts

@@ -8,6 +8,7 @@ import {
   SolAccountType,
   type KeyringAccountType,
   type CaipChainId,
+  EthScope,
 } from '@metamask/keyring-api';
 import type {
   NetworkControllerGetStateAction,
@@ -16,17 +17,36 @@ import type {
   NetworkControllerRemoveNetworkAction,
   NetworkControllerFindNetworkClientIdByChainIdAction,
 } from '@metamask/network-controller';
+import { KnownCaipNamespace, type CaipAccountId } from '@metamask/utils';
 
-import { getDefaultMultichainNetworkControllerState } from './constants';
 import { MultichainNetworkController } from './MultichainNetworkController';
+import { createMockInternalAccount } from '../../tests/utils';
+import { type ActiveNetworksResponse } from '../api/accounts-api';
+import { getDefaultMultichainNetworkControllerState } from '../constants';
+import type { AbstractMultichainNetworkService } from '../MultichainNetworkService/AbstractMultichainNetworkService';
 import {
   type AllowedActions,
   type AllowedEvents,
   type MultichainNetworkControllerAllowedActions,
   type MultichainNetworkControllerAllowedEvents,
   MULTICHAIN_NETWORK_CONTROLLER_NAME,
-} from './types';
-import { createMockInternalAccount } from '../tests/utils';
+} from '../types';
+
+/**
+ * Creates a mock network service for testing.
+ *
+ * @param mockResponse - The mock response to return from fetchNetworkActivity
+ * @returns A mock network service that implements the MultichainNetworkService interface.
+ */
+function createMockNetworkService(
+  mockResponse: ActiveNetworksResponse = { activeNetworks: [] },
+): AbstractMultichainNetworkService {
+  return {
+    fetchNetworkActivity: jest
+      .fn<Promise<ActiveNetworksResponse>, [CaipAccountId[]]>()
+      .mockResolvedValue(mockResponse),
+  };
+}
 
 /**
  * Setup a test controller instance.
@@ -38,6 +58,7 @@ import { createMockInternalAccount } from '../tests/utils';
  * @param args.removeNetwork - Mock for NetworkController:removeNetwork action.
  * @param args.getSelectedChainId - Mock for NetworkController:getSelectedChainId action.
  * @param args.findNetworkClientIdByChainId - Mock for NetworkController:findNetworkClientIdByChainId action.
+ * @param args.mockNetworkService - Mock for MultichainNetworkService.
  * @returns A collection of test controllers and mocks.
  */
 function setupController({
@@ -47,6 +68,7 @@ function setupController({
   removeNetwork,
   getSelectedChainId,
   findNetworkClientIdByChainId,
+  mockNetworkService,
 }: {
   options?: Partial<
     ConstructorParameters<typeof MultichainNetworkController>[0]
@@ -71,6 +93,7 @@ function setupController({
     ReturnType<NetworkControllerFindNetworkClientIdByChainIdAction['handler']>,
     Parameters<NetworkControllerFindNetworkClientIdByChainIdAction['handler']>
   >;
+  mockNetworkService?: AbstractMultichainNetworkService;
 } = {}) {
   const messenger = new Messenger<
     MultichainNetworkControllerAllowedActions,
@@ -149,18 +172,21 @@ function setupController({
       'NetworkController:removeNetwork',
       'NetworkController:getSelectedChainId',
       'NetworkController:findNetworkClientIdByChainId',
+      'AccountsController:listMultichainAccounts',
     ],
     allowedEvents: ['AccountsController:selectedAccountChange'],
   });
 
-  // Default state to use Solana network with EVM as active network
+  const defaultNetworkService = createMockNetworkService();
+
   const controller = new MultichainNetworkController({
-    messenger: options.messenger || controllerMessenger,
+    messenger: options.messenger ?? controllerMessenger,
     state: {
       selectedMultichainNetworkChainId: SolScope.Mainnet,
       isEvmSelected: true,
       ...options.state,
     },
+    networkService: mockNetworkService ?? defaultNetworkService,
   });
 
   const triggerSelectedAccountChange = (accountType: KeyringAccountType) => {
@@ -191,6 +217,7 @@ function setupController({
     mockFindNetworkClientIdByChainId,
     publishSpy,
     triggerSelectedAccountChange,
+    networkService: mockNetworkService ?? defaultNetworkService,
   };
 }
 
@@ -545,4 +572,124 @@ describe('MultichainNetworkController', () => {
       );
     });
   });
+
+  describe('getNetworksWithTransactionActivityByAccounts', () => {
+    const MOCK_EVM_ADDRESS = '0x1234567890123456789012345678901234567890';
+    const MOCK_SOLANA_ADDRESS = 'solana123';
+    const MOCK_EVM_CHAIN_1 = '1';
+    const MOCK_EVM_CHAIN_137 = '137';
+    const MOCK_SOLANA_CHAIN = '5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp';
+
+    it('returns empty object when no accounts exist', async () => {
+      const { controller, messenger } = setupController({
+        getSelectedChainId: jest.fn().mockReturnValue('0x1'),
+      });
+
+      messenger.registerActionHandler(
+        'AccountsController:listMultichainAccounts',
+        () => [],
+      );
+
+      const result =
+        await controller.getNetworksWithTransactionActivityByAccounts();
+      expect(result).toStrictEqual({});
+    });
+
+    it('fetches and formats network activity for EVM accounts', async () => {
+      const mockResponse: ActiveNetworksResponse = {
+        activeNetworks: [
+          `${KnownCaipNamespace.Eip155}:${MOCK_EVM_CHAIN_1}:${MOCK_EVM_ADDRESS}`,
+          `${KnownCaipNamespace.Eip155}:${MOCK_EVM_CHAIN_137}:${MOCK_EVM_ADDRESS}`,
+        ],
+      };
+
+      const mockNetworkService = createMockNetworkService(mockResponse);
+      await mockNetworkService.fetchNetworkActivity([
+        `${KnownCaipNamespace.Eip155}:${MOCK_EVM_CHAIN_1}:${MOCK_EVM_ADDRESS}`,
+      ]);
+
+      const { controller, messenger } = setupController({
+        mockNetworkService,
+      });
+
+      messenger.registerActionHandler(
+        'AccountsController:listMultichainAccounts',
+        () => [
+          createMockInternalAccount({
+            type: EthAccountType.Eoa,
+            address: MOCK_EVM_ADDRESS,
+            scopes: [EthScope.Eoa],
+          }),
+        ],
+      );
+
+      const result =
+        await controller.getNetworksWithTransactionActivityByAccounts();
+
+      expect(mockNetworkService.fetchNetworkActivity).toHaveBeenCalledWith([
+        `${KnownCaipNamespace.Eip155}:0:${MOCK_EVM_ADDRESS}`,
+      ]);
+
+      expect(result).toStrictEqual({
+        [MOCK_EVM_ADDRESS]: {
+          namespace: KnownCaipNamespace.Eip155,
+          activeChains: [MOCK_EVM_CHAIN_1, MOCK_EVM_CHAIN_137],
+        },
+      });
+    });
+
+    it('formats network activity for mixed EVM and non-EVM accounts', async () => {
+      const mockResponse: ActiveNetworksResponse = {
+        activeNetworks: [
+          `${KnownCaipNamespace.Eip155}:${MOCK_EVM_CHAIN_1}:${MOCK_EVM_ADDRESS}`,
+          `${KnownCaipNamespace.Solana}:${MOCK_SOLANA_CHAIN}:${MOCK_SOLANA_ADDRESS}`,
+        ],
+      };
+
+      const mockNetworkService = createMockNetworkService(mockResponse);
+      await mockNetworkService.fetchNetworkActivity([
+        `${KnownCaipNamespace.Eip155}:${MOCK_EVM_CHAIN_1}:${MOCK_EVM_ADDRESS}`,
+        `${KnownCaipNamespace.Solana}:${MOCK_SOLANA_CHAIN}:${MOCK_SOLANA_ADDRESS}`,
+      ]);
+
+      const { controller, messenger } = setupController({
+        mockNetworkService,
+      });
+
+      messenger.registerActionHandler(
+        'AccountsController:listMultichainAccounts',
+        () => [
+          createMockInternalAccount({
+            type: EthAccountType.Eoa,
+            address: MOCK_EVM_ADDRESS,
+            scopes: [EthScope.Eoa],
+          }),
+          createMockInternalAccount({
+            type: SolAccountType.DataAccount,
+            address: MOCK_SOLANA_ADDRESS,
+            scopes: [SolScope.Mainnet],
+          }),
+        ],
+      );
+
+      const result =
+        await controller.getNetworksWithTransactionActivityByAccounts();
+
+      expect(mockNetworkService.fetchNetworkActivity).toHaveBeenCalledWith([
+        `${KnownCaipNamespace.Eip155}:0:${MOCK_EVM_ADDRESS}`,
+        `${KnownCaipNamespace.Solana}:${MOCK_SOLANA_CHAIN}:${MOCK_SOLANA_ADDRESS}`,
+      ]);
+
+      expect(result).toStrictEqual({
+        [MOCK_EVM_ADDRESS]: {
+          namespace: KnownCaipNamespace.Eip155,
+          activeChains: [MOCK_EVM_CHAIN_1],
+        },
+        [MOCK_SOLANA_ADDRESS]: {
+          namespace: KnownCaipNamespace.Solana,
+          activeChains: [MOCK_SOLANA_CHAIN],
+        },
+      });
+    });
+  });
 });

packages/multichain-network-controller/src/MultichainNetworkController.ts renamed to packages/multichain-network-controller/src/MultichainNetworkController/MultichainNetworkController.ts

@@ -4,23 +4,29 @@ import type { InternalAccount } from '@metamask/keyring-internal-api';
 import type { NetworkClientId } from '@metamask/network-controller';
 import { type CaipChainId, isCaipChainId } from '@metamask/utils';
 
+import {
+  type ActiveNetworksByAddress,
+  toAllowedCaipAccountIds,
+  toActiveNetworksByAddress,
+} from '../api/accounts-api';
 import {
   AVAILABLE_MULTICHAIN_NETWORK_CONFIGURATIONS,
   MULTICHAIN_NETWORK_CONTROLLER_METADATA,
   getDefaultMultichainNetworkControllerState,
-} from './constants';
+} from '../constants';
+import type { AbstractMultichainNetworkService } from '../MultichainNetworkService/AbstractMultichainNetworkService';
 import {
   MULTICHAIN_NETWORK_CONTROLLER_NAME,
   type MultichainNetworkControllerState,
   type MultichainNetworkControllerMessenger,
   type SupportedCaipChainId,
-} from './types';
+} from '../types';
 import {
   checkIfSupportedCaipChainId,
   getChainIdForNonEvmAddress,
   convertEvmCaipToHexChainId,
   isEvmCaipChainId,
-} from './utils';
+} from '../utils';
 
 /**
  * The MultichainNetworkController is responsible for fetching and caching account
@@ -31,15 +37,19 @@ export class MultichainNetworkController extends BaseController<
   MultichainNetworkControllerState,
   MultichainNetworkControllerMessenger
 > {
+  readonly #networkService: AbstractMultichainNetworkService;
+
   constructor({
     messenger,
     state,
+    networkService,
   }: {
     messenger: MultichainNetworkControllerMessenger;
     state?: Omit<
       Partial<MultichainNetworkControllerState>,
       'multichainNetworkConfigurationsByChainId'
     >;
+    networkService: AbstractMultichainNetworkService;
   }) {
     super({
       messenger,
@@ -55,6 +65,7 @@ export class MultichainNetworkController extends BaseController<
       },
     });
 
+    this.#networkService = networkService;
     this.#subscribeToMessageEvents();
     this.#registerMessageHandlers();
   }
@@ -144,6 +155,35 @@ export class MultichainNetworkController extends BaseController<
     return await this.#setActiveEvmNetwork(id);
   }
 
+  /**
+   * Returns the active networks for the available EVM addresses (non-EVM networks will be supported in the future).
+   * Fetches the data from the API and caches it in state.
+   *
+   * @returns A promise that resolves to the active networks for the available addresses
+   */
+  async getNetworksWithTransactionActivityByAccounts(): Promise<ActiveNetworksByAddress> {
+    const accounts = this.messagingSystem.call(
+      'AccountsController:listMultichainAccounts',
+    );
+    if (!accounts || accounts.length === 0) {
+      return this.state.networksWithTransactionActivity;
+    }
+
+    const formattedAccounts = accounts
+      .map((account: InternalAccount) => toAllowedCaipAccountIds(account))
+      .flat();
+
+    const activeNetworks =
+      await this.#networkService.fetchNetworkActivity(formattedAccounts);
+    const formattedNetworks = toActiveNetworksByAddress(activeNetworks);
+
+    this.update((state) => {
+      state.networksWithTransactionActivity = formattedNetworks;
+    });
+
+    return this.state.networksWithTransactionActivity;
+  }
+
   /**
    * Removes an EVM network from the list of networks.
    * This method re-directs the request to the network-controller.
@@ -268,5 +308,9 @@ export class MultichainNetworkController extends BaseController<
       'MultichainNetworkController:setActiveNetwork',
       this.setActiveNetwork.bind(this),
     );
+    this.messagingSystem.registerActionHandler(
+      'MultichainNetworkController:getNetworksWithTransactionActivityByAccounts',
+      this.getNetworksWithTransactionActivityByAccounts.bind(this),
+    );
   }
 }

packages/multichain-network-controller/src/MultichainNetworkService/AbstractMultichainNetworkService.ts

@@ -0,0 +1,9 @@
+import type { PublicInterface } from '@metamask/utils';
+
+import type { MultichainNetworkService } from './MultichainNetworkService';
+
+/**
+ * A service object which is responsible for fetching network activity data.
+ */
+export type AbstractMultichainNetworkService =
+  PublicInterface<MultichainNetworkService>;