@metamask/keyring-sdk 4.0.0 → 4.2.0

package/CHANGELOG.md

@@ -7,6 +7,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [4.2.0]
+
+### Added
+
+- Add `AtomicKeyring` support ([#640](https://github.com/MetaMask/accounts/pull/640))
+  - Atomic keyrings run long-running operations inside their own read-write lock, entirely outside the controller mutex (only the `update` method will be guarded by the `KeyringController`'s vault mutex).
+  - Add `AtomicUpdater` type, callback forwarded by the `KeyringController` during register phase.
+  - Add `isAtomicKeyring` helper to identify atomic keyrings.
+- Add `ReadWriteLock` primitive with parallel readers, exclusive writers ([#640](https://github.com/MetaMask/accounts/pull/640))
+  - Also support priority mode: `'read'` or `'write'`.
+
+## [4.1.0]
+
+### Added
+
+- Add `isKeyringV1Adapter` type guard ([#685](https://github.com/MetaMask/accounts/pull/685))
+  - Use this instead of doing type checks with `instanceof`.
+
+### Changed
+
+- Bump `@metamask/keyring-api` from `^24.2.0` to `^24.3.0` ([#674](https://github.com/MetaMask/accounts/pull/674))
+
 ## [4.0.0]
 
 ### Changed
@@ -130,7 +152,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Initial release, extracted from `@metamask/keyring-api` ([#478](https://github.com/MetaMask/accounts/pull/478), [#482](https://github.com/MetaMask/accounts/pull/482))
 
-[Unreleased]: https://github.com/MetaMask/accounts/compare/@metamask/keyring-sdk@4.0.0...HEAD
+[Unreleased]: https://github.com/MetaMask/accounts/compare/@metamask/keyring-sdk@4.2.0...HEAD
+[4.2.0]: https://github.com/MetaMask/accounts/compare/@metamask/keyring-sdk@4.1.0...@metamask/keyring-sdk@4.2.0
+[4.1.0]: https://github.com/MetaMask/accounts/compare/@metamask/keyring-sdk@4.0.0...@metamask/keyring-sdk@4.1.0
 [4.0.0]: https://github.com/MetaMask/accounts/compare/@metamask/keyring-sdk@3.1.0...@metamask/keyring-sdk@4.0.0
 [3.1.0]: https://github.com/MetaMask/accounts/compare/@metamask/keyring-sdk@3.0.0...@metamask/keyring-sdk@3.1.0
 [3.0.0]: https://github.com/MetaMask/accounts/compare/@metamask/keyring-sdk@2.3.0...@metamask/keyring-sdk@3.0.0

package/README.md

@@ -42,6 +42,97 @@ export class MyKeyringV2 extends EthKeyringWrapper<MyLegacyKeyring> {
 }
 ```
 
+## Atomic keyrings
+
+Most keyrings are in-memory: their operations complete in microseconds, so the
+`KeyringController` can safely wrap every operation in a controller-wide mutex.
+That model breaks down for keyrings whose operations are long-running network
+protocols (for example, MPC ceremonies): holding the mutex for the ceremony
+freezes every other controller operation, and multi-step remote/local
+transitions cannot be made crash-safe.
+
+`AtomicKeyring` inverts the lock ownership for such keyrings. The keyring
+serializes its own operations with an internal read-write lock, runs long work
+entirely outside the controller mutex, and calls back into the controller —
+through the injected `update` callback — only when it has new state to persist.
+The controller holds its mutex just for the sub-millisecond commit window.
+
+```ts
+import {
+  AtomicKeyring,
+  isAtomicKeyring,
+  type AtomicUpdater,
+} from '@metamask/keyring-sdk';
+
+class ExampleAtomicKeyring extends AtomicKeyring {
+  #state: 'uninitialized' | 'staged' | 'ready' = 'uninitialized';
+
+  constructor(updater: AtomicUpdater) {
+    super({ updater });
+  }
+
+  // Snapshot reads stay lock-free: the controller calls them while holding
+  // its own mutex.
+  async serialize(): Promise<Json> {
+    return { state: this.#state };
+  }
+
+  async createAccount(): Promise<void> {
+    // Long-running work runs inside the write lock, outside the controller
+    // mutex. Readers and other writers queue behind it.
+    await this.withWriteLock(async () => {
+      const next = await this.#runCeremony(); // compute and validate — may fail freely
+
+      // Checkpoint 1: stage the pre-computed state.
+      await this.update(() => {
+        this.#state = 'staged';
+      });
+
+      await this.#activateRemote(); // remote commit
+
+      // Checkpoint 2: promote to ready.
+      await this.update(() => {
+        this.#state = 'ready';
+      });
+    });
+  }
+}
+
+// Brand-based detection — never `instanceof`, which fails across duplicate
+// copies of the package.
+if (isAtomicKeyring(value)) {
+  /* dispatch without holding the controller mutex */
+}
+```
+
+The contract, enforced by design rather than caller discipline:
+
+- **Actions are pure assignments.** Compute and validate the next state
+  _before_ calling `update`. A throwing action is a keyring bug.
+- **No nested `update` calls.** A nested call is rejected with an explicit
+  error, never a deadlock.
+- **Snapshot reads stay lock-free.** `getAccounts` and `serialize` are called
+  by the controller while it holds its mutex (and by `update` while the keyring
+  holds its write lock), so they must return immediately from the current
+  state.
+- **`init` stays cheap.** The controller invokes `init` under its lock, at
+  construction and vault-restore time. Long work belongs in write operations.
+- **No rollback.** On the atomic dispatch path a failed operation keeps every
+  committed checkpoint, so the next write operation advances the state machine
+  instead of re-running the ceremony.
+
+A crash between the checkpoints leaves a persisted, recoverable intermediate
+state; the next write operation advances the state machine (`staged` →
+`ready`) without re-running the ceremony.
+
+`ReadWriteLock` is also exported on its own, for keyrings that want the
+read-write lock without the base class: parallel readers, exclusive writers,
+first-in-first-out grant order, and a new reader always queues behind a
+pending writer — so a steady stream of reads cannot starve a long write. For
+read-heavy workloads, `{ priority: 'read' }` lets new readers join active
+readers even while a writer is merely queued, at the cost that continuous
+reads can starve a queued writer.
+
 ## Contributing
 
 This package is part of a monorepo. Instructions for contributing can be found in the [monorepo README](https://github.com/MetaMask/accounts#readme).

package/dist/atomic-keyring.cjs

@@ -0,0 +1,126 @@
+"use strict";
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _AtomicKeyring_updater, _AtomicKeyring_rwLock, _AtomicKeyring_updating;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isAtomicKeyring = exports.AtomicKeyring = void 0;
+const read_write_lock_1 = require("./read-write-lock.cjs");
+/**
+ * Brand used to mark `AtomicKeyring` instances. Registered on the global
+ * symbol registry, so the brand survives duplicate copies of this package —
+ * where `instanceof` would fail — and `isAtomicKeyring` keeps working.
+ */
+const ATOMIC_KEYRING_BRAND = Symbol.for('@metamask/keyring-sdk/atomic-keyring');
+/**
+ * Base class for keyrings that serialize their own operations and call back
+ * into the controller only to persist state.
+ *
+ * Long-running work runs inside the lock helpers, entirely outside the
+ * controller mutex; state is committed through `update`.
+ *
+ * Subclasses implementing an `init` lifecycle hook must keep it cheap —
+ * in-memory work only. The controller invokes `init` under its lock, at
+ * construction and vault-restore time; an `init` that performs long work,
+ * or calls `update` (which needs that same, non-reentrant lock), would
+ * block or deadlock the controller. Long work belongs in write operations,
+ * which the controller dispatches without holding its lock.
+ *
+ * Snapshot reads the controller performs itself — `getAccounts` and
+ * `serialize` — must stay lock-free in subclasses: the controller calls
+ * them while holding its own mutex, and the updater calls `serialize` while
+ * the keyring is inside a write operation. They must return immediately
+ * from the current state.
+ */
+class AtomicKeyring {
+    /**
+     * The updater is required at construction — no unbound state, ever.
+     *
+     * @param options - Constructor options.
+     * @param options.updater - The controller's vault-write callback, which
+     * this keyring invokes through `update` to commit state.
+     */
+    constructor(options) {
+        _AtomicKeyring_updater.set(this, void 0);
+        _AtomicKeyring_rwLock.set(this, new read_write_lock_1.ReadWriteLock());
+        _AtomicKeyring_updating.set(this, false);
+        __classPrivateFieldSet(this, _AtomicKeyring_updater, options.updater, "f");
+        this[ATOMIC_KEYRING_BRAND] = true;
+    }
+    /**
+     * Commit a state mutation on behalf of this keyring. Injects `this` into
+     * the updater, so the controller can verify registration.
+     *
+     * Actions must be pure assignments of pre-computed next state: compute
+     * and validate before calling `update`. A throwing action is a keyring
+     * bug, and is rethrown as such. Nested `update` calls are rejected with
+     * an error, never a deadlock.
+     *
+     * Call `update` only from within a write-locked operation, so commits
+     * cannot interleave with other operations on this keyring.
+     *
+     * @param action - The state mutation to commit. Must be a pure assignment
+     * of pre-computed next state.
+     * @throws If called while another `update` call is in progress, or if the
+     * action or updater throws.
+     */
+    async update(action) {
+        if (__classPrivateFieldGet(this, _AtomicKeyring_updating, "f")) {
+            throw new Error('AtomicKeyring - Nested update() calls are not allowed. The update() action must not call update() again.');
+        }
+        __classPrivateFieldSet(this, _AtomicKeyring_updating, true, "f");
+        try {
+            await __classPrivateFieldGet(this, _AtomicKeyring_updater, "f").call(this, this, action);
+        }
+        finally {
+            __classPrivateFieldSet(this, _AtomicKeyring_updating, false, "f");
+        }
+    }
+    /**
+     * Run a read operation — parallel with other readers, queued behind
+     * writers. Only for operations that can tolerate waiting behind a write
+     * section.
+     *
+     * @param fn - The operation to run while holding the read lock.
+     * @returns Whatever `fn` resolves to.
+     */
+    async withReadLock(fn) {
+        return __classPrivateFieldGet(this, _AtomicKeyring_rwLock, "f").withReadLock(fn);
+    }
+    /**
+     * Run a write operation — exclusive with readers and other writers.
+     * Long-running network work belongs here, outside the controller mutex.
+     *
+     * @param fn - The operation to run while holding the write lock.
+     * @returns Whatever `fn` resolves to.
+     */
+    async withWriteLock(fn) {
+        return __classPrivateFieldGet(this, _AtomicKeyring_rwLock, "f").withWriteLock(fn);
+    }
+}
+exports.AtomicKeyring = AtomicKeyring;
+_AtomicKeyring_updater = new WeakMap(), _AtomicKeyring_rwLock = new WeakMap(), _AtomicKeyring_updating = new WeakMap();
+/**
+ * Whether the value is an `AtomicKeyring`.
+ *
+ * Brand-based — a global-registry symbol set by the constructor — so it
+ * works across duplicate copies of the package, where `instanceof` fails.
+ *
+ * @param value - The value to check.
+ * @returns Whether the value is an `AtomicKeyring` instance.
+ */
+function isAtomicKeyring(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        value[ATOMIC_KEYRING_BRAND] === true);
+}
+exports.isAtomicKeyring = isAtomicKeyring;
+//# sourceMappingURL=atomic-keyring.cjs.map

package/dist/atomic-keyring.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"atomic-keyring.cjs","sourceRoot":"","sources":["../src/atomic-keyring.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;AAAA,2DAAkD;AAiBlD;;;;GAIG;AACH,MAAM,oBAAoB,GAAG,MAAM,CAAC,GAAG,CAAC,sCAAsC,CAAC,CAAC;AAEhF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAsB,aAAa;IAOjC;;;;;;OAMG;IACH,YAAY,OAAmC;QAbtC,yCAAwB;QAExB,gCAAyB,IAAI,+BAAa,EAAE,EAAC;QAEtD,kCAAqB,KAAK,EAAC;QAUzB,uBAAA,IAAI,0BAAY,OAAO,CAAC,OAAO,MAAA,CAAC;QAC/B,IAAqC,CAAC,oBAAoB,CAAC,GAAG,IAAI,CAAC;IACtE,CAAC;IAED;;;;;;;;;;;;;;;;OAgBG;IACO,KAAK,CAAC,MAAM,CAAC,MAAkC;QACvD,IAAI,uBAAA,IAAI,+BAAU,EAAE,CAAC;YACnB,MAAM,IAAI,KAAK,CACb,0GAA0G,CAC3G,CAAC;QACJ,CAAC;QAED,uBAAA,IAAI,2BAAa,IAAI,MAAA,CAAC;QACtB,IAAI,CAAC;YACH,MAAM,uBAAA,IAAI,8BAAS,MAAb,IAAI,EAAU,IAAI,EAAE,MAAM,CAAC,CAAC;QACpC,CAAC;gBAAS,CAAC;YACT,uBAAA,IAAI,2BAAa,KAAK,MAAA,CAAC;QACzB,CAAC;IACH,CAAC;IAED;;;;;;;OAOG;IACO,KAAK,CAAC,YAAY,CAC1B,EAAyB;QAEzB,OAAO,uBAAA,IAAI,6BAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC;IACvC,CAAC;IAED;;;;;;OAMG;IACO,KAAK,CAAC,aAAa,CAC3B,EAAyB;QAEzB,OAAO,uBAAA,IAAI,6BAAQ,CAAC,aAAa,CAAC,EAAE,CAAC,CAAC;IACxC,CAAC;CACF;AA7ED,sCA6EC;;AAED;;;;;;;;GAQG;AACH,SAAgB,eAAe,CAAC,KAAc;IAC5C,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACb,KAAsC,CAAC,oBAAoB,CAAC,KAAK,IAAI,CACvE,CAAC;AACJ,CAAC;AAND,0CAMC","sourcesContent":["import { ReadWriteLock } from './read-write-lock';\n\n/**\n * A vault-write callback injected into an `AtomicKeyring` at construction,\n * via the keyring builder context.\n *\n * Stateless: the calling keyring is the first parameter, so a single\n * function serves every keyring. Acquires the controller lock, verifies the\n * keyring is still registered, runs `action()`, writes the vault if and only\n * if the serialized state changed, then releases — a sub-millisecond commit\n * window.\n */\nexport type AtomicUpdater = (\n  keyring: AtomicKeyring,\n  action: () => void | Promise<void>,\n) => Promise<void>;\n\n/**\n * Brand used to mark `AtomicKeyring` instances. Registered on the global\n * symbol registry, so the brand survives duplicate copies of this package —\n * where `instanceof` would fail — and `isAtomicKeyring` keeps working.\n */\nconst ATOMIC_KEYRING_BRAND = Symbol.for('@metamask/keyring-sdk/atomic-keyring');\n\n/**\n * Base class for keyrings that serialize their own operations and call back\n * into the controller only to persist state.\n *\n * Long-running work runs inside the lock helpers, entirely outside the\n * controller mutex; state is committed through `update`.\n *\n * Subclasses implementing an `init` lifecycle hook must keep it cheap —\n * in-memory work only. The controller invokes `init` under its lock, at\n * construction and vault-restore time; an `init` that performs long work,\n * or calls `update` (which needs that same, non-reentrant lock), would\n * block or deadlock the controller. Long work belongs in write operations,\n * which the controller dispatches without holding its lock.\n *\n * Snapshot reads the controller performs itself — `getAccounts` and\n * `serialize` — must stay lock-free in subclasses: the controller calls\n * them while holding its own mutex, and the updater calls `serialize` while\n * the keyring is inside a write operation. They must return immediately\n * from the current state.\n */\nexport abstract class AtomicKeyring {\n  readonly #updater: AtomicUpdater;\n\n  readonly #rwLock: ReadWriteLock = new ReadWriteLock();\n\n  #updating: boolean = false;\n\n  /**\n   * The updater is required at construction — no unbound state, ever.\n   *\n   * @param options - Constructor options.\n   * @param options.updater - The controller's vault-write callback, which\n   * this keyring invokes through `update` to commit state.\n   */\n  constructor(options: { updater: AtomicUpdater }) {\n    this.#updater = options.updater;\n    (this as Record<PropertyKey, unknown>)[ATOMIC_KEYRING_BRAND] = true;\n  }\n\n  /**\n   * Commit a state mutation on behalf of this keyring. Injects `this` into\n   * the updater, so the controller can verify registration.\n   *\n   * Actions must be pure assignments of pre-computed next state: compute\n   * and validate before calling `update`. A throwing action is a keyring\n   * bug, and is rethrown as such. Nested `update` calls are rejected with\n   * an error, never a deadlock.\n   *\n   * Call `update` only from within a write-locked operation, so commits\n   * cannot interleave with other operations on this keyring.\n   *\n   * @param action - The state mutation to commit. Must be a pure assignment\n   * of pre-computed next state.\n   * @throws If called while another `update` call is in progress, or if the\n   * action or updater throws.\n   */\n  protected async update(action: () => void | Promise<void>): Promise<void> {\n    if (this.#updating) {\n      throw new Error(\n        'AtomicKeyring - Nested update() calls are not allowed. The update() action must not call update() again.',\n      );\n    }\n\n    this.#updating = true;\n    try {\n      await this.#updater(this, action);\n    } finally {\n      this.#updating = false;\n    }\n  }\n\n  /**\n   * Run a read operation — parallel with other readers, queued behind\n   * writers. Only for operations that can tolerate waiting behind a write\n   * section.\n   *\n   * @param fn - The operation to run while holding the read lock.\n   * @returns Whatever `fn` resolves to.\n   */\n  protected async withReadLock<Result>(\n    fn: () => Promise<Result>,\n  ): Promise<Result> {\n    return this.#rwLock.withReadLock(fn);\n  }\n\n  /**\n   * Run a write operation — exclusive with readers and other writers.\n   * Long-running network work belongs here, outside the controller mutex.\n   *\n   * @param fn - The operation to run while holding the write lock.\n   * @returns Whatever `fn` resolves to.\n   */\n  protected async withWriteLock<Result>(\n    fn: () => Promise<Result>,\n  ): Promise<Result> {\n    return this.#rwLock.withWriteLock(fn);\n  }\n}\n\n/**\n * Whether the value is an `AtomicKeyring`.\n *\n * Brand-based — a global-registry symbol set by the constructor — so it\n * works across duplicate copies of the package, where `instanceof` fails.\n *\n * @param value - The value to check.\n * @returns Whether the value is an `AtomicKeyring` instance.\n */\nexport function isAtomicKeyring(value: unknown): value is AtomicKeyring {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    (value as Record<PropertyKey, unknown>)[ATOMIC_KEYRING_BRAND] === true\n  );\n}\n"]}

package/dist/atomic-keyring.d.cts

@@ -0,0 +1,90 @@
+/**
+ * A vault-write callback injected into an `AtomicKeyring` at construction,
+ * via the keyring builder context.
+ *
+ * Stateless: the calling keyring is the first parameter, so a single
+ * function serves every keyring. Acquires the controller lock, verifies the
+ * keyring is still registered, runs `action()`, writes the vault if and only
+ * if the serialized state changed, then releases — a sub-millisecond commit
+ * window.
+ */
+export type AtomicUpdater = (keyring: AtomicKeyring, action: () => void | Promise<void>) => Promise<void>;
+/**
+ * Base class for keyrings that serialize their own operations and call back
+ * into the controller only to persist state.
+ *
+ * Long-running work runs inside the lock helpers, entirely outside the
+ * controller mutex; state is committed through `update`.
+ *
+ * Subclasses implementing an `init` lifecycle hook must keep it cheap —
+ * in-memory work only. The controller invokes `init` under its lock, at
+ * construction and vault-restore time; an `init` that performs long work,
+ * or calls `update` (which needs that same, non-reentrant lock), would
+ * block or deadlock the controller. Long work belongs in write operations,
+ * which the controller dispatches without holding its lock.
+ *
+ * Snapshot reads the controller performs itself — `getAccounts` and
+ * `serialize` — must stay lock-free in subclasses: the controller calls
+ * them while holding its own mutex, and the updater calls `serialize` while
+ * the keyring is inside a write operation. They must return immediately
+ * from the current state.
+ */
+export declare abstract class AtomicKeyring {
+    #private;
+    /**
+     * The updater is required at construction — no unbound state, ever.
+     *
+     * @param options - Constructor options.
+     * @param options.updater - The controller's vault-write callback, which
+     * this keyring invokes through `update` to commit state.
+     */
+    constructor(options: {
+        updater: AtomicUpdater;
+    });
+    /**
+     * Commit a state mutation on behalf of this keyring. Injects `this` into
+     * the updater, so the controller can verify registration.
+     *
+     * Actions must be pure assignments of pre-computed next state: compute
+     * and validate before calling `update`. A throwing action is a keyring
+     * bug, and is rethrown as such. Nested `update` calls are rejected with
+     * an error, never a deadlock.
+     *
+     * Call `update` only from within a write-locked operation, so commits
+     * cannot interleave with other operations on this keyring.
+     *
+     * @param action - The state mutation to commit. Must be a pure assignment
+     * of pre-computed next state.
+     * @throws If called while another `update` call is in progress, or if the
+     * action or updater throws.
+     */
+    protected update(action: () => void | Promise<void>): Promise<void>;
+    /**
+     * Run a read operation — parallel with other readers, queued behind
+     * writers. Only for operations that can tolerate waiting behind a write
+     * section.
+     *
+     * @param fn - The operation to run while holding the read lock.
+     * @returns Whatever `fn` resolves to.
+     */
+    protected withReadLock<Result>(fn: () => Promise<Result>): Promise<Result>;
+    /**
+     * Run a write operation — exclusive with readers and other writers.
+     * Long-running network work belongs here, outside the controller mutex.
+     *
+     * @param fn - The operation to run while holding the write lock.
+     * @returns Whatever `fn` resolves to.
+     */
+    protected withWriteLock<Result>(fn: () => Promise<Result>): Promise<Result>;
+}
+/**
+ * Whether the value is an `AtomicKeyring`.
+ *
+ * Brand-based — a global-registry symbol set by the constructor — so it
+ * works across duplicate copies of the package, where `instanceof` fails.
+ *
+ * @param value - The value to check.
+ * @returns Whether the value is an `AtomicKeyring` instance.
+ */
+export declare function isAtomicKeyring(value: unknown): value is AtomicKeyring;
+//# sourceMappingURL=atomic-keyring.d.cts.map

package/dist/atomic-keyring.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"atomic-keyring.d.cts","sourceRoot":"","sources":["../src/atomic-keyring.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AACH,MAAM,MAAM,aAAa,GAAG,CAC1B,OAAO,EAAE,aAAa,EACtB,MAAM,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAC/B,OAAO,CAAC,IAAI,CAAC,CAAC;AASnB;;;;;;;;;;;;;;;;;;;GAmBG;AACH,8BAAsB,aAAa;;IAOjC;;;;;;OAMG;gBACS,OAAO,EAAE;QAAE,OAAO,EAAE,aAAa,CAAA;KAAE;IAK/C;;;;;;;;;;;;;;;;OAgBG;cACa,MAAM,CAAC,MAAM,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAezE;;;;;;;OAOG;cACa,YAAY,CAAC,MAAM,EACjC,EAAE,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,GACxB,OAAO,CAAC,MAAM,CAAC;IAIlB;;;;;;OAMG;cACa,aAAa,CAAC,MAAM,EAClC,EAAE,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,GACxB,OAAO,CAAC,MAAM,CAAC;CAGnB;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,aAAa,CAMtE"}

package/dist/atomic-keyring.d.mts

@@ -0,0 +1,90 @@
+/**
+ * A vault-write callback injected into an `AtomicKeyring` at construction,
+ * via the keyring builder context.
+ *
+ * Stateless: the calling keyring is the first parameter, so a single
+ * function serves every keyring. Acquires the controller lock, verifies the
+ * keyring is still registered, runs `action()`, writes the vault if and only
+ * if the serialized state changed, then releases — a sub-millisecond commit
+ * window.
+ */
+export type AtomicUpdater = (keyring: AtomicKeyring, action: () => void | Promise<void>) => Promise<void>;
+/**
+ * Base class for keyrings that serialize their own operations and call back
+ * into the controller only to persist state.
+ *
+ * Long-running work runs inside the lock helpers, entirely outside the
+ * controller mutex; state is committed through `update`.
+ *
+ * Subclasses implementing an `init` lifecycle hook must keep it cheap —
+ * in-memory work only. The controller invokes `init` under its lock, at
+ * construction and vault-restore time; an `init` that performs long work,
+ * or calls `update` (which needs that same, non-reentrant lock), would
+ * block or deadlock the controller. Long work belongs in write operations,
+ * which the controller dispatches without holding its lock.
+ *
+ * Snapshot reads the controller performs itself — `getAccounts` and
+ * `serialize` — must stay lock-free in subclasses: the controller calls
+ * them while holding its own mutex, and the updater calls `serialize` while
+ * the keyring is inside a write operation. They must return immediately
+ * from the current state.
+ */
+export declare abstract class AtomicKeyring {
+    #private;
+    /**
+     * The updater is required at construction — no unbound state, ever.
+     *
+     * @param options - Constructor options.
+     * @param options.updater - The controller's vault-write callback, which
+     * this keyring invokes through `update` to commit state.
+     */
+    constructor(options: {
+        updater: AtomicUpdater;
+    });
+    /**
+     * Commit a state mutation on behalf of this keyring. Injects `this` into
+     * the updater, so the controller can verify registration.
+     *
+     * Actions must be pure assignments of pre-computed next state: compute
+     * and validate before calling `update`. A throwing action is a keyring
+     * bug, and is rethrown as such. Nested `update` calls are rejected with
+     * an error, never a deadlock.
+     *
+     * Call `update` only from within a write-locked operation, so commits
+     * cannot interleave with other operations on this keyring.
+     *
+     * @param action - The state mutation to commit. Must be a pure assignment
+     * of pre-computed next state.
+     * @throws If called while another `update` call is in progress, or if the
+     * action or updater throws.
+     */
+    protected update(action: () => void | Promise<void>): Promise<void>;
+    /**
+     * Run a read operation — parallel with other readers, queued behind
+     * writers. Only for operations that can tolerate waiting behind a write
+     * section.
+     *
+     * @param fn - The operation to run while holding the read lock.
+     * @returns Whatever `fn` resolves to.
+     */
+    protected withReadLock<Result>(fn: () => Promise<Result>): Promise<Result>;
+    /**
+     * Run a write operation — exclusive with readers and other writers.
+     * Long-running network work belongs here, outside the controller mutex.
+     *
+     * @param fn - The operation to run while holding the write lock.
+     * @returns Whatever `fn` resolves to.
+     */
+    protected withWriteLock<Result>(fn: () => Promise<Result>): Promise<Result>;
+}
+/**
+ * Whether the value is an `AtomicKeyring`.
+ *
+ * Brand-based — a global-registry symbol set by the constructor — so it
+ * works across duplicate copies of the package, where `instanceof` fails.
+ *
+ * @param value - The value to check.
+ * @returns Whether the value is an `AtomicKeyring` instance.
+ */
+export declare function isAtomicKeyring(value: unknown): value is AtomicKeyring;
+//# sourceMappingURL=atomic-keyring.d.mts.map

package/dist/atomic-keyring.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"atomic-keyring.d.mts","sourceRoot":"","sources":["../src/atomic-keyring.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AACH,MAAM,MAAM,aAAa,GAAG,CAC1B,OAAO,EAAE,aAAa,EACtB,MAAM,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAC/B,OAAO,CAAC,IAAI,CAAC,CAAC;AASnB;;;;;;;;;;;;;;;;;;;GAmBG;AACH,8BAAsB,aAAa;;IAOjC;;;;;;OAMG;gBACS,OAAO,EAAE;QAAE,OAAO,EAAE,aAAa,CAAA;KAAE;IAK/C;;;;;;;;;;;;;;;;OAgBG;cACa,MAAM,CAAC,MAAM,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAezE;;;;;;;OAOG;cACa,YAAY,CAAC,MAAM,EACjC,EAAE,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,GACxB,OAAO,CAAC,MAAM,CAAC;IAIlB;;;;;;OAMG;cACa,aAAa,CAAC,MAAM,EAClC,EAAE,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,GACxB,OAAO,CAAC,MAAM,CAAC;CAGnB;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,aAAa,CAMtE"}

package/dist/atomic-keyring.mjs

@@ -0,0 +1,121 @@
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _AtomicKeyring_updater, _AtomicKeyring_rwLock, _AtomicKeyring_updating;
+import { ReadWriteLock } from "./read-write-lock.mjs";
+/**
+ * Brand used to mark `AtomicKeyring` instances. Registered on the global
+ * symbol registry, so the brand survives duplicate copies of this package —
+ * where `instanceof` would fail — and `isAtomicKeyring` keeps working.
+ */
+const ATOMIC_KEYRING_BRAND = Symbol.for('@metamask/keyring-sdk/atomic-keyring');
+/**
+ * Base class for keyrings that serialize their own operations and call back
+ * into the controller only to persist state.
+ *
+ * Long-running work runs inside the lock helpers, entirely outside the
+ * controller mutex; state is committed through `update`.
+ *
+ * Subclasses implementing an `init` lifecycle hook must keep it cheap —
+ * in-memory work only. The controller invokes `init` under its lock, at
+ * construction and vault-restore time; an `init` that performs long work,
+ * or calls `update` (which needs that same, non-reentrant lock), would
+ * block or deadlock the controller. Long work belongs in write operations,
+ * which the controller dispatches without holding its lock.
+ *
+ * Snapshot reads the controller performs itself — `getAccounts` and
+ * `serialize` — must stay lock-free in subclasses: the controller calls
+ * them while holding its own mutex, and the updater calls `serialize` while
+ * the keyring is inside a write operation. They must return immediately
+ * from the current state.
+ */
+export class AtomicKeyring {
+    /**
+     * The updater is required at construction — no unbound state, ever.
+     *
+     * @param options - Constructor options.
+     * @param options.updater - The controller's vault-write callback, which
+     * this keyring invokes through `update` to commit state.
+     */
+    constructor(options) {
+        _AtomicKeyring_updater.set(this, void 0);
+        _AtomicKeyring_rwLock.set(this, new ReadWriteLock());
+        _AtomicKeyring_updating.set(this, false);
+        __classPrivateFieldSet(this, _AtomicKeyring_updater, options.updater, "f");
+        this[ATOMIC_KEYRING_BRAND] = true;
+    }
+    /**
+     * Commit a state mutation on behalf of this keyring. Injects `this` into
+     * the updater, so the controller can verify registration.
+     *
+     * Actions must be pure assignments of pre-computed next state: compute
+     * and validate before calling `update`. A throwing action is a keyring
+     * bug, and is rethrown as such. Nested `update` calls are rejected with
+     * an error, never a deadlock.
+     *
+     * Call `update` only from within a write-locked operation, so commits
+     * cannot interleave with other operations on this keyring.
+     *
+     * @param action - The state mutation to commit. Must be a pure assignment
+     * of pre-computed next state.
+     * @throws If called while another `update` call is in progress, or if the
+     * action or updater throws.
+     */
+    async update(action) {
+        if (__classPrivateFieldGet(this, _AtomicKeyring_updating, "f")) {
+            throw new Error('AtomicKeyring - Nested update() calls are not allowed. The update() action must not call update() again.');
+        }
+        __classPrivateFieldSet(this, _AtomicKeyring_updating, true, "f");
+        try {
+            await __classPrivateFieldGet(this, _AtomicKeyring_updater, "f").call(this, this, action);
+        }
+        finally {
+            __classPrivateFieldSet(this, _AtomicKeyring_updating, false, "f");
+        }
+    }
+    /**
+     * Run a read operation — parallel with other readers, queued behind
+     * writers. Only for operations that can tolerate waiting behind a write
+     * section.
+     *
+     * @param fn - The operation to run while holding the read lock.
+     * @returns Whatever `fn` resolves to.
+     */
+    async withReadLock(fn) {
+        return __classPrivateFieldGet(this, _AtomicKeyring_rwLock, "f").withReadLock(fn);
+    }
+    /**
+     * Run a write operation — exclusive with readers and other writers.
+     * Long-running network work belongs here, outside the controller mutex.
+     *
+     * @param fn - The operation to run while holding the write lock.
+     * @returns Whatever `fn` resolves to.
+     */
+    async withWriteLock(fn) {
+        return __classPrivateFieldGet(this, _AtomicKeyring_rwLock, "f").withWriteLock(fn);
+    }
+}
+_AtomicKeyring_updater = new WeakMap(), _AtomicKeyring_rwLock = new WeakMap(), _AtomicKeyring_updating = new WeakMap();
+/**
+ * Whether the value is an `AtomicKeyring`.
+ *
+ * Brand-based — a global-registry symbol set by the constructor — so it
+ * works across duplicate copies of the package, where `instanceof` fails.
+ *
+ * @param value - The value to check.
+ * @returns Whether the value is an `AtomicKeyring` instance.
+ */
+export function isAtomicKeyring(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        value[ATOMIC_KEYRING_BRAND] === true);
+}
+//# sourceMappingURL=atomic-keyring.mjs.map

package/dist/atomic-keyring.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"atomic-keyring.mjs","sourceRoot":"","sources":["../src/atomic-keyring.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,OAAO,EAAE,aAAa,EAAE,8BAA0B;AAiBlD;;;;GAIG;AACH,MAAM,oBAAoB,GAAG,MAAM,CAAC,GAAG,CAAC,sCAAsC,CAAC,CAAC;AAEhF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,OAAgB,aAAa;IAOjC;;;;;;OAMG;IACH,YAAY,OAAmC;QAbtC,yCAAwB;QAExB,gCAAyB,IAAI,aAAa,EAAE,EAAC;QAEtD,kCAAqB,KAAK,EAAC;QAUzB,uBAAA,IAAI,0BAAY,OAAO,CAAC,OAAO,MAAA,CAAC;QAC/B,IAAqC,CAAC,oBAAoB,CAAC,GAAG,IAAI,CAAC;IACtE,CAAC;IAED;;;;;;;;;;;;;;;;OAgBG;IACO,KAAK,CAAC,MAAM,CAAC,MAAkC;QACvD,IAAI,uBAAA,IAAI,+BAAU,EAAE,CAAC;YACnB,MAAM,IAAI,KAAK,CACb,0GAA0G,CAC3G,CAAC;QACJ,CAAC;QAED,uBAAA,IAAI,2BAAa,IAAI,MAAA,CAAC;QACtB,IAAI,CAAC;YACH,MAAM,uBAAA,IAAI,8BAAS,MAAb,IAAI,EAAU,IAAI,EAAE,MAAM,CAAC,CAAC;QACpC,CAAC;gBAAS,CAAC;YACT,uBAAA,IAAI,2BAAa,KAAK,MAAA,CAAC;QACzB,CAAC;IACH,CAAC;IAED;;;;;;;OAOG;IACO,KAAK,CAAC,YAAY,CAC1B,EAAyB;QAEzB,OAAO,uBAAA,IAAI,6BAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC;IACvC,CAAC;IAED;;;;;;OAMG;IACO,KAAK,CAAC,aAAa,CAC3B,EAAyB;QAEzB,OAAO,uBAAA,IAAI,6BAAQ,CAAC,aAAa,CAAC,EAAE,CAAC,CAAC;IACxC,CAAC;CACF;;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACb,KAAsC,CAAC,oBAAoB,CAAC,KAAK,IAAI,CACvE,CAAC;AACJ,CAAC","sourcesContent":["import { ReadWriteLock } from './read-write-lock';\n\n/**\n * A vault-write callback injected into an `AtomicKeyring` at construction,\n * via the keyring builder context.\n *\n * Stateless: the calling keyring is the first parameter, so a single\n * function serves every keyring. Acquires the controller lock, verifies the\n * keyring is still registered, runs `action()`, writes the vault if and only\n * if the serialized state changed, then releases — a sub-millisecond commit\n * window.\n */\nexport type AtomicUpdater = (\n  keyring: AtomicKeyring,\n  action: () => void | Promise<void>,\n) => Promise<void>;\n\n/**\n * Brand used to mark `AtomicKeyring` instances. Registered on the global\n * symbol registry, so the brand survives duplicate copies of this package —\n * where `instanceof` would fail — and `isAtomicKeyring` keeps working.\n */\nconst ATOMIC_KEYRING_BRAND = Symbol.for('@metamask/keyring-sdk/atomic-keyring');\n\n/**\n * Base class for keyrings that serialize their own operations and call back\n * into the controller only to persist state.\n *\n * Long-running work runs inside the lock helpers, entirely outside the\n * controller mutex; state is committed through `update`.\n *\n * Subclasses implementing an `init` lifecycle hook must keep it cheap —\n * in-memory work only. The controller invokes `init` under its lock, at\n * construction and vault-restore time; an `init` that performs long work,\n * or calls `update` (which needs that same, non-reentrant lock), would\n * block or deadlock the controller. Long work belongs in write operations,\n * which the controller dispatches without holding its lock.\n *\n * Snapshot reads the controller performs itself — `getAccounts` and\n * `serialize` — must stay lock-free in subclasses: the controller calls\n * them while holding its own mutex, and the updater calls `serialize` while\n * the keyring is inside a write operation. They must return immediately\n * from the current state.\n */\nexport abstract class AtomicKeyring {\n  readonly #updater: AtomicUpdater;\n\n  readonly #rwLock: ReadWriteLock = new ReadWriteLock();\n\n  #updating: boolean = false;\n\n  /**\n   * The updater is required at construction — no unbound state, ever.\n   *\n   * @param options - Constructor options.\n   * @param options.updater - The controller's vault-write callback, which\n   * this keyring invokes through `update` to commit state.\n   */\n  constructor(options: { updater: AtomicUpdater }) {\n    this.#updater = options.updater;\n    (this as Record<PropertyKey, unknown>)[ATOMIC_KEYRING_BRAND] = true;\n  }\n\n  /**\n   * Commit a state mutation on behalf of this keyring. Injects `this` into\n   * the updater, so the controller can verify registration.\n   *\n   * Actions must be pure assignments of pre-computed next state: compute\n   * and validate before calling `update`. A throwing action is a keyring\n   * bug, and is rethrown as such. Nested `update` calls are rejected with\n   * an error, never a deadlock.\n   *\n   * Call `update` only from within a write-locked operation, so commits\n   * cannot interleave with other operations on this keyring.\n   *\n   * @param action - The state mutation to commit. Must be a pure assignment\n   * of pre-computed next state.\n   * @throws If called while another `update` call is in progress, or if the\n   * action or updater throws.\n   */\n  protected async update(action: () => void | Promise<void>): Promise<void> {\n    if (this.#updating) {\n      throw new Error(\n        'AtomicKeyring - Nested update() calls are not allowed. The update() action must not call update() again.',\n      );\n    }\n\n    this.#updating = true;\n    try {\n      await this.#updater(this, action);\n    } finally {\n      this.#updating = false;\n    }\n  }\n\n  /**\n   * Run a read operation — parallel with other readers, queued behind\n   * writers. Only for operations that can tolerate waiting behind a write\n   * section.\n   *\n   * @param fn - The operation to run while holding the read lock.\n   * @returns Whatever `fn` resolves to.\n   */\n  protected async withReadLock<Result>(\n    fn: () => Promise<Result>,\n  ): Promise<Result> {\n    return this.#rwLock.withReadLock(fn);\n  }\n\n  /**\n   * Run a write operation — exclusive with readers and other writers.\n   * Long-running network work belongs here, outside the controller mutex.\n   *\n   * @param fn - The operation to run while holding the write lock.\n   * @returns Whatever `fn` resolves to.\n   */\n  protected async withWriteLock<Result>(\n    fn: () => Promise<Result>,\n  ): Promise<Result> {\n    return this.#rwLock.withWriteLock(fn);\n  }\n}\n\n/**\n * Whether the value is an `AtomicKeyring`.\n *\n * Brand-based — a global-registry symbol set by the constructor — so it\n * works across duplicate copies of the package, where `instanceof` fails.\n *\n * @param value - The value to check.\n * @returns Whether the value is an `AtomicKeyring` instance.\n */\nexport function isAtomicKeyring(value: unknown): value is AtomicKeyring {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    (value as Record<PropertyKey, unknown>)[ATOMIC_KEYRING_BRAND] === true\n  );\n}\n"]}

package/dist/index.cjs

@@ -14,9 +14,11 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./atomic-keyring.cjs"), exports);
 __exportStar(require("./keyring-account-registry.cjs"), exports);
 __exportStar(require("./migration.cjs"), exports);
 __exportStar(require("./mnemonic.cjs"), exports);
 __exportStar(require("./entropy.cjs"), exports);
+__exportStar(require("./read-write-lock.cjs"), exports);
 __exportStar(require("./eth/index.cjs"), exports);
 //# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,iEAA2C;AAC3C,kDAA4B;AAC5B,iDAA2B;AAC3B,gDAA0B;AAC1B,kDAAsB","sourcesContent":["export * from './keyring-account-registry';\nexport * from './migration';\nexport * from './mnemonic';\nexport * from './entropy';\nexport * from './eth';\n"]}
+{"version":3,"file":"index.cjs","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,uDAAiC;AACjC,iEAA2C;AAC3C,kDAA4B;AAC5B,iDAA2B;AAC3B,gDAA0B;AAC1B,wDAAkC;AAClC,kDAAsB","sourcesContent":["export * from './atomic-keyring';\nexport * from './keyring-account-registry';\nexport * from './migration';\nexport * from './mnemonic';\nexport * from './entropy';\nexport * from './read-write-lock';\nexport * from './eth';\n"]}

package/dist/index.d.cts

@@ -1,6 +1,8 @@
+export * from "./atomic-keyring.cjs";
 export * from "./keyring-account-registry.cjs";
 export * from "./migration.cjs";
 export * from "./mnemonic.cjs";
 export * from "./entropy.cjs";
+export * from "./read-write-lock.cjs";
 export * from "./eth/index.cjs";
 //# sourceMappingURL=index.d.cts.map

package/dist/index.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.cts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,+CAA2C;AAC3C,gCAA4B;AAC5B,+BAA2B;AAC3B,8BAA0B;AAC1B,gCAAsB"}
+{"version":3,"file":"index.d.cts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,qCAAiC;AACjC,+CAA2C;AAC3C,gCAA4B;AAC5B,+BAA2B;AAC3B,8BAA0B;AAC1B,sCAAkC;AAClC,gCAAsB"}

package/dist/index.d.mts

@@ -1,6 +1,8 @@
+export * from "./atomic-keyring.mjs";
 export * from "./keyring-account-registry.mjs";
 export * from "./migration.mjs";
 export * from "./mnemonic.mjs";
 export * from "./entropy.mjs";
+export * from "./read-write-lock.mjs";
 export * from "./eth/index.mjs";
 //# sourceMappingURL=index.d.mts.map