feat(keyring-controller): add withKeyringV2 support

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;