@valve-tech/chain-source 0.10.1 → 0.11.0

package/AGENTS.md

@@ -0,0 +1,271 @@
+# AGENTS.md
+
+Terse reference for AI agents (Claude Code, Cursor, Aider, etc.) integrating
+`@valve-tech/chain-source`. 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
+
+Canonical EVM chain-observation primitive. Owns the upstream poll cycle,
+the per-method capability probe, and a typed multi-subscriber pub/sub
+for new blocks and mempool snapshots. Plus on-demand RPC passthroughs
+(block, fee history, receipt, tx by hash, fresh mempool snapshot).
+
+Designed as the **shared foundation** for derived views of chain state.
+Both `@valve-tech/gas-oracle` (gas-tier reducer) and
+`@valve-tech/tx-tracker` (per-tx state machine) consume a `ChainSource`
+rather than re-implementing their own poll loops — one upstream RPC
+stream feeds every consumer that attaches.
+
+Browser/mobile-safe: no Node-only imports (`events`, `fs`, etc.).
+`viem ^2.0.0` is the only peer dependency.
+
+See `docs/tx-tracker-spec.md` §3 for the full design contract.
+
+## Public API
+
+All exports live under `src/index.ts`. Single subpath; no sub-exports.
+
+```ts
+import {
+  createChainSource,                 // primary constructor
+  Subscriptions,                     // typed pub/sub primitive (browser-safe)
+  normalizeMempool,                  // pure helper — txpool_content → NormalizedMempool
+  probeCapabilities,                 // standalone capability probe (used internally)
+  // low-level transport helpers (also used internally)
+  safeRequest,
+  fetchBlock,
+  fetchHeadBlockNumber,
+  fetchFeeHistory,
+  fetchTxPool,
+  fetchReceipt,
+  fetchTransaction,
+  zeroHash,
+  // types
+  type ChainSource,
+  type CreateChainSourceOptions,
+  type BlockResult,
+  type Capabilities,
+  type EventSource,
+  type FeeHistoryResult,
+  type NormalizedMempool,
+  type PollOptions,
+  type RawTx,
+  type TransactionReceipt,
+} from '@valve-tech/chain-source'
+```
+
+## Five types you must know
+
+| Type | What it is |
+|---|---|
+| `CreateChainSourceOptions` | Constructor config. Required: `client` (a viem `PublicClient`). Tuneables: `pollIntervalMs` (default `10_000`), `poll: { mempool?, feeHistory? }`, `onError`. |
+| `ChainSource` | The instance. Lifecycle (`start` / `stop` / `pollOnce` / `ready`), two subscribe streams, five on-demand fetchers, plus `capabilities()`. |
+| `BlockResult` | Wire-shape block: hex-encoded numbers (`number`, `timestamp`, `baseFeePerGas`, `gasLimit`, `gasUsed`, optional blob fields), full `transactions: RawTx[]`. Consumers decode the fields they need. |
+| `NormalizedMempool` | `{ pending, queued }` two-level map: `sender (lowercase) → nonce (decimal string) → RawTx`. Always pre-normalized; consumers do O(1) two-key lookups, no case/format folding needed. |
+| `Capabilities` | The probe result. Per-method, not per-transport — see the matrix below. |
+
+## The capability matrix
+
+Probed eagerly at construction, cached on the source, exposed via
+`source.capabilities()`. The toolkit's "no silent downgrade" rule (spec
+§2.2) is enforced *here* — every event a downstream emits carries an
+`EventSource` discriminator chosen against this matrix.
+
+```ts
+interface Capabilities {
+  newHeads:                 'subscription' | 'poll-only' | 'unavailable'
+  newPendingTransactions:   'subscription' | 'poll-only' | 'unavailable'
+  txpoolContent:            'available' | 'gated'
+  receiptByHash:            'available' | 'unavailable'
+  reprobeOnReconnect:       boolean
+}
+```
+
+Read `'subscription'` as "push path is live", `'poll-only'` as
+"falling back to the interval timer", `'unavailable'` as "no path —
+this signal is silent on this RPC". The probe runs one opportunistic
+`eth_subscribe('newHeads')` round-trip to distinguish "subscribe is on
+the transport" from "subscribe actually works on this provider" — some
+viem transports wrap-but-can't-subscribe and the structural-only check
+would lie.
+
+`reprobeOnReconnect` is `true` for WS transports that signal reconnect.
+HTTP has no persistent connection so it's always `false`.
+
+## The conservative probing window
+
+For a brief window between `createChainSource()` and the eager probe
+landing, `capabilities()` returns a `PROBING_DEFAULT` snapshot with
+every signal set to the most defensive value (`unavailable` / `gated`).
+This is intentional: a consumer that reads capabilities in this window
+gets the safest answer (no path, fall back to the most defensive flow).
+
+Callers that need a guaranteed-completed probe:
+
+```ts
+await source.ready()
+const caps = source.capabilities()  // real values, not the defensive default
+```
+
+## `EventSource` discriminator
+
+Reserved vocabulary for downstream events. The source itself doesn't
+author editorial events (no `confirmed` / `failed` / `dropped` here —
+those live in `@valve-tech/tx-tracker`); but events that downstreams
+build from chain-source observations carry a `source` discriminator
+chosen from this union:
+
+```ts
+type EventSource =
+  | 'subscription'        // arrived via eth_subscribe (push)
+  | 'block-poll'          // arrived via the source's eth_getBlockByNumber tick
+  | 'mempool-snapshot'    // arrived via the source's txpool_content tick
+  | 'receipt-poll'        // tx-tracker fallback per-hash receipt poll
+```
+
+Consumers that need hard guarantees on the freshness/authority of an
+observation filter to `'subscription'`.
+
+## Two integration shapes (pick one)
+
+### 1. Standalone (you're building your own derived view)
+
+```ts
+import { createPublicClient, http } from 'viem'
+import { mainnet } from 'viem/chains'
+import { createChainSource } from '@valve-tech/chain-source'
+
+const client = createPublicClient({ chain: mainnet, transport: http() })
+const source = createChainSource({ client })
+
+const unsubBlocks = source.subscribeBlocks((block) => {
+  // BlockResult — hex strings; decode the fields you care about
+  console.log('block', BigInt(block.number), block.transactions.length, 'txs')
+})
+
+const unsubMempool = source.subscribeMempool((snapshot) => {
+  // NormalizedMempool — pre-lowercased addresses, pre-decimalized nonces
+  console.log('senders', Object.keys(snapshot.pending).length)
+})
+
+source.start()
+
+// On-demand:
+const receipt = await source.getReceipt('0xabc...')
+const tx      = await source.getTransaction('0xabc...')
+const fees    = await source.getFeeHistory(20, [25, 50, 75])
+
+// Teardown — preserves the subscriber registry across restarts.
+source.stop()
+unsubBlocks()
+unsubMempool()
+```
+
+### 2. Shared with sibling derived views (multi-subscriber)
+
+```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()
+// ↑ ONE shared poll cycle. Two derived views. No double-polling.
+```
+
+Each lifecycle is independent — `oracle.stop()` stops the oracle, not
+the source. The owner of the source (whoever called
+`createChainSource`) calls `source.stop()`.
+
+## Pitfalls (read these)
+
+1. **Don't call `source.start()` per request.** Module-scope the
+   source so it starts once at process boot. A hot-path
+   `createChainSource() → start() → subscribe → wait → stop` cycle
+   pays the capability probe cost on every request and wastes the
+   shared-fan-out design.
+
+2. **`subscribeBlocks` / `subscribeMempool` callbacks must be cheap.**
+   The fan-out runs synchronously over a snapshot of the subscriber
+   set. Per-subscriber throws are swallowed (see `Subscriptions`),
+   but a subscriber that blocks (synchronous heavy work) blocks every
+   subscriber registered after it for that emit. Push expensive work
+   into a microtask / worker if needed.
+
+3. **Re-subscribing the same callback reference is a no-op.** The
+   backing set deduplicates by reference. If you really want
+   "deliver twice", register two distinct closures.
+
+4. **`subscribeMempool` snapshots are NOT deduped.** Mempool entries
+   come and go between blocks even on a static head — every
+   successful tick emits. Block events ARE deduped (by hash, not
+   number; same-height reorgs surface as fresh observations).
+
+5. **`getMempoolSnapshot()` returns `null` when `txpool_content` is
+   gated.** Most public RPCs gate this method. Check
+   `source.capabilities().txpoolContent` before assuming a snapshot
+   exists. For continuous mempool access, prefer `subscribeMempool` —
+   that path reuses the source's poll cycle rather than firing a
+   fresh RPC per call.
+
+6. **`capabilities()` returns the defensive default before
+   `await source.ready()`.** If your code branches on capabilities at
+   construction time, await ready first or you'll always take the
+   most-defensive branch.
+
+7. **Stopping the source resets dedup state.** A start → stop → start
+   pattern re-emits the current head + a fresh mempool snapshot on
+   first re-tick (deliberate — a paused-then-resumed consumer should
+   see a current snapshot, not wait for the next chain block). It does
+   NOT clear the subscriber registry.
+
+8. **Wire-format note.** Numeric fields on `BlockResult` /
+   `FeeHistoryResult` / `TxPoolContent` arrive as **hex strings** —
+   that's what the upstream JSON-RPC returns. The source decodes only
+   the bits IT needs (block number for the head-probe gate); your
+   consumer code decodes the rest at the point of use. `JSON.stringify`
+   on a state object containing decoded `bigint` values will throw —
+   hex-encode at the wire boundary if you persist.
+
+## On-demand RPC helpers — source vs. transport
+
+The package exports both `source.getBlock(...)` (instance method) and
+`fetchBlock(client, ...)` (free function). Same underlying call.
+
+- Use the instance methods (`source.getBlock`, `source.getReceipt`,
+  etc.) when you have a source and want errors to flow through its
+  `onError` sink.
+- Use the free functions (`fetchBlock`, `fetchReceipt`, etc.) when
+  you need a one-shot RPC without spinning up a source — e.g. inside
+  a script, a test, or a function that already has a `PublicClient`
+  in scope.
+
+`safeRequest(client, method, params, onError?)` is the underlying
+"never throws, returns null on error" wrapper used everywhere in the
+package — use it directly for any custom RPC method that should follow
+the same posture.
+
+## Skills (for AI agents)
+
+`skills/` 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/chain-source/skills/chain-source-integration/SKILL.md`
+for trigger conditions, anti-pattern flags, and recipes for picking
+the right integration shape.
+
+## Verifying provenance
+
+Every published version ships with SLSA provenance attestation:
+
+```bash
+npm view @valve-tech/chain-source@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,16 @@ 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.11.0] — 2026-05-11
+
+### Changed
+
+- Doc comment in `src/types.ts` no longer describes the
+  gas-oracle import migration as "future" — the migration shipped
+  in this same release. Comment now states that this package is the
+  canonical owner and gas-oracle re-exports from `index.ts`. No
+  type-shape change.
+
 ## [0.10.1] — 2026-05-08
 
 Synchronized release — no changes to this package. Republished at

package/dist/types.d.ts

@@ -11,12 +11,13 @@
  * on a state with `bigint` will throw; persistence layers hex-encode
  * at their wire boundary, see `docs/tx-tracker-spec.md` §2.5.
  *
- * The shapes here are **functionally identical** to the equivalent
- * types currently in `@valve-tech/gas-oracle/src/transport.ts` and
- * `mempool.ts`. That is intentional — a future PR migrates gas-oracle
- * to import from this package and removes its local copies. Keeping
- * them structurally identical now means the migration is a simple
- * import swap, not a type-shape change.
+ * This package is the canonical owner of the wire-shape types
+ * (`RawTx`, `BlockResult`, `FeeHistoryResult`, `TxPoolContent`,
+ * `NormalizedMempool`) and the poll-cycle toggle (`PollOptions`).
+ * `@valve-tech/gas-oracle` and `@valve-tech/tx-tracker` import them
+ * from here; gas-oracle re-exports them from its own `index.ts` so
+ * downstream consumers using the gas-oracle package don't have to
+ * add a second import to type a fixture or a stored snapshot.
  */
 /**
  * Minimal tx shape extracted from `eth_getBlockByNumber(latest, true)`

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,KAAK;IACpB,oBAAoB,CAAC,EAAE,MAAM,CAAA;IAC7B,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,aAAa,EAAE,MAAM,EAAE,CAAA;IACvB,MAAM,CAAC,EAAE,MAAM,EAAE,EAAE,CAAA;IACnB,YAAY,EAAE,MAAM,EAAE,CAAA;IACtB,WAAW,EAAE,MAAM,CAAA;CACpB;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,SAAS,EAAE,MAAM,CAAA;IACjB,aAAa,EAAE,MAAM,CAAA;IACrB,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;IACf,YAAY,EAAE,KAAK,EAAE,CAAA;IACrB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAA;IAC9C,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAA;CAC9C;AAED;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GAAG,aAAa,CAAA;AAE7C;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC,eAAe,EAAE,MAAM,CAAA;IACvB,SAAS,EAAE,MAAM,CAAA;IACjB,WAAW,EAAE,MAAM,CAAA;IACnB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CACvB;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,WAAW;IAC1B,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,WAAW,GACnB,cAAc,GACd,YAAY,GACZ,kBAAkB,GAClB,cAAc,CAAA;AAElB;;;;;;;;;;GAUG;AACH,MAAM,WAAW,YAAY;IAC3B,+DAA+D;IAC/D,QAAQ,EAAE,cAAc,GAAG,WAAW,GAAG,aAAa,CAAA;IACtD,4EAA4E;IAC5E,sBAAsB,EAAE,cAAc,GAAG,WAAW,GAAG,aAAa,CAAA;IACpE,oEAAoE;IACpE,aAAa,EAAE,WAAW,GAAG,OAAO,CAAA;IACpC,qEAAqE;IACrE,aAAa,EAAE,WAAW,GAAG,aAAa,CAAA;IAC1C,qEAAqE;IACrE,kBAAkB,EAAE,OAAO,CAAA;CAC5B"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,KAAK;IACpB,oBAAoB,CAAC,EAAE,MAAM,CAAA;IAC7B,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,aAAa,EAAE,MAAM,EAAE,CAAA;IACvB,MAAM,CAAC,EAAE,MAAM,EAAE,EAAE,CAAA;IACnB,YAAY,EAAE,MAAM,EAAE,CAAA;IACtB,WAAW,EAAE,MAAM,CAAA;CACpB;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,SAAS,EAAE,MAAM,CAAA;IACjB,aAAa,EAAE,MAAM,CAAA;IACrB,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;IACf,YAAY,EAAE,KAAK,EAAE,CAAA;IACrB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAA;IAC9C,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAA;CAC9C;AAED;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GAAG,aAAa,CAAA;AAE7C;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC,eAAe,EAAE,MAAM,CAAA;IACvB,SAAS,EAAE,MAAM,CAAA;IACjB,WAAW,EAAE,MAAM,CAAA;IACnB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CACvB;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,WAAW;IAC1B,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,WAAW,GACnB,cAAc,GACd,YAAY,GACZ,kBAAkB,GAClB,cAAc,CAAA;AAElB;;;;;;;;;;GAUG;AACH,MAAM,WAAW,YAAY;IAC3B,+DAA+D;IAC/D,QAAQ,EAAE,cAAc,GAAG,WAAW,GAAG,aAAa,CAAA;IACtD,4EAA4E;IAC5E,sBAAsB,EAAE,cAAc,GAAG,WAAW,GAAG,aAAa,CAAA;IACpE,oEAAoE;IACpE,aAAa,EAAE,WAAW,GAAG,OAAO,CAAA;IACpC,qEAAqE;IACrE,aAAa,EAAE,WAAW,GAAG,aAAa,CAAA;IAC1C,qEAAqE;IACrE,kBAAkB,EAAE,OAAO,CAAA;CAC5B"}

package/dist/types.js

@@ -11,12 +11,13 @@
  * on a state with `bigint` will throw; persistence layers hex-encode
  * at their wire boundary, see `docs/tx-tracker-spec.md` §2.5.
  *
- * The shapes here are **functionally identical** to the equivalent
- * types currently in `@valve-tech/gas-oracle/src/transport.ts` and
- * `mempool.ts`. That is intentional — a future PR migrates gas-oracle
- * to import from this package and removes its local copies. Keeping
- * them structurally identical now means the migration is a simple
- * import swap, not a type-shape change.
+ * This package is the canonical owner of the wire-shape types
+ * (`RawTx`, `BlockResult`, `FeeHistoryResult`, `TxPoolContent`,
+ * `NormalizedMempool`) and the poll-cycle toggle (`PollOptions`).
+ * `@valve-tech/gas-oracle` and `@valve-tech/tx-tracker` import them
+ * from here; gas-oracle re-exports them from its own `index.ts` so
+ * downstream consumers using the gas-oracle package don't have to
+ * add a second import to type a fixture or a stored snapshot.
  */
 export {};
 //# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@valve-tech/chain-source",
-  "version": "0.10.1",
+  "version": "0.11.0",
   "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. Part of the valve-tech/evm-toolkit synchronized release line — implementation lands in subsequent 0.3.x releases per docs/tx-tracker-spec.md.",
   "license": "MIT",
   "homepage": "https://github.com/valve-tech/evm-toolkit/tree/main/packages/chain-source#readme",
@@ -32,7 +32,9 @@
   },
   "files": [
     "dist",
+    "skills",
     "README.md",
+    "AGENTS.md",
     "CHANGELOG.md",
     "LICENSE"
   ],

package/skills/chain-source-integration/SKILL.md

@@ -0,0 +1,257 @@
+---
+name: chain-source-integration
+description: Integrate `@valve-tech/chain-source` — the canonical EVM chain-observation primitive — into a dapp, indexer, watcher, or backend. Use when the user is wiring up a multi-subscriber poll/push source for new blocks or mempool snapshots, deciding whether to subscribe vs poll, asking about RPC capability disclosure (HTTP-only vs WS, `txpool_content` gating, `eth_getTransactionReceipt` fallback), sharing one upstream RPC stream between `@valve-tech/gas-oracle` and `@valve-tech/tx-tracker`, or sees imports from `@valve-tech/chain-source`. Also fires for questions about `subscribeBlocks` / `subscribeMempool`, the conservative probing-window default, the `EventSource` discriminator (`'subscription'` vs `'block-poll'` vs `'mempool-snapshot'` vs `'receipt-poll'`), or "why am I getting null from `getMempoolSnapshot()`?". Skip when the user only wants per-tx state (delegate to tx-tracker skill) or only wants gas-tier recommendations (delegate to gas-oracle skill); both are derived views built on top of this package and have their own integration skills.
+---
+
+# Integrating `@valve-tech/chain-source`
+
+Canonical EVM chain-observation primitive: a unified push-or-poll
+source for new blocks, mempool snapshots, on-demand receipt + tx
+lookups, and explicit per-method capability disclosure. This skill is
+for AI agents working in a project that imports the package — it
+grounds you in the right integration shape and the per-RPC capability
+realities you'll hit in production.
+
+## Decision tree: which integration to use
+
+```
+Is the user composing this WITH @valve-tech/gas-oracle or
+@valve-tech/tx-tracker (or both)?
+├── Yes — construct ONE shared ChainSource, pass `source` (not `client`)
+│         to each sibling. One upstream RPC poll cycle, multiple
+│         derived views. Module-scope the source.
+└── No — does the user need their own derived view of chain state
+         (custom indexer, alerting, analytics, anything that needs
+         the block + mempool stream)?
+         ├── Yes — use `createChainSource` directly. Subscribe via
+         │         `subscribeBlocks` / `subscribeMempool`.
+         └── No  — they probably want one of the sibling packages
+                  instead. Don't ship chain-source as a dependency just
+                  to call `getReceipt` once — viem's `client.getTransactionReceipt`
+                  already does that.
+```
+
+## How to recognize this package in the user's code
+
+```ts
+import {
+  createChainSource,                 // primary constructor
+  Subscriptions,                     // pub/sub primitive (rare to import)
+  normalizeMempool,                  // pure helper
+} from '@valve-tech/chain-source'
+```
+
+`package.json` will show `"@valve-tech/chain-source": "^0.10.x"` — and
+typically also one or both of `@valve-tech/gas-oracle` /
+`@valve-tech/tx-tracker` if they're using the shared-source shape.
+
+## The capability matrix — what each state means for your code
+
+`source.capabilities()` returns this snapshot. Branch on it for any
+code path whose correctness depends on the underlying RPC's surface.
+
+| Field | States | What to do |
+|---|---|---|
+| `newHeads` | `subscription` / `poll-only` / `unavailable` | If `subscription`, you'll get push events. If `poll-only`, you're on the interval timer (default 10s). `unavailable` means the transport has no `subscribe` at all (HTTP-only). |
+| `newPendingTransactions` | `subscription` / `poll-only` / `unavailable` | Same shape. `poll-only` here means mempool falls back to the `txpool_content` tick. `unavailable` means there's no mempool path at all on this provider — `subscribeMempool` will never fire and `getMempoolSnapshot()` returns `null`. |
+| `txpoolContent` | `available` / `gated` | Most public RPCs gate this. If `gated`, mempool is silent unless WS push is available. |
+| `receiptByHash` | `available` / `unavailable` | `unavailable` is rare but real on some L2s/sidechains. tx-tracker's receipt-poll fallback path becomes a no-op. |
+| `reprobeOnReconnect` | boolean | `true` for WS transports that signal reconnect; `false` for HTTP. Informational. |
+
+Always read capabilities AFTER `await source.ready()` if you're
+branching at construction time — before that, you get a defensive
+default with everything `unavailable` / `gated`.
+
+## Per-RPC capability profiles (what to expect)
+
+| RPC class | `newHeads` | `newPendingTxs` | `txpool_content` | Notes |
+|---|---|---|---|---|
+| Self-hosted geth/reth (HTTP+WS) | `subscription` | `subscription` | `available` | Full surface; the default-everything-works case. |
+| Self-hosted geth/reth (HTTP only) | `unavailable` | `poll-only` | `available` | No push; poll cycle drives everything. |
+| Alchemy / Infura / QuickNode (WS) | `subscription` | `subscription` (Alchemy) / `unavailable` (some) | `gated` | Push-based blocks; mempool depends on plan tier. |
+| Public RPC aggregators (LlamaNodes, Ankr, etc., HTTP) | `unavailable` | `unavailable` | `gated` | Block-poll only; mempool is silent. Set `poll: { mempool: false }` to skip the doomed RPC. |
+| PulseChain RPCs (typical) | varies by node | varies | often `gated` | Verify `txpool_content` per node — public PulseChain RPCs frequently gate it. |
+
+If `txpoolContent === 'gated'` AND `newPendingTransactions === 'unavailable'`,
+mempool data is structurally unobtainable on this RPC. Flag that to the
+user — don't write code that silently does nothing.
+
+## Anti-patterns to flag
+
+When reviewing user code, watch for these and suggest fixes:
+
+1. **Constructing a `ChainSource` per request / per render.** The
+   capability probe runs eagerly at construction; the poll loop runs
+   on a timer. Both are wasted if you tear it down 100ms later.
+   Module-scope it.
+
+2. **Constructing a separate `ChainSource` for the gas-oracle AND
+   for the tx-tracker.** That's two independent poll cycles for the
+   same chain — double the RPC traffic for no benefit. Construct one
+   source, pass it to both:
+   ```ts
+   const source = createChainSource({ client })
+   const oracle = createGasOracle({ source, chainId: 1 })
+   const tracker = createTxTracker({ source, chainId: 1 })
+   ```
+
+3. **Reading `source.capabilities()` without `await source.ready()`
+   first** — getting the defensive default and branching on it. Code
+   ends up perma-stuck on the most-defensive path even on a fully-
+   capable provider. Either `await ready()` or wait for the first
+   subscribe event before branching.
+
+4. **Ignoring `source.capabilities().txpoolContent === 'gated'`** then
+   wiring up `subscribeMempool` and being confused about why nothing
+   fires. If the upstream gates the method AND there's no WS push
+   path for `newPendingTransactions`, the mempool stream will never
+   emit — either set `poll: { mempool: false }` to skip the doomed
+   RPC or surface the gap to the user.
+
+5. **Calling `source.start()` but never `subscribeBlocks` / never
+   `subscribeMempool`.** The poll cycle runs, the RPCs fire, but
+   nothing is consuming the events — pure waste. Either subscribe or
+   use the on-demand methods (`getBlock`, `getReceipt`, etc.) which
+   don't need `start()`.
+
+6. **Calling `source.subscribeMempool` and treating the snapshots as
+   diffs.** They're not — every successful mempool tick emits the
+   FULL pending+queued snapshot. If you need diffs, hold the previous
+   snapshot in your subscriber and compute the delta yourself.
+
+7. **Persisting `BlockResult` / `NormalizedMempool` via
+   `JSON.stringify`** without hex-encoding bigints first. The
+   wire-shape types are hex strings already, but anything you
+   decoded to bigint will throw. The toolkit deliberately keeps
+   bigint as the canonical numeric form internally; encoding at the
+   wire boundary is the consumer's job.
+
+8. **Subscribing the same callback reference twice expecting two
+   deliveries.** The backing set deduplicates by reference. If you
+   really want two deliveries, register two distinct closures.
+
+## Standalone usage — minimal
+
+```ts
+import { createPublicClient, http } from 'viem'
+import { mainnet } from 'viem/chains'
+import { createChainSource } from '@valve-tech/chain-source'
+
+const client = createPublicClient({ chain: mainnet, transport: http() })
+const source = createChainSource({
+  client,
+  pollIntervalMs: 12_000,                         // optional; default 10_000
+  poll: { mempool: false },                       // skip doomed txpool_content
+  onError: (method, err) => console.warn(method, err),
+})
+
+await source.ready()  // wait for capability probe before branching
+
+if (source.capabilities().newHeads === 'unavailable') {
+  console.log('poll-only mode — no WS subscribe path')
+}
+
+const unsub = source.subscribeBlocks((block) => {
+  console.log('new block', BigInt(block.number))
+})
+
+source.start()
+// ... later
+unsub()
+source.stop()
+```
+
+## Composing with gas-oracle and tx-tracker
+
+When the user is using two or more derived views, the canonical shape
+is one shared source:
+
+```ts
+import { createPublicClient, http } from 'viem'
+import { mainnet } from 'viem/chains'
+import { createChainSource } from '@valve-tech/chain-source'
+import { createGasOracle }   from '@valve-tech/gas-oracle'
+import { createTxTracker }   from '@valve-tech/tx-tracker'
+
+const client  = createPublicClient({ chain: mainnet, transport: http() })
+const source  = createChainSource({ client })
+const oracle  = createGasOracle({ source, chainId: 1 })
+const tracker = createTxTracker({ source, chainId: 1 })
+
+source.start(); oracle.start(); tracker.start()
+```
+
+`ChainSource` owns the upstream poll cycle. The oracle reads it for
+tier reduction; the tracker reads it for per-tx observations. **One
+upstream RPC poll cycle, two derived views** (per spec §3.1). Each
+surface owns its own lifecycle — `oracle.stop()` does not stop the
+source or the tracker. The owner of the source (whoever called
+`createChainSource`) calls `source.stop()`.
+
+For per-tx tracking work (subscribe to a hash, watch for replacement,
+detect drops), redirect to the tx-tracker integration skill at
+`node_modules/@valve-tech/tx-tracker/skills/tx-tracker-integration/SKILL.md` —
+chain-source itself is intentionally **stateless about per-tx
+anything**.
+
+For gas-tier work (priority-fee tiers, replacement bumps, block
+position queries), redirect to
+`node_modules/@valve-tech/gas-oracle/skills/gas-oracle-integration/SKILL.md` —
+chain-source is intentionally **stateless about gas math**.
+
+## On-demand RPCs without a running source
+
+When you only need a one-shot RPC (a script, a test, a utility
+function that already has a `PublicClient`), the package exports
+free-function transport helpers — same calls as the source's instance
+methods, no construction or lifecycle overhead:
+
+```ts
+import {
+  fetchBlock,
+  fetchReceipt,
+  fetchTransaction,
+  fetchFeeHistory,
+  fetchTxPool,
+  safeRequest,
+} from '@valve-tech/chain-source'
+
+const block   = await fetchBlock(client, 'latest')
+const receipt = await fetchReceipt(client, '0xabc...')
+const tx      = await fetchTransaction(client, '0xabc...')
+
+// Custom method with the same "never throws, returns null" posture:
+const custom = await safeRequest(client, 'eth_chainId', [])
+```
+
+These are the same primitives the source uses internally. Each takes
+an optional `onError(err)` sink as the last arg.
+
+## The `EventSource` discriminator
+
+When a downstream view (tx-tracker, your own derived view) emits
+events built from chain-source observations, those events should
+carry an `EventSource` discriminator chosen against the capability
+matrix. This is the toolkit's "no silent downgrade" rule made
+observable:
+
+```ts
+type EventSource =
+  | 'subscription'        // arrived via eth_subscribe (push)
+  | 'block-poll'          // arrived via the source's eth_getBlockByNumber tick
+  | 'mempool-snapshot'    // arrived via the source's txpool_content tick
+  | 'receipt-poll'        // tx-tracker fallback per-hash receipt poll
+```
+
+When you build your own derived view, follow the same pattern —
+attach a `source` field to your emitted events so consumers can filter
+to `'subscription'` for hard-guarantee freshness.
+
+## Where to find more
+
+- Full API + types: `node_modules/@valve-tech/chain-source/AGENTS.md`
+- Human-facing docs: `node_modules/@valve-tech/chain-source/README.md`
+- Source (when types alone aren't enough): `node_modules/@valve-tech/chain-source/dist/`
+  (compiled JS + .d.ts) — sources aren't shipped, only built output.
+- Design contract: the published-on-GitHub `docs/tx-tracker-spec.md`
+  §3 covers the source's role in the toolkit's broader architecture.