Skip to content

Conversation

@salimtb
Copy link
Contributor

@salimtb salimtb commented Dec 9, 2025

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.

References

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
  • I've introduced breaking changes in this PR and have prepared draft pull requests for clients and consumer packages to resolve them

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.

Written by Cursor Bugbot for commit 10463da. This will update automatically on new commits. Configure here.

@salimtb salimtb changed the title Feat/improve token detection feat: improve token detection Dec 9, 2025
@salimtb
Copy link
Contributor Author

salimtb commented Dec 9, 2025

@metamaskbot publish-preview

@github-actions
Copy link
Contributor

github-actions bot commented Dec 9, 2025

Preview builds have been published. See these instructions for more information about preview builds.

Expand for full list of packages and versions.
{
  "@metamask-previews/account-tree-controller": "4.0.0-preview-c92c27f1",
  "@metamask-previews/accounts-controller": "35.0.0-preview-c92c27f1",
  "@metamask-previews/address-book-controller": "7.0.1-preview-c92c27f1",
  "@metamask-previews/analytics-controller": "0.0.0-preview-c92c27f1",
  "@metamask-previews/announcement-controller": "8.0.0-preview-c92c27f1",
  "@metamask-previews/app-metadata-controller": "2.0.0-preview-c92c27f1",
  "@metamask-previews/approval-controller": "8.0.0-preview-c92c27f1",
  "@metamask-previews/assets-controllers": "93.1.0-preview-c92c27f1",
  "@metamask-previews/base-controller": "9.0.0-preview-c92c27f1",
  "@metamask-previews/bridge-controller": "64.0.0-preview-c92c27f1",
  "@metamask-previews/bridge-status-controller": "64.0.1-preview-c92c27f1",
  "@metamask-previews/build-utils": "3.0.4-preview-c92c27f1",
  "@metamask-previews/chain-agnostic-permission": "1.3.0-preview-c92c27f1",
  "@metamask-previews/claims-controller": "0.2.0-preview-c92c27f1",
  "@metamask-previews/composable-controller": "12.0.0-preview-c92c27f1",
  "@metamask-previews/controller-utils": "11.16.0-preview-c92c27f1",
  "@metamask-previews/core-backend": "5.0.0-preview-c92c27f1",
  "@metamask-previews/delegation-controller": "2.0.0-preview-c92c27f1",
  "@metamask-previews/earn-controller": "11.0.0-preview-c92c27f1",
  "@metamask-previews/eip-5792-middleware": "2.0.0-preview-c92c27f1",
  "@metamask-previews/eip-7702-internal-rpc-middleware": "0.1.0-preview-c92c27f1",
  "@metamask-previews/eip1193-permission-middleware": "1.0.3-preview-c92c27f1",
  "@metamask-previews/ens-controller": "19.0.0-preview-c92c27f1",
  "@metamask-previews/error-reporting-service": "3.0.0-preview-c92c27f1",
  "@metamask-previews/eth-block-tracker": "15.0.0-preview-c92c27f1",
  "@metamask-previews/eth-json-rpc-middleware": "22.0.1-preview-c92c27f1",
  "@metamask-previews/eth-json-rpc-provider": "6.0.0-preview-c92c27f1",
  "@metamask-previews/foundryup": "1.0.1-preview-c92c27f1",
  "@metamask-previews/gas-fee-controller": "26.0.0-preview-c92c27f1",
  "@metamask-previews/gator-permissions-controller": "0.8.0-preview-c92c27f1",
  "@metamask-previews/json-rpc-engine": "10.2.0-preview-c92c27f1",
  "@metamask-previews/json-rpc-middleware-stream": "8.0.8-preview-c92c27f1",
  "@metamask-previews/keyring-controller": "25.0.0-preview-c92c27f1",
  "@metamask-previews/logging-controller": "7.0.1-preview-c92c27f1",
  "@metamask-previews/message-manager": "14.1.0-preview-c92c27f1",
  "@metamask-previews/messenger": "0.3.0-preview-c92c27f1",
  "@metamask-previews/multichain-account-service": "4.0.0-preview-c92c27f1",
  "@metamask-previews/multichain-api-middleware": "1.2.5-preview-c92c27f1",
  "@metamask-previews/multichain-network-controller": "3.0.0-preview-c92c27f1",
  "@metamask-previews/multichain-transactions-controller": "7.0.0-preview-c92c27f1",
  "@metamask-previews/name-controller": "9.0.0-preview-c92c27f1",
  "@metamask-previews/network-controller": "27.0.0-preview-c92c27f1",
  "@metamask-previews/network-enablement-controller": "4.0.0-preview-c92c27f1",
  "@metamask-previews/notification-services-controller": "21.0.0-preview-c92c27f1",
  "@metamask-previews/permission-controller": "12.1.1-preview-c92c27f1",
  "@metamask-previews/permission-log-controller": "5.0.0-preview-c92c27f1",
  "@metamask-previews/phishing-controller": "16.1.0-preview-c92c27f1",
  "@metamask-previews/polling-controller": "16.0.0-preview-c92c27f1",
  "@metamask-previews/preferences-controller": "22.0.0-preview-c92c27f1",
  "@metamask-previews/profile-metrics-controller": "1.0.0-preview-c92c27f1",
  "@metamask-previews/profile-sync-controller": "27.0.0-preview-c92c27f1",
  "@metamask-previews/rate-limit-controller": "7.0.0-preview-c92c27f1",
  "@metamask-previews/remote-feature-flag-controller": "3.0.0-preview-c92c27f1",
  "@metamask-previews/sample-controllers": "4.0.0-preview-c92c27f1",
  "@metamask-previews/seedless-onboarding-controller": "7.1.0-preview-c92c27f1",
  "@metamask-previews/selected-network-controller": "26.0.0-preview-c92c27f1",
  "@metamask-previews/shield-controller": "4.0.0-preview-c92c27f1",
  "@metamask-previews/signature-controller": "38.0.0-preview-c92c27f1",
  "@metamask-previews/storage-service": "0.0.0-preview-c92c27f1",
  "@metamask-previews/subscription-controller": "5.4.0-preview-c92c27f1",
  "@metamask-previews/token-search-discovery-controller": "4.0.0-preview-c92c27f1",
  "@metamask-previews/transaction-controller": "62.5.0-preview-c92c27f1",
  "@metamask-previews/transaction-pay-controller": "10.4.0-preview-c92c27f1",
  "@metamask-previews/user-operation-controller": "41.0.0-preview-c92c27f1"
}

@salimtb salimtb marked this pull request as ready for review December 10, 2025 12:19
@salimtb salimtb requested review from a team as code owners December 10, 2025 12:19
@salimtb
Copy link
Contributor Author

salimtb commented Dec 10, 2025

@metamaskbot publish-preview

@github-actions
Copy link
Contributor

Preview builds have been published. See these instructions for more information about preview builds.

Expand for full list of packages and versions.
{
  "@metamask-previews/account-tree-controller": "4.0.0-preview-267e79c3",
  "@metamask-previews/accounts-controller": "35.0.0-preview-267e79c3",
  "@metamask-previews/address-book-controller": "7.0.1-preview-267e79c3",
  "@metamask-previews/analytics-controller": "0.0.0-preview-267e79c3",
  "@metamask-previews/announcement-controller": "8.0.0-preview-267e79c3",
  "@metamask-previews/app-metadata-controller": "2.0.0-preview-267e79c3",
  "@metamask-previews/approval-controller": "8.0.0-preview-267e79c3",
  "@metamask-previews/assets-controllers": "93.1.0-preview-267e79c3",
  "@metamask-previews/base-controller": "9.0.0-preview-267e79c3",
  "@metamask-previews/bridge-controller": "64.0.0-preview-267e79c3",
  "@metamask-previews/bridge-status-controller": "64.0.1-preview-267e79c3",
  "@metamask-previews/build-utils": "3.0.4-preview-267e79c3",
  "@metamask-previews/chain-agnostic-permission": "1.3.0-preview-267e79c3",
  "@metamask-previews/claims-controller": "0.2.0-preview-267e79c3",
  "@metamask-previews/composable-controller": "12.0.0-preview-267e79c3",
  "@metamask-previews/controller-utils": "11.16.0-preview-267e79c3",
  "@metamask-previews/core-backend": "5.0.0-preview-267e79c3",
  "@metamask-previews/delegation-controller": "2.0.0-preview-267e79c3",
  "@metamask-previews/earn-controller": "11.0.0-preview-267e79c3",
  "@metamask-previews/eip-5792-middleware": "2.0.0-preview-267e79c3",
  "@metamask-previews/eip-7702-internal-rpc-middleware": "0.1.0-preview-267e79c3",
  "@metamask-previews/eip1193-permission-middleware": "1.0.3-preview-267e79c3",
  "@metamask-previews/ens-controller": "19.0.0-preview-267e79c3",
  "@metamask-previews/error-reporting-service": "3.0.0-preview-267e79c3",
  "@metamask-previews/eth-block-tracker": "15.0.0-preview-267e79c3",
  "@metamask-previews/eth-json-rpc-middleware": "22.0.1-preview-267e79c3",
  "@metamask-previews/eth-json-rpc-provider": "6.0.0-preview-267e79c3",
  "@metamask-previews/foundryup": "1.0.1-preview-267e79c3",
  "@metamask-previews/gas-fee-controller": "26.0.0-preview-267e79c3",
  "@metamask-previews/gator-permissions-controller": "0.8.0-preview-267e79c3",
  "@metamask-previews/json-rpc-engine": "10.2.0-preview-267e79c3",
  "@metamask-previews/json-rpc-middleware-stream": "8.0.8-preview-267e79c3",
  "@metamask-previews/keyring-controller": "25.0.0-preview-267e79c3",
  "@metamask-previews/logging-controller": "7.0.1-preview-267e79c3",
  "@metamask-previews/message-manager": "14.1.0-preview-267e79c3",
  "@metamask-previews/messenger": "0.3.0-preview-267e79c3",
  "@metamask-previews/multichain-account-service": "4.0.0-preview-267e79c3",
  "@metamask-previews/multichain-api-middleware": "1.2.5-preview-267e79c3",
  "@metamask-previews/multichain-network-controller": "3.0.0-preview-267e79c3",
  "@metamask-previews/multichain-transactions-controller": "7.0.0-preview-267e79c3",
  "@metamask-previews/name-controller": "9.0.0-preview-267e79c3",
  "@metamask-previews/network-controller": "27.0.0-preview-267e79c3",
  "@metamask-previews/network-enablement-controller": "4.0.0-preview-267e79c3",
  "@metamask-previews/notification-services-controller": "21.0.0-preview-267e79c3",
  "@metamask-previews/permission-controller": "12.1.1-preview-267e79c3",
  "@metamask-previews/permission-log-controller": "5.0.0-preview-267e79c3",
  "@metamask-previews/phishing-controller": "16.1.0-preview-267e79c3",
  "@metamask-previews/polling-controller": "16.0.0-preview-267e79c3",
  "@metamask-previews/preferences-controller": "22.0.0-preview-267e79c3",
  "@metamask-previews/profile-metrics-controller": "1.0.0-preview-267e79c3",
  "@metamask-previews/profile-sync-controller": "27.0.0-preview-267e79c3",
  "@metamask-previews/rate-limit-controller": "7.0.0-preview-267e79c3",
  "@metamask-previews/remote-feature-flag-controller": "3.0.0-preview-267e79c3",
  "@metamask-previews/sample-controllers": "4.0.0-preview-267e79c3",
  "@metamask-previews/seedless-onboarding-controller": "7.1.0-preview-267e79c3",
  "@metamask-previews/selected-network-controller": "26.0.0-preview-267e79c3",
  "@metamask-previews/shield-controller": "4.0.0-preview-267e79c3",
  "@metamask-previews/signature-controller": "38.0.0-preview-267e79c3",
  "@metamask-previews/storage-service": "0.0.0-preview-267e79c3",
  "@metamask-previews/subscription-controller": "5.4.0-preview-267e79c3",
  "@metamask-previews/token-search-discovery-controller": "4.0.0-preview-267e79c3",
  "@metamask-previews/transaction-controller": "62.5.0-preview-267e79c3",
  "@metamask-previews/transaction-pay-controller": "10.4.0-preview-267e79c3",
  "@metamask-previews/user-operation-controller": "41.0.0-preview-267e79c3"
}

| NetworkControllerGetNetworkClientByIdAction
| NetworkControllerGetStateAction
| TokensControllerGetStateAction
| TokenDetectionControllerAddDetectedTokensViaPollingAction
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Amazing TY

Comment on lines +161 to +162
| KeyringControllerLockEvent
| KeyringControllerUnlockEvent
Copy link
Contributor

@Prithpal-Sooriya Prithpal-Sooriya Dec 11, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice bug fix to prevent calls when wallet is locked!

Comment on lines +165 to +167
| AccountsControllerSelectedEvmAccountChangeEvent
| TransactionControllerTransactionConfirmedEvent
| TransactionControllerIncomingTransactionsReceivedEvent;
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice bug fix to ensure the wallet balances and tokens update from various events related to TX updates or Account selection changes.

Comment on lines +811 to +818
if (!this.#useTokenDetection()) {
return;
}

// Check if external services are enabled (websocket requires external services)
if (!this.#useExternalServices()) {
return;
}
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice WS fix!

@salimtb salimtb added this pull request to the merge queue Dec 11, 2025
Merged via the queue into main with commit e2a7b97 Dec 11, 2025
281 checks passed
@salimtb salimtb deleted the feat/improve-token-detection branch December 11, 2025 14:03
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants