feat(keyring-controller): add withKeyringV2 support (#8390)

## Explanation

Another approach for `withKeyringV2` where we actually extend the
existing list of keyring instances to have an optional `keyringV2`
field.

This allow to keep them in memory and have the same lifecycle than v1
keyring instance (and since all v2 implementations are wrappers for now,
they are "bound" to v1 instances anyway).

Original PR:
- #8372

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

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Introduces new V2 keyring selection/execution paths and caches V2
adapters alongside legacy keyrings, which could affect keyring
lifecycle, rollback/persistence behavior, and error handling. Dependency
bumps to keyring packages may also subtly change signing/account
behavior.
> 
> **Overview**
> Adds first-class `KeyringV2` support by storing an optional in-memory
V2 adapter next to each legacy keyring entry and creating/destroying
these adapters during keyring create/restore/clear flows.
> 
> Introduces `withKeyringV2` (locked, persisted/rollback) and
`withKeyringV2Unsafe` (lock-free, no rollback) APIs plus messenger
action types, including a new `KeyringSelectorV2`
(`type`/`address`/`id`/`filter`) and a `KeyringV2NotSupported` error
when no V2 builder exists for a selected keyring.
> 
> Updates tests to cover selector variants, lock/rollback semantics, and
messenger callability; bumps
`@metamask/eth-hd-keyring`/`@metamask/eth-simple-keyring` versions and
adjusts Jest coverage thresholds accordingly.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
d8bc565. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

---------

Co-authored-by: Mathieu Artu <mathieu.artu@consensys.net>

Author: ccharly

packages/keyring-controller/CHANGELOG.md

@@ -12,6 +12,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Expose `KeyringController:signTransaction` method through `KeyringController` messenger ([#8408](https://github.com/MetaMask/core/pull/8408))
 - Persist vault when keyring state changes during unlock ([#8415](https://github.com/MetaMask/core/pull/8415))
   - If a keyring's serialized state differs after deserialization (e.g. a migration ran, or metadata was missing), the vault is now re-persisted so the change is not lost on the next unlock.
+- Added `KeyringV2` support ([#8390](https://github.com/MetaMask/core/pull/8390))
+  - The controller now maintains a list of `KeyringV2` instance in memory alongside previous `Keyring` instance.
+  - This new keyring interface is more generic and will become the new standard to interact with keyring (creating accounts, executing logic that involves accounts like signing, etc...).
+  - For now, most `KeyringV2` are wrappers (read adapters) around existing `Keyring` instance.
+- Added `withKeyringV2Unsafe` method and `KeyringController:withKeyringV2Unsafe` messenger action for lock-free read-only access to `KeyringV2` adapters ([#8390](https://github.com/MetaMask/core/pull/8390))
+  - Mirrors `withKeyringUnsafe` semantics: no mutex acquired, no persistence or rollback.
+  - Caller is responsible for ensuring the operation is read-only and accesses only immutable keyring data.
+- Added `withKeyringV2` method and `KeyringController:withKeyringV2` messenger action for atomic operations using the `KeyringV2` API ([#8390](https://github.com/MetaMask/core/pull/8390))
+  - Accepts a `KeyringSelectorV2` to select keyrings by `type`, `address`, `id`, or `filter`.
+  - Ships with default V2 builders for HD (`HdKeyringV2`) and Simple (`SimpleKeyringV2`) keyrings; additional builders can be registered via the `keyringV2Builders` constructor option.
 
 ### Changed
 

packages/keyring-controller/jest.config.js

@@ -17,10 +17,10 @@ module.exports = merge(baseConfig, {
   // An object that configures minimum threshold enforcement for coverage results
   coverageThreshold: {
     global: {
-      branches: 95.09,
+      branches: 94.91,
       functions: 100,
-      lines: 99,
-      statements: 99,
+      lines: 99.08,
+      statements: 99.08,
     },
   },
 

packages/keyring-controller/package.json

@@ -52,9 +52,9 @@
     "@ethereumjs/util": "^9.1.0",
     "@metamask/base-controller": "^9.0.1",
     "@metamask/browser-passworder": "^6.0.0",
-    "@metamask/eth-hd-keyring": "^13.0.0",
+    "@metamask/eth-hd-keyring": "^13.1.1",
     "@metamask/eth-sig-util": "^8.2.0",
-    "@metamask/eth-simple-keyring": "^11.0.0",
+    "@metamask/eth-simple-keyring": "^11.1.2",
     "@metamask/keyring-api": "^21.6.0",
     "@metamask/keyring-internal-api": "^10.0.0",
     "@metamask/messenger": "^1.1.1",

packages/keyring-controller/src/KeyringController-method-action-types.ts

@@ -310,6 +310,71 @@ export type KeyringControllerWithKeyringUnsafeAction = {
   handler: KeyringController['withKeyringUnsafe'];
 };
 
+/**
+ * Select a keyring using its `KeyringV2` adapter, and execute
+ * the given operation with the wrapped keyring as a mutually
+ * exclusive atomic operation.
+ *
+ * The cached `KeyringV2` adapter is retrieved from the keyring
+ * entry.
+ *
+ * A `KeyringV2Builder` for the selected keyring's type must exist
+ * (either as a default or registered via the `keyringV2Builders`
+ * constructor option); otherwise an error is thrown.
+ *
+ * The method automatically persists changes at the end of the
+ * function execution, or rolls back the changes if an error
+ * is thrown.
+ *
+ * @param selector - Keyring selector object.
+ * @param operation - Function to execute with the wrapped V2 keyring.
+ * @returns Promise resolving to the result of the function execution.
+ * @template CallbackResult - The type of the value resolved by the callback function.
+ */
+export type KeyringControllerWithKeyringV2Action = {
+  type: `KeyringController:withKeyringV2`;
+  handler: KeyringController['withKeyringV2'];
+};
+
+/**
+ * Select a keyring, wrap it in a `KeyringV2` adapter, and execute
+ * the given read-only operation **without** acquiring the controller's
+ * mutual exclusion lock.
+ *
+ * ## When to use this method
+ *
+ * This method is an escape hatch for read-only access to keyring data that
+ * is immutable once the keyring is initialized. A typical safe use case is
+ * reading immutable fields from a `KeyringV2` adapter: data that is set
+ * during initialization and never mutated afterwards.
+ *
+ * ## Why it is "unsafe"
+ *
+ * The "unsafe" designation mirrors the semantics of `unsafe { }` blocks in
+ * Rust: the method itself does not enforce thread-safety guarantees. By
+ * calling this method the **caller** explicitly takes responsibility for
+ * ensuring that:
+ *
+ * - The operation is **read-only** — no state is mutated.
+ * - The data being read is **immutable** after the keyring is initialized,
+ * so concurrent locked operations cannot alter it while this callback
+ * runs.
+ *
+ * Do **not** use this method to:
+ * - Mutate keyring state (add accounts, sign, etc.) — use `withKeyringV2`.
+ * - Read mutable fields that could change during concurrent operations.
+ *
+ * @param selector - Keyring selector object.
+ * @param operation - Read-only function to execute with the wrapped V2 keyring.
+ * @returns Promise resolving to the result of the function execution.
+ * @template SelectedKeyring - The type of the selected V2 keyring.
+ * @template CallbackResult - The type of the value resolved by the callback function.
+ */
+export type KeyringControllerWithKeyringV2UnsafeAction = {
+  type: `KeyringController:withKeyringV2Unsafe`;
+  handler: KeyringController['withKeyringV2Unsafe'];
+};
+
 /**
  * Union of all KeyringController action types.
  */
@@ -334,4 +399,6 @@ export type KeyringControllerMethodActions =
   | KeyringControllerPatchUserOperationAction
   | KeyringControllerSignUserOperationAction
   | KeyringControllerWithKeyringAction
-  | KeyringControllerWithKeyringUnsafeAction;
+  | KeyringControllerWithKeyringUnsafeAction
+  | KeyringControllerWithKeyringV2Action
+  | KeyringControllerWithKeyringV2UnsafeAction;