@metamask-previews/keyring-controller 15.0.0-preview-aedc5103 → 15.0.0-preview-02d970ca

package/dist/{chunk-5QTEIEPG.mjs → chunk-USAGXPFN.mjs}

@@ -3,7 +3,7 @@ import {
   __privateGet,
   __privateMethod,
   __privateSet
-} from "./chunk-XPARO3LL.mjs";
+} from "./chunk-4OE2G6WW.mjs";
 
 // src/KeyringController.ts
 import { isValidPrivate, toBuffer, getBinarySize } from "@ethereumjs/util";
@@ -86,7 +86,7 @@ async function displayForKeyring(keyring) {
     accounts: accounts.map(normalize)
   };
 }
-var _initVaultMutex, _vaultOperationMutex, _keyringBuilders, _keyrings, _unsupportedKeyrings, _password, _encryptor, _cacheEncryptionKey, _qrKeyringStateListener, _registerMessageHandlers, registerMessageHandlers_fn, _getKeyringBuilderForType, getKeyringBuilderForType_fn, _addQRKeyring, addQRKeyring_fn, _subscribeToQRKeyringEvents, subscribeToQRKeyringEvents_fn, _unsubscribeFromQRKeyringsEvents, unsubscribeFromQRKeyringsEvents_fn, _createNewVaultWithKeyring, createNewVaultWithKeyring_fn, _getUpdatedKeyrings, getUpdatedKeyrings_fn, _unlockKeyrings, unlockKeyrings_fn, _updateVault, updateVault_fn, _getAccountsFromKeyrings, getAccountsFromKeyrings_fn, _createKeyringWithFirstAccount, createKeyringWithFirstAccount_fn, _newKeyring, newKeyring_fn, _clearKeyrings, clearKeyrings_fn, _restoreKeyring, restoreKeyring_fn, _destroyKeyring, destroyKeyring_fn, _removeEmptyKeyrings, removeEmptyKeyrings_fn, _checkForDuplicate, checkForDuplicate_fn, _setUnlocked, setUnlocked_fn, _getMemState, getMemState_fn, _withVaultLock, withVaultLock_fn;
+var _controllerOperationMutex, _vaultOperationMutex, _keyringBuilders, _keyrings, _unsupportedKeyrings, _password, _encryptor, _cacheEncryptionKey, _qrKeyringStateListener, _registerMessageHandlers, registerMessageHandlers_fn, _getKeyringBuilderForType, getKeyringBuilderForType_fn, _addQRKeyring, addQRKeyring_fn, _subscribeToQRKeyringEvents, subscribeToQRKeyringEvents_fn, _unsubscribeFromQRKeyringsEvents, unsubscribeFromQRKeyringsEvents_fn, _createNewVaultWithKeyring, createNewVaultWithKeyring_fn, _getUpdatedKeyrings, getUpdatedKeyrings_fn, _getSerializedKeyrings, getSerializedKeyrings_fn, _restoreSerializedKeyrings, restoreSerializedKeyrings_fn, _unlockKeyrings, unlockKeyrings_fn, _updateVault, updateVault_fn, _getAccountsFromKeyrings, getAccountsFromKeyrings_fn, _createKeyringWithFirstAccount, createKeyringWithFirstAccount_fn, _newKeyring, newKeyring_fn, _clearKeyrings, clearKeyrings_fn, _restoreKeyring, restoreKeyring_fn, _destroyKeyring, destroyKeyring_fn, _removeEmptyKeyrings, removeEmptyKeyrings_fn, _checkForDuplicate, checkForDuplicate_fn, _setUnlocked, setUnlocked_fn, _persistOrRollback, persistOrRollback_fn, _withRollback, withRollback_fn, _assertControllerMutexIsLocked, assertControllerMutexIsLocked_fn, _withControllerLock, withControllerLock_fn, _withVaultLock, withVaultLock_fn;
 var KeyringController = class extends BaseController {
   /**
    * Creates a KeyringController instance.
@@ -170,6 +170,21 @@ var KeyringController = class extends BaseController {
      * @returns A promise resolving to the updated keyrings array.
      */
     __privateAdd(this, _getUpdatedKeyrings);
+    /**
+     * Serialize the current array of keyring instances,
+     * including unsupported keyrings by default.
+     *
+     * @param options - Method options.
+     * @param options.includeUnsupported - Whether to include unsupported keyrings.
+     * @returns The serialized keyrings.
+     */
+    __privateAdd(this, _getSerializedKeyrings);
+    /**
+     * Restore a serialized keyrings array.
+     *
+     * @param serializedKeyrings - The serialized keyrings array.
+     */
+    __privateAdd(this, _restoreSerializedKeyrings);
     /**
      * Unlock Keyrings, decrypting the vault and deserializing all
      * keyrings contained in it, using a password or an encryption key with salt.
@@ -210,7 +225,6 @@ var KeyringController = class extends BaseController {
      *
      * @param type - The type of keyring to add.
      * @param data - The data to restore a previously serialized keyring.
-     * @param persist - Whether to persist the keyring to the vault.
      * @returns The new keyring.
      * @throws If the keyring includes duplicated accounts.
      */
@@ -218,9 +232,6 @@ var KeyringController = class extends BaseController {
     /**
      * Remove all managed keyrings, destroying all their
      * instances in memory.
-     *
-     * @param options - Operations options.
-     * @param options.skipStateUpdate - Whether to skip updating the controller state.
      */
     __privateAdd(this, _clearKeyrings);
     /**
@@ -266,7 +277,42 @@ var KeyringController = class extends BaseController {
      * @fires KeyringController:unlock
      */
     __privateAdd(this, _setUnlocked);
-    __privateAdd(this, _getMemState);
+    /**
+     * Execute the given function after acquiring the controller lock
+     * and save the keyrings to state after it, or rollback to their
+     * previous state in case of error.
+     *
+     * @param fn - The function to execute.
+     * @returns The result of the function.
+     */
+    __privateAdd(this, _persistOrRollback);
+    /**
+     * Execute the given function after acquiring the controller lock
+     * and rollback keyrings and password states in case of error.
+     *
+     * @param fn - The function to execute atomically.
+     * @returns The result of the function.
+     */
+    __privateAdd(this, _withRollback);
+    /**
+     * Assert that the controller mutex is locked.
+     *
+     * @throws If the controller mutex is not locked.
+     */
+    __privateAdd(this, _assertControllerMutexIsLocked);
+    /**
+     * Lock the controller mutex before executing the given function,
+     * and release it after the function is resolved or after an
+     * error is thrown.
+     *
+     * This wrapper ensures that each mutable operation that interacts with the
+     * controller and that changes its state is executed in a mutually exclusive way,
+     * preventing unsafe concurrent access that could lead to unpredictable behavior.
+     *
+     * @param fn - The function to execute while the controller mutex is locked.
+     * @returns The result of the function.
+     */
+    __privateAdd(this, _withControllerLock);
     /**
      * Lock the vault mutex before executing the given function,
      * and release it after the function is resolved or after an
@@ -279,7 +325,7 @@ var KeyringController = class extends BaseController {
      * @returns The result of the function.
      */
     __privateAdd(this, _withVaultLock);
-    __privateAdd(this, _initVaultMutex, new Mutex());
+    __privateAdd(this, _controllerOperationMutex, new Mutex());
     __privateAdd(this, _vaultOperationMutex, new Mutex());
     __privateAdd(this, _keyringBuilders, void 0);
     __privateAdd(this, _keyrings, void 0);
@@ -303,75 +349,71 @@ var KeyringController = class extends BaseController {
    *
    * @param accountCount - Number of accounts before adding a new one, used to
    * make the method idempotent.
-   * @returns Promise resolving to keyring current state and added account
-   * address.
+   * @returns Promise resolving to the added account address.
    */
   async addNewAccount(accountCount) {
-    const primaryKeyring = this.getKeyringsByType("HD Key Tree")[0];
-    if (!primaryKeyring) {
-      throw new Error("No HD keyring found");
-    }
-    const oldAccounts = await primaryKeyring.getAccounts();
-    if (accountCount && oldAccounts.length !== accountCount) {
-      if (accountCount > oldAccounts.length) {
-        throw new Error("Account out of sequence");
+    return __privateMethod(this, _persistOrRollback, persistOrRollback_fn).call(this, async () => {
+      const primaryKeyring = this.getKeyringsByType("HD Key Tree")[0];
+      if (!primaryKeyring) {
+        throw new Error("No HD keyring found");
       }
-      const existingAccount = oldAccounts[accountCount];
-      if (!existingAccount) {
-        throw new Error(`Can't find account at index ${accountCount}`);
+      const oldAccounts = await primaryKeyring.getAccounts();
+      if (accountCount && oldAccounts.length !== accountCount) {
+        if (accountCount > oldAccounts.length) {
+          throw new Error("Account out of sequence");
+        }
+        const existingAccount = oldAccounts[accountCount];
+        if (!existingAccount) {
+          throw new Error(`Can't find account at index ${accountCount}`);
+        }
+        return existingAccount;
       }
-      return {
-        keyringState: __privateMethod(this, _getMemState, getMemState_fn).call(this),
-        addedAccountAddress: existingAccount
-      };
-    }
-    const [addedAccountAddress] = await primaryKeyring.addAccounts(1);
-    await this.verifySeedPhrase();
-    await __privateMethod(this, _updateVault, updateVault_fn).call(this);
-    return {
-      keyringState: __privateMethod(this, _getMemState, getMemState_fn).call(this),
-      addedAccountAddress
-    };
+      const [addedAccountAddress] = await primaryKeyring.addAccounts(1);
+      await this.verifySeedPhrase();
+      return addedAccountAddress;
+    });
   }
   /**
    * Adds a new account to the specified keyring.
    *
    * @param keyring - Keyring to add the account to.
    * @param accountCount - Number of accounts before adding a new one, used to make the method idempotent.
-   * @returns Promise resolving to keyring current state and added account
+   * @returns Promise resolving to the added account address
    */
   async addNewAccountForKeyring(keyring, accountCount) {
-    const oldAccounts = await __privateMethod(this, _getAccountsFromKeyrings, getAccountsFromKeyrings_fn).call(this);
-    if (accountCount && oldAccounts.length !== accountCount) {
-      if (accountCount > oldAccounts.length) {
-        throw new Error("Account out of sequence");
+    return __privateMethod(this, _persistOrRollback, persistOrRollback_fn).call(this, async () => {
+      const oldAccounts = await __privateMethod(this, _getAccountsFromKeyrings, getAccountsFromKeyrings_fn).call(this);
+      if (accountCount && oldAccounts.length !== accountCount) {
+        if (accountCount > oldAccounts.length) {
+          throw new Error("Account out of sequence");
+        }
+        const existingAccount = oldAccounts[accountCount];
+        assertIsStrictHexString(existingAccount);
+        return existingAccount;
       }
-      const existingAccount = oldAccounts[accountCount];
-      assertIsStrictHexString(existingAccount);
-      return existingAccount;
-    }
-    await keyring.addAccounts(1);
-    await __privateMethod(this, _updateVault, updateVault_fn).call(this);
-    const addedAccountAddress = (await __privateMethod(this, _getAccountsFromKeyrings, getAccountsFromKeyrings_fn).call(this)).find(
-      (selectedAddress) => !oldAccounts.includes(selectedAddress)
-    );
-    assertIsStrictHexString(addedAccountAddress);
-    return addedAccountAddress;
+      await keyring.addAccounts(1);
+      const addedAccountAddress = (await __privateMethod(this, _getAccountsFromKeyrings, getAccountsFromKeyrings_fn).call(this)).find(
+        (selectedAddress) => !oldAccounts.includes(selectedAddress)
+      );
+      assertIsStrictHexString(addedAccountAddress);
+      return addedAccountAddress;
+    });
   }
   /**
    * Adds a new account to the default (first) HD seed phrase keyring without updating identities in preferences.
    *
-   * @returns Promise resolving to current state when the account is added.
+   * @returns Promise resolving to the added account address.
    */
   async addNewAccountWithoutUpdate() {
-    const primaryKeyring = this.getKeyringsByType("HD Key Tree")[0];
-    if (!primaryKeyring) {
-      throw new Error("No HD keyring found");
-    }
-    await primaryKeyring.addAccounts(1);
-    await __privateMethod(this, _updateVault, updateVault_fn).call(this);
-    await this.verifySeedPhrase();
-    return __privateMethod(this, _getMemState, getMemState_fn).call(this);
+    return __privateMethod(this, _persistOrRollback, persistOrRollback_fn).call(this, async () => {
+      const primaryKeyring = this.getKeyringsByType("HD Key Tree")[0];
+      if (!primaryKeyring) {
+        throw new Error("No HD keyring found");
+      }
+      const [addedAccountAddress] = await primaryKeyring.addAccounts(1);
+      await this.verifySeedPhrase();
+      return addedAccountAddress;
+    });
   }
   /**
    * Effectively the same as creating a new keychain then populating it
@@ -380,14 +422,13 @@ var KeyringController = class extends BaseController {
    * @param password - Password to unlock keychain.
    * @param seed - A BIP39-compliant seed phrase as Uint8Array,
    * either as a string or an array of UTF-8 bytes that represent the string.
-   * @returns Promise resolving to the restored keychain object.
+   * @returns Promise resolving when the operation ends successfully.
    */
   async createNewVaultAndRestore(password, seed) {
-    const releaseLock = await __privateGet(this, _initVaultMutex).acquire();
-    if (!password || !password.length) {
-      throw new Error("Invalid password");
-    }
-    try {
+    return __privateMethod(this, _persistOrRollback, persistOrRollback_fn).call(this, async () => {
+      if (!password || !password.length) {
+        throw new Error("Invalid password");
+      }
       await __privateMethod(this, _createNewVaultWithKeyring, createNewVaultWithKeyring_fn).call(this, password, {
         type: "HD Key Tree" /* hd */,
         opts: {
@@ -395,30 +436,23 @@ var KeyringController = class extends BaseController {
           numberOfAccounts: 1
         }
       });
-      return __privateMethod(this, _getMemState, getMemState_fn).call(this);
-    } finally {
-      releaseLock();
-    }
+    });
   }
   /**
    * Create a new primary keychain and wipe any previous keychains.
    *
    * @param password - Password to unlock the new vault.
-   * @returns Newly-created keychain object.
+   * @returns Promise resolving when the operation ends successfully.
    */
   async createNewVaultAndKeychain(password) {
-    const releaseLock = await __privateGet(this, _initVaultMutex).acquire();
-    try {
+    return __privateMethod(this, _persistOrRollback, persistOrRollback_fn).call(this, async () => {
       const accounts = await __privateMethod(this, _getAccountsFromKeyrings, getAccountsFromKeyrings_fn).call(this);
       if (!accounts.length) {
         await __privateMethod(this, _createNewVaultWithKeyring, createNewVaultWithKeyring_fn).call(this, password, {
           type: "HD Key Tree" /* hd */
         });
       }
-      return __privateMethod(this, _getMemState, getMemState_fn).call(this);
-    } finally {
-      releaseLock();
-    }
+    });
   }
   /**
    * Adds a new keyring of the given `type`.
@@ -432,7 +466,7 @@ var KeyringController = class extends BaseController {
     if (type === "QR Hardware Wallet Device" /* qr */) {
       return this.getOrAddQRKeyring();
     }
-    return __privateMethod(this, _newKeyring, newKeyring_fn).call(this, type, opts, true);
+    return __privateMethod(this, _persistOrRollback, persistOrRollback_fn).call(this, async () => __privateMethod(this, _newKeyring, newKeyring_fn).call(this, type, opts));
   }
   /**
    * Method to verify a given password validity. Throws an
@@ -488,7 +522,10 @@ var KeyringController = class extends BaseController {
    * @returns A promise resolving to an array of addresses.
    */
   async getAccounts() {
-    return __privateMethod(this, _getAccountsFromKeyrings, getAccountsFromKeyrings_fn).call(this);
+    return this.state.keyrings.reduce(
+      (accounts, keyring) => accounts.concat(keyring.accounts),
+      []
+    );
   }
   /**
    * Get encryption public key.
@@ -532,7 +569,7 @@ var KeyringController = class extends BaseController {
    *
    * @deprecated Use of this method is discouraged as actions executed directly on
    * keyrings are not being reflected in the KeyringController state and not
-   * persisted in the vault.
+   * persisted in the vault. Use `withKeyring` instead.
    * @param account - An account address.
    * @returns Promise resolving to keyring of the `account` if one exists.
    */
@@ -567,7 +604,7 @@ var KeyringController = class extends BaseController {
    *
    * @deprecated Use of this method is discouraged as actions executed directly on
    * keyrings are not being reflected in the KeyringController state and not
-   * persisted in the vault.
+   * persisted in the vault. Use `withKeyring` instead.
    * @param type - Keyring type name.
    * @returns An array of keyrings of the given type.
    */
@@ -577,11 +614,12 @@ var KeyringController = class extends BaseController {
   /**
    * Persist all serialized keyrings in the vault.
    *
+   * @deprecated This method is being phased out in favor of `withKeyring`.
    * @returns Promise resolving with `true` value when the
    * operation completes.
    */
   async persistAllKeyrings() {
-    return __privateMethod(this, _updateVault, updateVault_fn).call(this);
+    return __privateMethod(this, _persistOrRollback, persistOrRollback_fn).call(this, async () => true);
   }
   /**
    * Imports an account with the specified import strategy.
@@ -589,88 +627,89 @@ var KeyringController = class extends BaseController {
    * @param strategy - Import strategy name.
    * @param args - Array of arguments to pass to the underlying stategy.
    * @throws Will throw when passed an unrecognized strategy.
-   * @returns Promise resolving to keyring current state and imported account
-   * address.
+   * @returns Promise resolving to the imported account address.
    */
   async importAccountWithStrategy(strategy, args) {
-    let privateKey;
-    switch (strategy) {
-      case "privateKey":
-        const [importedKey] = args;
-        if (!importedKey) {
-          throw new Error("Cannot import an empty key.");
-        }
-        const prefixed = add0x(importedKey);
-        let bufferedPrivateKey;
-        try {
-          bufferedPrivateKey = toBuffer(prefixed);
-        } catch {
-          throw new Error("Cannot import invalid private key.");
-        }
-        if (!isValidPrivate(bufferedPrivateKey) || // ensures that the key is 64 bytes long
-        getBinarySize(prefixed) !== 64 + "0x".length) {
-          throw new Error("Cannot import invalid private key.");
-        }
-        privateKey = remove0x(prefixed);
-        break;
-      case "json":
-        let wallet;
-        const [input, password] = args;
-        try {
-          wallet = importers.fromEtherWallet(input, password);
-        } catch (e) {
-          wallet = wallet || await Wallet.fromV3(input, password, true);
-        }
-        privateKey = bytesToHex(wallet.getPrivateKey());
-        break;
-      default:
-        throw new Error(`Unexpected import strategy: '${strategy}'`);
-    }
-    const newKeyring = await __privateMethod(this, _newKeyring, newKeyring_fn).call(this, "Simple Key Pair" /* simple */, [privateKey], true);
-    const accounts = await newKeyring.getAccounts();
-    return {
-      keyringState: __privateMethod(this, _getMemState, getMemState_fn).call(this),
-      importedAccountAddress: accounts[0]
-    };
+    return __privateMethod(this, _persistOrRollback, persistOrRollback_fn).call(this, async () => {
+      let privateKey;
+      switch (strategy) {
+        case "privateKey":
+          const [importedKey] = args;
+          if (!importedKey) {
+            throw new Error("Cannot import an empty key.");
+          }
+          const prefixed = add0x(importedKey);
+          let bufferedPrivateKey;
+          try {
+            bufferedPrivateKey = toBuffer(prefixed);
+          } catch {
+            throw new Error("Cannot import invalid private key.");
+          }
+          if (!isValidPrivate(bufferedPrivateKey) || // ensures that the key is 64 bytes long
+          getBinarySize(prefixed) !== 64 + "0x".length) {
+            throw new Error("Cannot import invalid private key.");
+          }
+          privateKey = remove0x(prefixed);
+          break;
+        case "json":
+          let wallet;
+          const [input, password] = args;
+          try {
+            wallet = importers.fromEtherWallet(input, password);
+          } catch (e) {
+            wallet = wallet || await Wallet.fromV3(input, password, true);
+          }
+          privateKey = bytesToHex(wallet.getPrivateKey());
+          break;
+        default:
+          throw new Error(`Unexpected import strategy: '${strategy}'`);
+      }
+      const newKeyring = await __privateMethod(this, _newKeyring, newKeyring_fn).call(this, "Simple Key Pair" /* simple */, [
+        privateKey
+      ]);
+      const accounts = await newKeyring.getAccounts();
+      return accounts[0];
+    });
   }
   /**
    * Removes an account from keyring state.
    *
    * @param address - Address of the account to remove.
    * @fires KeyringController:accountRemoved
-   * @returns Promise resolving current state when this account removal completes.
+   * @returns Promise resolving when the account is removed.
    */
   async removeAccount(address) {
-    const keyring = await this.getKeyringForAccount(
-      address
-    );
-    if (!keyring.removeAccount) {
-      throw new Error("`KeyringController - The keyring for the current address does not support the method removeAccount" /* UnsupportedRemoveAccount */);
-    }
-    await keyring.removeAccount(address);
-    const accounts = await keyring.getAccounts();
-    if (accounts.length === 0) {
-      await __privateMethod(this, _removeEmptyKeyrings, removeEmptyKeyrings_fn).call(this);
-    }
-    await __privateMethod(this, _updateVault, updateVault_fn).call(this);
+    await __privateMethod(this, _persistOrRollback, persistOrRollback_fn).call(this, async () => {
+      const keyring = await this.getKeyringForAccount(
+        address
+      );
+      if (!keyring.removeAccount) {
+        throw new Error("`KeyringController - The keyring for the current address does not support the method removeAccount" /* UnsupportedRemoveAccount */);
+      }
+      await keyring.removeAccount(address);
+      const accounts = await keyring.getAccounts();
+      if (accounts.length === 0) {
+        await __privateMethod(this, _removeEmptyKeyrings, removeEmptyKeyrings_fn).call(this);
+      }
+    });
     this.messagingSystem.publish(`${name}:accountRemoved`, address);
-    return __privateMethod(this, _getMemState, getMemState_fn).call(this);
   }
   /**
    * Deallocates all secrets and locks the wallet.
    *
-   * @returns Promise resolving to current state.
+   * @returns Promise resolving when the operation completes.
    */
   async setLocked() {
-    __privateMethod(this, _unsubscribeFromQRKeyringsEvents, unsubscribeFromQRKeyringsEvents_fn).call(this);
-    __privateSet(this, _password, void 0);
-    this.update((state) => {
-      state.isUnlocked = false;
-      state.keyrings = [];
+    return __privateMethod(this, _withRollback, withRollback_fn).call(this, async () => {
+      __privateMethod(this, _unsubscribeFromQRKeyringsEvents, unsubscribeFromQRKeyringsEvents_fn).call(this);
+      __privateSet(this, _password, void 0);
+      await __privateMethod(this, _clearKeyrings, clearKeyrings_fn).call(this);
+      this.update((state) => {
+        state.isUnlocked = false;
+        state.keyrings = [];
+      });
+      this.messagingSystem.publish(`${name}:lock`);
     });
-    await __privateMethod(this, _clearKeyrings, clearKeyrings_fn).call(this);
-    this.messagingSystem.publish(`${name}:lock`);
-    return __privateMethod(this, _getMemState, getMemState_fn).call(this);
   }
   /**
    * Signs message by calling down into a specific keyring.
@@ -824,32 +863,26 @@ var KeyringController = class extends BaseController {
    *
    * @param encryptionKey - Key to unlock the keychain.
    * @param encryptionSalt - Salt to unlock the keychain.
-   * @returns Promise resolving to the current state.
+   * @returns Promise resolving when the operation completes.
    */
   async submitEncryptionKey(encryptionKey, encryptionSalt) {
-    __privateSet(this, _keyrings, await __privateMethod(this, _unlockKeyrings, unlockKeyrings_fn).call(this, void 0, encryptionKey, encryptionSalt));
-    __privateMethod(this, _setUnlocked, setUnlocked_fn).call(this);
-    const qrKeyring = this.getQRKeyring();
-    if (qrKeyring) {
-      __privateMethod(this, _subscribeToQRKeyringEvents, subscribeToQRKeyringEvents_fn).call(this, qrKeyring);
-    }
-    return __privateMethod(this, _getMemState, getMemState_fn).call(this);
+    return __privateMethod(this, _withRollback, withRollback_fn).call(this, async () => {
+      __privateSet(this, _keyrings, await __privateMethod(this, _unlockKeyrings, unlockKeyrings_fn).call(this, void 0, encryptionKey, encryptionSalt));
+      __privateMethod(this, _setUnlocked, setUnlocked_fn).call(this);
+    });
   }
   /**
    * Attempts to decrypt the current vault and load its keyrings,
    * using the given password.
    *
    * @param password - Password to unlock the keychain.
-   * @returns Promise resolving to the current state.
+   * @returns Promise resolving when the operation completes.
    */
   async submitPassword(password) {
-    __privateSet(this, _keyrings, await __privateMethod(this, _unlockKeyrings, unlockKeyrings_fn).call(this, password));
-    __privateMethod(this, _setUnlocked, setUnlocked_fn).call(this);
-    const qrKeyring = this.getQRKeyring();
-    if (qrKeyring) {
-      __privateMethod(this, _subscribeToQRKeyringEvents, subscribeToQRKeyringEvents_fn).call(this, qrKeyring);
-    }
-    return __privateMethod(this, _getMemState, getMemState_fn).call(this);
+    return __privateMethod(this, _withRollback, withRollback_fn).call(this, async () => {
+      __privateSet(this, _keyrings, await __privateMethod(this, _unlockKeyrings, unlockKeyrings_fn).call(this, password));
+      __privateMethod(this, _setUnlocked, setUnlocked_fn).call(this);
+    });
   }
   /**
    * Verifies the that the seed phrase restores the current keychain's accounts.
@@ -884,6 +917,29 @@ var KeyringController = class extends BaseController {
     });
     return seedWords;
   }
+  async withKeyring(selector, operation, options = {
+    createIfMissing: false
+  }) {
+    return __privateMethod(this, _persistOrRollback, persistOrRollback_fn).call(this, async () => {
+      let keyring;
+      if ("address" in selector) {
+        keyring = await this.getKeyringForAccount(selector.address);
+      } else {
+        keyring = this.getKeyringsByType(selector.type)[selector.index || 0];
+        if (!keyring && options.createIfMissing) {
+          keyring = await __privateMethod(this, _newKeyring, newKeyring_fn).call(this, selector.type, options.createWithData);
+        }
+      }
+      if (!keyring) {
+        throw new Error("KeyringController - Keyring not found." /* KeyringNotFound */);
+      }
+      const result = await operation(keyring);
+      if (Object.is(result, keyring)) {
+        throw new Error("KeyringController - Returning keyring instances is unsafe" /* UnsafeDirectKeyringAccess */);
+      }
+      return result;
+    });
+  }
   // QR Hardware related methods
   /**
    * Get QR Hardware keyring.
@@ -899,14 +955,15 @@ var KeyringController = class extends BaseController {
    * @returns The added keyring
    */
   async getOrAddQRKeyring() {
-    return this.getQRKeyring() || await __privateMethod(this, _addQRKeyring, addQRKeyring_fn).call(this);
+    return this.getQRKeyring() || await __privateMethod(this, _persistOrRollback, persistOrRollback_fn).call(this, async () => __privateMethod(this, _addQRKeyring, addQRKeyring_fn).call(this));
   }
   // TODO: Replace `any` with type
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   async restoreQRKeyring(serialized) {
-    const keyring = this.getQRKeyring() || await __privateMethod(this, _addQRKeyring, addQRKeyring_fn).call(this);
-    keyring.deserialize(serialized);
-    await __privateMethod(this, _updateVault, updateVault_fn).call(this);
+    return __privateMethod(this, _persistOrRollback, persistOrRollback_fn).call(this, async () => {
+      const keyring = this.getQRKeyring() || await __privateMethod(this, _addQRKeyring, addQRKeyring_fn).call(this);
+      keyring.deserialize(serialized);
+    });
   }
   async resetQRKeyringState() {
     (await this.getOrAddQRKeyring()).resetStore();
@@ -933,34 +990,37 @@ var KeyringController = class extends BaseController {
     (await this.getOrAddQRKeyring()).cancelSync();
   }
   async connectQRHardware(page) {
-    try {
-      const keyring = this.getQRKeyring() || await __privateMethod(this, _addQRKeyring, addQRKeyring_fn).call(this);
-      let accounts;
-      switch (page) {
-        case -1:
-          accounts = await keyring.getPreviousPage();
-          break;
-        case 1:
-          accounts = await keyring.getNextPage();
-          break;
-        default:
-          accounts = await keyring.getFirstPage();
+    return __privateMethod(this, _persistOrRollback, persistOrRollback_fn).call(this, async () => {
+      try {
+        const keyring = this.getQRKeyring() || await __privateMethod(this, _addQRKeyring, addQRKeyring_fn).call(this);
+        let accounts;
+        switch (page) {
+          case -1:
+            accounts = await keyring.getPreviousPage();
+            break;
+          case 1:
+            accounts = await keyring.getNextPage();
+            break;
+          default:
+            accounts = await keyring.getFirstPage();
+        }
+        return accounts.map((account) => {
+          return {
+            ...account,
+            balance: "0x0"
+          };
+        });
+      } catch (e) {
+        throw new Error(`Unspecified error when connect QR Hardware, ${e}`);
       }
-      return accounts.map((account) => {
-        return {
-          ...account,
-          balance: "0x0"
-        };
-      });
-    } catch (e) {
-      throw new Error(`Unspecified error when connect QR Hardware, ${e}`);
-    }
+    });
   }
   async unlockQRHardwareWalletAccount(index) {
-    const keyring = this.getQRKeyring() || await __privateMethod(this, _addQRKeyring, addQRKeyring_fn).call(this);
-    keyring.setAccountToUnlock(index);
-    await keyring.addAccounts(1);
-    await __privateMethod(this, _updateVault, updateVault_fn).call(this);
+    return __privateMethod(this, _persistOrRollback, persistOrRollback_fn).call(this, async () => {
+      const keyring = this.getQRKeyring() || await __privateMethod(this, _addQRKeyring, addQRKeyring_fn).call(this);
+      keyring.setAccountToUnlock(index);
+      await keyring.addAccounts(1);
+    });
   }
   async getAccountKeyringType(account) {
     const keyring = await this.getKeyringForAccount(
@@ -969,21 +1029,22 @@ var KeyringController = class extends BaseController {
     return keyring.type;
   }
   async forgetQRDevice() {
-    const keyring = this.getQRKeyring();
-    if (!keyring) {
-      return { removedAccounts: [], remainingAccounts: [] };
-    }
-    const allAccounts = await __privateMethod(this, _getAccountsFromKeyrings, getAccountsFromKeyrings_fn).call(this);
-    keyring.forgetDevice();
-    const remainingAccounts = await __privateMethod(this, _getAccountsFromKeyrings, getAccountsFromKeyrings_fn).call(this);
-    const removedAccounts = allAccounts.filter(
-      (address) => !remainingAccounts.includes(address)
-    );
-    await __privateMethod(this, _updateVault, updateVault_fn).call(this);
-    return { removedAccounts, remainingAccounts };
+    return __privateMethod(this, _persistOrRollback, persistOrRollback_fn).call(this, async () => {
+      const keyring = this.getQRKeyring();
+      if (!keyring) {
+        return { removedAccounts: [], remainingAccounts: [] };
+      }
+      const allAccounts = await __privateMethod(this, _getAccountsFromKeyrings, getAccountsFromKeyrings_fn).call(this);
+      keyring.forgetDevice();
+      const remainingAccounts = await __privateMethod(this, _getAccountsFromKeyrings, getAccountsFromKeyrings_fn).call(this);
+      const removedAccounts = allAccounts.filter(
+        (address) => !remainingAccounts.includes(address)
+      );
+      return { removedAccounts, remainingAccounts };
+    });
   }
 };
-_initVaultMutex = new WeakMap();
+_controllerOperationMutex = new WeakMap();
 _vaultOperationMutex = new WeakMap();
 _keyringBuilders = new WeakMap();
 _keyrings = new WeakMap();
@@ -1051,15 +1112,10 @@ getKeyringBuilderForType_fn = function(type) {
 };
 _addQRKeyring = new WeakSet();
 addQRKeyring_fn = async function() {
-  const qrKeyring = await __privateMethod(this, _newKeyring, newKeyring_fn).call(this, "QR Hardware Wallet Device" /* qr */, {
+  __privateMethod(this, _assertControllerMutexIsLocked, assertControllerMutexIsLocked_fn).call(this);
+  return await __privateMethod(this, _newKeyring, newKeyring_fn).call(this, "QR Hardware Wallet Device" /* qr */, {
     accounts: []
   });
-  const accounts = await qrKeyring.getAccounts();
-  await __privateMethod(this, _checkForDuplicate, checkForDuplicate_fn).call(this, "QR Hardware Wallet Device" /* qr */, accounts);
-  __privateGet(this, _keyrings).push(qrKeyring);
-  await __privateMethod(this, _updateVault, updateVault_fn).call(this);
-  __privateMethod(this, _subscribeToQRKeyringEvents, subscribeToQRKeyringEvents_fn).call(this, qrKeyring);
-  return qrKeyring;
 };
 _subscribeToQRKeyringEvents = new WeakSet();
 subscribeToQRKeyringEvents_fn = function(qrKeyring) {
@@ -1081,6 +1137,7 @@ unsubscribeFromQRKeyringsEvents_fn = function() {
 };
 _createNewVaultWithKeyring = new WeakSet();
 createNewVaultWithKeyring_fn = async function(password, keyring) {
+  __privateMethod(this, _assertControllerMutexIsLocked, assertControllerMutexIsLocked_fn).call(this);
   if (typeof password !== "string") {
     throw new TypeError("KeyringController - Password must be of type string." /* WrongPasswordType */);
   }
@@ -1088,12 +1145,36 @@ createNewVaultWithKeyring_fn = async function(password, keyring) {
   await __privateMethod(this, _clearKeyrings, clearKeyrings_fn).call(this);
   await __privateMethod(this, _createKeyringWithFirstAccount, createKeyringWithFirstAccount_fn).call(this, keyring.type, keyring.opts);
   __privateMethod(this, _setUnlocked, setUnlocked_fn).call(this);
-  return __privateMethod(this, _getMemState, getMemState_fn).call(this);
 };
 _getUpdatedKeyrings = new WeakSet();
 getUpdatedKeyrings_fn = async function() {
   return Promise.all(__privateGet(this, _keyrings).map(displayForKeyring));
 };
+_getSerializedKeyrings = new WeakSet();
+getSerializedKeyrings_fn = async function({ includeUnsupported } = {
+  includeUnsupported: true
+}) {
+  const serializedKeyrings = await Promise.all(
+    __privateGet(this, _keyrings).map(async (keyring) => {
+      const [type, data] = await Promise.all([
+        keyring.type,
+        keyring.serialize()
+      ]);
+      return { type, data };
+    })
+  );
+  if (includeUnsupported) {
+    serializedKeyrings.push(...__privateGet(this, _unsupportedKeyrings));
+  }
+  return serializedKeyrings;
+};
+_restoreSerializedKeyrings = new WeakSet();
+restoreSerializedKeyrings_fn = async function(serializedKeyrings) {
+  await __privateMethod(this, _clearKeyrings, clearKeyrings_fn).call(this);
+  for (const serializedKeyring of serializedKeyrings) {
+    await __privateMethod(this, _restoreKeyring, restoreKeyring_fn).call(this, serializedKeyring);
+  }
+};
 _unlockKeyrings = new WeakSet();
 unlockKeyrings_fn = async function(password, encryptionKey, encryptionSalt) {
   return __privateMethod(this, _withVaultLock, withVaultLock_fn).call(this, async ({ releaseLock }) => {
@@ -1101,7 +1182,6 @@ unlockKeyrings_fn = async function(password, encryptionKey, encryptionSalt) {
     if (!encryptedVault) {
       throw new Error("KeyringController - Cannot unlock without a previous vault." /* VaultError */);
     }
-    await __privateMethod(this, _clearKeyrings, clearKeyrings_fn).call(this, { skipStateUpdate: true });
     let vault;
     const updatedState = {};
     if (__privateGet(this, _cacheEncryptionKey)) {
@@ -1141,7 +1221,7 @@ unlockKeyrings_fn = async function(password, encryptionKey, encryptionSalt) {
     if (!isSerializedKeyringsArray(vault)) {
       throw new Error("KeyringController - The decrypted vault has an unexpected shape." /* VaultDataError */);
     }
-    await Promise.all(vault.map(__privateMethod(this, _restoreKeyring, restoreKeyring_fn).bind(this)));
+    await __privateMethod(this, _restoreSerializedKeyrings, restoreSerializedKeyrings_fn).call(this, vault);
     const updatedKeyrings = await __privateMethod(this, _getUpdatedKeyrings, getUpdatedKeyrings_fn).call(this);
     this.update((state) => {
       state.keyrings = updatedKeyrings;
@@ -1164,16 +1244,7 @@ updateVault_fn = function() {
     if (!__privateGet(this, _password) && !encryptionKey) {
       throw new Error("KeyringController - Cannot persist vault without password and encryption key" /* MissingCredentials */);
     }
-    const serializedKeyrings = await Promise.all(
-      __privateGet(this, _keyrings).map(async (keyring) => {
-        const [type, data] = await Promise.all([
-          keyring.type,
-          keyring.serialize()
-        ]);
-        return { type, data };
-      })
-    );
-    serializedKeyrings.push(...__privateGet(this, _unsupportedKeyrings));
+    const serializedKeyrings = await __privateMethod(this, _getSerializedKeyrings, getSerializedKeyrings_fn).call(this);
     if (!serializedKeyrings.some((keyring) => keyring.type === "HD Key Tree" /* hd */)) {
       throw new Error("KeyringController - No HD Keyring found" /* NoHdKeyring */);
     }
@@ -1233,14 +1304,16 @@ getAccountsFromKeyrings_fn = async function() {
 };
 _createKeyringWithFirstAccount = new WeakSet();
 createKeyringWithFirstAccount_fn = async function(type, opts) {
-  const keyring = await __privateMethod(this, _newKeyring, newKeyring_fn).call(this, type, opts, true);
+  __privateMethod(this, _assertControllerMutexIsLocked, assertControllerMutexIsLocked_fn).call(this);
+  const keyring = await __privateMethod(this, _newKeyring, newKeyring_fn).call(this, type, opts);
   const [firstAccount] = await keyring.getAccounts();
   if (!firstAccount) {
     throw new Error("KeyringController - First Account not found." /* NoFirstAccount */);
   }
 };
 _newKeyring = new WeakSet();
-newKeyring_fn = async function(type, data, persist = false) {
+newKeyring_fn = async function(type, data) {
+  __privateMethod(this, _assertControllerMutexIsLocked, assertControllerMutexIsLocked_fn).call(this);
   const keyringBuilder = __privateMethod(this, _getKeyringBuilderForType, getKeyringBuilderForType_fn).call(this, type);
   if (!keyringBuilder) {
     throw new Error(
@@ -1262,32 +1335,26 @@ newKeyring_fn = async function(type, data, persist = false) {
     await keyring.addAccounts(1);
   }
   await __privateMethod(this, _checkForDuplicate, checkForDuplicate_fn).call(this, type, await keyring.getAccounts());
-  if (persist) {
-    __privateGet(this, _keyrings).push(keyring);
-    await __privateMethod(this, _updateVault, updateVault_fn).call(this);
+  if (type === "QR Hardware Wallet Device" /* qr */) {
+    __privateMethod(this, _subscribeToQRKeyringEvents, subscribeToQRKeyringEvents_fn).call(this, keyring);
   }
+  __privateGet(this, _keyrings).push(keyring);
   return keyring;
 };
 _clearKeyrings = new WeakSet();
-clearKeyrings_fn = async function(options = { skipStateUpdate: false }) {
+clearKeyrings_fn = async function() {
+  __privateMethod(this, _assertControllerMutexIsLocked, assertControllerMutexIsLocked_fn).call(this);
   for (const keyring of __privateGet(this, _keyrings)) {
     await __privateMethod(this, _destroyKeyring, destroyKeyring_fn).call(this, keyring);
   }
   __privateSet(this, _keyrings, []);
-  if (!options.skipStateUpdate) {
-    this.update((state) => {
-      state.keyrings = [];
-    });
-  }
 };
 _restoreKeyring = new WeakSet();
 restoreKeyring_fn = async function(serialized) {
+  __privateMethod(this, _assertControllerMutexIsLocked, assertControllerMutexIsLocked_fn).call(this);
   try {
     const { type, data } = serialized;
-    const keyring = await __privateMethod(this, _newKeyring, newKeyring_fn).call(this, type, data);
-    await keyring.getAccounts();
-    __privateGet(this, _keyrings).push(keyring);
-    return keyring;
+    return await __privateMethod(this, _newKeyring, newKeyring_fn).call(this, type, data);
   } catch (_) {
     __privateGet(this, _unsupportedKeyrings).push(serialized);
     return void 0;
@@ -1299,6 +1366,7 @@ destroyKeyring_fn = async function(keyring) {
 };
 _removeEmptyKeyrings = new WeakSet();
 removeEmptyKeyrings_fn = async function() {
+  __privateMethod(this, _assertControllerMutexIsLocked, assertControllerMutexIsLocked_fn).call(this);
   const validKeyrings = [];
   await Promise.all(
     __privateGet(this, _keyrings).map(async (keyring) => {
@@ -1334,27 +1402,57 @@ checkForDuplicate_fn = async function(type, newAccountArray) {
 };
 _setUnlocked = new WeakSet();
 setUnlocked_fn = function() {
+  __privateMethod(this, _assertControllerMutexIsLocked, assertControllerMutexIsLocked_fn).call(this);
   this.update((state) => {
     state.isUnlocked = true;
   });
   this.messagingSystem.publish(`${name}:unlock`);
 };
-_getMemState = new WeakSet();
-getMemState_fn = function() {
-  return {
-    isUnlocked: this.state.isUnlocked,
-    keyrings: this.state.keyrings
-  };
+_persistOrRollback = new WeakSet();
+persistOrRollback_fn = async function(fn) {
+  return __privateMethod(this, _withRollback, withRollback_fn).call(this, async ({ releaseLock }) => {
+    const callbackResult = await fn({ releaseLock });
+    await __privateMethod(this, _updateVault, updateVault_fn).call(this);
+    return callbackResult;
+  });
+};
+_withRollback = new WeakSet();
+withRollback_fn = async function(fn) {
+  return __privateMethod(this, _withControllerLock, withControllerLock_fn).call(this, async ({ releaseLock }) => {
+    const currentSerializedKeyrings = await __privateMethod(this, _getSerializedKeyrings, getSerializedKeyrings_fn).call(this);
+    const currentPassword = __privateGet(this, _password);
+    try {
+      return await fn({ releaseLock });
+    } catch (e) {
+      await __privateMethod(this, _restoreSerializedKeyrings, restoreSerializedKeyrings_fn).call(this, currentSerializedKeyrings);
+      __privateSet(this, _password, currentPassword);
+      throw e;
+    }
+  });
+};
+_assertControllerMutexIsLocked = new WeakSet();
+assertControllerMutexIsLocked_fn = function() {
+  if (!__privateGet(this, _controllerOperationMutex).isLocked()) {
+    throw new Error("KeyringController - attempt to update vault during a non mutually exclusive operation" /* ControllerLockRequired */);
+  }
+};
+_withControllerLock = new WeakSet();
+withControllerLock_fn = async function(fn) {
+  return withLock(__privateGet(this, _controllerOperationMutex), fn);
 };
 _withVaultLock = new WeakSet();
 withVaultLock_fn = async function(fn) {
-  const releaseLock = await __privateGet(this, _vaultOperationMutex).acquire();
+  __privateMethod(this, _assertControllerMutexIsLocked, assertControllerMutexIsLocked_fn).call(this);
+  return withLock(__privateGet(this, _vaultOperationMutex), fn);
+};
+async function withLock(mutex, fn) {
+  const releaseLock = await mutex.acquire();
   try {
     return await fn({ releaseLock });
   } finally {
     releaseLock();
   }
-};
+}
 var KeyringController_default = KeyringController;
 
 export {
@@ -1367,4 +1465,4 @@ export {
   KeyringController,
   KeyringController_default
 };
-//# sourceMappingURL=chunk-5QTEIEPG.mjs.map
+//# sourceMappingURL=chunk-USAGXPFN.mjs.map