@metamask-previews/keyring-controller 25.2.0-preview-60aa3d02f → 25.2.0-preview-51be4cab9

package/dist/KeyringController.mjs

@@ -9,7 +9,7 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
     if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
     return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
 };
-var _KeyringController_instances, _KeyringController_controllerOperationMutex, _KeyringController_vaultOperationMutex, _KeyringController_keyringBuilders, _KeyringController_encryptor, _KeyringController_keyrings, _KeyringController_unsupportedKeyrings, _KeyringController_encryptionKey, _KeyringController_getKeyringForAccount, _KeyringController_findKeyringIndexForAccount, _KeyringController_assertNoUnsafeDirectKeyringAccess, _KeyringController_registerMessageHandlers, _KeyringController_selectKeyring, _KeyringController_getKeyringById, _KeyringController_getKeyringByIdOrDefault, _KeyringController_getKeyringMetadata, _KeyringController_getKeyringBuilderForType, _KeyringController_createNewVaultWithKeyring, _KeyringController_deriveAndSetEncryptionKey, _KeyringController_setEncryptionKey, _KeyringController_verifySeedPhrase, _KeyringController_getUpdatedKeyrings, _KeyringController_getSerializedKeyrings, _KeyringController_getSessionState, _KeyringController_restoreSerializedKeyrings, _KeyringController_unlockKeyrings, _KeyringController_updateVault, _KeyringController_isNewEncryptionAvailable, _KeyringController_getAccountsFromKeyrings, _KeyringController_createKeyringWithFirstAccount, _KeyringController_newKeyring, _KeyringController_createKeyring, _KeyringController_clearKeyrings, _KeyringController_restoreKeyring, _KeyringController_destroyKeyring, _KeyringController_assertNoDuplicateAccounts, _KeyringController_setUnlocked, _KeyringController_assertIsUnlocked, _KeyringController_persistOrRollback, _KeyringController_withRollback, _KeyringController_assertControllerMutexIsLocked, _KeyringController_withControllerLock, _KeyringController_withVaultLock;
+var _KeyringController_instances, _KeyringController_controllerOperationMutex, _KeyringController_vaultOperationMutex, _KeyringController_keyringBuilders, _KeyringController_keyringV2Builders, _KeyringController_encryptor, _KeyringController_keyrings, _KeyringController_unsupportedKeyrings, _KeyringController_encryptionKey, _KeyringController_getKeyringForAccount, _KeyringController_getKeyringEntryForAccount, _KeyringController_findKeyringIndexForAccount, _KeyringController_getKeyringEntriesByType, _KeyringController_assertNoUnsafeDirectKeyringAccess, _KeyringController_registerMessageHandlers, _KeyringController_selectKeyringEntry, _KeyringController_getKeyringById, _KeyringController_getKeyringEntryById, _KeyringController_getKeyringByIdOrDefault, _KeyringController_getKeyringMetadata, _KeyringController_getKeyringBuilderForType, _KeyringController_getKeyringV2BuilderForType, _KeyringController_createNewVaultWithKeyring, _KeyringController_deriveAndSetEncryptionKey, _KeyringController_setEncryptionKey, _KeyringController_verifySeedPhrase, _KeyringController_getUpdatedKeyrings, _KeyringController_getSerializedKeyrings, _KeyringController_getSessionState, _KeyringController_restoreSerializedKeyrings, _KeyringController_unlockKeyrings, _KeyringController_updateVault, _KeyringController_isNewEncryptionAvailable, _KeyringController_getAccountsFromKeyrings, _KeyringController_createKeyringWithFirstAccount, _KeyringController_newKeyring, _KeyringController_createKeyring, _KeyringController_clearKeyrings, _KeyringController_restoreKeyring, _KeyringController_destroyKeyring, _KeyringController_assertNoDuplicateAccounts, _KeyringController_setUnlocked, _KeyringController_assertIsUnlocked, _KeyringController_persistOrRollback, _KeyringController_withRollback, _KeyringController_assertControllerMutexIsLocked, _KeyringController_withControllerLock, _KeyringController_withVaultLock;
 function $importDefault(module) {
     if (module?.__esModule) {
         return module.default;
@@ -18,16 +18,16 @@ function $importDefault(module) {
 }
 import { isValidPrivate, getBinarySize } from "@ethereumjs/util";
 import { BaseController } from "@metamask/base-controller";
-import { HdKeyring } from "@metamask/eth-hd-keyring";
+import { HdKeyring, HdKeyringV2 } from "@metamask/eth-hd-keyring";
 import { normalize as ethNormalize } from "@metamask/eth-sig-util";
-import SimpleKeyring from "@metamask/eth-simple-keyring";
+import SimpleKeyring, { SimpleKeyringV2 } from "@metamask/eth-simple-keyring";
 import { add0x, assertIsStrictHexString, bytesToHex, hasProperty, hexToBytes, isObject, isStrictHexString, isValidHexAddress, isValidJson, remove0x } from "@metamask/utils";
 import { Mutex } from "async-mutex";
 import $Wallet from "ethereumjs-wallet";
 const { thirdparty: importers } = $Wallet;
 const Wallet = $importDefault($Wallet);
 import $lodash from "lodash";
-const { cloneDeep, isEqual } = $lodash;
+const { cloneDeep } = $lodash;
 // When generating a ULID within the same millisecond, monotonicFactory provides some guarantees regarding sort order.
 import { ulid } from "ulid";
 import { KeyringControllerErrorMessage } from "./constants.mjs";
@@ -51,6 +51,8 @@ const MESSENGER_EXPOSED_METHODS = [
     'addNewAccount',
     'withKeyring',
     'withKeyringUnsafe',
+    'withKeyringV2',
+    'withKeyringV2Unsafe',
     'addNewKeyring',
     'createNewVaultAndKeychain',
     'createNewVaultAndRestore',
@@ -127,6 +129,17 @@ const defaultKeyringBuilders = [
     keyringBuilderFactory(SimpleKeyring),
     keyringBuilderFactory(HdKeyring),
 ];
+const hdKeyringV2Builder = Object.assign((keyring, metadata) => new HdKeyringV2({
+    legacyKeyring: keyring,
+    entropySource: metadata.id,
+}), { type: KeyringTypes.hd });
+const simpleKeyringV2Builder = Object.assign((keyring) => new SimpleKeyringV2({
+    legacyKeyring: keyring,
+}), { type: KeyringTypes.simple });
+const defaultKeyringV2Builders = [
+    simpleKeyringV2Builder,
+    hdKeyringV2Builder,
+];
 export const getDefaultKeyringState = () => {
     return {
         isUnlocked: false,
@@ -251,7 +264,7 @@ export class KeyringController extends BaseController {
      * @param options.state - Initial state to set on this controller.
      */
     constructor(options) {
-        const { encryptor, keyringBuilders, messenger, state } = options;
+        const { encryptor, keyringBuilders, keyringV2Builders, messenger, state } = options;
         super({
             name,
             metadata: {
@@ -296,6 +309,7 @@ export class KeyringController extends BaseController {
         _KeyringController_controllerOperationMutex.set(this, new Mutex());
         _KeyringController_vaultOperationMutex.set(this, new Mutex());
         _KeyringController_keyringBuilders.set(this, void 0);
+        _KeyringController_keyringV2Builders.set(this, void 0);
         _KeyringController_encryptor.set(this, void 0);
         _KeyringController_keyrings.set(this, void 0);
         _KeyringController_unsupportedKeyrings.set(this, void 0);
@@ -303,6 +317,9 @@ export class KeyringController extends BaseController {
         __classPrivateFieldSet(this, _KeyringController_keyringBuilders, keyringBuilders
             ? keyringBuilders.concat(defaultKeyringBuilders)
             : defaultKeyringBuilders, "f");
+        __classPrivateFieldSet(this, _KeyringController_keyringV2Builders, keyringV2Builders
+            ? keyringV2Builders.concat(defaultKeyringV2Builders)
+            : defaultKeyringV2Builders, "f");
         __classPrivateFieldSet(this, _KeyringController_encryptor, encryptor, "f");
         __classPrivateFieldSet(this, _KeyringController_keyrings, [], "f");
         __classPrivateFieldSet(this, _KeyringController_unsupportedKeyrings, [], "f");
@@ -547,9 +564,7 @@ export class KeyringController extends BaseController {
      */
     getKeyringsByType(type) {
         __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_assertIsUnlocked).call(this);
-        return __classPrivateFieldGet(this, _KeyringController_keyrings, "f")
-            .filter(({ keyring }) => keyring.type === type)
-            .map(({ keyring }) => keyring);
+        return __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_getKeyringEntriesByType).call(this, type).map(({ keyring }) => keyring);
     }
     /**
      * Persist all serialized keyrings in the vault.
@@ -638,7 +653,7 @@ export class KeyringController extends BaseController {
             if (keyringIndex === -1) {
                 throw new KeyringControllerError(KeyringControllerErrorMessage.NoKeyring);
             }
-            const { keyring } = __classPrivateFieldGet(this, _KeyringController_keyrings, "f")[keyringIndex];
+            const { keyring, keyringV2 } = __classPrivateFieldGet(this, _KeyringController_keyrings, "f")[keyringIndex];
             const isPrimaryKeyring = keyringIndex === 0;
             const shouldRemoveKeyring = (await keyring.getAccounts()).length === 1;
             // Primary keyring should never be removed, so we need to keep at least one account in it
@@ -659,7 +674,7 @@ export class KeyringController extends BaseController {
             await keyring.removeAccount(address);
             if (shouldRemoveKeyring) {
                 __classPrivateFieldGet(this, _KeyringController_keyrings, "f").splice(keyringIndex, 1);
-                await __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_destroyKeyring).call(this, keyring);
+                await __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_destroyKeyring).call(this, keyring, keyringV2);
             }
         });
         this.messenger.publish(`${name}:accountRemoved`, address);
@@ -872,7 +887,7 @@ export class KeyringController extends BaseController {
      * @returns Promise resolving when the operation completes.
      */
     async submitEncryptionKey(encryptionKey, encryptionSalt) {
-        const { newMetadata } = await __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_withRollback).call(this, async () => {
+        const { hasChanged } = await __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_withRollback).call(this, async () => {
             const result = await __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_unlockKeyrings).call(this, {
                 encryptionKey,
                 encryptionSalt,
@@ -884,7 +899,7 @@ export class KeyringController extends BaseController {
             // if new metadata has been generated during login, we
             // can attempt to upgrade the vault.
             await __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_withRollback).call(this, async () => {
-                if (newMetadata) {
+                if (hasChanged) {
                     await __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_updateVault).call(this);
                 }
             });
@@ -915,17 +930,17 @@ export class KeyringController extends BaseController {
      * @returns Promise resolving when the operation completes.
      */
     async submitPassword(password) {
-        const { newMetadata } = await __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_withRollback).call(this, async () => {
+        const { hasChanged } = await __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_withRollback).call(this, async () => {
             const result = await __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_unlockKeyrings).call(this, { password });
             __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_setUnlocked).call(this);
             return result;
         });
         try {
             // If there are stronger encryption params available, or
-            // if new metadata has been generated during login, we
+            // if the keyring state has changed during deserialization, we
             // can attempt to upgrade the vault.
             await __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_withRollback).call(this, async () => {
-                if (newMetadata || __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_isNewEncryptionAvailable).call(this)) {
+                if (hasChanged || __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_isNewEncryptionAvailable).call(this)) {
                     await __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_deriveAndSetEncryptionKey).call(this, password, {
                         // If the vault is being upgraded, we want to ignore the metadata
                         // that is already in the vault, so we can effectively
@@ -957,17 +972,20 @@ export class KeyringController extends BaseController {
     }) {
         __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_assertIsUnlocked).call(this);
         return __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_persistOrRollback).call(this, async () => {
-            let keyring = await __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_selectKeyring).call(this, selector);
-            if (!keyring && 'type' in selector && options.createIfMissing) {
-                keyring = (await __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_newKeyring).call(this, selector.type, options.createWithData));
+            let entry = await __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_selectKeyringEntry).call(this, {
+                v2: false,
+                selector,
+            });
+            if (!entry && 'type' in selector && options.createIfMissing) {
+                const newKeyring = (await __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_newKeyring).call(this, selector.type, options.createWithData));
+                entry = __classPrivateFieldGet(this, _KeyringController_keyrings, "f").find(({ keyring }) => keyring === newKeyring);
             }
-            if (!keyring) {
+            if (!entry) {
                 throw new KeyringControllerError(KeyringControllerErrorMessage.KeyringNotFound);
             }
-            return __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_assertNoUnsafeDirectKeyringAccess).call(this, await operation({
-                keyring,
-                metadata: __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_getKeyringMetadata).call(this, keyring),
-            }), keyring);
+            const { metadata } = entry;
+            const keyring = entry.keyring;
+            return __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_assertNoUnsafeDirectKeyringAccess).call(this, await operation({ keyring, metadata }), keyring);
         });
     }
     /**
@@ -1006,16 +1024,109 @@ export class KeyringController extends BaseController {
      */
     async withKeyringUnsafe(selector, operation) {
         __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_assertIsUnlocked).call(this);
-        const keyring = await __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_selectKeyring).call(this, selector);
-        if (!keyring) {
+        const entry = await __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_selectKeyringEntry).call(this, { v2: false, selector });
+        if (!entry) {
             throw new KeyringControllerError(KeyringControllerErrorMessage.KeyringNotFound);
         }
+        const { metadata } = entry;
+        const keyring = entry.keyring;
         // Even if this method is "unsafe", we still want to prevent returning
         // the keyring directly.
-        return __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_assertNoUnsafeDirectKeyringAccess).call(this, await operation({
-            keyring,
-            metadata: __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_getKeyringMetadata).call(this, keyring),
-        }), keyring);
+        return __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_assertNoUnsafeDirectKeyringAccess).call(this, await operation({ keyring, metadata }), keyring);
+    }
+    /**
+     * 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.
+     */
+    async withKeyringV2(selector, operation) {
+        __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_assertIsUnlocked).call(this);
+        return __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_persistOrRollback).call(this, async () => {
+            const entry = await __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_selectKeyringEntry).call(this, {
+                v2: true,
+                selector,
+            });
+            if (!entry) {
+                throw new KeyringControllerError(KeyringControllerErrorMessage.KeyringNotFound);
+            }
+            if (!entry.keyringV2) {
+                throw new KeyringControllerError(KeyringControllerErrorMessage.KeyringV2NotSupported);
+            }
+            const { metadata } = entry;
+            const keyring = entry.keyringV2;
+            return __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_assertNoUnsafeDirectKeyringAccess).call(this, await operation({
+                keyring,
+                metadata,
+            }), keyring);
+        });
+    }
+    /**
+     * 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.
+     */
+    async withKeyringV2Unsafe(selector, operation) {
+        __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_assertIsUnlocked).call(this);
+        const entry = await __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_selectKeyringEntry).call(this, {
+            v2: true,
+            selector,
+        });
+        if (!entry) {
+            throw new KeyringControllerError(KeyringControllerErrorMessage.KeyringNotFound);
+        }
+        if (!entry.keyringV2) {
+            throw new KeyringControllerError(KeyringControllerErrorMessage.KeyringV2NotSupported);
+        }
+        const { metadata } = entry;
+        const keyring = entry.keyringV2;
+        // Even if this method is "unsafe", we still want to prevent returning
+        // the keyring directly.
+        return __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_assertNoUnsafeDirectKeyringAccess).call(this, await operation({ keyring, metadata }), keyring);
     }
     async getAccountKeyringType(account) {
         __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_assertIsUnlocked).call(this);
@@ -1023,11 +1134,15 @@ export class KeyringController extends BaseController {
         return keyring.type;
     }
 }
-_KeyringController_controllerOperationMutex = new WeakMap(), _KeyringController_vaultOperationMutex = new WeakMap(), _KeyringController_keyringBuilders = new WeakMap(), _KeyringController_encryptor = new WeakMap(), _KeyringController_keyrings = new WeakMap(), _KeyringController_unsupportedKeyrings = new WeakMap(), _KeyringController_encryptionKey = new WeakMap(), _KeyringController_instances = new WeakSet(), _KeyringController_getKeyringForAccount = async function _KeyringController_getKeyringForAccount(account) {
+_KeyringController_controllerOperationMutex = new WeakMap(), _KeyringController_vaultOperationMutex = new WeakMap(), _KeyringController_keyringBuilders = new WeakMap(), _KeyringController_keyringV2Builders = new WeakMap(), _KeyringController_encryptor = new WeakMap(), _KeyringController_keyrings = new WeakMap(), _KeyringController_unsupportedKeyrings = new WeakMap(), _KeyringController_encryptionKey = new WeakMap(), _KeyringController_instances = new WeakSet(), _KeyringController_getKeyringForAccount = async function _KeyringController_getKeyringForAccount(account) {
+    __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_assertIsUnlocked).call(this);
+    const entry = await __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_getKeyringEntryForAccount).call(this, account);
+    return entry?.keyring;
+}, _KeyringController_getKeyringEntryForAccount = async function _KeyringController_getKeyringEntryForAccount(account) {
     __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_assertIsUnlocked).call(this);
     const keyringIndex = await __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_findKeyringIndexForAccount).call(this, account);
     if (keyringIndex > -1) {
-        return __classPrivateFieldGet(this, _KeyringController_keyrings, "f")[keyringIndex].keyring;
+        return __classPrivateFieldGet(this, _KeyringController_keyrings, "f")[keyringIndex];
     }
     return undefined;
 }, _KeyringController_findKeyringIndexForAccount = async function _KeyringController_findKeyringIndexForAccount(account) {
@@ -1035,6 +1150,9 @@ _KeyringController_controllerOperationMutex = new WeakMap(), _KeyringController_
     const address = account.toLowerCase();
     const accountsPerKeyring = await Promise.all(__classPrivateFieldGet(this, _KeyringController_keyrings, "f").map(({ keyring }) => keyring.getAccounts()));
     return accountsPerKeyring.findIndex((accounts) => accounts.map((a) => a.toLowerCase()).includes(address));
+}, _KeyringController_getKeyringEntriesByType = function _KeyringController_getKeyringEntriesByType(type) {
+    __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_assertIsUnlocked).call(this);
+    return __classPrivateFieldGet(this, _KeyringController_keyrings, "f").filter(({ keyring }) => keyring.type === type);
 }, _KeyringController_assertNoUnsafeDirectKeyringAccess = function _KeyringController_assertNoUnsafeDirectKeyringAccess(value, keyring) {
     if (Object.is(value, keyring)) {
         // Access to a keyring instance outside of controller safeguards
@@ -1046,32 +1164,46 @@ _KeyringController_controllerOperationMutex = new WeakMap(), _KeyringController_
     return value;
 }, _KeyringController_registerMessageHandlers = function _KeyringController_registerMessageHandlers() {
     this.messenger.registerMethodActionHandlers(this, MESSENGER_EXPOSED_METHODS);
-}, _KeyringController_selectKeyring = 
+}, _KeyringController_selectKeyringEntry = 
 /**
- * Select a keyring using a selector without acquiring the controller lock.
+ * Select a keyring entry using a selector without acquiring the controller lock.
  *
- * @param selector - Keyring selector object.
- * @returns The selected keyring, or `undefined` if no match is found.
+ * @param options - Selection options.
+ * @param options.v2 - Tag to indicate whether the selector is for a V2 keyring.
+ * @param options.selector - Keyring selector object.
+ * @returns The selected keyring entry, or `undefined` if no match is found.
  * @template SelectedKeyring - The expected type of the selected keyring.
+ * @template SelectedKeyringV2 - The expected type of the selected keyring (v2).
  */
-async function _KeyringController_selectKeyring(selector) {
-    let keyring;
+async function _KeyringController_selectKeyringEntry({ v2, selector, }) {
+    let entry;
     if ('address' in selector) {
-        keyring = (await __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_getKeyringForAccount).call(this, selector.address));
+        entry = await __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_getKeyringEntryForAccount).call(this, selector.address);
     }
     else if ('type' in selector) {
-        keyring = this.getKeyringsByType(selector.type)[selector.index ?? 0];
+        entry = __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_getKeyringEntriesByType).call(this, selector.type)[selector.index ?? 0];
     }
     else if ('id' in selector) {
-        keyring = __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_getKeyringById).call(this, selector.id);
+        entry = __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_getKeyringEntryById).call(this, selector.id);
     }
     else if ('filter' in selector) {
-        keyring = __classPrivateFieldGet(this, _KeyringController_keyrings, "f").find(({ keyring: filteredKeyring, metadata }) => selector.filter(filteredKeyring, metadata))?.keyring;
+        entry = __classPrivateFieldGet(this, _KeyringController_keyrings, "f").find(({ keyring, keyringV2, metadata }) => {
+            // If v2, then we'll use the v2 selector which expects a `KeyringV2` instance.
+            if (v2) {
+                // However, some keyrings do not have a v2 wrapper, so we just skip them.
+                if (!keyringV2) {
+                    return false;
+                }
+                return selector.filter(keyringV2, metadata);
+            }
+            return selector.filter(keyring, metadata);
+        });
     }
-    return keyring;
+    return entry;
 }, _KeyringController_getKeyringById = function _KeyringController_getKeyringById(keyringId) {
-    return __classPrivateFieldGet(this, _KeyringController_keyrings, "f").find(({ metadata }) => metadata.id === keyringId)
-        ?.keyring;
+    return __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_getKeyringEntryById).call(this, keyringId)?.keyring;
+}, _KeyringController_getKeyringEntryById = function _KeyringController_getKeyringEntryById(keyringId) {
+    return __classPrivateFieldGet(this, _KeyringController_keyrings, "f").find(({ metadata }) => metadata.id === keyringId);
 }, _KeyringController_getKeyringByIdOrDefault = function _KeyringController_getKeyringByIdOrDefault(keyringId) {
     if (!keyringId) {
         return __classPrivateFieldGet(this, _KeyringController_keyrings, "f")[0]?.keyring;
@@ -1085,6 +1217,8 @@ async function _KeyringController_selectKeyring(selector) {
     return keyringWithMetadata.metadata;
 }, _KeyringController_getKeyringBuilderForType = function _KeyringController_getKeyringBuilderForType(type) {
     return __classPrivateFieldGet(this, _KeyringController_keyringBuilders, "f").find((keyringBuilder) => keyringBuilder.type === type);
+}, _KeyringController_getKeyringV2BuilderForType = function _KeyringController_getKeyringV2BuilderForType(type) {
+    return __classPrivateFieldGet(this, _KeyringController_keyringV2Builders, "f").find((builder) => builder.type === type);
 }, _KeyringController_createNewVaultWithKeyring = 
 /**
  * Create new vault with an initial keyring
@@ -1272,18 +1406,18 @@ async function _KeyringController_getSessionState() {
 async function _KeyringController_restoreSerializedKeyrings(serializedKeyrings) {
     await __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_clearKeyrings).call(this);
     const keyrings = [];
-    let newMetadata = false;
+    let hasChanged = false;
     for (const serializedKeyring of serializedKeyrings) {
         const result = await __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_restoreKeyring).call(this, serializedKeyring);
         if (result) {
             const { keyring, metadata } = result;
             keyrings.push({ keyring, metadata });
-            if (result.newMetadata) {
-                newMetadata = true;
+            if (result.hasChanged) {
+                hasChanged = true;
             }
         }
     }
-    return { keyrings, newMetadata };
+    return { keyrings, hasChanged };
 }, _KeyringController_unlockKeyrings = 
 /**
  * Unlock Keyrings, decrypting the vault and deserializing all
@@ -1313,14 +1447,14 @@ async function _KeyringController_unlockKeyrings(credentials) {
         if (!isSerializedKeyringsArray(vault)) {
             throw new KeyringControllerError(KeyringControllerErrorMessage.VaultDataError);
         }
-        const { keyrings, newMetadata } = await __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_restoreSerializedKeyrings).call(this, vault);
+        const { keyrings, hasChanged } = await __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_restoreSerializedKeyrings).call(this, vault);
         const updatedKeyrings = await __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_getUpdatedKeyrings).call(this);
         this.update((state) => {
             state.keyrings = updatedKeyrings;
             state.encryptionKey = encryptionKey;
             state.encryptionSalt = __classPrivateFieldGet(this, _KeyringController_encryptionKey, "f")?.salt;
         });
-        return { keyrings, newMetadata };
+        return { keyrings, hasChanged };
     });
 }, _KeyringController_updateVault = function _KeyringController_updateVault() {
     return __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_withVaultLock).call(this, async () => {
@@ -1408,8 +1542,8 @@ async function _KeyringController_createKeyringWithFirstAccount(type, opts) {
  * @throws If the keyring includes duplicated accounts.
  */
 async function _KeyringController_newKeyring(type, data) {
-    const keyring = await __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_createKeyring).call(this, type, data);
-    __classPrivateFieldGet(this, _KeyringController_keyrings, "f").push({ keyring, metadata: getDefaultKeyringMetadata() });
+    const { keyring, keyringV2, metadata } = await __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_createKeyring).call(this, type, data);
+    __classPrivateFieldGet(this, _KeyringController_keyrings, "f").push({ keyring, keyringV2, metadata });
     return keyring;
 }, _KeyringController_createKeyring = 
 /**
@@ -1426,11 +1560,13 @@ async function _KeyringController_newKeyring(type, data) {
  *
  * @param type - The type of keyring to add.
  * @param data - Keyring initialization options.
+ * @param metadata - Keyring metadata if available.
  * @returns The new keyring.
  * @throws If the keyring includes duplicated accounts.
  */
-async function _KeyringController_createKeyring(type, data) {
+async function _KeyringController_createKeyring(type, data, metadata) {
     __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_assertControllerMutexIsLocked).call(this);
+    const keyringMetadata = metadata ?? getDefaultKeyringMetadata();
     const keyringBuilder = __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_getKeyringBuilderForType).call(this, type);
     if (!keyringBuilder) {
         throw new KeyringControllerError(`${KeyringControllerErrorMessage.NoKeyringBuilder}. Keyring type: ${type}`);
@@ -1454,7 +1590,13 @@ async function _KeyringController_createKeyring(type, data) {
         await keyring.generateRandomMnemonic();
         await keyring.addAccounts(1);
     }
-    return keyring;
+    // We now create the keyring V2 wrappers and store them in memory.
+    const keyringBuilderV2 = __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_getKeyringV2BuilderForType).call(this, type);
+    let keyringV2;
+    if (keyringBuilderV2) {
+        keyringV2 = keyringBuilderV2(keyring, keyringMetadata);
+    }
+    return { keyring, keyringV2, metadata: keyringMetadata };
 }, _KeyringController_clearKeyrings = 
 /**
  * Remove all managed keyrings, destroying all their
@@ -1462,8 +1604,8 @@ async function _KeyringController_createKeyring(type, data) {
  */
 async function _KeyringController_clearKeyrings() {
     __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_assertControllerMutexIsLocked).call(this);
-    for (const { keyring } of __classPrivateFieldGet(this, _KeyringController_keyrings, "f")) {
-        await __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_destroyKeyring).call(this, keyring);
+    for (const { keyring, keyringV2 } of __classPrivateFieldGet(this, _KeyringController_keyrings, "f")) {
+        await __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_destroyKeyring).call(this, keyring, keyringV2);
     }
     __classPrivateFieldSet(this, _KeyringController_keyrings, [], "f");
     __classPrivateFieldSet(this, _KeyringController_unsupportedKeyrings, [], "f");
@@ -1479,23 +1621,28 @@ async function _KeyringController_restoreKeyring(serialized) {
     __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_assertControllerMutexIsLocked).call(this);
     try {
         const { type, data, metadata: serializedMetadata } = serialized;
-        let newMetadata = false;
+        // Track if we need to trigger a vault update.
+        let hasChanged = false;
+        // If metadata is missing, assume the data is from an installation before we had
+        // keyring metadata.
         let metadata = serializedMetadata;
-        const keyring = await __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_createKeyring).call(this, type, data);
-        await __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_assertNoDuplicateAccounts).call(this, [keyring]);
-        // If metadata is missing, assume the data is from an installation before
-        // we had keyring metadata.
         if (!metadata) {
-            newMetadata = true;
+            hasChanged = true;
             metadata = getDefaultKeyringMetadata();
         }
+        const oldState = JSON.stringify(data);
+        const { keyring, keyringV2 } = await __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_createKeyring).call(this, type, data, metadata);
+        const newState = JSON.stringify(await keyring.serialize());
+        hasChanged || (hasChanged = oldState !== newState);
+        await __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_assertNoDuplicateAccounts).call(this, [keyring]);
         // The keyring is added to the keyrings array only if it's successfully restored
         // and the metadata is successfully added to the controller
         __classPrivateFieldGet(this, _KeyringController_keyrings, "f").push({
             keyring,
+            keyringV2,
             metadata,
         });
-        return { keyring, metadata, newMetadata };
+        return { keyring, keyringV2, metadata, hasChanged };
     }
     catch (error) {
         console.error(error);
@@ -1511,9 +1658,13 @@ async function _KeyringController_restoreKeyring(serialized) {
  * clears the keyring bridge iframe from the DOM.
  *
  * @param keyring - The keyring to destroy.
+ * @param keyringV2 - The keyring v2 to destroy (if any).
  */
-async function _KeyringController_destroyKeyring(keyring) {
+async function _KeyringController_destroyKeyring(keyring, keyringV2) {
     await keyring.destroy?.();
+    if (keyringV2) {
+        await keyringV2.destroy?.();
+    }
 }, _KeyringController_assertNoDuplicateAccounts = 
 /**
  * Assert that there are no duplicate accounts in the keyrings.
@@ -1551,7 +1702,7 @@ async function _KeyringController_persistOrRollback(callback) {
         const callbackResult = await callback({ releaseLock });
         const newState = JSON.stringify(await __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_getSessionState).call(this));
         // State is committed only if the operation is successful and need to trigger a vault update.
-        if (!isEqual(oldState, newState)) {
+        if (oldState !== newState) {
             await __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_updateVault).call(this);
         }
         return callbackResult;