@valve-tech/tx-tracker 0.6.0 → 0.8.0

package/dist/group.js

@@ -0,0 +1,196 @@
+/**
+ * `createTxGroup` — synthesis layer on top of per-hash tracker
+ * subscriptions. Spec §18.1, v0.8.0 design F3.
+ *
+ * Listens to each member hash via the tracker's existing subscribe API,
+ * tracks confirmed/failed counters, and emits group-progress /
+ * group-complete / group-failed once per terminal transition. Member
+ * unsubscribes are torn down on stop().
+ *
+ * Replacement does NOT auto-promote — if a member is replaced via
+ * same-nonce bump, the group emits group-failed with reason
+ * 'replaced'. The consumer constructs a new group with the new hash
+ * if they want the replacement to count.
+ *
+ * Edge case: an empty hashes array immediately emits group-complete
+ * with total=0 (vacuously all confirmed) and marks the group terminal.
+ * This is a safe, predictable default and matches the mathematical
+ * sense of "all zero members confirmed."
+ */
+import { Subscriptions } from '@valve-tech/chain-source';
+import { buildGroupComplete, buildGroupFailed, buildGroupProgress, buildGroupStopped, } from './group-events.js';
+/**
+ * Construct a group subscription that synthesises per-member `TxEvent`
+ * streams into group-level events.
+ *
+ * @param tracker - The tracker instance to call `subscribe` on.
+ * @param hashes  - Member transaction hashes. Order is not significant.
+ * @param options - Optional group-level and member-level overrides.
+ */
+export const createTxGroup = (tracker, hashes, options = {}) => {
+    const groupId = options.groupId ??
+        `grp-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    const memberOptions = options.memberOptions ?? {};
+    const subs = new Subscriptions();
+    const total = hashes.length;
+    const confirmedSet = new Set();
+    let terminal = false;
+    const memberUnsubs = [];
+    const emit = (event) => subs.emit(event);
+    // Empty group — vacuously all confirmed. Emit complete immediately
+    // (synchronously; no member subscriptions to set up).
+    if (total === 0) {
+        terminal = true;
+        const zeroAt = { blockNumber: 0n, timestamp: 0n };
+        emit(buildGroupComplete({ groupId, at: zeroAt, total: 0 }));
+    }
+    const handleMemberEvent = (memberHash, event) => {
+        if (terminal)
+            return;
+        const at = event.at;
+        if (event.kind === 'seen-in-block' && event.confirmations >= 1) {
+            // Idempotency guard: same hash can emit multiple seen-in-block
+            // events (confirmations 1, 2, 3 …) — only count it once.
+            if (confirmedSet.has(memberHash))
+                return;
+            confirmedSet.add(memberHash);
+            if (confirmedSet.size < total) {
+                emit(buildGroupProgress({
+                    groupId,
+                    at,
+                    confirmed: confirmedSet.size,
+                    total,
+                    lastHash: memberHash,
+                }));
+            }
+            else {
+                terminal = true;
+                emit(buildGroupComplete({ groupId, at, total }));
+            }
+            return;
+        }
+        if (event.kind === 'unseen-for-N-blocks') {
+            terminal = true;
+            emit(buildGroupFailed({
+                groupId,
+                at,
+                failedHash: memberHash,
+                reason: 'dropped',
+            }));
+            return;
+        }
+        if (event.kind === 'replaced-by') {
+            terminal = true;
+            emit(buildGroupFailed({
+                groupId,
+                at,
+                failedHash: memberHash,
+                reason: 'replaced',
+            }));
+            return;
+        }
+    };
+    for (const hash of hashes) {
+        const unsub = tracker.subscribe(hash, (event) => handleMemberEvent(hash, event), { ...memberOptions, emitInitial: false });
+        memberUnsubs.push(unsub);
+    }
+    let stopped = false;
+    const stop = () => {
+        if (stopped)
+            return;
+        stopped = true;
+        for (const unsub of memberUnsubs) {
+            try {
+                unsub();
+            }
+            catch {
+                // Swallow per-sub teardown errors — we always emit group-stopped.
+            }
+        }
+        emit(buildGroupStopped({ groupId, at: { blockNumber: 0n, timestamp: 0n } }));
+    };
+    const snapshot = () => {
+        const out = {};
+        for (const hash of hashes)
+            out[hash] = tracker.getTxStatus(hash);
+        return out;
+    };
+    /**
+     * Async-iterable surface over the group event stream. Resolves each
+     * `next()` call with the next queued event, or parks the caller in a
+     * waiter array until one arrives. Terminal events (group-complete /
+     * group-failed / group-stopped) flip `done` so subsequent `next()`
+     * calls resolve immediately with `done: true`.
+     */
+    const events = () => ({
+        [Symbol.asyncIterator]: () => {
+            const queue = [];
+            const waiters = [];
+            let done = false;
+            const unsub = subs.subscribe((event) => {
+                if (event.kind === 'group-stopped' ||
+                    event.kind === 'group-complete' ||
+                    event.kind === 'group-failed') {
+                    done = true;
+                }
+                const waiter = waiters.shift();
+                if (waiter) {
+                    waiter({ value: event, done: false });
+                    if (done) {
+                        // Drain remaining waiters with done after a terminal event.
+                        // Reachable when a consumer parks multiple `next()` calls
+                        // concurrently before any event arrives — first waiter gets
+                        // the terminal event, the rest resolve with done:true here.
+                        while (waiters.length > 0) {
+                            waiters.shift()({
+                                value: undefined,
+                                done: true,
+                            });
+                        }
+                    }
+                }
+                else {
+                    queue.push(event);
+                }
+            });
+            return {
+                next: () => {
+                    if (queue.length > 0) {
+                        const value = queue.shift();
+                        return Promise.resolve({ value, done: false });
+                    }
+                    if (done) {
+                        return Promise.resolve({
+                            value: undefined,
+                            done: true,
+                        });
+                    }
+                    return new Promise((resolve) => {
+                        waiters.push(resolve);
+                    });
+                },
+                return: () => {
+                    unsub();
+                    done = true;
+                    while (waiters.length > 0) {
+                        waiters.shift()({
+                            value: undefined,
+                            done: true,
+                        });
+                    }
+                    return Promise.resolve({
+                        value: undefined,
+                        done: true,
+                    });
+                },
+            };
+        },
+    });
+    return {
+        events,
+        subscribe: (cb) => subs.subscribe(cb),
+        snapshot,
+        stop,
+    };
+};
+//# sourceMappingURL=group.js.map

package/dist/group.js.map

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

package/dist/index.d.ts

@@ -1,16 +1,63 @@
 /**
- * @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, GroupOptions, TxGroupSubscription, } 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';
+export { createTxGroup } from './group.js';
+export { watchTransaction } from './watch-transaction.js';
+export type { WatchTransactionOptions } from './watch-transaction.js';
+export { waitForTransaction } from './wait-for-transaction.js';
+export type { WaitForTransactionOptions, WaitForTransactionOutcome, } from './wait-for-transaction.js';
+export { waitForPending, WaitForPendingTimeoutError, } from './wait-for-pending.js';
+export type { WaitForPendingOptions } from './wait-for-pending.js';
+export { buildGroupComplete, buildGroupFailed, buildGroupProgress, buildGroupStopped, } from './group-events.js';
+export type { TxGroupEvent, TxGroupEventComplete, TxGroupEventEnvelope, TxGroupEventFailed, TxGroupEventProgress, TxGroupEventStopped, } from './group-events.js';
+export { replaceTransaction } from './replace-transaction.js';
+export type { ReplaceTransactionNewGas, ReplaceTransactionOptions, ReplaceTransactionOriginal, } from './replace-transaction.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,EAChB,YAAY,EACZ,mBAAmB,GACpB,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;AAExE,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAE1C,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AACzD,YAAY,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAA;AAErE,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAA;AAC9D,YAAY,EACV,yBAAyB,EACzB,yBAAyB,GAC1B,MAAM,2BAA2B,CAAA;AAElC,OAAO,EACL,cAAc,EACd,0BAA0B,GAC3B,MAAM,uBAAuB,CAAA;AAC9B,YAAY,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAA;AAElE,OAAO,EACL,kBAAkB,EAClB,gBAAgB,EAChB,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,mBAAmB,CAAA;AAC1B,YAAY,EACV,YAAY,EACZ,oBAAoB,EACpB,oBAAoB,EACpB,kBAAkB,EAClB,oBAAoB,EACpB,mBAAmB,GACpB,MAAM,mBAAmB,CAAA;AAE1B,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAA;AAC7D,YAAY,EACV,wBAAwB,EACxB,yBAAyB,EACzB,0BAA0B,GAC3B,MAAM,0BAA0B,CAAA"}

package/dist/index.js

@@ -1,2 +1,53 @@
-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';
+export { createTxGroup } from './group.js';
+export { watchTransaction } from './watch-transaction.js';
+export { waitForTransaction } from './wait-for-transaction.js';
+export { waitForPending, WaitForPendingTimeoutError, } from './wait-for-pending.js';
+export { buildGroupComplete, buildGroupFailed, buildGroupProgress, buildGroupStopped, } from './group-events.js';
+export { replaceTransaction } from './replace-transaction.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;AAa9C,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;AAGvB,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAE1C,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AAGzD,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAA;AAM9D,OAAO,EACL,cAAc,EACd,0BAA0B,GAC3B,MAAM,uBAAuB,CAAA;AAG9B,OAAO,EACL,kBAAkB,EAClB,gBAAgB,EAChB,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,mBAAmB,CAAA;AAU1B,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAA"}

package/dist/observations.d.ts

@@ -0,0 +1,169 @@
+/**
+ * Per-record decision functions — the **pure** logic that turns one
+ * upstream observation (a block or a mempool snapshot) plus one
+ * tracked record's current state into the events that should be
+ * emitted and the state patch the orchestrator should apply.
+ *
+ * These functions are extracted from `tracker.ts`'s `onBlock` /
+ * `onMempool` so each branch of the per-record state machine is
+ * testable with literal fixture inputs — no stub source, no async
+ * orchestration, no shared mutable closure. This is the same
+ * primitive-vs-orchestrator split that `oracle.ts` (`reducePollInputs`
+ * pure / poll loop stateful) and `chain-source` (math pure / source
+ * stateful) already follow.
+ *
+ * Inputs are immutable; outputs are immutable. The caller in
+ * `tracker.ts` applies the returned `statusPatch` and `identityPatch`
+ * to its mutable `TrackedRecord`, then emits the returned `events`
+ * via its event-bus + store-audit-log machinery.
+ */
+import type { EventSource, RawTx, TransactionReceipt } from '@valve-tech/chain-source';
+import { type At, type Hash, type TxEvent, type TxStatus } from './events.js';
+/**
+ * Read-only projection of `TrackedRecord` that the decision functions
+ * consume. The orchestrator passes its mutable record through this
+ * shape so the pure layer cannot accidentally mutate state.
+ */
+export interface ReadonlyTrackedRecord {
+    hash: Hash;
+    status: TxStatus;
+    identity: {
+        from: string;
+        nonce: string;
+    } | null;
+    inLastMempoolSnapshot: boolean;
+    unseenThresholdBlocks: number;
+}
+/**
+ * Cached `(from, nonce)` identity of the tracked tx. Used for
+ * replacement detection.
+ */
+export interface IdentityPatch {
+    from: string;
+    nonce: string;
+}
+/**
+ * Result of a decision function: events to emit and patches to apply
+ * to the tracked record. The patch shapes are deliberately narrow —
+ * only the fields the function decided to change. The orchestrator
+ * merges them into its mutable record.
+ */
+export interface ObservationResult {
+    events: TxEvent[];
+    statusPatch: Partial<TxStatus>;
+    identityPatch: IdentityPatch | null;
+    /** Set when the per-mempool-tick "in-snapshot?" flag should change. */
+    inMempoolPatch: boolean | null;
+}
+/**
+ * Inputs to `decideBlockObservation`. The orchestrator builds a
+ * `txHashSet` once per block and passes it for O(1) "did this hash
+ * appear?" lookups across every tracked record.
+ */
+export interface BlockObservationInput {
+    record: ReadonlyTrackedRecord;
+    blockHash: Hash;
+    blockNumber: bigint;
+    txHashSet: ReadonlySet<Hash>;
+    txs: ReadonlyArray<RawTx>;
+    chainId: number;
+    eventSource: EventSource;
+    envelope: At;
+    /**
+     * The previous canonical tip's block number, or `null` if this is
+     * the first block the tracker has seen. Used to gate the
+     * "confirmation bump" path — we don't bump confirmations on the
+     * very first block we observe.
+     */
+    previousTipNumber: bigint | null;
+    /**
+     * Pre-fetched receipts for hashes whose `withReceipts` flag is set.
+     * When a hash appears in this map, the receipt is attached to the
+     * `seen-in-block` event. Omitted or empty means no enrichment. This
+     * is the sole path for F2 eager receipt attachment (spec §18.2) —
+     * the orchestrator fetches and populates this map before calling
+     * `decideBlockObservation`, so the first emitted event carries the
+     * receipt without a follow-up re-emit.
+     */
+    prefetchedReceipts?: ReadonlyMap<Hash, TransactionReceipt>;
+}
+/**
+ * Per-record decision for one new canonical block. Returns the events
+ * to emit and the state patch to apply. Mutually-exclusive paths,
+ * evaluated in order:
+ *
+ *   1. Hash is in this block → fresh inclusion (emit `seen-in-block`
+ *      with `confirmations: 1`) OR same-block re-observation (no
+ *      emit; `lastSeenInBlock` is already current).
+ *   2. Hash NOT in this block but was previously included → bump
+ *      `confirmations` on the cached observation, emit a fresh
+ *      `seen-in-block` carrying the new count.
+ *   3. Hash NOT in this block, no prior inclusion, but identity is
+ *      cached AND a different hash with the same `(from, nonce)` is
+ *      in this block → emit `replaced-by` with the replacement's
+ *      block number.
+ *   4. Truly unseen → bump the unseen-block streak; emit
+ *      `unseen-for-N-blocks` when the streak crosses the
+ *      subscription's threshold. Does NOT emit on the first block
+ *      after subscription (no `firstObservedAtBlock` yet).
+ */
+export declare const decideBlockObservation: (input: BlockObservationInput) => ObservationResult;
+/**
+ * Inputs to `decideMempoolObservation`. The orchestrator builds the
+ * hash-keyed snapshot index once per mempool tick.
+ */
+export interface MempoolObservationInput {
+    record: ReadonlyTrackedRecord;
+    presence: {
+        bucket: 'pending' | 'queued';
+        tx: RawTx;
+    } | null;
+    /**
+     * The replacement candidate found in the snapshot for this record's
+     * `(from, nonce)` identity, or `null` if none. Computed by the
+     * orchestrator once per record so this function stays pure on
+     * inputs (no closure over the snapshot).
+     */
+    replacementInMempool: RawTx | null;
+    chainId: number;
+    eventSource: EventSource;
+    envelope: At;
+    /**
+     * The current canonical-tip block number the orchestrator is using
+     * for `firstObservedAtBlock` / `lastObservedAtBlock` book-keeping.
+     * Falls back to `0n` when no tip has been observed yet.
+     */
+    tipBlockNumber: bigint;
+}
+/**
+ * Per-record decision for one mempool snapshot. Three independent
+ * outputs that may all fire on the same call:
+ *
+ *   - **Presence transition** — emit `seen-in-mempool` on first
+ *     observation or bucket change; emit `left-mempool` when a
+ *     previously-seen hash is absent from this snapshot.
+ *   - **Replacement** — emit `replaced-by` (with `null` block) when
+ *     the orchestrator's pre-computed `replacementInMempool` is set
+ *     AND the record hasn't already recorded a replacement.
+ */
+export declare const decideMempoolObservation: (input: MempoolObservationInput) => ObservationResult;
+/**
+ * Find a tx in `txs` whose `(from, nonce)` matches `identity` but
+ * whose hash differs from `originalHash` — the replacement candidate
+ * for the original tracked tx. Compares senders case-insensitively
+ * since upstreams disagree on checksum form.
+ */
+export declare const findReplacementInBlock: (identity: {
+    from: string;
+    nonce: string;
+}, originalHash: Hash, txs: ReadonlyArray<RawTx>) => RawTx | null;
+/**
+ * Cache the tx's `(from, nonce)` as the record's identity if it's
+ * not already cached AND the tx carries both fields. Returns the
+ * patch to apply (or `null` when no change).
+ */
+export declare const cacheIdentity: (current: {
+    from: string;
+    nonce: string;
+} | null, tx: RawTx) => IdentityPatch | null;
+//# sourceMappingURL=observations.d.ts.map

package/dist/observations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observations.d.ts","sourceRoot":"","sources":["../src/observations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAA;AAEtF,OAAO,EAML,KAAK,EAAE,EACP,KAAK,IAAI,EACT,KAAK,OAAO,EACZ,KAAK,QAAQ,EACd,MAAM,aAAa,CAAA;AAEpB;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,IAAI,CAAA;IACV,MAAM,EAAE,QAAQ,CAAA;IAChB,QAAQ,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAA;IAChD,qBAAqB,EAAE,OAAO,CAAA;IAC9B,qBAAqB,EAAE,MAAM,CAAA;CAC9B;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;CACd;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,OAAO,EAAE,CAAA;IACjB,WAAW,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAA;IAC9B,aAAa,EAAE,aAAa,GAAG,IAAI,CAAA;IACnC,uEAAuE;IACvE,cAAc,EAAE,OAAO,GAAG,IAAI,CAAA;CAC/B;AAaD;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,qBAAqB,CAAA;IAC7B,SAAS,EAAE,IAAI,CAAA;IACf,WAAW,EAAE,MAAM,CAAA;IACnB,SAAS,EAAE,WAAW,CAAC,IAAI,CAAC,CAAA;IAC5B,GAAG,EAAE,aAAa,CAAC,KAAK,CAAC,CAAA;IACzB,OAAO,EAAE,MAAM,CAAA;IACf,WAAW,EAAE,WAAW,CAAA;IACxB,QAAQ,EAAE,EAAE,CAAA;IACZ;;;;;OAKG;IACH,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAA;IAChC;;;;;;;;OAQG;IACH,kBAAkB,CAAC,EAAE,WAAW,CAAC,IAAI,EAAE,kBAAkB,CAAC,CAAA;CAC3D;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,sBAAsB,GACjC,OAAO,qBAAqB,KAC3B,iBAkJF,CAAA;AAMD;;;GAGG;AACH,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,qBAAqB,CAAA;IAC7B,QAAQ,EAAE;QAAE,MAAM,EAAE,SAAS,GAAG,QAAQ,CAAC;QAAC,EAAE,EAAE,KAAK,CAAA;KAAE,GAAG,IAAI,CAAA;IAC5D;;;;;OAKG;IACH,oBAAoB,EAAE,KAAK,GAAG,IAAI,CAAA;IAClC,OAAO,EAAE,MAAM,CAAA;IACf,WAAW,EAAE,WAAW,CAAA;IACxB,QAAQ,EAAE,EAAE,CAAA;IACZ;;;;OAIG;IACH,cAAc,EAAE,MAAM,CAAA;CACvB;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,wBAAwB,GACnC,OAAO,uBAAuB,KAC7B,iBAqFF,CAAA;AAMD;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,GACjC,UAAU;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,EACzC,cAAc,IAAI,EAClB,KAAK,aAAa,CAAC,KAAK,CAAC,KACxB,KAAK,GAAG,IAUV,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,aAAa,GACxB,SAAS;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,EAC/C,IAAI,KAAK,KACR,aAAa,GAAG,IAIlB,CAAA"}