@valve-tech/tx-tracker 0.13.0 → 0.15.0

package/CHANGELOG.md

@@ -6,6 +6,173 @@ this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/).
 
+## [0.15.0] — 2026-05-14
+
+### Added
+
+- **`CreateTxTrackerOptions.confirmationsForTerminal: number | null`**
+  (default `null`). When set to a positive integer, a record
+  transitions to terminal (`terminalAtBlockNumber` set to the current
+  block) the first block its `lastSeenInBlock.confirmations` reaches
+  the threshold. Closes the long-standing gap where a normally-mined
+  tx never went terminal — retention enforcement only fired on
+  replacement and unseen-for-N-blocks paths, so successful txs
+  accumulated in long-lived stores forever. Records with 5,000+
+  confirmations were observed in production localStorage dumps; the
+  new option lets consumers opt in to retire them via the normal
+  retention pipeline. Recommended value: `≥ reorgDepthBlocks` (default
+  12) so a same-height reorg can't briefly unmine a "terminal" tx.
+  Validation: must be a positive integer or null/undefined; zero,
+  negative, and non-integer values throw at construction.
+- **`TxEventConfirmedTerminal` event kind** — `{ kind: 'confirmed-terminal',
+  confirmations }` fires once when the threshold is reached. Consumer-
+  facing signal that the record is now safe to forget. Carries the
+  triggering confirmations count for downstream gating.
+- **`TrackOptions.subscriptionId?: string`** — caller-provided stable
+  identifier for the persisted subscription (only meaningful when
+  `durable: true`). Repeated calls with the same id are idempotent.
+  Without an explicit id, the tracker auto-dedups by `(durable,
+  selector)`: a second subscribe on the same hash with `durable: true`
+  reuses the prior persisted entry rather than appending. Closes the
+  bug where React component remounts and page reloads accumulated
+  structurally-identical persisted entries across reloads, each
+  driving the same downstream fan-out N times.
+- **`createLocalStorageTrackerStore({ keyPrefix, storage?, eventLogCapacity?,
+  cleanupLegacyPrefixes? })`** — first-party TxTrackerStore implementation
+  backed by `localStorage` (or any `Storage`-shaped object). Records
+  stored under `{keyPrefix}:{chainId}:{hash}`; eventlogs under
+  `{keyPrefix}:eventlog:{chainId}:{hash}`. Bigint fields round-trip
+  losslessly via a sentinel-tagged JSON replacer/reviver.
+  **`delete()` clears BOTH the record AND the eventlog** — the
+  canonical bug class consumer-side localStorage stores routinely got
+  wrong, leaving orphaned eventlogs that never expired.
+  `cleanupLegacyPrefixes` deletes prior-prefix keys on construction for
+  prefix-bump migrations. Defensive against `setItem` failures (quota
+  exceeded, browser disabled storage) — surfaces as a rejected promise
+  so the tracker's `onError` can route it cleanly.
+- **`deleteKeysStartingWith(storage, prefix)`** — standalone helper for
+  prefix cleanup without instantiating the full store.
+- **Self-healing rehydration dedup.** On `tracker.start()`,
+  `dedupPersistedSubscriptions` runs on the rehydrated record's
+  subscription list; when the count shrinks (legacy duplicates
+  collapsed), the cleaned record is immediately written back via
+  `store.put`. Defensive against legacy flat-shape entries (pre-current
+  `selector` nesting) — those pass through untouched rather than
+  crashing the dedup helper.
+
+### Changed
+
+- **`runReceiptPollFallback` skips silently when `caps.ready === false`**.
+  Pre-v0.15, the conservative pre-probe `receiptByHash: 'unavailable'`
+  default tripped the "permanently unavailable" warning gate, firing
+  once per tracker instance even when the RPC ultimately supported the
+  method. The warning now waits for probe completion (`caps.ready === true`)
+  before deciding; pre-probe ticks no-op.
+- **`TxTrackerStore.delete` docstring tightened** to make explicit that
+  implementations must clear ALL state associated with the hash — the
+  record, the eventlog, any other per-hash keys. The first-party
+  `createInMemoryStore` and `createLocalStorageTrackerStore` already
+  enforce this; consumer implementations must do the same to avoid the
+  orphan-eventlog leak class.
+
+### Notes
+
+- The `confirmationsForTerminal` transition fires from both Path 1
+  (fresh inclusion at confirmations=1, relevant only when threshold=1)
+  and Path 2 (confirmation bump from prior block) in
+  `decideBlockObservation`. Terminal is anchored on the current block
+  (matching the existing terminal arms which all anchor on
+  detection-block, not origin-block) — retention math is consistent
+  across all four arms.
+- The status-poll path's mined emit (added in v0.14) hardcodes
+  `confirmations: 1` and doesn't participate in the new transition.
+  This is correct: status-poll mined observations are one-shot per
+  inclusion-block; confirmation accrual happens via block-poll's
+  Path 2, which is where the threshold is checked.
+- 40 new tests across `tracker.test.ts`, `local-storage-store.test.ts`,
+  and `events.test.ts`. 334 total tx-tracker tests (was 294). Coverage
+  remains 100/100/100/100.
+
+## [0.14.0] — 2026-05-14
+
+### Added
+
+- **`CreateTxTrackerOptions.statusPollEveryBlocks`** — default `1`
+  (every block tick). Controls cadence for a new default-on per-hash
+  status poll via `source.getTransaction(hash)`
+  (`eth_getTransactionByHash`). Set `0` to disable. `2`/`3`/etc. for
+  less-frequent cadences on consumers tracking many hashes.
+  Returns are treated as authoritative for the tx's current state:
+  pending (no `blockHash`) emits `seen-in-mempool`; mined (with
+  `blockHash`) emits `seen-in-block`. Both flow through the existing
+  event pipeline with `source: 'receipt-poll'` (see chain-source
+  v0.14.0 EventSource doc widening). The path is NOT permitted to
+  drive reorg / vanished-from-block events (spec §12.3) — divergence
+  detection stays anchored on the source's block stream.
+- **`TrackOptions.probeTransaction`** — per-subscription consumer
+  fallback called only when `source.getTransaction` returns null.
+  Use to consult a different RPC, multi-RPC fan-out, an indexer with
+  mempool support, or a commercial mempool service. First-set wins
+  across subscribes (mirrors `lostSignalPolicy` / `probeMined`).
+- `ProbeTransaction` type exported from the package root. Function
+  shape `(hash: Hash) => Promise<RawTx | null>`. RawTx is the existing
+  chain-source primitive — consumers don't need to construct a
+  custom shape; whatever they get back from
+  `eth_getTransactionByHash` drops in directly.
+
+### Notes
+
+- Motivation: `txpool_content` is gated on many public RPC gateways
+  (PulseChain et al), and even when available it only reflects the
+  polled node's local mempool — partial-visibility failures look
+  identical to "the tx was dropped" from the tracker's perspective.
+  `eth_getTransactionByHash` is universally exposed and queries the
+  node's indexed-tx store, so it sees txs the node has seen
+  referenced even if they're not currently in the local pool. Per-hash
+  polling is also dramatically lighter than full `txpool_content`
+  snapshots — one tx record vs the entire pending pool. Both
+  properties make per-hash status the right primitive for "is this
+  tx alive?" on consumer-grade RPCs.
+- **Load-bearing side effect: identity priming.** The status-poll
+  caches `(from, nonce)` on the first pending observation. This
+  unblocks replacement detection for txs that were never visible in
+  any local mempool snapshot — `replaced-by` previously couldn't
+  fire because the original's identity was never cached. Critical
+  for chains where partial mempool visibility is the norm.
+- The status-poll path is idempotent within a streak: one
+  `seen-in-mempool` emit per pending streak (tracked via internal
+  `statusPollLastEmittedKind` flag). On a pending→mined transition
+  the dedup flag resets, so a later pending streak (rare — e.g.
+  post-replacement) would re-emit cleanly.
+- Cross-path duplicate handling: if `txpool_content` snapshots ARE
+  available AND status-poll is also running, both paths can emit
+  `seen-in-mempool` for the same observation. Both are truthful;
+  consumers wanting unique delivery dedupe on `(kind, hash)` at the
+  edge.
+- Errors on `source.getTransaction` route through `onError` but the
+  dispatch falls through to `probeTransaction` if one is attached —
+  a transiently-failing source doesn't block the consumer's fallback.
+  Probe errors route through `onError` and short-circuit.
+- Cost characterization: with default `statusPollEveryBlocks: 1` and
+  a consumer tracking N hashes, the additional RPC load is N calls
+  per block tick. Consumers tracking >100 hashes may want
+  `statusPollEveryBlocks: 2` or higher; consumers on rate-limited
+  RPCs may want `0` (opt out entirely).
+- Closures aren't serialized — durable records rehydrated from the
+  store start with `probeTransaction: null` until a fresh subscribe
+  re-binds one. Same precedent as `probeMined` and predicate
+  selectors (spec §13.2).
+- 18 new `tracker.test.ts` cases pin the path's contract: happy
+  emit (mined + pending), null no-op, source-throw falls through to
+  probe, probe-throw routes via onError, probe-throw-no-onError
+  swallowed, pending idempotency, pending→mined transition resets
+  dedup, height-ordering block-poll-wins, identity-check rejects
+  orphaned mid-await emits, bad blockNumber routes via onError,
+  probeTransaction first-set-wins, `statusPollEveryBlocks: 0`
+  disables, `statusPollEveryBlocks: 3` skips ticks, defensive
+  identity caching when tx lacks from/nonce, identity priming
+  unblocks `replaced-by` for previously-invisible originals.
+
 ## [0.13.0] — 2026-05-12
 
 ### Added

package/dist/events.d.ts

@@ -153,6 +153,23 @@ export interface TxEventUnseenForNBlocks extends Envelope {
     kind: 'unseen-for-N-blocks';
     blocks: number;
 }
+/**
+ * Mined-and-confirmed terminal — fires when an included tx's
+ * `confirmations` reaches the `confirmationsForTerminal` threshold
+ * configured on the tracker. Marks the record as terminal for
+ * retention purposes (the existing terminal anchors are
+ * replacement and unseen-for-N-blocks; v0.15 closes the gap where a
+ * normally-mined tx never goes terminal and leaks records in
+ * long-lived stores). Carries the confirmations count that triggered
+ * the transition so consumers can gate downstream UI cleanup off the
+ * same event. Fires exactly once per record — the
+ * `terminalAtBlockNumber == null` gate on the decision arm dedups
+ * subsequent confirmation bumps.
+ */
+export interface TxEventConfirmedTerminal extends Envelope {
+    kind: 'confirmed-terminal';
+    confirmations: number;
+}
 /**
  * A capability the tracker had been relying on for this hash is
  * no longer authoritative — typically because the WS subscription
@@ -192,7 +209,7 @@ export interface TxEventStopped extends Envelope {
  * 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;
+export type TxEvent = TxEventStarted | TxEventSeenInMempool | TxEventLeftMempool | TxEventSeenInBlock | TxEventVanishedFromBlock | TxEventReplacedBy | TxEventUnseenForNBlocks | TxEventConfirmedTerminal | TxEventSignalDegraded | TxEventSignalRecovered | TxEventStopped;
 /**
  * `TxStatus` — cached snapshot the state machine maintains per
  * tracked hash. `getTxStatus(hash)` returns this; the iterator and
@@ -292,6 +309,10 @@ export declare const buildReplacedBy: (input: Envelope & {
 export declare const buildUnseenForNBlocks: (input: Envelope & {
     blocks: number;
 }) => TxEventUnseenForNBlocks;
+/** Build a `confirmed-terminal` event. */
+export declare const buildConfirmedTerminal: (input: Envelope & {
+    confirmations: number;
+}) => TxEventConfirmedTerminal;
 /** Build a `signal-degraded` event. */
 export declare const buildSignalDegraded: (input: Envelope & {
     capabilityLost: keyof Capabilities;

package/dist/events.d.ts.map

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

package/dist/events.js

@@ -91,6 +91,12 @@ export const buildUnseenForNBlocks = (input) => ({
     kind: 'unseen-for-N-blocks',
     blocks: input.blocks,
 });
+/** Build a `confirmed-terminal` event. */
+export const buildConfirmedTerminal = (input) => ({
+    ...makeEnvelope(input),
+    kind: 'confirmed-terminal',
+    confirmations: input.confirmations,
+});
 /** Build a `signal-degraded` event. */
 export const buildSignalDegraded = (input) => ({
     ...makeEnvelope(input),

package/dist/events.js.map

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

package/dist/index.d.ts

@@ -40,9 +40,11 @@
  *   source.stop()
  */
 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 type { CreateTxTrackerOptions, TxTracker, TrackOptions, BulkTrackOptions, TxMatchEvent, TxSubscription, LostSignalPolicy, ProbeMined, ProbeMinedResult, ProbeTransaction, GroupOptions, TxGroupSubscription, } from './tracker.js';
+export { createLocalStorageTrackerStore, deleteKeysStartingWith, } from './local-storage-store.js';
+export type { LocalStorageLike, LocalStorageTrackerStoreOptions, } from './local-storage-store.js';
+export { buildStarted, buildSeenInMempool, buildLeftMempool, buildSeenInBlock, buildVanishedFromBlock, buildReplacedBy, buildUnseenForNBlocks, buildConfirmedTerminal, buildSignalDegraded, buildSignalRecovered, buildStopped, buildInitialStatus, } from './events.js';
+export type { Address, At, Envelope, Hash, TxEvent, TxEventStarted, TxEventSeenInMempool, TxEventLeftMempool, TxEventSeenInBlock, TxEventVanishedFromBlock, TxEventReplacedBy, TxEventUnseenForNBlocks, TxEventConfirmedTerminal, 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';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"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"}
+{"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,UAAU,EACV,gBAAgB,EAChB,gBAAgB,EAChB,YAAY,EACZ,mBAAmB,GACpB,MAAM,cAAc,CAAA;AAErB,OAAO,EACL,8BAA8B,EAC9B,sBAAsB,GACvB,MAAM,0BAA0B,CAAA;AACjC,YAAY,EACV,gBAAgB,EAChB,+BAA+B,GAChC,MAAM,0BAA0B,CAAA;AAEjC,OAAO,EACL,YAAY,EACZ,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EAChB,sBAAsB,EACtB,eAAe,EACf,qBAAqB,EACrB,sBAAsB,EACtB,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,wBAAwB,EACxB,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

@@ -40,7 +40,8 @@
  *   source.stop()
  */
 export { createTxTracker } from './tracker.js';
-export { buildStarted, buildSeenInMempool, buildLeftMempool, buildSeenInBlock, buildVanishedFromBlock, buildReplacedBy, buildUnseenForNBlocks, buildSignalDegraded, buildSignalRecovered, buildStopped, buildInitialStatus, } from './events.js';
+export { createLocalStorageTrackerStore, deleteKeysStartingWith, } from './local-storage-store.js';
+export { buildStarted, buildSeenInMempool, buildLeftMempool, buildSeenInBlock, buildVanishedFromBlock, buildReplacedBy, buildUnseenForNBlocks, buildConfirmedTerminal, 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';

package/dist/index.js.map

@@ -1 +1 @@
-{"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AAgB9C,OAAO,EACL,8BAA8B,EAC9B,sBAAsB,GACvB,MAAM,0BAA0B,CAAA;AAMjC,OAAO,EACL,YAAY,EACZ,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EAChB,sBAAsB,EACtB,eAAe,EACf,qBAAqB,EACrB,sBAAsB,EACtB,mBAAmB,EACnB,oBAAoB,EACpB,YAAY,EACZ,kBAAkB,GACnB,MAAM,aAAa,CAAA;AAqBpB,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/local-storage-store.d.ts

@@ -0,0 +1,98 @@
+/**
+ * `createLocalStorageTrackerStore` — first-party `TxTrackerStore`
+ * implementation backed by `localStorage` (or any `Storage`-shaped
+ * object). Targeted at browser dApps that need durable per-hash
+ * subscriptions surviving page reloads but don't want to maintain
+ * their own custom store.
+ *
+ * Key layout (under the consumer-supplied `keyPrefix`):
+ *
+ *   {keyPrefix}:{chainId}:{hash}            → the TrackedTxRecord JSON
+ *   {keyPrefix}:eventlog:{chainId}:{hash}   → the per-hash event log JSON
+ *
+ * The eventlog is a separate key from the record so put/get can avoid
+ * paying read-and-rewrite for the (potentially-large) log on every
+ * status update.
+ *
+ * **`delete()` clears BOTH keys.** This is the contract the
+ * `TxTrackerStore.delete` docstring requires; we lock it in here so
+ * consumers don't accumulate orphan eventlogs when records expire
+ * (the canonical bug that motivated this first-party store —
+ * consumer-implemented localStorage stores routinely forgot to clear
+ * the eventlog key).
+ *
+ * Browser-safety: `localStorage` is browser-only. The factory accepts
+ * a `storage` override (defaults to `globalThis.localStorage`) so
+ * (a) tests can inject a fake and (b) consumers running in
+ * server-rendered contexts can supply a no-op implementation rather
+ * than throwing at construction.
+ */
+import type { PersistedSubscription, TxTrackerStore } from './store.js';
+/**
+ * Storage-shaped interface — the subset of the DOM `Storage` API the
+ * store needs. `localStorage` and `sessionStorage` both satisfy this;
+ * consumers can supply any object with the same shape (in-memory fake,
+ * server-rendered no-op, IndexedDB-backed polyfill, etc.).
+ */
+export interface LocalStorageLike {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+    readonly length: number;
+    key(index: number): string | null;
+}
+export interface LocalStorageTrackerStoreOptions {
+    /**
+     * Namespace prefix for all keys this store writes. Required. Use
+     * a versioned prefix (e.g. `'myapp.tx-tracker.v1'`) and bump the
+     * version suffix when the persisted shape changes — the prior-
+     * prefix keys can then be cleaned up via `cleanupLegacyPrefixes`.
+     */
+    keyPrefix: string;
+    /**
+     * Storage backend. Defaults to `globalThis.localStorage` when
+     * available; throws at construction otherwise (server-rendered or
+     * Node contexts must supply an explicit `storage` parameter, even
+     * if it's a no-op).
+     */
+    storage?: LocalStorageLike;
+    /**
+     * Cap on the per-hash event log. When `appendEvent` would push the
+     * log past this length, the oldest entries are dropped. Default 256
+     * (matches `InMemoryStoreOptions.eventLogCapacity`).
+     */
+    eventLogCapacity?: number;
+    /**
+     * On construction, delete every key in `storage` that starts with
+     * any of these prefixes followed by `:`. Use to clean up records
+     * orphaned by a prior `keyPrefix` bump. Pass the OLD prefix (or
+     * prefixes), not the current one — passing the current one would
+     * wipe live state.
+     */
+    cleanupLegacyPrefixes?: string[];
+}
+/**
+ * Build a localStorage-backed `TxTrackerStore`. See module docstring
+ * for the key layout and serialization details.
+ *
+ * @example
+ *   import {
+ *     createTxTracker,
+ *     createLocalStorageTrackerStore,
+ *   } from '@valve-tech/tx-tracker'
+ *
+ *   const store = createLocalStorageTrackerStore({
+ *     keyPrefix: 'myapp.tx-tracker.v1',
+ *     cleanupLegacyPrefixes: ['myapp.tx-tracker.v0'],
+ *   })
+ *   const tracker = createTxTracker({ source, chainId: 1, store })
+ */
+export declare const createLocalStorageTrackerStore: (options: LocalStorageTrackerStoreOptions) => TxTrackerStore;
+/**
+ * Delete every key in `storage` whose name starts with `prefix`.
+ * Exported so consumers can run prefix cleanup without instantiating
+ * the full store — e.g., on app boot before constructing the tracker.
+ */
+export declare const deleteKeysStartingWith: (storage: LocalStorageLike, prefix: string) => void;
+export type { PersistedSubscription };
+//# sourceMappingURL=local-storage-store.d.ts.map

package/dist/local-storage-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-storage-store.d.ts","sourceRoot":"","sources":["../src/local-storage-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAGH,OAAO,KAAK,EACV,qBAAqB,EAErB,cAAc,EACf,MAAM,YAAY,CAAA;AAEnB;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAA;IACnC,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACzC,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAA;CAClC;AAED,MAAM,WAAW,+BAA+B;IAC9C;;;;;OAKG;IACH,SAAS,EAAE,MAAM,CAAA;IAEjB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,gBAAgB,CAAA;IAE1B;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAA;IAEzB;;;;;;OAMG;IACH,qBAAqB,CAAC,EAAE,MAAM,EAAE,CAAA;CACjC;AAwDD;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,8BAA8B,GACzC,SAAS,+BAA+B,KACvC,cA2GF,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,GACjC,SAAS,gBAAgB,EACzB,QAAQ,MAAM,KACb,IASF,CAAA;AAMD,YAAY,EAAE,qBAAqB,EAAE,CAAA"}

package/dist/local-storage-store.js

@@ -0,0 +1,208 @@
+/**
+ * `createLocalStorageTrackerStore` — first-party `TxTrackerStore`
+ * implementation backed by `localStorage` (or any `Storage`-shaped
+ * object). Targeted at browser dApps that need durable per-hash
+ * subscriptions surviving page reloads but don't want to maintain
+ * their own custom store.
+ *
+ * Key layout (under the consumer-supplied `keyPrefix`):
+ *
+ *   {keyPrefix}:{chainId}:{hash}            → the TrackedTxRecord JSON
+ *   {keyPrefix}:eventlog:{chainId}:{hash}   → the per-hash event log JSON
+ *
+ * The eventlog is a separate key from the record so put/get can avoid
+ * paying read-and-rewrite for the (potentially-large) log on every
+ * status update.
+ *
+ * **`delete()` clears BOTH keys.** This is the contract the
+ * `TxTrackerStore.delete` docstring requires; we lock it in here so
+ * consumers don't accumulate orphan eventlogs when records expire
+ * (the canonical bug that motivated this first-party store —
+ * consumer-implemented localStorage stores routinely forgot to clear
+ * the eventlog key).
+ *
+ * Browser-safety: `localStorage` is browser-only. The factory accepts
+ * a `storage` override (defaults to `globalThis.localStorage`) so
+ * (a) tests can inject a fake and (b) consumers running in
+ * server-rendered contexts can supply a no-op implementation rather
+ * than throwing at construction.
+ */
+const DEFAULT_EVENT_LOG_CAPACITY = 256;
+const recordKey = (prefix, chainId, hash) => `${prefix}:${chainId}:${hash}`;
+const eventLogKey = (prefix, chainId, hash) => `${prefix}:eventlog:${chainId}:${hash}`;
+/**
+ * JSON replacer that round-trips `bigint` losslessly. The toolkit's
+ * persisted shapes carry block numbers and other on-chain quantities
+ * as bigint; native `JSON.stringify` throws on them. We tag with a
+ * sentinel discriminator so the reviver can rehydrate to bigint
+ * without ambiguity against arbitrary user strings.
+ */
+const SENTINEL = '$tx-tracker:bigint';
+const bigintReplacer = (_key, value) => {
+    if (typeof value === 'bigint') {
+        return { [SENTINEL]: value.toString() };
+    }
+    return value;
+};
+const bigintReviver = (_key, value) => {
+    if (value !== null &&
+        typeof value === 'object' &&
+        SENTINEL in value &&
+        typeof value[SENTINEL] === 'string') {
+        try {
+            return BigInt(value[SENTINEL]);
+        }
+        catch {
+            // Malformed sentinel — fall back to the raw object; downstream
+            // type guards (typeof === 'bigint') will treat as missing.
+            return value;
+        }
+    }
+    return value;
+};
+const stringifyRecord = (value) => JSON.stringify(value, bigintReplacer);
+const parseRecord = (raw) => {
+    if (raw === null)
+        return null;
+    try {
+        return JSON.parse(raw, bigintReviver);
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * Build a localStorage-backed `TxTrackerStore`. See module docstring
+ * for the key layout and serialization details.
+ *
+ * @example
+ *   import {
+ *     createTxTracker,
+ *     createLocalStorageTrackerStore,
+ *   } from '@valve-tech/tx-tracker'
+ *
+ *   const store = createLocalStorageTrackerStore({
+ *     keyPrefix: 'myapp.tx-tracker.v1',
+ *     cleanupLegacyPrefixes: ['myapp.tx-tracker.v0'],
+ *   })
+ *   const tracker = createTxTracker({ source, chainId: 1, store })
+ */
+export const createLocalStorageTrackerStore = (options) => {
+    const storage = options.storage ??
+        (typeof globalThis !== 'undefined' &&
+            'localStorage' in globalThis &&
+            globalThis.localStorage
+            ? globalThis.localStorage
+            : null);
+    if (!storage) {
+        throw new Error('createLocalStorageTrackerStore: no `storage` supplied and globalThis.localStorage is unavailable. Pass `storage: ...` explicitly when running in a non-browser environment.');
+    }
+    if (!options.keyPrefix) {
+        throw new Error('createLocalStorageTrackerStore: keyPrefix is required');
+    }
+    const keyPrefix = options.keyPrefix;
+    const eventLogCapacity = options.eventLogCapacity ?? DEFAULT_EVENT_LOG_CAPACITY;
+    // Cleanup pass on construction. Skip the current prefix even if a
+    // consumer accidentally lists it — wiping live state mid-session
+    // would be the most-surprising-thing possible.
+    for (const legacy of options.cleanupLegacyPrefixes ?? []) {
+        if (!legacy || legacy === keyPrefix)
+            continue;
+        deleteKeysStartingWith(storage, `${legacy}:`);
+    }
+    return {
+        put: async (record) => {
+            storage.setItem(recordKey(keyPrefix, record.chainId, record.hash), stringifyRecord(record));
+        },
+        get: async (chainId, hash) => {
+            const raw = storage.getItem(recordKey(keyPrefix, chainId, hash));
+            return parseRecord(raw);
+        },
+        delete: async (chainId, hash) => {
+            // Critically: clear BOTH the record AND the eventlog. The bug
+            // class this fixes is the consumer-side localStorage store that
+            // remembered only the record key on delete, leaving the eventlog
+            // as a permanent orphan.
+            storage.removeItem(recordKey(keyPrefix, chainId, hash));
+            storage.removeItem(eventLogKey(keyPrefix, chainId, hash));
+        },
+        listDurable: async (chainId) => {
+            const prefix = `${keyPrefix}:${chainId}:`;
+            const result = [];
+            // Snapshot the keys first — mutations during iteration would
+            // shift the `key(i)` indexing. Browser localStorage is
+            // synchronous, but defensive against any Storage-shaped object
+            // that mutates during the iteration.
+            //
+            // Filter: record keys are `{keyPrefix}:{chainId}:{hash}`, eventlog
+            // keys are `{keyPrefix}:eventlog:{chainId}:{hash}`. With a numeric
+            // chainId the two prefixes don't overlap (`p:1:` vs `p:eventlog:`),
+            // so a single `startsWith(prefix)` check is enough — eventlog keys
+            // can never match the record prefix.
+            const keys = [];
+            for (let i = 0; i < storage.length; i++) {
+                const k = storage.key(i);
+                if (k === null)
+                    continue;
+                if (!k.startsWith(prefix))
+                    continue;
+                keys.push(k);
+            }
+            for (const k of keys) {
+                const record = parseRecord(storage.getItem(k));
+                if (!record)
+                    continue;
+                if (record.chainId !== chainId)
+                    continue;
+                if (record.subscriptions.some((sub) => sub.durable)) {
+                    result.push(record);
+                }
+            }
+            return result;
+        },
+        appendEvent: async (chainId, hash, event) => {
+            // Async so a `storage.setItem` throw (quota exceeded, browser
+            // disabled storage, private-mode constraints) surfaces as a
+            // rejected promise rather than a synchronous throw — the tracker
+            // routes store errors through `onError` and never lets them
+            // halt the live emit fanout (spec Appendix A).
+            const key = eventLogKey(keyPrefix, chainId, hash);
+            const existing = parseRecord(storage.getItem(key)) ?? [];
+            existing.push(event);
+            // Drop oldest entries when the log exceeds the cap. Slicing
+            // from the tail keeps the most-recent window — the audit-trail
+            // pattern indexers expect.
+            const trimmed = existing.length > eventLogCapacity
+                ? existing.slice(existing.length - eventLogCapacity)
+                : existing;
+            storage.setItem(key, stringifyRecord(trimmed));
+        },
+        readEventLog: async (chainId, hash, since) => {
+            const key = eventLogKey(keyPrefix, chainId, hash);
+            const raw = storage.getItem(key);
+            const events = parseRecord(raw) ?? [];
+            if (since === undefined)
+                return events;
+            return events.filter((e) => e.at.blockNumber >= since);
+        },
+    };
+};
+/**
+ * Delete every key in `storage` whose name starts with `prefix`.
+ * Exported so consumers can run prefix cleanup without instantiating
+ * the full store — e.g., on app boot before constructing the tracker.
+ */
+export const deleteKeysStartingWith = (storage, prefix) => {
+    if (!prefix)
+        return;
+    // Snapshot keys first; removing during iteration shifts indexing.
+    const matched = [];
+    for (let i = 0; i < storage.length; i++) {
+        const k = storage.key(i);
+        if (k !== null && k.startsWith(prefix))
+            matched.push(k);
+    }
+    for (const k of matched)
+        storage.removeItem(k);
+};
+//# sourceMappingURL=local-storage-store.js.map

package/dist/local-storage-store.js.map

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