crypto-aio 0.0.3 → 0.2.0

package/dist/core/errors/codes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codes.js","sourceRoot":"","sources":["../../../src/core/errors/codes.ts"],"names":[],"mappings":"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","sourcesContent":["export type ErrorCategory =\n  | 'config'\n  | 'unsupported'\n  | 'validation'\n  | 'provider'\n  | 'chain'\n  | 'signing'\n  | 'state'\n  | 'timeout';\n\ninterface CodeDefinition {\n  readonly category: ErrorCategory;\n  readonly retryable: boolean;\n}\n\n/** Frozen, with every entry: the table is shared by every error and every caller. */\nexport const ERROR_CODES = deepFreezeCodes({\n  CONFIG_INVALID: { category: 'config', retryable: false },\n  DEPENDENCY_MISSING: { category: 'config', retryable: false },\n  INCOMPATIBLE_SELECTION: { category: 'config', retryable: false },\n  UNSUPPORTED_CAPABILITY: { category: 'unsupported', retryable: false },\n  INVALID_ADDRESS: { category: 'validation', retryable: false },\n  INVALID_AMOUNT: { category: 'validation', retryable: false },\n  ASSET_RESOLUTION: { category: 'validation', retryable: false },\n  INVALID_INTENT: { category: 'validation', retryable: false },\n  PROVIDER_UNAVAILABLE: { category: 'provider', retryable: true },\n  RATE_LIMITED: { category: 'provider', retryable: true },\n  PROVIDER_MISCONFIGURED: { category: 'provider', retryable: false },\n  PROVIDER_INCONSISTENT: { category: 'provider', retryable: true },\n  RPC_ERROR: { category: 'provider', retryable: false },\n  INSUFFICIENT_FUNDS: { category: 'chain', retryable: false },\n  NONCE_CONFLICT: { category: 'chain', retryable: false },\n  NONCE_TOO_HIGH: { category: 'chain', retryable: false },\n  FEE_TOO_LOW: { category: 'chain', retryable: false },\n  TX_REFUSED: { category: 'chain', retryable: false },\n  TX_REJECTED: { category: 'chain', retryable: false },\n  TX_REVERTED: { category: 'chain', retryable: false },\n  /** Included and executed, but no transfer to the recipient shows: value may have moved. */\n  TX_UNEVIDENCED: { category: 'chain', retryable: false },\n  TX_EXPIRED: { category: 'chain', retryable: false },\n  TX_REPLACED: { category: 'chain', retryable: false },\n  SIGNER_UNAVAILABLE: { category: 'signing', retryable: false },\n  SIGNING_FAILED: { category: 'signing', retryable: false },\n  SIGNATURE_MISMATCH: { category: 'signing', retryable: false },\n  POLICY_REJECTED: { category: 'signing', retryable: false },\n  KEY_NOT_EXPORTABLE: { category: 'signing', retryable: false },\n  IDEMPOTENCY_CONFLICT: { category: 'state', retryable: false },\n  FENCING: { category: 'state', retryable: false },\n  VERSION_CONFLICT: { category: 'state', retryable: true },\n  INVALID_TRANSITION: { category: 'state', retryable: false },\n  NOT_FOUND: { category: 'state', retryable: false },\n  SEQUENCE_BUSY: { category: 'state', retryable: true },\n  /** The outcome may have happened (e.g. a delivered broadcast) but was not recorded. */\n  STATE_UNRECORDED: { category: 'state', retryable: true },\n  SCANNER_REORG_TOO_DEEP: { category: 'state', retryable: false },\n  /** A stored Operation's record format is newer than this version reads. */\n  RECORD_FORMAT_UNSUPPORTED: { category: 'state', retryable: false },\n  TIMEOUT: { category: 'timeout', retryable: true },\n} as const satisfies Record<string, CodeDefinition>);\n\nfunction deepFreezeCodes<T extends Record<string, CodeDefinition>>(codes: T): T {\n  for (const definition of Object.values(codes)) Object.freeze(definition);\n  return Object.freeze(codes);\n}\n\nexport type ErrorCode = keyof typeof ERROR_CODES;\n\nexport type CodesOf<C extends ErrorCategory> = {\n  [K in ErrorCode]: (typeof ERROR_CODES)[K]['category'] extends C ? K : never;\n}[ErrorCode];\n"]}

package/dist/core/errors/error.d.ts

@@ -0,0 +1,66 @@
+import { type CodesOf, type ErrorCategory, type ErrorCode } from './codes';
+export type { CodesOf, ErrorCategory, ErrorCode } from './codes';
+export type ErrorContextValue = string | number | boolean | undefined;
+export type ErrorContext = Readonly<Record<string, ErrorContextValue>>;
+export interface CryptoAioErrorOptions {
+    readonly cause?: unknown;
+    readonly context?: ErrorContext;
+    readonly details?: Readonly<Record<string, unknown>>;
+    readonly retryable?: boolean;
+    readonly ambiguous?: boolean;
+}
+export interface SerializedError {
+    readonly name: string;
+    readonly code: ErrorCode;
+    readonly category: ErrorCategory;
+    readonly message: string;
+    readonly retryable: boolean;
+    readonly ambiguous: boolean;
+    readonly context: ErrorContext;
+    readonly details?: Readonly<Record<string, unknown>>;
+}
+export declare class CryptoAioError extends Error {
+    readonly code: ErrorCode;
+    readonly category: ErrorCategory;
+    readonly retryable: boolean;
+    readonly ambiguous: boolean;
+    readonly context: ErrorContext;
+    readonly details?: Readonly<Record<string, unknown>>;
+    constructor(code: ErrorCode, message: string, options?: CryptoAioErrorOptions);
+    toJSON(): SerializedError;
+}
+export declare class ConfigError extends CryptoAioError {
+    constructor(code: CodesOf<'config'>, message: string, options?: CryptoAioErrorOptions);
+}
+export declare class UnsupportedCapabilityError extends CryptoAioError {
+    constructor(code: CodesOf<'unsupported'>, message: string, options?: CryptoAioErrorOptions);
+}
+export declare class ValidationError extends CryptoAioError {
+    constructor(code: CodesOf<'validation'>, message: string, options?: CryptoAioErrorOptions);
+}
+export declare class ProviderError extends CryptoAioError {
+    constructor(code: CodesOf<'provider'>, message: string, options?: CryptoAioErrorOptions);
+}
+export declare class ChainError extends CryptoAioError {
+    constructor(code: CodesOf<'chain'>, message: string, options?: CryptoAioErrorOptions);
+}
+export declare class SigningError extends CryptoAioError {
+    constructor(code: CodesOf<'signing'>, message: string, options?: CryptoAioErrorOptions);
+}
+export declare class StateError extends CryptoAioError {
+    constructor(code: CodesOf<'state'>, message: string, options?: CryptoAioErrorOptions);
+}
+export declare class TimeoutError extends CryptoAioError {
+    constructor(code: CodesOf<'timeout'>, message: string, options?: CryptoAioErrorOptions);
+}
+export declare function createError(code: ErrorCode, message: string, options?: CryptoAioErrorOptions): CryptoAioError;
+export declare function isCryptoAioError(value: unknown, code?: ErrorCode): value is CryptoAioError;
+/**
+ * Returns a copy of `error` (same class, same stack) with merged context, and optional flag
+ * and `details` overrides. The copy keeps the stack of the error it reports.
+ */
+export declare function withContext(error: CryptoAioError, context: ErrorContext, overrides?: {
+    readonly ambiguous?: boolean;
+    readonly retryable?: boolean;
+    readonly details?: Readonly<Record<string, unknown>>;
+}): CryptoAioError;

package/dist/core/errors/error.js

@@ -0,0 +1,129 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TimeoutError = exports.StateError = exports.SigningError = exports.ChainError = exports.ProviderError = exports.ValidationError = exports.UnsupportedCapabilityError = exports.ConfigError = exports.CryptoAioError = void 0;
+exports.createError = createError;
+exports.isCryptoAioError = isCryptoAioError;
+exports.withContext = withContext;
+const codes_1 = require("./codes");
+class CryptoAioError extends Error {
+    code;
+    category;
+    retryable;
+    ambiguous;
+    context;
+    details;
+    constructor(code, message, options = {}) {
+        super(message, options.cause === undefined ? undefined : { cause: options.cause });
+        this.name = new.target.name;
+        const definition = codes_1.ERROR_CODES[code];
+        this.code = code;
+        this.category = definition.category;
+        this.retryable = options.retryable ?? definition.retryable;
+        this.ambiguous = options.ambiguous ?? false;
+        this.context = Object.freeze({ ...options.context });
+        if (options.details)
+            this.details = Object.freeze({ ...options.details });
+    }
+    toJSON() {
+        return {
+            name: this.name,
+            code: this.code,
+            category: this.category,
+            message: this.message,
+            retryable: this.retryable,
+            ambiguous: this.ambiguous,
+            context: this.context,
+            ...(this.details ? { details: this.details } : {}),
+        };
+    }
+}
+exports.CryptoAioError = CryptoAioError;
+class ConfigError extends CryptoAioError {
+    constructor(code, message, options) {
+        super(code, message, options);
+    }
+}
+exports.ConfigError = ConfigError;
+class UnsupportedCapabilityError extends CryptoAioError {
+    constructor(code, message, options) {
+        super(code, message, options);
+    }
+}
+exports.UnsupportedCapabilityError = UnsupportedCapabilityError;
+class ValidationError extends CryptoAioError {
+    constructor(code, message, options) {
+        super(code, message, options);
+    }
+}
+exports.ValidationError = ValidationError;
+class ProviderError extends CryptoAioError {
+    constructor(code, message, options) {
+        super(code, message, options);
+    }
+}
+exports.ProviderError = ProviderError;
+class ChainError extends CryptoAioError {
+    constructor(code, message, options) {
+        super(code, message, options);
+    }
+}
+exports.ChainError = ChainError;
+class SigningError extends CryptoAioError {
+    constructor(code, message, options) {
+        super(code, message, options);
+    }
+}
+exports.SigningError = SigningError;
+class StateError extends CryptoAioError {
+    constructor(code, message, options) {
+        super(code, message, options);
+    }
+}
+exports.StateError = StateError;
+class TimeoutError extends CryptoAioError {
+    constructor(code, message, options) {
+        super(code, message, options);
+    }
+}
+exports.TimeoutError = TimeoutError;
+const BY_CATEGORY = {
+    config: ConfigError,
+    unsupported: UnsupportedCapabilityError,
+    validation: ValidationError,
+    provider: ProviderError,
+    chain: ChainError,
+    signing: SigningError,
+    state: StateError,
+    timeout: TimeoutError,
+};
+function createError(code, message, options) {
+    const Ctor = BY_CATEGORY[codes_1.ERROR_CODES[code].category];
+    return new Ctor(code, message, options);
+}
+function isCryptoAioError(value, code) {
+    return value instanceof CryptoAioError && (code === undefined || value.code === code);
+}
+/**
+ * Returns a copy of `error` (same class, same stack) with merged context, and optional flag
+ * and `details` overrides. The copy keeps the stack of the error it reports.
+ */
+function withContext(error, context, overrides = {}) {
+    const Ctor = error.constructor;
+    const details = overrides.details ?? error.details;
+    const copy = new Ctor(error.code, error.message, {
+        cause: error.cause,
+        context: { ...error.context, ...context },
+        ...(details ? { details } : {}),
+        retryable: overrides.retryable ?? error.retryable,
+        ambiguous: overrides.ambiguous ?? error.ambiguous,
+    });
+    if (error.stack !== undefined) {
+        Object.defineProperty(copy, 'stack', {
+            value: error.stack,
+            writable: true,
+            configurable: true,
+        });
+    }
+    return copy;
+}
+//# sourceMappingURL=error.js.map

package/dist/core/errors/error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.js","sourceRoot":"","sources":["../../../src/core/errors/error.ts"],"names":[],"mappings":"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","sourcesContent":["import { ERROR_CODES, type CodesOf, type ErrorCategory, type ErrorCode } from './codes';\n\nexport type { CodesOf, ErrorCategory, ErrorCode } from './codes';\n\nexport type ErrorContextValue = string | number | boolean | undefined;\nexport type ErrorContext = Readonly<Record<string, ErrorContextValue>>;\n\nexport interface CryptoAioErrorOptions {\n  readonly cause?: unknown;\n  readonly context?: ErrorContext;\n  readonly details?: Readonly<Record<string, unknown>>;\n  readonly retryable?: boolean;\n  readonly ambiguous?: boolean;\n}\n\nexport interface SerializedError {\n  readonly name: string;\n  readonly code: ErrorCode;\n  readonly category: ErrorCategory;\n  readonly message: string;\n  readonly retryable: boolean;\n  readonly ambiguous: boolean;\n  readonly context: ErrorContext;\n  readonly details?: Readonly<Record<string, unknown>>;\n}\n\nexport class CryptoAioError extends Error {\n  readonly code: ErrorCode;\n  readonly category: ErrorCategory;\n  readonly retryable: boolean;\n  readonly ambiguous: boolean;\n  readonly context: ErrorContext;\n  readonly details?: Readonly<Record<string, unknown>>;\n\n  constructor(code: ErrorCode, message: string, options: CryptoAioErrorOptions = {}) {\n    super(message, options.cause === undefined ? undefined : { cause: options.cause });\n    this.name = new.target.name;\n    const definition = ERROR_CODES[code];\n    this.code = code;\n    this.category = definition.category;\n    this.retryable = options.retryable ?? definition.retryable;\n    this.ambiguous = options.ambiguous ?? false;\n    this.context = Object.freeze({ ...options.context });\n    if (options.details) this.details = Object.freeze({ ...options.details });\n  }\n\n  toJSON(): SerializedError {\n    return {\n      name: this.name,\n      code: this.code,\n      category: this.category,\n      message: this.message,\n      retryable: this.retryable,\n      ambiguous: this.ambiguous,\n      context: this.context,\n      ...(this.details ? { details: this.details } : {}),\n    };\n  }\n}\n\nexport class ConfigError extends CryptoAioError {\n  constructor(code: CodesOf<'config'>, message: string, options?: CryptoAioErrorOptions) {\n    super(code, message, options);\n  }\n}\nexport class UnsupportedCapabilityError extends CryptoAioError {\n  constructor(\n    code: CodesOf<'unsupported'>,\n    message: string,\n    options?: CryptoAioErrorOptions,\n  ) {\n    super(code, message, options);\n  }\n}\nexport class ValidationError extends CryptoAioError {\n  constructor(\n    code: CodesOf<'validation'>,\n    message: string,\n    options?: CryptoAioErrorOptions,\n  ) {\n    super(code, message, options);\n  }\n}\nexport class ProviderError extends CryptoAioError {\n  constructor(\n    code: CodesOf<'provider'>,\n    message: string,\n    options?: CryptoAioErrorOptions,\n  ) {\n    super(code, message, options);\n  }\n}\nexport class ChainError extends CryptoAioError {\n  constructor(code: CodesOf<'chain'>, message: string, options?: CryptoAioErrorOptions) {\n    super(code, message, options);\n  }\n}\nexport class SigningError extends CryptoAioError {\n  constructor(\n    code: CodesOf<'signing'>,\n    message: string,\n    options?: CryptoAioErrorOptions,\n  ) {\n    super(code, message, options);\n  }\n}\nexport class StateError extends CryptoAioError {\n  constructor(code: CodesOf<'state'>, message: string, options?: CryptoAioErrorOptions) {\n    super(code, message, options);\n  }\n}\nexport class TimeoutError extends CryptoAioError {\n  constructor(\n    code: CodesOf<'timeout'>,\n    message: string,\n    options?: CryptoAioErrorOptions,\n  ) {\n    super(code, message, options);\n  }\n}\n\ntype AnyErrorConstructor = new (\n  code: ErrorCode,\n  message: string,\n  options?: CryptoAioErrorOptions,\n) => CryptoAioError;\n\nconst BY_CATEGORY: Record<ErrorCategory, AnyErrorConstructor> = {\n  config: ConfigError as AnyErrorConstructor,\n  unsupported: UnsupportedCapabilityError as AnyErrorConstructor,\n  validation: ValidationError as AnyErrorConstructor,\n  provider: ProviderError as AnyErrorConstructor,\n  chain: ChainError as AnyErrorConstructor,\n  signing: SigningError as AnyErrorConstructor,\n  state: StateError as AnyErrorConstructor,\n  timeout: TimeoutError as AnyErrorConstructor,\n};\n\nexport function createError(\n  code: ErrorCode,\n  message: string,\n  options?: CryptoAioErrorOptions,\n): CryptoAioError {\n  const Ctor = BY_CATEGORY[ERROR_CODES[code].category];\n  return new Ctor(code, message, options);\n}\n\nexport function isCryptoAioError(\n  value: unknown,\n  code?: ErrorCode,\n): value is CryptoAioError {\n  return value instanceof CryptoAioError && (code === undefined || value.code === code);\n}\n\n/**\n * Returns a copy of `error` (same class, same stack) with merged context, and optional flag\n * and `details` overrides. The copy keeps the stack of the error it reports.\n */\nexport function withContext(\n  error: CryptoAioError,\n  context: ErrorContext,\n  overrides: {\n    readonly ambiguous?: boolean;\n    readonly retryable?: boolean;\n    readonly details?: Readonly<Record<string, unknown>>;\n  } = {},\n): CryptoAioError {\n  const Ctor = error.constructor as AnyErrorConstructor;\n  const details = overrides.details ?? error.details;\n  const copy = new Ctor(error.code, error.message, {\n    cause: error.cause,\n    context: { ...error.context, ...context },\n    ...(details ? { details } : {}),\n    retryable: overrides.retryable ?? error.retryable,\n    ambiguous: overrides.ambiguous ?? error.ambiguous,\n  });\n  if (error.stack !== undefined) {\n    Object.defineProperty(copy, 'stack', {\n      value: error.stack,\n      writable: true,\n      configurable: true,\n    });\n  }\n  return copy;\n}\n"]}

package/dist/core/events/bus.d.ts

@@ -0,0 +1,12 @@
+import type { Clock } from '../util/clock';
+import type { Logger } from './logger';
+import type { AioEvent, AioEventName, AioEvents } from './types';
+export declare class EventBus {
+    #private;
+    private readonly clock;
+    private readonly log;
+    constructor(clock: Clock, log: Logger);
+    on<E extends AioEventName>(type: E, handler: (event: AioEvent<E>) => void): () => void;
+    onAny(handler: (event: AioEvent) => void): () => void;
+    emit<E extends AioEventName>(type: E, payload: AioEvents[E]): void;
+}

package/dist/core/events/bus.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EventBus = void 0;
+const error_1 = require("../errors/error");
+class EventBus {
+    clock;
+    log;
+    #handlers = new Map();
+    #any = new Set();
+    constructor(clock, log) {
+        this.clock = clock;
+        this.log = log;
+    }
+    on(type, handler) {
+        const set = this.#handlers.get(type) ?? new Set();
+        this.#handlers.set(type, set);
+        const h = handler;
+        set.add(h);
+        return () => {
+            set.delete(h);
+        };
+    }
+    onAny(handler) {
+        this.#any.add(handler);
+        return () => {
+            this.#any.delete(handler);
+        };
+    }
+    emit(type, payload) {
+        const event = { ...payload, type, at: this.clock.now() };
+        for (const handler of [...(this.#handlers.get(type) ?? []), ...this.#any]) {
+            try {
+                handler(event);
+            }
+            catch (error) {
+                // The code only; a handler's error message may carry anything.
+                this.log.warn('event handler threw', {
+                    type,
+                    code: (0, error_1.isCryptoAioError)(error) ? error.code : 'UNKNOWN',
+                });
+            }
+        }
+    }
+}
+exports.EventBus = EventBus;
+//# sourceMappingURL=bus.js.map

package/dist/core/events/bus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bus.js","sourceRoot":"","sources":["../../../src/core/events/bus.ts"],"names":[],"mappings":";;;AAAA,2CAAmD;AAOnD,MAAa,QAAQ;IAKA;IACA;IALV,SAAS,GAAG,IAAI,GAAG,EAAiC,CAAC;IACrD,IAAI,GAAG,IAAI,GAAG,EAAc,CAAC;IAEtC,YACmB,KAAY,EACZ,GAAW;QADX,UAAK,GAAL,KAAK,CAAO;QACZ,QAAG,GAAH,GAAG,CAAQ;IAC3B,CAAC;IAEJ,EAAE,CAAyB,IAAO,EAAE,OAAqC;QACvE,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,IAAI,GAAG,EAAc,CAAC;QAC9D,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QAC9B,MAAM,CAAC,GAAG,OAAgC,CAAC;QAC3C,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QACX,OAAO,GAAG,EAAE;YACV,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QAChB,CAAC,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,OAAkC;QACtC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACvB,OAAO,GAAG,EAAE;YACV,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAC5B,CAAC,CAAC;IACJ,CAAC;IAED,IAAI,CAAyB,IAAO,EAAE,OAAqB;QACzD,MAAM,KAAK,GAAG,EAAE,GAAG,OAAO,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,EAAc,CAAC;QACrE,KAAK,MAAM,OAAO,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YAC1E,IAAI,CAAC;gBACH,OAAO,CAAC,KAAK,CAAC,CAAC;YACjB,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,+DAA+D;gBAC/D,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,qBAAqB,EAAE;oBACnC,IAAI;oBACJ,IAAI,EAAE,IAAA,wBAAgB,EAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS;iBACvD,CAAC,CAAC;YACL,CAAC;QACH,CAAC;IACH,CAAC;CACF;AAxCD,4BAwCC","sourcesContent":["import { isCryptoAioError } from '../errors/error';\nimport type { Clock } from '../util/clock';\nimport type { Logger } from './logger';\nimport type { AioEvent, AioEventName, AioEvents } from './types';\n\ntype AnyHandler = (event: AioEvent) => void;\n\nexport class EventBus {\n  readonly #handlers = new Map<AioEventName, Set<AnyHandler>>();\n  readonly #any = new Set<AnyHandler>();\n\n  constructor(\n    private readonly clock: Clock,\n    private readonly log: Logger,\n  ) {}\n\n  on<E extends AioEventName>(type: E, handler: (event: AioEvent<E>) => void): () => void {\n    const set = this.#handlers.get(type) ?? new Set<AnyHandler>();\n    this.#handlers.set(type, set);\n    const h = handler as unknown as AnyHandler;\n    set.add(h);\n    return () => {\n      set.delete(h);\n    };\n  }\n\n  onAny(handler: (event: AioEvent) => void): () => void {\n    this.#any.add(handler);\n    return () => {\n      this.#any.delete(handler);\n    };\n  }\n\n  emit<E extends AioEventName>(type: E, payload: AioEvents[E]): void {\n    const event = { ...payload, type, at: this.clock.now() } as AioEvent;\n    for (const handler of [...(this.#handlers.get(type) ?? []), ...this.#any]) {\n      try {\n        handler(event);\n      } catch (error) {\n        // The code only; a handler's error message may carry anything.\n        this.log.warn('event handler threw', {\n          type,\n          code: isCryptoAioError(error) ? error.code : 'UNKNOWN',\n        });\n      }\n    }\n  }\n}\n"]}

package/dist/core/events/logger.d.ts

@@ -0,0 +1,13 @@
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+export type LogFields = Readonly<Record<string, unknown>>;
+export interface Logger {
+    debug(message: string, fields?: LogFields): void;
+    info(message: string, fields?: LogFields): void;
+    warn(message: string, fields?: LogFields): void;
+    error(message: string, fields?: LogFields): void;
+    child(namespace: string): Logger;
+}
+export type LogWriter = (level: LogLevel, namespace: string, message: string, fields?: Record<string, unknown>) => void;
+/** Structured logger; fields are always redacted before they reach the writer. */
+export declare function createLogger(namespace?: string, write?: LogWriter): Logger;
+export declare const noopLogger: Logger;

package/dist/core/events/logger.js

@@ -0,0 +1,42 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.noopLogger = void 0;
+exports.createLogger = createLogger;
+const debug_1 = __importDefault(require("debug"));
+const redact_1 = require("../secret/redact");
+const debuggers = new Map();
+const debugWriter = (level, namespace, message, fields) => {
+    const name = `${namespace}:${level}`;
+    let log = debuggers.get(name);
+    if (!log) {
+        log = (0, debug_1.default)(name);
+        debuggers.set(name, log);
+    }
+    if (fields && Object.keys(fields).length > 0)
+        log('%s %o', message, fields);
+    else
+        log('%s', message);
+};
+/** Structured logger; fields are always redacted before they reach the writer. */
+function createLogger(namespace = 'crypto-aio', write = debugWriter) {
+    const emit = (level) => (message, fields) => write(level, namespace, (0, redact_1.redactText)(message), fields ? (0, redact_1.redactDeep)(fields) : undefined);
+    return {
+        debug: emit('debug'),
+        info: emit('info'),
+        warn: emit('warn'),
+        error: emit('error'),
+        child: (child) => createLogger(`${namespace}:${child}`, write),
+    };
+}
+const noop = () => undefined;
+exports.noopLogger = {
+    debug: noop,
+    info: noop,
+    warn: noop,
+    error: noop,
+    child: () => exports.noopLogger,
+};
+//# sourceMappingURL=logger.js.map

package/dist/core/events/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../../src/core/events/logger.ts"],"names":[],"mappings":";;;;;;AAmCA,oCAkBC;AArDD,kDAAgC;AAChC,6CAA0D;AAoB1D,MAAM,SAAS,GAAG,IAAI,GAAG,EAAgC,CAAC;AAE1D,MAAM,WAAW,GAAc,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE;IACnE,MAAM,IAAI,GAAG,GAAG,SAAS,IAAI,KAAK,EAAE,CAAC;IACrC,IAAI,GAAG,GAAG,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC9B,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,GAAG,GAAG,IAAA,eAAW,EAAC,IAAI,CAAC,CAAC;QACxB,SAAS,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IAC3B,CAAC;IACD,IAAI,MAAM,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,MAAM,GAAG,CAAC;QAAE,GAAG,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;;QACvE,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;AAC1B,CAAC,CAAC;AAEF,kFAAkF;AAClF,SAAgB,YAAY,CAC1B,SAAS,GAAG,YAAY,EACxB,QAAmB,WAAW;IAE9B,MAAM,IAAI,GAAG,CAAC,KAAe,EAAE,EAAE,CAAC,CAAC,OAAe,EAAE,MAAkB,EAAE,EAAE,CACxE,KAAK,CACH,KAAK,EACL,SAAS,EACT,IAAA,mBAAU,EAAC,OAAO,CAAC,EACnB,MAAM,CAAC,CAAC,CAAE,IAAA,mBAAU,EAAC,MAAM,CAA6B,CAAC,CAAC,CAAC,SAAS,CACrE,CAAC;IACJ,OAAO;QACL,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC;QACpB,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC;QAClB,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC;QAClB,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC;QACpB,KAAK,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,YAAY,CAAC,GAAG,SAAS,IAAI,KAAK,EAAE,EAAE,KAAK,CAAC;KAC/D,CAAC;AACJ,CAAC;AAED,MAAM,IAAI,GAAG,GAAS,EAAE,CAAC,SAAS,CAAC;AAEtB,QAAA,UAAU,GAAW;IAChC,KAAK,EAAE,IAAI;IACX,IAAI,EAAE,IAAI;IACV,IAAI,EAAE,IAAI;IACV,KAAK,EAAE,IAAI;IACX,KAAK,EAAE,GAAG,EAAE,CAAC,kBAAU;CACxB,CAAC","sourcesContent":["import createDebug from 'debug';\nimport { redactDeep, redactText } from '../secret/redact';\n\nexport type LogLevel = 'debug' | 'info' | 'warn' | 'error';\nexport type LogFields = Readonly<Record<string, unknown>>;\n\nexport interface Logger {\n  debug(message: string, fields?: LogFields): void;\n  info(message: string, fields?: LogFields): void;\n  warn(message: string, fields?: LogFields): void;\n  error(message: string, fields?: LogFields): void;\n  child(namespace: string): Logger;\n}\n\nexport type LogWriter = (\n  level: LogLevel,\n  namespace: string,\n  message: string,\n  fields?: Record<string, unknown>,\n) => void;\n\nconst debuggers = new Map<string, createDebug.Debugger>();\n\nconst debugWriter: LogWriter = (level, namespace, message, fields) => {\n  const name = `${namespace}:${level}`;\n  let log = debuggers.get(name);\n  if (!log) {\n    log = createDebug(name);\n    debuggers.set(name, log);\n  }\n  if (fields && Object.keys(fields).length > 0) log('%s %o', message, fields);\n  else log('%s', message);\n};\n\n/** Structured logger; fields are always redacted before they reach the writer. */\nexport function createLogger(\n  namespace = 'crypto-aio',\n  write: LogWriter = debugWriter,\n): Logger {\n  const emit = (level: LogLevel) => (message: string, fields?: LogFields) =>\n    write(\n      level,\n      namespace,\n      redactText(message),\n      fields ? (redactDeep(fields) as Record<string, unknown>) : undefined,\n    );\n  return {\n    debug: emit('debug'),\n    info: emit('info'),\n    warn: emit('warn'),\n    error: emit('error'),\n    child: (child) => createLogger(`${namespace}:${child}`, write),\n  };\n}\n\nconst noop = (): void => undefined;\n\nexport const noopLogger: Logger = {\n  debug: noop,\n  info: noop,\n  warn: noop,\n  error: noop,\n  child: () => noopLogger,\n};\n"]}

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

@@ -0,0 +1,131 @@
+import type { Evidence, TxState } from '../model/transaction';
+import type { OperationState } from '../store/types';
+/** Every payload is operational-class data only (no addresses, amounts, raw txs or URLs). */
+export interface AioEvents {
+    'rpc.request': {
+        transportId: string;
+        endpointId: string;
+        method: string;
+        attempt: number;
+    };
+    'rpc.response': {
+        transportId: string;
+        endpointId: string;
+        method: string;
+        latencyMs: number;
+        bytes: number;
+    };
+    'rpc.error': {
+        transportId: string;
+        endpointId: string;
+        method: string;
+        latencyMs: number;
+        code: string;
+        retryable: boolean;
+    };
+    'provider.health': {
+        transportId: string;
+        endpointId: string;
+        state: 'healthy' | 'lagging' | 'open' | 'disabled';
+        height?: string;
+        lag?: string;
+    };
+    'provider.misconfigured': {
+        transportId: string;
+        endpointId: string;
+        expected: string;
+        actual: string;
+    };
+    'provider.inconsistent': {
+        transportId: string;
+        method: string;
+        endpointIds: readonly string[];
+    };
+    'operation.state': {
+        namespace: string;
+        operationId: string;
+        chain: string;
+        network: string;
+        from: OperationState | null;
+        to: OperationState;
+        code?: string;
+    };
+    'operation.stalled': {
+        namespace: string;
+        operationId: string;
+        code: string;
+    };
+    'attempt.state': {
+        namespace: string;
+        operationId: string;
+        attemptId: string;
+        state: TxState;
+        evidence: Evidence;
+    };
+    'tx.reorged': {
+        namespace: string;
+        operationId?: string;
+        attemptId?: string;
+        previousBlockHash: string;
+    };
+    'nonce.allocated': {
+        namespace: string;
+        chain: string;
+        network: string;
+        operationId: string;
+        /** The nonce or seqno: an operational identifier, never UTXO inputs. */
+        value: string;
+    };
+    /**
+     * A submitted Operation has waited past the grace period while the chain's pending nonce
+     * (`expected`) is below its own. At-least-once: a monitor reports each (Operation,
+     * expected) once, but that memory is per process and bounded, so the same gap is reported
+     * again after a restart, by another process, or once it was forgotten.
+     */
+    'nonce.gap': {
+        namespace: string;
+        chain: string;
+        network: string;
+        operationId: string;
+        /** The chain's pending nonce: an operational identifier. */
+        expected: string;
+        blockingOperationId?: string;
+    };
+    'signer.requested': {
+        namespace: string;
+        operationId: string;
+        signerId: string;
+        requests: number;
+    };
+    'signer.completed': {
+        namespace: string;
+        operationId: string;
+        signerId: string;
+        status: 'signed' | 'pending' | 'error';
+        latencyMs: number;
+    };
+    'scanner.block': {
+        namespace: string;
+        cursorKey: string;
+        height: string;
+    };
+    'scanner.rollback': {
+        namespace: string;
+        cursorKey: string;
+        toHeight: string;
+        removed: number;
+    };
+    'recovery.skipped': {
+        namespace: string;
+        operationId: string;
+        state: OperationState;
+        reason: string;
+    };
+}
+export type AioEventName = keyof AioEvents;
+export type AioEvent<E extends AioEventName = AioEventName> = {
+    [K in E]: AioEvents[K] & {
+        readonly type: K;
+        readonly at: number;
+    };
+}[E];

package/dist/core/events/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/core/events/types.ts"],"names":[],"mappings":"","sourcesContent":["import type { Evidence, TxState } from '../model/transaction';\nimport type { OperationState } from '../store/types';\n\n/** Every payload is operational-class data only (no addresses, amounts, raw txs or URLs). */\nexport interface AioEvents {\n  'rpc.request': {\n    transportId: string;\n    endpointId: string;\n    method: string;\n    attempt: number;\n  };\n  'rpc.response': {\n    transportId: string;\n    endpointId: string;\n    method: string;\n    latencyMs: number;\n    bytes: number;\n  };\n  'rpc.error': {\n    transportId: string;\n    endpointId: string;\n    method: string;\n    latencyMs: number;\n    code: string;\n    retryable: boolean;\n  };\n  'provider.health': {\n    transportId: string;\n    endpointId: string;\n    state: 'healthy' | 'lagging' | 'open' | 'disabled';\n    height?: string;\n    lag?: string;\n  };\n  'provider.misconfigured': {\n    transportId: string;\n    endpointId: string;\n    expected: string;\n    actual: string;\n  };\n  'provider.inconsistent': {\n    transportId: string;\n    method: string;\n    endpointIds: readonly string[];\n  };\n  'operation.state': {\n    namespace: string;\n    operationId: string;\n    chain: string;\n    network: string;\n    from: OperationState | null;\n    to: OperationState;\n    code?: string;\n  };\n  'operation.stalled': { namespace: string; operationId: string; code: string };\n  'attempt.state': {\n    namespace: string;\n    operationId: string;\n    attemptId: string;\n    state: TxState;\n    evidence: Evidence;\n  };\n  'tx.reorged': {\n    namespace: string;\n    operationId?: string;\n    attemptId?: string;\n    previousBlockHash: string;\n  };\n  'nonce.allocated': {\n    namespace: string;\n    chain: string;\n    network: string;\n    operationId: string;\n    /** The nonce or seqno: an operational identifier, never UTXO inputs. */\n    value: string;\n  };\n  /**\n   * A submitted Operation has waited past the grace period while the chain's pending nonce\n   * (`expected`) is below its own. At-least-once: a monitor reports each (Operation,\n   * expected) once, but that memory is per process and bounded, so the same gap is reported\n   * again after a restart, by another process, or once it was forgotten.\n   */\n  'nonce.gap': {\n    namespace: string;\n    chain: string;\n    network: string;\n    operationId: string;\n    /** The chain's pending nonce: an operational identifier. */\n    expected: string;\n    blockingOperationId?: string;\n  };\n  'signer.requested': {\n    namespace: string;\n    operationId: string;\n    signerId: string;\n    requests: number;\n  };\n  'signer.completed': {\n    namespace: string;\n    operationId: string;\n    signerId: string;\n    status: 'signed' | 'pending' | 'error';\n    latencyMs: number;\n  };\n  'scanner.block': { namespace: string; cursorKey: string; height: string };\n  'scanner.rollback': {\n    namespace: string;\n    cursorKey: string;\n    toHeight: string;\n    removed: number;\n  };\n  'recovery.skipped': {\n    namespace: string;\n    operationId: string;\n    state: OperationState;\n    reason: string;\n  };\n}\n\nexport type AioEventName = keyof AioEvents;\n\nexport type AioEvent<E extends AioEventName = AioEventName> = {\n  [K in E]: AioEvents[K] & { readonly type: K; readonly at: number };\n}[E];\n"]}

package/dist/core/lifecycle/engine-rules.d.ts

@@ -0,0 +1,106 @@
+import type { LifecycleOptions } from '../config/types';
+import { type CryptoAioError, type ErrorCode, type SerializedError } from '../errors/error';
+import type { FeeOverride, FeeSpeed } from '../model/fee';
+import type { OrderingData, OrderingKind } from '../model/ordering';
+import type { TxState, UnsignedTx } from '../model/transaction';
+import type { AttemptObservation, AttemptRecord, OperationRecord, OperationState, SequenceState } from '../store/types';
+import type { ObservationPatch } from './observations';
+export type ResolvedLifecycle = Required<LifecycleOptions>;
+export declare const LIFECYCLE_DEFAULTS: ResolvedLifecycle;
+export declare function withLifecycleDefaults(options: LifecycleOptions): ResolvedLifecycle;
+export declare const PRE_SIGNING_STATES: ReadonlySet<OperationState>;
+export declare const LEASED_ORDERINGS: Set<string>;
+export declare const DEFINITIVE_CATEGORIES: Set<string>;
+/**
+ * A crypto-aio error as it is; anything else under `fallback`, the most specific
+ * existing code for the caller's context (there is no generic code), with a sanitized message.
+ */
+export declare function serializeError(error: unknown, fallback: ErrorCode): SerializedError;
+export declare function rehydrateError(serialized: SerializedError, operationId: string): Error;
+/**
+ * The error's crypto-aio code, or `'UNKNOWN'`. Logs carry this, never the error itself:
+ * messages may hold addresses, amounts or store detail.
+ */
+export declare function errorCode(error: unknown): string;
+export declare function isDefinitive(error: unknown): error is CryptoAioError;
+/**
+ * Observation states backed by chain evidence: the Attempt was mined, or its slot or expiry
+ * was consumed. No broadcast answer ever overwrites them; `replacedBy` is kept.
+ */
+export declare const CHAIN_EVIDENCE_STATES: ReadonlySet<TxState>;
+/**
+ * A node once accepted these bytes, or they may be live. `firstSeenAt` is the durable
+ * marker: set when a node accepted them or the monitor saw them held, and kept by a refusal
+ * that found them possibly live. A `pending`, `mempool` or `dropped` observation also
+ * counts: one left by an accepted or ambiguous send, and the `pending` the monitor
+ * writes for a signed Attempt that was never broadcast, which errs in the safe direction
+ * (a genuine rejection then stalls it and keeps its nonce instead of failing it). A later
+ * rejection says nothing about bytes that may still sit in a mempool, so it is only a
+ * refusal: never terminal, the nonce is kept.
+ */
+export declare function mayBeLive(observation: AttemptObservation | null): boolean;
+/**
+ * A send that may have delivered the bytes (accepted, already known or ambiguous): a
+ * missing, `refused` or `dropped` observation becomes `pending`, and a refusal's reason no
+ * longer applies. Stronger evidence (chain or proven states) is left alone. The one rule
+ * for every such send, so they cannot drift apart. Known gap: an ambiguous send clears a
+ * refusal and its reason, so the monitor then shows bytes the node still refuses as
+ * `dropped`, not `refused`; only a resend through the engine (a same-key repeat,
+ * `rebroadcast`, recovery) records the refusal again.
+ */
+export declare function pendingAfterSend(current: AttemptObservation | null): ObservationPatch;
+/** Every nonce a live Operation holds: its reservation, unsigned payload and Attempts. */
+export declare function heldNonces(op: OperationRecord): bigint[];
+/** Failures proven on chain at finality: their nonce was consumed. */
+export declare const CONSUMED_FAILURES: ReadonlySet<string>;
+/** Whether some value in [from, next) is neither released nor held. */
+export declare function hasReclaimable(state: SequenceState | null, from: bigint, held: readonly bigint[]): boolean;
+/** `signed`, or `submitted` with an unknown broadcast outcome: its stored bytes are (re)sent. */
+export declare function awaitsBroadcast(op: OperationRecord): boolean;
+/** The node's own answer (refused, rejected): not ambiguous, so the bytes were not taken. */
+export declare function isRefusal(error: unknown): boolean;
+/**
+ * A replacement records the fee spec it was asked for (plain data, as every store record
+ * must be) in its fee details, so a repeat of the same request is recognised instead of
+ * signed again. The core adds it after `build`, so a driver never sets or reads it: its
+ * `assemble` reads only the fee fields it named itself.
+ */
+export declare function withRequestedFee(unsigned: UnsignedTx, fee: FeeSpeed | FeeOverride): UnsignedTx;
+/** An Attempt's total fee, summed over its charges. */
+export declare function feeOf(attempt: AttemptRecord): bigint;
+/**
+ * The cancel a new cancel is bumped from: among the earlier cancels that superseded
+ * the active Attempt `previous` (refused ones gave it the active role back), the one paying
+ * the most, so repeated bumps climb; otherwise `previous` itself, so a cancel never starts
+ * below a newer, higher replacement. Fees are compared only between cancels: by the
+ * driver's `comparePrice` when it has one, otherwise by total charges.
+ */
+export declare function cancelBase(op: OperationRecord, previous: AttemptRecord, comparePrice?: (a: UnsignedTx, b: UnsignedTx) => number): AttemptRecord;
+/** The same `FeeSpeed` name, or a canonically equal `FeeOverride`. */
+export declare function sameFeeSpec(attempt: AttemptRecord, fee: FeeSpeed | FeeOverride | undefined): boolean;
+/**
+ * What `restoreAfterRefusal` puts back: the Operation as the refused Attempt found it.
+ * Without `state`, only the active Attempt is swapped (state and error are kept).
+ */
+export interface RestorePoint {
+    readonly state?: OperationState;
+    readonly activeAttemptId: string;
+    readonly error?: SerializedError;
+    readonly ambiguous?: boolean;
+}
+/** A node's refusal or rejection of these bytes; both are handled alike. */
+export declare const NODE_REFUSED_STATES: ReadonlySet<TxState>;
+/** Observations under which a superseded Attempt may still be live on the network. */
+export declare const LIVE_STATES: ReadonlySet<TxState>;
+/** The states in which a replacement or cancel may supersede the active Attempt. */
+export declare const CONFLICTABLE_STATES: ReadonlySet<OperationState>;
+/** The only state `rebuild` reopens. */
+export declare const REBUILDABLE_STATES: ReadonlySet<OperationState>;
+/** Where the stored bytes of a new Attempt whose broadcast never completed are resent. */
+export declare const RESUMABLE_STATES: ReadonlySet<OperationState>;
+/**
+ * The built transaction must use exactly the slot the engine reserved: the ordering
+ * kind of the driver, the allocated nonce or seqno, and no input held by another live
+ * Operation. Anything else would persist a reservation nobody allocated.
+ */
+export declare function assertBuiltOrdering(operationId: string, kind: OrderingKind, allocated: OrderingData | undefined, excluded: readonly string[] | undefined, built: OrderingData): void;