@valve-tech/tx-tracker 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Valve Tech
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,56 @@
+# @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` —
+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.
+
+```ts
+// v0.1.0+ shape (not yet implemented):
+import { createChainSource } from '@valve-tech/chain-source'
+import { createTxTracker } from '@valve-tech/tx-tracker'
+
+const source = createChainSource({ client })
+const tracker = createTxTracker({ source, chainId: 1 })
+source.start(); tracker.start()
+
+for await (const event of tracker.track('0xabc...')) {
+  if (event.kind === 'seen-in-block' && event.confirmations >= 6) break
+}
+```
+
+## Why this exists
+
+Tx-tracking on EVM is unforgiving:
+- **Three different consumer shapes** (wallet UI, indexer, relay) want
+  the same underlying observations but very different consumption
+  ergonomics.
+- **Five state transitions** (pending, mined, replaced, dropped,
+  reorged) plus their authoritative-vs-degraded sources.
+- **Per-method capability variance** — some upstreams gate
+  `txpool_content`, some allow `eth_subscribe('newHeads')` but not
+  `newPendingTransactions`, some only offer HTTP.
+- **No silent downgrade** — a tracker that says "your tx is mined"
+  when the WS dropped and the receipt poll happens to still see the
+  old block is lying. Every event in this package carries a `source`
+  discriminator so consumers know how authoritative it is.
+
+This package handles all of it as one push-based core with three thin
+adapters (callback / async iterator / snapshot).
+
+## Install
+
+```bash
+yarn add @valve-tech/tx-tracker @valve-tech/chain-source viem
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @valve-tech/tx-tracker — placeholder for v0.0.1.
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * Until v0.1.0 is published, no symbols are exported.
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,CAAA"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@valve-tech/tx-tracker",
+  "version": "0.0.1",
+  "description": "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`, etc.) so wallet UIs, indexers, and relays can write their own interpretations on top. Three consumption shapes (callback, async iterator, snapshot) over one push-based core. Per-method capability detection — works on HTTP, WS, both, or neither. Implementation lands in v0.1.0 — this 0.0.1 stub claims the npm name.",
+  "license": "MIT",
+  "homepage": "https://github.com/valve-tech/evm-toolkit/tree/main/packages/tx-tracker#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/valve-tech/evm-toolkit.git",
+    "directory": "packages/tx-tracker"
+  },
+  "bugs": {
+    "url": "https://github.com/valve-tech/evm-toolkit/issues"
+  },
+  "keywords": [
+    "ethereum",
+    "evm",
+    "viem",
+    "transaction",
+    "tx",
+    "tracker",
+    "mempool",
+    "reorg",
+    "indexer"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p .",
+    "typecheck": "tsc -p . --noEmit",
+    "lint": "eslint src",
+    "test": "vitest run",
+    "prepare": "yarn build"
+  },
+  "peerDependencies": {
+    "viem": "^2.0.0"
+  },
+  "dependencies": {
+    "@valve-tech/chain-source": "workspace:^"
+  }
+}