@metamask/keyring-sdk 4.1.0 → 4.2.0

package/CHANGELOG.md

@@ -7,6 +7,17 @@ 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
@@ -141,7 +152,8 @@ 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.1.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

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

package/dist/index.d.mts.map

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

package/dist/index.mjs

@@ -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.mjs.map

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,+CAA2C;AAC3C,gCAA4B;AAC5B,+BAA2B;AAC3B,8BAA0B;AAC1B,gCAAsB","sourcesContent":["export * from './keyring-account-registry';\nexport * from './migration';\nexport * from './mnemonic';\nexport * from './entropy';\nexport * from './eth';\n"]}
+{"version":3,"file":"index.mjs","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,qCAAiC;AACjC,+CAA2C;AAC3C,gCAA4B;AAC5B,+BAA2B;AAC3B,8BAA0B;AAC1B,sCAAkC;AAClC,gCAAsB","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/read-write-lock.cjs

@@ -0,0 +1,150 @@
+"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 _ReadWriteLock_instances, _ReadWriteLock_readerCount, _ReadWriteLock_writerActive, _ReadWriteLock_waiters, _ReadWriteLock_priority, _ReadWriteLock_withLock, _ReadWriteLock_hasWaiters, _ReadWriteLock_isReading, _ReadWriteLock_isWriting, _ReadWriteLock_acquire, _ReadWriteLock_grant, _ReadWriteLock_release, _ReadWriteLock_drain;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReadWriteLock = void 0;
+/**
+ * A read-write lock: multiple readers may hold the lock simultaneously,
+ * while writers hold it exclusively.
+ *
+ * Grant order is first-in-first-out, and the lock is write-preferring by
+ * default: a pending writer blocks new readers, and consecutive queued
+ * readers are granted together once the lock turns over to them. Set the
+ * `priority` option to `'read'` to let new readers join active readers even
+ * while a writer is queued — better read latency, at the cost that
+ * continuous reads can starve a queued writer. The lock is always released
+ * when the callback settles, whether it resolves or throws.
+ */
+class ReadWriteLock {
+    /**
+     * @param options - Lock options.
+     * @param options.priority - Which mode takes priority when both are
+     * contended. Defaults to `'write'`.
+     */
+    constructor(options = {}) {
+        _ReadWriteLock_instances.add(this);
+        _ReadWriteLock_readerCount.set(this, 0);
+        _ReadWriteLock_writerActive.set(this, false);
+        _ReadWriteLock_waiters.set(this, []);
+        _ReadWriteLock_priority.set(this, void 0);
+        __classPrivateFieldSet(this, _ReadWriteLock_priority, options.priority ?? 'write', "f");
+    }
+    /**
+     * Run a read operation — parallel with other readers, exclusive with
+     * writers. New readers queue behind any pending writer.
+     *
+     * @param fn - The operation to run while holding the read lock.
+     * @returns Whatever `fn` resolves to.
+     */
+    async withReadLock(fn) {
+        return __classPrivateFieldGet(this, _ReadWriteLock_instances, "m", _ReadWriteLock_withLock).call(this, 'read', fn);
+    }
+    /**
+     * Run a write operation — exclusive with readers and other writers.
+     *
+     * @param fn - The operation to run while holding the write lock.
+     * @returns Whatever `fn` resolves to.
+     */
+    async withWriteLock(fn) {
+        return __classPrivateFieldGet(this, _ReadWriteLock_instances, "m", _ReadWriteLock_withLock).call(this, 'write', fn);
+    }
+}
+exports.ReadWriteLock = ReadWriteLock;
+_ReadWriteLock_readerCount = new WeakMap(), _ReadWriteLock_writerActive = new WeakMap(), _ReadWriteLock_waiters = new WeakMap(), _ReadWriteLock_priority = new WeakMap(), _ReadWriteLock_instances = new WeakSet(), _ReadWriteLock_withLock = 
+/**
+ * Acquire the lock in the given mode, run the operation, and release the
+ * lock — including on a throw, so the lock can never leak.
+ *
+ * @param mode - The mode in which to hold the lock.
+ * @param fn - The operation to run while holding the lock.
+ * @returns Whatever `fn` resolves to.
+ */
+async function _ReadWriteLock_withLock(mode, fn) {
+    await __classPrivateFieldGet(this, _ReadWriteLock_instances, "m", _ReadWriteLock_acquire).call(this, mode);
+    try {
+        return await fn();
+    }
+    finally {
+        __classPrivateFieldGet(this, _ReadWriteLock_instances, "m", _ReadWriteLock_release).call(this, mode);
+    }
+}, _ReadWriteLock_hasWaiters = function _ReadWriteLock_hasWaiters() {
+    return __classPrivateFieldGet(this, _ReadWriteLock_waiters, "f").length > 0;
+}, _ReadWriteLock_isReading = function _ReadWriteLock_isReading() {
+    return __classPrivateFieldGet(this, _ReadWriteLock_readerCount, "f") > 0;
+}, _ReadWriteLock_isWriting = function _ReadWriteLock_isWriting() {
+    return __classPrivateFieldGet(this, _ReadWriteLock_writerActive, "f");
+}, _ReadWriteLock_acquire = 
+/**
+ * Acquire the lock in the given mode, queuing when it cannot be granted
+ * immediately.
+ *
+ * @param mode - The mode to acquire.
+ * @returns A promise that resolves once the lock is held.
+ */
+async function _ReadWriteLock_acquire(mode) {
+    return new Promise((resolve) => {
+        // Writing is exclusive, so we cannot acquire the lock if a writer is active.
+        const blockedByWriter = __classPrivateFieldGet(this, _ReadWriteLock_instances, "m", _ReadWriteLock_isWriting).call(this);
+        // Writing is exclusive with readers, so we cannot acquire the lock if any reader is active.
+        const blockedByReaders = mode === 'write' && __classPrivateFieldGet(this, _ReadWriteLock_instances, "m", _ReadWriteLock_isReading).call(this);
+        // We cannot acquire the lock for reading if there are waiters, unless priority is 'read'.
+        const blockedByWriterPriority = mode === 'read' && __classPrivateFieldGet(this, _ReadWriteLock_priority, "f") === 'write' && __classPrivateFieldGet(this, _ReadWriteLock_instances, "m", _ReadWriteLock_hasWaiters).call(this); // We might have pending write requests in the queue.
+        const acquire = !(blockedByWriter ||
+            blockedByReaders ||
+            blockedByWriterPriority);
+        if (acquire) {
+            __classPrivateFieldGet(this, _ReadWriteLock_instances, "m", _ReadWriteLock_grant).call(this, mode);
+            resolve();
+        }
+        else {
+            // We cannot grant the lock immediately, so we queue the waiter.
+            __classPrivateFieldGet(this, _ReadWriteLock_waiters, "f").push({ mode, resolve });
+        }
+    });
+}, _ReadWriteLock_grant = function _ReadWriteLock_grant(mode) {
+    if (mode === 'read') {
+        __classPrivateFieldSet(this, _ReadWriteLock_readerCount, __classPrivateFieldGet(this, _ReadWriteLock_readerCount, "f") + 1, "f");
+    }
+    else {
+        __classPrivateFieldSet(this, _ReadWriteLock_writerActive, true, "f");
+    }
+}, _ReadWriteLock_release = function _ReadWriteLock_release(mode) {
+    if (mode === 'read') {
+        __classPrivateFieldSet(this, _ReadWriteLock_readerCount, __classPrivateFieldGet(this, _ReadWriteLock_readerCount, "f") - 1, "f");
+    }
+    else {
+        __classPrivateFieldSet(this, _ReadWriteLock_writerActive, false, "f");
+    }
+    __classPrivateFieldGet(this, _ReadWriteLock_instances, "m", _ReadWriteLock_drain).call(this);
+}, _ReadWriteLock_drain = function _ReadWriteLock_drain() {
+    let waiter = __classPrivateFieldGet(this, _ReadWriteLock_waiters, "f").shift();
+    while (waiter !== undefined) {
+        // Writing is exclusive, so we cannot acquire the lock if a writer is active.
+        const blockedByWriter = __classPrivateFieldGet(this, _ReadWriteLock_instances, "m", _ReadWriteLock_isWriting).call(this);
+        // Reading blocks a writer, so we cannot acquire the lock for writing if any reader is active.
+        const blockedByReaders = waiter.mode === 'write' && __classPrivateFieldGet(this, _ReadWriteLock_instances, "m", _ReadWriteLock_isReading).call(this);
+        const acquire = !(blockedByWriter || blockedByReaders);
+        if (acquire) {
+            // Grant the front waiter and continue with the next one, so consecutive queued readers are granted together.
+            __classPrivateFieldGet(this, _ReadWriteLock_instances, "m", _ReadWriteLock_grant).call(this, waiter.mode);
+            waiter.resolve();
+            waiter = __classPrivateFieldGet(this, _ReadWriteLock_waiters, "f").shift();
+        }
+        else {
+            // The waiter is blocked by an active holder; put it back at the front and stop.
+            __classPrivateFieldGet(this, _ReadWriteLock_waiters, "f").unshift(waiter);
+            return;
+        }
+    }
+};
+//# sourceMappingURL=read-write-lock.cjs.map

package/dist/read-write-lock.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-write-lock.cjs","sourceRoot":"","sources":["../src/read-write-lock.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * A mode in which the lock can be held: shared (`'read'`) or exclusive\n * (`'write'`).\n */\ntype LockMode = 'read' | 'write';\n\n/**\n * A queued lock-acquisition request.\n */\ntype LockWaiter = {\n  /** The mode being acquired. */\n  mode: LockMode;\n  /** Resolves once the lock has been granted. */\n  resolve: () => void;\n};\n\n/**\n * Which mode a {@link ReadWriteLock} prioritizes when both are contended.\n */\nexport type ReadWriteLockPriority = 'read' | 'write';\n\n/**\n * Options for constructing a {@link ReadWriteLock}.\n */\nexport type ReadWriteLockOptions = {\n  /**\n   * Which mode takes priority when both are contended. Defaults to\n   * `'write'`.\n   *\n   * - `'write'`: a pending writer blocks new readers, so a steady stream of\n   * reads cannot starve a long write.\n   * - `'read'`: new readers join active readers even while a writer is\n   * queued, for better read latency — at the cost that a continuous stream\n   * of reads can starve a queued writer.\n   */\n  priority?: ReadWriteLockPriority;\n};\n\n/**\n * A read-write lock: multiple readers may hold the lock simultaneously,\n * while writers hold it exclusively.\n *\n * Grant order is first-in-first-out, and the lock is write-preferring by\n * default: a pending writer blocks new readers, and consecutive queued\n * readers are granted together once the lock turns over to them. Set the\n * `priority` option to `'read'` to let new readers join active readers even\n * while a writer is queued — better read latency, at the cost that\n * continuous reads can starve a queued writer. The lock is always released\n * when the callback settles, whether it resolves or throws.\n */\nexport class ReadWriteLock {\n  #readerCount: number = 0;\n\n  #writerActive: boolean = false;\n\n  readonly #waiters: LockWaiter[] = [];\n\n  readonly #priority: ReadWriteLockPriority;\n\n  /**\n   * @param options - Lock options.\n   * @param options.priority - Which mode takes priority when both are\n   * contended. Defaults to `'write'`.\n   */\n  constructor(options: ReadWriteLockOptions = {}) {\n    this.#priority = options.priority ?? 'write';\n  }\n\n  /**\n   * Run a read operation — parallel with other readers, exclusive with\n   * writers. New readers queue behind any pending writer.\n   *\n   * @param fn - The operation to run while holding the read lock.\n   * @returns Whatever `fn` resolves to.\n   */\n  async withReadLock<Result>(fn: () => Promise<Result>): Promise<Result> {\n    return this.#withLock('read', fn);\n  }\n\n  /**\n   * Run a write operation — exclusive with readers and other writers.\n   *\n   * @param fn - The operation to run while holding the write lock.\n   * @returns Whatever `fn` resolves to.\n   */\n  async withWriteLock<Result>(fn: () => Promise<Result>): Promise<Result> {\n    return this.#withLock('write', fn);\n  }\n\n  /**\n   * Acquire the lock in the given mode, run the operation, and release the\n   * lock — including on a throw, so the lock can never leak.\n   *\n   * @param mode - The mode in which to hold the lock.\n   * @param fn - The operation to run while holding the lock.\n   * @returns Whatever `fn` resolves to.\n   */\n  async #withLock<Result>(\n    mode: LockMode,\n    fn: () => Promise<Result>,\n  ): Promise<Result> {\n    await this.#acquire(mode);\n    try {\n      return await fn();\n    } finally {\n      this.#release(mode);\n    }\n  }\n\n  /**\n   * Whether any acquisition request is queued, waiting for the lock to turn\n   * over to it. A queued waiter always blocks newcomers, which keeps the\n   * grant order first-in-first-out.\n   *\n   * @returns Whether any acquisition request is queued.\n   */\n  #hasWaiters(): boolean {\n    return this.#waiters.length > 0;\n  }\n\n  /**\n   * Whether the lock is currently held for reading. Readers hold the lock\n   * in parallel, so this does not mean an exclusive hold.\n   *\n   * @returns Whether any reader is active.\n   */\n  #isReading(): boolean {\n    return this.#readerCount > 0;\n  }\n\n  /**\n   * Whether the lock is currently held for writing. A writer holds the lock\n   * exclusively: while writing, no other holder — reader or writer — can\n   * be active.\n   *\n   * @returns Whether a writer is active.\n   */\n  #isWriting(): boolean {\n    return this.#writerActive;\n  }\n\n  /**\n   * Acquire the lock in the given mode, queuing when it cannot be granted\n   * immediately.\n   *\n   * @param mode - The mode to acquire.\n   * @returns A promise that resolves once the lock is held.\n   */\n  async #acquire(mode: LockMode): Promise<void> {\n    return new Promise<void>((resolve) => {\n      // Writing is exclusive, so we cannot acquire the lock if a writer is active.\n      const blockedByWriter = this.#isWriting();\n      // Writing is exclusive with readers, so we cannot acquire the lock if any reader is active.\n      const blockedByReaders = mode === 'write' && this.#isReading();\n      // We cannot acquire the lock for reading if there are waiters, unless priority is 'read'.\n      const blockedByWriterPriority =\n        mode === 'read' && this.#priority === 'write' && this.#hasWaiters(); // We might have pending write requests in the queue.\n\n      const acquire = !(\n        blockedByWriter ||\n        blockedByReaders ||\n        blockedByWriterPriority\n      );\n\n      if (acquire) {\n        this.#grant(mode);\n        resolve();\n      } else {\n        // We cannot grant the lock immediately, so we queue the waiter.\n        this.#waiters.push({ mode, resolve });\n      }\n    });\n  }\n\n  /**\n   * Grant the lock in the given mode. Only called when the grant is legal.\n   *\n   * @param mode - The mode to grant.\n   */\n  #grant(mode: LockMode): void {\n    if (mode === 'read') {\n      this.#readerCount += 1;\n    } else {\n      this.#writerActive = true;\n    }\n  }\n\n  /**\n   * Release the lock in the given mode, then grant queued waiters in order.\n   *\n   * @param mode - The mode being released.\n   */\n  #release(mode: LockMode): void {\n    if (mode === 'read') {\n      this.#readerCount -= 1;\n    } else {\n      this.#writerActive = false;\n    }\n    this.#drain();\n  }\n\n  /**\n   * Grant queued waiters, in order, while the front of the queue can be\n   * granted. Consecutive queued readers are granted together; a granted\n   * writer blocks everything behind it. Unlike a newcomer, the front\n   * waiter is never blocked by queued waiters — everyone behind it\n   * arrived later — so only active holders block a grant here.\n   */\n  #drain(): void {\n    let waiter: LockWaiter | undefined = this.#waiters.shift();\n    while (waiter !== undefined) {\n      // Writing is exclusive, so we cannot acquire the lock if a writer is active.\n      const blockedByWriter = this.#isWriting();\n      // Reading blocks a writer, so we cannot acquire the lock for writing if any reader is active.\n      const blockedByReaders = waiter.mode === 'write' && this.#isReading();\n\n      const acquire = !(blockedByWriter || blockedByReaders);\n\n      if (acquire) {\n        // Grant the front waiter and continue with the next one, so consecutive queued readers are granted together.\n        this.#grant(waiter.mode);\n        waiter.resolve();\n        waiter = this.#waiters.shift();\n      } else {\n        // The waiter is blocked by an active holder; put it back at the front and stop.\n        this.#waiters.unshift(waiter);\n        return;\n      }\n    }\n  }\n}\n"]}

package/dist/read-write-lock.d.cts

@@ -0,0 +1,57 @@
+/**
+ * Which mode a {@link ReadWriteLock} prioritizes when both are contended.
+ */
+export type ReadWriteLockPriority = 'read' | 'write';
+/**
+ * Options for constructing a {@link ReadWriteLock}.
+ */
+export type ReadWriteLockOptions = {
+    /**
+     * Which mode takes priority when both are contended. Defaults to
+     * `'write'`.
+     *
+     * - `'write'`: a pending writer blocks new readers, so a steady stream of
+     * reads cannot starve a long write.
+     * - `'read'`: new readers join active readers even while a writer is
+     * queued, for better read latency — at the cost that a continuous stream
+     * of reads can starve a queued writer.
+     */
+    priority?: ReadWriteLockPriority;
+};
+/**
+ * A read-write lock: multiple readers may hold the lock simultaneously,
+ * while writers hold it exclusively.
+ *
+ * Grant order is first-in-first-out, and the lock is write-preferring by
+ * default: a pending writer blocks new readers, and consecutive queued
+ * readers are granted together once the lock turns over to them. Set the
+ * `priority` option to `'read'` to let new readers join active readers even
+ * while a writer is queued — better read latency, at the cost that
+ * continuous reads can starve a queued writer. The lock is always released
+ * when the callback settles, whether it resolves or throws.
+ */
+export declare class ReadWriteLock {
+    #private;
+    /**
+     * @param options - Lock options.
+     * @param options.priority - Which mode takes priority when both are
+     * contended. Defaults to `'write'`.
+     */
+    constructor(options?: ReadWriteLockOptions);
+    /**
+     * Run a read operation — parallel with other readers, exclusive with
+     * writers. New readers queue behind any pending writer.
+     *
+     * @param fn - The operation to run while holding the read lock.
+     * @returns Whatever `fn` resolves to.
+     */
+    withReadLock<Result>(fn: () => Promise<Result>): Promise<Result>;
+    /**
+     * Run a write operation — exclusive with readers and other writers.
+     *
+     * @param fn - The operation to run while holding the write lock.
+     * @returns Whatever `fn` resolves to.
+     */
+    withWriteLock<Result>(fn: () => Promise<Result>): Promise<Result>;
+}
+//# sourceMappingURL=read-write-lock.d.cts.map

package/dist/read-write-lock.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-write-lock.d.cts","sourceRoot":"","sources":["../src/read-write-lock.ts"],"names":[],"mappings":"AAgBA;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG,MAAM,GAAG,OAAO,CAAC;AAErD;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC;;;;;;;;;OASG;IACH,QAAQ,CAAC,EAAE,qBAAqB,CAAC;CAClC,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,qBAAa,aAAa;;IASxB;;;;OAIG;gBACS,OAAO,GAAE,oBAAyB;IAI9C;;;;;;OAMG;IACG,YAAY,CAAC,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC;IAItE;;;;;OAKG;IACG,aAAa,CAAC,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC;CAiJxE"}

package/dist/read-write-lock.d.mts

@@ -0,0 +1,57 @@
+/**
+ * Which mode a {@link ReadWriteLock} prioritizes when both are contended.
+ */
+export type ReadWriteLockPriority = 'read' | 'write';
+/**
+ * Options for constructing a {@link ReadWriteLock}.
+ */
+export type ReadWriteLockOptions = {
+    /**
+     * Which mode takes priority when both are contended. Defaults to
+     * `'write'`.
+     *
+     * - `'write'`: a pending writer blocks new readers, so a steady stream of
+     * reads cannot starve a long write.
+     * - `'read'`: new readers join active readers even while a writer is
+     * queued, for better read latency — at the cost that a continuous stream
+     * of reads can starve a queued writer.
+     */
+    priority?: ReadWriteLockPriority;
+};
+/**
+ * A read-write lock: multiple readers may hold the lock simultaneously,
+ * while writers hold it exclusively.
+ *
+ * Grant order is first-in-first-out, and the lock is write-preferring by
+ * default: a pending writer blocks new readers, and consecutive queued
+ * readers are granted together once the lock turns over to them. Set the
+ * `priority` option to `'read'` to let new readers join active readers even
+ * while a writer is queued — better read latency, at the cost that
+ * continuous reads can starve a queued writer. The lock is always released
+ * when the callback settles, whether it resolves or throws.
+ */
+export declare class ReadWriteLock {
+    #private;
+    /**
+     * @param options - Lock options.
+     * @param options.priority - Which mode takes priority when both are
+     * contended. Defaults to `'write'`.
+     */
+    constructor(options?: ReadWriteLockOptions);
+    /**
+     * Run a read operation — parallel with other readers, exclusive with
+     * writers. New readers queue behind any pending writer.
+     *
+     * @param fn - The operation to run while holding the read lock.
+     * @returns Whatever `fn` resolves to.
+     */
+    withReadLock<Result>(fn: () => Promise<Result>): Promise<Result>;
+    /**
+     * Run a write operation — exclusive with readers and other writers.
+     *
+     * @param fn - The operation to run while holding the write lock.
+     * @returns Whatever `fn` resolves to.
+     */
+    withWriteLock<Result>(fn: () => Promise<Result>): Promise<Result>;
+}
+//# sourceMappingURL=read-write-lock.d.mts.map

package/dist/read-write-lock.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-write-lock.d.mts","sourceRoot":"","sources":["../src/read-write-lock.ts"],"names":[],"mappings":"AAgBA;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG,MAAM,GAAG,OAAO,CAAC;AAErD;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC;;;;;;;;;OASG;IACH,QAAQ,CAAC,EAAE,qBAAqB,CAAC;CAClC,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,qBAAa,aAAa;;IASxB;;;;OAIG;gBACS,OAAO,GAAE,oBAAyB;IAI9C;;;;;;OAMG;IACG,YAAY,CAAC,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC;IAItE;;;;;OAKG;IACG,aAAa,CAAC,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC;CAiJxE"}

package/dist/read-write-lock.mjs

@@ -0,0 +1,146 @@
+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 _ReadWriteLock_instances, _ReadWriteLock_readerCount, _ReadWriteLock_writerActive, _ReadWriteLock_waiters, _ReadWriteLock_priority, _ReadWriteLock_withLock, _ReadWriteLock_hasWaiters, _ReadWriteLock_isReading, _ReadWriteLock_isWriting, _ReadWriteLock_acquire, _ReadWriteLock_grant, _ReadWriteLock_release, _ReadWriteLock_drain;
+/**
+ * A read-write lock: multiple readers may hold the lock simultaneously,
+ * while writers hold it exclusively.
+ *
+ * Grant order is first-in-first-out, and the lock is write-preferring by
+ * default: a pending writer blocks new readers, and consecutive queued
+ * readers are granted together once the lock turns over to them. Set the
+ * `priority` option to `'read'` to let new readers join active readers even
+ * while a writer is queued — better read latency, at the cost that
+ * continuous reads can starve a queued writer. The lock is always released
+ * when the callback settles, whether it resolves or throws.
+ */
+export class ReadWriteLock {
+    /**
+     * @param options - Lock options.
+     * @param options.priority - Which mode takes priority when both are
+     * contended. Defaults to `'write'`.
+     */
+    constructor(options = {}) {
+        _ReadWriteLock_instances.add(this);
+        _ReadWriteLock_readerCount.set(this, 0);
+        _ReadWriteLock_writerActive.set(this, false);
+        _ReadWriteLock_waiters.set(this, []);
+        _ReadWriteLock_priority.set(this, void 0);
+        __classPrivateFieldSet(this, _ReadWriteLock_priority, options.priority ?? 'write', "f");
+    }
+    /**
+     * Run a read operation — parallel with other readers, exclusive with
+     * writers. New readers queue behind any pending writer.
+     *
+     * @param fn - The operation to run while holding the read lock.
+     * @returns Whatever `fn` resolves to.
+     */
+    async withReadLock(fn) {
+        return __classPrivateFieldGet(this, _ReadWriteLock_instances, "m", _ReadWriteLock_withLock).call(this, 'read', fn);
+    }
+    /**
+     * Run a write operation — exclusive with readers and other writers.
+     *
+     * @param fn - The operation to run while holding the write lock.
+     * @returns Whatever `fn` resolves to.
+     */
+    async withWriteLock(fn) {
+        return __classPrivateFieldGet(this, _ReadWriteLock_instances, "m", _ReadWriteLock_withLock).call(this, 'write', fn);
+    }
+}
+_ReadWriteLock_readerCount = new WeakMap(), _ReadWriteLock_writerActive = new WeakMap(), _ReadWriteLock_waiters = new WeakMap(), _ReadWriteLock_priority = new WeakMap(), _ReadWriteLock_instances = new WeakSet(), _ReadWriteLock_withLock = 
+/**
+ * Acquire the lock in the given mode, run the operation, and release the
+ * lock — including on a throw, so the lock can never leak.
+ *
+ * @param mode - The mode in which to hold the lock.
+ * @param fn - The operation to run while holding the lock.
+ * @returns Whatever `fn` resolves to.
+ */
+async function _ReadWriteLock_withLock(mode, fn) {
+    await __classPrivateFieldGet(this, _ReadWriteLock_instances, "m", _ReadWriteLock_acquire).call(this, mode);
+    try {
+        return await fn();
+    }
+    finally {
+        __classPrivateFieldGet(this, _ReadWriteLock_instances, "m", _ReadWriteLock_release).call(this, mode);
+    }
+}, _ReadWriteLock_hasWaiters = function _ReadWriteLock_hasWaiters() {
+    return __classPrivateFieldGet(this, _ReadWriteLock_waiters, "f").length > 0;
+}, _ReadWriteLock_isReading = function _ReadWriteLock_isReading() {
+    return __classPrivateFieldGet(this, _ReadWriteLock_readerCount, "f") > 0;
+}, _ReadWriteLock_isWriting = function _ReadWriteLock_isWriting() {
+    return __classPrivateFieldGet(this, _ReadWriteLock_writerActive, "f");
+}, _ReadWriteLock_acquire = 
+/**
+ * Acquire the lock in the given mode, queuing when it cannot be granted
+ * immediately.
+ *
+ * @param mode - The mode to acquire.
+ * @returns A promise that resolves once the lock is held.
+ */
+async function _ReadWriteLock_acquire(mode) {
+    return new Promise((resolve) => {
+        // Writing is exclusive, so we cannot acquire the lock if a writer is active.
+        const blockedByWriter = __classPrivateFieldGet(this, _ReadWriteLock_instances, "m", _ReadWriteLock_isWriting).call(this);
+        // Writing is exclusive with readers, so we cannot acquire the lock if any reader is active.
+        const blockedByReaders = mode === 'write' && __classPrivateFieldGet(this, _ReadWriteLock_instances, "m", _ReadWriteLock_isReading).call(this);
+        // We cannot acquire the lock for reading if there are waiters, unless priority is 'read'.
+        const blockedByWriterPriority = mode === 'read' && __classPrivateFieldGet(this, _ReadWriteLock_priority, "f") === 'write' && __classPrivateFieldGet(this, _ReadWriteLock_instances, "m", _ReadWriteLock_hasWaiters).call(this); // We might have pending write requests in the queue.
+        const acquire = !(blockedByWriter ||
+            blockedByReaders ||
+            blockedByWriterPriority);
+        if (acquire) {
+            __classPrivateFieldGet(this, _ReadWriteLock_instances, "m", _ReadWriteLock_grant).call(this, mode);
+            resolve();
+        }
+        else {
+            // We cannot grant the lock immediately, so we queue the waiter.
+            __classPrivateFieldGet(this, _ReadWriteLock_waiters, "f").push({ mode, resolve });
+        }
+    });
+}, _ReadWriteLock_grant = function _ReadWriteLock_grant(mode) {
+    if (mode === 'read') {
+        __classPrivateFieldSet(this, _ReadWriteLock_readerCount, __classPrivateFieldGet(this, _ReadWriteLock_readerCount, "f") + 1, "f");
+    }
+    else {
+        __classPrivateFieldSet(this, _ReadWriteLock_writerActive, true, "f");
+    }
+}, _ReadWriteLock_release = function _ReadWriteLock_release(mode) {
+    if (mode === 'read') {
+        __classPrivateFieldSet(this, _ReadWriteLock_readerCount, __classPrivateFieldGet(this, _ReadWriteLock_readerCount, "f") - 1, "f");
+    }
+    else {
+        __classPrivateFieldSet(this, _ReadWriteLock_writerActive, false, "f");
+    }
+    __classPrivateFieldGet(this, _ReadWriteLock_instances, "m", _ReadWriteLock_drain).call(this);
+}, _ReadWriteLock_drain = function _ReadWriteLock_drain() {
+    let waiter = __classPrivateFieldGet(this, _ReadWriteLock_waiters, "f").shift();
+    while (waiter !== undefined) {
+        // Writing is exclusive, so we cannot acquire the lock if a writer is active.
+        const blockedByWriter = __classPrivateFieldGet(this, _ReadWriteLock_instances, "m", _ReadWriteLock_isWriting).call(this);
+        // Reading blocks a writer, so we cannot acquire the lock for writing if any reader is active.
+        const blockedByReaders = waiter.mode === 'write' && __classPrivateFieldGet(this, _ReadWriteLock_instances, "m", _ReadWriteLock_isReading).call(this);
+        const acquire = !(blockedByWriter || blockedByReaders);
+        if (acquire) {
+            // Grant the front waiter and continue with the next one, so consecutive queued readers are granted together.
+            __classPrivateFieldGet(this, _ReadWriteLock_instances, "m", _ReadWriteLock_grant).call(this, waiter.mode);
+            waiter.resolve();
+            waiter = __classPrivateFieldGet(this, _ReadWriteLock_waiters, "f").shift();
+        }
+        else {
+            // The waiter is blocked by an active holder; put it back at the front and stop.
+            __classPrivateFieldGet(this, _ReadWriteLock_waiters, "f").unshift(waiter);
+            return;
+        }
+    }
+};
+//# sourceMappingURL=read-write-lock.mjs.map

package/dist/read-write-lock.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-write-lock.mjs","sourceRoot":"","sources":["../src/read-write-lock.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * A mode in which the lock can be held: shared (`'read'`) or exclusive\n * (`'write'`).\n */\ntype LockMode = 'read' | 'write';\n\n/**\n * A queued lock-acquisition request.\n */\ntype LockWaiter = {\n  /** The mode being acquired. */\n  mode: LockMode;\n  /** Resolves once the lock has been granted. */\n  resolve: () => void;\n};\n\n/**\n * Which mode a {@link ReadWriteLock} prioritizes when both are contended.\n */\nexport type ReadWriteLockPriority = 'read' | 'write';\n\n/**\n * Options for constructing a {@link ReadWriteLock}.\n */\nexport type ReadWriteLockOptions = {\n  /**\n   * Which mode takes priority when both are contended. Defaults to\n   * `'write'`.\n   *\n   * - `'write'`: a pending writer blocks new readers, so a steady stream of\n   * reads cannot starve a long write.\n   * - `'read'`: new readers join active readers even while a writer is\n   * queued, for better read latency — at the cost that a continuous stream\n   * of reads can starve a queued writer.\n   */\n  priority?: ReadWriteLockPriority;\n};\n\n/**\n * A read-write lock: multiple readers may hold the lock simultaneously,\n * while writers hold it exclusively.\n *\n * Grant order is first-in-first-out, and the lock is write-preferring by\n * default: a pending writer blocks new readers, and consecutive queued\n * readers are granted together once the lock turns over to them. Set the\n * `priority` option to `'read'` to let new readers join active readers even\n * while a writer is queued — better read latency, at the cost that\n * continuous reads can starve a queued writer. The lock is always released\n * when the callback settles, whether it resolves or throws.\n */\nexport class ReadWriteLock {\n  #readerCount: number = 0;\n\n  #writerActive: boolean = false;\n\n  readonly #waiters: LockWaiter[] = [];\n\n  readonly #priority: ReadWriteLockPriority;\n\n  /**\n   * @param options - Lock options.\n   * @param options.priority - Which mode takes priority when both are\n   * contended. Defaults to `'write'`.\n   */\n  constructor(options: ReadWriteLockOptions = {}) {\n    this.#priority = options.priority ?? 'write';\n  }\n\n  /**\n   * Run a read operation — parallel with other readers, exclusive with\n   * writers. New readers queue behind any pending writer.\n   *\n   * @param fn - The operation to run while holding the read lock.\n   * @returns Whatever `fn` resolves to.\n   */\n  async withReadLock<Result>(fn: () => Promise<Result>): Promise<Result> {\n    return this.#withLock('read', fn);\n  }\n\n  /**\n   * Run a write operation — exclusive with readers and other writers.\n   *\n   * @param fn - The operation to run while holding the write lock.\n   * @returns Whatever `fn` resolves to.\n   */\n  async withWriteLock<Result>(fn: () => Promise<Result>): Promise<Result> {\n    return this.#withLock('write', fn);\n  }\n\n  /**\n   * Acquire the lock in the given mode, run the operation, and release the\n   * lock — including on a throw, so the lock can never leak.\n   *\n   * @param mode - The mode in which to hold the lock.\n   * @param fn - The operation to run while holding the lock.\n   * @returns Whatever `fn` resolves to.\n   */\n  async #withLock<Result>(\n    mode: LockMode,\n    fn: () => Promise<Result>,\n  ): Promise<Result> {\n    await this.#acquire(mode);\n    try {\n      return await fn();\n    } finally {\n      this.#release(mode);\n    }\n  }\n\n  /**\n   * Whether any acquisition request is queued, waiting for the lock to turn\n   * over to it. A queued waiter always blocks newcomers, which keeps the\n   * grant order first-in-first-out.\n   *\n   * @returns Whether any acquisition request is queued.\n   */\n  #hasWaiters(): boolean {\n    return this.#waiters.length > 0;\n  }\n\n  /**\n   * Whether the lock is currently held for reading. Readers hold the lock\n   * in parallel, so this does not mean an exclusive hold.\n   *\n   * @returns Whether any reader is active.\n   */\n  #isReading(): boolean {\n    return this.#readerCount > 0;\n  }\n\n  /**\n   * Whether the lock is currently held for writing. A writer holds the lock\n   * exclusively: while writing, no other holder — reader or writer — can\n   * be active.\n   *\n   * @returns Whether a writer is active.\n   */\n  #isWriting(): boolean {\n    return this.#writerActive;\n  }\n\n  /**\n   * Acquire the lock in the given mode, queuing when it cannot be granted\n   * immediately.\n   *\n   * @param mode - The mode to acquire.\n   * @returns A promise that resolves once the lock is held.\n   */\n  async #acquire(mode: LockMode): Promise<void> {\n    return new Promise<void>((resolve) => {\n      // Writing is exclusive, so we cannot acquire the lock if a writer is active.\n      const blockedByWriter = this.#isWriting();\n      // Writing is exclusive with readers, so we cannot acquire the lock if any reader is active.\n      const blockedByReaders = mode === 'write' && this.#isReading();\n      // We cannot acquire the lock for reading if there are waiters, unless priority is 'read'.\n      const blockedByWriterPriority =\n        mode === 'read' && this.#priority === 'write' && this.#hasWaiters(); // We might have pending write requests in the queue.\n\n      const acquire = !(\n        blockedByWriter ||\n        blockedByReaders ||\n        blockedByWriterPriority\n      );\n\n      if (acquire) {\n        this.#grant(mode);\n        resolve();\n      } else {\n        // We cannot grant the lock immediately, so we queue the waiter.\n        this.#waiters.push({ mode, resolve });\n      }\n    });\n  }\n\n  /**\n   * Grant the lock in the given mode. Only called when the grant is legal.\n   *\n   * @param mode - The mode to grant.\n   */\n  #grant(mode: LockMode): void {\n    if (mode === 'read') {\n      this.#readerCount += 1;\n    } else {\n      this.#writerActive = true;\n    }\n  }\n\n  /**\n   * Release the lock in the given mode, then grant queued waiters in order.\n   *\n   * @param mode - The mode being released.\n   */\n  #release(mode: LockMode): void {\n    if (mode === 'read') {\n      this.#readerCount -= 1;\n    } else {\n      this.#writerActive = false;\n    }\n    this.#drain();\n  }\n\n  /**\n   * Grant queued waiters, in order, while the front of the queue can be\n   * granted. Consecutive queued readers are granted together; a granted\n   * writer blocks everything behind it. Unlike a newcomer, the front\n   * waiter is never blocked by queued waiters — everyone behind it\n   * arrived later — so only active holders block a grant here.\n   */\n  #drain(): void {\n    let waiter: LockWaiter | undefined = this.#waiters.shift();\n    while (waiter !== undefined) {\n      // Writing is exclusive, so we cannot acquire the lock if a writer is active.\n      const blockedByWriter = this.#isWriting();\n      // Reading blocks a writer, so we cannot acquire the lock for writing if any reader is active.\n      const blockedByReaders = waiter.mode === 'write' && this.#isReading();\n\n      const acquire = !(blockedByWriter || blockedByReaders);\n\n      if (acquire) {\n        // Grant the front waiter and continue with the next one, so consecutive queued readers are granted together.\n        this.#grant(waiter.mode);\n        waiter.resolve();\n        waiter = this.#waiters.shift();\n      } else {\n        // The waiter is blocked by an active holder; put it back at the front and stop.\n        this.#waiters.unshift(waiter);\n        return;\n      }\n    }\n  }\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metamask/keyring-sdk",
-  "version": "4.1.0",
+  "version": "4.2.0",
   "description": "MetaMask Keyring SDK",
   "keywords": [
     "keyring",