Skip to content

feat(wallet): add @metamask/assets-controllers to the default initialization configurations - #11314

Closed
dawnseeker8 wants to merge 4 commits into
mainfrom
cursor/wallet-assets-controllers-1943
Closed

dawnseeker8 wants to merge 4 commits into
mainfrom
cursor/wallet-assets-controllers-1943

Conversation

@dawnseeker8

@dawnseeker8 dawnseeker8 commented Nov 5, 2026 •

Copy link
Copy Markdown
Contributor

Explanation

@metamask/wallet does not yet construct any of the legacy @metamask/assets-controllers controllers. Hosts construct them, and several constructors call other controllers immediately (AccountsController:getSelectedAccount, KeyringController:getState, TokensController:getState, NetworkController:getNetworkClientById, and others) or start async work. So the host has to construct them in a specific order, after their dependencies.

This PR does two things, one commit each.

1. @metamask/assets-controllers: constructors no longer call other controllers.

The constructors of TokensController, TokenBalancesController, TokenDetectionController, TokenRatesController, AccountTrackerController, NftController, MultichainBalancesController, MultichainAssetsRatesController and MultichainAssetsController now only register handlers and subscribe to events.

  • The reads of other controllers, and the initial work (token-list enrichment, initial non-EVM balance fetch, Blockaid re-scan polling, seeding the selected chain in accountsByChainId), move to a new idempotent init() method.
  • init() returns early when the controller is deprecated.
  • TokenListController gains init(), which calls initialize() once.
  • TokenDetectionController.init() reports a missing PreferencesController through messenger.captureException instead of throwing. The next PreferencesController:stateChange fills in the value.
  • NftController exposes addNfts through its messenger.
  • TokensController's provider and chainId are now optional. Without a provider it uses the selected network client's provider (new allowed action NetworkController:getSelectedNetworkClient).

Every changed controller has a test that constructs it on a messenger with no handlers registered, plus an idempotency test. Existing tests that relied on constructor side effects now call init().

2. @metamask/wallet: the 16 messenger-based controllers become defaults.

The configurations live in src/initialization/instances/assets-controllers/, one file per controller in one folder, as permission-controller/ does. The codeowners script allows one initializationPath per package.

  • Each getMessenger delegates exactly the external actions and events the controller's messenger type declares. That includes controllers the client registers (PreferencesController, SnapController, PhishingController, AccountTreeController, AuthenticationController, AccountActivityService).
  • Callback options are built from messenger calls at call time, so construction order does not matter:
    • AccountTrackerController.getStakedBalanceForChain and TokenDetectionController.getBalancesInSingleCall call AssetsContractController.
    • NftDetectionController.addNfts, removeNft and getNftState call NftController.
    • Those three configurations use a messenger type that also includes those actions.
  • Service and option defaults, each overridable through instanceOptions:
    • CodefiTokenPricesServiceV2 for tokenPricesService.
    • TokenListService for tokenListService.
    • Ethereum mainnet for chainId.
    • A no-op trackMetaMetricsEvent.
    • NftDetectionController disabled: false and RatesController includeUsdRate: false.
  • Wallet.init() already calls init() on every instance that has one, so it now starts the assets controllers too. Polling is still started by the client.

DeFiPositionsControllerV2 is not included. It is newer, not in the ticket's scope, and can be added separately.

Notes for reviewers

  • The PreferencesController dependency appears at runtime, not at construction. AccountTrackerController.refresh (triggered by AccountsController:selectedEvmAccountChange and NetworkController:networkAdded) calls PreferencesController:getState without a guard. Hosts already register PreferencesController before unlocking, so Wallet.test.ts now registers a stub for it in the tests that unlock or import an SRP. The wallet changelog calls this out.
  • wallet.init() still has one rejected result, MultichainNetworkController:getState from NetworkEnablementController. It was already there before this PR and comes from another controller the wallet doesn't construct.
  • The wallet tests are table-driven in one assets-controllers.test.ts. It mocks @metamask/assets-controllers with subclasses that record their constructor options, so the forwarded options, default services and messenger-backed callbacks can be checked directly. The instances are still real controllers.

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
Open in Web Open in Cursor 

Note

High Risk
Breaking constructor/init contract across many asset controllers plus Wallet default registration risks messenger collisions, wrong init ordering, and subtle pre-init behavior if hosts skip wallet.init() or duplicate controllers.

Reviewed by Cursor Bugbot for commit ea8cfb0. Bugbot is set up for automated code reviews on this repo. Configure here.

cursoragent and others added 3 commits November 5, 2026 10:01
… into init

Constructors of TokensController, TokenBalancesController,
TokenDetectionController, TokenRatesController, AccountTrackerController,
NftController, MultichainBalancesController,
MultichainAssetsRatesController and MultichainAssetsController no longer
call other controllers or start background work. The work moves to a new
idempotent init method. TokenListController gains init, which calls
initialize once. NftController exposes addNfts through its messenger, and
TokensController falls back to the selected network client's provider.

Co-authored-by: Xiaoming Wang <dawnseeker8@users.noreply.github.com>
Co-authored-by: Xiaoming Wang <dawnseeker8@users.noreply.github.com>
…gurations

Adds the 16 messenger-based @metamask/assets-controllers controllers to
the wallet's default initialization configurations. Each configuration
delegates the actions and events its controller's messenger declares,
builds callback options from messenger calls so construction order does
not matter, and defaults the token prices and token list services.
Wallet.init() runs the controllers' init methods.

Co-authored-by: Xiaoming Wang <dawnseeker8@users.noreply.github.com>
@dawnseeker8
dawnseeker8 requested review from a team as code owners November 5, 2026 10:18
Co-authored-by: Xiaoming Wang <dawnseeker8@users.noreply.github.com>

@cursor cursor Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

Fix All in Cursor

❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.

Reviewed by Cursor Bugbot for commit ea8cfb0. Configure here.

console.error('Failed to fetch initial balances:', result.reason);
}
}
}

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Initial balances skip when locked

Medium Severity

MultichainBalancesController.init() is a one-shot fetch that Wallet.init() runs before unlock, but #updateBalance returns immediately while the keyring is locked. There is no KeyringController:unlock listener, and #initialized then blocks a later init(), so existing non-EVM accounts never get that startup refresh.

Additional Locations (1)
Fix in Cursor Fix in Web

Reviewed by Cursor Bugbot for commit ea8cfb0. Configure here.

@dawnseeker8

Copy link
Copy Markdown
Contributor Author

duplicate PR found with #11315 (may be due to cursor creation bug).

@dawnseeker8 dawnseeker8 closed this Nov 9, 2026
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.

2 participants