crypto-aio 0.0.3 → 0.1.0

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,107 @@
+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. Known gap:
+ * they are ranked by total charges, not by a price the driver compares, so on EVM a
+ * repeat cancel may need an explicit `fee`.
+ */
+export declare function cancelBase(op: OperationRecord, previous: AttemptRecord): 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;

package/dist/core/lifecycle/engine-rules.js

@@ -0,0 +1,257 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RESUMABLE_STATES = exports.REBUILDABLE_STATES = exports.CONFLICTABLE_STATES = exports.LIVE_STATES = exports.NODE_REFUSED_STATES = exports.CONSUMED_FAILURES = exports.CHAIN_EVIDENCE_STATES = exports.DEFINITIVE_CATEGORIES = exports.LEASED_ORDERINGS = exports.PRE_SIGNING_STATES = exports.LIFECYCLE_DEFAULTS = void 0;
+exports.withLifecycleDefaults = withLifecycleDefaults;
+exports.serializeError = serializeError;
+exports.rehydrateError = rehydrateError;
+exports.errorCode = errorCode;
+exports.isDefinitive = isDefinitive;
+exports.mayBeLive = mayBeLive;
+exports.pendingAfterSend = pendingAfterSend;
+exports.heldNonces = heldNonces;
+exports.hasReclaimable = hasReclaimable;
+exports.awaitsBroadcast = awaitsBroadcast;
+exports.isRefusal = isRefusal;
+exports.withRequestedFee = withRequestedFee;
+exports.feeOf = feeOf;
+exports.cancelBase = cancelBase;
+exports.sameFeeSpec = sameFeeSpec;
+exports.assertBuiltOrdering = assertBuiltOrdering;
+const error_1 = require("../errors/error");
+const redact_1 = require("../secret/redact");
+const json_1 = require("../util/json");
+exports.LIFECYCLE_DEFAULTS = {
+    pollIntervalMs: 5_000,
+    droppedGracePeriodMs: 120_000,
+    rebroadcastIntervalMs: 60_000,
+    leaseMs: 30_000,
+    claimLeaseMs: 60_000,
+    waitTimeoutMs: 600_000,
+    requireIdempotencyKey: false,
+    broadcastFanout: 1,
+    signTimeoutMs: 120_000,
+};
+function withLifecycleDefaults(options) {
+    const out = { ...exports.LIFECYCLE_DEFAULTS };
+    for (const [key, value] of Object.entries(options))
+        if (value !== undefined)
+            out[key] = value;
+    const { signTimeoutMs } = out;
+    if (typeof signTimeoutMs !== 'number' ||
+        !Number.isFinite(signTimeoutMs) ||
+        signTimeoutMs <= 0) {
+        throw new error_1.ConfigError('CONFIG_INVALID', 'lifecycle.signTimeoutMs must be a finite number greater than 0');
+    }
+    return out;
+}
+exports.PRE_SIGNING_STATES = new Set([
+    'created',
+    'prepared',
+    'awaiting-signature',
+]);
+exports.LEASED_ORDERINGS = new Set(['nonce', 'seqno', 'inputs']);
+exports.DEFINITIVE_CATEGORIES = new Set([
+    'validation',
+    'chain',
+    'unsupported',
+    'config',
+    'signing',
+]);
+/**
+ * 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.
+ */
+function serializeError(error, fallback) {
+    return ((0, error_1.isCryptoAioError)(error) ? error : (0, error_1.createError)(fallback, (0, redact_1.sanitizeError)(error).message)).toJSON();
+}
+function rehydrateError(serialized, operationId) {
+    return (0, error_1.createError)(serialized.code, serialized.message, {
+        context: { ...serialized.context, operationId },
+        ...(serialized.details ? { details: serialized.details } : {}),
+        retryable: serialized.retryable,
+        ambiguous: serialized.ambiguous,
+    });
+}
+/**
+ * The error's crypto-aio code, or `'UNKNOWN'`. Logs carry this, never the error itself:
+ * messages may hold addresses, amounts or store detail.
+ */
+function errorCode(error) {
+    return (0, error_1.isCryptoAioError)(error) ? error.code : 'UNKNOWN';
+}
+function isDefinitive(error) {
+    return ((0, error_1.isCryptoAioError)(error) &&
+        !error.retryable &&
+        exports.DEFINITIVE_CATEGORIES.has(error.category));
+}
+/**
+ * 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.
+ */
+exports.CHAIN_EVIDENCE_STATES = new Set([
+    'included',
+    'final',
+    'failed',
+    'replaced',
+    'expired',
+]);
+/**
+ * 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.
+ */
+function mayBeLive(observation) {
+    return (observation !== null &&
+        (observation.firstSeenAt !== undefined ||
+            observation.state === 'pending' ||
+            observation.state === 'mempool' ||
+            observation.state === 'dropped'));
+}
+/**
+ * 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.
+ */
+function pendingAfterSend(current) {
+    return current === null || current.state === 'refused' || current.state === 'dropped'
+        ? { state: 'pending', reason: undefined }
+        : {};
+}
+/** Every nonce a live Operation holds: its reservation, unsigned payload and Attempts. */
+function heldNonces(op) {
+    const orderings = [
+        op.reservation,
+        op.unsigned?.ordering,
+        ...op.attempts.map((a) => a.ordering),
+    ];
+    return orderings.flatMap((o) => (o?.kind === 'nonce' ? [o.nonce] : []));
+}
+/** Failures proven on chain at finality: their nonce was consumed. */
+exports.CONSUMED_FAILURES = new Set([
+    'TX_REVERTED',
+    'TX_REPLACED',
+]);
+/** Whether some value in [from, next) is neither released nor held. */
+function hasReclaimable(state, from, held) {
+    if (!state)
+        return false;
+    const taken = new Set([...state.released, ...held]);
+    for (let value = from; value < state.next; value++)
+        if (!taken.has(value))
+            return true;
+    return false;
+}
+/** `signed`, or `submitted` with an unknown broadcast outcome: its stored bytes are (re)sent. */
+function awaitsBroadcast(op) {
+    return op.state === 'signed' || (op.state === 'submitted' && op.ambiguous === true);
+}
+/** The node's own answer (refused, rejected): not ambiguous, so the bytes were not taken. */
+function isRefusal(error) {
+    return (0, error_1.isCryptoAioError)(error) && error.category === 'chain' && !error.ambiguous;
+}
+/**
+ * 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.
+ */
+function withRequestedFee(unsigned, fee) {
+    return {
+        ...unsigned,
+        fee: { ...unsigned.fee, details: { ...unsigned.fee.details, requestedFee: fee } },
+    };
+}
+/** An Attempt's total fee, summed over its charges. */
+function feeOf(attempt) {
+    return attempt.fee.charges.reduce((sum, charge) => sum + charge.amount, 0n);
+}
+/**
+ * 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. Known gap:
+ * they are ranked by total charges, not by a price the driver compares, so on EVM a
+ * repeat cancel may need an explicit `fee`.
+ */
+function cancelBase(op, previous) {
+    let best;
+    for (const attempt of op.attempts) {
+        if (attempt.purpose !== 'cancel' || attempt.supersedes !== previous.id)
+            continue;
+        if (!best || feeOf(attempt) > feeOf(best))
+            best = attempt;
+    }
+    return best ?? previous;
+}
+/** The same `FeeSpeed` name, or a canonically equal `FeeOverride`. */
+function sameFeeSpec(attempt, fee) {
+    const recorded = attempt.fee.details.requestedFee;
+    if (recorded === undefined || fee === undefined)
+        return false;
+    try {
+        return (0, json_1.canonicalJson)(recorded) === (0, json_1.canonicalJson)(fee);
+    }
+    catch {
+        return false;
+    }
+}
+/** A node's refusal or rejection of these bytes; both are handled alike. */
+exports.NODE_REFUSED_STATES = new Set([
+    'refused',
+    'rejected',
+]);
+/** Observations under which a superseded Attempt may still be live on the network. */
+exports.LIVE_STATES = new Set([
+    'pending',
+    'mempool',
+    'included',
+]);
+/** The states in which a replacement or cancel may supersede the active Attempt. */
+exports.CONFLICTABLE_STATES = new Set([
+    'submitted',
+    'stalled',
+]);
+/** The only state `rebuild` reopens. */
+exports.REBUILDABLE_STATES = new Set([
+    'expired',
+]);
+/** Where the stored bytes of a new Attempt whose broadcast never completed are resent. */
+exports.RESUMABLE_STATES = new Set([
+    'signed',
+    'submitted',
+    'stalled',
+]);
+/**
+ * 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.
+ */
+function assertBuiltOrdering(operationId, kind, allocated, excluded, built) {
+    // No existing code names an input conflict without implying a nonce, so NONCE_CONFLICT
+    // (the ordering-slot conflict code) is kept and the message says what actually clashed.
+    if (built.kind === kind && built.kind === 'inputs') {
+        if (built.inputs.some((input) => excluded?.includes(input))) {
+            throw new error_1.ChainError('NONCE_CONFLICT', 'input reservation conflict: the built transaction spends an input held by another operation', { context: { operationId } });
+        }
+        return;
+    }
+    const matches = built.kind === kind &&
+        (built.kind === 'nonce'
+            ? allocated?.kind === 'nonce' && built.nonce === allocated.nonce
+            : built.kind === 'seqno'
+                ? allocated?.kind === 'seqno' && built.seqno === allocated.seqno
+                : true);
+    if (!matches) {
+        throw new error_1.ChainError('NONCE_CONFLICT', 'the built transaction does not use the ordering slot reserved for it', { context: { operationId } });
+    }
+}
+//# sourceMappingURL=engine-rules.js.map

package/dist/core/lifecycle/engine-rules.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine-rules.js","sourceRoot":"","sources":["../../../src/core/lifecycle/engine-rules.ts"],"names":[],"mappings":"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","sourcesContent":["import type { LifecycleOptions } from '../config/types';\nimport {\n  ChainError,\n  ConfigError,\n  createError,\n  isCryptoAioError,\n  type CryptoAioError,\n  type ErrorCode,\n  type SerializedError,\n} from '../errors/error';\nimport type { FeeOverride, FeeSpeed } from '../model/fee';\nimport type { OrderingData, OrderingKind } from '../model/ordering';\nimport type { TxState, UnsignedTx } from '../model/transaction';\nimport { sanitizeError } from '../secret/redact';\nimport type {\n  AttemptObservation,\n  AttemptRecord,\n  OperationRecord,\n  OperationState,\n  SequenceState,\n} from '../store/types';\nimport { canonicalJson } from '../util/json';\nimport type { ObservationPatch } from './observations';\n\n/*\n * The engine's pure rules: lifecycle defaults, error serialization, and the state\n * sets and predicates `OperationEngine` decides with. No I/O and no engine state.\n */\n\nexport type ResolvedLifecycle = Required<LifecycleOptions>;\n\nexport const LIFECYCLE_DEFAULTS: ResolvedLifecycle = {\n  pollIntervalMs: 5_000,\n  droppedGracePeriodMs: 120_000,\n  rebroadcastIntervalMs: 60_000,\n  leaseMs: 30_000,\n  claimLeaseMs: 60_000,\n  waitTimeoutMs: 600_000,\n  requireIdempotencyKey: false,\n  broadcastFanout: 1,\n  signTimeoutMs: 120_000,\n};\n\nexport function withLifecycleDefaults(options: LifecycleOptions): ResolvedLifecycle {\n  const out: Record<string, unknown> = { ...LIFECYCLE_DEFAULTS };\n  for (const [key, value] of Object.entries(options))\n    if (value !== undefined) out[key] = value;\n  const { signTimeoutMs } = out as ResolvedLifecycle;\n  if (\n    typeof signTimeoutMs !== 'number' ||\n    !Number.isFinite(signTimeoutMs) ||\n    signTimeoutMs <= 0\n  ) {\n    throw new ConfigError(\n      'CONFIG_INVALID',\n      'lifecycle.signTimeoutMs must be a finite number greater than 0',\n    );\n  }\n  return out as ResolvedLifecycle;\n}\n\nexport const PRE_SIGNING_STATES: ReadonlySet<OperationState> = new Set<OperationState>([\n  'created',\n  'prepared',\n  'awaiting-signature',\n]);\n\nexport const LEASED_ORDERINGS = new Set(['nonce', 'seqno', 'inputs']);\nexport const DEFINITIVE_CATEGORIES = new Set([\n  'validation',\n  'chain',\n  'unsupported',\n  'config',\n  'signing',\n]);\n\n/**\n * A crypto-aio error as it is; anything else under `fallback`, the most specific\n * existing code for the caller's context (there is no generic code), with a sanitized message.\n */\nexport function serializeError(error: unknown, fallback: ErrorCode): SerializedError {\n  return (\n    isCryptoAioError(error) ? error : createError(fallback, sanitizeError(error).message)\n  ).toJSON();\n}\n\nexport function rehydrateError(serialized: SerializedError, operationId: string): Error {\n  return createError(serialized.code, serialized.message, {\n    context: { ...serialized.context, operationId },\n    ...(serialized.details ? { details: serialized.details } : {}),\n    retryable: serialized.retryable,\n    ambiguous: serialized.ambiguous,\n  });\n}\n\n/**\n * The error's crypto-aio code, or `'UNKNOWN'`. Logs carry this, never the error itself:\n * messages may hold addresses, amounts or store detail.\n */\nexport function errorCode(error: unknown): string {\n  return isCryptoAioError(error) ? error.code : 'UNKNOWN';\n}\n\nexport function isDefinitive(error: unknown): error is CryptoAioError {\n  return (\n    isCryptoAioError(error) &&\n    !error.retryable &&\n    DEFINITIVE_CATEGORIES.has(error.category)\n  );\n}\n\n/**\n * Observation states backed by chain evidence: the Attempt was mined, or its slot or expiry\n * was consumed. No broadcast answer ever overwrites them; `replacedBy` is kept.\n */\nexport const CHAIN_EVIDENCE_STATES: ReadonlySet<TxState> = new Set<TxState>([\n  'included',\n  'final',\n  'failed',\n  'replaced',\n  'expired',\n]);\n\n/**\n * A node once accepted these bytes, or they may be live. `firstSeenAt` is the durable\n * marker: set when a node accepted them or the monitor saw them held, and kept by a refusal\n * that found them possibly live. A `pending`, `mempool` or `dropped` observation also\n * counts: one left by an accepted or ambiguous send, and the `pending` the monitor\n * writes for a signed Attempt that was never broadcast, which errs in the safe direction\n * (a genuine rejection then stalls it and keeps its nonce instead of failing it). A later\n * rejection says nothing about bytes that may still sit in a mempool, so it is only a\n * refusal: never terminal, the nonce is kept.\n */\nexport function mayBeLive(observation: AttemptObservation | null): boolean {\n  return (\n    observation !== null &&\n    (observation.firstSeenAt !== undefined ||\n      observation.state === 'pending' ||\n      observation.state === 'mempool' ||\n      observation.state === 'dropped')\n  );\n}\n\n/**\n * A send that may have delivered the bytes (accepted, already known or ambiguous): a\n * missing, `refused` or `dropped` observation becomes `pending`, and a refusal's reason no\n * longer applies. Stronger evidence (chain or proven states) is left alone. The one rule\n * for every such send, so they cannot drift apart. Known gap: an ambiguous send clears a\n * refusal and its reason, so the monitor then shows bytes the node still refuses as\n * `dropped`, not `refused`; only a resend through the engine (a same-key repeat,\n * `rebroadcast`, recovery) records the refusal again.\n */\nexport function pendingAfterSend(current: AttemptObservation | null): ObservationPatch {\n  return current === null || current.state === 'refused' || current.state === 'dropped'\n    ? { state: 'pending', reason: undefined }\n    : {};\n}\n\n/** Every nonce a live Operation holds: its reservation, unsigned payload and Attempts. */\nexport function heldNonces(op: OperationRecord): bigint[] {\n  const orderings = [\n    op.reservation,\n    op.unsigned?.ordering,\n    ...op.attempts.map((a) => a.ordering),\n  ];\n  return orderings.flatMap((o) => (o?.kind === 'nonce' ? [o.nonce] : []));\n}\n\n/** Failures proven on chain at finality: their nonce was consumed. */\nexport const CONSUMED_FAILURES: ReadonlySet<string> = new Set([\n  'TX_REVERTED',\n  'TX_REPLACED',\n]);\n\n/** Whether some value in [from, next) is neither released nor held. */\nexport function hasReclaimable(\n  state: SequenceState | null,\n  from: bigint,\n  held: readonly bigint[],\n): boolean {\n  if (!state) return false;\n  const taken = new Set([...state.released, ...held]);\n  for (let value = from; value < state.next; value++) if (!taken.has(value)) return true;\n  return false;\n}\n\n/** `signed`, or `submitted` with an unknown broadcast outcome: its stored bytes are (re)sent. */\nexport function awaitsBroadcast(op: OperationRecord): boolean {\n  return op.state === 'signed' || (op.state === 'submitted' && op.ambiguous === true);\n}\n\n/** The node's own answer (refused, rejected): not ambiguous, so the bytes were not taken. */\nexport function isRefusal(error: unknown): boolean {\n  return isCryptoAioError(error) && error.category === 'chain' && !error.ambiguous;\n}\n\n/**\n * A replacement records the fee spec it was asked for (plain data, as every store record\n * must be) in its fee details, so a repeat of the same request is recognised instead of\n * signed again. The core adds it after `build`, so a driver never sets or reads it: its\n * `assemble` reads only the fee fields it named itself.\n */\nexport function withRequestedFee(\n  unsigned: UnsignedTx,\n  fee: FeeSpeed | FeeOverride,\n): UnsignedTx {\n  return {\n    ...unsigned,\n    fee: { ...unsigned.fee, details: { ...unsigned.fee.details, requestedFee: fee } },\n  };\n}\n\n/** An Attempt's total fee, summed over its charges. */\nexport function feeOf(attempt: AttemptRecord): bigint {\n  return attempt.fee.charges.reduce((sum, charge) => sum + charge.amount, 0n);\n}\n\n/**\n * The cancel a new cancel is bumped from: among the earlier cancels that superseded\n * the active Attempt `previous` (refused ones gave it the active role back), the one paying\n * the most, so repeated bumps climb; otherwise `previous` itself, so a cancel never starts\n * below a newer, higher replacement. Fees are compared only between cancels. Known gap:\n * they are ranked by total charges, not by a price the driver compares, so on EVM a\n * repeat cancel may need an explicit `fee`.\n */\nexport function cancelBase(op: OperationRecord, previous: AttemptRecord): AttemptRecord {\n  let best: AttemptRecord | undefined;\n  for (const attempt of op.attempts) {\n    if (attempt.purpose !== 'cancel' || attempt.supersedes !== previous.id) continue;\n    if (!best || feeOf(attempt) > feeOf(best)) best = attempt;\n  }\n  return best ?? previous;\n}\n\n/** The same `FeeSpeed` name, or a canonically equal `FeeOverride`. */\nexport function sameFeeSpec(\n  attempt: AttemptRecord,\n  fee: FeeSpeed | FeeOverride | undefined,\n): boolean {\n  const recorded = attempt.fee.details.requestedFee;\n  if (recorded === undefined || fee === undefined) return false;\n  try {\n    return canonicalJson(recorded) === canonicalJson(fee);\n  } catch {\n    return false;\n  }\n}\n\n/**\n * What `restoreAfterRefusal` puts back: the Operation as the refused Attempt found it.\n * Without `state`, only the active Attempt is swapped (state and error are kept).\n */\nexport interface RestorePoint {\n  readonly state?: OperationState;\n  readonly activeAttemptId: string;\n  readonly error?: SerializedError;\n  readonly ambiguous?: boolean;\n}\n\n/** A node's refusal or rejection of these bytes; both are handled alike. */\nexport const NODE_REFUSED_STATES: ReadonlySet<TxState> = new Set<TxState>([\n  'refused',\n  'rejected',\n]);\n\n/** Observations under which a superseded Attempt may still be live on the network. */\nexport const LIVE_STATES: ReadonlySet<TxState> = new Set<TxState>([\n  'pending',\n  'mempool',\n  'included',\n]);\n\n/** The states in which a replacement or cancel may supersede the active Attempt. */\nexport const CONFLICTABLE_STATES: ReadonlySet<OperationState> = new Set<OperationState>([\n  'submitted',\n  'stalled',\n]);\n/** The only state `rebuild` reopens. */\nexport const REBUILDABLE_STATES: ReadonlySet<OperationState> = new Set<OperationState>([\n  'expired',\n]);\n/** Where the stored bytes of a new Attempt whose broadcast never completed are resent. */\nexport const RESUMABLE_STATES: ReadonlySet<OperationState> = new Set<OperationState>([\n  'signed',\n  'submitted',\n  'stalled',\n]);\n\n/**\n * The built transaction must use exactly the slot the engine reserved: the ordering\n * kind of the driver, the allocated nonce or seqno, and no input held by another live\n * Operation. Anything else would persist a reservation nobody allocated.\n */\nexport function assertBuiltOrdering(\n  operationId: string,\n  kind: OrderingKind,\n  allocated: OrderingData | undefined,\n  excluded: readonly string[] | undefined,\n  built: OrderingData,\n): void {\n  // No existing code names an input conflict without implying a nonce, so NONCE_CONFLICT\n  // (the ordering-slot conflict code) is kept and the message says what actually clashed.\n  if (built.kind === kind && built.kind === 'inputs') {\n    if (built.inputs.some((input) => excluded?.includes(input))) {\n      throw new ChainError(\n        'NONCE_CONFLICT',\n        'input reservation conflict: the built transaction spends an input held by another operation',\n        { context: { operationId } },\n      );\n    }\n    return;\n  }\n  const matches =\n    built.kind === kind &&\n    (built.kind === 'nonce'\n      ? allocated?.kind === 'nonce' && built.nonce === allocated.nonce\n      : built.kind === 'seqno'\n        ? allocated?.kind === 'seqno' && built.seqno === allocated.seqno\n        : true);\n  if (!matches) {\n    throw new ChainError(\n      'NONCE_CONFLICT',\n      'the built transaction does not use the ordering slot reserved for it',\n      { context: { operationId } },\n    );\n  }\n}\n"]}