@valve-tech/tx-tracker 0.6.0 → 0.8.0

package/dist/tracker.d.ts

@@ -0,0 +1,211 @@
+/**
+ * `createTxTracker` — the per-tx state machine that turns a
+ * `ChainSource`'s block + mempool stream into a stream of neutral
+ * observations per tracked hash.
+ *
+ * Per `docs/tx-tracker-spec.md` §5.2 + §6 + §11 + §12. This file is
+ * the load-bearing piece of `@valve-tech/tx-tracker`; everything
+ * else is supporting infrastructure (events, store, reorg detector,
+ * selectors).
+ *
+ * Design rules carried in from the spec and the contributing skill:
+ *
+ *   - **Three consumption shapes, one underlying stream** (§5.3).
+ *     `getTxStatus(hash)` reads the cached snapshot; `subscribe(hash, cb)`
+ *     attaches a callback; `track(hash)` returns an async iterator.
+ *     All three see consistent state because they read from one
+ *     internal `Subscriptions<TxEvent>` per hash.
+ *
+ *   - **Neutral observations only** (§2.1). The tracker emits
+ *     `seen-in-mempool` / `seen-in-block` / `vanished-from-block` /
+ *     `replaced-by` / `unseen-for-N-blocks` and lets the consumer
+ *     write the policy that says "confirmed" or "stuck" in their
+ *     UX voice.
+ *
+ *   - **No silent downgrade** (§2.2). Every emitted event carries a
+ *     `source` discriminator. When the source's `capabilities()`
+ *     change between ticks, the tracker emits `signal-degraded` /
+ *     `signal-recovered` per affected capability.
+ *
+ *   - **No own poll cycle** (§3.1, contributing-skill rule 3). The
+ *     tracker hangs off `source.subscribeBlocks` and
+ *     `source.subscribeMempool`; every per-tick computation runs
+ *     inside those callbacks.
+ *
+ *   - **Browser/mobile safe** (§2.4). No Node-only deps; the
+ *     pub/sub primitive is `chain-source`'s `Subscriptions<E>`.
+ */
+import type { ChainSource, Capabilities, RawTx } from '@valve-tech/chain-source';
+import type { TxGroupEvent } from './group-events.js';
+import { type Address, type At, type Hash, type TxEvent, type TxStatus } from './events.js';
+import { type BulkSelector, type TxTrackerStore } from './store.js';
+/**
+ * Lost-signal policy (spec §8). `'emit-uncertain'` is the default
+ * — every transition to a degraded source emits `signal-degraded`.
+ * `'silent'` keeps the events to itself; `'receipt-poll-fallback'`
+ * fetches `eth_getTransactionReceipt` every `pollEveryBlocks` block
+ * ticks and emits `seen-in-block` with `source: 'receipt-poll'` on a
+ * hit. Requires `capabilities().receiptByHash === 'available'`;
+ * when unavailable, downgrades to emit-uncertain semantics with a
+ * one-shot warning via `onError`.
+ */
+export type LostSignalPolicy = 'emit-uncertain' | 'silent' | {
+    strategy: 'receipt-poll-fallback';
+    pollEveryBlocks: number;
+};
+/**
+ * Per-subscription overrides on top of the tracker defaults. See
+ * spec §5.4.
+ */
+export interface TrackOptions {
+    /**
+     * Emit a synthetic `started` event on subscribe even if no real
+     * observation has fired yet. Default true. Wallets use this to
+     * render an "awaiting first observation" state without polling.
+     */
+    emitInitial?: boolean;
+    /**
+     * Persist this subscription via the store. Default false — the
+     * subscription survives only the current process. Indexer / relay
+     * consumers set this true.
+     */
+    durable?: boolean;
+    /** Per-subscription override of the tracker's `lostSignalPolicy`. */
+    lostSignalPolicy?: LostSignalPolicy;
+    /**
+     * How many consecutive blocks the hash must be unseen (not in
+     * mempool, not in the canonical block) before
+     * `unseen-for-N-blocks` fires. Default 30 (spec §6.1).
+     */
+    unseenThresholdBlocks?: number;
+    /**
+     * Eager receipt enrichment. When true, fetch the transaction
+     * receipt at seen-in-block time and attach it to the event via
+     * the `receipt` field. Adds one RPC per inclusion. Default false.
+     * Capability gate: requires source.capabilities().receiptByHash ===
+     * 'available'; when unavailable, events still flow but `receipt`
+     * is absent and a one-shot warning surfaces via onError.
+     */
+    withReceipts?: boolean;
+}
+/** Bulk subscription options — extends per-hash `TrackOptions`. */
+export interface BulkTrackOptions extends TrackOptions {
+    /**
+     * Auto-track every tx the selector matches by starting an
+     * implicit per-hash subscription for it. Default true — an
+     * indexer wiring `trackFromAddress(treasury)` typically wants
+     * the per-hash event stream too. Set false to receive only the
+     * raw `matched` stream without per-hash detail.
+     */
+    autoTrackMatched?: boolean;
+}
+/** One emit from a bulk subscription — see spec §11.1. */
+export interface TxMatchEvent {
+    kind: 'matched';
+    hash: Hash;
+    matchedBy: 'from' | 'to' | 'predicate';
+    selector: BulkSelector;
+    tx: RawTx;
+    source: 'mempool-snapshot' | 'block-poll';
+    at: At;
+}
+/** Handle returned by every bulk-track method. */
+export interface TxSubscription {
+    /**
+     * Async iterator over the raw `matched` stream. Iteration ends
+     * when `stop()` is called or the tracker stops.
+     */
+    events(): AsyncIterable<TxMatchEvent>;
+    /**
+     * Imperative subscription to per-hash events on every matched tx.
+     * Returns an unsubscribe handle.
+     */
+    subscribe(cb: (event: TxEvent) => void): () => void;
+    /**
+     * Stop the bulk subscription. Per-hash subscriptions auto-tracked
+     * via this bulk subscription continue under their own retention
+     * rules (spec §11.1).
+     */
+    stop(): void;
+}
+/** Factory options. */
+export interface CreateTxTrackerOptions {
+    source: ChainSource;
+    chainId: number;
+    store?: TxTrackerStore;
+    lostSignalPolicy?: LostSignalPolicy;
+    reorgDepthBlocks?: number;
+    /** Default `unseenThresholdBlocks` for new subscriptions. */
+    unseenThresholdBlocks?: number;
+    /** Cap on simultaneous bulk subscriptions (spec §11.3). */
+    maxBulkSubscriptions?: number;
+    onError?: (method: string, err: unknown) => void;
+    lifecycle?: 'eager' | 'lazy';
+}
+/**
+ * Options for a group subscription. All fields are optional — the group
+ * works with defaults. See `createTxGroup` in `group.ts`.
+ */
+export interface GroupOptions {
+    /** Optional human-readable group ID echoed in events. Default: random. */
+    groupId?: string;
+    /** Per-member TrackOptions applied to each hash. */
+    memberOptions?: TrackOptions;
+}
+/**
+ * Handle returned by `tracker.group(hashes, options?)`. Exposes three
+ * consumption shapes (async iterator, callback, snapshot) over the same
+ * group-event stream, plus a `stop()` to tear down all member
+ * subscriptions.
+ */
+export interface TxGroupSubscription {
+    /** Async-iterable surface over the group event stream. */
+    events(): AsyncIterable<TxGroupEvent>;
+    /**
+     * Imperative callback subscription. Returns an unsubscribe handle.
+     */
+    subscribe(cb: (event: TxGroupEvent) => void): () => void;
+    /** Snapshot of each member's current `TxStatus` (null if not yet observed). */
+    snapshot(): Record<Hash, TxStatus | null>;
+    /** Tear down all member subscriptions and emit `group-stopped`. */
+    stop(): void;
+}
+/** Public surface returned by `createTxTracker`. */
+export interface TxTracker {
+    start(): void;
+    stop(): void;
+    getTxStatus(hash: Hash): TxStatus | null;
+    track(hash: Hash, options?: TrackOptions): AsyncIterable<TxEvent>;
+    subscribe(hash: Hash, cb: (event: TxEvent) => void, options?: TrackOptions): () => void;
+    trackFromAddress(address: Address, options?: BulkTrackOptions): TxSubscription;
+    trackToAddress(address: Address, options?: BulkTrackOptions): TxSubscription;
+    trackPredicate(match: (tx: RawTx) => boolean, options?: BulkTrackOptions): TxSubscription;
+    capabilities(): Capabilities;
+    subscribeAll(cb: (event: TxEvent) => void): () => void;
+    /**
+     * Cross-tx correlation — track a logical group of related hashes
+     * (e.g., a wallet's "claim + swap" pair). Emits group-level
+     * synthesis events derived from the per-member event streams.
+     * See spec §18.1, v0.8.0 design F3.
+     */
+    group(hashes: Hash[], options?: GroupOptions): TxGroupSubscription;
+}
+/**
+ * Build a configured tracker.
+ *
+ * @example
+ *   import { createChainSource } from '@valve-tech/chain-source'
+ *   import { createTxTracker } from '@valve-tech/tx-tracker'
+ *
+ *   const source  = createChainSource({ client })
+ *   const tracker = createTxTracker({ source, chainId: 1 })
+ *
+ *   source.start()
+ *   tracker.start()
+ *
+ *   for await (const event of tracker.track('0xabc...')) {
+ *     if (event.kind === 'seen-in-block' && event.confirmations >= 3) break
+ *   }
+ */
+export declare const createTxTracker: (options: CreateTxTrackerOptions) => TxTracker;
+//# sourceMappingURL=tracker.d.ts.map

package/dist/tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracker.d.ts","sourceRoot":"","sources":["../src/tracker.ts"],"names":[],"mappings":"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"}