crypto-aio 0.0.2 → 0.1.0

package/dist/core/lifecycle/monitor.d.ts

@@ -0,0 +1,138 @@
+import type { ResolvedSelection } from '../config/types';
+import type { EventBus } from '../events/bus';
+import type { Logger } from '../events/logger';
+import type { TxStatus } from '../model/transaction';
+import { type Fence, type OperationRecord, type Stores } from '../store/types';
+import type { Clock } from '../util/clock';
+import { type OperationEngine, type OperationTarget, type ReadTarget, type ResolvedLifecycle } from './engine';
+import { type OperationView } from './views';
+import { type RecoveryReport, type WorkerOptions } from './workers';
+export interface WaitOptions {
+    /** Default: the handle's `confirmations`. Ignored when `finality: 'final'`. */
+    readonly confirmations?: number;
+    readonly finality?: 'included' | 'final';
+    readonly timeoutMs?: number;
+    readonly pollIntervalMs?: number;
+    readonly signal?: AbortSignal;
+}
+export interface ConfirmationResult {
+    readonly status: TxStatus;
+    readonly operation?: OperationView;
+}
+export interface TxStatusEvent {
+    readonly status: TxStatus;
+    readonly operation?: OperationView;
+}
+export type { RecoveryReport, WorkerOptions } from './workers';
+/**
+ * Rebuilds the wallet-bound target of a stored Operation (from its `context`); `undefined`
+ * (or a rejection) when it cannot be resolved any more, e.g. its wallet config is gone.
+ */
+export type TargetResolver = (op: OperationRecord) => Promise<OperationTarget | undefined>;
+/** Rebuilds the signer-free read target of a stored Operation; see `TargetResolver`. */
+export type ReadResolver = (op: OperationRecord) => Promise<ReadTarget | undefined>;
+export interface MonitorDeps {
+    readonly engine: OperationEngine;
+    readonly stores: Stores;
+    readonly events: EventBus;
+    readonly clock: Clock;
+    readonly log: Logger;
+    readonly namespace: string;
+    readonly lifecycle: () => ResolvedLifecycle;
+    /**
+     * Every check, worker pass and recovery read runs on this target (no wallet), so a
+     * signer rotated out of config or a hung `getPublicKey` never stalls monitoring.
+     */
+    readonly resolveRead: ReadResolver;
+    /**
+     * Resolved lazily, only for the writes that need a wallet-bound target: the
+     * all-rejected verdict, nonce reconciliation and recovery's resend (none of them signs).
+     * Known gap: for the all-rejected verdict this resolution is bounded neither by the
+     * pass `signal` nor by a per-pass cache, so each such Operation of a pass can wait up
+     * to `lifecycle.signTimeoutMs` for a wallet whose resolution keeps failing.
+     */
+    readonly resolveTarget: TargetResolver;
+}
+interface Snapshot {
+    readonly status: TxStatus;
+    readonly record?: OperationRecord;
+}
+/**
+ * Watches Attempts on chain and moves their Operation on evidence.
+ * Observed data (a single endpoint's view, absence, `dropped`, `refused`, an unfinalized
+ * block) only ever produces non-terminal states; a terminal state needs `proven` evidence
+ * (finalized data confirmed by quorum proof reads). A stale view decides nothing.
+ */
+export declare class Monitor {
+    #private;
+    private readonly deps;
+    constructor(deps: MonitorDeps);
+    private get observationDeps();
+    /** Finds a managed Operation by id, Attempt ref or observed canonical tx hash. */
+    find(ref: string): Promise<OperationRecord | null>;
+    /**
+     * One evaluation pass: observe live Attempts, persist observations, apply the transition.
+     * `signal` is checked before every read, so an aborted pass stops after at most the
+     * read in flight; it then throws the signal's reason and decides nothing further.
+     */
+    check(target: ReadTarget, op: OperationRecord, fence?: Fence, signal?: AbortSignal): Promise<OperationRecord>;
+    /** Current status of a managed Operation (after a check) or of an arbitrary transaction id. */
+    status(target: ReadTarget, ref: string, signal?: AbortSignal): Promise<Snapshot>;
+    /**
+     * Polls until the wanted status: `confirmations` (default: the handle's) or, with
+     * `finality: 'final'`, proven finality for a managed Operation and observed finality for
+     * a transaction it does not manage. The caller's `signal` and the deadline bound
+     * every pass and sleep; a pass stops after at most the read in flight.
+     */
+    waitFor(target: ReadTarget, ref: string, options?: WaitOptions): Promise<Snapshot>;
+    /**
+     * Yields each status change until the Operation is terminal, or until a transaction
+     * it does not manage reaches observed finality, whether it succeeded or reverted. Ends
+     * quietly when `signal` aborts.
+     */
+    watch(target: ReadTarget, ref: string, options?: {
+        readonly pollIntervalMs?: number;
+        readonly signal?: AbortSignal;
+    }): AsyncGenerator<Snapshot>;
+    /** One worker pass (see `Workers.runOnce`); resolves to how many Operations it claimed. */
+    runOnce(options: {
+        readonly workerId: string;
+        readonly batch?: number;
+        readonly signal?: AbortSignal;
+    }): Promise<number>;
+    /** Runs worker passes until `signal` aborts (see `Workers.start`). */
+    start(options?: WorkerOptions): Promise<void>;
+    /** Startup recovery for this namespace; it never signs (see `Workers.recover`). */
+    recover(options?: {
+        readonly signal?: AbortSignal;
+    }): Promise<RecoveryReport>;
+    private observeAttempt;
+    /**
+     * A block at or below the finalized height becomes `final`/`failed` + `proven` only when
+     * the quorum proof confirms it. A retryable proof failure (e.g. PROVIDER_INCONSISTENT)
+     * decides nothing: the observed patch is kept.
+     */
+    private proveFinal;
+    /**
+     * Whether the block recorded for `observation` is no longer the one at its height.
+     * Only the quorum-served hash decides; a disagreement or other retryable failure, or no
+     * block at that height yet, decides nothing (`false`).
+     */
+    private orphaned;
+    /** The transaction is not visible anywhere we can see: only finalized proofs may declare it dead. */
+    private whenAbsent;
+    private applyEvaluation;
+    /**
+     * Hands the all-rejected verdict to the engine: an unfenced pass (`tryOnce`) tries the
+     * lease once, a fenced one waits `acquireTimeoutMs`, and either wait is bounded by the
+     * pass `signal` (the caller's abort and, in `waitFor`, its deadline). A fenced pass's
+     * terminal write carries its claim `fence`, so a worker whose claim was taken over writes
+     * nothing. An unresolvable target leaves the Operation non-terminal.
+     */
+    private failRejected;
+    private bestStatus;
+    private rawStatus;
+    private defaultError;
+}
+/** Refuses a stored Operation of another chain or network than `selection` (INVALID_INTENT). */
+export declare function assertSameNetwork(selection: Pick<ResolvedSelection, 'chain' | 'network'>, record: OperationRecord): void;