feat: add group.status

packages/account-tree-controller/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- **BREAKING:** Expose `status` on `AccountGroupMultichainAccountObject` ([#9104](https://github.com/MetaMask/core/pull/9104))
+  - The controller now requires the new event `MultichainAccountService:groupStatusChange`.
+  - The field reflects `MultichainAccountGroupStatus` and is kept in sync via the new `MultichainAccountService:groupStatusChange` event subscription.
+
 ### Changed
 
 - Bump `@metamask/utils` from `^11.9.0` to `^11.11.0` ([#9074](https://github.com/MetaMask/core/pull/9074))

packages/account-tree-controller/src/AccountTreeController.test.ts

@@ -254,6 +254,7 @@ const MOCK_PREPOPULATED_STATE: Partial<AccountTreeControllerState> = {
           [MOCK_PREPOPULATED_GROUP_ID]: {
             id: MOCK_PREPOPULATED_GROUP_ID,
             type: AccountGroupType.MultichainAccount,
+            status: 'uninitialized',
             accounts: [MOCK_HD_ACCOUNT_1.id],
             metadata: {
               name: 'Account 1',
@@ -562,6 +563,7 @@ describe('AccountTreeController', () => {
                 [expectedWalletId1Group]: {
                   id: expectedWalletId1Group,
                   type: AccountGroupType.MultichainAccount,
+                  status: 'uninitialized',
                   accounts: [MOCK_HD_ACCOUNT_1.id],
                   metadata: {
                     name: 'Account 1',
@@ -589,6 +591,7 @@ describe('AccountTreeController', () => {
                 [expectedWalletId2Group1]: {
                   id: expectedWalletId2Group1,
                   type: AccountGroupType.MultichainAccount,
+                  status: 'uninitialized',
                   accounts: [MOCK_HD_ACCOUNT_2.id],
                   metadata: {
                     name: 'Account 1', // Updated: per-wallet numbering (wallet 2, account 1)
@@ -603,6 +606,7 @@ describe('AccountTreeController', () => {
                 [expectedWalletId2Group2]: {
                   id: expectedWalletId2Group2,
                   type: AccountGroupType.MultichainAccount,
+                  status: 'uninitialized',
                   accounts: [MOCK_SNAP_ACCOUNT_1.id],
                   metadata: {
                     name: 'Account 2', // Updated: per-wallet sequential numbering (wallet 2, account 2)
@@ -1286,6 +1290,7 @@ describe('AccountTreeController', () => {
                 [walletId1Group]: {
                   id: walletId1Group,
                   type: AccountGroupType.MultichainAccount,
+                  status: 'uninitialized',
                   metadata: {
                     name: 'Account 1',
                     entropy: {
@@ -1377,6 +1382,7 @@ describe('AccountTreeController', () => {
                 [walletId1Group2]: {
                   id: walletId1Group2,
                   type: AccountGroupType.MultichainAccount,
+                  status: 'uninitialized',
                   metadata: {
                     name: 'Account 2',
                     entropy: {
@@ -1612,6 +1618,7 @@ describe('AccountTreeController', () => {
                 [walletId1Group]: {
                   id: walletId1Group,
                   type: AccountGroupType.MultichainAccount,
+                  status: 'uninitialized',
                   metadata: {
                     name: 'Account 1',
                     entropy: {
@@ -1720,6 +1727,7 @@ describe('AccountTreeController', () => {
                 [walletId1Group]: {
                   id: walletId1Group,
                   type: AccountGroupType.MultichainAccount,
+                  status: 'uninitialized',
                   metadata: {
                     name: 'Account 1',
                     entropy: {
@@ -1748,6 +1756,7 @@ describe('AccountTreeController', () => {
                 [walletId2Group]: {
                   id: walletId2Group,
                   type: AccountGroupType.MultichainAccount,
+                  status: 'uninitialized',
                   metadata: {
                     name: 'Account 1', // Updated: per-wallet naming (different wallet)
                     entropy: {
@@ -1871,6 +1880,57 @@ describe('AccountTreeController', () => {
     });
   });
 
+  describe('on MultichainAccountService:groupStatusChange', () => {
+    it('updates the group status when the event is published', () => {
+      const { controller, messenger } = setup({
+        accounts: [MOCK_HD_ACCOUNT_1],
+        keyrings: [MOCK_HD_KEYRING_1],
+      });
+      controller.init();
+
+      const walletId = MOCK_PREPOPULATED_WALLET_ID;
+      const groupId = MOCK_PREPOPULATED_GROUP_ID;
+
+      expect(
+        controller.state.accountTree.wallets[walletId]?.groups[groupId]?.status,
+      ).toBe('uninitialized');
+
+      messenger.publish(
+        'MultichainAccountService:groupStatusChange',
+        groupId,
+        'in-progress:alignment',
+      );
+      expect(
+        controller.state.accountTree.wallets[walletId]?.groups[groupId]?.status,
+      ).toBe('in-progress:alignment');
+
+      messenger.publish(
+        'MultichainAccountService:groupStatusChange',
+        groupId,
+        'aligned',
+      );
+      expect(
+        controller.state.accountTree.wallets[walletId]?.groups[groupId]?.status,
+      ).toBe('aligned');
+    });
+
+    it('does nothing when the group ID is unknown', () => {
+      const { controller, messenger } = setup({
+        accounts: [MOCK_HD_ACCOUNT_1],
+        keyrings: [MOCK_HD_KEYRING_1],
+      });
+      controller.init();
+
+      expect(() =>
+        messenger.publish(
+          'MultichainAccountService:groupStatusChange',
+          'unknown-group-id' as ReturnType<typeof toMultichainAccountGroupId>,
+          'aligned',
+        ),
+      ).not.toThrow();
+    });
+  });
+
   describe('getAccountWalletObject', () => {
     it('gets a wallet using its ID', () => {
       const { controller } = setup({

packages/account-tree-controller/src/AccountTreeController.ts

@@ -1,10 +1,14 @@
-import { AccountWalletType, select } from '@metamask/account-api';
+import {
+  AccountGroupType,
+  AccountWalletType,
+  select,
+} from '@metamask/account-api';
 import type {
   AccountGroupId,
   AccountWalletId,
   AccountSelector,
+  MultichainAccountGroupId,
   MultichainAccountWalletId,
-  AccountGroupType,
 } from '@metamask/account-api';
 import type { MultichainAccountWalletStatus } from '@metamask/account-api';
 import type { AccountId } from '@metamask/accounts-controller';
@@ -13,6 +17,7 @@ import { BaseController } from '@metamask/base-controller';
 import type { TraceCallback } from '@metamask/controller-utils';
 import { isEvmAccountType } from '@metamask/keyring-api';
 import type { InternalAccount } from '@metamask/keyring-internal-api';
+import type { MultichainAccountGroupStatus } from '@metamask/multichain-account-service';
 import { assert } from '@metamask/utils';
 
 import type { BackupAndSyncEmitAnalyticsEventParams } from './backup-and-sync/analytics';
@@ -277,6 +282,13 @@ export class AccountTreeController extends BaseController<
       },
     );
 
+    this.messenger.subscribe(
+      'MultichainAccountService:groupStatusChange',
+      (groupId, status) => {
+        this.#handleMultichainAccountGroupStatusChange(groupId, status);
+      },
+    );
+
     this.messenger.registerMethodActionHandlers(
       this,
       MESSENGER_EXPOSED_METHODS,
@@ -1173,6 +1185,11 @@ export class AccountTreeController extends BaseController<
         ...result.group,
         // Type-wise, we are guaranteed to always have at least 1 account.
         accounts: [id],
+        // Entropy (multichain) groups start as 'uninitialized'; the service will
+        // publish a groupStatusChange event to set the real status shortly after.
+        ...(result.group.type === AccountGroupType.MultichainAccount && {
+          status: 'uninitialized',
+        }),
         metadata: {
           name: '',
           ...{ pinned: false, hidden: false, lastSelected: 0 }, // Default UI states
@@ -1423,6 +1440,28 @@ export class AccountTreeController extends BaseController<
     });
   }
 
+  /**
+   * Handles multichain account group status change from
+   * the MultichainAccountService.
+   *
+   * @param groupId - Multichain account group ID.
+   * @param groupStatus - New multichain account group status.
+   */
+  #handleMultichainAccountGroupStatusChange(
+    groupId: MultichainAccountGroupId,
+    groupStatus: MultichainAccountGroupStatus,
+  ): void {
+    this.update((state) => {
+      const walletId = this.#groupIdToWalletId.get(groupId);
+      if (walletId) {
+        const group = state.accountTree.wallets[walletId]?.groups[groupId];
+        if (group?.type === AccountGroupType.MultichainAccount) {
+          group.status = groupStatus;
+        }
+      }
+    });
+  }
+
   /**
    * Gets account group object.
    *

packages/account-tree-controller/src/group.ts

@@ -13,6 +13,7 @@ import {
   XlmAccountType,
 } from '@metamask/keyring-api';
 import type { KeyringAccountType } from '@metamask/keyring-api';
+import type { MultichainAccountGroupStatus } from '@metamask/multichain-account-service';
 
 import type { UpdatableField, ExtractFieldValues } from './type-utils';
 import type { AccountTreeControllerState } from './types';
@@ -79,6 +80,7 @@ type IsAccountGroupObject<
 export type AccountGroupMultichainAccountObject = {
   type: AccountGroupType.MultichainAccount;
   id: MultichainAccountGroupId;
+  status: MultichainAccountGroupStatus;
   // Blockchain Accounts (at least 1 account per multichain-accounts):
   accounts: [AccountId, ...AccountId[]];
   metadata: AccountTreeGroupMetadata & {

packages/account-tree-controller/src/types.ts

@@ -20,7 +20,10 @@ import type {
   MultichainAccountServiceCreateMultichainAccountGroupAction,
   MultichainAccountServiceCreateMultichainAccountGroupsAction,
 } from '@metamask/multichain-account-service';
-import type { MultichainAccountServiceWalletStatusChangeEvent } from '@metamask/multichain-account-service';
+import type {
+  MultichainAccountServiceGroupStatusChangeEvent,
+  MultichainAccountServiceWalletStatusChangeEvent,
+} from '@metamask/multichain-account-service';
 import type {
   AuthenticationController,
   UserStorageController,
@@ -158,7 +161,8 @@ export type AllowedEvents =
   | AccountsControllerAccountsRemovedEvent
   | AccountsControllerSelectedAccountChangeEvent
   | UserStorageController.UserStorageControllerStateChangeEvent
-  | MultichainAccountServiceWalletStatusChangeEvent;
+  | MultichainAccountServiceWalletStatusChangeEvent
+  | MultichainAccountServiceGroupStatusChangeEvent;
 
 export type AccountTreeControllerEvents =
   | AccountTreeControllerStateChangeEvent

packages/account-tree-controller/tests/mockMessenger.ts

@@ -49,6 +49,7 @@ export function getAccountTreeControllerMessenger(
       'AccountsController:selectedAccountChange',
       'UserStorageController:stateChange',
       'MultichainAccountService:walletStatusChange',
+      'MultichainAccountService:groupStatusChange',
     ],
     actions: [
       'AccountsController:listMultichainAccounts',

packages/multichain-account-service/CHANGELOG.md

@@ -16,6 +16,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Use this if you need to access the inner (wrapped) keyring.
 - Add `isAligned` ([#9039](https://github.com/MetaMask/core/pull/9039))
   - This allows callers to cheaply check whether alignment has already occurred before triggering an explicit alignment operation.
+- Add `MultichainAccountGroupStatus` type and `MultichainAccountServiceGroupStatusChangeEvent` event ([#9104](https://github.com/MetaMask/core/pull/9104))
+  - `MultichainAccountGroup` now tracks a `status` field (`'uninitialized' | 'in-progress:create-accounts' | 'in-progress:alignment' | 'aligned' | 'misaligned'`).
+  - The service messenger emits `MultichainAccountService:groupStatusChange` whenever a group's status changes.
 
 ### Changed