feat(multichain-account-service): add :walletStatusChange event + mutex for concurrent mutable operations

Author: ccharly

package.json

@@ -47,7 +47,8 @@
   "resolutions": {
     "[email protected]": "^6.5.7",
     "fast-xml-parser@^4.3.4": "^4.4.1",
-    "[email protected]": "^7.5.10"
+    "[email protected]": "^7.5.10",
+    "@metamask/account-api@^0.9.0": "npm:@metamask-previews/[email protected]"
   },
   "devDependencies": {
     "@babel/core": "^7.23.5",

packages/multichain-account-service/CHANGELOG.md

@@ -9,12 +9,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- Add mutable operation lock (per wallets) ([#6527](https://github.com/MetaMask/core/pull/6527))
+  - Operations such as discovery, alignment, group creation will now lock an internal mutex (per wallets).
+- Add wallet status tracking with `:walletStatusChange` event ([#6527](https://github.com/MetaMask/core/pull/6527))
+  - This can be used to track what's the current status of a wallet (e.g. which operation is currently running OR if the wallet is ready to run any new operations).
+- Add `MultichainAccountWalletStatus` enum ([#6527](https://github.com/MetaMask/core/pull/6527))
+  - Enumeration of all possible wallet statuses.
+- Add `MultichainAccountWallet.status` ([#6527](https://github.com/MetaMask/core/pull/6527))
+  - To get the current status of a multichain account wallet instance.
 - Add multichain account group lifecycle events ([#6441](https://github.com/MetaMask/core/pull/6441))
   - Add `multichainAccountGroupCreated` event emitted from wallet level when new groups are created.
   - Add `multichainAccountGroupUpdated` event emitted from wallet level when groups are synchronized.
 
 ### Changed
 
+- **BREAKING:** Remove `MultichainAccountService:getIsAlignementInProgress` action ([#6527](https://github.com/MetaMask/core/pull/6527))
+  - This is now being replaced with the wallet's status logic.
 - Bump `@metamask/keyring-api` from `^20.1.0` to `^21.0.0` ([#6560](https://github.com/MetaMask/core/pull/6560))
 - Bump `@metamask/keyring-internal-api` from `^8.1.0` to `^9.0.0` ([#6560](https://github.com/MetaMask/core/pull/6560))
 - Bump `@metamask/keyring-snap-client` from `^7.0.0` to `^8.0.0` ([#6560](https://github.com/MetaMask/core/pull/6560))

packages/multichain-account-service/package.json

@@ -56,7 +56,8 @@
     "@metamask/snaps-sdk": "^9.0.0",
     "@metamask/snaps-utils": "^11.0.0",
     "@metamask/superstruct": "^3.1.0",
-    "@metamask/utils": "^11.4.2"
+    "@metamask/utils": "^11.4.2",
+    "async-mutex": "^0.5.0"
   },
   "devDependencies": {
     "@metamask/account-api": "^0.12.0",

packages/multichain-account-service/src/MultichainAccountGroup.test.ts

@@ -5,6 +5,7 @@ import {
   toMultichainAccountGroupId,
   toMultichainAccountWalletId,
 } from '@metamask/account-api';
+import type { Messenger } from '@metamask/base-controller';
 import { EthScope, SolScope } from '@metamask/keyring-api';
 import type { InternalAccount } from '@metamask/keyring-internal-api';
 
@@ -18,13 +19,20 @@ import {
   MOCK_WALLET_1_ENTROPY_SOURCE,
   MOCK_WALLET_1_EVM_ACCOUNT,
   MOCK_WALLET_1_SOL_ACCOUNT,
-  setupAccountProvider,
+  setupNamedAccountProvider,
   getMultichainAccountServiceMessenger,
   getRootMessenger,
 } from './tests';
+import type {
+  AllowedActions,
+  AllowedEvents,
+  MultichainAccountServiceActions,
+  MultichainAccountServiceEvents,
+} from './types';
 
 function setup({
   groupIndex = 0,
+  messenger = getRootMessenger(),
   accounts = [
     [MOCK_WALLET_1_EVM_ACCOUNT],
     [
@@ -34,26 +42,33 @@ function setup({
       MOCK_SNAP_ACCOUNT_2, // Non-BIP-44 account.
     ],
   ],
-}: { groupIndex?: number; accounts?: InternalAccount[][] } = {}): {
+}: {
+  groupIndex?: number;
+  messenger?: Messenger<
+    MultichainAccountServiceActions | AllowedActions,
+    MultichainAccountServiceEvents | AllowedEvents
+  >;
+  accounts?: InternalAccount[][];
+} = {}): {
   wallet: MultichainAccountWallet<Bip44Account<InternalAccount>>;
   group: MultichainAccountGroup<Bip44Account<InternalAccount>>;
   providers: MockAccountProvider[];
 } {
   const providers = accounts.map((providerAccounts) => {
-    return setupAccountProvider({ accounts: providerAccounts });
+    return setupNamedAccountProvider({ accounts: providerAccounts });
   });
 
   const wallet = new MultichainAccountWallet<Bip44Account<InternalAccount>>({
-    providers,
     entropySource: MOCK_WALLET_1_ENTROPY_SOURCE,
-    messenger: getMultichainAccountServiceMessenger(getRootMessenger()),
+    messenger: getMultichainAccountServiceMessenger(messenger),
+    providers,
   });
 
   const group = new MultichainAccountGroup({
     wallet,
     groupIndex,
     providers,
-    messenger: getMultichainAccountServiceMessenger(getRootMessenger()),
+    messenger: getMultichainAccountServiceMessenger(messenger),
   });
 
   return { wallet, group, providers };

packages/multichain-account-service/src/MultichainAccountService.test.ts

@@ -26,7 +26,7 @@ import {
   getRootMessenger,
   makeMockAccountProvider,
   mockAsInternalAccount,
-  setupAccountProvider,
+  setupNamedAccountProvider,
 } from './tests';
 import type {
   AllowedActions,
@@ -72,7 +72,7 @@ function mockAccountProvider<Provider>(
     .mocked(providerClass)
     .mockImplementation(() => mocks as unknown as Provider);
 
-  setupAccountProvider({
+  setupNamedAccountProvider({
     mocks,
     accounts,
     filter: (account) => account.type === type,
@@ -692,58 +692,6 @@ describe('MultichainAccountService', () => {
     });
   });
 
-  describe('getIsAlignmentInProgress', () => {
-    it('returns false initially', () => {
-      const { service } = setup({
-        accounts: [MOCK_HD_ACCOUNT_1],
-      });
-      expect(service.getIsAlignmentInProgress()).toBe(false);
-    });
-
-    it('returns true during alignWallets and false after completion', async () => {
-      const { service } = setup({
-        accounts: [MOCK_HD_ACCOUNT_1],
-      });
-
-      const alignmentPromise = service.alignWallets();
-      expect(service.getIsAlignmentInProgress()).toBe(true);
-
-      await alignmentPromise;
-      expect(service.getIsAlignmentInProgress()).toBe(false);
-    });
-
-    it('returns true during alignWallet and false after completion', async () => {
-      const { service } = setup({
-        accounts: [MOCK_HD_ACCOUNT_1],
-      });
-
-      const alignmentPromise = service.alignWallet(
-        MOCK_HD_KEYRING_1.metadata.id,
-      );
-      expect(service.getIsAlignmentInProgress()).toBe(true);
-
-      await alignmentPromise;
-      expect(service.getIsAlignmentInProgress()).toBe(false);
-    });
-
-    it('returns false after alignment completes even with provider errors', async () => {
-      const { service, mocks } = setup({
-        accounts: [MOCK_HD_ACCOUNT_1],
-      });
-
-      // Mock a provider error during alignment
-      mocks.EvmAccountProvider.createAccounts.mockRejectedValueOnce(
-        new Error('Test error'),
-      );
-
-      // Alignment should complete gracefully without throwing
-      await service.alignWallets();
-
-      // Flag should be reset even after provider errors
-      expect(service.getIsAlignmentInProgress()).toBe(false);
-    });
-  });
-
   describe('actions', () => {
     it('gets a multichain account with MultichainAccountService:getMultichainAccount', () => {
       const accounts = [MOCK_HD_ACCOUNT_1];
@@ -885,18 +833,6 @@ describe('MultichainAccountService', () => {
         ),
       ).toBeUndefined();
     });
-
-    it('gets alignment progress with MultichainAccountService:getIsAlignmentInProgress', () => {
-      const { messenger } = setup({
-        accounts: [MOCK_HD_ACCOUNT_1],
-      });
-
-      const isInProgress = messenger.call(
-        'MultichainAccountService:getIsAlignmentInProgress',
-      );
-
-      expect(isInProgress).toBe(false);
-    });
   });
 
   describe('setBasicFunctionality', () => {

packages/multichain-account-service/src/MultichainAccountService.ts

@@ -120,10 +120,6 @@ export class MultichainAccountService {
       'MultichainAccountService:alignWallet',
       (...args) => this.alignWallet(...args),
     );
-    this.#messenger.registerActionHandler(
-      'MultichainAccountService:getIsAlignmentInProgress',
-      () => this.getIsAlignmentInProgress(),
-    );
     this.#messenger.subscribe('AccountsController:accountAdded', (account) =>
       this.#handleOnAccountAdded(account),
     );
@@ -397,17 +393,6 @@ export class MultichainAccountService {
     }
   }
 
-  /**
-   * Gets whether wallet alignment is currently in progress.
-   *
-   * @returns True if any wallet alignment is in progress, false otherwise.
-   */
-  getIsAlignmentInProgress(): boolean {
-    return Array.from(this.#wallets.values()).some((wallet) =>
-      wallet.getIsAlignmentInProgress(),
-    );
-  }
-
   /**
    * Align all multichain account wallets.
    */