@valve-tech/tx-tracker 0.6.0 → 0.8.0

package/AGENTS.md

@@ -0,0 +1,237 @@
+# AGENTS.md
+
+Terse reference for AI agents (Claude Code, Cursor, Aider, etc.) integrating
+`@valve-tech/tx-tracker`. The full README is for humans; this file is for
+agents that need to ground their work in the package's actual surface
+quickly.
+
+## What this package does
+
+Per-tx state machine for EVM chains. Consumes a `ChainSource`'s block +
+mempool stream and emits **neutral observations** (`seen-in-mempool`,
+`seen-in-block`, `replaced-by`, `vanished-from-block`,
+`unseen-for-N-blocks`, `signal-degraded`, `signal-recovered`,
+`stopped`). Three consumption shapes (callback / async iterator /
+snapshot) over one push-based core. Per-method capability disclosure
+keeps the no-silent-downgrade rule.
+
+Sibling to `@valve-tech/gas-oracle` — both consume the same
+`ChainSource`, neither depends on the other. One upstream RPC poll
+cycle can feed both.
+
+`viem ^2.0.0` is the only external peer. `@valve-tech/chain-source`
+is a runtime dependency.
+
+## Public API
+
+All exports live under `src/index.ts` (single subpath; no sub-exports).
+
+```ts
+import {
+  createTxTracker,                   // primary constructor
+  createInMemoryStore,               // default TxTrackerStore impl
+  computeRetentionExpiry,            // pure helper
+  defaultRetentionBlocks,            // 64
+  defaultReorgDepthBlocks,           // 12
+  defaultMaxBulkSubscriptions,       // 16
+  // pure detectors / matchers
+  appendBlock,
+  detectDivergences,
+  compileSelector,
+  matchAll,
+  // event builders (mostly internal — exported for store implementers)
+  buildStarted, buildSeenInMempool, buildLeftMempool,
+  buildSeenInBlock, buildVanishedFromBlock, buildReplacedBy,
+  buildUnseenForNBlocks, buildSignalDegraded, buildSignalRecovered,
+  buildStopped, buildInitialStatus,
+  // types
+  type TxTracker,
+  type CreateTxTrackerOptions,
+  type TrackOptions,
+  type BulkTrackOptions,
+  type TxMatchEvent,
+  type TxSubscription,
+  type LostSignalPolicy,
+  type TxEvent,
+  type TxEventStarted, type TxEventSeenInMempool, type TxEventLeftMempool,
+  type TxEventSeenInBlock, type TxEventVanishedFromBlock,
+  type TxEventReplacedBy, type TxEventUnseenForNBlocks,
+  type TxEventSignalDegraded, type TxEventSignalRecovered,
+  type TxEventStopped,
+  type TxStatus,
+  type Address, type Hash, type At, type Envelope,
+  // store types
+  type TxTrackerStore,
+  type TrackedTxRecord,
+  type PersistedSubscription,
+  type HashSelector,
+  type BulkSelector,
+  type InMemoryStoreOptions,
+  // reorg
+  type BlockSample,
+  type BlockDivergence,
+  // selectors
+  type CompiledSelector,
+  type BulkMatchPayload,
+} from '@valve-tech/tx-tracker'
+```
+
+## Five types you must know
+
+| Type | What it is |
+|---|---|
+| `CreateTxTrackerOptions` | Constructor config. Required: `source`, `chainId`. Tuneables: `store`, `lostSignalPolicy`, `reorgDepthBlocks`, `unseenThresholdBlocks`, `maxBulkSubscriptions`, `onError`, `lifecycle`. |
+| `TxEvent` | Discriminated union of 10 variants (see below). Every variant carries `{ hash, chainId, source, at: { blockNumber, timestamp } }`. |
+| `TxStatus` | Cached snapshot returned by `getTxStatus(hash)`. Carries the **last observation** (`lastSeenInBlock`, `lastSeenInMempool`, `replacedBy`, `vanishedAt`) plus housekeeping (`unseenStreak`, `firstObservedAtBlock`, `lastObservedAtBlock`, `capabilities`). |
+| `TxTrackerStore` | Persistence surface. `put` / `get` / `delete` / `listDurable` / `appendEvent` / `readEventLog?`. Default: `createInMemoryStore`. |
+| `BulkSelector` | `{ kind: 'from' \| 'to' \| 'predicate', address?, match? }`. From / to lowercase the address once at compile time. Predicate runs O(N) per tx per tick. |
+
+## The discriminated `TxEvent`
+
+Every event carries the same envelope; the `kind` field discriminates
+the variant-specific payload.
+
+```ts
+type TxEvent =
+  | { kind: 'started';              capabilities: Capabilities }
+  | { kind: 'seen-in-mempool';      bucket: 'pending' | 'queued'; tx: RawTx }
+  | { kind: 'left-mempool' }
+  | { kind: 'seen-in-block';        blockHash; blockNumber; transactionIndex; confirmations }
+  | { kind: 'vanished-from-block';  previousBlockHash; canonicalBlockHash; blockNumber }
+  | { kind: 'replaced-by';          replacementHash; replacementBlockNumber: bigint | null }
+  | { kind: 'unseen-for-N-blocks';  blocks: number }
+  | { kind: 'signal-degraded';      capabilityLost: keyof Capabilities; fallbackSource }
+  | { kind: 'signal-recovered';     capabilityRestored: keyof Capabilities }
+  | { kind: 'stopped';              reason: 'unsubscribed' | 'retention-expired' | 'tracker-stopped' }
+```
+
+The envelope on every variant:
+
+```ts
+{
+  hash: Hash
+  chainId: number
+  source: 'subscription' | 'block-poll' | 'mempool-snapshot' | 'receipt-poll'
+  at: { blockNumber: bigint; timestamp: bigint }
+}
+```
+
+## Three consumption shapes (consistent across all three)
+
+```ts
+// 1. Snapshot — sub-millisecond, returns null if not tracked
+const status = tracker.getTxStatus(hash)
+
+// 2. Callback — returns an unsubscribe handle
+const unsub = tracker.subscribe(hash, (event) => { /* ... */ })
+
+// 3. Async iterator — recommended for new code
+for await (const event of tracker.track(hash)) {
+  if (event.kind === 'seen-in-block' && event.confirmations >= 6) break
+}
+```
+
+All three back onto the same internal `Subscriptions<TxEvent>` per
+hash, so they see consistent state.
+
+## Bulk subscriptions (indexer-style)
+
+```ts
+const sub = tracker.trackFromAddress(treasuryAddress, { durable: true })
+// raw match stream:
+for await (const m of sub.events()) { /* m: TxMatchEvent */ }
+// per-hash event stream (auto-tracked by default):
+sub.subscribe((event) => { /* TxEvent */ })
+sub.stop()  // does NOT stop already-auto-tracked per-hash subs
+```
+
+`trackFromAddress` / `trackToAddress` / `trackPredicate`. Capped at
+`maxBulkSubscriptions: 16` by default.
+
+## Composing with gas-oracle
+
+One `ChainSource` shared across both — one upstream RPC poll cycle:
+
+```ts
+import { createChainSource } from '@valve-tech/chain-source'
+import { createGasOracle }   from '@valve-tech/gas-oracle'
+import { createTxTracker }   from '@valve-tech/tx-tracker'
+
+const source  = createChainSource({ client })
+const oracle  = createGasOracle({ source, chainId: 1 })
+const tracker = createTxTracker({ source, chainId: 1 })
+
+source.start(); oracle.start(); tracker.start()
+```
+
+Each surface owns its own lifecycle — `oracle.stop()` does not stop
+the source or the tracker.
+
+## Configuration patterns
+
+| Setting | Default | Tune up for | Tune down for |
+|---|---|---|---|
+| `reorgDepthBlocks` | 12 | Weak-finality chains (PoW, small validator sets) | High-finality chains; only care about shallow reorgs |
+| `unseenThresholdBlocks` | 30 | Slow chains (Ethereum: ~6 min) | Fast L2s |
+| `lostSignalPolicy` | `'emit-uncertain'` | (default — loud is correct) | `'silent'` for wallets that don't want capability-churn UI flicker |
+| `createInMemoryStore({ retentionBlocks })` | 64 | Indexers replaying long windows | Wallet UIs |
+| `createInMemoryStore({ eventLogCapacity })` | 256 | Heavy catch-up on restart | Memory-constrained mobile / edge |
+
+`reorgDepthBlocks` and retention are in **block-units, not seconds** —
+reorg safety is a depth invariant. Spec §10.1.
+
+## Wire format
+
+All numeric fields are `bigint` (block numbers, fees, timestamps).
+`JSON.stringify(event)` will throw without hex-encoding at the wire
+boundary. Durable store implementers MUST hex-encode (`'0x' + n.toString(16)`)
+on write and decode on read. The default in-memory store keeps `bigint`
+end-to-end.
+
+## Capability disclosure
+
+`tracker.capabilities()` forwards the source's snapshot:
+
+```ts
+{
+  newHeads:                'subscription' | 'poll-only' | 'unavailable'
+  newPendingTransactions:  'subscription' | 'poll-only' | 'unavailable'
+  txpoolContent:           'available' | 'gated'
+  receiptByHash:           'available' | 'unavailable'
+  reprobeOnReconnect:      boolean
+}
+```
+
+When capabilities change mid-tracking, the tracker emits
+`signal-degraded` / `signal-recovered` per affected key. Consumers that
+need hard inclusion guarantees filter to `event.source === 'subscription'`.
+
+## Examples
+
+- `examples/07-tx-tracker.ts` — minimal tracker, no oracle (async iterator)
+- `examples/08-tx-tracker-with-oracle.ts` — shared `ChainSource` between gas-oracle + tracker
+- `examples/09-bulk-from-address.ts` — indexer-style bulk subscription
+
+(Examples live under `node_modules/@valve-tech/gas-oracle/examples/` —
+the toolkit's examples directory is hosted by gas-oracle.) Run with
+`yarn tsx examples/07-tx-tracker.ts`.
+
+## Skills (for AI agents)
+
+`skills/` directory ships in the npm tarball. If you're an AI agent
+working in a project that has installed this package, look in
+`node_modules/@valve-tech/tx-tracker/skills/tx-tracker-integration/SKILL.md`
+for trigger conditions and integration recipes that go deeper than this
+file.
+
+## Verifying provenance
+
+v0.6.0+ ships with SLSA provenance attestation:
+
+```bash
+npm view @valve-tech/tx-tracker@latest --json | jq .dist.attestations
+npm audit signatures
+```
+
+The attestation links the published tarball to the GitHub Actions
+workflow run that built it.

package/CHANGELOG.md

@@ -6,6 +6,146 @@ 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.8.0] — 2026-05-06
+
+### Added
+- `lostSignalPolicy: { strategy: 'receipt-poll-fallback', pollEveryBlocks: N }` runtime. Closes the type-vs-runtime gap from v0.3.x — when a tracked subscription is in a degraded state, the tracker fetches `getReceipt` every N block ticks and emits `seen-in-block` with `source: 'receipt-poll'` on hit. Capability gate: requires `receiptByHash === 'available'`.
+- `withReceipts: true` opt-in receipt enrichment on `TrackOptions`. When set, the tracker pre-fetches the receipt before the per-record block decision and attaches it to `seen-in-block` events via the new `TxEventSeenInBlock.receipt` field. One emit per inclusion — receipt is on the first event, not a follow-up.
+- `tracker.group(hashes, options?)` — cross-tx correlation (spec §18.1). Emits `group-progress` / `group-complete` / `group-failed` / `group-stopped` derived from per-member event streams. Replacement does NOT auto-promote.
+- `watchTransaction({ client, hash, ... })` — one-shot callback convenience export.
+- `waitForTransaction({ client, hash, ... })` — Promise variant of `watchTransaction`. Resolves with discriminated-union outcome (`mined` / `dropped` / `replaced` / `failed`).
+- `waitForPending({ client, hash, timeoutBlocks })` — Promise that resolves on first `seen-in-mempool`; rejects with typed `WaitForPendingTimeoutError` if the hash isn't observed within `timeoutBlocks`.
+- `replaceTransaction({ original, walletClient, newGas })` — same-nonce replacement primitive. Caller-provides-newGas keeps tx-tracker independent of `@valve-tech/gas-oracle`.
+
+### Changed
+- `onBlock` is now async to support pre-fetching receipts before the per-record decision. Stale-block guard added against the resulting interleave window so a delayed pre-fetch can't clobber state advanced by a concurrent block tick.
+- `decideBlockObservation` accepts an optional `prefetchedReceipts: ReadonlyMap<Hash, TransactionReceipt>` parameter (backward-compatible — existing callsites omit it).
+
+## [0.7.0] — 2026-05-06
+
+> **The implementation lands.** This is the first release of
+> `@valve-tech/tx-tracker` with a real public surface. Prior versions
+> (v0.0.1 → v0.6.0) were stubs reserving the npm name. The full
+> design contract is at `docs/tx-tracker-spec.md` in the
+> `valve-tech/evm-toolkit` repo.
+
+### Added
+
+- **Per-tx state machine** (`createTxTracker`) consuming a
+  `ChainSource` for upstream block + mempool signals. Three
+  consumption shapes over one push-based core: `getTxStatus(hash)`
+  for the cached snapshot, `subscribe(hash, cb)` for callback-style,
+  and `track(hash)` for the async-iterator shape — all three back
+  onto the same internal stream so they see consistent state.
+- **`TxEvent` discriminated union** (spec §6) with neutral
+  observation kinds: `started`, `seen-in-mempool`, `left-mempool`,
+  `seen-in-block`, `vanished-from-block`, `replaced-by`,
+  `unseen-for-N-blocks`, `signal-degraded`, `signal-recovered`,
+  `stopped`. Every event carries an envelope (`hash`, `chainId`,
+  `source`, `at: { blockNumber, timestamp }`) so consumers can
+  apply policy (`'confirmed'`, `'stuck'`, etc.) in their own UX
+  voice without the tracker prejudging.
+- **`TxTrackerStore` interface + `createInMemoryStore` default**
+  (spec §9, §10). Block-unit retention (`retentionBlocks: 64` by
+  default — reorg safety is a depth invariant, not a wall-clock
+  invariant), bounded per-hash audit log (`eventLogCapacity: 256`
+  by default) for catch-up replay.
+- **Reorg detector** (`detectDivergences`, spec §12) — pure function
+  over `BlockSample[]` that flags same-height different-hash
+  divergences within `reorgDepthBlocks` (default 12). Ring is
+  conservative about heights with no canonical entry — a partial
+  canonical sequence does not nuke unrelated ring entries.
+- **Bulk subscriptions** (spec §11): `trackFromAddress`,
+  `trackToAddress`, `trackPredicate`. Auto-tracks matched hashes
+  by default (`autoTrackMatched: true`) so the per-hash event
+  stream is available too. Capped at `maxBulkSubscriptions: 16`.
+- **Capability disclosure** — `tracker.capabilities()` forwards the
+  source's snapshot. `signal-degraded` / `signal-recovered` events
+  fire on every tracked hash when source-level capability
+  transitions cross authority boundaries.
+- **Replacement detection** — caches `(from, nonce)` on first
+  observation and emits `replaced-by` when a different hash with
+  the same identity appears (mempool: `replacementBlockNumber: null`;
+  block: filled-in block number).
+- **`subscribeAll(cb)`** — global stream of every event the tracker
+  emits, useful for indexers piping to a single sink.
+- **`AGENTS.md`** + **`skills/tx-tracker-integration/SKILL.md`** for AI
+  agents working in downstream projects that import the package. Both
+  ship in the npm tarball; the SKILL.md trigger phrases catch
+  "track this transaction," "watch tx hash," "stuck transaction," and
+  composition questions with `@valve-tech/gas-oracle`.
+
+### Changed
+
+- **Coverage hardening pre-1.0.** Eliminated dead defensive branches
+  in `reorg.ts` (sort-comparator equal-key arms unreachable after
+  the dedup `filter`; `?? 0n` defaults unreachable after the empty-
+  array early return). Tightened `capabilityRank`'s input type from
+  `string` to a `CapabilityValue` union literal so the switch is
+  exhaustive without a default arm.
+- **Test suite up from 75 → 95 tests** (+20). New coverage:
+  `trackToAddress`, per-subscription `lostSignalPolicy` overrides,
+  durable-subscription persistence (with stub stores), predicate-
+  selector + `durable: true` warning, store.appendEvent / store.put
+  failure routing through `onError`, bad-block-number handling,
+  async iterator queue-vs-waiter ordering and early-break cleanup,
+  bulk async iterator drain via `sub.stop()`, multi-sub-on-same-hash
+  cleanup semantics, idempotent `stop` / `unsub` / `sub.stop`,
+  reorg handler skipping records without `lastSeenInBlock`,
+  `findReplacement` raw-nonce fallback when `BigInt()` throws,
+  `lifecycle: 'lazy'` accepts-the-option contract.
+- Coverage went **89.23% / 78.59% / 92.13% / 91.84%** stmts / branches
+  / funcs / lines → **96.13% / 88.93% / 98.87% / 97.61%**, then to
+  **97.22% / 92.7% / 98.9% / 98.12%** after the per-record decision
+  logic was extracted into pure functions (see "Refactor" below).
+
+### Refactor
+
+- **Per-record decision logic extracted from `tracker.ts` into a new
+  pure module `observations.ts`.** The previous shape — two giant
+  closures inside `onBlock` / `onMempool` mutating shared state and
+  emitting events as a side effect — was a pile of conditionals that
+  could only be tested by spinning up the full state machine through
+  a stub source. Now `decideBlockObservation` and
+  `decideMempoolObservation` are pure functions: literal inputs in,
+  `{ events, statusPatch, identityPatch, inMempoolPatch }` out. The
+  orchestrator in `tracker.ts` shrank to "compute envelope, loop
+  records, call decision fn, merge patch, emit events." Same shape
+  as the rest of the toolkit (`reducePollInputs` pure / poll loop
+  stateful in gas-oracle; math pure / source stateful in chain-source).
+  - **`observations.ts` lands at 100% statements / 100% branches**
+    (67/67 stmts, 55/55 branches) covered by 33 fixture-driven unit
+    tests in `observations.test.ts`. Each per-record decision arm
+    has a dedicated test with literal inputs — no async, no stubs,
+    no shared state.
+  - `tracker.ts` shrank from 374 statements → 344 (the extracted
+    code is gone) and is now mostly orchestration; its branch
+    coverage rose from 86.69% → 88.75%.
+  - `findReplacement` (closure-based) replaced with pure
+    `findReplacementInMempool(snapshot, identity, originalHash)`.
+    `cacheIdentityFromTx` (mutation-based) replaced with pure
+    `cacheIdentity(current, tx)` returning a patch.
+  - **No behavior change.** All 95 pre-refactor integration tests
+    continue to pass unchanged; the refactor is internal-only and
+    the public API surface is identical.
+  - Tracker test suite: 95 → 133 (+38: 33 from `observations.test.ts`
+    plus 5 new tracker integration tests covering reorg height-mismatch
+    skip and async-iterator multi-waiter drain paths).
+
+### Notes
+
+- Implements spec §5–§12 minus the `'receipt-poll-fallback'`
+  lostSignalPolicy strategy (the type is accepted; the runtime
+  falls back to `'emit-uncertain'` and a follow-up PR adds the
+  per-block receipt fetch path).
+- Predicate bulk selectors are silently non-durable per spec §13.2
+  (closures don't survive a process boundary). The tracker logs a
+  warning via `onError` when a `predicate` selector is registered
+  with `durable: true` and persists everything else about the
+  selector.
+- `gas-oracle` and `tx-tracker` remain siblings — neither imports
+  the other; both consume `@valve-tech/chain-source` directly.
+
 ## [0.6.0] — 2026-05-05
 
 ### Notes

package/README.md

@@ -1,10 +1,5 @@
 # @valve-tech/tx-tracker
 
-> **Status: stub (v0.0.1).** This package is a name reservation. The
-> implementation lands in v0.1.0. See
-> [`docs/tx-tracker-spec.md`](https://github.com/valve-tech/evm-toolkit/blob/main/docs/tx-tracker-spec.md)
-> for the full design contract.
-
 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` —
@@ -12,8 +7,11 @@ so wallet UIs, indexers, and relays can write their own interpretations
 on top. The package itself never says "confirmed" or "stuck"; it gives
 you the data to decide.
 
+See
+[`docs/tx-tracker-spec.md`](https://github.com/valve-tech/evm-toolkit/blob/main/docs/tx-tracker-spec.md)
+for the full design contract.
+
 ```ts
-// v0.1.0+ shape (not yet implemented):
 import { createChainSource } from '@valve-tech/chain-source'
 import { createTxTracker } from '@valve-tech/tx-tracker'
 
@@ -51,6 +49,15 @@ adapters (callback / async iterator / snapshot).
 yarn add @valve-tech/tx-tracker @valve-tech/chain-source viem
 ```
 
+## For AI agents
+
+This package ships an [`AGENTS.md`](AGENTS.md) reference and a
+[`skills/`](skills/) directory for Claude Code / Cursor skill files
+shipped in the npm tarball. After install, both are reachable at:
+
+- `node_modules/@valve-tech/tx-tracker/AGENTS.md`
+- `node_modules/@valve-tech/tx-tracker/skills/tx-tracker-integration/SKILL.md`
+
 ## License
 
 MIT