@valve-tech/chain-source 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,46 @@
+# @valve-tech/chain-source
+
+> **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)
+> §3 for the design contract.
+
+Canonical EVM chain-observation primitive. Provides a unified push-or-poll
+source for new blocks, mempool snapshots, on-demand receipt and tx
+lookups, and explicit capability disclosure (HTTP / WS / per-method
+gating). Designed to be consumed by multiple downstream views of chain
+state — `@valve-tech/gas-oracle` and `@valve-tech/tx-tracker` are the
+first two.
+
+```ts
+// v0.1.0+ shape (not yet implemented):
+import { createChainSource } from '@valve-tech/chain-source'
+import { createPublicClient, http } from 'viem'
+import { mainnet } from 'viem/chains'
+
+const client = createPublicClient({ chain: mainnet, transport: http() })
+const source = createChainSource({ client })
+source.start()
+
+source.subscribeBlocks((block) => { /* ... */ })
+source.subscribeMempool((snapshot) => { /* ... */ })
+const receipt = await source.getReceipt('0xabc...')
+```
+
+## Why this exists
+
+Both gas-oracle and tx-tracker need the same upstream signals — new
+blocks, mempool snapshots, capability probing. Re-implementing the
+poll loop in each would mean double-polling for consumers who use
+both. Sharing a `ChainSource` instance between them gives one upstream
+RPC stream feeding multiple derived views.
+
+## Install
+
+```bash
+yarn add @valve-tech/chain-source viem
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @valve-tech/chain-source — 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` §3 in the
+ * `valve-tech/evm-toolkit` repo, which defines the `ChainSource`
+ * interface 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;;;;;;;;;;;;GAYG;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,48 @@
+{
+  "name": "@valve-tech/chain-source",
+  "version": "0.0.1",
+  "description": "Canonical EVM chain-observation primitive: a unified push-or-poll source for new blocks, mempool snapshots, on-demand receipt + tx lookups, and capability disclosure (HTTP / WS / per-method gating). Used as the shared foundation by @valve-tech/gas-oracle and @valve-tech/tx-tracker; consumable directly by anyone building their own derived view on chain state. viem-native. 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/chain-source#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/valve-tech/evm-toolkit.git",
+    "directory": "packages/chain-source"
+  },
+  "bugs": {
+    "url": "https://github.com/valve-tech/evm-toolkit/issues"
+  },
+  "keywords": [
+    "ethereum",
+    "evm",
+    "viem",
+    "rpc",
+    "mempool",
+    "subscription",
+    "chain-observer"
+  ],
+  "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"
+  }
+}