feat(keyring-controller): add withController for atomic operations over multiple keyrings

[ccharly]

Explanation

Today there's no way to make multiple operations in an "atomic" (read transactional) way.

A good example of this is if you want to use a keyring using withKeyring that's not existing yet (I'm omitting the createIfMissing variants, as we wanted to move away from this pattern).

To do this in a safe way, you usually have to use your own lock to make sure you can get-or-create the keyring and prevent concurrent keyring creations.

This new withController is based on the withKeyring but with an access to a "restricted" state and methods of the controller. This way, you can interact with multiple keyring at once while being guarded (to prevent race-conditions) by the controller's global lock.

The former problem can then be written that way now:

const account = await keyringController.withController(async (controller) => {
  // Here, `controller.keyrings` is a "view" on the existing keyrings (instances), only valid
  // for this block.
  let keyring: MyKeyring | undefined = controller.keyrings.find(isMyKeyring);
  if (!keyring) {
    const { keyring: myKeyring } = await controller.addNewKeyring({ type: 'My Keyring', data: { ... }});
    keyring = myKeyring;
  }
  
  const [account] = await keyring.createAccounts(...);
  return account;
});

This will also be used to write the migration from the existing SnapKeyring (1 for ALL Snaps) to multiple SnapKeyring (1 PER Snap) in a safe way like:

await keyringController.withController(async (controller) => {
  const accounts: Map<SnapId, KeyringAccount[]> = new Map();

  // Get existing Snap accounts from the single Snap keyring instance we have today.
  const keyring: SnapKeyring | undefined = controller.keyrings.find(isSnapKeyring);
  if (keyring) {
    for (const account of keyring.listAccounts()) {
      accounts[account.metadata.snap.id] ??= [];
      accounts[account.metadata.snap.id].push(account);
    }
  }
  
  // Re-create all new Snap keyrings, 1 per Snap.
  for (const [snapId, snapAccounts] of accounts.entries()) {
    await controller.addNewKeyring({ type: 'Snap keyring', data: snapAccounts });
  }
  
  // We can safely remove the existing Snap keyring now.
  await controller.removeKeyring(...);
});

References

N/A

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

Medium Risk
Adds a new transactional API that can create/remove keyrings and changes how keyring instances are managed/persisted, plus broad keyring dependency upgrades; failures could impact vault persistence or keyring lifecycle.

Overview
Introduces KeyringController.withController, a new atomic, controller-wide transaction API that exposes a restricted view of keyrings and stages addNewKeyring/removeKeyring changes with automatic persist-or-rollback behavior and lifecycle cleanup.

Updates messenger action types and tests to support the new KeyringController:withController action, tightens unsafe direct keyring instance leakage checks, and adjusts keyring entry typing to include optional v2 instances.

Separately, advances the keyring v2 transition by mapping @metamask/*/v2 imports in Jest, switching some types/imports to @metamask/keyring-api/v2, adding Stellar account sort-order support in account-tree-controller, and bumping multiple packages to newer @metamask/keyring-* (and related) versions with corresponding yarn.lock updates.

^{Reviewed by Cursor Bugbot for commit 0f03c1f. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 3 potential issues.

^{❌ 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 02a9fac. Configure here.}

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	@​metamask/​snaps-controllers@​19.0.0 ⏵ 19.0.1				+1
	@​metamask/​keyring-internal-api@​10.0.0 ⏵ 10.1.0	+1		+1	+2
	@​metamask/​eth-money-keyring@​2.0.0 ⏵ 2.0.1	+1			+2
	@​metamask/​keyring-snap-client@​8.2.0 ⏵ 9.0.0	+1		+1	+4
	@​metamask/​snaps-utils@​12.1.2 ⏵ 12.2.0	+1		+1	+1
	@​metamask/​account-api@​1.0.0 ⏵ 1.0.2				+3
	@​metamask/​snaps-sdk@​10.4.0 ⏵ 11.1.0	-1			+4
	@​metamask/​keyring-api@​21.6.0 ⏵ 23.0.0	+1			+1
	@​metamask/​eth-snap-keyring@​19.0.0 ⏵ 21.0.0			+1	+2
	@​metamask/​utils@​11.10.0 ⏵ 11.11.0	+1		+1	+2
	@​metamask/​eth-hd-keyring@​13.1.1 ⏵ 14.0.0	+1			+3
	@​metamask/​eth-simple-keyring@​11.1.2 ⏵ 12.0.0				+1

View full report