@valve-tech/tx-tracker 0.7.0 → 0.9.2

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: options.chainId ?? options.client.chain?.id ?? 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;AAuC9C,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,OAAO,CAAC,OAAO,IAAI,OAAO,CAAC,MAAM,CAAC,KAAK,EAAE,EAAE,IAAI,CAAC;YACzD,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,63 @@
+/**
+ * `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;
+    /**
+     * Tag emitted events with this chainId. Falls back to
+     * `client.chain?.id`, then `0`. Consumers piping events from multiple
+     * watchers into one stream should set this for unambiguous routing.
+     */
+    chainId?: 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;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,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: options.chainId ?? options.client.chain?.id ?? 0,
+        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;AAoC9C;;;;;;;;;;;;;;;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,OAAO,CAAC,OAAO,IAAI,OAAO,CAAC,MAAM,CAAC,KAAK,EAAE,EAAE,IAAI,CAAC;QACzD,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.9.2",
   "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.9.2"
   },
   "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`