@valve-tech/tx-tracker 0.6.0 → 0.7.0

package/dist/reorg.js

@@ -0,0 +1,125 @@
+/**
+ * Reorg detector — pure function over a recent-block ring.
+ *
+ * Per `docs/tx-tracker-spec.md` §12. The tracker keeps a small ring
+ * of recently-observed canonical blocks (`BlockSample` below). On
+ * every new tip, it walks the ring backward up to `reorgDepthBlocks`
+ * (default 12) and asks: "is the canonical chain at any of those
+ * heights different from what we recorded?" Any divergence becomes
+ * a `vanished-from-block` candidate the tracker translates per
+ * affected hash.
+ *
+ * Bounded depth (§12.2): a fixed 12-block window keeps the per-tick
+ * work O(depth) regardless of how anomalous the upstream's history
+ * is. Deeper reorgs are vanishingly rare on chains the package
+ * targets; "find the common ancestor" would let one bad reorg make
+ * a tick arbitrarily long.
+ *
+ * Pure: no I/O, no clock, no mutation of input. The tracker (in
+ * `tracker.ts`) calls `appendBlock` to fold each newly-observed
+ * canonical block into the ring, and `detectDivergences` against
+ * a candidate canonical sequence (typically the source's most
+ * recent emit + the on-demand block fetches the tracker did to
+ * walk the chain backward).
+ */
+/**
+ * Append a freshly-observed canonical block into a bounded ring
+ * keyed by block number, capped at `capacityBlocks` entries. Returns
+ * a new ring (input is not mutated). The newest entry overwrites
+ * any previous entry at the same number — a same-height reorg
+ * replaces the stale block with the new canonical one.
+ */
+export const appendBlock = (ring, block, capacityBlocks) => {
+    const next = ring.filter((b) => b.number !== block.number);
+    next.push(block);
+    // Sort ascending by block number. The ring is small (~depth + a
+    // few) so the cost is negligible. The same-number case is
+    // unreachable here — `filter` above strips any prior entry at
+    // `block.number` before we push, so the comparator never sees
+    // equal keys; we return -1 in that arm only to satisfy bigint
+    // sort's contract.
+    /* c8 ignore next */
+    next.sort((a, b) => (a.number < b.number ? -1 : 1));
+    if (next.length > capacityBlocks) {
+        next.splice(0, next.length - capacityBlocks);
+    }
+    return next;
+};
+/**
+ * Compare the tracker's `ring` (already-recorded canonical blocks)
+ * against a freshly-observed `canonical` sequence (the tracker's
+ * latest observation, plus any walk-back probes it performed). At
+ * each height present in BOTH sides, if the hashes disagree the
+ * detector returns a `BlockDivergence`.
+ *
+ * **Heights present only in `ring` are skipped** — the detector
+ * treats "no canonical entry at this height" as "no information,"
+ * not "vanished." A real same-height reorg requires the caller to
+ * explicitly pass the new canonical block at that height; gapping
+ * (e.g. caller skipped a height) is not a divergence signal.
+ *
+ * If you need to detect "ring's tip is no longer in canonical" you
+ * pass the canonical chain that explicitly covers that height; with
+ * a partial canonical sequence the detector stays conservative.
+ *
+ * `depthBlocks` caps how far back the comparison runs. The tracker
+ * rarely cares about divergences beyond `reorgDepthBlocks` because
+ * any tracked tx that deep would already be considered finalized by
+ * downstream consumer policy.
+ *
+ * Returns an empty array on a clean chain extension (no divergences).
+ */
+export const detectDivergences = (input) => {
+    const { ring, canonical, depthBlocks } = input;
+    if (ring.length === 0 || canonical.length === 0)
+        return [];
+    // Index the canonical sequence by number for O(1) lookup. The
+    // canonical sequence is small (≤ depthBlocks), so map construction
+    // is cheap.
+    const canonicalByNumber = new Map();
+    for (const block of canonical) {
+        canonicalByNumber.set(block.number, block);
+    }
+    // The "tip" is the highest-numbered block in either side. Compare
+    // back from there for `depthBlocks` heights (inclusive of the tip).
+    // The early `length === 0` guard above means `ring[length-1]` and
+    // `canonical[length-1]` are always defined here — the `!` reflects
+    // that invariant rather than papering over a real nullable.
+    const ringTip = ring[ring.length - 1].number;
+    const canonicalTip = canonical[canonical.length - 1].number;
+    const tip = ringTip > canonicalTip ? ringTip : canonicalTip;
+    const lowestComparedNumber = tip - BigInt(depthBlocks - 1);
+    const divergences = [];
+    for (const sampled of ring) {
+        if (sampled.number < lowestComparedNumber)
+            continue;
+        const canonicalAtHeight = canonicalByNumber.get(sampled.number) ?? null;
+        if (!canonicalAtHeight)
+            continue; // no canonical info at this height
+        if (canonicalAtHeight.hash === sampled.hash)
+            continue; // unchanged
+        divergences.push({
+            blockNumber: sampled.number,
+            previousBlockHash: sampled.hash,
+            canonicalBlockHash: canonicalAtHeight.hash,
+            vanishedTransactionHashes: sampled.transactionHashes,
+        });
+    }
+    // Sort ascending by number so the tracker emits vanished events
+    // in chain order — easier on consumers piping to a single sink.
+    // Divergences are unique by `blockNumber` (one entry per ring
+    // height), so the comparator never sees equal keys; we return -1
+    // in that arm only to satisfy the sort contract.
+    /* c8 ignore next */
+    divergences.sort((a, b) => (a.blockNumber < b.blockNumber ? -1 : 1));
+    return divergences;
+};
+/**
+ * Default reorg-detection depth in blocks. Conservative — even
+ * Ethereum's worst recent reorgs are under 7 blocks, and unbounded
+ * walks would let a single anomalous reorg make the tick arbitrarily
+ * long (§12.2). Tunable per-tracker via
+ * `CreateTxTrackerOptions.reorgDepthBlocks`.
+ */
+export const defaultReorgDepthBlocks = 12;
+//# sourceMappingURL=reorg.js.map

package/dist/reorg.js.map

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

package/dist/selectors.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Bulk-subscription matchers — pure functions over `RawTx`.
+ *
+ * Per `docs/tx-tracker-spec.md` §11. Indexers want "all txs from
+ * these senders" or "all txs touching this contract"; the tracker
+ * supports `from` / `to` / `predicate` selectors. The matchers
+ * themselves are pure (no I/O, no cached state) — `tracker.ts`
+ * iterates the source's mempool snapshots and the canonical block's
+ * `transactions` array per tick and asks each registered selector
+ * whether each tx matches.
+ *
+ * `from` and `to` selectors normalize addresses to lowercase ASCII
+ * before comparison because upstream RPCs are inconsistent about
+ * checksum vs lowercase. Mempool snapshots are already lowercased
+ * by `chain-source`'s `normalizeMempool`, but the same matcher is
+ * called against block-tx records (where the upstream may emit
+ * checksum form), so the selector normalizes its own
+ * pre-stored target once and compares lowercase-vs-lowercase.
+ *
+ * Predicate selectors are caller-defined. The tracker calls them
+ * O(N) per tick per matched-tx; spec §11.3 documents that slow
+ * predicates degrade the tick.
+ */
+import type { RawTx } from '@valve-tech/chain-source';
+import type { Hash } from './events.js';
+import type { BulkSelector } from './store.js';
+/**
+ * One match the bulk subscription is about to emit. The tracker
+ * builds the surrounding `TxMatchEvent` envelope (`source`,
+ * `at`, etc.) before pushing to the consumer; this shape is just
+ * the matcher's payload.
+ */
+export interface BulkMatchPayload {
+    hash: Hash;
+    matchedBy: 'from' | 'to' | 'predicate';
+    selector: BulkSelector;
+    tx: RawTx;
+}
+/**
+ * One compiled selector — `selector` is the original consumer-facing
+ * shape, `match` is the cached pure function the tracker calls per
+ * tx. The tracker compiles each registered selector once at
+ * registration time so the per-tick fanout pays only the function
+ * call, not a dispatch on `selector.kind`.
+ */
+export interface CompiledSelector {
+    selector: BulkSelector;
+    match: (tx: RawTx) => boolean;
+}
+/**
+ * Compile a `BulkSelector` into its pure matcher. `from` / `to`
+ * cache the lowercased address once; `predicate` returns the
+ * caller's function as-is.
+ *
+ * Throws on a malformed selector (`from` / `to` without an address,
+ * `predicate` without a function) — caught at registration time
+ * rather than at the per-tick callsite, where the failure mode would
+ * be silent zero matches.
+ */
+export declare const compileSelector: (selector: BulkSelector) => CompiledSelector;
+/**
+ * Iterate `txs` against every compiled selector and yield one
+ * `BulkMatchPayload` per (tx, selector) match. Used by the tracker's
+ * per-tick fan-out over both `block.transactions` (after a new tip
+ * lands) and the source's mempool snapshot deltas.
+ *
+ * The tracker, not this helper, decides whether to auto-track each
+ * matched hash — `BulkTrackOptions.autoTrackMatched` (default true)
+ * lives in `tracker.ts`.
+ */
+export declare const matchAll: (txs: ReadonlyArray<RawTx>, compiled: ReadonlyArray<CompiledSelector>) => BulkMatchPayload[];
+/**
+ * Default per-tracker bulk-subscription cap (§11.3). Higher fan-out
+ * is technically allowed but indicates the consumer should be
+ * running an indexer-shaped store rather than the in-memory default.
+ */
+export declare const defaultMaxBulkSubscriptions = 16;
+//# sourceMappingURL=selectors.d.ts.map

package/dist/selectors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"selectors.d.ts","sourceRoot":"","sources":["../src/selectors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,0BAA0B,CAAA;AAErD,OAAO,KAAK,EAAW,IAAI,EAAE,MAAM,aAAa,CAAA;AAChD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAE9C;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,IAAI,CAAA;IACV,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,WAAW,CAAA;IACtC,QAAQ,EAAE,YAAY,CAAA;IACtB,EAAE,EAAE,KAAK,CAAA;CACV;AAED;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,YAAY,CAAA;IACtB,KAAK,EAAE,CAAC,EAAE,EAAE,KAAK,KAAK,OAAO,CAAA;CAC9B;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,GAAI,UAAU,YAAY,KAAG,gBAwCxD,CAAA;AAeD;;;;;;;;;GASG;AACH,eAAO,MAAM,QAAQ,GACnB,KAAK,aAAa,CAAC,KAAK,CAAC,EACzB,UAAU,aAAa,CAAC,gBAAgB,CAAC,KACxC,gBAAgB,EAelB,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,KAAK,CAAA"}

package/dist/selectors.js

@@ -0,0 +1,119 @@
+/**
+ * Bulk-subscription matchers — pure functions over `RawTx`.
+ *
+ * Per `docs/tx-tracker-spec.md` §11. Indexers want "all txs from
+ * these senders" or "all txs touching this contract"; the tracker
+ * supports `from` / `to` / `predicate` selectors. The matchers
+ * themselves are pure (no I/O, no cached state) — `tracker.ts`
+ * iterates the source's mempool snapshots and the canonical block's
+ * `transactions` array per tick and asks each registered selector
+ * whether each tx matches.
+ *
+ * `from` and `to` selectors normalize addresses to lowercase ASCII
+ * before comparison because upstream RPCs are inconsistent about
+ * checksum vs lowercase. Mempool snapshots are already lowercased
+ * by `chain-source`'s `normalizeMempool`, but the same matcher is
+ * called against block-tx records (where the upstream may emit
+ * checksum form), so the selector normalizes its own
+ * pre-stored target once and compares lowercase-vs-lowercase.
+ *
+ * Predicate selectors are caller-defined. The tracker calls them
+ * O(N) per tick per matched-tx; spec §11.3 documents that slow
+ * predicates degrade the tick.
+ */
+/**
+ * Compile a `BulkSelector` into its pure matcher. `from` / `to`
+ * cache the lowercased address once; `predicate` returns the
+ * caller's function as-is.
+ *
+ * Throws on a malformed selector (`from` / `to` without an address,
+ * `predicate` without a function) — caught at registration time
+ * rather than at the per-tick callsite, where the failure mode would
+ * be silent zero matches.
+ */
+export const compileSelector = (selector) => {
+    switch (selector.kind) {
+        case 'from': {
+            if (!selector.address) {
+                throw new Error('compileSelector: "from" selector requires an address');
+            }
+            const target = selector.address.toLowerCase();
+            return {
+                selector,
+                match: (tx) => (tx.from ? tx.from.toLowerCase() === target : false),
+            };
+        }
+        case 'to': {
+            if (!selector.address) {
+                throw new Error('compileSelector: "to" selector requires an address');
+            }
+            const target = selector.address.toLowerCase();
+            return {
+                selector,
+                match: (tx) => 
+                // RawTx in chain-source's wire shape doesn't carry `to`
+                // explicitly (it's loose for portability across
+                // mempool/block payloads); the matcher reads the field
+                // off the structurally-typed object so block-side txs
+                // (which DO carry `to`) match correctly. Mempool snapshots
+                // also carry `to`; both are read off the same field name
+                // upstream clients use.
+                extractTo(tx) ? extractTo(tx)?.toLowerCase() === target : false,
+            };
+        }
+        case 'predicate': {
+            if (typeof selector.match !== 'function') {
+                throw new Error('compileSelector: "predicate" selector requires a match function');
+            }
+            const fn = selector.match;
+            return { selector, match: (tx) => fn(tx) };
+        }
+    }
+};
+/**
+ * Read `tx.to` off a RawTx without losing type-safety. The
+ * `chain-source` `RawTx` is intentionally loose (no `to` field) —
+ * mempool / block payloads carry `to` even though it's not in the
+ * narrow type, and `to`-selectors must compare against it. Safe
+ * cast through `Record<string, unknown>` keeps lint clean and
+ * avoids `any`.
+ */
+const extractTo = (tx) => {
+    const value = tx.to;
+    return typeof value === 'string' ? value : undefined;
+};
+/**
+ * Iterate `txs` against every compiled selector and yield one
+ * `BulkMatchPayload` per (tx, selector) match. Used by the tracker's
+ * per-tick fan-out over both `block.transactions` (after a new tip
+ * lands) and the source's mempool snapshot deltas.
+ *
+ * The tracker, not this helper, decides whether to auto-track each
+ * matched hash — `BulkTrackOptions.autoTrackMatched` (default true)
+ * lives in `tracker.ts`.
+ */
+export const matchAll = (txs, compiled) => {
+    const matches = [];
+    for (const tx of txs) {
+        if (!tx.hash)
+            continue; // can't bulk-track an unhashed tx
+        for (const cs of compiled) {
+            if (!cs.match(tx))
+                continue;
+            matches.push({
+                hash: tx.hash,
+                matchedBy: cs.selector.kind,
+                selector: cs.selector,
+                tx,
+            });
+        }
+    }
+    return matches;
+};
+/**
+ * Default per-tracker bulk-subscription cap (§11.3). Higher fan-out
+ * is technically allowed but indicates the consumer should be
+ * running an indexer-shaped store rather than the in-memory default.
+ */
+export const defaultMaxBulkSubscriptions = 16;
+//# sourceMappingURL=selectors.js.map

package/dist/selectors.js.map

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

package/dist/store.d.ts

@@ -0,0 +1,166 @@
+/**
+ * `TxTrackerStore` — persistence surface for the tracker, plus the
+ * default `createInMemoryStore` implementation.
+ *
+ * Per `docs/tx-tracker-spec.md` §9 + §10. Indexers and relays cannot
+ * lose tracked hashes across a process restart; wallets are fine
+ * in-memory. The store interface lets either case plug in.
+ *
+ * Two responsibilities:
+ *
+ *   - **Record store** — `put` / `get` / `delete` / `listDurable`
+ *     for `TrackedTxRecord` (one per `(chainId, hash)`).
+ *   - **Per-hash audit log** — `appendEvent` / `readEventLog?` over
+ *     `TxEvent[]`. Default implementation is a bounded ring keyed
+ *     by `(chainId, hash)`.
+ *
+ * The interface is **async-shaped** so durable stores (Redis, SQLite,
+ * JSON-on-disk) can implement it directly. The in-memory default
+ * resolves synchronously under the hood — `Promise.resolve` wrappers
+ * are cheap.
+ *
+ * **Wire format** (§9.1, §2.5): `TrackedTxRecord` carries `bigint`
+ * fields (`firstSeenBlockNumber`, `lastObservedBlockNumber`,
+ * `retentionExpiresAtBlockNumber`) and `TxStatus` carries `bigint`
+ * inside its nested `at` / `lastSeenIn*` shapes. The in-memory store
+ * keeps them as `bigint` end-to-end. Durable store implementers MUST
+ * hex-encode (`'0x' + n.toString(16)`) on write and decode on read;
+ * the package never calls `JSON.stringify` on a record itself.
+ */
+import type { TxEvent, TxStatus, Hash, Address } from './events.js';
+/**
+ * One persisted record per tracked `(chainId, hash)`. `subscriptions`
+ * carries every persisted (durable) subscription that referenced this
+ * hash so `listDurable` can rehydrate them after restart.
+ */
+export interface TrackedTxRecord {
+    chainId: number;
+    hash: Hash;
+    /** Cached current status, kept in sync with every emit. */
+    status: TxStatus;
+    /** Block number of the very first observation. */
+    firstSeenBlockNumber: bigint;
+    /** Block number of the most recent observation (any kind). */
+    lastObservedBlockNumber: bigint;
+    /**
+     * Block number after which the record is GC-eligible. Set when the
+     * record reaches a terminal observation (`seen-in-block` reaching
+     * the consumer's confirmation threshold, `unseen-for-N-blocks`,
+     * `replaced-by`, etc.) plus `retentionBlocks`.
+     */
+    retentionExpiresAtBlockNumber: bigint;
+    /** Persisted subscriptions referencing this hash. */
+    subscriptions: PersistedSubscription[];
+}
+/**
+ * Per-hash and per-bulk subscription metadata. Predicate selectors
+ * are non-serializable (closures cannot survive a process boundary)
+ * — the tracker silently demotes them to non-durable and surfaces a
+ * warning at registration. Per spec §13.2 only `'from'` / `'to'`
+ * bulk selectors and per-hash selectors persist meaningfully.
+ */
+export interface PersistedSubscription {
+    /** Stable identifier. The tracker assigns this on registration. */
+    id: string;
+    /** Whether the consumer asked for durable persistence. */
+    durable: boolean;
+    selector: HashSelector | BulkSelector;
+}
+/**
+ * Per-hash selector — one tracked hash, ergonomic for wallet UIs.
+ */
+export interface HashSelector {
+    kind: 'hash';
+    hash: Hash;
+}
+/**
+ * Bulk selector — `'from' | 'to' | 'predicate'`. `predicate`
+ * carries a non-serializable function reference; durable persistence
+ * records `kind: 'predicate'` without the function and the tracker
+ * cannot rehydrate it on restart.
+ */
+export interface BulkSelector {
+    kind: 'from' | 'to' | 'predicate';
+    /** For 'from' / 'to'. */
+    address?: Address;
+    /** For 'predicate'. Function references do not persist meaningfully. */
+    match?: (tx: import('@valve-tech/chain-source').RawTx) => boolean;
+}
+/**
+ * Persistence surface. Indexers and relays cannot lose tracked hashes
+ * across restart; wallets are fine in-memory. `readEventLog` is
+ * optional — durable stores that don't keep a log can omit it.
+ */
+export interface TxTrackerStore {
+    /**
+     * Persist (or update) a tracked-tx record. Idempotent on
+     * `(chainId, hash)`.
+     */
+    put(record: TrackedTxRecord): Promise<void>;
+    /** Read the latest record for a hash. Returns null if absent. */
+    get(chainId: number, hash: Hash): Promise<TrackedTxRecord | null>;
+    /** Remove a hash. Called when the retention window expires. */
+    delete(chainId: number, hash: Hash): Promise<void>;
+    /**
+     * List records that carry at least one durable subscription. Called
+     * once at `tracker.start()` so durable per-hash subscriptions can
+     * be re-registered against the source after a restart.
+     */
+    listDurable(chainId: number): Promise<TrackedTxRecord[]>;
+    /**
+     * Append an event to the per-hash audit log. Indexers replay this
+     * log on restart; wallets can wrap a no-op store implementation.
+     * Failures here are routed through the tracker's `onError` and
+     * never block live emit (per spec Appendix A).
+     */
+    appendEvent(chainId: number, hash: Hash, event: TxEvent): Promise<void>;
+    /**
+     * Read the per-hash audit log, optionally constrained to events
+     * with `at.blockNumber >= since`. Optional — implementations
+     * without a log return `undefined` on the type and get pruned
+     * from the catch-up code path.
+     */
+    readEventLog?(chainId: number, hash: Hash, since?: bigint): Promise<TxEvent[]>;
+}
+/**
+ * Tunable knobs for the default in-memory store.
+ *
+ * - `retentionBlocks` (default 64): how many blocks past the last
+ *   terminal observation a record stays in the store. After this
+ *   window passes, the record is GC'd. Block-units, not seconds —
+ *   reorg safety is a block-depth invariant, not a time invariant
+ *   (spec §10.1).
+ *
+ * - `eventLogCapacity` (default 256): bounded ring buffer cap on
+ *   the per-hash audit log. Older events are dropped when the cap
+ *   is exceeded; the latest status is always retained.
+ */
+export interface InMemoryStoreOptions {
+    retentionBlocks?: number;
+    eventLogCapacity?: number;
+}
+/**
+ * Default in-memory store. Synchronous internals wrapped in
+ * `Promise.resolve`; safe for any consumer that doesn't need
+ * cross-process durability.
+ *
+ * @example
+ *   import { createInMemoryStore } from '@valve-tech/tx-tracker'
+ *
+ *   const store = createInMemoryStore({ retentionBlocks: 32 })
+ *   const tracker = createTxTracker({ source, chainId: 1, store })
+ */
+export declare const createInMemoryStore: (options?: InMemoryStoreOptions) => TxTrackerStore;
+/**
+ * Compute the retention-expiry block for a terminal observation.
+ * Pure helper exposed so the tracker (which decides when to call
+ * `store.put` with an updated `retentionExpiresAtBlockNumber`) and
+ * the store implementations stay in sync on the calculation.
+ */
+export declare const computeRetentionExpiry: (terminalBlockNumber: bigint, retentionBlocks?: number) => bigint;
+/**
+ * Default retention window in blocks — exposed so the tracker can
+ * use the same default if no store-level override is present.
+ */
+export declare const defaultRetentionBlocks = 64;
+//# sourceMappingURL=store.d.ts.map

package/dist/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,aAAa,CAAA;AAEnE;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,IAAI,CAAA;IACV,2DAA2D;IAC3D,MAAM,EAAE,QAAQ,CAAA;IAChB,kDAAkD;IAClD,oBAAoB,EAAE,MAAM,CAAA;IAC5B,8DAA8D;IAC9D,uBAAuB,EAAE,MAAM,CAAA;IAC/B;;;;;OAKG;IACH,6BAA6B,EAAE,MAAM,CAAA;IACrC,qDAAqD;IACrD,aAAa,EAAE,qBAAqB,EAAE,CAAA;CACvC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,qBAAqB;IACpC,mEAAmE;IACnE,EAAE,EAAE,MAAM,CAAA;IACV,0DAA0D;IAC1D,OAAO,EAAE,OAAO,CAAA;IAChB,QAAQ,EAAE,YAAY,GAAG,YAAY,CAAA;CACtC;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,IAAI,CAAA;CACX;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,WAAW,CAAA;IACjC,yBAAyB;IACzB,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,wEAAwE;IACxE,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,OAAO,0BAA0B,EAAE,KAAK,KAAK,OAAO,CAAA;CAClE;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,GAAG,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAE3C,iEAAiE;IACjE,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAAA;IAEjE,+DAA+D;IAC/D,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAElD;;;;OAIG;IACH,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAAA;IAExD;;;;;OAKG;IACH,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAEvE;;;;;OAKG;IACH,YAAY,CAAC,CACX,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,IAAI,EACV,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,OAAO,EAAE,CAAC,CAAA;CACtB;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,oBAAoB;IACnC,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAC1B;AAcD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,mBAAmB,GAC9B,UAAS,oBAAyB,KACjC,cAsDF,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,GACjC,qBAAqB,MAAM,EAC3B,kBAAiB,MAAiC,KACjD,MAAuD,CAAA;AAE1D;;;GAGG;AACH,eAAO,MAAM,sBAAsB,KAA2B,CAAA"}

package/dist/store.js

@@ -0,0 +1,110 @@
+/**
+ * `TxTrackerStore` — persistence surface for the tracker, plus the
+ * default `createInMemoryStore` implementation.
+ *
+ * Per `docs/tx-tracker-spec.md` §9 + §10. Indexers and relays cannot
+ * lose tracked hashes across a process restart; wallets are fine
+ * in-memory. The store interface lets either case plug in.
+ *
+ * Two responsibilities:
+ *
+ *   - **Record store** — `put` / `get` / `delete` / `listDurable`
+ *     for `TrackedTxRecord` (one per `(chainId, hash)`).
+ *   - **Per-hash audit log** — `appendEvent` / `readEventLog?` over
+ *     `TxEvent[]`. Default implementation is a bounded ring keyed
+ *     by `(chainId, hash)`.
+ *
+ * The interface is **async-shaped** so durable stores (Redis, SQLite,
+ * JSON-on-disk) can implement it directly. The in-memory default
+ * resolves synchronously under the hood — `Promise.resolve` wrappers
+ * are cheap.
+ *
+ * **Wire format** (§9.1, §2.5): `TrackedTxRecord` carries `bigint`
+ * fields (`firstSeenBlockNumber`, `lastObservedBlockNumber`,
+ * `retentionExpiresAtBlockNumber`) and `TxStatus` carries `bigint`
+ * inside its nested `at` / `lastSeenIn*` shapes. The in-memory store
+ * keeps them as `bigint` end-to-end. Durable store implementers MUST
+ * hex-encode (`'0x' + n.toString(16)`) on write and decode on read;
+ * the package never calls `JSON.stringify` on a record itself.
+ */
+const DEFAULT_RETENTION_BLOCKS = 64;
+const DEFAULT_EVENT_LOG_CAPACITY = 256;
+/**
+ * Composite key for the in-memory map. Keying by `(chainId, hash)`
+ * lets a single store back multi-chain trackers if a future caller
+ * wants that — today the tracker is single-chain, but the store
+ * type is already chain-aware so no migration is needed later.
+ */
+const recordKey = (chainId, hash) => `${chainId}:${hash}`;
+/**
+ * Default in-memory store. Synchronous internals wrapped in
+ * `Promise.resolve`; safe for any consumer that doesn't need
+ * cross-process durability.
+ *
+ * @example
+ *   import { createInMemoryStore } from '@valve-tech/tx-tracker'
+ *
+ *   const store = createInMemoryStore({ retentionBlocks: 32 })
+ *   const tracker = createTxTracker({ source, chainId: 1, store })
+ */
+export const createInMemoryStore = (options = {}) => {
+    const eventLogCapacity = options.eventLogCapacity ?? DEFAULT_EVENT_LOG_CAPACITY;
+    const records = new Map();
+    const eventLogs = new Map();
+    return {
+        put: (record) => {
+            records.set(recordKey(record.chainId, record.hash), record);
+            return Promise.resolve();
+        },
+        get: (chainId, hash) => Promise.resolve(records.get(recordKey(chainId, hash)) ?? null),
+        delete: (chainId, hash) => {
+            const key = recordKey(chainId, hash);
+            records.delete(key);
+            eventLogs.delete(key);
+            return Promise.resolve();
+        },
+        listDurable: (chainId) => {
+            const result = [];
+            for (const record of records.values()) {
+                if (record.chainId !== chainId)
+                    continue;
+                if (record.subscriptions.some((sub) => sub.durable)) {
+                    result.push(record);
+                }
+            }
+            return Promise.resolve(result);
+        },
+        appendEvent: (chainId, hash, event) => {
+            const key = recordKey(chainId, hash);
+            const log = eventLogs.get(key) ?? [];
+            log.push(event);
+            // Drop oldest when capacity exceeded. Latest entries are the
+            // ones consumers care about for catch-up; keeping a strict
+            // ring rather than unbounded growth caps memory.
+            if (log.length > eventLogCapacity) {
+                log.splice(0, log.length - eventLogCapacity);
+            }
+            eventLogs.set(key, log);
+            return Promise.resolve();
+        },
+        readEventLog: (chainId, hash, since) => {
+            const log = eventLogs.get(recordKey(chainId, hash)) ?? [];
+            if (since === undefined)
+                return Promise.resolve([...log]);
+            return Promise.resolve(log.filter((e) => e.at.blockNumber >= since));
+        },
+    };
+};
+/**
+ * Compute the retention-expiry block for a terminal observation.
+ * Pure helper exposed so the tracker (which decides when to call
+ * `store.put` with an updated `retentionExpiresAtBlockNumber`) and
+ * the store implementations stay in sync on the calculation.
+ */
+export const computeRetentionExpiry = (terminalBlockNumber, retentionBlocks = DEFAULT_RETENTION_BLOCKS) => terminalBlockNumber + BigInt(retentionBlocks);
+/**
+ * Default retention window in blocks — exposed so the tracker can
+ * use the same default if no store-level override is present.
+ */
+export const defaultRetentionBlocks = DEFAULT_RETENTION_BLOCKS;
+//# sourceMappingURL=store.js.map

package/dist/store.js.map

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