crypto-aio 0.0.3 → 0.1.0

package/dist/core/ordering/reservations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reservations.js","sourceRoot":"","sources":["../../../src/core/ordering/reservations.ts"],"names":[],"mappings":";;AAMA,wCAiBC;AAGD,kCAWC;AAMD,wDAWC;AAtDD,0CAAkE;AAElE;;;GAGG;AACH,SAAgB,cAAc,CAC5B,UAAsC,EACtC,QAAiB;IAEjB,MAAM,MAAM,GAAG,IAAI,GAAG,EAAU,CAAC;IACjC,KAAK,MAAM,EAAE,IAAI,UAAU,EAAE,CAAC;QAC5B,IAAI,EAAE,CAAC,EAAE,KAAK,QAAQ,IAAI,IAAA,kBAAU,EAAC,EAAE,CAAC,KAAK,CAAC;YAAE,SAAS;QACzD,IAAI,EAAE,CAAC,WAAW,EAAE,IAAI,KAAK,QAAQ;YACnC,KAAK,MAAM,KAAK,IAAI,EAAE,CAAC,WAAW,CAAC,MAAM;gBAAE,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QAC/D,IAAI,EAAE,CAAC,QAAQ,EAAE,QAAQ,CAAC,IAAI,KAAK,QAAQ;YACzC,KAAK,MAAM,KAAK,IAAI,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,MAAM;gBAAE,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACrE,KAAK,MAAM,OAAO,IAAI,EAAE,CAAC,QAAQ,EAAE,CAAC;YAClC,IAAI,OAAO,CAAC,QAAQ,CAAC,IAAI,KAAK,QAAQ;gBACpC,KAAK,MAAM,KAAK,IAAI,OAAO,CAAC,QAAQ,CAAC,MAAM;oBAAE,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACnE,CAAC;IACH,CAAC;IACD,OAAO,CAAC,GAAG,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC;AAC5B,CAAC;AAED,qGAAqG;AACrG,SAAgB,WAAW,CACzB,UAAsC,EACtC,QAAiB;IAEjB,OAAO,UAAU,CAAC,IAAI,CACpB,CAAC,EAAE,EAAE,EAAE,CACL,EAAE,CAAC,EAAE,KAAK,QAAQ;QAClB,CAAC,IAAA,kBAAU,EAAC,EAAE,CAAC,KAAK,CAAC;QACrB,EAAE,CAAC,KAAK,KAAK,UAAU;QACvB,EAAE,CAAC,WAAW,EAAE,IAAI,KAAK,OAAO,CACnC,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,SAAgB,sBAAsB,CACpC,UAAsC;IAEtC,IAAI,MAA0D,CAAC;IAC/D,KAAK,MAAM,EAAE,IAAI,UAAU,EAAE,CAAC;QAC5B,IAAI,IAAA,kBAAU,EAAC,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,KAAK,KAAK,UAAU;YAAE,SAAS;QAC9D,IAAI,EAAE,CAAC,WAAW,EAAE,IAAI,KAAK,OAAO;YAAE,SAAS;QAC/C,IAAI,CAAC,MAAM,IAAI,EAAE,CAAC,WAAW,CAAC,KAAK,GAAG,MAAM,CAAC,KAAK;YAChD,MAAM,GAAG,EAAE,KAAK,EAAE,EAAE,CAAC,WAAW,CAAC,KAAK,EAAE,WAAW,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC;IACjE,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC","sourcesContent":["import { isTerminal, type OperationRecord } from '../store/types';\n\n/**\n * Inputs held by live Operations: their reservation, unsigned payload and every Attempt.\n * Coin selection excludes them, so two Operations of a wallet never pick the same coin.\n */\nexport function reservedInputs(\n  operations: readonly OperationRecord[],\n  exceptId?: string,\n): string[] {\n  const inputs = new Set<string>();\n  for (const op of operations) {\n    if (op.id === exceptId || isTerminal(op.state)) continue;\n    if (op.reservation?.kind === 'inputs')\n      for (const input of op.reservation.inputs) inputs.add(input);\n    if (op.unsigned?.ordering.kind === 'inputs')\n      for (const input of op.unsigned.ordering.inputs) inputs.add(input);\n    for (const attempt of op.attempts) {\n      if (attempt.ordering.kind === 'inputs')\n        for (const input of attempt.ordering.inputs) inputs.add(input);\n    }\n  }\n  return [...inputs].sort();\n}\n\n/** The live Operation that may still consume the wallet's current seqno (TON is strictly serial). */\nexport function seqnoHolder(\n  operations: readonly OperationRecord[],\n  exceptId?: string,\n): OperationRecord | undefined {\n  return operations.find(\n    (op) =>\n      op.id !== exceptId &&\n      !isTerminal(op.state) &&\n      op.state !== 'included' &&\n      op.reservation?.kind === 'seqno',\n  );\n}\n\n/**\n * The lowest nonce still reserved by a live, not-yet-included Operation. Included\n * nonces are already consumed on chain, so counting them would mask a gap above them.\n */\nexport function lowestOutstandingNonce(\n  operations: readonly OperationRecord[],\n): { nonce: bigint; operationId: string } | undefined {\n  let lowest: { nonce: bigint; operationId: string } | undefined;\n  for (const op of operations) {\n    if (isTerminal(op.state) || op.state === 'included') continue;\n    if (op.reservation?.kind !== 'nonce') continue;\n    if (!lowest || op.reservation.nonce < lowest.nonce)\n      lowest = { nonce: op.reservation.nonce, operationId: op.id };\n  }\n  return lowest;\n}\n"]}

package/dist/core/ordering/sequence.d.ts

@@ -0,0 +1,61 @@
+import type { Lease, LockManager, SequenceStore } from '../store/types';
+import type { Clock } from '../util/clock';
+export declare function sequenceKey(namespace: string, chain: string, network: string, address: string): string;
+/** A held lease that can be renewed; renewal failure means another worker took over. */
+export declare class LeaseHandle {
+    #private;
+    private readonly locks;
+    private readonly ttlMs;
+    constructor(locks: LockManager, ttlMs: number, lease: Lease);
+    get current(): Lease;
+    renew(): Promise<void>;
+}
+export interface SequenceCoordinatorDeps {
+    readonly locks: LockManager;
+    readonly sequences: SequenceStore;
+    readonly clock: Clock;
+    readonly owner: string;
+    readonly leaseMs: number;
+    /** How long to wait for a busy address before failing with SEQUENCE_BUSY (default: leaseMs). */
+    readonly acquireTimeoutMs?: number;
+    /**
+     * Observes a failed best-effort lease release (the lease then lapses by its TTL).
+     * Its own failure is ignored. Log only the error code: messages may carry store detail.
+     */
+    onReleaseError?(error: unknown): void;
+}
+export declare class SequenceCoordinator {
+    #private;
+    private readonly deps;
+    constructor(deps: SequenceCoordinatorDeps);
+    /**
+     * Runs `fn` while holding the address lease for `key`, then releases it.
+     *
+     * Not re-entrant: a nested `withLease` on the same key waits like any other caller.
+     * It fails with SEQUENCE_BUSY after `acquireTimeoutMs`, or, when that is not shorter
+     * than `leaseMs`, it can outlive the outer lease, take it over and fence the outer
+     * caller. Code that already holds the lease must pass its `LeaseHandle` down instead.
+     * The lease is not renewed automatically; long callbacks call `lease.renew()`.
+     * `options.acquireTimeoutMs` overrides the wait for this call (`0`: a single try).
+     */
+    withLease<T>(key: string, fn: (lease: LeaseHandle) => Promise<T>, signal?: AbortSignal, options?: {
+        readonly acquireTimeoutMs?: number;
+    }): Promise<T>;
+    allocate(lease: LeaseHandle, key: string, chainPending: bigint): Promise<bigint>;
+    /**
+     * Returns a reserved value for reuse. Only legal while no valid signed bytes exist for
+     * it. Precondition: called at most once per allocation, by the Operation holding the
+     * value, after its terminal CAS or after a failure before its reservation was persisted.
+     * Releasing a value that is at or above `next`, or already released, is a no-op.
+     */
+    release(lease: LeaseHandle, key: string, value: bigint): Promise<void>;
+    /**
+     * Nonce reconciliation: returns to `released` every value in [chainPending, next) that is
+     * neither released already nor in `reserved`, and returns those values (ascending). It
+     * never touches a value below `chainPending` (the chain consumed it) or at or above
+     * `next` (never allocated). The caller holds `lease` and reads `reserved` (the values live
+     * Operations hold) under it, so no allocation can interleave; nothing is written when
+     * there is nothing to reclaim.
+     */
+    reclaim(lease: LeaseHandle, key: string, chainPending: bigint, reserved: readonly bigint[]): Promise<bigint[]>;
+}

package/dist/core/ordering/sequence.js

@@ -0,0 +1,155 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SequenceCoordinator = exports.LeaseHandle = void 0;
+exports.sequenceKey = sequenceKey;
+const error_1 = require("../errors/error");
+function sequenceKey(namespace, chain, network, address) {
+    return `seq:${namespace}:${chain}:${network}:${address}`;
+}
+const byValue = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+/** A held lease that can be renewed; renewal failure means another worker took over. */
+class LeaseHandle {
+    locks;
+    ttlMs;
+    #lease;
+    constructor(locks, ttlMs, lease) {
+        this.locks = locks;
+        this.ttlMs = ttlMs;
+        this.#lease = lease;
+    }
+    get current() {
+        return this.#lease;
+    }
+    async renew() {
+        const renewed = await this.locks.renew(this.#lease, this.ttlMs);
+        if (!renewed)
+            throw new error_1.StateError('FENCING', 'the address lease was lost to another worker');
+        this.#lease = renewed;
+    }
+}
+exports.LeaseHandle = LeaseHandle;
+/**
+ * Lease tokens increase per key only, so a lease for another key cannot fence this one.
+ * Messages omit the key: it embeds the wallet address, and error messages reach logs.
+ */
+function fenceFor(lease, key) {
+    const { key: leased, token } = lease.current;
+    if (leased !== key) {
+        throw new error_1.StateError('FENCING', 'a lease for another address cannot write this sequence');
+    }
+    return token;
+}
+class SequenceCoordinator {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /**
+     * Runs `fn` while holding the address lease for `key`, then releases it.
+     *
+     * Not re-entrant: a nested `withLease` on the same key waits like any other caller.
+     * It fails with SEQUENCE_BUSY after `acquireTimeoutMs`, or, when that is not shorter
+     * than `leaseMs`, it can outlive the outer lease, take it over and fence the outer
+     * caller. Code that already holds the lease must pass its `LeaseHandle` down instead.
+     * The lease is not renewed automatically; long callbacks call `lease.renew()`.
+     * `options.acquireTimeoutMs` overrides the wait for this call (`0`: a single try).
+     */
+    async withLease(key, fn, signal, options = {}) {
+        signal?.throwIfAborted();
+        const deadline = this.deps.clock.now() +
+            (options.acquireTimeoutMs ?? this.deps.acquireTimeoutMs ?? this.deps.leaseMs);
+        let lease = await this.deps.locks.acquire(key, this.deps.owner, this.deps.leaseMs);
+        while (!lease) {
+            if (this.deps.clock.now() >= deadline) {
+                throw new error_1.StateError('SEQUENCE_BUSY', 'the address lease is held by another operation', { retryable: true });
+            }
+            await this.deps.clock.sleep(25, signal);
+            lease = await this.deps.locks.acquire(key, this.deps.owner, this.deps.leaseMs);
+        }
+        const handle = new LeaseHandle(this.deps.locks, this.deps.leaseMs, lease);
+        try {
+            return await fn(handle);
+        }
+        finally {
+            // Best effort: a failed release must not replace the callback's outcome (for
+            // example a completed broadcast). The lease then lapses by its TTL, and fencing
+            // still guards every write.
+            await this.#release(handle.current);
+        }
+    }
+    /**
+     * A release that throws, synchronously or not, is reported and absorbed, and so
+     * is the observer's own failure, including an async observer's rejection.
+     */
+    async #release(lease) {
+        try {
+            await this.deps.locks.release(lease);
+        }
+        catch (error) {
+            try {
+                const observed = this.deps.onReleaseError?.(error);
+                if (typeof observed?.then === 'function') {
+                    Promise.resolve(observed).catch(() => undefined);
+                }
+            }
+            catch {
+                // An observer failure must not replace the outcome either.
+            }
+        }
+    }
+    async allocate(lease, key, chainPending) {
+        const fence = fenceFor(lease, key);
+        const state = await this.deps.sequences.get(key);
+        const released = [...(state?.released ?? [])]
+            .filter((n) => n >= chainPending)
+            .sort(byValue);
+        const floor = state && state.next > chainPending ? state.next : chainPending;
+        const pick = released[0] ?? floor;
+        const next = pick >= floor ? pick + 1n : floor;
+        await this.deps.sequences.put(key, { next, released: released.filter((n) => n !== pick), fence }, state?.version ?? null);
+        return pick;
+    }
+    /**
+     * Returns a reserved value for reuse. Only legal while no valid signed bytes exist for
+     * it. Precondition: called at most once per allocation, by the Operation holding the
+     * value, after its terminal CAS or after a failure before its reservation was persisted.
+     * Releasing a value that is at or above `next`, or already released, is a no-op.
+     */
+    async release(lease, key, value) {
+        const fence = fenceFor(lease, key);
+        const state = await this.deps.sequences.get(key);
+        if (!state || value >= state.next || state.released.includes(value))
+            return;
+        await this.deps.sequences.put(key, { next: state.next, released: [...state.released, value].sort(byValue), fence }, state.version);
+    }
+    /**
+     * Nonce reconciliation: returns to `released` every value in [chainPending, next) that is
+     * neither released already nor in `reserved`, and returns those values (ascending). It
+     * never touches a value below `chainPending` (the chain consumed it) or at or above
+     * `next` (never allocated). The caller holds `lease` and reads `reserved` (the values live
+     * Operations hold) under it, so no allocation can interleave; nothing is written when
+     * there is nothing to reclaim.
+     */
+    async reclaim(lease, key, chainPending, reserved) {
+        const fence = fenceFor(lease, key);
+        const state = await this.deps.sequences.get(key);
+        if (!state)
+            return [];
+        const held = new Set([...state.released, ...reserved]);
+        const reclaimed = [];
+        for (let value = chainPending; value < state.next; value++) {
+            if (!held.has(value))
+                reclaimed.push(value);
+        }
+        if (reclaimed.length === 0)
+            return [];
+        await this.deps.sequences.put(key, {
+            next: state.next,
+            released: [...state.released, ...reclaimed].sort(byValue),
+            fence,
+        }, state.version);
+        return reclaimed;
+    }
+}
+exports.SequenceCoordinator = SequenceCoordinator;
+//# sourceMappingURL=sequence.js.map

package/dist/core/ordering/sequence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sequence.js","sourceRoot":"","sources":["../../../src/core/ordering/sequence.ts"],"names":[],"mappings":"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","sourcesContent":["import { StateError } from '../errors/error';\nimport type { Lease, LockManager, SequenceStore } from '../store/types';\nimport type { Clock } from '../util/clock';\n\nexport function sequenceKey(\n  namespace: string,\n  chain: string,\n  network: string,\n  address: string,\n): string {\n  return `seq:${namespace}:${chain}:${network}:${address}`;\n}\n\nconst byValue = (a: bigint, b: bigint): number => (a < b ? -1 : a > b ? 1 : 0);\n\n/** A held lease that can be renewed; renewal failure means another worker took over. */\nexport class LeaseHandle {\n  #lease: Lease;\n\n  constructor(\n    private readonly locks: LockManager,\n    private readonly ttlMs: number,\n    lease: Lease,\n  ) {\n    this.#lease = lease;\n  }\n\n  get current(): Lease {\n    return this.#lease;\n  }\n\n  async renew(): Promise<void> {\n    const renewed = await this.locks.renew(this.#lease, this.ttlMs);\n    if (!renewed)\n      throw new StateError('FENCING', 'the address lease was lost to another worker');\n    this.#lease = renewed;\n  }\n}\n\n/**\n * Lease tokens increase per key only, so a lease for another key cannot fence this one.\n * Messages omit the key: it embeds the wallet address, and error messages reach logs.\n */\nfunction fenceFor(lease: LeaseHandle, key: string): bigint {\n  const { key: leased, token } = lease.current;\n  if (leased !== key) {\n    throw new StateError(\n      'FENCING',\n      'a lease for another address cannot write this sequence',\n    );\n  }\n  return token;\n}\n\nexport interface SequenceCoordinatorDeps {\n  readonly locks: LockManager;\n  readonly sequences: SequenceStore;\n  readonly clock: Clock;\n  readonly owner: string;\n  readonly leaseMs: number;\n  /** How long to wait for a busy address before failing with SEQUENCE_BUSY (default: leaseMs). */\n  readonly acquireTimeoutMs?: number;\n  /**\n   * Observes a failed best-effort lease release (the lease then lapses by its TTL).\n   * Its own failure is ignored. Log only the error code: messages may carry store detail.\n   */\n  onReleaseError?(error: unknown): void;\n}\n\nexport class SequenceCoordinator {\n  constructor(private readonly deps: SequenceCoordinatorDeps) {}\n\n  /**\n   * Runs `fn` while holding the address lease for `key`, then releases it.\n   *\n   * Not re-entrant: a nested `withLease` on the same key waits like any other caller.\n   * It fails with SEQUENCE_BUSY after `acquireTimeoutMs`, or, when that is not shorter\n   * than `leaseMs`, it can outlive the outer lease, take it over and fence the outer\n   * caller. Code that already holds the lease must pass its `LeaseHandle` down instead.\n   * The lease is not renewed automatically; long callbacks call `lease.renew()`.\n   * `options.acquireTimeoutMs` overrides the wait for this call (`0`: a single try).\n   */\n  async withLease<T>(\n    key: string,\n    fn: (lease: LeaseHandle) => Promise<T>,\n    signal?: AbortSignal,\n    options: { readonly acquireTimeoutMs?: number } = {},\n  ): Promise<T> {\n    signal?.throwIfAborted();\n    const deadline =\n      this.deps.clock.now() +\n      (options.acquireTimeoutMs ?? this.deps.acquireTimeoutMs ?? this.deps.leaseMs);\n    let lease = await this.deps.locks.acquire(key, this.deps.owner, this.deps.leaseMs);\n    while (!lease) {\n      if (this.deps.clock.now() >= deadline) {\n        throw new StateError(\n          'SEQUENCE_BUSY',\n          'the address lease is held by another operation',\n          { retryable: true },\n        );\n      }\n      await this.deps.clock.sleep(25, signal);\n      lease = await this.deps.locks.acquire(key, this.deps.owner, this.deps.leaseMs);\n    }\n    const handle = new LeaseHandle(this.deps.locks, this.deps.leaseMs, lease);\n    try {\n      return await fn(handle);\n    } finally {\n      // Best effort: a failed release must not replace the callback's outcome (for\n      // example a completed broadcast). The lease then lapses by its TTL, and fencing\n      // still guards every write.\n      await this.#release(handle.current);\n    }\n  }\n\n  /**\n   * A release that throws, synchronously or not, is reported and absorbed, and so\n   * is the observer's own failure, including an async observer's rejection.\n   */\n  async #release(lease: Lease): Promise<void> {\n    try {\n      await this.deps.locks.release(lease);\n    } catch (error) {\n      try {\n        const observed: unknown = this.deps.onReleaseError?.(error);\n        if (typeof (observed as { then?: unknown } | null)?.then === 'function') {\n          Promise.resolve(observed).catch(() => undefined);\n        }\n      } catch {\n        // An observer failure must not replace the outcome either.\n      }\n    }\n  }\n\n  async allocate(lease: LeaseHandle, key: string, chainPending: bigint): Promise<bigint> {\n    const fence = fenceFor(lease, key);\n    const state = await this.deps.sequences.get(key);\n    const released = [...(state?.released ?? [])]\n      .filter((n) => n >= chainPending)\n      .sort(byValue);\n    const floor = state && state.next > chainPending ? state.next : chainPending;\n    const pick = released[0] ?? floor;\n    const next = pick >= floor ? pick + 1n : floor;\n    await this.deps.sequences.put(\n      key,\n      { next, released: released.filter((n) => n !== pick), fence },\n      state?.version ?? null,\n    );\n    return pick;\n  }\n\n  /**\n   * Returns a reserved value for reuse. Only legal while no valid signed bytes exist for\n   * it. Precondition: called at most once per allocation, by the Operation holding the\n   * value, after its terminal CAS or after a failure before its reservation was persisted.\n   * Releasing a value that is at or above `next`, or already released, is a no-op.\n   */\n  async release(lease: LeaseHandle, key: string, value: bigint): Promise<void> {\n    const fence = fenceFor(lease, key);\n    const state = await this.deps.sequences.get(key);\n    if (!state || value >= state.next || state.released.includes(value)) return;\n    await this.deps.sequences.put(\n      key,\n      { next: state.next, released: [...state.released, value].sort(byValue), fence },\n      state.version,\n    );\n  }\n\n  /**\n   * Nonce reconciliation: returns to `released` every value in [chainPending, next) that is\n   * neither released already nor in `reserved`, and returns those values (ascending). It\n   * never touches a value below `chainPending` (the chain consumed it) or at or above\n   * `next` (never allocated). The caller holds `lease` and reads `reserved` (the values live\n   * Operations hold) under it, so no allocation can interleave; nothing is written when\n   * there is nothing to reclaim.\n   */\n  async reclaim(\n    lease: LeaseHandle,\n    key: string,\n    chainPending: bigint,\n    reserved: readonly bigint[],\n  ): Promise<bigint[]> {\n    const fence = fenceFor(lease, key);\n    const state = await this.deps.sequences.get(key);\n    if (!state) return [];\n    const held = new Set([...state.released, ...reserved]);\n    const reclaimed: bigint[] = [];\n    for (let value = chainPending; value < state.next; value++) {\n      if (!held.has(value)) reclaimed.push(value);\n    }\n    if (reclaimed.length === 0) return [];\n    await this.deps.sequences.put(\n      key,\n      {\n        next: state.next,\n        released: [...state.released, ...reclaimed].sort(byValue),\n        fence,\n      },\n      state.version,\n    );\n    return reclaimed;\n  }\n}\n"]}

package/dist/core/registry/adapters.d.ts

@@ -0,0 +1,10 @@
+import type { AdapterManifest, DriverFactory } from '../driver/types';
+export declare class AdapterCatalog {
+    #private;
+    register(manifest: AdapterManifest): void;
+    /** Manifests for a chain in registration order; the first is the family default. */
+    forChain(chainId: string): AdapterManifest[];
+    get(chainId: string, library: string): AdapterManifest | undefined;
+    load(manifest: AdapterManifest): Promise<DriverFactory>;
+    clone(): AdapterCatalog;
+}

package/dist/core/registry/adapters.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AdapterCatalog = void 0;
+const error_1 = require("../errors/error");
+const keyOf = (m) => `${m.family}/${m.library}`;
+function dependencyError(manifest, error) {
+    const code = error?.code;
+    if (code !== 'MODULE_NOT_FOUND' && code !== 'ERR_MODULE_NOT_FOUND')
+        return error;
+    const message = error instanceof Error ? error.message : String(error);
+    const deps = manifest.peerDependencies.filter((d) => message.includes(`'${d.name}'`) || message.includes(`"${d.name}"`));
+    // Only a missing peer dependency is the user's to install. Any other missing module
+    // (the adapter's own file, a broken build) keeps its own error.
+    if (deps.length === 0)
+        return error;
+    const install = deps.map((d) => `${d.name}@${d.range}`).join(' ');
+    return new error_1.ConfigError('DEPENDENCY_MISSING', `library '${manifest.library}' (${manifest.family}) needs ${deps.map((d) => d.name).join(', ')}; install it: npm i ${install}`, { cause: error, details: { packages: deps.map((d) => d.name) } });
+}
+class AdapterCatalog {
+    #manifests = new Map();
+    #loaded = new Map();
+    register(manifest) {
+        const key = keyOf(manifest);
+        if (this.#manifests.has(key)) {
+            throw new error_1.ConfigError('CONFIG_INVALID', `adapter '${key}' is already registered`);
+        }
+        this.#manifests.set(key, manifest);
+    }
+    /** Manifests for a chain in registration order; the first is the family default. */
+    forChain(chainId) {
+        return [...this.#manifests.values()].filter((m) => m.chains.includes(chainId));
+    }
+    get(chainId, library) {
+        return this.forChain(chainId).find((m) => m.library === library);
+    }
+    load(manifest) {
+        const key = keyOf(manifest);
+        let pending = this.#loaded.get(key);
+        if (!pending) {
+            pending = manifest.load().catch((error) => {
+                this.#loaded.delete(key);
+                throw dependencyError(manifest, error);
+            });
+            this.#loaded.set(key, pending);
+        }
+        return pending;
+    }
+    clone() {
+        const copy = new AdapterCatalog();
+        for (const [key, manifest] of this.#manifests)
+            copy.#manifests.set(key, manifest);
+        return copy;
+    }
+}
+exports.AdapterCatalog = AdapterCatalog;
+//# sourceMappingURL=adapters.js.map

package/dist/core/registry/adapters.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapters.js","sourceRoot":"","sources":["../../../src/core/registry/adapters.ts"],"names":[],"mappings":"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","sourcesContent":["import type { AdapterManifest, DriverFactory } from '../driver/types';\nimport { ConfigError } from '../errors/error';\n\nconst keyOf = (m: AdapterManifest): string => `${m.family}/${m.library}`;\n\nfunction dependencyError(manifest: AdapterManifest, error: unknown): unknown {\n  const code = (error as { code?: unknown } | null)?.code;\n  if (code !== 'MODULE_NOT_FOUND' && code !== 'ERR_MODULE_NOT_FOUND') return error;\n  const message = error instanceof Error ? error.message : String(error);\n  const deps = manifest.peerDependencies.filter(\n    (d) => message.includes(`'${d.name}'`) || message.includes(`\"${d.name}\"`),\n  );\n  // Only a missing peer dependency is the user's to install. Any other missing module\n  // (the adapter's own file, a broken build) keeps its own error.\n  if (deps.length === 0) return error;\n  const install = deps.map((d) => `${d.name}@${d.range}`).join(' ');\n  return new ConfigError(\n    'DEPENDENCY_MISSING',\n    `library '${manifest.library}' (${manifest.family}) needs ${deps.map((d) => d.name).join(', ')}; install it: npm i ${install}`,\n    { cause: error, details: { packages: deps.map((d) => d.name) } },\n  );\n}\n\nexport class AdapterCatalog {\n  readonly #manifests = new Map<string, AdapterManifest>();\n  readonly #loaded = new Map<string, Promise<DriverFactory>>();\n\n  register(manifest: AdapterManifest): void {\n    const key = keyOf(manifest);\n    if (this.#manifests.has(key)) {\n      throw new ConfigError('CONFIG_INVALID', `adapter '${key}' is already registered`);\n    }\n    this.#manifests.set(key, manifest);\n  }\n\n  /** Manifests for a chain in registration order; the first is the family default. */\n  forChain(chainId: string): AdapterManifest[] {\n    return [...this.#manifests.values()].filter((m) => m.chains.includes(chainId));\n  }\n\n  get(chainId: string, library: string): AdapterManifest | undefined {\n    return this.forChain(chainId).find((m) => m.library === library);\n  }\n\n  load(manifest: AdapterManifest): Promise<DriverFactory> {\n    const key = keyOf(manifest);\n    let pending = this.#loaded.get(key);\n    if (!pending) {\n      pending = manifest.load().catch((error: unknown) => {\n        this.#loaded.delete(key);\n        throw dependencyError(manifest, error);\n      });\n      this.#loaded.set(key, pending);\n    }\n    return pending;\n  }\n\n  clone(): AdapterCatalog {\n    const copy = new AdapterCatalog();\n    for (const [key, manifest] of this.#manifests) copy.#manifests.set(key, manifest);\n    return copy;\n  }\n}\n"]}

package/dist/core/registry/assets.d.ts

@@ -0,0 +1,18 @@
+import { type AssetId, type AssetInfo, type AssetMetadata, type AssetRef } from '../model/asset';
+import type { ChainInfo } from '../model/chain';
+export interface AssetRegistration {
+    readonly chain: string;
+    readonly network: string;
+    readonly ref: AssetRef;
+    readonly metadata: AssetMetadata;
+    readonly aliases?: readonly string[];
+}
+export declare class AssetCatalog {
+    #private;
+    register(registration: AssetRegistration): AssetInfo;
+    registerNative(chain: ChainInfo): void;
+    get(id: AssetId): AssetInfo | undefined;
+    native(chain: string, network: string): AssetInfo;
+    resolveAlias(chain: string, network: string, alias: string): AssetInfo;
+    clone(): AssetCatalog;
+}

package/dist/core/registry/assets.js

@@ -0,0 +1,90 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AssetCatalog = void 0;
+const error_1 = require("../errors/error");
+const asset_1 = require("../model/asset");
+const names_1 = require("../util/names");
+const ALIAS = /^[A-Z0-9._-]{1,32}$/;
+class AssetCatalog {
+    #byId = new Map();
+    #aliases = new Map();
+    register(registration) {
+        const id = (0, asset_1.assetId)(registration.chain, registration.network, registration.ref);
+        const problem = (0, asset_1.metadataProblem)(registration.metadata);
+        if (problem)
+            throw new error_1.ConfigError('CONFIG_INVALID', `asset '${id}': ${problem}`);
+        const existing = this.#byId.get(id);
+        if (existing &&
+            (existing.metadata.symbol !== registration.metadata.symbol ||
+                existing.metadata.decimals !== registration.metadata.decimals)) {
+            throw new error_1.ConfigError('CONFIG_INVALID', `asset '${id}' is already registered with different metadata`);
+        }
+        const scopeKey = `${registration.chain}:${registration.network}`;
+        const scope = this.#aliases.get(scopeKey) ?? new Map();
+        const aliases = (registration.aliases ?? []).map((alias) => {
+            const normalized = alias.trim().toUpperCase();
+            if (!ALIAS.test(normalized)) {
+                throw new error_1.ConfigError('CONFIG_INVALID', `invalid asset alias '${alias}'`);
+            }
+            const owner = scope.get(normalized);
+            if (owner && owner !== id) {
+                throw new error_1.ConfigError('CONFIG_INVALID', `alias '${normalized}' on ${scopeKey} already refers to '${owner}'`);
+            }
+            return normalized;
+        });
+        const info = existing ??
+            Object.freeze({
+                id,
+                chain: registration.chain,
+                network: registration.network,
+                ref: registration.ref,
+                metadata: Object.freeze({ ...registration.metadata }),
+            });
+        this.#byId.set(id, info);
+        for (const alias of aliases)
+            scope.set(alias, id);
+        this.#aliases.set(scopeKey, scope);
+        return info;
+    }
+    registerNative(chain) {
+        for (const network of Object.keys(chain.networks)) {
+            this.register({
+                chain: chain.id,
+                network,
+                ref: 'native',
+                metadata: chain.nativeAsset,
+                aliases: [chain.nativeAsset.symbol],
+            });
+        }
+    }
+    get(id) {
+        return this.#byId.get(id);
+    }
+    native(chain, network) {
+        const info = this.#byId.get((0, asset_1.assetId)(chain, network, 'native'));
+        if (!info) {
+            throw new error_1.ValidationError('ASSET_RESOLUTION', `no native asset registered for ${chain}:${network}`);
+        }
+        return info;
+    }
+    resolveAlias(chain, network, alias) {
+        const scopeKey = `${chain}:${network}`;
+        const scope = this.#aliases.get(scopeKey);
+        const id = scope?.get(alias.trim().toUpperCase());
+        const info = id ? this.#byId.get(id) : undefined;
+        if (!info) {
+            throw new error_1.ValidationError('ASSET_RESOLUTION', (0, names_1.unknownName)(`asset alias on ${scopeKey}`, scope?.keys() ?? []));
+        }
+        return info;
+    }
+    clone() {
+        const copy = new AssetCatalog();
+        for (const [id, info] of this.#byId)
+            copy.#byId.set(id, info);
+        for (const [key, scope] of this.#aliases)
+            copy.#aliases.set(key, new Map(scope));
+        return copy;
+    }
+}
+exports.AssetCatalog = AssetCatalog;
+//# sourceMappingURL=assets.js.map

package/dist/core/registry/assets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assets.js","sourceRoot":"","sources":["../../../src/core/registry/assets.ts"],"names":[],"mappings":"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","sourcesContent":["import { ConfigError, ValidationError } from '../errors/error';\nimport {\n  assetId,\n  metadataProblem,\n  type AssetId,\n  type AssetInfo,\n  type AssetMetadata,\n  type AssetRef,\n} from '../model/asset';\nimport type { ChainInfo } from '../model/chain';\nimport { unknownName } from '../util/names';\n\nexport interface AssetRegistration {\n  readonly chain: string;\n  readonly network: string;\n  readonly ref: AssetRef;\n  readonly metadata: AssetMetadata;\n  readonly aliases?: readonly string[];\n}\n\nconst ALIAS = /^[A-Z0-9._-]{1,32}$/;\n\nexport class AssetCatalog {\n  readonly #byId = new Map<AssetId, AssetInfo>();\n  readonly #aliases = new Map<string, Map<string, AssetId>>();\n\n  register(registration: AssetRegistration): AssetInfo {\n    const id = assetId(registration.chain, registration.network, registration.ref);\n    const problem = metadataProblem(registration.metadata);\n    if (problem) throw new ConfigError('CONFIG_INVALID', `asset '${id}': ${problem}`);\n    const existing = this.#byId.get(id);\n    if (\n      existing &&\n      (existing.metadata.symbol !== registration.metadata.symbol ||\n        existing.metadata.decimals !== registration.metadata.decimals)\n    ) {\n      throw new ConfigError(\n        'CONFIG_INVALID',\n        `asset '${id}' is already registered with different metadata`,\n      );\n    }\n    const scopeKey = `${registration.chain}:${registration.network}`;\n    const scope = this.#aliases.get(scopeKey) ?? new Map<string, AssetId>();\n    const aliases = (registration.aliases ?? []).map((alias) => {\n      const normalized = alias.trim().toUpperCase();\n      if (!ALIAS.test(normalized)) {\n        throw new ConfigError('CONFIG_INVALID', `invalid asset alias '${alias}'`);\n      }\n      const owner = scope.get(normalized);\n      if (owner && owner !== id) {\n        throw new ConfigError(\n          'CONFIG_INVALID',\n          `alias '${normalized}' on ${scopeKey} already refers to '${owner}'`,\n        );\n      }\n      return normalized;\n    });\n    const info: AssetInfo =\n      existing ??\n      Object.freeze({\n        id,\n        chain: registration.chain,\n        network: registration.network,\n        ref: registration.ref,\n        metadata: Object.freeze({ ...registration.metadata }),\n      });\n    this.#byId.set(id, info);\n    for (const alias of aliases) scope.set(alias, id);\n    this.#aliases.set(scopeKey, scope);\n    return info;\n  }\n\n  registerNative(chain: ChainInfo): void {\n    for (const network of Object.keys(chain.networks)) {\n      this.register({\n        chain: chain.id,\n        network,\n        ref: 'native',\n        metadata: chain.nativeAsset,\n        aliases: [chain.nativeAsset.symbol],\n      });\n    }\n  }\n\n  get(id: AssetId): AssetInfo | undefined {\n    return this.#byId.get(id);\n  }\n\n  native(chain: string, network: string): AssetInfo {\n    const info = this.#byId.get(assetId(chain, network, 'native'));\n    if (!info) {\n      throw new ValidationError(\n        'ASSET_RESOLUTION',\n        `no native asset registered for ${chain}:${network}`,\n      );\n    }\n    return info;\n  }\n\n  resolveAlias(chain: string, network: string, alias: string): AssetInfo {\n    const scopeKey = `${chain}:${network}`;\n    const scope = this.#aliases.get(scopeKey);\n    const id = scope?.get(alias.trim().toUpperCase());\n    const info = id ? this.#byId.get(id) : undefined;\n    if (!info) {\n      throw new ValidationError(\n        'ASSET_RESOLUTION',\n        unknownName(`asset alias on ${scopeKey}`, scope?.keys() ?? []),\n      );\n    }\n    return info;\n  }\n\n  clone(): AssetCatalog {\n    const copy = new AssetCatalog();\n    for (const [id, info] of this.#byId) copy.#byId.set(id, info);\n    for (const [key, scope] of this.#aliases) copy.#aliases.set(key, new Map(scope));\n    return copy;\n  }\n}\n"]}

package/dist/core/registry/chains.d.ts

@@ -0,0 +1,10 @@
+import type { ChainInfo, NetworkInfo } from '../model/chain';
+export declare class ChainCatalog {
+    #private;
+    register(chain: ChainInfo): void;
+    has(id: string): boolean;
+    get(id: string): ChainInfo;
+    list(): ChainInfo[];
+    network(chainId: string, networkId: string): NetworkInfo;
+    clone(): ChainCatalog;
+}

package/dist/core/registry/chains.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ChainCatalog = void 0;
+const error_1 = require("../errors/error");
+const names_1 = require("../util/names");
+class ChainCatalog {
+    #chains = new Map();
+    register(chain) {
+        validateChain(chain);
+        if (this.#chains.has(chain.id)) {
+            throw new error_1.ConfigError('CONFIG_INVALID', `chain '${chain.id}' is already registered`);
+        }
+        this.#chains.set(chain.id, Object.freeze({ ...chain }));
+    }
+    has(id) {
+        return this.#chains.has(id);
+    }
+    get(id) {
+        const chain = this.#chains.get(id);
+        if (!chain) {
+            // The caller's text (perhaps a pasted secret) is never repeated; the registered
+            // chains are listed.
+            throw new error_1.ConfigError('CONFIG_INVALID', (0, names_1.unknownName)('chain', this.#chains.keys()));
+        }
+        return chain;
+    }
+    list() {
+        return [...this.#chains.values()];
+    }
+    network(chainId, networkId) {
+        const chain = this.get(chainId);
+        // Own keys only: `toString` or `constructor` is not a network.
+        const network = Object.hasOwn(chain.networks, networkId)
+            ? chain.networks[networkId]
+            : undefined;
+        if (!network) {
+            throw new error_1.ConfigError('CONFIG_INVALID', (0, names_1.unknownName)(`network for chain '${chain.id}'`, Object.keys(chain.networks)));
+        }
+        return network;
+    }
+    clone() {
+        const copy = new ChainCatalog();
+        for (const chain of this.#chains.values())
+            copy.#chains.set(chain.id, chain);
+        return copy;
+    }
+}
+exports.ChainCatalog = ChainCatalog;
+function validateChain(chain) {
+    const fail = (reason) => {
+        throw new error_1.ConfigError('CONFIG_INVALID', `invalid chain '${chain.id}': ${reason}`);
+    };
+    if (!/^[a-z][a-z0-9-]*$/.test(chain.id))
+        fail('id must be lowercase kebab-case');
+    if (!chain.networks[chain.defaultNetwork]) {
+        fail(`default network '${chain.defaultNetwork}' is not defined`);
+    }
+    const { decimals } = chain.nativeAsset;
+    if (!Number.isInteger(decimals) || decimals < 0 || decimals > 255) {
+        fail('native asset decimals must be an integer in [0, 255]');
+    }
+    if (chain.schemes.length === 0)
+        fail('at least one signature scheme is required');
+    if (chain.xpubNetworkClass !== undefined &&
+        typeof chain.xpubNetworkClass !== 'boolean') {
+        fail('xpubNetworkClass must be a boolean');
+    }
+    for (const [key, network] of Object.entries(chain.networks)) {
+        if (network.id !== key)
+            fail(`network key '${key}' does not match its id '${network.id}'`);
+        if (!Number.isInteger(network.reorgWindow) || network.reorgWindow < 1) {
+            fail(`network '${key}': reorgWindow must be a positive integer`);
+        }
+        if (!Number.isInteger(network.defaultConfirmations) ||
+            network.defaultConfirmations < 1) {
+            fail(`network '${key}': defaultConfirmations must be a positive integer`);
+        }
+    }
+}
+//# sourceMappingURL=chains.js.map

package/dist/core/registry/chains.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chains.js","sourceRoot":"","sources":["../../../src/core/registry/chains.ts"],"names":[],"mappings":"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","sourcesContent":["import { ConfigError } from '../errors/error';\nimport type { ChainInfo, NetworkInfo } from '../model/chain';\nimport { unknownName } from '../util/names';\n\nexport class ChainCatalog {\n  readonly #chains = new Map<string, ChainInfo>();\n\n  register(chain: ChainInfo): void {\n    validateChain(chain);\n    if (this.#chains.has(chain.id)) {\n      throw new ConfigError(\n        'CONFIG_INVALID',\n        `chain '${chain.id}' is already registered`,\n      );\n    }\n    this.#chains.set(chain.id, Object.freeze({ ...chain }));\n  }\n\n  has(id: string): boolean {\n    return this.#chains.has(id);\n  }\n\n  get(id: string): ChainInfo {\n    const chain = this.#chains.get(id);\n    if (!chain) {\n      // The caller's text (perhaps a pasted secret) is never repeated; the registered\n      // chains are listed.\n      throw new ConfigError('CONFIG_INVALID', unknownName('chain', this.#chains.keys()));\n    }\n    return chain;\n  }\n\n  list(): ChainInfo[] {\n    return [...this.#chains.values()];\n  }\n\n  network(chainId: string, networkId: string): NetworkInfo {\n    const chain = this.get(chainId);\n    // Own keys only: `toString` or `constructor` is not a network.\n    const network = Object.hasOwn(chain.networks, networkId)\n      ? chain.networks[networkId]\n      : undefined;\n    if (!network) {\n      throw new ConfigError(\n        'CONFIG_INVALID',\n        unknownName(`network for chain '${chain.id}'`, Object.keys(chain.networks)),\n      );\n    }\n    return network;\n  }\n\n  clone(): ChainCatalog {\n    const copy = new ChainCatalog();\n    for (const chain of this.#chains.values()) copy.#chains.set(chain.id, chain);\n    return copy;\n  }\n}\n\nfunction validateChain(chain: ChainInfo): void {\n  const fail = (reason: string): never => {\n    throw new ConfigError('CONFIG_INVALID', `invalid chain '${chain.id}': ${reason}`);\n  };\n  if (!/^[a-z][a-z0-9-]*$/.test(chain.id)) fail('id must be lowercase kebab-case');\n  if (!chain.networks[chain.defaultNetwork]) {\n    fail(`default network '${chain.defaultNetwork}' is not defined`);\n  }\n  const { decimals } = chain.nativeAsset;\n  if (!Number.isInteger(decimals) || decimals < 0 || decimals > 255) {\n    fail('native asset decimals must be an integer in [0, 255]');\n  }\n  if (chain.schemes.length === 0) fail('at least one signature scheme is required');\n  if (\n    chain.xpubNetworkClass !== undefined &&\n    typeof chain.xpubNetworkClass !== 'boolean'\n  ) {\n    fail('xpubNetworkClass must be a boolean');\n  }\n  for (const [key, network] of Object.entries(chain.networks)) {\n    if (network.id !== key)\n      fail(`network key '${key}' does not match its id '${network.id}'`);\n    if (!Number.isInteger(network.reorgWindow) || network.reorgWindow < 1) {\n      fail(`network '${key}': reorgWindow must be a positive integer`);\n    }\n    if (\n      !Number.isInteger(network.defaultConfirmations) ||\n      network.defaultConfirmations < 1\n    ) {\n      fail(`network '${key}': defaultConfirmations must be a positive integer`);\n    }\n  }\n}\n"]}

package/dist/core/registry/plugin.d.ts

@@ -0,0 +1,41 @@
+import type { AdapterManifest } from '../driver/types';
+import type { ChainInfo } from '../model/chain';
+import { AdapterCatalog } from './adapters';
+import { AssetCatalog, type AssetRegistration } from './assets';
+import { ChainCatalog } from './chains';
+import { PresetCatalog, type ProviderPreset } from './providers';
+import { SchemeCatalog, type SignatureScheme } from './schemes';
+/** Everything a chain family contributes. Plugin modules must not import SDKs. */
+export interface Plugin {
+    readonly name: string;
+    readonly chains?: readonly ChainInfo[];
+    readonly adapters?: readonly AdapterManifest[];
+    readonly presets?: readonly ProviderPreset[];
+    readonly assets?: readonly AssetRegistration[];
+    readonly schemes?: readonly SignatureScheme[];
+}
+export interface Catalogs {
+    readonly chains: ChainCatalog;
+    readonly assets: AssetCatalog;
+    readonly adapters: AdapterCatalog;
+    readonly presets: PresetCatalog;
+    readonly schemes: SchemeCatalog;
+    /** Every registered plugin by name, to tell a repeat from a different plugin. */
+    readonly plugins: Map<string, Plugin>;
+}
+export declare function createCatalogs(): Catalogs;
+export declare function cloneCatalogs(catalogs: Catalogs): Catalogs;
+/**
+ * Registers a plugin. Registering the same plugin again (`samePlugin`) is a no-op, so
+ * `use()` stays idempotent; a different plugin under a registered name is `CONFIG_INVALID`.
+ */
+export declare function applyPlugin(catalogs: Catalogs, plugin: Plugin): void;
+/**
+ * Whether two plugins are the same: the same object, or structurally equal
+ * data around the same functions. Functions and class instances match only themselves (a
+ * closure over other values, or a bound function, is another function), so a factory
+ * such as `evmPlugin()` keeps its functions at module level to stay idempotent. Data is
+ * every own enumerable key, symbols included, and every array index: a hole matches only
+ * a hole.
+ */
+export declare function samePlugin(a: Plugin, b: Plugin): boolean;