@valve-tech/tx-tracker 0.5.0 → 0.7.0

package/dist/events.d.ts

@@ -0,0 +1,299 @@
+/**
+ * `TxEvent` — the discriminated union of every observation the
+ * tracker emits, plus payload builders that guarantee every event
+ * carries a complete envelope.
+ *
+ * Per `docs/tx-tracker-spec.md` §6, this taxonomy is the contract
+ * between the tracker and every consumer. Naming is **strictly
+ * neutral** (§2.1): `seen-in-mempool` not `pending`, `seen-in-block`
+ * not `mined`, `vanished-from-block` not `reorged`. The tracker
+ * publishes facts; the consumer writes the policy on top.
+ *
+ * Every event variant extends a common `Envelope` carrying the
+ * tracked `hash`, the `chainId`, the `source` discriminator (per
+ * §2.2 — never silently downgrade) and the `at` block coordinate
+ * the observation was made at. Builders here produce that envelope
+ * once so the state machine in `tracker.ts` cannot accidentally
+ * publish a partial event.
+ *
+ * No I/O, no wall-clock, no mutation — pure data shape + pure
+ * builders. Browser/mobile safe (§2.4).
+ */
+import type { Capabilities, EventSource, RawTx } from '@valve-tech/chain-source';
+/**
+ * Hash type carried on every event. The chain-source layer keeps
+ * hashes as plain `string` rather than viem's `Hash` brand to stay
+ * permissive at the JSON boundary; tx-tracker mirrors that posture
+ * — every consumer can `as Hash` at the seam if they need the
+ * branded form.
+ */
+export type Hash = string;
+/**
+ * EVM address. Same posture as `Hash` — plain `string` so consumers
+ * who normalize to lowercase or to checksum form don't trip a brand
+ * check at the boundary.
+ */
+export type Address = string;
+/**
+ * Block coordinate the observation was made at. `blockNumber` is the
+ * canonical-tip number when the observation landed; `timestamp` is
+ * the tip block's timestamp (seconds since epoch, same units the
+ * EVM exposes). Both `bigint` per the toolkit's wire-format rule
+ * (§2.5).
+ */
+export interface At {
+    blockNumber: bigint;
+    timestamp: bigint;
+}
+/**
+ * Common envelope on every event. The state machine builds this once
+ * per emit and merges it into the variant-specific payload below.
+ */
+export interface Envelope {
+    hash: Hash;
+    chainId: number;
+    source: EventSource;
+    at: At;
+}
+/**
+ * Per-variant payload shapes. Consumers narrow on `event.kind` to
+ * access variant-specific fields. The eslint config disallows TS
+ * namespaces, so each variant is a top-level interface and the
+ * `TxEvent` union below sums them.
+ */
+/**
+ * Synthetic first event of a subscription when `emitInitial: true`
+ * (the default). Carries the capability snapshot at subscribe time
+ * so consumers can decide their fallback posture without a separate
+ * call.
+ */
+export interface TxEventStarted extends Envelope {
+    kind: 'started';
+    capabilities: Capabilities;
+}
+/**
+ * Tracked hash was observed in the upstream's mempool snapshot or
+ * pushed via `eth_subscribe('newPendingTransactions')`. `bucket`
+ * disambiguates `txpool_content`'s pending-vs-queued split.
+ */
+export interface TxEventSeenInMempool extends Envelope {
+    kind: 'seen-in-mempool';
+    bucket: 'pending' | 'queued';
+    tx: RawTx;
+}
+/**
+ * Tracked hash is no longer in the mempool snapshot. The tx may
+ * have been mined, replaced, or evicted by the upstream node;
+ * subsequent `seen-in-block` / `replaced-by` / `unseen-for-N-blocks`
+ * disambiguates which of those happened.
+ */
+export interface TxEventLeftMempool extends Envelope {
+    kind: 'left-mempool';
+}
+/**
+ * Tracked hash was found in the canonical block at
+ * `blockNumber` / `blockHash`, at index `transactionIndex`.
+ * `confirmations` counts blocks observed since this inclusion
+ * inclusive of the inclusion block itself (so the first
+ * inclusion event has `confirmations: 1`).
+ */
+export interface TxEventSeenInBlock extends Envelope {
+    kind: 'seen-in-block';
+    blockHash: Hash;
+    blockNumber: bigint;
+    transactionIndex: number;
+    confirmations: number;
+}
+/**
+ * Tx was previously seen at block `blockNumber` with hash
+ * `previousBlockHash`, but the canonical block at the same height
+ * now has `canonicalBlockHash` and the tracked tx is not in its
+ * `transactions`. Reorg.
+ *
+ * Per spec §12.3, this event never carries
+ * `source: 'receipt-poll'` — receipt-poll cannot detect a reorg
+ * because most providers happily return a receipt for a tx in a
+ * no-longer-canonical block.
+ */
+export interface TxEventVanishedFromBlock extends Envelope {
+    kind: 'vanished-from-block';
+    previousBlockHash: Hash;
+    canonicalBlockHash: Hash;
+    blockNumber: bigint;
+}
+/**
+ * A different hash with the same `(from, nonce)` pair was either
+ * seen in the mempool or mined. `replacementBlockNumber` is `null`
+ * when the replacement was only observed in the mempool; it
+ * carries the mined block's number when the replacement reached
+ * inclusion before the original.
+ */
+export interface TxEventReplacedBy extends Envelope {
+    kind: 'replaced-by';
+    replacementHash: Hash;
+    replacementBlockNumber: bigint | null;
+}
+/**
+ * Tracked hash has not been in the mempool nor in any polled
+ * block for `blocks` consecutive observations. Threshold is
+ * configurable per subscription (`unseenThresholdBlocks`,
+ * default 30 — see `tracker.ts`). Consumer interprets as
+ * "likely dropped" / "stuck" / "rejected" in their own UX.
+ */
+export interface TxEventUnseenForNBlocks extends Envelope {
+    kind: 'unseen-for-N-blocks';
+    blocks: number;
+}
+/**
+ * A capability the tracker had been relying on for this hash is
+ * no longer authoritative — typically because the WS subscription
+ * dropped or `txpool_content` was newly gated. Tracking continues
+ * via `fallbackSource`; the consumer's interpretation of subsequent
+ * events should weigh that lower authority.
+ */
+export interface TxEventSignalDegraded extends Envelope {
+    kind: 'signal-degraded';
+    capabilityLost: keyof Capabilities;
+    fallbackSource: EventSource;
+}
+/**
+ * A previously-degraded capability is back. Fired after a
+ * matching `signal-degraded` only.
+ */
+export interface TxEventSignalRecovered extends Envelope {
+    kind: 'signal-recovered';
+    capabilityRestored: keyof Capabilities;
+}
+/**
+ * Subscription teardown — fires once per subscription. Always the
+ * final event in the stream for that subscription. `reason`
+ * disambiguates which lifecycle path closed the iterator:
+ *
+ * - `'unsubscribed'`: consumer called the returned unsubscribe
+ *   handle (or `break`'d an async iterator).
+ * - `'retention-expired'`: store's retention window elapsed past
+ *   the last terminal observation; the record was GC'd.
+ * - `'tracker-stopped'`: `tracker.stop()` was called.
+ */
+export interface TxEventStopped extends Envelope {
+    kind: 'stopped';
+    reason: 'unsubscribed' | 'retention-expired' | 'tracker-stopped';
+}
+/**
+ * Discriminated union of every event variant. Narrow on `kind` to
+ * access variant-specific fields.
+ */
+export type TxEvent = TxEventStarted | TxEventSeenInMempool | TxEventLeftMempool | TxEventSeenInBlock | TxEventVanishedFromBlock | TxEventReplacedBy | TxEventUnseenForNBlocks | TxEventSignalDegraded | TxEventSignalRecovered | TxEventStopped;
+/**
+ * `TxStatus` — cached snapshot the state machine maintains per
+ * tracked hash. `getTxStatus(hash)` returns this; the iterator and
+ * callback adapters read from the same backing store so all three
+ * consumption shapes see consistent state.
+ *
+ * Carries the **last observation** rather than a derived editorial
+ * verb. Consumers interpret the fields as policy.
+ */
+export interface TxStatus {
+    hash: Hash;
+    chainId: number;
+    /** Last observed inclusion (null if never observed in a block). */
+    lastSeenInBlock: {
+        blockHash: Hash;
+        blockNumber: bigint;
+        transactionIndex: number;
+        /** Most recent confirmations count emitted. */
+        confirmations: number;
+        source: EventSource;
+    } | null;
+    /** Last observed mempool placement (null if never observed). */
+    lastSeenInMempool: {
+        bucket: 'pending' | 'queued';
+        tx: RawTx;
+        at: At;
+        source: EventSource;
+    } | null;
+    /** Replacement hash if ever observed (null otherwise). */
+    replacedBy: {
+        hash: Hash;
+        blockNumber: bigint | null;
+    } | null;
+    /** Last vanished-from-block observation, when applicable. */
+    vanishedAt: {
+        previousBlockHash: Hash;
+        canonicalBlockHash: Hash;
+        blockNumber: bigint;
+    } | null;
+    /** Number of consecutive observed blocks the hash has been unseen. */
+    unseenStreak: number;
+    /** First observation block number — used by retention. */
+    firstObservedAtBlock: bigint | null;
+    /** Most recent observation block number — used by retention. */
+    lastObservedAtBlock: bigint | null;
+    /** Capabilities at the most recent emit. */
+    capabilities: Capabilities;
+}
+/** Build a `started` event. */
+export declare const buildStarted: (input: Envelope & {
+    capabilities: Capabilities;
+}) => TxEventStarted;
+/** Build a `seen-in-mempool` event. */
+export declare const buildSeenInMempool: (input: Envelope & {
+    bucket: "pending" | "queued";
+    tx: RawTx;
+}) => TxEventSeenInMempool;
+/** Build a `left-mempool` event. */
+export declare const buildLeftMempool: (input: Envelope) => TxEventLeftMempool;
+/** Build a `seen-in-block` event. */
+export declare const buildSeenInBlock: (input: Envelope & {
+    blockHash: Hash;
+    blockNumber: bigint;
+    transactionIndex: number;
+    confirmations: number;
+}) => TxEventSeenInBlock;
+/**
+ * Build a `vanished-from-block` event. Spec §12.3 forbids
+ * `source: 'receipt-poll'` for this kind — receipt-poll cannot
+ * detect a reorg authoritatively, so the builder rejects that
+ * combination at construction rather than letting a malformed
+ * event ship to consumers.
+ */
+export declare const buildVanishedFromBlock: (input: Envelope & {
+    previousBlockHash: Hash;
+    canonicalBlockHash: Hash;
+    blockNumber: bigint;
+}) => TxEventVanishedFromBlock;
+/** Build a `replaced-by` event. */
+export declare const buildReplacedBy: (input: Envelope & {
+    replacementHash: Hash;
+    replacementBlockNumber: bigint | null;
+}) => TxEventReplacedBy;
+/** Build an `unseen-for-N-blocks` event. */
+export declare const buildUnseenForNBlocks: (input: Envelope & {
+    blocks: number;
+}) => TxEventUnseenForNBlocks;
+/** Build a `signal-degraded` event. */
+export declare const buildSignalDegraded: (input: Envelope & {
+    capabilityLost: keyof Capabilities;
+    fallbackSource: EventSource;
+}) => TxEventSignalDegraded;
+/** Build a `signal-recovered` event. */
+export declare const buildSignalRecovered: (input: Envelope & {
+    capabilityRestored: keyof Capabilities;
+}) => TxEventSignalRecovered;
+/** Build a `stopped` event. */
+export declare const buildStopped: (input: Envelope & {
+    reason: "unsubscribed" | "retention-expired" | "tracker-stopped";
+}) => TxEventStopped;
+/**
+ * Snapshot constructor for a freshly-tracked hash. Used by the
+ * tracker to seed its in-memory record before any observation has
+ * landed. All "last observed" fields start `null`; `unseenStreak`
+ * starts `0`. Capabilities are passed in (sourced from
+ * `source.capabilities()` at construction).
+ */
+export declare const buildInitialStatus: (input: {
+    hash: Hash;
+    chainId: number;
+    capabilities: Capabilities;
+}) => TxStatus;
+//# sourceMappingURL=events.d.ts.map

package/dist/events.d.ts.map

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

package/dist/events.js

@@ -0,0 +1,131 @@
+/**
+ * `TxEvent` — the discriminated union of every observation the
+ * tracker emits, plus payload builders that guarantee every event
+ * carries a complete envelope.
+ *
+ * Per `docs/tx-tracker-spec.md` §6, this taxonomy is the contract
+ * between the tracker and every consumer. Naming is **strictly
+ * neutral** (§2.1): `seen-in-mempool` not `pending`, `seen-in-block`
+ * not `mined`, `vanished-from-block` not `reorged`. The tracker
+ * publishes facts; the consumer writes the policy on top.
+ *
+ * Every event variant extends a common `Envelope` carrying the
+ * tracked `hash`, the `chainId`, the `source` discriminator (per
+ * §2.2 — never silently downgrade) and the `at` block coordinate
+ * the observation was made at. Builders here produce that envelope
+ * once so the state machine in `tracker.ts` cannot accidentally
+ * publish a partial event.
+ *
+ * No I/O, no wall-clock, no mutation — pure data shape + pure
+ * builders. Browser/mobile safe (§2.4).
+ */
+/**
+ * Build an event envelope from the per-tracker context plus the
+ * call-site overrides. Used by every builder below so the envelope
+ * shape is centralized.
+ */
+const makeEnvelope = (input) => ({
+    hash: input.hash,
+    chainId: input.chainId,
+    source: input.source,
+    at: { blockNumber: input.at.blockNumber, timestamp: input.at.timestamp },
+});
+/** Build a `started` event. */
+export const buildStarted = (input) => ({
+    ...makeEnvelope(input),
+    kind: 'started',
+    capabilities: input.capabilities,
+});
+/** Build a `seen-in-mempool` event. */
+export const buildSeenInMempool = (input) => ({
+    ...makeEnvelope(input),
+    kind: 'seen-in-mempool',
+    bucket: input.bucket,
+    tx: input.tx,
+});
+/** Build a `left-mempool` event. */
+export const buildLeftMempool = (input) => ({
+    ...makeEnvelope(input),
+    kind: 'left-mempool',
+});
+/** Build a `seen-in-block` event. */
+export const buildSeenInBlock = (input) => ({
+    ...makeEnvelope(input),
+    kind: 'seen-in-block',
+    blockHash: input.blockHash,
+    blockNumber: input.blockNumber,
+    transactionIndex: input.transactionIndex,
+    confirmations: input.confirmations,
+});
+/**
+ * Build a `vanished-from-block` event. Spec §12.3 forbids
+ * `source: 'receipt-poll'` for this kind — receipt-poll cannot
+ * detect a reorg authoritatively, so the builder rejects that
+ * combination at construction rather than letting a malformed
+ * event ship to consumers.
+ */
+export const buildVanishedFromBlock = (input) => {
+    if (input.source === 'receipt-poll') {
+        throw new Error('buildVanishedFromBlock: receipt-poll cannot detect reorgs ' +
+            '(spec §12.3). Use block-poll or subscription source.');
+    }
+    return {
+        ...makeEnvelope(input),
+        kind: 'vanished-from-block',
+        previousBlockHash: input.previousBlockHash,
+        canonicalBlockHash: input.canonicalBlockHash,
+        blockNumber: input.blockNumber,
+    };
+};
+/** Build a `replaced-by` event. */
+export const buildReplacedBy = (input) => ({
+    ...makeEnvelope(input),
+    kind: 'replaced-by',
+    replacementHash: input.replacementHash,
+    replacementBlockNumber: input.replacementBlockNumber,
+});
+/** Build an `unseen-for-N-blocks` event. */
+export const buildUnseenForNBlocks = (input) => ({
+    ...makeEnvelope(input),
+    kind: 'unseen-for-N-blocks',
+    blocks: input.blocks,
+});
+/** Build a `signal-degraded` event. */
+export const buildSignalDegraded = (input) => ({
+    ...makeEnvelope(input),
+    kind: 'signal-degraded',
+    capabilityLost: input.capabilityLost,
+    fallbackSource: input.fallbackSource,
+});
+/** Build a `signal-recovered` event. */
+export const buildSignalRecovered = (input) => ({
+    ...makeEnvelope(input),
+    kind: 'signal-recovered',
+    capabilityRestored: input.capabilityRestored,
+});
+/** Build a `stopped` event. */
+export const buildStopped = (input) => ({
+    ...makeEnvelope(input),
+    kind: 'stopped',
+    reason: input.reason,
+});
+/**
+ * Snapshot constructor for a freshly-tracked hash. Used by the
+ * tracker to seed its in-memory record before any observation has
+ * landed. All "last observed" fields start `null`; `unseenStreak`
+ * starts `0`. Capabilities are passed in (sourced from
+ * `source.capabilities()` at construction).
+ */
+export const buildInitialStatus = (input) => ({
+    hash: input.hash,
+    chainId: input.chainId,
+    lastSeenInBlock: null,
+    lastSeenInMempool: null,
+    replacedBy: null,
+    vanishedAt: null,
+    unseenStreak: 0,
+    firstObservedAtBlock: null,
+    lastObservedAtBlock: null,
+    capabilities: input.capabilities,
+});
+//# sourceMappingURL=events.js.map

package/dist/events.js.map

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

package/dist/index.d.ts

@@ -1,16 +1,52 @@
 /**
- * @valve-tech/tx-tracker — placeholder for v0.0.1.
+ * `@valve-tech/tx-tracker` — per-tx state machine for EVM chains.
  *
- * The implementation lands in v0.1.0. This stub claims the npm name
- * and documents the planned shape so consumers reading the package
- * via `npm view` know what it is.
+ * Emits **neutral observations** (`seen-in-mempool`, `seen-in-block`,
+ * `replaced-by`, `vanished-from-block`, `unseen-for-N-blocks`,
+ * `signal-degraded`, `signal-recovered`, `stopped`) so wallet UIs,
+ * indexers, and relays can write their own interpretations on top.
+ * The tracker itself never says "confirmed" or "stuck"; it gives
+ * you the data to decide.
  *
- * Design contract: see `docs/tx-tracker-spec.md` in the
- * `valve-tech/evm-toolkit` repo, which defines the `TxTracker`,
- * `TxEvent`, `TxTrackerStore`, and bulk-subscription surfaces this
- * package will export.
+ * Three consumption shapes (callback, async iterator, snapshot)
+ * over one push-based core. Per-method capability detection keeps
+ * the "no silent downgrade" invariant — every emitted event carries
+ * a `source` discriminator (`'subscription' | 'block-poll' |
+ * 'mempool-snapshot' | 'receipt-poll'`).
  *
- * Until v0.1.0 is published, no symbols are exported.
+ * Consumes `@valve-tech/chain-source` for upstream signals; sibling
+ * to `@valve-tech/gas-oracle` (both consume the same source, neither
+ * depends on the other).
+ *
+ * @example
+ *   import { createPublicClient, http } from 'viem'
+ *   import { mainnet } from 'viem/chains'
+ *   import { createChainSource } from '@valve-tech/chain-source'
+ *   import { createTxTracker } from '@valve-tech/tx-tracker'
+ *
+ *   const client  = createPublicClient({ chain: mainnet, transport: http() })
+ *   const source  = createChainSource({ client })
+ *   const tracker = createTxTracker({ source, chainId: 1 })
+ *
+ *   source.start()
+ *   tracker.start()
+ *
+ *   for await (const event of tracker.track('0xabc...')) {
+ *     console.log(event.kind, event.source, event.at.blockNumber)
+ *     if (event.kind === 'seen-in-block' && event.confirmations >= 6) break
+ *   }
+ *
+ *   tracker.stop()
+ *   source.stop()
  */
-export {};
+export { createTxTracker } from './tracker.js';
+export type { CreateTxTrackerOptions, TxTracker, TrackOptions, BulkTrackOptions, TxMatchEvent, TxSubscription, LostSignalPolicy, } from './tracker.js';
+export { buildStarted, buildSeenInMempool, buildLeftMempool, buildSeenInBlock, buildVanishedFromBlock, buildReplacedBy, buildUnseenForNBlocks, buildSignalDegraded, buildSignalRecovered, buildStopped, buildInitialStatus, } from './events.js';
+export type { Address, At, Envelope, Hash, TxEvent, TxEventStarted, TxEventSeenInMempool, TxEventLeftMempool, TxEventSeenInBlock, TxEventVanishedFromBlock, TxEventReplacedBy, TxEventUnseenForNBlocks, TxEventSignalDegraded, TxEventSignalRecovered, TxEventStopped, TxStatus, } from './events.js';
+export { createInMemoryStore, computeRetentionExpiry, defaultRetentionBlocks, } from './store.js';
+export type { BulkSelector, HashSelector, InMemoryStoreOptions, PersistedSubscription, TrackedTxRecord, TxTrackerStore, } from './store.js';
+export { appendBlock, defaultReorgDepthBlocks, detectDivergences, } from './reorg.js';
+export type { BlockDivergence, BlockSample } from './reorg.js';
+export { compileSelector, defaultMaxBulkSubscriptions, matchAll, } from './selectors.js';
+export type { BulkMatchPayload, CompiledSelector } from './selectors.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AAC9C,YAAY,EACV,sBAAsB,EACtB,SAAS,EACT,YAAY,EACZ,gBAAgB,EAChB,YAAY,EACZ,cAAc,EACd,gBAAgB,GACjB,MAAM,cAAc,CAAA;AAErB,OAAO,EACL,YAAY,EACZ,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EAChB,sBAAsB,EACtB,eAAe,EACf,qBAAqB,EACrB,mBAAmB,EACnB,oBAAoB,EACpB,YAAY,EACZ,kBAAkB,GACnB,MAAM,aAAa,CAAA;AACpB,YAAY,EACV,OAAO,EACP,EAAE,EACF,QAAQ,EACR,IAAI,EACJ,OAAO,EACP,cAAc,EACd,oBAAoB,EACpB,kBAAkB,EAClB,kBAAkB,EAClB,wBAAwB,EACxB,iBAAiB,EACjB,uBAAuB,EACvB,qBAAqB,EACrB,sBAAsB,EACtB,cAAc,EACd,QAAQ,GACT,MAAM,aAAa,CAAA;AAEpB,OAAO,EACL,mBAAmB,EACnB,sBAAsB,EACtB,sBAAsB,GACvB,MAAM,YAAY,CAAA;AACnB,YAAY,EACV,YAAY,EACZ,YAAY,EACZ,oBAAoB,EACpB,qBAAqB,EACrB,eAAe,EACf,cAAc,GACf,MAAM,YAAY,CAAA;AAEnB,OAAO,EACL,WAAW,EACX,uBAAuB,EACvB,iBAAiB,GAClB,MAAM,YAAY,CAAA;AACnB,YAAY,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAE9D,OAAO,EACL,eAAe,EACf,2BAA2B,EAC3B,QAAQ,GACT,MAAM,gBAAgB,CAAA;AACvB,YAAY,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAA"}

package/dist/index.js

@@ -1,2 +1,47 @@
-export {};
+/**
+ * `@valve-tech/tx-tracker` — 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`,
+ * `signal-degraded`, `signal-recovered`, `stopped`) so wallet UIs,
+ * indexers, and relays can write their own interpretations on top.
+ * The tracker itself never says "confirmed" or "stuck"; it gives
+ * you the data to decide.
+ *
+ * Three consumption shapes (callback, async iterator, snapshot)
+ * over one push-based core. Per-method capability detection keeps
+ * the "no silent downgrade" invariant — every emitted event carries
+ * a `source` discriminator (`'subscription' | 'block-poll' |
+ * 'mempool-snapshot' | 'receipt-poll'`).
+ *
+ * Consumes `@valve-tech/chain-source` for upstream signals; sibling
+ * to `@valve-tech/gas-oracle` (both consume the same source, neither
+ * depends on the other).
+ *
+ * @example
+ *   import { createPublicClient, http } from 'viem'
+ *   import { mainnet } from 'viem/chains'
+ *   import { createChainSource } from '@valve-tech/chain-source'
+ *   import { createTxTracker } from '@valve-tech/tx-tracker'
+ *
+ *   const client  = createPublicClient({ chain: mainnet, transport: http() })
+ *   const source  = createChainSource({ client })
+ *   const tracker = createTxTracker({ source, chainId: 1 })
+ *
+ *   source.start()
+ *   tracker.start()
+ *
+ *   for await (const event of tracker.track('0xabc...')) {
+ *     console.log(event.kind, event.source, event.at.blockNumber)
+ *     if (event.kind === 'seen-in-block' && event.confirmations >= 6) break
+ *   }
+ *
+ *   tracker.stop()
+ *   source.stop()
+ */
+export { createTxTracker } from './tracker.js';
+export { buildStarted, buildSeenInMempool, buildLeftMempool, buildSeenInBlock, buildVanishedFromBlock, buildReplacedBy, buildUnseenForNBlocks, buildSignalDegraded, buildSignalRecovered, buildStopped, buildInitialStatus, } from './events.js';
+export { createInMemoryStore, computeRetentionExpiry, defaultRetentionBlocks, } from './store.js';
+export { appendBlock, defaultReorgDepthBlocks, detectDivergences, } from './reorg.js';
+export { compileSelector, defaultMaxBulkSubscriptions, matchAll, } from './selectors.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AAW9C,OAAO,EACL,YAAY,EACZ,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EAChB,sBAAsB,EACtB,eAAe,EACf,qBAAqB,EACrB,mBAAmB,EACnB,oBAAoB,EACpB,YAAY,EACZ,kBAAkB,GACnB,MAAM,aAAa,CAAA;AAoBpB,OAAO,EACL,mBAAmB,EACnB,sBAAsB,EACtB,sBAAsB,GACvB,MAAM,YAAY,CAAA;AAUnB,OAAO,EACL,WAAW,EACX,uBAAuB,EACvB,iBAAiB,GAClB,MAAM,YAAY,CAAA;AAGnB,OAAO,EACL,eAAe,EACf,2BAA2B,EAC3B,QAAQ,GACT,MAAM,gBAAgB,CAAA"}