@metamask-previews/keyring-controller 25.1.1-preview-ce9be8b82 → 25.2.0-preview-373edc9

package/CHANGELOG.md

@@ -7,10 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [25.2.0]
+
 ### Added
 
 - Added `filter` selector variant to `withKeyring` ([#8348](https://github.com/MetaMask/core/pull/8348))
   - `KeyringSelector` now accepts `{ filter: ({ keyring, metadata }) => boolean }`, which selects the first keyring for which the predicate returns `true`.
+- Add `isKeyringNotFoundError` ([#8351](https://github.com/MetaMask/core/pull/8351))
+  - This function can be used when trying to access a non-existing keyring using `withKeyring`.
+- Added `withKeyringUnsafe` action ([#8358](https://github.com/MetaMask/core/pull/8358))
+  - This new variant of `withKeyring` allows to fetch a keyring instance the same way.
+  - Mutations are not allowed and won't be replicated in the vault.
+  - Can be used to read immutable data safely.
+- Add `KeyringTypes.money` enum value ([#8360](https://github.com/MetaMask/core/pull/8360))
 
 ## [25.1.1]
 
@@ -943,7 +952,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
     All changes listed after this point were applied to this package following the monorepo conversion.
 
-[Unreleased]: https://github.com/MetaMask/core/compare/@metamask/keyring-controller@25.1.1...HEAD
+[Unreleased]: https://github.com/MetaMask/core/compare/@metamask/keyring-controller@25.2.0...HEAD
+[25.2.0]: https://github.com/MetaMask/core/compare/@metamask/keyring-controller@25.1.1...@metamask/keyring-controller@25.2.0
 [25.1.1]: https://github.com/MetaMask/core/compare/@metamask/keyring-controller@25.1.0...@metamask/keyring-controller@25.1.1
 [25.1.0]: https://github.com/MetaMask/core/compare/@metamask/keyring-controller@25.0.0...@metamask/keyring-controller@25.1.0
 [25.0.0]: https://github.com/MetaMask/core/compare/@metamask/keyring-controller@24.0.0...@metamask/keyring-controller@25.0.0

package/dist/KeyringController.cjs

@@ -36,7 +36,7 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
-var _KeyringController_instances, _KeyringController_controllerOperationMutex, _KeyringController_vaultOperationMutex, _KeyringController_keyringBuilders, _KeyringController_encryptor, _KeyringController_keyrings, _KeyringController_unsupportedKeyrings, _KeyringController_encryptionKey, _KeyringController_findKeyringIndexForAccount, _KeyringController_registerMessageHandlers, _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_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;
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.KeyringController = exports.getDefaultKeyringState = exports.keyringBuilderFactory = exports.SignTypedDataVersion = exports.AccountImportStrategy = exports.isCustodyKeyring = exports.KeyringTypes = void 0;
 const util_1 = require("@ethereumjs/util");
@@ -69,6 +69,7 @@ var KeyringTypes;
     KeyringTypes["ledger"] = "Ledger Hardware";
     KeyringTypes["lattice"] = "Lattice Hardware";
     KeyringTypes["snap"] = "Snap Keyring";
+    KeyringTypes["money"] = "Money Keyring";
     /* eslint-enable @typescript-eslint/naming-convention */
 })(KeyringTypes || (exports.KeyringTypes = KeyringTypes = {}));
 /**
@@ -526,19 +527,14 @@ class KeyringController extends base_controller_1.BaseController {
      */
     async getKeyringForAccount(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;
+        const keyring = await __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_getKeyringForAccount).call(this, account);
+        if (keyring) {
+            return keyring;
         }
-        // Adding more info to the error
-        let errorInfo = '';
         if (__classPrivateFieldGet(this, _KeyringController_keyrings, "f").length === 0) {
-            errorInfo = 'There are no keyrings';
+            throw new errors_1.KeyringControllerError(constants_1.KeyringControllerErrorMessage.NoKeyring);
         }
-        else {
-            errorInfo = 'There are keyrings, but none match the address';
-        }
-        throw new errors_1.KeyringControllerError(`${constants_1.KeyringControllerErrorMessage.NoKeyring}. Error info: ${errorInfo}`);
+        throw new errors_1.KeyringControllerError(constants_1.KeyringControllerErrorMessage.KeyringNotFound);
     }
     /**
      * Returns all keyrings of the given type.
@@ -961,39 +957,66 @@ class KeyringController extends base_controller_1.BaseController {
     }) {
         __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_assertIsUnlocked).call(this);
         return __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_persistOrRollback).call(this, async () => {
-            let keyring;
-            if ('address' in selector) {
-                keyring = (await this.getKeyringForAccount(selector.address));
-            }
-            else if ('type' in selector) {
-                keyring = this.getKeyringsByType(selector.type)[selector.index ?? 0];
-                if (!keyring && options.createIfMissing) {
-                    keyring = (await __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_newKeyring).call(this, selector.type, options.createWithData));
-                }
-            }
-            else if ('id' in selector) {
-                keyring = __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_getKeyringById).call(this, selector.id);
-            }
-            else if ('filter' in selector) {
-                keyring = __classPrivateFieldGet(this, _KeyringController_keyrings, "f").find(({ keyring: filteredKeyring, metadata }) => selector.filter(filteredKeyring, metadata))?.keyring;
+            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));
             }
             if (!keyring) {
                 throw new errors_1.KeyringControllerError(constants_1.KeyringControllerErrorMessage.KeyringNotFound);
             }
-            const result = await operation({
+            return __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_assertNoUnsafeDirectKeyringAccess).call(this, await operation({
                 keyring,
                 metadata: __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_getKeyringMetadata).call(this, keyring),
-            });
-            if (Object.is(result, keyring)) {
-                // Access to a keyring instance outside of controller safeguards
-                // should be discouraged, as it can lead to unexpected behavior.
-                // This error is thrown to prevent consumers using `withKeyring`
-                // as a way to get a reference to a keyring instance.
-                throw new errors_1.KeyringControllerError(constants_1.KeyringControllerErrorMessage.UnsafeDirectKeyringAccess);
-            }
-            return result;
+            }), keyring);
         });
     }
+    /**
+     * Select a keyring and execute the given operation with the selected
+     * keyring, **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 the `mnemonic` from an `HdKeyring`: the mnemonic is set during
+     * `deserialize()` and never mutated afterwards, so it can safely be read
+     * without holding the lock.
+     *
+     * ## 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 `withKeyring`.
+     * - Read mutable fields that could change during concurrent operations.
+     *
+     * @param selector - Keyring selector object.
+     * @param operation - Read-only function to execute with the selected keyring.
+     * @returns Promise resolving to the result of the function execution.
+     * @template SelectedKeyring - The type of the selected keyring.
+     * @template CallbackResult - The type of the value resolved by the callback function.
+     */
+    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) {
+            throw new errors_1.KeyringControllerError(constants_1.KeyringControllerErrorMessage.KeyringNotFound);
+        }
+        // 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);
+    }
     async getAccountKeyringType(account) {
         __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_assertIsUnlocked).call(this);
         const keyring = (await this.getKeyringForAccount(account));
@@ -1001,11 +1024,27 @@ class KeyringController extends base_controller_1.BaseController {
     }
 }
 exports.KeyringController = KeyringController;
-_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_findKeyringIndexForAccount = async function _KeyringController_findKeyringIndexForAccount(account) {
+_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) {
+    __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 undefined;
+}, _KeyringController_findKeyringIndexForAccount = async function _KeyringController_findKeyringIndexForAccount(account) {
     __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_assertIsUnlocked).call(this);
     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_assertNoUnsafeDirectKeyringAccess = function _KeyringController_assertNoUnsafeDirectKeyringAccess(value, keyring) {
+    if (Object.is(value, keyring)) {
+        // Access to a keyring instance outside of controller safeguards
+        // should be discouraged, as it can lead to unexpected behavior.
+        // This error is thrown to prevent consumers using `withKeyring`
+        // as a way to get a reference to a keyring instance.
+        throw new errors_1.KeyringControllerError(constants_1.KeyringControllerErrorMessage.UnsafeDirectKeyringAccess);
+    }
+    return value;
 }, _KeyringController_registerMessageHandlers = function _KeyringController_registerMessageHandlers() {
     this.messenger.registerActionHandler(`${name}:signMessage`, this.signMessage.bind(this));
     this.messenger.registerActionHandler(`${name}:signEip7702Authorization`, this.signEip7702Authorization.bind(this));
@@ -1022,10 +1061,34 @@ _KeyringController_controllerOperationMutex = new WeakMap(), _KeyringController_
     this.messenger.registerActionHandler(`${name}:signUserOperation`, this.signUserOperation.bind(this));
     this.messenger.registerActionHandler(`${name}:addNewAccount`, this.addNewAccount.bind(this));
     this.messenger.registerActionHandler(`${name}:withKeyring`, this.withKeyring.bind(this));
+    this.messenger.registerActionHandler(`${name}:withKeyringUnsafe`, this.withKeyringUnsafe.bind(this));
     this.messenger.registerActionHandler(`${name}:addNewKeyring`, this.addNewKeyring.bind(this));
     this.messenger.registerActionHandler(`${name}:createNewVaultAndKeychain`, this.createNewVaultAndKeychain.bind(this));
     this.messenger.registerActionHandler(`${name}:createNewVaultAndRestore`, this.createNewVaultAndRestore.bind(this));
     this.messenger.registerActionHandler(`${name}:removeAccount`, this.removeAccount.bind(this));
+}, _KeyringController_selectKeyring = 
+/**
+ * Select a keyring using a selector without acquiring the controller lock.
+ *
+ * @param selector - Keyring selector object.
+ * @returns The selected keyring, or `undefined` if no match is found.
+ * @template SelectedKeyring - The expected type of the selected keyring.
+ */
+async function _KeyringController_selectKeyring(selector) {
+    let keyring;
+    if ('address' in selector) {
+        keyring = (await __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_getKeyringForAccount).call(this, selector.address));
+    }
+    else if ('type' in selector) {
+        keyring = this.getKeyringsByType(selector.type)[selector.index ?? 0];
+    }
+    else if ('id' in selector) {
+        keyring = __classPrivateFieldGet(this, _KeyringController_instances, "m", _KeyringController_getKeyringById).call(this, selector.id);
+    }
+    else if ('filter' in selector) {
+        keyring = __classPrivateFieldGet(this, _KeyringController_keyrings, "f").find(({ keyring: filteredKeyring, metadata }) => selector.filter(filteredKeyring, metadata))?.keyring;
+    }
+    return keyring;
 }, _KeyringController_getKeyringById = function _KeyringController_getKeyringById(keyringId) {
     return __classPrivateFieldGet(this, _KeyringController_keyrings, "f").find(({ metadata }) => metadata.id === keyringId)
         ?.keyring;