crypto-aio 0.0.3 → 0.1.0

package/dist/core/transport/types.d.ts

@@ -0,0 +1,144 @@
+import type { Secret } from '../secret/secret';
+export type RetryClass = 'safe' | 'ambiguous-on-failure' | 'never-auto';
+export type RequestPurpose = 'read' | 'monitor' | 'proof' | 'broadcast';
+export interface EndpointConfig {
+    readonly name?: string;
+    readonly url: string | Secret<string>;
+    readonly kind?: 'rpc' | 'indexer';
+    readonly headers?: Readonly<Record<string, string | Secret<string>>>;
+    readonly priority?: number;
+    readonly rateLimit?: {
+        readonly rps: number;
+        readonly burst?: number;
+    };
+    readonly timeoutMs?: number;
+}
+export interface TransportOptions {
+    readonly fetch?: typeof fetch;
+    readonly maxAttempts?: number;
+    readonly baseDelayMs?: number;
+    readonly maxDelayMs?: number;
+    readonly timeoutMs?: number;
+    readonly maxLagBlocks?: number;
+    readonly proofQuorum?: number;
+    readonly failureThreshold?: number;
+    readonly openMs?: number;
+    readonly healthIntervalMs?: number;
+    /**
+     * The most bytes one answer may carry (default 64 MiB). A longer answer, by its declared
+     * length or as it arrives, is cancelled and fails as a retryable `PROVIDER_UNAVAILABLE`,
+     * so one endpoint can never make a call hold unbounded memory.
+     */
+    readonly maxResponseBytes?: number;
+}
+export interface CallOptions {
+    readonly retry?: RetryClass;
+    readonly purpose?: RequestPurpose;
+    /**
+     * Independent endpoints that must agree; `'proof'` uses `proofQuorum`, capped by the
+     * endpoints the quorum counts. A proof quorum (`'proof'` under any purpose, or any quorum
+     * for a monitor or proof purpose) with probes configured counts every endpoint not proven
+     * mismatched until three health refreshes in a row, at most one per `healthIntervalMs`,
+     * fail its probes or find its requests failing (its circuit breaker not closed), even
+     * while it cannot answer, so a shortfall decides nothing (a retryable
+     * `PROVIDER_UNAVAILABLE`); any other quorum counts the usable endpoints. An endpoint out
+     * of a proof quorum's count never answers toward the read: while its circuit breaker is
+     * half-open it is tried alongside the others (the read waits for that trial, up to its
+     * timeout, unless the endpoint has no rate-limit token free), and its disagreement or
+     * refusal can only block the read. In a proof quorum, a definitive error decides only when
+     * every endpoint asked returns an equivalent one: the same error code, HTTP status and
+     * JSON-RPC code, and for a JSON-RPC code each server defines (-32000 to -32099, and
+     * -32603) the same message. Otherwise the read is a retryable `PROVIDER_INCONSISTENT`.
+     */
+    readonly quorum?: number | 'proof';
+    /**
+     * The part of each endpoint's result that must agree under `quorum` (default: the whole
+     * result). Lets a caller compare consensus facts only, e.g. a block's number, hash and
+     * parent hash, not fields that node implementations format differently. The call still
+     * resolves with the first endpoint's whole result. A key that throws on any result counts
+     * as a disagreement (a retryable `PROVIDER_INCONSISTENT`).
+     */
+    readonly quorumKey?: (result: unknown) => unknown;
+    /**
+     * Parse JSON answers with exact integers: an integer outside the safe range becomes a
+     * `bigint` instead of a rounded number (`rpc`, `rpcRaw` and `http`; health probes always
+     * parse plainly). A quorum key sees the revived values.
+     */
+    readonly exactIntegers?: boolean;
+    /** Send to this many endpoints concurrently (raw-transaction broadcasts). */
+    readonly fanout?: number;
+    readonly signal?: AbortSignal;
+    readonly timeoutMs?: number;
+}
+export interface HttpRequest {
+    readonly method: 'GET' | 'POST';
+    readonly path: string;
+    readonly query?: Readonly<Record<string, string>>;
+    readonly body?: unknown;
+    readonly headers?: Readonly<Record<string, string>>;
+    readonly responseType?: 'json' | 'text';
+    /**
+     * Low-cardinality template label used for event and log method fields instead of the
+     * raw path, e.g. `'/address/:address/utxo'`. Must contain no identifiers (addresses,
+     * hashes, ids). When omitted, events fall back to the bare HTTP method.
+     */
+    readonly route?: string;
+}
+/** Single-attempt calls against one specific endpoint (used by health probes). */
+export interface EndpointCall {
+    rpc<T = unknown>(method: string, params?: unknown): Promise<T>;
+    http<T = unknown>(request: HttpRequest): Promise<T>;
+}
+export interface HealthProbes {
+    readonly identity?: (call: EndpointCall) => Promise<string>;
+    readonly expectedIdentity?: string;
+    readonly height?: (call: EndpointCall) => Promise<bigint>;
+}
+export type EndpointState = 'healthy' | 'lagging' | 'open' | 'half-open' | 'disabled' | 'unknown';
+export interface EndpointStatus {
+    readonly id: string;
+    readonly kind: 'rpc' | 'indexer';
+    readonly state: EndpointState;
+    readonly failures: number;
+    readonly height?: bigint;
+    readonly lag?: bigint;
+    readonly latencyMs?: number;
+    readonly reason?: string;
+}
+export interface Transport {
+    readonly id: string;
+    rpc<T = unknown>(method: string, params?: unknown, options?: CallOptions): Promise<T>;
+    /** Posts an arbitrary JSON-RPC payload (single or batch) and returns the parsed body. */
+    rpcRaw(payload: unknown, options?: CallOptions): Promise<unknown>;
+    http<T = unknown>(request: HttpRequest, options?: CallOptions): Promise<T>;
+    /** fetch-compatible function for SDKs; only `PLACEHOLDER_ORIGIN` URLs are accepted. */
+    createFetch(classify?: (url: URL, init: RequestInit | undefined) => CallOptions): typeof fetch;
+    setProbes(probes: HealthProbes): void;
+    /** Whether any health probe (`identity` and/or `height`) has ever been configured via
+     * `setProbes`. A transport with none configured can never mark an endpoint 'healthy' or
+     * 'lagging' — its endpoints stay 'unknown' forever, which callers like `Blockchain.ready()`
+     * treat as acceptable only in that case. */
+    hasProbes(): boolean;
+    refreshHealth(signal?: AbortSignal): Promise<void>;
+    ensureFreshHealth(signal?: AbortSignal): Promise<void>;
+    status(): EndpointStatus[];
+    /**
+     * Highest verified block height: a high-water mark (the stale-view guard of monitors
+     * and scanners). It drops in two cases only: a height taken before an identity probe
+     * existed stops counting once its endpoint turns out to serve another network, and a
+     * peak that no verified endpoint comes within `maxLagBlocks` of for three health
+     * refreshes in a row falls back to the verified best, so one forged far-future head
+     * cannot keep every view stale until restart.
+     */
+    highestHeight(): bigint | undefined;
+    /**
+     * The lag tolerance in effect (`TransportOptions.maxLagBlocks`). The driver pool
+     * resolves it in this order: the chain's `maxLagBlocks` config, else the root
+     * `transport.maxLagBlocks`, else the plugin network's own, else the built-in default.
+     * An endpoint further behind is lagging, and a view further behind `highestHeight()` is
+     * stale.
+     */
+    readonly maxLagBlocks: number;
+}
+/** SDKs are configured with this origin; the transport maps it onto real endpoints. */
+export declare const PLACEHOLDER_ORIGIN = "https://transport.crypto-aio.invalid";

package/dist/core/transport/types.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PLACEHOLDER_ORIGIN = void 0;
+/** SDKs are configured with this origin; the transport maps it onto real endpoints. */
+exports.PLACEHOLDER_ORIGIN = 'https://transport.crypto-aio.invalid';
+//# sourceMappingURL=types.js.map

package/dist/core/transport/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/core/transport/types.ts"],"names":[],"mappings":";;;AAyJA,uFAAuF;AAC1E,QAAA,kBAAkB,GAAG,sCAAsC,CAAC","sourcesContent":["import type { Secret } from '../secret/secret';\n\nexport type RetryClass = 'safe' | 'ambiguous-on-failure' | 'never-auto';\nexport type RequestPurpose = 'read' | 'monitor' | 'proof' | 'broadcast';\n\nexport interface EndpointConfig {\n  readonly name?: string;\n  readonly url: string | Secret<string>;\n  readonly kind?: 'rpc' | 'indexer';\n  readonly headers?: Readonly<Record<string, string | Secret<string>>>;\n  readonly priority?: number;\n  readonly rateLimit?: { readonly rps: number; readonly burst?: number };\n  readonly timeoutMs?: number;\n}\n\nexport interface TransportOptions {\n  readonly fetch?: typeof fetch;\n  readonly maxAttempts?: number;\n  readonly baseDelayMs?: number;\n  readonly maxDelayMs?: number;\n  readonly timeoutMs?: number;\n  readonly maxLagBlocks?: number;\n  readonly proofQuorum?: number;\n  readonly failureThreshold?: number;\n  readonly openMs?: number;\n  readonly healthIntervalMs?: number;\n  /**\n   * The most bytes one answer may carry (default 64 MiB). A longer answer, by its declared\n   * length or as it arrives, is cancelled and fails as a retryable `PROVIDER_UNAVAILABLE`,\n   * so one endpoint can never make a call hold unbounded memory.\n   */\n  readonly maxResponseBytes?: number;\n}\n\nexport interface CallOptions {\n  readonly retry?: RetryClass;\n  readonly purpose?: RequestPurpose;\n  /**\n   * Independent endpoints that must agree; `'proof'` uses `proofQuorum`, capped by the\n   * endpoints the quorum counts. A proof quorum (`'proof'` under any purpose, or any quorum\n   * for a monitor or proof purpose) with probes configured counts every endpoint not proven\n   * mismatched until three health refreshes in a row, at most one per `healthIntervalMs`,\n   * fail its probes or find its requests failing (its circuit breaker not closed), even\n   * while it cannot answer, so a shortfall decides nothing (a retryable\n   * `PROVIDER_UNAVAILABLE`); any other quorum counts the usable endpoints. An endpoint out\n   * of a proof quorum's count never answers toward the read: while its circuit breaker is\n   * half-open it is tried alongside the others (the read waits for that trial, up to its\n   * timeout, unless the endpoint has no rate-limit token free), and its disagreement or\n   * refusal can only block the read. In a proof quorum, a definitive error decides only when\n   * every endpoint asked returns an equivalent one: the same error code, HTTP status and\n   * JSON-RPC code, and for a JSON-RPC code each server defines (-32000 to -32099, and\n   * -32603) the same message. Otherwise the read is a retryable `PROVIDER_INCONSISTENT`.\n   */\n  readonly quorum?: number | 'proof';\n  /**\n   * The part of each endpoint's result that must agree under `quorum` (default: the whole\n   * result). Lets a caller compare consensus facts only, e.g. a block's number, hash and\n   * parent hash, not fields that node implementations format differently. The call still\n   * resolves with the first endpoint's whole result. A key that throws on any result counts\n   * as a disagreement (a retryable `PROVIDER_INCONSISTENT`).\n   */\n  readonly quorumKey?: (result: unknown) => unknown;\n  /**\n   * Parse JSON answers with exact integers: an integer outside the safe range becomes a\n   * `bigint` instead of a rounded number (`rpc`, `rpcRaw` and `http`; health probes always\n   * parse plainly). A quorum key sees the revived values.\n   */\n  readonly exactIntegers?: boolean;\n  /** Send to this many endpoints concurrently (raw-transaction broadcasts). */\n  readonly fanout?: number;\n  readonly signal?: AbortSignal;\n  readonly timeoutMs?: number;\n}\n\nexport interface HttpRequest {\n  readonly method: 'GET' | 'POST';\n  readonly path: string;\n  readonly query?: Readonly<Record<string, string>>;\n  readonly body?: unknown;\n  readonly headers?: Readonly<Record<string, string>>;\n  readonly responseType?: 'json' | 'text';\n  /**\n   * Low-cardinality template label used for event and log method fields instead of the\n   * raw path, e.g. `'/address/:address/utxo'`. Must contain no identifiers (addresses,\n   * hashes, ids). When omitted, events fall back to the bare HTTP method.\n   */\n  readonly route?: string;\n}\n\n/** Single-attempt calls against one specific endpoint (used by health probes). */\nexport interface EndpointCall {\n  rpc<T = unknown>(method: string, params?: unknown): Promise<T>;\n  http<T = unknown>(request: HttpRequest): Promise<T>;\n}\n\nexport interface HealthProbes {\n  readonly identity?: (call: EndpointCall) => Promise<string>;\n  readonly expectedIdentity?: string;\n  readonly height?: (call: EndpointCall) => Promise<bigint>;\n}\n\nexport type EndpointState =\n  'healthy' | 'lagging' | 'open' | 'half-open' | 'disabled' | 'unknown';\n\nexport interface EndpointStatus {\n  readonly id: string;\n  readonly kind: 'rpc' | 'indexer';\n  readonly state: EndpointState;\n  readonly failures: number;\n  readonly height?: bigint;\n  readonly lag?: bigint;\n  readonly latencyMs?: number;\n  readonly reason?: string;\n}\n\nexport interface Transport {\n  readonly id: string;\n  rpc<T = unknown>(method: string, params?: unknown, options?: CallOptions): Promise<T>;\n  /** Posts an arbitrary JSON-RPC payload (single or batch) and returns the parsed body. */\n  rpcRaw(payload: unknown, options?: CallOptions): Promise<unknown>;\n  http<T = unknown>(request: HttpRequest, options?: CallOptions): Promise<T>;\n  /** fetch-compatible function for SDKs; only `PLACEHOLDER_ORIGIN` URLs are accepted. */\n  createFetch(\n    classify?: (url: URL, init: RequestInit | undefined) => CallOptions,\n  ): typeof fetch;\n  setProbes(probes: HealthProbes): void;\n  /** Whether any health probe (`identity` and/or `height`) has ever been configured via\n   * `setProbes`. A transport with none configured can never mark an endpoint 'healthy' or\n   * 'lagging' — its endpoints stay 'unknown' forever, which callers like `Blockchain.ready()`\n   * treat as acceptable only in that case. */\n  hasProbes(): boolean;\n  refreshHealth(signal?: AbortSignal): Promise<void>;\n  ensureFreshHealth(signal?: AbortSignal): Promise<void>;\n  status(): EndpointStatus[];\n  /**\n   * Highest verified block height: a high-water mark (the stale-view guard of monitors\n   * and scanners). It drops in two cases only: a height taken before an identity probe\n   * existed stops counting once its endpoint turns out to serve another network, and a\n   * peak that no verified endpoint comes within `maxLagBlocks` of for three health\n   * refreshes in a row falls back to the verified best, so one forged far-future head\n   * cannot keep every view stale until restart.\n   */\n  highestHeight(): bigint | undefined;\n  /**\n   * The lag tolerance in effect (`TransportOptions.maxLagBlocks`). The driver pool\n   * resolves it in this order: the chain's `maxLagBlocks` config, else the root\n   * `transport.maxLagBlocks`, else the plugin network's own, else the built-in default.\n   * An endpoint further behind is lagging, and a view further behind `highestHeight()` is\n   * stale.\n   */\n  readonly maxLagBlocks: number;\n}\n\n/** SDKs are configured with this origin; the transport maps it onto real endpoints. */\nexport const PLACEHOLDER_ORIGIN = 'https://transport.crypto-aio.invalid';\n"]}

package/dist/core/util/bytes.d.ts

@@ -0,0 +1,9 @@
+import { concatBytes, randomBytes, utf8ToBytes } from '@noble/hashes/utils';
+export { concatBytes, randomBytes, utf8ToBytes };
+/** Decodes hex with or without a `0x` prefix. Throws `TypeError` on malformed input. */
+export declare function fromHex(hex: string): Uint8Array;
+export declare function toHex(bytes: Uint8Array, prefix?: boolean): string;
+export declare function bytesToUtf8(bytes: Uint8Array): string;
+/** Length-checked comparison that does not stop at the first differing byte. */
+export declare function equalBytes(a: Uint8Array, b: Uint8Array): boolean;
+export declare function randomId(prefix: string): string;

package/dist/core/util/bytes.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.utf8ToBytes = exports.randomBytes = exports.concatBytes = void 0;
+exports.fromHex = fromHex;
+exports.toHex = toHex;
+exports.bytesToUtf8 = bytesToUtf8;
+exports.equalBytes = equalBytes;
+exports.randomId = randomId;
+const utils_1 = require("@noble/hashes/utils");
+Object.defineProperty(exports, "concatBytes", { enumerable: true, get: function () { return utils_1.concatBytes; } });
+Object.defineProperty(exports, "randomBytes", { enumerable: true, get: function () { return utils_1.randomBytes; } });
+Object.defineProperty(exports, "utf8ToBytes", { enumerable: true, get: function () { return utils_1.utf8ToBytes; } });
+/** Decodes hex with or without a `0x` prefix. Throws `TypeError` on malformed input. */
+function fromHex(hex) {
+    const clean = hex.startsWith('0x') || hex.startsWith('0X') ? hex.slice(2) : hex;
+    if (clean.length % 2 !== 0 || !/^[0-9a-fA-F]*$/.test(clean)) {
+        throw new TypeError('invalid hex string');
+    }
+    return (0, utils_1.hexToBytes)(clean);
+}
+function toHex(bytes, prefix = false) {
+    const hex = (0, utils_1.bytesToHex)(bytes);
+    return prefix ? `0x${hex}` : hex;
+}
+function bytesToUtf8(bytes) {
+    return new TextDecoder().decode(bytes);
+}
+/** Length-checked comparison that does not stop at the first differing byte. */
+function equalBytes(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i++)
+        diff |= (a[i] ?? 0) ^ (b[i] ?? 0);
+    return diff === 0;
+}
+function randomId(prefix) {
+    return `${prefix}_${(0, utils_1.bytesToHex)((0, utils_1.randomBytes)(12))}`;
+}
+//# sourceMappingURL=bytes.js.map

package/dist/core/util/bytes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bytes.js","sourceRoot":"","sources":["../../../src/core/util/bytes.ts"],"names":[],"mappings":";;;AAWA,0BAMC;AAED,sBAGC;AAED,kCAEC;AAGD,gCAKC;AAED,4BAEC;AAtCD,+CAM6B;AAEpB,4FANP,mBAAW,OAMO;AAAE,4FAJpB,mBAAW,OAIoB;AAAE,4FAHjC,mBAAW,OAGiC;AAE9C,wFAAwF;AACxF,SAAgB,OAAO,CAAC,GAAW;IACjC,MAAM,KAAK,GAAG,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;IAChF,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAC5D,MAAM,IAAI,SAAS,CAAC,oBAAoB,CAAC,CAAC;IAC5C,CAAC;IACD,OAAO,IAAA,kBAAU,EAAC,KAAK,CAAC,CAAC;AAC3B,CAAC;AAED,SAAgB,KAAK,CAAC,KAAiB,EAAE,MAAM,GAAG,KAAK;IACrD,MAAM,GAAG,GAAG,IAAA,kBAAU,EAAC,KAAK,CAAC,CAAC;IAC9B,OAAO,MAAM,CAAC,CAAC,CAAC,KAAK,GAAG,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC;AACnC,CAAC;AAED,SAAgB,WAAW,CAAC,KAAiB;IAC3C,OAAO,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACzC,CAAC;AAED,gFAAgF;AAChF,SAAgB,UAAU,CAAC,CAAa,EAAE,CAAa;IACrD,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IACxC,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE;QAAE,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;IACrE,OAAO,IAAI,KAAK,CAAC,CAAC;AACpB,CAAC;AAED,SAAgB,QAAQ,CAAC,MAAc;IACrC,OAAO,GAAG,MAAM,IAAI,IAAA,kBAAU,EAAC,IAAA,mBAAW,EAAC,EAAE,CAAC,CAAC,EAAE,CAAC;AACpD,CAAC","sourcesContent":["import {\n  bytesToHex,\n  concatBytes,\n  hexToBytes,\n  randomBytes,\n  utf8ToBytes,\n} from '@noble/hashes/utils';\n\nexport { concatBytes, randomBytes, utf8ToBytes };\n\n/** Decodes hex with or without a `0x` prefix. Throws `TypeError` on malformed input. */\nexport function fromHex(hex: string): Uint8Array {\n  const clean = hex.startsWith('0x') || hex.startsWith('0X') ? hex.slice(2) : hex;\n  if (clean.length % 2 !== 0 || !/^[0-9a-fA-F]*$/.test(clean)) {\n    throw new TypeError('invalid hex string');\n  }\n  return hexToBytes(clean);\n}\n\nexport function toHex(bytes: Uint8Array, prefix = false): string {\n  const hex = bytesToHex(bytes);\n  return prefix ? `0x${hex}` : hex;\n}\n\nexport function bytesToUtf8(bytes: Uint8Array): string {\n  return new TextDecoder().decode(bytes);\n}\n\n/** Length-checked comparison that does not stop at the first differing byte. */\nexport function equalBytes(a: Uint8Array, b: Uint8Array): boolean {\n  if (a.length !== b.length) return false;\n  let diff = 0;\n  for (let i = 0; i < a.length; i++) diff |= (a[i] ?? 0) ^ (b[i] ?? 0);\n  return diff === 0;\n}\n\nexport function randomId(prefix: string): string {\n  return `${prefix}_${bytesToHex(randomBytes(12))}`;\n}\n"]}

package/dist/core/util/clock.d.ts

@@ -0,0 +1,6 @@
+export interface Clock {
+    now(): number;
+    sleep(ms: number, signal?: AbortSignal): Promise<void>;
+}
+export declare function abortReason(signal: AbortSignal): unknown;
+export declare const systemClock: Clock;

package/dist/core/util/clock.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.systemClock = void 0;
+exports.abortReason = abortReason;
+function abortReason(signal) {
+    return signal.reason ?? new Error('The operation was aborted');
+}
+exports.systemClock = {
+    now: () => Date.now(),
+    sleep: (ms, signal) => new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(abortReason(signal));
+            return;
+        }
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(abortReason(signal));
+        };
+        const timer = setTimeout(() => {
+            signal?.removeEventListener('abort', onAbort);
+            resolve();
+        }, Math.max(0, ms));
+        signal?.addEventListener('abort', onAbort, { once: true });
+    }),
+};
+//# sourceMappingURL=clock.js.map

package/dist/core/util/clock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clock.js","sourceRoot":"","sources":["../../../src/core/util/clock.ts"],"names":[],"mappings":";;;AAKA,kCAEC;AAFD,SAAgB,WAAW,CAAC,MAAmB;IAC7C,OAAO,MAAM,CAAC,MAAM,IAAI,IAAI,KAAK,CAAC,2BAA2B,CAAC,CAAC;AACjE,CAAC;AAEY,QAAA,WAAW,GAAU;IAChC,GAAG,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE;IACrB,KAAK,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,CACpB,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACpC,IAAI,MAAM,EAAE,OAAO,EAAE,CAAC;YACpB,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC;YAC5B,OAAO;QACT,CAAC;QACD,MAAM,OAAO,GAAG,GAAG,EAAE;YACnB,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,MAAM,CAAC,WAAW,CAAC,MAAqB,CAAC,CAAC,CAAC;QAC7C,CAAC,CAAC;QACF,MAAM,KAAK,GAAG,UAAU,CACtB,GAAG,EAAE;YACH,MAAM,EAAE,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YAC9C,OAAO,EAAE,CAAC;QACZ,CAAC,EACD,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,CAAC,CAChB,CAAC;QACF,MAAM,EAAE,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IAC7D,CAAC,CAAC;CACL,CAAC","sourcesContent":["export interface Clock {\n  now(): number;\n  sleep(ms: number, signal?: AbortSignal): Promise<void>;\n}\n\nexport function abortReason(signal: AbortSignal): unknown {\n  return signal.reason ?? new Error('The operation was aborted');\n}\n\nexport const systemClock: Clock = {\n  now: () => Date.now(),\n  sleep: (ms, signal) =>\n    new Promise<void>((resolve, reject) => {\n      if (signal?.aborted) {\n        reject(abortReason(signal));\n        return;\n      }\n      const onAbort = () => {\n        clearTimeout(timer);\n        reject(abortReason(signal as AbortSignal));\n      };\n      const timer = setTimeout(\n        () => {\n          signal?.removeEventListener('abort', onAbort);\n          resolve();\n        },\n        Math.max(0, ms),\n      );\n      signal?.addEventListener('abort', onAbort, { once: true });\n    }),\n};\n"]}

package/dist/core/util/freeze.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Freezes plain data all the way down: every array and every plain object reachable
+ * from `value`, so data that handles share (chain tables, presets, resolved config) cannot
+ * be changed through any of them. Class instances (a `Signer`, a `Secret`, a `Uint8Array`)
+ * and functions keep their identity and are never frozen. A reference cycle is
+ * walked once, so it freezes instead of overflowing the stack.
+ */
+export declare function deepFreeze<T>(value: T): T;

package/dist/core/util/freeze.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deepFreeze = deepFreeze;
+/**
+ * Freezes plain data all the way down: every array and every plain object reachable
+ * from `value`, so data that handles share (chain tables, presets, resolved config) cannot
+ * be changed through any of them. Class instances (a `Signer`, a `Secret`, a `Uint8Array`)
+ * and functions keep their identity and are never frozen. A reference cycle is
+ * walked once, so it freezes instead of overflowing the stack.
+ */
+function deepFreeze(value) {
+    freezeOnce(value, new WeakSet());
+    return value;
+}
+function freezeOnce(value, seen) {
+    if (!isPlainData(value) || seen.has(value))
+        return;
+    seen.add(value);
+    for (const item of Object.values(value))
+        freezeOnce(item, seen);
+    Object.freeze(value);
+}
+function isPlainData(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    if (Array.isArray(value))
+        return true;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+//# sourceMappingURL=freeze.js.map

package/dist/core/util/freeze.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"freeze.js","sourceRoot":"","sources":["../../../src/core/util/freeze.ts"],"names":[],"mappings":";;AAOA,gCAGC;AAVD;;;;;;GAMG;AACH,SAAgB,UAAU,CAAI,KAAQ;IACpC,UAAU,CAAC,KAAK,EAAE,IAAI,OAAO,EAAU,CAAC,CAAC;IACzC,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,UAAU,CAAC,KAAc,EAAE,IAAqB;IACvD,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC;QAAE,OAAO;IACnD,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IAChB,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC;QAAE,UAAU,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAChE,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACvB,CAAC;AAED,SAAS,WAAW,CAAC,KAAc;IACjC,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC9D,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACtC,MAAM,KAAK,GAAY,MAAM,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;IACpD,OAAO,KAAK,KAAK,MAAM,CAAC,SAAS,IAAI,KAAK,KAAK,IAAI,CAAC;AACtD,CAAC","sourcesContent":["/**\n * Freezes plain data all the way down: every array and every plain object reachable\n * from `value`, so data that handles share (chain tables, presets, resolved config) cannot\n * be changed through any of them. Class instances (a `Signer`, a `Secret`, a `Uint8Array`)\n * and functions keep their identity and are never frozen. A reference cycle is\n * walked once, so it freezes instead of overflowing the stack.\n */\nexport function deepFreeze<T>(value: T): T {\n  freezeOnce(value, new WeakSet<object>());\n  return value;\n}\n\nfunction freezeOnce(value: unknown, seen: WeakSet<object>): void {\n  if (!isPlainData(value) || seen.has(value)) return;\n  seen.add(value);\n  for (const item of Object.values(value)) freezeOnce(item, seen);\n  Object.freeze(value);\n}\n\nfunction isPlainData(value: unknown): value is object {\n  if (value === null || typeof value !== 'object') return false;\n  if (Array.isArray(value)) return true;\n  const proto: unknown = Object.getPrototypeOf(value);\n  return proto === Object.prototype || proto === null;\n}\n"]}

package/dist/core/util/json.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Deterministic JSON for hashing: object keys sorted, `undefined` properties omitted,
+ * bigint → `{"$bigint":"<decimal>"}`, Uint8Array → `{"$bytes":"<hex>"}`.
+ */
+export declare function canonicalJson(value: unknown): string;
+/**
+ * Deterministic JSON for comparing quorum answers, which no two different values
+ * share. `canonicalJson` writes a bigint as `{"$bigint":…}` and bytes as `{"$bytes":…}`, the
+ * same text as a plain object with that key, so one endpoint's object could agree with
+ * another's bigint; it also drops a `__proto__` key. Here every plain-object key that starts
+ * with `$` gains one more `$`, and `__proto__` becomes `$__proto__`, before tagging, so no
+ * two keys become one and no plain object's key is ever `$bigint` or `$bytes`.
+ * `canonicalJson` itself is unchanged: the intent hash depends on it.
+ */
+export declare function quorumJson(value: unknown): string;
+/**
+ * `JSON.parse`, optionally exact for integers: with `exactIntegers`, every integer
+ * literal outside the safe range becomes a `bigint` read from its source text (Node ≥ 22
+ * `JSON.parse` source text access), so a u64 amount is never rounded. Safe integers,
+ * fractions and exponents stay numbers, so answers keep their shape for ordinary values.
+ * With the flag, an integer literal longer than 80 digits (sign excluded) is malformed and
+ * throws a `SyntaxError`, as `JSON.parse` does: no amount is that long (u256 has 78 digits),
+ * and `BigInt()` of a multi-megabyte literal would take seconds.
+ */
+export declare function parseJson(text: string, exactIntegers?: boolean): unknown;
+export declare function sha256Hex(input: string | Uint8Array): string;
+/** JSON that round-trips bigint and Uint8Array (for external store implementations). */
+export declare function stringifyTagged(value: unknown): string;
+export declare function parseTagged<T = unknown>(text: string): T;

package/dist/core/util/json.js

@@ -0,0 +1,165 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.canonicalJson = canonicalJson;
+exports.quorumJson = quorumJson;
+exports.parseJson = parseJson;
+exports.sha256Hex = sha256Hex;
+exports.stringifyTagged = stringifyTagged;
+exports.parseTagged = parseTagged;
+const sha256_1 = require("@noble/hashes/sha256");
+const utils_1 = require("@noble/hashes/utils");
+const bytes_1 = require("./bytes");
+/**
+ * Deterministic JSON for hashing: object keys sorted, `undefined` properties omitted,
+ * bigint → `{"$bigint":"<decimal>"}`, Uint8Array → `{"$bytes":"<hex>"}`.
+ */
+function canonicalJson(value) {
+    return JSON.stringify(canonicalize(value, new WeakSet()));
+}
+function canonicalize(value, seen) {
+    if (value === null)
+        return null;
+    switch (typeof value) {
+        case 'string':
+        case 'boolean':
+            return value;
+        case 'number':
+            if (!Number.isFinite(value))
+                throw new TypeError('canonicalJson: non-finite number');
+            return value;
+        case 'bigint':
+            return { $bigint: value.toString() };
+        case 'undefined':
+            return undefined;
+        case 'object':
+            break;
+        default:
+            throw new TypeError(`canonicalJson: unsupported type ${typeof value}`);
+    }
+    if (value instanceof Uint8Array)
+        return { $bytes: (0, bytes_1.toHex)(value) };
+    if (seen.has(value))
+        throw new TypeError('canonicalJson: circular structure');
+    seen.add(value);
+    try {
+        if (Array.isArray(value)) {
+            return value.map((item) => {
+                const c = canonicalize(item, seen);
+                return c === undefined ? null : c;
+            });
+        }
+        const proto = Object.getPrototypeOf(value);
+        if (proto !== Object.prototype && proto !== null) {
+            const toJSON = value.toJSON;
+            if (typeof toJSON === 'function')
+                return canonicalize(toJSON.call(value), seen);
+            throw new TypeError('canonicalJson: only plain objects are supported');
+        }
+        const out = {};
+        for (const key of Object.keys(value).sort()) {
+            const c = canonicalize(value[key], seen);
+            if (c !== undefined)
+                out[key] = c;
+        }
+        return out;
+    }
+    finally {
+        seen.delete(value);
+    }
+}
+/**
+ * Deterministic JSON for comparing quorum answers, which no two different values
+ * share. `canonicalJson` writes a bigint as `{"$bigint":…}` and bytes as `{"$bytes":…}`, the
+ * same text as a plain object with that key, so one endpoint's object could agree with
+ * another's bigint; it also drops a `__proto__` key. Here every plain-object key that starts
+ * with `$` gains one more `$`, and `__proto__` becomes `$__proto__`, before tagging, so no
+ * two keys become one and no plain object's key is ever `$bigint` or `$bytes`.
+ * `canonicalJson` itself is unchanged: the intent hash depends on it.
+ */
+function quorumJson(value) {
+    return canonicalJson(escapeKeys(value, new WeakSet()));
+}
+/** `value` with the keys of its plain objects escaped as `quorumJson` describes. */
+function escapeKeys(value, seen) {
+    if (value === null || typeof value !== 'object' || value instanceof Uint8Array)
+        return value;
+    if (seen.has(value))
+        throw new TypeError('canonicalJson: circular structure');
+    seen.add(value);
+    try {
+        if (Array.isArray(value))
+            return value.map((item) => escapeKeys(item, seen));
+        const proto = Object.getPrototypeOf(value);
+        if (proto !== Object.prototype && proto !== null) {
+            // As canonicalJson reads it: its toJSON() value, or (without one) a TypeError there.
+            const toJSON = value.toJSON;
+            return typeof toJSON === 'function' ? escapeKeys(toJSON.call(value), seen) : value;
+        }
+        const out = {};
+        for (const key of Object.keys(value)) {
+            const escaped = key.startsWith('$') || key === '__proto__' ? `$${key}` : key;
+            out[escaped] = escapeKeys(value[key], seen);
+        }
+        return out;
+    }
+    finally {
+        seen.delete(value);
+    }
+}
+/** The longest integer literal `parseJson` revives, in digits without the sign. */
+const MAX_EXACT_DIGITS = 80;
+/**
+ * `JSON.parse`, optionally exact for integers: with `exactIntegers`, every integer
+ * literal outside the safe range becomes a `bigint` read from its source text (Node ≥ 22
+ * `JSON.parse` source text access), so a u64 amount is never rounded. Safe integers,
+ * fractions and exponents stay numbers, so answers keep their shape for ordinary values.
+ * With the flag, an integer literal longer than 80 digits (sign excluded) is malformed and
+ * throws a `SyntaxError`, as `JSON.parse` does: no amount is that long (u256 has 78 digits),
+ * and `BigInt()` of a multi-megabyte literal would take seconds.
+ */
+function parseJson(text, exactIntegers = false) {
+    // A run of 16 digits is the shortest literal that can leave the safe range; without one,
+    // the reviver (about 7 times slower on large bodies) cannot change anything.
+    if (!exactIntegers || !/\d{16}/.test(text))
+        return JSON.parse(text);
+    return JSON.parse(text, (_key, value, context) => {
+        const source = context?.source;
+        if (typeof value !== 'number' ||
+            Number.isSafeInteger(value) ||
+            source === undefined ||
+            !/^-?\d+$/.test(source))
+            return value;
+        const digits = source.startsWith('-') ? source.length - 1 : source.length;
+        if (digits > MAX_EXACT_DIGITS)
+            throw new SyntaxError(`integer literal longer than ${MAX_EXACT_DIGITS} digits`);
+        return BigInt(source);
+    });
+}
+function sha256Hex(input) {
+    return (0, utils_1.bytesToHex)((0, sha256_1.sha256)(typeof input === 'string' ? (0, utils_1.utf8ToBytes)(input) : input));
+}
+/** JSON that round-trips bigint and Uint8Array (for external store implementations). */
+function stringifyTagged(value) {
+    return JSON.stringify(value, (_key, v) => {
+        if (typeof v === 'bigint')
+            return { $bigint: v.toString() };
+        if (v instanceof Uint8Array)
+            return { $bytes: (0, bytes_1.toHex)(v) };
+        return v;
+    });
+}
+function parseTagged(text) {
+    return JSON.parse(text, (_key, v) => {
+        if (v !== null && typeof v === 'object' && !Array.isArray(v)) {
+            const o = v;
+            if (Object.keys(o).length === 1) {
+                if (typeof o.$bigint === 'string')
+                    return BigInt(o.$bigint);
+                if (typeof o.$bytes === 'string')
+                    return (0, bytes_1.fromHex)(o.$bytes);
+            }
+        }
+        return v;
+    });
+}
+//# sourceMappingURL=json.js.map

package/dist/core/util/json.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json.js","sourceRoot":"","sources":["../../../src/core/util/json.ts"],"names":[],"mappings":"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","sourcesContent":["import { sha256 } from '@noble/hashes/sha256';\nimport { bytesToHex, utf8ToBytes } from '@noble/hashes/utils';\nimport { fromHex, toHex } from './bytes';\n\n/**\n * Deterministic JSON for hashing: object keys sorted, `undefined` properties omitted,\n * bigint → `{\"$bigint\":\"<decimal>\"}`, Uint8Array → `{\"$bytes\":\"<hex>\"}`.\n */\nexport function canonicalJson(value: unknown): string {\n  return JSON.stringify(canonicalize(value, new WeakSet()));\n}\n\nfunction canonicalize(value: unknown, seen: WeakSet<object>): unknown {\n  if (value === null) return null;\n  switch (typeof value) {\n    case 'string':\n    case 'boolean':\n      return value;\n    case 'number':\n      if (!Number.isFinite(value))\n        throw new TypeError('canonicalJson: non-finite number');\n      return value;\n    case 'bigint':\n      return { $bigint: value.toString() };\n    case 'undefined':\n      return undefined;\n    case 'object':\n      break;\n    default:\n      throw new TypeError(`canonicalJson: unsupported type ${typeof value}`);\n  }\n  if (value instanceof Uint8Array) return { $bytes: toHex(value) };\n  if (seen.has(value)) throw new TypeError('canonicalJson: circular structure');\n  seen.add(value);\n  try {\n    if (Array.isArray(value)) {\n      return value.map((item) => {\n        const c = canonicalize(item, seen);\n        return c === undefined ? null : c;\n      });\n    }\n    const proto: unknown = Object.getPrototypeOf(value);\n    if (proto !== Object.prototype && proto !== null) {\n      const toJSON = (value as { toJSON?: () => unknown }).toJSON;\n      if (typeof toJSON === 'function') return canonicalize(toJSON.call(value), seen);\n      throw new TypeError('canonicalJson: only plain objects are supported');\n    }\n    const out: Record<string, unknown> = {};\n    for (const key of Object.keys(value).sort()) {\n      const c = canonicalize((value as Record<string, unknown>)[key], seen);\n      if (c !== undefined) out[key] = c;\n    }\n    return out;\n  } finally {\n    seen.delete(value);\n  }\n}\n\n/**\n * Deterministic JSON for comparing quorum answers, which no two different values\n * share. `canonicalJson` writes a bigint as `{\"$bigint\":…}` and bytes as `{\"$bytes\":…}`, the\n * same text as a plain object with that key, so one endpoint's object could agree with\n * another's bigint; it also drops a `__proto__` key. Here every plain-object key that starts\n * with `$` gains one more `$`, and `__proto__` becomes `$__proto__`, before tagging, so no\n * two keys become one and no plain object's key is ever `$bigint` or `$bytes`.\n * `canonicalJson` itself is unchanged: the intent hash depends on it.\n */\nexport function quorumJson(value: unknown): string {\n  return canonicalJson(escapeKeys(value, new WeakSet()));\n}\n\n/** `value` with the keys of its plain objects escaped as `quorumJson` describes. */\nfunction escapeKeys(value: unknown, seen: WeakSet<object>): unknown {\n  if (value === null || typeof value !== 'object' || value instanceof Uint8Array)\n    return value;\n  if (seen.has(value)) throw new TypeError('canonicalJson: circular structure');\n  seen.add(value);\n  try {\n    if (Array.isArray(value)) return value.map((item) => escapeKeys(item, seen));\n    const proto: unknown = Object.getPrototypeOf(value);\n    if (proto !== Object.prototype && proto !== null) {\n      // As canonicalJson reads it: its toJSON() value, or (without one) a TypeError there.\n      const toJSON = (value as { toJSON?: () => unknown }).toJSON;\n      return typeof toJSON === 'function' ? escapeKeys(toJSON.call(value), seen) : value;\n    }\n    const out: Record<string, unknown> = {};\n    for (const key of Object.keys(value)) {\n      const escaped = key.startsWith('$') || key === '__proto__' ? `$${key}` : key;\n      out[escaped] = escapeKeys((value as Record<string, unknown>)[key], seen);\n    }\n    return out;\n  } finally {\n    seen.delete(value);\n  }\n}\n\n/** The longest integer literal `parseJson` revives, in digits without the sign. */\nconst MAX_EXACT_DIGITS = 80;\n\n/**\n * `JSON.parse`, optionally exact for integers: with `exactIntegers`, every integer\n * literal outside the safe range becomes a `bigint` read from its source text (Node ≥ 22\n * `JSON.parse` source text access), so a u64 amount is never rounded. Safe integers,\n * fractions and exponents stay numbers, so answers keep their shape for ordinary values.\n * With the flag, an integer literal longer than 80 digits (sign excluded) is malformed and\n * throws a `SyntaxError`, as `JSON.parse` does: no amount is that long (u256 has 78 digits),\n * and `BigInt()` of a multi-megabyte literal would take seconds.\n */\nexport function parseJson(text: string, exactIntegers = false): unknown {\n  // A run of 16 digits is the shortest literal that can leave the safe range; without one,\n  // the reviver (about 7 times slower on large bodies) cannot change anything.\n  if (!exactIntegers || !/\\d{16}/.test(text)) return JSON.parse(text);\n  return JSON.parse(\n    text,\n    (_key: string, value: unknown, context?: { readonly source?: string }) => {\n      const source = context?.source;\n      if (\n        typeof value !== 'number' ||\n        Number.isSafeInteger(value) ||\n        source === undefined ||\n        !/^-?\\d+$/.test(source)\n      )\n        return value;\n      const digits = source.startsWith('-') ? source.length - 1 : source.length;\n      if (digits > MAX_EXACT_DIGITS)\n        throw new SyntaxError(`integer literal longer than ${MAX_EXACT_DIGITS} digits`);\n      return BigInt(source);\n    },\n  );\n}\n\nexport function sha256Hex(input: string | Uint8Array): string {\n  return bytesToHex(sha256(typeof input === 'string' ? utf8ToBytes(input) : input));\n}\n\n/** JSON that round-trips bigint and Uint8Array (for external store implementations). */\nexport function stringifyTagged(value: unknown): string {\n  return JSON.stringify(value, (_key, v: unknown) => {\n    if (typeof v === 'bigint') return { $bigint: v.toString() };\n    if (v instanceof Uint8Array) return { $bytes: toHex(v) };\n    return v;\n  });\n}\n\nexport function parseTagged<T = unknown>(text: string): T {\n  return JSON.parse(text, (_key, v: unknown) => {\n    if (v !== null && typeof v === 'object' && !Array.isArray(v)) {\n      const o = v as Record<string, unknown>;\n      if (Object.keys(o).length === 1) {\n        if (typeof o.$bigint === 'string') return BigInt(o.$bigint);\n        if (typeof o.$bytes === 'string') return fromHex(o.$bytes);\n      }\n    }\n    return v;\n  }) as T;\n}\n"]}

package/dist/core/util/names.d.ts

@@ -0,0 +1,21 @@
+/**
+ * How an error names something the caller typed (a chain, network,
+ * library, provider, wallet, signer, scheme, asset alias, option key or capability). What a
+ * caller typed may be a pasted secret, so an error never repeats it, at any length: it lists
+ * the names that would have been accepted instead, which the library or the caller's own
+ * configuration defined.
+ */
+/** At most this many accepted names are listed; the rest are counted. */
+export declare const MAX_LISTED_NAMES = 12;
+/** `'a'`, `'a' and 'b'`, `'a', 'b' and 'c'`, or `'a', …, 'l' and 3 more`: sorted, unique. */
+export declare function listNames(names: Iterable<string>): string;
+/**
+ * The text of a refusal of an unknown `what`, listing the accepted names and never the
+ * caller's: `unknown network; the accepted names are 'mainnet' and 'sepolia'`.
+ */
+export declare function unknownName(what: string, accepted: Iterable<string>): string;
+/**
+ * A value as an error may show it: quoted when it is one of `known` (a fixed word of this
+ * library, such as a capability name), else `unshown`.
+ */
+export declare function knownName(value: unknown, known: readonly string[], unshown: string): string;

package/dist/core/util/names.js

@@ -0,0 +1,46 @@
+"use strict";
+/**
+ * How an error names something the caller typed (a chain, network,
+ * library, provider, wallet, signer, scheme, asset alias, option key or capability). What a
+ * caller typed may be a pasted secret, so an error never repeats it, at any length: it lists
+ * the names that would have been accepted instead, which the library or the caller's own
+ * configuration defined.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_LISTED_NAMES = void 0;
+exports.listNames = listNames;
+exports.unknownName = unknownName;
+exports.knownName = knownName;
+/** At most this many accepted names are listed; the rest are counted. */
+exports.MAX_LISTED_NAMES = 12;
+/** `'a'`, `'a' and 'b'`, `'a', 'b' and 'c'`, or `'a', …, 'l' and 3 more`: sorted, unique. */
+function listNames(names) {
+    const sorted = [...new Set(names)].sort();
+    const shown = sorted.slice(0, exports.MAX_LISTED_NAMES).map((name) => `'${name}'`);
+    const rest = sorted.length - shown.length;
+    if (rest > 0)
+        return `${shown.join(', ')} and ${rest} more`;
+    if (shown.length <= 1)
+        return shown.join('');
+    return `${shown.slice(0, -1).join(', ')} and ${shown.at(-1)}`;
+}
+/**
+ * The text of a refusal of an unknown `what`, listing the accepted names and never the
+ * caller's: `unknown network; the accepted names are 'mainnet' and 'sepolia'`.
+ */
+function unknownName(what, accepted) {
+    const names = [...new Set(accepted)];
+    if (names.length === 0)
+        return `unknown ${what}; none is configured`;
+    if (names.length === 1)
+        return `unknown ${what}; the only accepted name is ${listNames(names)}`;
+    return `unknown ${what}; the accepted names are ${listNames(names)}`;
+}
+/**
+ * A value as an error may show it: quoted when it is one of `known` (a fixed word of this
+ * library, such as a capability name), else `unshown`.
+ */
+function knownName(value, known, unshown) {
+    return typeof value === 'string' && known.includes(value) ? `'${value}'` : unshown;
+}
+//# sourceMappingURL=names.js.map

package/dist/core/util/names.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"names.js","sourceRoot":"","sources":["../../../src/core/util/names.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;;AAMH,8BAOC;AAMD,kCAMC;AAMD,8BAMC;AAnCD,yEAAyE;AAC5D,QAAA,gBAAgB,GAAG,EAAE,CAAC;AAEnC,6FAA6F;AAC7F,SAAgB,SAAS,CAAC,KAAuB;IAC/C,MAAM,MAAM,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAC1C,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,wBAAgB,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,IAAI,GAAG,CAAC,CAAC;IAC3E,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;IAC1C,IAAI,IAAI,GAAG,CAAC;QAAE,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,IAAI,OAAO,CAAC;IAC5D,IAAI,KAAK,CAAC,MAAM,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC7C,OAAO,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,CAAW,EAAE,CAAC;AAC1E,CAAC;AAED;;;GAGG;AACH,SAAgB,WAAW,CAAC,IAAY,EAAE,QAA0B;IAClE,MAAM,KAAK,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC;IACrC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,WAAW,IAAI,sBAAsB,CAAC;IACrE,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QACpB,OAAO,WAAW,IAAI,+BAA+B,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC;IAC1E,OAAO,WAAW,IAAI,4BAA4B,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC;AACvE,CAAC;AAED;;;GAGG;AACH,SAAgB,SAAS,CACvB,KAAc,EACd,KAAwB,EACxB,OAAe;IAEf,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC;AACrF,CAAC","sourcesContent":["/**\n * How an error names something the caller typed (a chain, network,\n * library, provider, wallet, signer, scheme, asset alias, option key or capability). What a\n * caller typed may be a pasted secret, so an error never repeats it, at any length: it lists\n * the names that would have been accepted instead, which the library or the caller's own\n * configuration defined.\n */\n\n/** At most this many accepted names are listed; the rest are counted. */\nexport const MAX_LISTED_NAMES = 12;\n\n/** `'a'`, `'a' and 'b'`, `'a', 'b' and 'c'`, or `'a', …, 'l' and 3 more`: sorted, unique. */\nexport function listNames(names: Iterable<string>): string {\n  const sorted = [...new Set(names)].sort();\n  const shown = sorted.slice(0, MAX_LISTED_NAMES).map((name) => `'${name}'`);\n  const rest = sorted.length - shown.length;\n  if (rest > 0) return `${shown.join(', ')} and ${rest} more`;\n  if (shown.length <= 1) return shown.join('');\n  return `${shown.slice(0, -1).join(', ')} and ${shown.at(-1) as string}`;\n}\n\n/**\n * The text of a refusal of an unknown `what`, listing the accepted names and never the\n * caller's: `unknown network; the accepted names are 'mainnet' and 'sepolia'`.\n */\nexport function unknownName(what: string, accepted: Iterable<string>): string {\n  const names = [...new Set(accepted)];\n  if (names.length === 0) return `unknown ${what}; none is configured`;\n  if (names.length === 1)\n    return `unknown ${what}; the only accepted name is ${listNames(names)}`;\n  return `unknown ${what}; the accepted names are ${listNames(names)}`;\n}\n\n/**\n * A value as an error may show it: quoted when it is one of `known` (a fixed word of this\n * library, such as a capability name), else `unshown`.\n */\nexport function knownName(\n  value: unknown,\n  known: readonly string[],\n  unshown: string,\n): string {\n  return typeof value === 'string' && known.includes(value) ? `'${value}'` : unshown;\n}\n"]}