fix: should not update balances when app is locked (#7492)

## Explanation

### Current state and why it needs to change

The `AccountTrackerController` previously had inconsistent lock/unlock
handling compared to `TokenBalancesController`:

1. **No lock state tracking**: The controller had no way to track
whether the keyring was locked, meaning it could attempt balance fetches
even when the wallet was locked.

2. **Refresh on unlock**: When `KeyringController:unlock` was fired, it
would immediately trigger a full balance refresh for all networks. This
behavior was unnecessary since polling continues regardless of lock
state.

3. **Refresh all networks on network add**: When a new network was added
via `NetworkController:networkAdded`, the controller would refresh
balances for **all** networks instead of just the newly added one.

### Solution

This PR aligns `AccountTrackerController` with the pattern already
established in `TokenBalancesController`:

1. **Added `#isLocked` property**: Tracks whether the keyring is locked,
initialized from `KeyringController:getState` in the constructor.

2. **Added `isActive` getter**: Returns `true` when the keyring is
unlocked AND the user is onboarded. Balance fetching is skipped when
`isActive` is `false`.

3. **Subscribe to `KeyringController:lock`**: Sets `#isLocked = true`
when the keyring is locked.

4. **Updated `KeyringController:unlock` subscription**: Now only sets
`#isLocked = false` without triggering an immediate refresh. Polling
continues as normal and will fetch balances on the next interval.

5. **Optimized `NetworkController:networkAdded` handler**: Now extracts
the `networkClientId` from the added network configuration and only
refreshes balances for that specific network.

### Breaking changes

- `AccountTrackerController` messenger must now allow
`KeyringController:getState` action
- `AccountTrackerController` messenger must now allow
`KeyringController:lock` event

## References

- Similar pattern exists in `TokenBalancesController` (`#isUnlocked`
property and `isActive` getter)

## 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 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)
- [x] I've introduced [breaking
changes](https://github.com/MetaMask/core/tree/main/docs/breaking-changes.md)
in this PR and have prepared draft pull requests for clients and
consumer packages to resolve them

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> AccountTrackerController now tracks keyring lock state to gate balance
updates, adds isActive, refreshes only the newly added network on
networkAdded, and requires KeyringController:getState and :lock.
> 
> - **AccountTrackerController**
>   - **Lock state & activity gating**:
> - Add `#isLocked` (initialized via `KeyringController:getState`) and
`isActive` getter; skip balance updates when inactive (locked or not
onboarded).
> - Subscribe to `KeyringController:lock`/`unlock` to update lock state;
unlock no longer triggers immediate refresh.
>   - **Network addition behavior**:
> - On `NetworkController:networkAdded`, refresh balances only for the
newly added network’s `networkClientId`.
>   - **Messenger contract (BREAKING)**:
> - Requires `KeyringController:getState` action and
`KeyringController:lock` event in allowed actions/events.
>   - **Tests & docs**:
> - Update tests to publish full `NetworkConfiguration` and assert
`isActive` transitions.
> - Update `CHANGELOG.md` to document breaking changes and behavior
tweaks.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
6c2de6a. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: salimtb

packages/assets-controllers/CHANGELOG.md

@@ -11,6 +11,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Export `selectAllAssets` ([#7496](https://github.com/MetaMask/core/pull/7496))
 
+### Changed
+
+- **BREAKING:** `AccountTrackerController` now requires `KeyringController:getState` action and `KeyringController:lock` event in addition to existing allowed actions and events ([#7492](https://github.com/MetaMask/core/pull/7492))
+  - Added `#isLocked` property to track keyring lock state, initialized from `KeyringController:getState`
+  - Added `isActive` getter that returns `true` when keyring is unlocked and user is onboarded
+  - Balance updates are now skipped when controller is not active (locked or not onboarded)
+  - `KeyringController:unlock` event now only updates lock state without triggering immediate refresh
+  - `KeyringController:lock` event sets controller to inactive state
+- `AccountTrackerController` now only refreshes balances for the newly added network on `NetworkController:networkAdded` event instead of all networks ([#7492](https://github.com/MetaMask/core/pull/7492))
+
 ## [94.1.0]
 
 ### Added

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

@@ -388,10 +388,14 @@ describe('AccountTrackerController', () => {
           stakedBalances: {},
         });
 
-        messenger.publish(
-          'NetworkController:networkAdded',
-          {} as NetworkConfiguration,
-        );
+        messenger.publish('NetworkController:networkAdded', {
+          chainId: '0x1',
+          blockExplorerUrls: [],
+          name: 'Mainnet',
+          nativeCurrency: 'ETH',
+          defaultRpcEndpointIndex: 0,
+          rpcEndpoints: [{ networkClientId: 'mainnet' }],
+        } as unknown as NetworkConfiguration);
 
         await clock.tickAsync(1);
 
@@ -402,29 +406,23 @@ describe('AccountTrackerController', () => {
     );
   });
 
-  it('refreshes addresses when keyring is unlocked', async () => {
+  it('sets isActive to true when keyring is unlocked', async () => {
     await withController(
       {
         selectedAccount: ACCOUNT_1,
         listAccounts: [ACCOUNT_1],
       },
       async ({ controller, messenger }) => {
-        mockedGetTokenBalancesForMultipleAddresses.mockResolvedValueOnce({
-          tokenBalances: {
-            '0x0000000000000000000000000000000000000000': {
-              [ADDRESS_1]: new BN('abcdef', 16),
-            },
-          },
-          stakedBalances: {},
-        });
+        // Verify controller is active initially (unlocked by default in tests)
+        expect(controller.isActive).toBe(true);
 
-        messenger.publish('KeyringController:unlock');
-
-        await clock.tickAsync(1);
+        // Lock the keyring
+        messenger.publish('KeyringController:lock');
+        expect(controller.isActive).toBe(false);
 
-        expect(
-          controller.state.accountsByChainId['0x1'][CHECKSUM_ADDRESS_1].balance,
-        ).toBe('0xabcdef');
+        // Unlock the keyring
+        messenger.publish('KeyringController:unlock');
+        expect(controller.isActive).toBe(true);
       },
     );
   });
@@ -2033,6 +2031,11 @@ async function withController<ReturnValue>(
     mockNetworkState,
   );
 
+  messenger.registerActionHandler(
+    'KeyringController:getState',
+    jest.fn().mockReturnValue({ isUnlocked: true }),
+  );
+
   const accountTrackerMessenger = new Messenger<
     'AccountTrackerController',
     AllAccountTrackerControllerActions,
@@ -2050,12 +2053,14 @@ async function withController<ReturnValue>(
       'PreferencesController:getState',
       'AccountsController:getSelectedAccount',
       'AccountsController:listAccounts',
+      'KeyringController:getState',
     ],
     events: [
       'AccountsController:selectedEvmAccountChange',
       'TransactionController:unapprovedTransactionAdded',
       'TransactionController:transactionConfirmed',
       'NetworkController:networkAdded',
+      'KeyringController:lock',
       'KeyringController:unlock',
     ],
   });

packages/assets-controllers/src/AccountTrackerController.ts

@@ -15,7 +15,11 @@ import {
   toChecksumHexAddress,
 } from '@metamask/controller-utils';
 import EthQuery from '@metamask/eth-query';
-import type { KeyringControllerUnlockEvent } from '@metamask/keyring-controller';
+import type {
+  KeyringControllerGetStateAction,
+  KeyringControllerLockEvent,
+  KeyringControllerUnlockEvent,
+} from '@metamask/keyring-controller';
 import type { InternalAccount } from '@metamask/keyring-internal-api';
 import type { Messenger } from '@metamask/messenger';
 import type {
@@ -192,7 +196,8 @@ export type AllowedActions =
     }
   | AccountsControllerGetSelectedAccountAction
   | NetworkControllerGetStateAction
-  | NetworkControllerGetNetworkClientByIdAction;
+  | NetworkControllerGetNetworkClientByIdAction
+  | KeyringControllerGetStateAction;
 
 /**
  * The event that {@link AccountTrackerController} can emit.
@@ -217,6 +222,7 @@ export type AllowedEvents =
   | TransactionControllerUnapprovedTransactionAddedEvent
   | TransactionControllerTransactionConfirmedEvent
   | NetworkControllerNetworkAddedEvent
+  | KeyringControllerLockEvent
   | KeyringControllerUnlockEvent;
 
 /**
@@ -256,6 +262,9 @@ export class AccountTrackerController extends StaticIntervalPollingController<Ac
 
   readonly #isOnboarded: () => boolean;
 
+  /** Track if the keyring is locked */
+  #isLocked = true;
+
   /**
    * Creates an AccountTracker instance.
    *
@@ -331,6 +340,9 @@ export class AccountTrackerController extends StaticIntervalPollingController<Ac
     this.#fetchingEnabled = fetchingEnabled;
     this.#isOnboarded = isOnboarded;
 
+    const { isUnlocked } = this.messenger.call('KeyringController:getState');
+    this.#isLocked = !isUnlocked;
+
     this.setIntervalLength(interval);
 
     this.messenger.subscribe(
@@ -345,16 +357,25 @@ export class AccountTrackerController extends StaticIntervalPollingController<Ac
       (event): string => event.address,
     );
 
-    this.messenger.subscribe('NetworkController:networkAdded', () => {
-      this.refresh(this.#getNetworkClientIds()).catch(() => {
-        // Silently handle refresh errors
-      });
-    });
+    this.messenger.subscribe(
+      'NetworkController:networkAdded',
+      (networkConfiguration) => {
+        const { networkClientId } =
+          networkConfiguration.rpcEndpoints[
+            networkConfiguration.defaultRpcEndpointIndex
+          ];
+        this.refresh([networkClientId]).catch(() => {
+          // Silently handle refresh errors
+        });
+      },
+    );
 
     this.messenger.subscribe('KeyringController:unlock', () => {
-      this.refresh(this.#getNetworkClientIds()).catch(() => {
-        // Silently handle refresh errors
-      });
+      this.#isLocked = false;
+    });
+
+    this.messenger.subscribe('KeyringController:lock', () => {
+      this.#isLocked = true;
     });
 
     this.messenger.subscribe(
@@ -392,6 +413,16 @@ export class AccountTrackerController extends StaticIntervalPollingController<Ac
     this.#registerMessageHandlers();
   }
 
+  /**
+   * Whether the controller is active (keyring is unlocked and user is onboarded).
+   * When locked or not onboarded, balance updates should be skipped.
+   *
+   * @returns Whether the controller should perform balance updates.
+   */
+  get isActive(): boolean {
+    return !this.#isLocked && this.#isOnboarded();
+  }
+
   #syncAccounts(newChainIds: string[]): void {
     const accountsByChainId = cloneDeep(this.state.accountsByChainId);
     const { selectedNetworkClientId } = this.messenger.call(
@@ -645,7 +676,7 @@ export class AccountTrackerController extends StaticIntervalPollingController<Ac
 
       this.#syncAccounts(chainIds);
 
-      if (!this.#fetchingEnabled() || !this.#isOnboarded()) {
+      if (!this.#fetchingEnabled() || !this.isActive) {
         return;
       }
 
@@ -815,8 +846,8 @@ export class AccountTrackerController extends StaticIntervalPollingController<Ac
   ): Promise<
     Record<string, { balance: string; stakedBalance?: StakedBalance }>
   > {
-    // Skip balance fetching if not onboarded to avoid unnecessary RPC calls during onboarding
-    if (!this.#isOnboarded()) {
+    // Skip balance fetching if locked or not onboarded to avoid unnecessary RPC calls
+    if (!this.isActive) {
       return {};
     }