@metamask-previews/keyring-controller 28.2.0-preview-56cdd31f1 → 28.2.0-preview-4a8d4a2

package/dist/KeyringController.js

@@ -8,11 +8,11 @@ import { SimpleKeyring as SimpleKeyringV2 } from '@metamask/eth-simple-keyring/v
 import { add0x, assertIsStrictHexString, bytesToHex, hasProperty, hexToBytes, isObject, isStrictHexString, isValidHexAddress, isValidJson, remove0x, } from '@metamask/utils';
 import { Mutex } from 'async-mutex';
 import * as ethereumjsWallet from 'ethereumjs-wallet';
-import { cloneDeep } from 'lodash-es';
 // When generating a ULID within the same millisecond, monotonicFactory provides some guarantees regarding sort order.
 import { ulid } from 'ulid';
 import { KeyringControllerErrorMessage } from './constants.js';
 import { KeyringControllerError } from './errors.js';
+import { VaultTransaction } from './VaultTransaction.js';
 /**
  * `ethereumjs-wallet` is CommonJS, and Node cannot reliably detect its named
  * exports, so importing `thirdparty` directly fails at run time. It also
@@ -257,6 +257,14 @@ function normalize(address) {
     //       address value!
     return isEthAddress(address) ? ethNormalize(address) : address;
 }
+/**
+ * The standard wallet persist policy: the vault is written when the
+ * session state changed since the transaction began.
+ *
+ * @param hasChanged - Lazily checks whether the session state changed.
+ * @returns Whether the vault should be written.
+ */
+const persistWhenSessionChanged = (hasChanged) => hasChanged();
 /**
  * Controller responsible for establishing and managing user identity.
  *
@@ -347,7 +355,9 @@ export class KeyringController extends BaseController {
      */
     async addNewAccount(accountCount) {
         this.#assertIsUnlocked();
-        return this.#persistOrRollback(async () => {
+        // TODO: Migrate this to `#withKeyringOrRollback` so that only the
+        // operated keyring is snapshotted and diffed.
+        return this.#withTransaction(() => this.#beginWalletTransaction(persistWhenSessionChanged), async () => {
             const primaryKeyring = this.getKeyringsByType('HD Key Tree')[0];
             if (!primaryKeyring) {
                 throw new KeyringControllerError('No HD keyring found');
@@ -382,7 +392,9 @@ export class KeyringController extends BaseController {
         // and account using a "Snap Keyring". This function assume the `keyring` is
         // ethereum compatible, but "Snap Keyring" might not be.
         this.#assertIsUnlocked();
-        return this.#persistOrRollback(async () => {
+        // TODO: Migrate this to `#withKeyringOrRollback` so that only the
+        // operated keyring is snapshotted and diffed.
+        return this.#withTransaction(() => this.#beginWalletTransaction(persistWhenSessionChanged), async () => {
             const oldAccounts = await this.#getAccountsFromKeyrings();
             if (accountCount && oldAccounts.length !== accountCount) {
                 if (accountCount > oldAccounts.length) {
@@ -408,9 +420,9 @@ export class KeyringController extends BaseController {
      * @returns Promise resolving when the operation ends successfully.
      */
     async createNewVaultAndRestore(password, seed) {
-        return this.#persistOrRollback(async () => {
+        return this.#withTransaction(() => this.#beginWalletTransaction(persistWhenSessionChanged), async (transaction) => {
             assertIsValidPassword(password);
-            await this.#createNewVaultWithKeyring(password, {
+            await this.#createNewVaultWithKeyring(transaction, password, {
                 type: KeyringTypes.hd,
                 opts: {
                     mnemonic: seed,
@@ -429,10 +441,10 @@ export class KeyringController extends BaseController {
      * @returns Promise resolving when the operation ends successfully.
      */
     async createNewVaultAndKeychain(password) {
-        return this.#persistOrRollback(async () => {
+        return this.#withTransaction(() => this.#beginWalletTransaction(persistWhenSessionChanged), async (transaction) => {
             const accounts = await this.#getAccountsFromKeyrings();
             if (!accounts.length) {
-                await this.#createNewVaultWithKeyring(password, {
+                await this.#createNewVaultWithKeyring(transaction, password, {
                     type: KeyringTypes.hd,
                 });
             }
@@ -448,7 +460,9 @@ export class KeyringController extends BaseController {
      */
     async addNewKeyring(type, opts) {
         this.#assertIsUnlocked();
-        return this.#getKeyringMetadata(await this.#persistOrRollback(async () => this.#newKeyring(type, opts)));
+        // TODO: Migrate this to `#withKeyringOrRollback` so that only the
+        // operated keyring is snapshotted and diffed.
+        return this.#getKeyringMetadata(await this.#withTransaction(() => this.#beginWalletTransaction(persistWhenSessionChanged), async () => this.#newKeyring(type, opts)));
     }
     /**
      * Method to verify a given password validity. Throws an
@@ -649,9 +663,10 @@ export class KeyringController extends BaseController {
      * operation completes.
      */
     async persistAllKeyrings() {
-        return this.#withRollback(async () => {
+        return this.#withTransaction(
+        // The deprecated method's contract is an unconditional vault write.
+        () => this.#beginWalletTransaction(() => true), async () => {
             this.#assertIsUnlocked();
-            await this.#updateVault();
             return true;
         });
     }
@@ -668,7 +683,9 @@ export class KeyringController extends BaseController {
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     args) {
         this.#assertIsUnlocked();
-        return this.#persistOrRollback(async () => {
+        // TODO: Migrate this to `#withKeyringOrRollback` so that only the
+        // operated keyring is snapshotted and diffed.
+        return this.#withTransaction(() => this.#beginWalletTransaction(persistWhenSessionChanged), async () => {
             let privateKey;
             switch (strategy) {
                 case AccountImportStrategy.privateKey: {
@@ -724,12 +741,15 @@ export class KeyringController extends BaseController {
      */
     async removeAccount(address) {
         this.#assertIsUnlocked();
-        await this.#persistOrRollback(async () => {
+        // TODO: Migrate this to `#withKeyringOrRollback` so that only the
+        // operated keyring is snapshotted and diffed.
+        await this.#withTransaction(() => this.#beginWalletTransaction(persistWhenSessionChanged), async (transaction) => {
             const keyringIndex = await this.#findKeyringIndexForAccount(address);
             if (keyringIndex === -1) {
                 throw new KeyringControllerError(KeyringControllerErrorMessage.NoKeyring);
             }
-            const { keyring, keyringV2 } = this.#keyrings[keyringIndex];
+            const entry = this.#keyrings[keyringIndex];
+            const { keyring } = entry;
             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
@@ -749,8 +769,7 @@ export class KeyringController extends BaseController {
             // eslint-disable-next-line @typescript-eslint/await-thenable
             await keyring.removeAccount(address);
             if (shouldRemoveKeyring) {
-                this.#keyrings.splice(keyringIndex, 1);
-                await this.#destroyKeyring(keyring, keyringV2);
+                await transaction.remove(entry);
             }
         });
         this.messenger.publish(`${name}:accountRemoved`, address);
@@ -762,9 +781,12 @@ export class KeyringController extends BaseController {
      */
     async setLocked() {
         this.#assertIsUnlocked();
-        return this.#withRollback(async () => {
+        return this.#withTransaction(
+        // Locking clears the session without rewriting the vault, and the
+        // encryption key is gone by commit time anyway.
+        () => this.#beginWalletTransaction(() => false), async (transaction) => {
             this.#encryptionKey = undefined;
-            await this.#clearKeyrings();
+            await this.#clearKeyrings(transaction);
             this.update((state) => {
                 state.isUnlocked = false;
                 state.keyrings = [];
@@ -946,7 +968,7 @@ export class KeyringController extends BaseController {
      */
     changePassword(password) {
         this.#assertIsUnlocked();
-        return this.#persistOrRollback(async () => {
+        return this.#withTransaction(() => this.#beginWalletTransaction(persistWhenSessionChanged), async () => {
             assertIsValidPassword(password);
             await this.#deriveAndSetEncryptionKey(password, {
                 ignoreExistingVault: true,
@@ -963,8 +985,12 @@ export class KeyringController extends BaseController {
      * @returns Promise resolving when the operation completes.
      */
     async submitEncryptionKey(encryptionKey, encryptionSalt) {
-        const { hasChanged } = await this.#withRollback(async () => {
-            const result = await this.#unlockKeyrings({
+        const { hasChanged } = await this.#withTransaction(
+        // The unlock transaction is a rollback safety net: whether to
+        // upgrade the vault is the next transaction's decision, on the
+        // restoration's own change flag.
+        () => this.#beginWalletTransaction(() => false), async (transaction) => {
+            const result = await this.#unlockKeyrings(transaction, {
                 encryptionKey,
                 encryptionSalt,
             });
@@ -974,11 +1000,10 @@ export class KeyringController extends BaseController {
         try {
             // if new metadata has been generated during login, we
             // can attempt to upgrade the vault.
-            await this.#withRollback(async () => {
-                if (hasChanged) {
-                    await this.#updateVault();
-                }
-            });
+            await this.#withTransaction(
+            // The criterion is the restoration's change flag from the unlock
+            // above — not this transaction's own session diff.
+            () => this.#beginWalletTransaction(() => hasChanged), async () => undefined);
         }
         catch (error) {
             // We don't want to throw an error if the upgrade fails
@@ -1006,8 +1031,11 @@ export class KeyringController extends BaseController {
      * @returns Promise resolving when the operation completes.
      */
     async submitPassword(password) {
-        const { hasChanged } = await this.#withRollback(async () => {
-            const result = await this.#unlockKeyrings({ password });
+        const { hasChanged } = await this.#withTransaction(
+        // The unlock transaction is a rollback safety net: whether to
+        // upgrade the vault is the next transaction's decision.
+        () => this.#beginWalletTransaction(() => false), async (transaction) => {
+            const result = await this.#unlockKeyrings(transaction, { password });
             this.#setUnlocked();
             return result;
         });
@@ -1015,17 +1043,24 @@ export class KeyringController extends BaseController {
             // If there are stronger encryption params available, or
             // if the keyring state has changed during deserialization, we
             // can attempt to upgrade the vault.
-            await this.#withRollback(async () => {
+            await this.#withTransaction(
+            // The criterion combines the restoration's change flag from the
+            // unlock above — not this transaction's own session diff — with
+            // the available encryption params, and gates the re-derivation
+            // of the encryption key on it.
+            () => this.#beginWalletTransaction(async () => {
                 if (hasChanged || this.#isNewEncryptionAvailable()) {
+                    // If the vault is being upgraded, we want to ignore the
+                    // metadata that is already in the vault, so we can
+                    // effectively re-encrypt the vault with the new encryption
+                    // config.
                     await this.#deriveAndSetEncryptionKey(password, {
-                        // If the vault is being upgraded, we want to ignore the metadata
-                        // that is already in the vault, so we can effectively
-                        // re-encrypt the vault with the new encryption config.
                         ignoreExistingVault: true,
                     });
-                    await this.#updateVault();
+                    return true;
                 }
-            });
+                return false;
+            }), async () => undefined);
         }
         catch (error) {
             // We don't want to throw an error if the upgrade fails
@@ -1065,22 +1100,16 @@ export class KeyringController extends BaseController {
         createIfMissing: false,
     }) {
         this.#assertIsUnlocked();
-        return this.#persistOrRollback(async () => {
-            let entry = await this.#selectKeyringEntry({
-                v2: false,
-                selector,
-            });
-            if (!entry && 'type' in selector && options.createIfMissing) {
-                const newKeyring = (await this.#newKeyring(selector.type, options.createWithData));
-                entry = this.#keyrings.find(({ keyring }) => keyring === newKeyring);
-            }
-            if (!entry) {
-                throw new KeyringControllerError(KeyringControllerErrorMessage.KeyringNotFound);
+        return this.#withKeyringOrRollback({ v2: false }, () => this.#selectKeyringEntry({ v2: false, selector }), async () => {
+            if (!options.createIfMissing || !('type' in selector)) {
+                return;
             }
-            const { metadata } = entry;
-            const keyring = entry.keyring;
-            return this.#assertNoUnsafeDirectKeyringAccess(await this.#cleanUpEmptiedKeyringsAfter(async () => operation({ keyring, metadata })), keyring);
-        });
+            const newKeyring = (await this.#newKeyring(selector.type, options.createWithData));
+            return this.#keyrings.find(({ keyring }) => keyring === newKeyring);
+        }, async ({ keyring, metadata }) => this.#assertNoUnsafeDirectKeyringAccess(await operation({
+            keyring: keyring,
+            metadata,
+        }), keyring));
     }
     /**
      * Select a keyring and execute the given operation with the selected
@@ -1144,6 +1173,9 @@ export class KeyringController extends BaseController {
      * function execution, or rolls back the changes if an error
      * is thrown.
      *
+     * Only the selected keyring is snapshotted, persisted, and rolled back:
+     * the operation must not mutate other keyrings.
+     *
      * @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.
@@ -1151,24 +1183,10 @@ export class KeyringController extends BaseController {
      */
     async withKeyringV2(selector, operation) {
         this.#assertIsUnlocked();
-        return this.#persistOrRollback(async () => {
-            const entry = await this.#selectKeyringEntry({
-                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 this.#assertNoUnsafeDirectKeyringAccess(await this.#cleanUpEmptiedKeyringsAfter(async () => operation({
-                keyring,
-                metadata,
-            })), keyring);
-        });
+        return this.#withKeyringOrRollback({ v2: true }, () => this.#selectKeyringEntry({ v2: true, selector }), async () => undefined, async ({ keyringV2, metadata }) => this.#assertNoUnsafeDirectKeyringAccess(await operation({
+            keyring: keyringV2,
+            metadata,
+        }), keyringV2));
     }
     /**
      * Select a keyring, wrap it in a `KeyringV2` adapter, and execute
@@ -1237,7 +1255,7 @@ export class KeyringController extends BaseController {
      */
     async withController(operation) {
         this.#assertIsUnlocked();
-        return this.#persistOrRollback(async () => {
+        return this.#withTransaction(() => this.#beginWalletTransaction(persistWhenSessionChanged), async (transaction) => {
             // Track created and removed keyrings during the operation execution.
             const createdEntries = new Set();
             const removedEntries = new Set();
@@ -1273,7 +1291,7 @@ export class KeyringController extends BaseController {
                 },
             };
             const destroyKeyrings = async (entries) => {
-                await Promise.all([...entries].map(({ keyring, keyringV2 }) => this.#destroyKeyring(keyring, keyringV2)));
+                await Promise.all([...entries].map((entry) => transaction.destroy(entry)));
             };
             let result;
             try {
@@ -1423,13 +1441,14 @@ export class KeyringController extends BaseController {
      * creates a new wallet with 1 account.
      *
      * @fires KeyringController:unlock
+     * @param transaction - The transaction creating the new vault.
      * @param password - The password to encrypt the vault with.
      * @param keyring - A object containing the params to instantiate a new keyring.
      * @param keyring.type - The keyring type.
      * @param keyring.opts - Optional parameters required to instantiate the keyring.
      * @returns A promise that resolves to the state.
      */
-    async #createNewVaultWithKeyring(password, keyring) {
+    async #createNewVaultWithKeyring(transaction, password, keyring) {
         this.#assertControllerMutexIsLocked();
         if (typeof password !== 'string') {
             throw new TypeError(KeyringControllerErrorMessage.WrongPasswordType);
@@ -1441,7 +1460,7 @@ export class KeyringController extends BaseController {
         await this.#deriveAndSetEncryptionKey(password, {
             ignoreExistingVault: true,
         });
-        await this.#clearKeyrings();
+        await this.#clearKeyrings(transaction);
         await this.#createKeyringWithFirstAccount(keyring.type, keyring.opts);
         this.#setUnlocked();
     }
@@ -1568,15 +1587,11 @@ export class KeyringController extends BaseController {
     }
     /**
      * Serialize the current array of keyring instances,
-     * including unsupported keyrings by default.
+     * including unsupported keyrings.
      *
-     * @param options - Method options.
-     * @param options.includeUnsupported - Whether to include unsupported keyrings.
      * @returns The serialized keyrings.
      */
-    async #getSerializedKeyrings({ includeUnsupported } = {
-        includeUnsupported: true,
-    }) {
+    async #getSerializedKeyrings() {
         const serializedKeyrings = await Promise.all(this.#keyrings.map(async ({ keyring, metadata }) => {
             return {
                 type: keyring.type,
@@ -1584,31 +1599,18 @@ export class KeyringController extends BaseController {
                 metadata,
             };
         }));
-        if (includeUnsupported) {
-            serializedKeyrings.push(...this.#unsupportedKeyrings);
-        }
+        serializedKeyrings.push(...this.#unsupportedKeyrings);
         return serializedKeyrings;
     }
-    /**
-     * Get a snapshot of session data held by instance variables.
-     *
-     * @returns An object with serialized keyrings, keyrings metadata,
-     * and the user password.
-     */
-    async #getSessionState() {
-        return {
-            keyrings: await this.#getSerializedKeyrings(),
-            encryptionKey: this.#encryptionKey,
-        };
-    }
     /**
      * Restore a serialized keyrings array.
      *
+     * @param transaction - The transaction restoring the keyrings.
      * @param serializedKeyrings - The serialized keyrings array.
      * @returns The restored keyrings.
      */
-    async #restoreSerializedKeyrings(serializedKeyrings) {
-        await this.#clearKeyrings();
+    async #restoreSerializedKeyrings(transaction, serializedKeyrings) {
+        await this.#clearKeyrings(transaction);
         const keyrings = [];
         let hasChanged = false;
         for (const serializedKeyring of serializedKeyrings) {
@@ -1627,10 +1629,11 @@ export class KeyringController extends BaseController {
      * Unlock Keyrings, decrypting the vault and deserializing all
      * keyrings contained in it, using a password or an encryption key with salt.
      *
+     * @param transaction - The transaction unlocking the keyrings.
      * @param credentials - The credentials to unlock the keyrings.
      * @returns A promise resolving to the deserialized keyrings array.
      */
-    async #unlockKeyrings(credentials) {
+    async #unlockKeyrings(transaction, credentials) {
         return this.#withVaultLock(async () => {
             if (!this.state.vault) {
                 throw new KeyringControllerError(KeyringControllerErrorMessage.VaultError);
@@ -1651,7 +1654,7 @@ export class KeyringController extends BaseController {
             if (!isSerializedKeyringsArray(vault)) {
                 throw new KeyringControllerError(KeyringControllerErrorMessage.VaultDataError);
             }
-            const { keyrings, hasChanged } = await this.#restoreSerializedKeyrings(vault);
+            const { keyrings, hasChanged } = await this.#restoreSerializedKeyrings(transaction, vault);
             const updatedKeyrings = await this.#getUpdatedKeyrings();
             this.update((state) => {
                 state.keyrings = updatedKeyrings;
@@ -1718,14 +1721,10 @@ export class KeyringController extends BaseController {
      * @returns A promise resolving to an array of accounts.
      */
     async #getAccountsFromKeyrings(additionalKeyrings = []) {
-        const keyrings = this.#keyrings.map(({ keyring }) => keyring);
-        const keyringArrays = await Promise.all([...keyrings, ...additionalKeyrings].map(async (keyring) => keyring.getAccounts()));
-        const addresses = keyringArrays.reduce((res, arr) => {
-            return res.concat(arr);
-        }, []);
-        // Cast to `string[]` here is safe here because `addresses` has no nullish
-        // values, and `normalize` returns `string` unless given a nullish value
-        return addresses.map(normalize);
+        return getAccountsFromKeyrings([
+            ...this.#keyrings.map(({ keyring }) => keyring),
+            ...additionalKeyrings,
+        ]);
     }
     /**
      * Create a new keyring, ensuring that the first account is
@@ -1814,60 +1813,16 @@ export class KeyringController extends BaseController {
         }
         return { keyring, keyringV2, metadata: keyringMetadata };
     }
-    /**
-     * Run the given operation and afterwards clean up any keyring whose
-     * account list transitioned from non-empty to empty during the operation.
-     *
-     * This mirrors the cleanup behavior of {@link KeyringController.removeAccount}
-     * for code paths where the consumer mutates a keyring directly via
-     * {@link KeyringController.withKeyring} or
-     * {@link KeyringController.withKeyringV2}: if the consumer drains the last
-     * account from a keyring, the now-empty keyring is removed from
-     * {@link KeyringController.#keyrings} and destroyed before persistence runs.
-     *
-     * Pre-existing empty keyrings (e.g. those created intentionally via
-     * {@link KeyringController.addNewKeyring} without subsequent account
-     * creation) are left alone, as are keyrings created within the operation
-     * itself (they are not part of the pre-operation snapshot). The primary
-     * keyring (see {@link KeyringController.#isPrimaryKeyring}) is also preserved
-     * unconditionally to keep `removeAccount`'s primary-keyring invariant intact.
-     *
-     * @param operation - The operation to execute.
-     * @returns The result of the operation.
-     * @template Result - The type of the value resolved by the operation.
-     */
-    async #cleanUpEmptiedKeyringsAfter(operation) {
-        // Only the primary keyring exists, which is never auto-removed, so there
-        // is nothing to clean up regardless of what the operation does.
-        if (this.#keyrings.length <= 1) {
-            return operation();
-        }
-        const wasNonEmpty = new WeakSet();
-        await Promise.all(this.#keyrings.map(async ({ keyring }) => {
-            if ((await keyring.getAccounts()).length > 0) {
-                wasNonEmpty.add(keyring);
-            }
-        }));
-        const result = await operation();
-        const isNowEmpty = await Promise.all(this.#keyrings.map(async ({ keyring }) => (await keyring.getAccounts()).length === 0));
-        const emptied = this.#keyrings.filter((entry, index) => !this.#isPrimaryKeyring(entry, this.#keyrings) &&
-            wasNonEmpty.has(entry.keyring) &&
-            isNowEmpty[index]);
-        if (emptied.length > 0) {
-            const removed = new Set(emptied);
-            this.#keyrings = this.#keyrings.filter((entry) => !removed.has(entry));
-            await Promise.all(emptied.map(({ keyring, keyringV2 }) => this.#destroyKeyring(keyring, keyringV2)));
-        }
-        return result;
-    }
     /**
      * Remove all managed keyrings, destroying all their
      * instances in memory.
+     *
+     * @param transaction - The transaction clearing the keyrings.
      */
-    async #clearKeyrings() {
+    async #clearKeyrings(transaction) {
         this.#assertControllerMutexIsLocked();
-        for (const { keyring, keyringV2 } of this.#keyrings) {
-            await this.#destroyKeyring(keyring, keyringV2);
+        for (const entry of this.#keyrings) {
+            await transaction.destroy(entry);
         }
         this.#keyrings = [];
         this.#unsupportedKeyrings = [];
@@ -1912,22 +1867,6 @@ export class KeyringController extends BaseController {
             return undefined;
         }
     }
-    /**
-     * Destroy Keyring
-     *
-     * Some keyrings support a method called `destroy`, that destroys the
-     * keyring along with removing all its event listeners and, in some cases,
-     * clears the keyring bridge iframe from the DOM.
-     *
-     * @param keyring - The keyring to destroy.
-     * @param keyringV2 - The keyring v2 to destroy (if any).
-     */
-    async #destroyKeyring(keyring, keyringV2) {
-        await keyring.destroy?.();
-        if (keyringV2) {
-            await keyringV2.destroy?.();
-        }
-    }
     /**
      * Assert that there are no duplicate accounts in the keyrings.
      *
@@ -1935,10 +1874,10 @@ export class KeyringController extends BaseController {
      * @throws If there are duplicate accounts.
      */
     async #assertNoDuplicateAccounts(additionalKeyrings = []) {
-        const accounts = await this.#getAccountsFromKeyrings(additionalKeyrings);
-        if (new Set(accounts).size !== accounts.length) {
-            throw new KeyringControllerError(KeyringControllerErrorMessage.DuplicatedAccount);
-        }
+        await assertNoDuplicateAccounts([
+            ...this.#keyrings.map(({ keyring }) => keyring),
+            ...additionalKeyrings,
+        ]);
     }
     /**
      * Set the `isUnlocked` to true and notify listeners
@@ -1964,47 +1903,174 @@ export class KeyringController extends BaseController {
         }
     }
     /**
-     * Execute the given function after acquiring the controller lock
-     * and save the vault to state after it (only if needed), or rollback to their
-     * previous state in case of error.
+     * Execute a transaction that operates on a single keyring entry, selected
+     * (and possibly created) before the transaction starts. Only that keyring
+     * is snapshotted, diffed, persisted, and rolled back; the other keyrings
+     * keep their instances even if the transaction fails. This relies on the
+     * `withKeyring` family only mutating the keyring it is given.
      *
-     * @param callback - The function to execute.
-     * @returns The result of the function.
+     * If the operation drains the operated keyring of all its accounts, the
+     * keyring is removed and destroyed (mirroring `removeAccount`), unless it
+     * is the primary keyring. A setup failure — selection, creation, or
+     * validation — never triggers a rollback; see
+     * `#beginKeyringTransaction`.
+     *
+     * @param options - Transaction options.
+     * @param options.v2 - Whether the transaction operates on the keyring's
+     *   V2 adapter. The selected or created entry must then have one.
+     * @param select - Selects the keyring entry to operate on, if any.
+     * @param create - Creates the keyring entry to operate on when selection
+     *   found nothing, if needed.
+     * @param run - Runs the operation with the selected or created entry.
+     * @returns The result of the operation.
      */
-    async #persistOrRollback(callback) {
-        return this.#withRollback(async ({ releaseLock }) => {
-            const oldState = JSON.stringify(await this.#getSessionState());
-            const callbackResult = await callback({ releaseLock });
-            const newState = JSON.stringify(await this.#getSessionState());
-            // State is committed only if the operation is successful and need to trigger a vault update.
-            if (oldState !== newState) {
-                await this.#updateVault();
+    async #withKeyringOrRollback({ v2 }, select, create, run) {
+        return this.#withTransaction(() => this.#beginKeyringTransaction({ v2 }, select, create), async (transaction, entry) => {
+            // The drain cleanup below can only fire when the wallet holds
+            // other keyrings: the bracketing account reads are skipped
+            // entirely otherwise, so single-keyring wallets make no extra
+            // `getAccounts` calls. For a created keyring, the wallet holds it
+            // already, so even a `getAccounts` rejection before the operation
+            // runs must still be rolled back.
+            const canDrain = this.#keyrings.length > 1;
+            const wasNonEmpty = canDrain && (await entry.keyring.getAccounts()).length > 0;
+            const result = await run(entry);
+            const isEmpty = canDrain && (await entry.keyring.getAccounts()).length === 0;
+            // Only the operated keyring can have transitioned to empty.
+            if (wasNonEmpty &&
+                isEmpty &&
+                !this.#isPrimaryKeyring(entry, this.#keyrings)) {
+                await transaction.remove(entry);
             }
-            return callbackResult;
+            // The vault is updated by the commit, only if the operated keyring
+            // changed.
+            return result;
         });
     }
     /**
-     * Execute the given function after acquiring the controller lock
-     * and rollback keyrings and password states in case of error.
+     * Begin a keyring-scoped transaction: select, or create, the entry to
+     * operate on, validate it, and snapshot the operated keyring.
      *
-     * @param callback - The function to execute atomically.
-     * @returns The result of the function.
+     * Everything here runs before the transaction starts, so a failure
+     * leaves the controller untouched and never triggers a rollback: the
+     * rollback of an entry without a snapshot would misread it as created
+     * by the transaction, destroying a pre-existing keyring. The V2
+     * validation happens before any of the keyring's accounts are read, so
+     * that the missing adapter takes precedence over keyring-level errors.
+     *
+     * @param options - Transaction options.
+     * @param options.v2 - Whether the transaction operates on the keyring's
+     *   V2 adapter.
+     * @param select - Selects the keyring entry to operate on, if any.
+     * @param create - Creates the keyring entry to operate on when selection
+     *   found nothing, if needed.
+     * @returns The transaction, and the operated entry.
+     */
+    async #beginKeyringTransaction({ v2 }, select, create) {
+        const selected = await select();
+        const entry = selected ?? (await create());
+        if (!entry) {
+            throw new KeyringControllerError(KeyringControllerErrorMessage.KeyringNotFound);
+        }
+        if (v2 && !entry.keyringV2) {
+            throw new KeyringControllerError(KeyringControllerErrorMessage.KeyringV2NotSupported);
+        }
+        const transaction = new VaultTransaction({ type: 'keyring', entry, created: !selected }, this.#vaultSession(), this.#vaultOperations());
+        await transaction.begin();
+        return { transaction, setup: entry };
+    }
+    /**
+     * The vault session state, as the transactions see it: what they
+     * snapshot at `begin()`, mutate through, and restore on `rollback()`.
+     *
+     * @returns The vault session.
      */
-    async #withRollback(callback) {
-        return this.#withControllerLock(async ({ releaseLock }) => {
-            const currentSerializedKeyrings = await this.#getSerializedKeyrings();
-            const currentEncryptionKey = cloneDeep(this.#encryptionKey);
+    #vaultSession() {
+        return {
+            getKeyrings: () => [...this.#keyrings],
+            replaceKeyrings: (keyrings) => {
+                this.#keyrings = keyrings;
+            },
+            removeKeyring: (entry) => {
+                const index = this.#keyrings.indexOf(entry);
+                if (index !== -1) {
+                    this.#keyrings.splice(index, 1);
+                    return true;
+                }
+                return false;
+            },
+            insertKeyringAt: (index, entry) => {
+                this.#keyrings.splice(index, 0, entry);
+            },
+            getUnsupportedKeyrings: () => [...this.#unsupportedKeyrings],
+            setUnsupportedKeyrings: (keyrings) => {
+                this.#unsupportedKeyrings = keyrings;
+            },
+            parkUnsupportedKeyring: (keyring) => {
+                this.#unsupportedKeyrings.push(keyring);
+            },
+            getEncryptionKey: () => this.#encryptionKey,
+            setEncryptionKey: (key) => {
+                this.#encryptionKey = key;
+            },
+        };
+    }
+    /**
+     * The controller-owned primitives the transactions drive: building new
+     * keyring entries, and enforcing the no-duplicate-accounts invariant on
+     * an explicit list of keyrings.
+     *
+     * @returns The vault operations.
+     */
+    #vaultOperations() {
+        return {
+            createKeyring: async (type, data, metadata) => this.#createKeyring(type, data, metadata),
+            assertNoDuplicateAccounts: async (keyrings) => assertNoDuplicateAccounts(keyrings),
+            updateVault: async () => this.#updateVault(),
+        };
+    }
+    /**
+     * Execute the given function inside a vault transaction, after
+     * acquiring the controller lock. The transaction is constructed and
+     * begun before the function runs — a failure there leaves the
+     * controller untouched — and committed after the function succeeds, or
+     * rolled back if it throws.
+     *
+     * @param construct - Constructs and begins the transaction, plus
+     *   whatever the operation needs from the construction.
+     * @param run - Runs the operation, with the transaction and what its
+     *   construction produced.
+     * @returns The result of the operation.
+     */
+    async #withTransaction(construct, run) {
+        return this.#withControllerLock(async () => {
+            const { transaction, setup } = await construct();
             try {
-                return await callback({ releaseLock });
+                const result = await run(transaction, setup);
+                await transaction.commit();
+                return result;
             }
             catch (error) {
-                // Keyrings and encryption credentials are restored to their previous state
-                this.#encryptionKey = currentEncryptionKey;
-                await this.#restoreSerializedKeyrings(currentSerializedKeyrings);
+                // What the transaction owns is restored to its previous state.
+                await transaction.rollback();
                 throw error;
             }
         });
     }
+    /**
+     * Begin a wallet-scoped transaction, snapshotting the whole session.
+     *
+     * @param persist - Decides, when the transaction commits, whether the
+     *   vault is written.
+     * @returns The transaction, and nothing else for the operation.
+     */
+    async #beginWalletTransaction(persist) {
+        const transaction = new VaultTransaction({ type: 'wallet', persist }, this.#vaultSession(), this.#vaultOperations());
+        // The snapshot is taken before the transaction starts: a failure
+        // here leaves the controller untouched.
+        await transaction.begin();
+        return { transaction, setup: undefined };
+    }
     /**
      * Assert that the controller mutex is locked.
      *
@@ -2100,5 +2166,32 @@ async function withLock(mutex, callback) {
 function getDefaultKeyringMetadata() {
     return { id: ulid(), name: '' };
 }
+/**
+ * Retrieves all the accounts held by the given keyrings.
+ *
+ * @param keyrings - The keyrings to read the accounts from.
+ * @returns A promise resolving to an array of accounts.
+ */
+async function getAccountsFromKeyrings(keyrings) {
+    const keyringArrays = await Promise.all(keyrings.map(async (keyring) => keyring.getAccounts()));
+    const addresses = keyringArrays.reduce((res, arr) => {
+        return res.concat(arr);
+    }, []);
+    // Cast to `string[]` here is safe here because `addresses` has no nullish
+    // values, and `normalize` returns `string` unless given a nullish value
+    return addresses.map(normalize);
+}
+/**
+ * Assert that there are no duplicate accounts across the given keyrings.
+ *
+ * @param keyrings - The keyrings to check.
+ * @throws If there are duplicate accounts.
+ */
+async function assertNoDuplicateAccounts(keyrings) {
+    const accounts = await getAccountsFromKeyrings(keyrings);
+    if (new Set(accounts).size !== accounts.length) {
+        throw new KeyringControllerError(KeyringControllerErrorMessage.DuplicatedAccount);
+    }
+}
 export default KeyringController;
 //# sourceMappingURL=KeyringController.js.map