@metamask/keyring-api 21.3.0 → 21.5.0

package/dist/api/v2/wrapper/keyring-wrapper.cjs

@@ -0,0 +1,134 @@
+"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 _KeyringWrapper_capabilities, _KeyringWrapper_lock;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KeyringWrapper = void 0;
+const async_mutex_1 = require("async-mutex");
+const keyring_account_registry_1 = require("./keyring-account-registry.cjs");
+/**
+ * Generic adapter that turns an existing {@link Keyring} implementation into a
+ * {@link KeyringV2} instance.
+ *
+ * Consumers are expected to provide concrete mappings between high-level V2
+ * operations and the underlying keyring methods (for example BIP-44 account
+ * creation, private-key import, and request handling). This class focuses on
+ * the common mechanics required by all adapters: state serialization,
+ * account-ID/address mapping and basic account management.
+ */
+class KeyringWrapper {
+    constructor(options) {
+        _KeyringWrapper_capabilities.set(this, void 0);
+        /**
+         * Mutex to ensure exclusive access to the inner keyring during
+         * operations that mutate its state.
+         */
+        _KeyringWrapper_lock.set(this, new async_mutex_1.Mutex());
+        /**
+         * Registry for KeyringAccount objects.
+         * Provides O(1) lookups by AccountId or address.
+         *
+         * Subclasses should use this registry when creating accounts and
+         * clear/update it when deleting accounts or deserializing state.
+         */
+        this.registry = new keyring_account_registry_1.KeyringAccountRegistry();
+        this.inner = options.inner;
+        this.type = `${options.type}`;
+        __classPrivateFieldSet(this, _KeyringWrapper_capabilities, options.capabilities, "f");
+    }
+    /**
+     * Get the capabilities of this keyring.
+     *
+     * Subclasses can override this getter to return capabilities dynamically
+     * based on runtime state.
+     *
+     * @returns The keyring's capabilities.
+     */
+    get capabilities() {
+        return __classPrivateFieldGet(this, _KeyringWrapper_capabilities, "f");
+    }
+    /**
+     * Execute an operation with exclusive access to the inner keyring.
+     *
+     * This method ensures thread-safety for operations that read or mutate
+     * the inner keyring state. All operations that modify the keyring
+     * (createAccounts, deleteAccount, deserialize) should use this method
+     * to prevent race conditions.
+     *
+     * Within the callback, use `this.inner` to access the inner keyring.
+     *
+     * @param callback - A function that performs the operation.
+     * @returns The result of the callback.
+     */
+    async withLock(callback) {
+        return __classPrivateFieldGet(this, _KeyringWrapper_lock, "f").runExclusive(callback);
+    }
+    /**
+     * Serialize the underlying keyring state to a JSON-serializable object.
+     *
+     * This simply delegates to the legacy keyring's {@link Keyring.serialize}
+     * implementation.
+     *
+     * @returns The serialized keyring state.
+     */
+    async serialize() {
+        return this.inner.serialize();
+    }
+    /**
+     * Hydrate the underlying keyring from a previously serialized state.
+     *
+     * This clears the registry, delegates to the legacy keyring's
+     * {@link Keyring.deserialize} implementation, and rebuilds the registry
+     * by calling {@link getAccounts}.
+     *
+     * @param state - The serialized keyring state.
+     */
+    async deserialize(state) {
+        await this.withLock(async () => {
+            // Clear the registry when deserializing
+            this.registry.clear();
+            // Deserialize the legacy keyring
+            await this.inner.deserialize(state);
+            // Rebuild the registry by calling getAccounts().
+            // Subclass implementations of getAccounts() should populate the registry
+            // as a side effect (see the abstract method's documentation).
+            await this.getAccounts();
+        });
+    }
+    /**
+     * Look up a single account by its {@link AccountId}.
+     *
+     * This method first checks the registry for O(1) lookup.
+     * If not found, it falls back to calling {@link getAccounts} which
+     * should populate the registry as a side effect.
+     *
+     * @param accountId - The AccountId to look up.
+     * @returns The matching KeyringAccount.
+     */
+    async getAccount(accountId) {
+        let cached = this.registry.get(accountId);
+        if (cached) {
+            return cached;
+        }
+        // Prime the registry by calling getAccounts
+        await this.getAccounts();
+        // Try registry again after priming
+        cached = this.registry.get(accountId);
+        if (!cached) {
+            throw new Error(`Account not found for id: ${accountId}`);
+        }
+        return cached;
+    }
+}
+exports.KeyringWrapper = KeyringWrapper;
+_KeyringWrapper_capabilities = new WeakMap(), _KeyringWrapper_lock = new WeakMap();
+//# sourceMappingURL=keyring-wrapper.cjs.map

package/dist/api/v2/wrapper/keyring-wrapper.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyring-wrapper.cjs","sourceRoot":"","sources":["../../../../src/api/v2/wrapper/keyring-wrapper.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;AAEA,6CAAoC;AAEpC,6EAAoE;AAgCpE;;;;;;;;;GASG;AACH,MAAsB,cAAc;IA2BlC,YAAY,OAA4C;QApB/C,+CAAmC;QAI5C;;;WAGG;QACM,+BAAQ,IAAI,mBAAK,EAAE,EAAC;QAE7B;;;;;;WAMG;QACgB,aAAQ,GACzB,IAAI,iDAAsB,EAAsB,CAAC;QAGjD,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;QAC3B,IAAI,CAAC,IAAI,GAAG,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;QAC9B,uBAAA,IAAI,gCAAiB,OAAO,CAAC,YAAY,MAAA,CAAC;IAC5C,CAAC;IAED;;;;;;;OAOG;IACH,IAAI,YAAY;QACd,OAAO,uBAAA,IAAI,oCAAc,CAAC;IAC5B,CAAC;IAED;;;;;;;;;;;;OAYG;IACO,KAAK,CAAC,QAAQ,CACtB,QAA+B;QAE/B,OAAO,uBAAA,IAAI,4BAAM,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC;IAC3C,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,SAAS;QACb,OAAO,IAAI,CAAC,KAAK,CAAC,SAAS,EAAE,CAAC;IAChC,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,WAAW,CAAC,KAAW;QAC3B,MAAM,IAAI,CAAC,QAAQ,CAAC,KAAK,IAAI,EAAE;YAC7B,wCAAwC;YACxC,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC;YAEtB,iCAAiC;YACjC,MAAM,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;YAEpC,iDAAiD;YACjD,yEAAyE;YACzE,8DAA8D;YAC9D,MAAM,IAAI,CAAC,WAAW,EAAE,CAAC;QAC3B,CAAC,CAAC,CAAC;IACL,CAAC;IAgBD;;;;;;;;;OASG;IACH,KAAK,CAAC,UAAU,CAAC,SAAoB;QACnC,IAAI,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAC1C,IAAI,MAAM,EAAE,CAAC;YACX,OAAO,MAAM,CAAC;QAChB,CAAC;QAED,4CAA4C;QAC5C,MAAM,IAAI,CAAC,WAAW,EAAE,CAAC;QAEzB,mCAAmC;QACnC,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QACtC,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CAAC,6BAA6B,SAAS,EAAE,CAAC,CAAC;QAC5D,CAAC;QAED,OAAO,MAAM,CAAC;IAChB,CAAC;CA+CF;AA3LD,wCA2LC","sourcesContent":["import type { Keyring, AccountId } from '@metamask/keyring-utils';\nimport type { Json } from '@metamask/utils';\nimport { Mutex } from 'async-mutex';\n\nimport { KeyringAccountRegistry } from './keyring-account-registry';\nimport type {\n  CreateAccountOptions,\n  ExportAccountOptions,\n  ExportedAccount,\n} from '..';\nimport type { KeyringAccount } from '../../account';\nimport type { KeyringRequest } from '../../request';\nimport type { KeyringV2 } from '../keyring';\nimport type { KeyringCapabilities } from '../keyring-capabilities';\nimport type { KeyringType } from '../keyring-type';\n\n/**\n * Basic options for constructing a {@link KeyringWrapper}.\n */\nexport type KeyringWrapperOptions<InnerKeyring extends Keyring> = {\n  /**\n   * The underlying \"old\" keyring instance that this wrapper adapts.\n   */\n  inner: InnerKeyring;\n\n  /**\n   * The concrete keyring type exposed through the V2 interface.\n   */\n  type: KeyringType;\n\n  /**\n   * Capabilities of the underlying keyring.\n   */\n  capabilities: KeyringCapabilities;\n};\n\n/**\n * Generic adapter that turns an existing {@link Keyring} implementation into a\n * {@link KeyringV2} instance.\n *\n * Consumers are expected to provide concrete mappings between high-level V2\n * operations and the underlying keyring methods (for example BIP-44 account\n * creation, private-key import, and request handling). This class focuses on\n * the common mechanics required by all adapters: state serialization,\n * account-ID/address mapping and basic account management.\n */\nexport abstract class KeyringWrapper<\n  InnerKeyring extends Keyring,\n  KeyringAccountType extends KeyringAccount = KeyringAccount,\n> implements KeyringV2\n{\n  readonly type: `${KeyringType}`;\n\n  readonly #capabilities: KeyringCapabilities;\n\n  protected readonly inner: InnerKeyring;\n\n  /**\n   * Mutex to ensure exclusive access to the inner keyring during\n   * operations that mutate its state.\n   */\n  readonly #lock = new Mutex();\n\n  /**\n   * Registry for KeyringAccount objects.\n   * Provides O(1) lookups by AccountId or address.\n   *\n   * Subclasses should use this registry when creating accounts and\n   * clear/update it when deleting accounts or deserializing state.\n   */\n  protected readonly registry =\n    new KeyringAccountRegistry<KeyringAccountType>();\n\n  constructor(options: KeyringWrapperOptions<InnerKeyring>) {\n    this.inner = options.inner;\n    this.type = `${options.type}`;\n    this.#capabilities = options.capabilities;\n  }\n\n  /**\n   * Get the capabilities of this keyring.\n   *\n   * Subclasses can override this getter to return capabilities dynamically\n   * based on runtime state.\n   *\n   * @returns The keyring's capabilities.\n   */\n  get capabilities(): KeyringCapabilities {\n    return this.#capabilities;\n  }\n\n  /**\n   * Execute an operation with exclusive access to the inner keyring.\n   *\n   * This method ensures thread-safety for operations that read or mutate\n   * the inner keyring state. All operations that modify the keyring\n   * (createAccounts, deleteAccount, deserialize) should use this method\n   * to prevent race conditions.\n   *\n   * Within the callback, use `this.inner` to access the inner keyring.\n   *\n   * @param callback - A function that performs the operation.\n   * @returns The result of the callback.\n   */\n  protected async withLock<Result>(\n    callback: () => Promise<Result>,\n  ): Promise<Result> {\n    return this.#lock.runExclusive(callback);\n  }\n\n  /**\n   * Serialize the underlying keyring state to a JSON-serializable object.\n   *\n   * This simply delegates to the legacy keyring's {@link Keyring.serialize}\n   * implementation.\n   *\n   * @returns The serialized keyring state.\n   */\n  async serialize(): Promise<Json> {\n    return this.inner.serialize();\n  }\n\n  /**\n   * Hydrate the underlying keyring from a previously serialized state.\n   *\n   * This clears the registry, delegates to the legacy keyring's\n   * {@link Keyring.deserialize} implementation, and rebuilds the registry\n   * by calling {@link getAccounts}.\n   *\n   * @param state - The serialized keyring state.\n   */\n  async deserialize(state: Json): Promise<void> {\n    await this.withLock(async () => {\n      // Clear the registry when deserializing\n      this.registry.clear();\n\n      // Deserialize the legacy keyring\n      await this.inner.deserialize(state);\n\n      // Rebuild the registry by calling getAccounts().\n      // Subclass implementations of getAccounts() should populate the registry\n      // as a side effect (see the abstract method's documentation).\n      await this.getAccounts();\n    });\n  }\n\n  /**\n   * Return all accounts managed by this keyring.\n   *\n   * Concrete adapters are responsible for mapping the underlying keyring's\n   * notion of accounts (typically addresses returned by\n   * {@link Keyring.getAccounts}) into {@link KeyringAccount} objects.\n   * Implementations should use the configured {@link KeyringAccountRegistry}\n   * to establish the account ID/address mapping so that\n   * {@link getAccount} works as expected.\n   *\n   * @returns The list of managed accounts.\n   */\n  abstract getAccounts(): Promise<KeyringAccount[]>;\n\n  /**\n   * Look up a single account by its {@link AccountId}.\n   *\n   * This method first checks the registry for O(1) lookup.\n   * If not found, it falls back to calling {@link getAccounts} which\n   * should populate the registry as a side effect.\n   *\n   * @param accountId - The AccountId to look up.\n   * @returns The matching KeyringAccount.\n   */\n  async getAccount(accountId: AccountId): Promise<KeyringAccount> {\n    let cached = this.registry.get(accountId);\n    if (cached) {\n      return cached;\n    }\n\n    // Prime the registry by calling getAccounts\n    await this.getAccounts();\n\n    // Try registry again after priming\n    cached = this.registry.get(accountId);\n    if (!cached) {\n      throw new Error(`Account not found for id: ${accountId}`);\n    }\n\n    return cached;\n  }\n\n  /**\n   * Create one or more new accounts managed by this keyring.\n   *\n   * Implementations are responsible for interpreting the\n   * {@link CreateAccountOptions} (for example BIP-44 derivation or\n   * private-key import) and returning the resulting {@link KeyringAccount}\n   * objects. Implementors should also ensure that the registry is updated so\n   * that {@link getAccount} works for newly created accounts.\n   */\n  abstract createAccounts(\n    options: CreateAccountOptions,\n  ): Promise<KeyringAccount[]>;\n\n  /**\n   * Remove the account associated with the given {@link AccountId} from this\n   * keyring.\n   *\n   * Implementations are expected to translate the ID to an underlying\n   * address (typically via the registry) and then invoke the appropriate\n   * removal mechanism on the legacy keyring.\n   */\n  abstract deleteAccount(accountId: AccountId): Promise<void>;\n\n  /**\n   * Export the secrets associated with the given account in a format\n   * described by {@link ExportAccountOptions}.\n   *\n   * This method is optional, and concrete adapters should only\n   * implement it if the underlying keyring supports exporting\n   * accounts.\n   */\n  exportAccount?(\n    accountId: AccountId,\n    options?: ExportAccountOptions,\n  ): Promise<ExportedAccount>;\n\n  /**\n   * Handle a high-level {@link KeyringRequest} on behalf of this keyring.\n   *\n   * Concrete adapters are responsible for routing the request's method and\n   * parameters to the appropriate legacy keyring APIs (for example signing\n   * transactions or decrypting messages) and returning a JSON-serializable\n   * result.\n   */\n  abstract submitRequest(request: KeyringRequest): Promise<Json>;\n}\n"]}

package/dist/api/v2/wrapper/keyring-wrapper.d.cts

@@ -0,0 +1,154 @@
+import type { Keyring, AccountId } from "@metamask/keyring-utils";
+import type { Json } from "@metamask/utils";
+import { KeyringAccountRegistry } from "./keyring-account-registry.cjs";
+import type { CreateAccountOptions, ExportAccountOptions, ExportedAccount } from "../index.cjs";
+import type { KeyringAccount } from "../../account.cjs";
+import type { KeyringRequest } from "../../request.cjs";
+import type { KeyringV2 } from "../keyring.cjs";
+import type { KeyringCapabilities } from "../keyring-capabilities.cjs";
+import type { KeyringType } from "../keyring-type.cjs";
+/**
+ * Basic options for constructing a {@link KeyringWrapper}.
+ */
+export type KeyringWrapperOptions<InnerKeyring extends Keyring> = {
+    /**
+     * The underlying "old" keyring instance that this wrapper adapts.
+     */
+    inner: InnerKeyring;
+    /**
+     * The concrete keyring type exposed through the V2 interface.
+     */
+    type: KeyringType;
+    /**
+     * Capabilities of the underlying keyring.
+     */
+    capabilities: KeyringCapabilities;
+};
+/**
+ * Generic adapter that turns an existing {@link Keyring} implementation into a
+ * {@link KeyringV2} instance.
+ *
+ * Consumers are expected to provide concrete mappings between high-level V2
+ * operations and the underlying keyring methods (for example BIP-44 account
+ * creation, private-key import, and request handling). This class focuses on
+ * the common mechanics required by all adapters: state serialization,
+ * account-ID/address mapping and basic account management.
+ */
+export declare abstract class KeyringWrapper<InnerKeyring extends Keyring, KeyringAccountType extends KeyringAccount = KeyringAccount> implements KeyringV2 {
+    #private;
+    readonly type: `${KeyringType}`;
+    protected readonly inner: InnerKeyring;
+    /**
+     * Registry for KeyringAccount objects.
+     * Provides O(1) lookups by AccountId or address.
+     *
+     * Subclasses should use this registry when creating accounts and
+     * clear/update it when deleting accounts or deserializing state.
+     */
+    protected readonly registry: KeyringAccountRegistry<KeyringAccountType>;
+    constructor(options: KeyringWrapperOptions<InnerKeyring>);
+    /**
+     * Get the capabilities of this keyring.
+     *
+     * Subclasses can override this getter to return capabilities dynamically
+     * based on runtime state.
+     *
+     * @returns The keyring's capabilities.
+     */
+    get capabilities(): KeyringCapabilities;
+    /**
+     * Execute an operation with exclusive access to the inner keyring.
+     *
+     * This method ensures thread-safety for operations that read or mutate
+     * the inner keyring state. All operations that modify the keyring
+     * (createAccounts, deleteAccount, deserialize) should use this method
+     * to prevent race conditions.
+     *
+     * Within the callback, use `this.inner` to access the inner keyring.
+     *
+     * @param callback - A function that performs the operation.
+     * @returns The result of the callback.
+     */
+    protected withLock<Result>(callback: () => Promise<Result>): Promise<Result>;
+    /**
+     * Serialize the underlying keyring state to a JSON-serializable object.
+     *
+     * This simply delegates to the legacy keyring's {@link Keyring.serialize}
+     * implementation.
+     *
+     * @returns The serialized keyring state.
+     */
+    serialize(): Promise<Json>;
+    /**
+     * Hydrate the underlying keyring from a previously serialized state.
+     *
+     * This clears the registry, delegates to the legacy keyring's
+     * {@link Keyring.deserialize} implementation, and rebuilds the registry
+     * by calling {@link getAccounts}.
+     *
+     * @param state - The serialized keyring state.
+     */
+    deserialize(state: Json): Promise<void>;
+    /**
+     * Return all accounts managed by this keyring.
+     *
+     * Concrete adapters are responsible for mapping the underlying keyring's
+     * notion of accounts (typically addresses returned by
+     * {@link Keyring.getAccounts}) into {@link KeyringAccount} objects.
+     * Implementations should use the configured {@link KeyringAccountRegistry}
+     * to establish the account ID/address mapping so that
+     * {@link getAccount} works as expected.
+     *
+     * @returns The list of managed accounts.
+     */
+    abstract getAccounts(): Promise<KeyringAccount[]>;
+    /**
+     * Look up a single account by its {@link AccountId}.
+     *
+     * This method first checks the registry for O(1) lookup.
+     * If not found, it falls back to calling {@link getAccounts} which
+     * should populate the registry as a side effect.
+     *
+     * @param accountId - The AccountId to look up.
+     * @returns The matching KeyringAccount.
+     */
+    getAccount(accountId: AccountId): Promise<KeyringAccount>;
+    /**
+     * Create one or more new accounts managed by this keyring.
+     *
+     * Implementations are responsible for interpreting the
+     * {@link CreateAccountOptions} (for example BIP-44 derivation or
+     * private-key import) and returning the resulting {@link KeyringAccount}
+     * objects. Implementors should also ensure that the registry is updated so
+     * that {@link getAccount} works for newly created accounts.
+     */
+    abstract createAccounts(options: CreateAccountOptions): Promise<KeyringAccount[]>;
+    /**
+     * Remove the account associated with the given {@link AccountId} from this
+     * keyring.
+     *
+     * Implementations are expected to translate the ID to an underlying
+     * address (typically via the registry) and then invoke the appropriate
+     * removal mechanism on the legacy keyring.
+     */
+    abstract deleteAccount(accountId: AccountId): Promise<void>;
+    /**
+     * Export the secrets associated with the given account in a format
+     * described by {@link ExportAccountOptions}.
+     *
+     * This method is optional, and concrete adapters should only
+     * implement it if the underlying keyring supports exporting
+     * accounts.
+     */
+    exportAccount?(accountId: AccountId, options?: ExportAccountOptions): Promise<ExportedAccount>;
+    /**
+     * Handle a high-level {@link KeyringRequest} on behalf of this keyring.
+     *
+     * Concrete adapters are responsible for routing the request's method and
+     * parameters to the appropriate legacy keyring APIs (for example signing
+     * transactions or decrypting messages) and returning a JSON-serializable
+     * result.
+     */
+    abstract submitRequest(request: KeyringRequest): Promise<Json>;
+}
+//# sourceMappingURL=keyring-wrapper.d.cts.map

package/dist/api/v2/wrapper/keyring-wrapper.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyring-wrapper.d.cts","sourceRoot":"","sources":["../../../../src/api/v2/wrapper/keyring-wrapper.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,gCAAgC;AAClE,OAAO,KAAK,EAAE,IAAI,EAAE,wBAAwB;AAG5C,OAAO,EAAE,sBAAsB,EAAE,uCAAmC;AACpE,OAAO,KAAK,EACV,oBAAoB,EACpB,oBAAoB,EACpB,eAAe,EAChB,qBAAW;AACZ,OAAO,KAAK,EAAE,cAAc,EAAE,0BAAsB;AACpD,OAAO,KAAK,EAAE,cAAc,EAAE,0BAAsB;AACpD,OAAO,KAAK,EAAE,SAAS,EAAE,uBAAmB;AAC5C,OAAO,KAAK,EAAE,mBAAmB,EAAE,oCAAgC;AACnE,OAAO,KAAK,EAAE,WAAW,EAAE,4BAAwB;AAEnD;;GAEG;AACH,MAAM,MAAM,qBAAqB,CAAC,YAAY,SAAS,OAAO,IAAI;IAChE;;OAEG;IACH,KAAK,EAAE,YAAY,CAAC;IAEpB;;OAEG;IACH,IAAI,EAAE,WAAW,CAAC;IAElB;;OAEG;IACH,YAAY,EAAE,mBAAmB,CAAC;CACnC,CAAC;AAEF;;;;;;;;;GASG;AACH,8BAAsB,cAAc,CAClC,YAAY,SAAS,OAAO,EAC5B,kBAAkB,SAAS,cAAc,GAAG,cAAc,CAC1D,YAAW,SAAS;;IAEpB,QAAQ,CAAC,IAAI,EAAE,GAAG,WAAW,EAAE,CAAC;IAIhC,SAAS,CAAC,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAQvC;;;;;;OAMG;IACH,SAAS,CAAC,QAAQ,CAAC,QAAQ,6CACwB;gBAEvC,OAAO,EAAE,qBAAqB,CAAC,YAAY,CAAC;IAMxD;;;;;;;OAOG;IACH,IAAI,YAAY,IAAI,mBAAmB,CAEtC;IAED;;;;;;;;;;;;OAYG;cACa,QAAQ,CAAC,MAAM,EAC7B,QAAQ,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,GAC9B,OAAO,CAAC,MAAM,CAAC;IAIlB;;;;;;;OAOG;IACG,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAIhC;;;;;;;;OAQG;IACG,WAAW,CAAC,KAAK,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAe7C;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,WAAW,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC;IAEjD;;;;;;;;;OASG;IACG,UAAU,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,cAAc,CAAC;IAkB/D;;;;;;;;OAQG;IACH,QAAQ,CAAC,cAAc,CACrB,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,cAAc,EAAE,CAAC;IAE5B;;;;;;;OAOG;IACH,QAAQ,CAAC,aAAa,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAE3D;;;;;;;OAOG;IACH,aAAa,CAAC,CACZ,SAAS,EAAE,SAAS,EACpB,OAAO,CAAC,EAAE,oBAAoB,GAC7B,OAAO,CAAC,eAAe,CAAC;IAE3B;;;;;;;OAOG;IACH,QAAQ,CAAC,aAAa,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;CAC/D"}

package/dist/api/v2/wrapper/keyring-wrapper.d.mts

@@ -0,0 +1,154 @@
+import type { Keyring, AccountId } from "@metamask/keyring-utils";
+import type { Json } from "@metamask/utils";
+import { KeyringAccountRegistry } from "./keyring-account-registry.mjs";
+import type { CreateAccountOptions, ExportAccountOptions, ExportedAccount } from "../index.mjs";
+import type { KeyringAccount } from "../../account.mjs";
+import type { KeyringRequest } from "../../request.mjs";
+import type { KeyringV2 } from "../keyring.mjs";
+import type { KeyringCapabilities } from "../keyring-capabilities.mjs";
+import type { KeyringType } from "../keyring-type.mjs";
+/**
+ * Basic options for constructing a {@link KeyringWrapper}.
+ */
+export type KeyringWrapperOptions<InnerKeyring extends Keyring> = {
+    /**
+     * The underlying "old" keyring instance that this wrapper adapts.
+     */
+    inner: InnerKeyring;
+    /**
+     * The concrete keyring type exposed through the V2 interface.
+     */
+    type: KeyringType;
+    /**
+     * Capabilities of the underlying keyring.
+     */
+    capabilities: KeyringCapabilities;
+};
+/**
+ * Generic adapter that turns an existing {@link Keyring} implementation into a
+ * {@link KeyringV2} instance.
+ *
+ * Consumers are expected to provide concrete mappings between high-level V2
+ * operations and the underlying keyring methods (for example BIP-44 account
+ * creation, private-key import, and request handling). This class focuses on
+ * the common mechanics required by all adapters: state serialization,
+ * account-ID/address mapping and basic account management.
+ */
+export declare abstract class KeyringWrapper<InnerKeyring extends Keyring, KeyringAccountType extends KeyringAccount = KeyringAccount> implements KeyringV2 {
+    #private;
+    readonly type: `${KeyringType}`;
+    protected readonly inner: InnerKeyring;
+    /**
+     * Registry for KeyringAccount objects.
+     * Provides O(1) lookups by AccountId or address.
+     *
+     * Subclasses should use this registry when creating accounts and
+     * clear/update it when deleting accounts or deserializing state.
+     */
+    protected readonly registry: KeyringAccountRegistry<KeyringAccountType>;
+    constructor(options: KeyringWrapperOptions<InnerKeyring>);
+    /**
+     * Get the capabilities of this keyring.
+     *
+     * Subclasses can override this getter to return capabilities dynamically
+     * based on runtime state.
+     *
+     * @returns The keyring's capabilities.
+     */
+    get capabilities(): KeyringCapabilities;
+    /**
+     * Execute an operation with exclusive access to the inner keyring.
+     *
+     * This method ensures thread-safety for operations that read or mutate
+     * the inner keyring state. All operations that modify the keyring
+     * (createAccounts, deleteAccount, deserialize) should use this method
+     * to prevent race conditions.
+     *
+     * Within the callback, use `this.inner` to access the inner keyring.
+     *
+     * @param callback - A function that performs the operation.
+     * @returns The result of the callback.
+     */
+    protected withLock<Result>(callback: () => Promise<Result>): Promise<Result>;
+    /**
+     * Serialize the underlying keyring state to a JSON-serializable object.
+     *
+     * This simply delegates to the legacy keyring's {@link Keyring.serialize}
+     * implementation.
+     *
+     * @returns The serialized keyring state.
+     */
+    serialize(): Promise<Json>;
+    /**
+     * Hydrate the underlying keyring from a previously serialized state.
+     *
+     * This clears the registry, delegates to the legacy keyring's
+     * {@link Keyring.deserialize} implementation, and rebuilds the registry
+     * by calling {@link getAccounts}.
+     *
+     * @param state - The serialized keyring state.
+     */
+    deserialize(state: Json): Promise<void>;
+    /**
+     * Return all accounts managed by this keyring.
+     *
+     * Concrete adapters are responsible for mapping the underlying keyring's
+     * notion of accounts (typically addresses returned by
+     * {@link Keyring.getAccounts}) into {@link KeyringAccount} objects.
+     * Implementations should use the configured {@link KeyringAccountRegistry}
+     * to establish the account ID/address mapping so that
+     * {@link getAccount} works as expected.
+     *
+     * @returns The list of managed accounts.
+     */
+    abstract getAccounts(): Promise<KeyringAccount[]>;
+    /**
+     * Look up a single account by its {@link AccountId}.
+     *
+     * This method first checks the registry for O(1) lookup.
+     * If not found, it falls back to calling {@link getAccounts} which
+     * should populate the registry as a side effect.
+     *
+     * @param accountId - The AccountId to look up.
+     * @returns The matching KeyringAccount.
+     */
+    getAccount(accountId: AccountId): Promise<KeyringAccount>;
+    /**
+     * Create one or more new accounts managed by this keyring.
+     *
+     * Implementations are responsible for interpreting the
+     * {@link CreateAccountOptions} (for example BIP-44 derivation or
+     * private-key import) and returning the resulting {@link KeyringAccount}
+     * objects. Implementors should also ensure that the registry is updated so
+     * that {@link getAccount} works for newly created accounts.
+     */
+    abstract createAccounts(options: CreateAccountOptions): Promise<KeyringAccount[]>;
+    /**
+     * Remove the account associated with the given {@link AccountId} from this
+     * keyring.
+     *
+     * Implementations are expected to translate the ID to an underlying
+     * address (typically via the registry) and then invoke the appropriate
+     * removal mechanism on the legacy keyring.
+     */
+    abstract deleteAccount(accountId: AccountId): Promise<void>;
+    /**
+     * Export the secrets associated with the given account in a format
+     * described by {@link ExportAccountOptions}.
+     *
+     * This method is optional, and concrete adapters should only
+     * implement it if the underlying keyring supports exporting
+     * accounts.
+     */
+    exportAccount?(accountId: AccountId, options?: ExportAccountOptions): Promise<ExportedAccount>;
+    /**
+     * Handle a high-level {@link KeyringRequest} on behalf of this keyring.
+     *
+     * Concrete adapters are responsible for routing the request's method and
+     * parameters to the appropriate legacy keyring APIs (for example signing
+     * transactions or decrypting messages) and returning a JSON-serializable
+     * result.
+     */
+    abstract submitRequest(request: KeyringRequest): Promise<Json>;
+}
+//# sourceMappingURL=keyring-wrapper.d.mts.map

package/dist/api/v2/wrapper/keyring-wrapper.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyring-wrapper.d.mts","sourceRoot":"","sources":["../../../../src/api/v2/wrapper/keyring-wrapper.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,gCAAgC;AAClE,OAAO,KAAK,EAAE,IAAI,EAAE,wBAAwB;AAG5C,OAAO,EAAE,sBAAsB,EAAE,uCAAmC;AACpE,OAAO,KAAK,EACV,oBAAoB,EACpB,oBAAoB,EACpB,eAAe,EAChB,qBAAW;AACZ,OAAO,KAAK,EAAE,cAAc,EAAE,0BAAsB;AACpD,OAAO,KAAK,EAAE,cAAc,EAAE,0BAAsB;AACpD,OAAO,KAAK,EAAE,SAAS,EAAE,uBAAmB;AAC5C,OAAO,KAAK,EAAE,mBAAmB,EAAE,oCAAgC;AACnE,OAAO,KAAK,EAAE,WAAW,EAAE,4BAAwB;AAEnD;;GAEG;AACH,MAAM,MAAM,qBAAqB,CAAC,YAAY,SAAS,OAAO,IAAI;IAChE;;OAEG;IACH,KAAK,EAAE,YAAY,CAAC;IAEpB;;OAEG;IACH,IAAI,EAAE,WAAW,CAAC;IAElB;;OAEG;IACH,YAAY,EAAE,mBAAmB,CAAC;CACnC,CAAC;AAEF;;;;;;;;;GASG;AACH,8BAAsB,cAAc,CAClC,YAAY,SAAS,OAAO,EAC5B,kBAAkB,SAAS,cAAc,GAAG,cAAc,CAC1D,YAAW,SAAS;;IAEpB,QAAQ,CAAC,IAAI,EAAE,GAAG,WAAW,EAAE,CAAC;IAIhC,SAAS,CAAC,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAQvC;;;;;;OAMG;IACH,SAAS,CAAC,QAAQ,CAAC,QAAQ,6CACwB;gBAEvC,OAAO,EAAE,qBAAqB,CAAC,YAAY,CAAC;IAMxD;;;;;;;OAOG;IACH,IAAI,YAAY,IAAI,mBAAmB,CAEtC;IAED;;;;;;;;;;;;OAYG;cACa,QAAQ,CAAC,MAAM,EAC7B,QAAQ,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,GAC9B,OAAO,CAAC,MAAM,CAAC;IAIlB;;;;;;;OAOG;IACG,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAIhC;;;;;;;;OAQG;IACG,WAAW,CAAC,KAAK,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAe7C;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,WAAW,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC;IAEjD;;;;;;;;;OASG;IACG,UAAU,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,cAAc,CAAC;IAkB/D;;;;;;;;OAQG;IACH,QAAQ,CAAC,cAAc,CACrB,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,cAAc,EAAE,CAAC;IAE5B;;;;;;;OAOG;IACH,QAAQ,CAAC,aAAa,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAE3D;;;;;;;OAOG;IACH,aAAa,CAAC,CACZ,SAAS,EAAE,SAAS,EACpB,OAAO,CAAC,EAAE,oBAAoB,GAC7B,OAAO,CAAC,eAAe,CAAC;IAE3B;;;;;;;OAOG;IACH,QAAQ,CAAC,aAAa,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;CAC/D"}

package/dist/api/v2/wrapper/keyring-wrapper.mjs

@@ -0,0 +1,130 @@
+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 _KeyringWrapper_capabilities, _KeyringWrapper_lock;
+import { Mutex } from "async-mutex";
+import { KeyringAccountRegistry } from "./keyring-account-registry.mjs";
+/**
+ * Generic adapter that turns an existing {@link Keyring} implementation into a
+ * {@link KeyringV2} instance.
+ *
+ * Consumers are expected to provide concrete mappings between high-level V2
+ * operations and the underlying keyring methods (for example BIP-44 account
+ * creation, private-key import, and request handling). This class focuses on
+ * the common mechanics required by all adapters: state serialization,
+ * account-ID/address mapping and basic account management.
+ */
+export class KeyringWrapper {
+    constructor(options) {
+        _KeyringWrapper_capabilities.set(this, void 0);
+        /**
+         * Mutex to ensure exclusive access to the inner keyring during
+         * operations that mutate its state.
+         */
+        _KeyringWrapper_lock.set(this, new Mutex());
+        /**
+         * Registry for KeyringAccount objects.
+         * Provides O(1) lookups by AccountId or address.
+         *
+         * Subclasses should use this registry when creating accounts and
+         * clear/update it when deleting accounts or deserializing state.
+         */
+        this.registry = new KeyringAccountRegistry();
+        this.inner = options.inner;
+        this.type = `${options.type}`;
+        __classPrivateFieldSet(this, _KeyringWrapper_capabilities, options.capabilities, "f");
+    }
+    /**
+     * Get the capabilities of this keyring.
+     *
+     * Subclasses can override this getter to return capabilities dynamically
+     * based on runtime state.
+     *
+     * @returns The keyring's capabilities.
+     */
+    get capabilities() {
+        return __classPrivateFieldGet(this, _KeyringWrapper_capabilities, "f");
+    }
+    /**
+     * Execute an operation with exclusive access to the inner keyring.
+     *
+     * This method ensures thread-safety for operations that read or mutate
+     * the inner keyring state. All operations that modify the keyring
+     * (createAccounts, deleteAccount, deserialize) should use this method
+     * to prevent race conditions.
+     *
+     * Within the callback, use `this.inner` to access the inner keyring.
+     *
+     * @param callback - A function that performs the operation.
+     * @returns The result of the callback.
+     */
+    async withLock(callback) {
+        return __classPrivateFieldGet(this, _KeyringWrapper_lock, "f").runExclusive(callback);
+    }
+    /**
+     * Serialize the underlying keyring state to a JSON-serializable object.
+     *
+     * This simply delegates to the legacy keyring's {@link Keyring.serialize}
+     * implementation.
+     *
+     * @returns The serialized keyring state.
+     */
+    async serialize() {
+        return this.inner.serialize();
+    }
+    /**
+     * Hydrate the underlying keyring from a previously serialized state.
+     *
+     * This clears the registry, delegates to the legacy keyring's
+     * {@link Keyring.deserialize} implementation, and rebuilds the registry
+     * by calling {@link getAccounts}.
+     *
+     * @param state - The serialized keyring state.
+     */
+    async deserialize(state) {
+        await this.withLock(async () => {
+            // Clear the registry when deserializing
+            this.registry.clear();
+            // Deserialize the legacy keyring
+            await this.inner.deserialize(state);
+            // Rebuild the registry by calling getAccounts().
+            // Subclass implementations of getAccounts() should populate the registry
+            // as a side effect (see the abstract method's documentation).
+            await this.getAccounts();
+        });
+    }
+    /**
+     * Look up a single account by its {@link AccountId}.
+     *
+     * This method first checks the registry for O(1) lookup.
+     * If not found, it falls back to calling {@link getAccounts} which
+     * should populate the registry as a side effect.
+     *
+     * @param accountId - The AccountId to look up.
+     * @returns The matching KeyringAccount.
+     */
+    async getAccount(accountId) {
+        let cached = this.registry.get(accountId);
+        if (cached) {
+            return cached;
+        }
+        // Prime the registry by calling getAccounts
+        await this.getAccounts();
+        // Try registry again after priming
+        cached = this.registry.get(accountId);
+        if (!cached) {
+            throw new Error(`Account not found for id: ${accountId}`);
+        }
+        return cached;
+    }
+}
+_KeyringWrapper_capabilities = new WeakMap(), _KeyringWrapper_lock = new WeakMap();
+//# sourceMappingURL=keyring-wrapper.mjs.map

package/dist/api/v2/wrapper/keyring-wrapper.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyring-wrapper.mjs","sourceRoot":"","sources":["../../../../src/api/v2/wrapper/keyring-wrapper.ts"],"names":[],"mappings":";;;;;;;;;;;;AAEA,OAAO,EAAE,KAAK,EAAE,oBAAoB;AAEpC,OAAO,EAAE,sBAAsB,EAAE,uCAAmC;AAgCpE;;;;;;;;;GASG;AACH,MAAM,OAAgB,cAAc;IA2BlC,YAAY,OAA4C;QApB/C,+CAAmC;QAI5C;;;WAGG;QACM,+BAAQ,IAAI,KAAK,EAAE,EAAC;QAE7B;;;;;;WAMG;QACgB,aAAQ,GACzB,IAAI,sBAAsB,EAAsB,CAAC;QAGjD,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;QAC3B,IAAI,CAAC,IAAI,GAAG,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;QAC9B,uBAAA,IAAI,gCAAiB,OAAO,CAAC,YAAY,MAAA,CAAC;IAC5C,CAAC;IAED;;;;;;;OAOG;IACH,IAAI,YAAY;QACd,OAAO,uBAAA,IAAI,oCAAc,CAAC;IAC5B,CAAC;IAED;;;;;;;;;;;;OAYG;IACO,KAAK,CAAC,QAAQ,CACtB,QAA+B;QAE/B,OAAO,uBAAA,IAAI,4BAAM,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC;IAC3C,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,SAAS;QACb,OAAO,IAAI,CAAC,KAAK,CAAC,SAAS,EAAE,CAAC;IAChC,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,WAAW,CAAC,KAAW;QAC3B,MAAM,IAAI,CAAC,QAAQ,CAAC,KAAK,IAAI,EAAE;YAC7B,wCAAwC;YACxC,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC;YAEtB,iCAAiC;YACjC,MAAM,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;YAEpC,iDAAiD;YACjD,yEAAyE;YACzE,8DAA8D;YAC9D,MAAM,IAAI,CAAC,WAAW,EAAE,CAAC;QAC3B,CAAC,CAAC,CAAC;IACL,CAAC;IAgBD;;;;;;;;;OASG;IACH,KAAK,CAAC,UAAU,CAAC,SAAoB;QACnC,IAAI,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAC1C,IAAI,MAAM,EAAE,CAAC;YACX,OAAO,MAAM,CAAC;QAChB,CAAC;QAED,4CAA4C;QAC5C,MAAM,IAAI,CAAC,WAAW,EAAE,CAAC;QAEzB,mCAAmC;QACnC,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QACtC,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CAAC,6BAA6B,SAAS,EAAE,CAAC,CAAC;QAC5D,CAAC;QAED,OAAO,MAAM,CAAC;IAChB,CAAC;CA+CF","sourcesContent":["import type { Keyring, AccountId } from '@metamask/keyring-utils';\nimport type { Json } from '@metamask/utils';\nimport { Mutex } from 'async-mutex';\n\nimport { KeyringAccountRegistry } from './keyring-account-registry';\nimport type {\n  CreateAccountOptions,\n  ExportAccountOptions,\n  ExportedAccount,\n} from '..';\nimport type { KeyringAccount } from '../../account';\nimport type { KeyringRequest } from '../../request';\nimport type { KeyringV2 } from '../keyring';\nimport type { KeyringCapabilities } from '../keyring-capabilities';\nimport type { KeyringType } from '../keyring-type';\n\n/**\n * Basic options for constructing a {@link KeyringWrapper}.\n */\nexport type KeyringWrapperOptions<InnerKeyring extends Keyring> = {\n  /**\n   * The underlying \"old\" keyring instance that this wrapper adapts.\n   */\n  inner: InnerKeyring;\n\n  /**\n   * The concrete keyring type exposed through the V2 interface.\n   */\n  type: KeyringType;\n\n  /**\n   * Capabilities of the underlying keyring.\n   */\n  capabilities: KeyringCapabilities;\n};\n\n/**\n * Generic adapter that turns an existing {@link Keyring} implementation into a\n * {@link KeyringV2} instance.\n *\n * Consumers are expected to provide concrete mappings between high-level V2\n * operations and the underlying keyring methods (for example BIP-44 account\n * creation, private-key import, and request handling). This class focuses on\n * the common mechanics required by all adapters: state serialization,\n * account-ID/address mapping and basic account management.\n */\nexport abstract class KeyringWrapper<\n  InnerKeyring extends Keyring,\n  KeyringAccountType extends KeyringAccount = KeyringAccount,\n> implements KeyringV2\n{\n  readonly type: `${KeyringType}`;\n\n  readonly #capabilities: KeyringCapabilities;\n\n  protected readonly inner: InnerKeyring;\n\n  /**\n   * Mutex to ensure exclusive access to the inner keyring during\n   * operations that mutate its state.\n   */\n  readonly #lock = new Mutex();\n\n  /**\n   * Registry for KeyringAccount objects.\n   * Provides O(1) lookups by AccountId or address.\n   *\n   * Subclasses should use this registry when creating accounts and\n   * clear/update it when deleting accounts or deserializing state.\n   */\n  protected readonly registry =\n    new KeyringAccountRegistry<KeyringAccountType>();\n\n  constructor(options: KeyringWrapperOptions<InnerKeyring>) {\n    this.inner = options.inner;\n    this.type = `${options.type}`;\n    this.#capabilities = options.capabilities;\n  }\n\n  /**\n   * Get the capabilities of this keyring.\n   *\n   * Subclasses can override this getter to return capabilities dynamically\n   * based on runtime state.\n   *\n   * @returns The keyring's capabilities.\n   */\n  get capabilities(): KeyringCapabilities {\n    return this.#capabilities;\n  }\n\n  /**\n   * Execute an operation with exclusive access to the inner keyring.\n   *\n   * This method ensures thread-safety for operations that read or mutate\n   * the inner keyring state. All operations that modify the keyring\n   * (createAccounts, deleteAccount, deserialize) should use this method\n   * to prevent race conditions.\n   *\n   * Within the callback, use `this.inner` to access the inner keyring.\n   *\n   * @param callback - A function that performs the operation.\n   * @returns The result of the callback.\n   */\n  protected async withLock<Result>(\n    callback: () => Promise<Result>,\n  ): Promise<Result> {\n    return this.#lock.runExclusive(callback);\n  }\n\n  /**\n   * Serialize the underlying keyring state to a JSON-serializable object.\n   *\n   * This simply delegates to the legacy keyring's {@link Keyring.serialize}\n   * implementation.\n   *\n   * @returns The serialized keyring state.\n   */\n  async serialize(): Promise<Json> {\n    return this.inner.serialize();\n  }\n\n  /**\n   * Hydrate the underlying keyring from a previously serialized state.\n   *\n   * This clears the registry, delegates to the legacy keyring's\n   * {@link Keyring.deserialize} implementation, and rebuilds the registry\n   * by calling {@link getAccounts}.\n   *\n   * @param state - The serialized keyring state.\n   */\n  async deserialize(state: Json): Promise<void> {\n    await this.withLock(async () => {\n      // Clear the registry when deserializing\n      this.registry.clear();\n\n      // Deserialize the legacy keyring\n      await this.inner.deserialize(state);\n\n      // Rebuild the registry by calling getAccounts().\n      // Subclass implementations of getAccounts() should populate the registry\n      // as a side effect (see the abstract method's documentation).\n      await this.getAccounts();\n    });\n  }\n\n  /**\n   * Return all accounts managed by this keyring.\n   *\n   * Concrete adapters are responsible for mapping the underlying keyring's\n   * notion of accounts (typically addresses returned by\n   * {@link Keyring.getAccounts}) into {@link KeyringAccount} objects.\n   * Implementations should use the configured {@link KeyringAccountRegistry}\n   * to establish the account ID/address mapping so that\n   * {@link getAccount} works as expected.\n   *\n   * @returns The list of managed accounts.\n   */\n  abstract getAccounts(): Promise<KeyringAccount[]>;\n\n  /**\n   * Look up a single account by its {@link AccountId}.\n   *\n   * This method first checks the registry for O(1) lookup.\n   * If not found, it falls back to calling {@link getAccounts} which\n   * should populate the registry as a side effect.\n   *\n   * @param accountId - The AccountId to look up.\n   * @returns The matching KeyringAccount.\n   */\n  async getAccount(accountId: AccountId): Promise<KeyringAccount> {\n    let cached = this.registry.get(accountId);\n    if (cached) {\n      return cached;\n    }\n\n    // Prime the registry by calling getAccounts\n    await this.getAccounts();\n\n    // Try registry again after priming\n    cached = this.registry.get(accountId);\n    if (!cached) {\n      throw new Error(`Account not found for id: ${accountId}`);\n    }\n\n    return cached;\n  }\n\n  /**\n   * Create one or more new accounts managed by this keyring.\n   *\n   * Implementations are responsible for interpreting the\n   * {@link CreateAccountOptions} (for example BIP-44 derivation or\n   * private-key import) and returning the resulting {@link KeyringAccount}\n   * objects. Implementors should also ensure that the registry is updated so\n   * that {@link getAccount} works for newly created accounts.\n   */\n  abstract createAccounts(\n    options: CreateAccountOptions,\n  ): Promise<KeyringAccount[]>;\n\n  /**\n   * Remove the account associated with the given {@link AccountId} from this\n   * keyring.\n   *\n   * Implementations are expected to translate the ID to an underlying\n   * address (typically via the registry) and then invoke the appropriate\n   * removal mechanism on the legacy keyring.\n   */\n  abstract deleteAccount(accountId: AccountId): Promise<void>;\n\n  /**\n   * Export the secrets associated with the given account in a format\n   * described by {@link ExportAccountOptions}.\n   *\n   * This method is optional, and concrete adapters should only\n   * implement it if the underlying keyring supports exporting\n   * accounts.\n   */\n  exportAccount?(\n    accountId: AccountId,\n    options?: ExportAccountOptions,\n  ): Promise<ExportedAccount>;\n\n  /**\n   * Handle a high-level {@link KeyringRequest} on behalf of this keyring.\n   *\n   * Concrete adapters are responsible for routing the request's method and\n   * parameters to the appropriate legacy keyring APIs (for example signing\n   * transactions or decrypting messages) and returning a JSON-serializable\n   * result.\n   */\n  abstract submitRequest(request: KeyringRequest): Promise<Json>;\n}\n"]}