@valve-tech/tx-tracker 0.7.0 → 0.8.0

package/dist/wait-for-pending.d.ts

@@ -0,0 +1,41 @@
+/**
+ * `waitForPending` — Promise that resolves when a tx hash is first
+ * observed in any mempool. Rejects with `WaitForPendingTimeoutError`
+ * if `timeoutBlocks` elapses without observation.
+ *
+ * Surfaces the "submitted but never arrived" failure mode explicitly:
+ * when an RPC accepts a transaction but the tx never appears in any
+ * observed mempool, this helper times out rather than hanging.
+ *
+ * Internally constructs a private ChainSource + TxTracker (or accepts
+ * a `_sourceOverride` for tests) and tears them down before settling.
+ */
+import type { PublicClient } from 'viem';
+import type { ChainSource } from '@valve-tech/chain-source';
+import type { Hash, TxEventSeenInMempool } from './events.js';
+export declare class WaitForPendingTimeoutError extends Error {
+    readonly hash: Hash;
+    readonly observedBlocks: number;
+    constructor(hash: Hash, observedBlocks: number);
+}
+export interface WaitForPendingOptions {
+    client: PublicClient;
+    hash: Hash;
+    /**
+     * Reject with WaitForPendingTimeoutError if the hash isn't observed
+     * in any mempool within this many block ticks. Default 12.
+     */
+    timeoutBlocks?: number;
+    pollIntervalMs?: number;
+    onError?: (method: string, err: unknown) => void;
+}
+/**
+ * @internal
+ * Test-injection seam — same shape as the other helpers' seams.
+ * Not re-exported from index.ts.
+ */
+export interface WaitForPendingInternalOptions extends WaitForPendingOptions {
+    _sourceOverride?: ChainSource;
+}
+export declare const waitForPending: (options: WaitForPendingOptions) => Promise<TxEventSeenInMempool>;
+//# sourceMappingURL=wait-for-pending.d.ts.map

package/dist/wait-for-pending.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wait-for-pending.d.ts","sourceRoot":"","sources":["../src/wait-for-pending.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,MAAM,CAAA;AACxC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAA;AAG3D,OAAO,KAAK,EAAE,IAAI,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAA;AAG7D,qBAAa,0BAA2B,SAAQ,KAAK;IACnD,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAA;IACnB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;gBACnB,IAAI,EAAE,IAAI,EAAE,cAAc,EAAE,MAAM;CAQ/C;AAED,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,YAAY,CAAA;IACpB,IAAI,EAAE,IAAI,CAAA;IACV;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,KAAK,IAAI,CAAA;CACjD;AAED;;;;GAIG;AACH,MAAM,WAAW,6BAA8B,SAAQ,qBAAqB;IAC1E,eAAe,CAAC,EAAE,WAAW,CAAA;CAC9B;AAED,eAAO,MAAM,cAAc,GACzB,SAAS,qBAAqB,KAC7B,OAAO,CAAC,oBAAoB,CA0D9B,CAAA"}

package/dist/wait-for-pending.js

@@ -0,0 +1,71 @@
+/**
+ * `waitForPending` — Promise that resolves when a tx hash is first
+ * observed in any mempool. Rejects with `WaitForPendingTimeoutError`
+ * if `timeoutBlocks` elapses without observation.
+ *
+ * Surfaces the "submitted but never arrived" failure mode explicitly:
+ * when an RPC accepts a transaction but the tx never appears in any
+ * observed mempool, this helper times out rather than hanging.
+ *
+ * Internally constructs a private ChainSource + TxTracker (or accepts
+ * a `_sourceOverride` for tests) and tears them down before settling.
+ */
+import { createChainSource } from '@valve-tech/chain-source';
+import { createTxTracker } from './tracker.js';
+export class WaitForPendingTimeoutError extends Error {
+    constructor(hash, observedBlocks) {
+        super(`waitForPending: hash ${hash} not observed in any mempool after ${observedBlocks} block(s)`);
+        this.name = 'WaitForPendingTimeoutError';
+        this.hash = hash;
+        this.observedBlocks = observedBlocks;
+    }
+}
+export const waitForPending = (options) => {
+    const internalOptions = options;
+    const timeoutBlocks = options.timeoutBlocks ?? 12;
+    return new Promise((resolve, reject) => {
+        const source = internalOptions._sourceOverride ??
+            createChainSource({
+                client: options.client,
+                pollIntervalMs: options.pollIntervalMs,
+                onError: options.onError,
+            });
+        const tracker = createTxTracker({
+            source,
+            chainId: 0,
+            onError: options.onError,
+        });
+        source.start();
+        tracker.start();
+        let teardownSubscribe = null;
+        let teardownBlocks = null;
+        let observedBlocks = 0;
+        // No `settled` flag: tracker.stop() / source.stop() / the unsub handles
+        // are all idempotent, and Promise resolve/reject are no-ops on second
+        // call. The first finish() call detaches both callbacks, so subsequent
+        // events for this hash don't reach them — no double-call path remains.
+        const finish = (action) => {
+            teardownSubscribe?.();
+            teardownBlocks?.();
+            tracker.stop();
+            source.stop();
+            action();
+        };
+        teardownSubscribe = tracker.subscribe(options.hash, (event) => {
+            // Filter for the only event kind that resolves this helper. The
+            // synthetic `stopped` event fired during teardownSubscribe also
+            // flows through here and falls through the kind check.
+            if (event.kind === 'seen-in-mempool') {
+                finish(() => resolve(event));
+            }
+        }, { emitInitial: false });
+        teardownBlocks = source.subscribeBlocks(() => {
+            observedBlocks++;
+            if (observedBlocks >= timeoutBlocks) {
+                const err = new WaitForPendingTimeoutError(options.hash, observedBlocks);
+                finish(() => reject(err));
+            }
+        });
+    });
+};
+//# sourceMappingURL=wait-for-pending.js.map

package/dist/wait-for-pending.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wait-for-pending.js","sourceRoot":"","sources":["../src/wait-for-pending.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAA;AAG5D,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AAE9C,MAAM,OAAO,0BAA2B,SAAQ,KAAK;IAGnD,YAAY,IAAU,EAAE,cAAsB;QAC5C,KAAK,CACH,wBAAwB,IAAI,sCAAsC,cAAc,WAAW,CAC5F,CAAA;QACD,IAAI,CAAC,IAAI,GAAG,4BAA4B,CAAA;QACxC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;QAChB,IAAI,CAAC,cAAc,GAAG,cAAc,CAAA;IACtC,CAAC;CACF;AAuBD,MAAM,CAAC,MAAM,cAAc,GAAG,CAC5B,OAA8B,EACC,EAAE;IACjC,MAAM,eAAe,GAAG,OAAwC,CAAA;IAChE,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,IAAI,EAAE,CAAA;IAEjD,OAAO,IAAI,OAAO,CAAuB,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QAC3D,MAAM,MAAM,GACV,eAAe,CAAC,eAAe;YAC/B,iBAAiB,CAAC;gBAChB,MAAM,EAAE,OAAO,CAAC,MAAM;gBACtB,cAAc,EAAE,OAAO,CAAC,cAAc;gBACtC,OAAO,EAAE,OAAO,CAAC,OAAO;aACzB,CAAC,CAAA;QACJ,MAAM,OAAO,GAAG,eAAe,CAAC;YAC9B,MAAM;YACN,OAAO,EAAE,CAAC;YACV,OAAO,EAAE,OAAO,CAAC,OAAO;SACzB,CAAC,CAAA;QAEF,MAAM,CAAC,KAAK,EAAE,CAAA;QACd,OAAO,CAAC,KAAK,EAAE,CAAA;QAEf,IAAI,iBAAiB,GAAwB,IAAI,CAAA;QACjD,IAAI,cAAc,GAAwB,IAAI,CAAA;QAC9C,IAAI,cAAc,GAAG,CAAC,CAAA;QAEtB,wEAAwE;QACxE,sEAAsE;QACtE,uEAAuE;QACvE,uEAAuE;QACvE,MAAM,MAAM,GAAG,CAAC,MAAkB,EAAQ,EAAE;YAC1C,iBAAiB,EAAE,EAAE,CAAA;YACrB,cAAc,EAAE,EAAE,CAAA;YAClB,OAAO,CAAC,IAAI,EAAE,CAAA;YACd,MAAM,CAAC,IAAI,EAAE,CAAA;YACb,MAAM,EAAE,CAAA;QACV,CAAC,CAAA;QAED,iBAAiB,GAAG,OAAO,CAAC,SAAS,CACnC,OAAO,CAAC,IAAI,EACZ,CAAC,KAAK,EAAE,EAAE;YACR,gEAAgE;YAChE,gEAAgE;YAChE,uDAAuD;YACvD,IAAI,KAAK,CAAC,IAAI,KAAK,iBAAiB,EAAE,CAAC;gBACrC,MAAM,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAA;YAC9B,CAAC;QACH,CAAC,EACD,EAAE,WAAW,EAAE,KAAK,EAAE,CACvB,CAAA;QAED,cAAc,GAAG,MAAM,CAAC,eAAe,CAAC,GAAG,EAAE;YAC3C,cAAc,EAAE,CAAA;YAChB,IAAI,cAAc,IAAI,aAAa,EAAE,CAAC;gBACpC,MAAM,GAAG,GAAG,IAAI,0BAA0B,CAAC,OAAO,CAAC,IAAI,EAAE,cAAc,CAAC,CAAA;gBACxE,MAAM,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAA;YAC3B,CAAC;QACH,CAAC,CAAC,CAAA;IACJ,CAAC,CAAC,CAAA;AACJ,CAAC,CAAA"}

package/dist/wait-for-transaction.d.ts

@@ -0,0 +1,55 @@
+/**
+ * `waitForTransaction` — Promise variant of `watchTransaction`. Use
+ * when you'd rather `await` the outcome than register callbacks.
+ *
+ * Resolves with a discriminated union: { status: 'mined' | 'dropped'
+ * | 'replaced' | 'failed', ... }. Rejects only on tracker/source
+ * errors — transaction outcomes are part of the resolved value, not
+ * exceptions.
+ *
+ * Internally constructs a private ChainSource + TxTracker and tears
+ * them down before resolving.
+ */
+import type { PublicClient } from 'viem';
+import type { ChainSource, TransactionReceipt } from '@valve-tech/chain-source';
+import type { Hash, TxEventReplacedBy, TxEventSeenInBlock } from './events.js';
+export type WaitForTransactionOutcome = {
+    status: 'mined';
+    event: TxEventSeenInBlock;
+} | {
+    status: 'dropped';
+    reason: 'unseen-for-N-blocks';
+} | {
+    status: 'replaced';
+    replacementHash: Hash;
+    event: TxEventReplacedBy;
+} | {
+    status: 'failed';
+    event: TxEventSeenInBlock;
+    receipt: TransactionReceipt;
+};
+export interface WaitForTransactionOptions {
+    client: PublicClient;
+    hash: Hash;
+    /** Required confirmations before 'mined' resolves. Default 1. */
+    confirmations?: number;
+    /** Blocks of "no observation" before 'dropped' resolves. Default 12. */
+    staleAfterBlocks?: number;
+    /**
+     * If true, fetches the receipt at inclusion and resolves with
+     * 'failed' when receipt.status === '0x0'. Adds one RPC.
+     */
+    withReceipts?: boolean;
+    pollIntervalMs?: number;
+    onError?: (method: string, err: unknown) => void;
+}
+/**
+ * @internal
+ * Test-injection seam — same shape as watchTransaction's seam.
+ * Not re-exported from index.ts.
+ */
+export interface WaitForTransactionInternalOptions extends WaitForTransactionOptions {
+    _sourceOverride?: ChainSource;
+}
+export declare const waitForTransaction: (options: WaitForTransactionOptions) => Promise<WaitForTransactionOutcome>;
+//# sourceMappingURL=wait-for-transaction.d.ts.map

package/dist/wait-for-transaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wait-for-transaction.d.ts","sourceRoot":"","sources":["../src/wait-for-transaction.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,MAAM,CAAA;AACxC,OAAO,KAAK,EACV,WAAW,EACX,kBAAkB,EACnB,MAAM,0BAA0B,CAAA;AAGjC,OAAO,KAAK,EACV,IAAI,EACJ,iBAAiB,EACjB,kBAAkB,EACnB,MAAM,aAAa,CAAA;AAGpB,MAAM,MAAM,yBAAyB,GACjC;IAAE,MAAM,EAAE,OAAO,CAAC;IAAK,KAAK,EAAE,kBAAkB,CAAA;CAAE,GAClD;IAAE,MAAM,EAAE,SAAS,CAAC;IAAG,MAAM,EAAE,qBAAqB,CAAA;CAAE,GACtD;IAAE,MAAM,EAAE,UAAU,CAAC;IAAE,eAAe,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,iBAAiB,CAAA;CAAE,GACxE;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAI,KAAK,EAAE,kBAAkB,CAAC;IAAC,OAAO,EAAE,kBAAkB,CAAA;CAAE,CAAA;AAEnF,MAAM,WAAW,yBAAyB;IACxC,MAAM,EAAE,YAAY,CAAA;IACpB,IAAI,EAAE,IAAI,CAAA;IACV,iEAAiE;IACjE,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,wEAAwE;IACxE,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,KAAK,IAAI,CAAA;CACjD;AAED;;;;GAIG;AACH,MAAM,WAAW,iCAAkC,SAAQ,yBAAyB;IAClF,eAAe,CAAC,EAAE,WAAW,CAAA;CAC9B;AAED,eAAO,MAAM,kBAAkB,GAC7B,SAAS,yBAAyB,KACjC,OAAO,CAAC,yBAAyB,CAkEnC,CAAA"}

package/dist/wait-for-transaction.js

@@ -0,0 +1,72 @@
+/**
+ * `waitForTransaction` — Promise variant of `watchTransaction`. Use
+ * when you'd rather `await` the outcome than register callbacks.
+ *
+ * Resolves with a discriminated union: { status: 'mined' | 'dropped'
+ * | 'replaced' | 'failed', ... }. Rejects only on tracker/source
+ * errors — transaction outcomes are part of the resolved value, not
+ * exceptions.
+ *
+ * Internally constructs a private ChainSource + TxTracker and tears
+ * them down before resolving.
+ */
+import { createChainSource } from '@valve-tech/chain-source';
+import { createTxTracker } from './tracker.js';
+export const waitForTransaction = (options) => {
+    const internalOptions = options;
+    const confirmations = options.confirmations ?? 1;
+    const staleAfterBlocks = options.staleAfterBlocks ?? 12;
+    return new Promise((resolve) => {
+        const source = internalOptions._sourceOverride ??
+            createChainSource({
+                client: options.client,
+                pollIntervalMs: options.pollIntervalMs,
+                onError: options.onError,
+            });
+        const tracker = createTxTracker({
+            source,
+            chainId: 0,
+            onError: options.onError,
+        });
+        source.start();
+        tracker.start();
+        let teardownSubscribe = null;
+        // No `settled` flag: tracker.stop() / source.stop() / teardownSubscribe
+        // are all idempotent, and Promise resolve is a no-op on second call.
+        // The first finish() detaches the subscription, so subsequent events
+        // for this hash don't reach the callback — no double-call path remains.
+        const finish = (outcome) => {
+            teardownSubscribe?.();
+            tracker.stop();
+            source.stop();
+            resolve(outcome);
+        };
+        teardownSubscribe = tracker.subscribe(options.hash, (event) => {
+            if (event.kind === 'seen-in-block' && event.confirmations >= confirmations) {
+                if (options.withReceipts && event.receipt && event.receipt.status === '0x0') {
+                    finish({ status: 'failed', event, receipt: event.receipt });
+                    return;
+                }
+                finish({ status: 'mined', event });
+                return;
+            }
+            if (event.kind === 'unseen-for-N-blocks' && event.blocks >= staleAfterBlocks) {
+                finish({ status: 'dropped', reason: 'unseen-for-N-blocks' });
+                return;
+            }
+            if (event.kind === 'replaced-by') {
+                finish({
+                    status: 'replaced',
+                    replacementHash: event.replacementHash,
+                    event,
+                });
+                return;
+            }
+        }, {
+            emitInitial: false,
+            unseenThresholdBlocks: staleAfterBlocks,
+            ...(options.withReceipts ? { withReceipts: true } : {}),
+        });
+    });
+};
+//# sourceMappingURL=wait-for-transaction.js.map

package/dist/wait-for-transaction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wait-for-transaction.js","sourceRoot":"","sources":["../src/wait-for-transaction.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAOH,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAA;AAO5D,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AAiC9C,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAChC,OAAkC,EACE,EAAE;IACtC,MAAM,eAAe,GAAG,OAA4C,CAAA;IACpE,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,IAAI,CAAC,CAAA;IAChD,MAAM,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,IAAI,EAAE,CAAA;IAEvD,OAAO,IAAI,OAAO,CAA4B,CAAC,OAAO,EAAE,EAAE;QACxD,MAAM,MAAM,GACV,eAAe,CAAC,eAAe;YAC/B,iBAAiB,CAAC;gBAChB,MAAM,EAAE,OAAO,CAAC,MAAM;gBACtB,cAAc,EAAE,OAAO,CAAC,cAAc;gBACtC,OAAO,EAAE,OAAO,CAAC,OAAO;aACzB,CAAC,CAAA;QACJ,MAAM,OAAO,GAAG,eAAe,CAAC;YAC9B,MAAM;YACN,OAAO,EAAE,CAAC;YACV,OAAO,EAAE,OAAO,CAAC,OAAO;SACzB,CAAC,CAAA;QAEF,MAAM,CAAC,KAAK,EAAE,CAAA;QACd,OAAO,CAAC,KAAK,EAAE,CAAA;QAEf,IAAI,iBAAiB,GAAwB,IAAI,CAAA;QAEjD,wEAAwE;QACxE,qEAAqE;QACrE,qEAAqE;QACrE,wEAAwE;QACxE,MAAM,MAAM,GAAG,CAAC,OAAkC,EAAQ,EAAE;YAC1D,iBAAiB,EAAE,EAAE,CAAA;YACrB,OAAO,CAAC,IAAI,EAAE,CAAA;YACd,MAAM,CAAC,IAAI,EAAE,CAAA;YACb,OAAO,CAAC,OAAO,CAAC,CAAA;QAClB,CAAC,CAAA;QAED,iBAAiB,GAAG,OAAO,CAAC,SAAS,CACnC,OAAO,CAAC,IAAI,EACZ,CAAC,KAAK,EAAE,EAAE;YACR,IAAI,KAAK,CAAC,IAAI,KAAK,eAAe,IAAI,KAAK,CAAC,aAAa,IAAI,aAAa,EAAE,CAAC;gBAC3E,IAAI,OAAO,CAAC,YAAY,IAAI,KAAK,CAAC,OAAO,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,KAAK,KAAK,EAAE,CAAC;oBAC5E,MAAM,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC,CAAA;oBAC3D,OAAM;gBACR,CAAC;gBACD,MAAM,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAA;gBAClC,OAAM;YACR,CAAC;YACD,IAAI,KAAK,CAAC,IAAI,KAAK,qBAAqB,IAAI,KAAK,CAAC,MAAM,IAAI,gBAAgB,EAAE,CAAC;gBAC7E,MAAM,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,qBAAqB,EAAE,CAAC,CAAA;gBAC5D,OAAM;YACR,CAAC;YACD,IAAI,KAAK,CAAC,IAAI,KAAK,aAAa,EAAE,CAAC;gBACjC,MAAM,CAAC;oBACL,MAAM,EAAE,UAAU;oBAClB,eAAe,EAAE,KAAK,CAAC,eAAe;oBACtC,KAAK;iBACN,CAAC,CAAA;gBACF,OAAM;YACR,CAAC;QACH,CAAC,EACD;YACE,WAAW,EAAE,KAAK;YAClB,qBAAqB,EAAE,gBAAgB;YACvC,GAAG,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACxD,CACF,CAAA;IACH,CAAC,CAAC,CAAA;AACJ,CAAC,CAAA"}

package/dist/watch-transaction.d.ts

@@ -0,0 +1,57 @@
+/**
+ * `watchTransaction` — one-shot convenience over createChainSource +
+ * createTxTracker. Provex upstream item 4 (memory:
+ * upstream-candidates.md#L43). Use this when you don't need the full
+ * tracker API — just "tell me when this hash mines or drops."
+ *
+ * Internally constructs a private ChainSource and TxTracker, sets up
+ * a single-hash subscription, and tears down both source + tracker on
+ * terminal state or explicit stop.
+ */
+import type { PublicClient } from 'viem';
+import { type ChainSource } from '@valve-tech/chain-source';
+import type { Hash, TxEventSeenInBlock } from './events.js';
+export interface WatchTransactionOptions {
+    client: PublicClient;
+    hash: Hash;
+    /** Required confirmations before onMined fires. Default 1. */
+    confirmations?: number;
+    /** Blocks of "no observation" before onDropped fires. Default 12. */
+    staleAfterBlocks?: number;
+    /** Pass through to the internal ChainSource. */
+    pollIntervalMs?: number;
+    onMined?: (event: TxEventSeenInBlock) => void;
+    onDropped?: () => void;
+    onError?: (method: string, err: unknown) => void;
+}
+/**
+ * Extended options for internal use only — not part of the public API.
+ * The `_sourceOverride` seam allows tests to inject a pre-built
+ * `ChainSource` (driven by `emitBlock`/`emitMempool`) in place of the
+ * default `createChainSource(client)` path. Production callers never
+ * need this.
+ *
+ * @internal
+ */
+export interface WatchTransactionInternalOptions extends WatchTransactionOptions {
+    /** @internal — test injection seam; do not use in production code. */
+    _sourceOverride?: ChainSource;
+}
+/**
+ * Watch a single tx hash. Returns an unsubscribe function — calling
+ * it before terminal cancels the watch and tears down the internal
+ * source/tracker.
+ *
+ * @example
+ *   const stop = watchTransaction({
+ *     client,
+ *     hash: '0xabc...',
+ *     confirmations: 3,
+ *     onMined: (event) => console.log('mined at', event.blockNumber),
+ *     onDropped: () => console.log('dropped'),
+ *   })
+ *   // ... later, before terminal
+ *   stop()
+ */
+export declare const watchTransaction: (options: WatchTransactionOptions | WatchTransactionInternalOptions) => (() => void);
+//# sourceMappingURL=watch-transaction.d.ts.map

package/dist/watch-transaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"watch-transaction.d.ts","sourceRoot":"","sources":["../src/watch-transaction.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,MAAM,CAAA;AAExC,OAAO,EAEL,KAAK,WAAW,EACjB,MAAM,0BAA0B,CAAA;AAEjC,OAAO,KAAK,EACV,IAAI,EACJ,kBAAkB,EACnB,MAAM,aAAa,CAAA;AAGpB,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,YAAY,CAAA;IACpB,IAAI,EAAE,IAAI,CAAA;IACV,8DAA8D;IAC9D,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,qEAAqE;IACrE,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,gDAAgD;IAChD,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,IAAI,CAAA;IAC7C,SAAS,CAAC,EAAE,MAAM,IAAI,CAAA;IACtB,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,KAAK,IAAI,CAAA;CACjD;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,+BAAgC,SAAQ,uBAAuB;IAC9E,sEAAsE;IACtE,eAAe,CAAC,EAAE,WAAW,CAAA;CAC9B;AAED;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,gBAAgB,GAC3B,SAAS,uBAAuB,GAAG,+BAA+B,KACjE,CAAC,MAAM,IAAI,CAsDb,CAAA"}

package/dist/watch-transaction.js

@@ -0,0 +1,76 @@
+/**
+ * `watchTransaction` — one-shot convenience over createChainSource +
+ * createTxTracker. Provex upstream item 4 (memory:
+ * upstream-candidates.md#L43). Use this when you don't need the full
+ * tracker API — just "tell me when this hash mines or drops."
+ *
+ * Internally constructs a private ChainSource and TxTracker, sets up
+ * a single-hash subscription, and tears down both source + tracker on
+ * terminal state or explicit stop.
+ */
+import { createChainSource, } from '@valve-tech/chain-source';
+import { createTxTracker } from './tracker.js';
+/**
+ * Watch a single tx hash. Returns an unsubscribe function — calling
+ * it before terminal cancels the watch and tears down the internal
+ * source/tracker.
+ *
+ * @example
+ *   const stop = watchTransaction({
+ *     client,
+ *     hash: '0xabc...',
+ *     confirmations: 3,
+ *     onMined: (event) => console.log('mined at', event.blockNumber),
+ *     onDropped: () => console.log('dropped'),
+ *   })
+ *   // ... later, before terminal
+ *   stop()
+ */
+export const watchTransaction = (options) => {
+    const confirmations = options.confirmations ?? 1;
+    const staleAfterBlocks = options.staleAfterBlocks ?? 12;
+    const internal = options;
+    const source = internal._sourceOverride ?? createChainSource({
+        client: options.client,
+        pollIntervalMs: options.pollIntervalMs,
+        onError: options.onError,
+    });
+    const tracker = createTxTracker({
+        source,
+        chainId: 0, // chainId echoed in events but not load-bearing for one-shot
+        onError: options.onError,
+    });
+    source.start();
+    tracker.start();
+    let teardown = null;
+    let done = false;
+    const finish = () => {
+        if (done)
+            return;
+        done = true;
+        teardown?.();
+        teardown = null;
+        tracker.stop();
+        source.stop();
+    };
+    const unsub = tracker.subscribe(options.hash, (event) => {
+        if (done)
+            return;
+        if (event.kind === 'seen-in-block' && event.confirmations >= confirmations) {
+            options.onMined?.(event);
+            finish();
+            return;
+        }
+        if (event.kind === 'unseen-for-N-blocks' && event.blocks >= staleAfterBlocks) {
+            options.onDropped?.();
+            finish();
+            return;
+        }
+    }, {
+        emitInitial: false,
+        unseenThresholdBlocks: staleAfterBlocks,
+    });
+    teardown = unsub;
+    return () => finish();
+};
+//# sourceMappingURL=watch-transaction.js.map

package/dist/watch-transaction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"watch-transaction.js","sourceRoot":"","sources":["../src/watch-transaction.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,EACL,iBAAiB,GAElB,MAAM,0BAA0B,CAAA;AAMjC,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AA8B9C;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAC9B,OAAkE,EACpD,EAAE;IAChB,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,IAAI,CAAC,CAAA;IAChD,MAAM,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,IAAI,EAAE,CAAA;IAEvD,MAAM,QAAQ,GAAG,OAA0C,CAAA;IAC3D,MAAM,MAAM,GAAgB,QAAQ,CAAC,eAAe,IAAI,iBAAiB,CAAC;QACxE,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,cAAc,EAAE,OAAO,CAAC,cAAc;QACtC,OAAO,EAAE,OAAO,CAAC,OAAO;KACzB,CAAC,CAAA;IACF,MAAM,OAAO,GAAG,eAAe,CAAC;QAC9B,MAAM;QACN,OAAO,EAAE,CAAC,EAAE,6DAA6D;QACzE,OAAO,EAAE,OAAO,CAAC,OAAO;KACzB,CAAC,CAAA;IAEF,MAAM,CAAC,KAAK,EAAE,CAAA;IACd,OAAO,CAAC,KAAK,EAAE,CAAA;IAEf,IAAI,QAAQ,GAAwB,IAAI,CAAA;IACxC,IAAI,IAAI,GAAG,KAAK,CAAA;IAEhB,MAAM,MAAM,GAAG,GAAS,EAAE;QACxB,IAAI,IAAI;YAAE,OAAM;QAChB,IAAI,GAAG,IAAI,CAAA;QACX,QAAQ,EAAE,EAAE,CAAA;QACZ,QAAQ,GAAG,IAAI,CAAA;QACf,OAAO,CAAC,IAAI,EAAE,CAAA;QACd,MAAM,CAAC,IAAI,EAAE,CAAA;IACf,CAAC,CAAA;IAED,MAAM,KAAK,GAAG,OAAO,CAAC,SAAS,CAC7B,OAAO,CAAC,IAAI,EACZ,CAAC,KAAK,EAAE,EAAE;QACR,IAAI,IAAI;YAAE,OAAM;QAChB,IAAI,KAAK,CAAC,IAAI,KAAK,eAAe,IAAI,KAAK,CAAC,aAAa,IAAI,aAAa,EAAE,CAAC;YAC3E,OAAO,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,CAAA;YACxB,MAAM,EAAE,CAAA;YACR,OAAM;QACR,CAAC;QACD,IAAI,KAAK,CAAC,IAAI,KAAK,qBAAqB,IAAI,KAAK,CAAC,MAAM,IAAI,gBAAgB,EAAE,CAAC;YAC7E,OAAO,CAAC,SAAS,EAAE,EAAE,CAAA;YACrB,MAAM,EAAE,CAAA;YACR,OAAM;QACR,CAAC;IACH,CAAC,EACD;QACE,WAAW,EAAE,KAAK;QAClB,qBAAqB,EAAE,gBAAgB;KACxC,CACF,CAAA;IACD,QAAQ,GAAG,KAAK,CAAA;IAEhB,OAAO,GAAG,EAAE,CAAC,MAAM,EAAE,CAAA;AACvB,CAAC,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@valve-tech/tx-tracker",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Per-tx state machine for EVM chains: emits neutral observations (`seen-in-mempool`, `seen-in-block`, `replaced-by`, `vanished-from-block`, `unseen-for-N-blocks`, etc.) so wallet UIs, indexers, and relays can write their own interpretations on top. Three consumption shapes (callback, async iterator, snapshot) over one push-based core. Per-method capability detection — works on HTTP, WS, both, or neither. Part of the valve-tech/evm-toolkit synchronized release line — implementation lands in subsequent 0.3.x releases per docs/tx-tracker-spec.md.",
   "license": "MIT",
   "homepage": "https://github.com/valve-tech/evm-toolkit/tree/main/packages/tx-tracker#readme",
@@ -49,7 +49,7 @@
     "prepare": "yarn build"
   },
   "dependencies": {
-    "@valve-tech/chain-source": "^0.7.0"
+    "@valve-tech/chain-source": "^0.8.0"
   },
   "peerDependencies": {
     "viem": "^2.0.0"

package/skills/tx-tracker-integration/SKILL.md

@@ -158,6 +158,36 @@ import { createGasOracle } from '@valve-tech/gas-oracle'
 dependencies, and almost always `"@valve-tech/chain-source"` alongside
 it (the tracker requires a source).
 
+## Speed-up workflow (cross-package)
+
+For callers tracking a tx via `@valve-tech/tx-tracker` who want to bump
+it when it stalls or drops, pair with `@valve-tech/gas-oracle`'s
+`recommendBumpTier` + `bumpForReplacement` helpers:
+
+```ts
+import { recommendBumpTier, bumpForReplacement } from '@valve-tech/gas-oracle'
+
+// tx-tracker tells you the tx is stuck:
+tracker.on('stuck', (stuck) => {
+  const tier = recommendBumpTier(
+    gasOracleState,
+    { priorityTip: stuck.maxPriorityFeePerGas, identifier: { hash: stuck.hash } },
+  )
+  if (tier === null) return  // Already paying above top tier — caller's call
+
+  const target = gasOracleState.tiers[tier]
+  const gas = bumpForReplacement(
+    { maxFeePerGas: stuck.maxFeePerGas, maxPriorityFeePerGas: stuck.maxPriorityFeePerGas },
+    { maxFeePerGas: target.maxFeePerGas, maxPriorityFeePerGas: target.maxPriorityFeePerGas },
+  )
+  walletClient.sendTransaction({ ...stuck, ...gas })
+})
+```
+
+Outpace correction (passing `identifier`) reads `gasOracleState.mempoolSamples`
+to compute the tip needed to outpace the stuck tx in the live
+distribution, on top of the EIP-1559 +10% protocol floor.
+
 ## Where to find more
 
 - Full API + types: `node_modules/@valve-tech/tx-tracker/AGENTS.md`