feat: improve token detection (#7408)

## Explanation

Extension UI: MetaMask/metamask-extension#38708
Mobile UI: MetaMask/metamask-mobile#23864

Acceptance Criteria
• Replace all Account API v2 calls with Account API v4 for token
auto-detection.
• Continue using RPC-based detection for chains not supported by Account
API v4.
• If Account API v4 requests fail, fallback to RPC-based token
detection.
• If Account API v4 returns any unprocessed networks, fallback to RPC
detection for those networks as well.

<!--
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
-->

## 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)
- [ ] 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]
> Replaces token auto-detection via Accounts API v2 with v4, delegating
supported chains to TokenBalancesController, adding RPC fallbacks/new
actions, and improving polling, lock handling, and tests.
> 
> - **Breaking/Behavioral Changes**
> - Replace Accounts API v2 with v4 for token auto-detection; RPC-based
detection remains for unsupported chains.
> - `TokenDetectionController.detectTokens()` adds `forceRpc` and is
exposed via `TokenDetectionController:detectTokens`.
> - **TokenDetectionController**
> - Skips Accounts API–supported chains (handled by balances), performs
RPC detection otherwise.
> - Adds `addDetectedTokensViaPolling` and enhances
`addDetectedTokensViaWs`; respects prefs/external services; metrics
tracking.
> - Subscribes to tx confirmed events; refactors polling restart and
state helpers; minor type/utility cleanups.
> - **TokenBalancesController**
> - On Accounts API failure or unprocessed chains, calls
`TokenDetectionController:detectTokens` with `forceRpc: true`.
> - Imports untracked tokens via
`TokenDetectionController:addDetectedTokensViaPolling`.
> - Adds keyring lock/unlock gating (`isActive`), transaction events
handling, per-chain polling grouping/updates, token address filtering,
and robust state normalization.
> - **Accounts API Fetcher**
> - Supports v4 response shapes: handles CAIP `unprocessedNetworks`,
maps to hex; maintains timeout/batching; staked balances handling.
> - **Exports & Docs**
> - Update `index.ts` exports for new actions; changelog documents
breaking changes and new flows.
> - **Tests**
> - Extensive new/updated tests covering RPC fallback, polling behavior,
event handling, lock state, and edge cases.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
10463da. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: salimtb

eslint-suppressions.json

@@ -386,62 +386,6 @@
       "count": 2
     }
   },
-  "packages/assets-controllers/src/TokenBalancesController.test.ts": {
-    "@typescript-eslint/explicit-function-return-type": {
-      "count": 2
-    },
-    "camelcase": {
-      "count": 1
-    },
-    "jest/unbound-method": {
-      "count": 1
-    },
-    "require-atomic-updates": {
-      "count": 1
-    }
-  },
-  "packages/assets-controllers/src/TokenBalancesController.ts": {
-    "@typescript-eslint/explicit-function-return-type": {
-      "count": 19
-    },
-    "@typescript-eslint/naming-convention": {
-      "count": 1
-    },
-    "@typescript-eslint/no-misused-promises": {
-      "count": 1
-    },
-    "@typescript-eslint/prefer-nullish-coalescing": {
-      "count": 2
-    },
-    "id-denylist": {
-      "count": 6
-    },
-    "id-length": {
-      "count": 7
-    }
-  },
-  "packages/assets-controllers/src/TokenDetectionController.test.ts": {
-    "@typescript-eslint/explicit-function-return-type": {
-      "count": 5
-    },
-    "id-length": {
-      "count": 1
-    }
-  },
-  "packages/assets-controllers/src/TokenDetectionController.ts": {
-    "@typescript-eslint/explicit-function-return-type": {
-      "count": 12
-    },
-    "@typescript-eslint/naming-convention": {
-      "count": 4
-    },
-    "@typescript-eslint/no-misused-promises": {
-      "count": 5
-    },
-    "@typescript-eslint/prefer-nullish-coalescing": {
-      "count": 1
-    }
-  },
   "packages/assets-controllers/src/TokenListController.test.ts": {
     "@typescript-eslint/explicit-function-return-type": {
       "count": 2

packages/assets-controllers/CHANGELOG.md

@@ -16,6 +16,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- Bump `@metamask/transaction-controller` from `^62.4.0` to `^62.5.0` ([#7325](https://github.com/MetaMask/core/pull/7325))
+- **BREAKING:** Replace Account API v2 with Account API v4 for token auto-detection ([#7408](https://github.com/MetaMask/core/pull/7408))
+  - `TokenDetectionController` now delegates token detection for Account API v4 supported chains to `TokenBalancesController`
+  - RPC-based detection continues to be used for chains not supported by Account API v4
+  - Added `forceRpc` parameter to `TokenDetectionController.detectTokens()` to force RPC-based detection
+  - `TokenDetectionController:detectTokens` action is now registered for cross-controller communication
+- `TokenBalancesController` now triggers RPC-based token detection as fallback when Account API v4 fails or returns unprocessed chains ([#7408](https://github.com/MetaMask/core/pull/7408))
+  - Calls `TokenDetectionController:detectTokens` with `forceRpc: true` when fetcher fails
+  - Calls `TokenDetectionController:detectTokens` with `forceRpc: true` for any unprocessed chain IDs returned by the API
+- Refactored `TokenBalancesController` for improved code organization and maintainability ([#7408](https://github.com/MetaMask/core/pull/7408))
 - Remove warning logs for failed chain balance fetches in RPC balance fetcher ([#7429](https://github.com/MetaMask/core/pull/7429))
 - Reduce severity of ERC721 metadata interface log from `console.error` to `console.warn` ([#7412](https://github.com/MetaMask/core/pull/7412))
   - Fixes [#24988](https://github.com/MetaMask/metamask-extension/issues/24988)