@valve-tech/chain-source 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -6,6 +6,99 @@ 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.7.0] — 2026-05-06
+
+### Notes
+
+- Synchronized release — no consumer-visible changes to this package.
+  Bumped in lockstep with `@valve-tech/tx-tracker@0.7.0`, the
+  long-promised v0.3.x track ChainSource was built to feed (per
+  `docs/tx-tracker-spec.md` §3.1). chain-source itself stays
+  byte-identical with v0.6.0's dist; this release exists so
+  consumers running `npm view @valve-tech/chain-source versions`
+  see the toolkit-wide line is at v0.7.0.
+- Internal-only: the workspace test suite is now at 100/100/100/100
+  coverage on this package (was 97/97/97/98). No new exports, no
+  behavior change.
+
+## [0.6.0] — 2026-05-05
+
+### Added
+
+- **`createChainSource({ client, pollIntervalMs?, poll?, onError? })`** —
+  the canonical `ChainSource` primitive lands. Implements the
+  `subscribe / on-demand / capabilities / lifecycle` contract from
+  [`docs/tx-tracker-spec.md`](https://github.com/valve-tech/evm-toolkit/blob/main/docs/tx-tracker-spec.md)
+  §3.2.
+- **`subscribeBlocks(cb)` / `subscribeMempool(cb)`** — first-class
+  multi-subscriber streams. One upstream poll cycle fans out to every
+  attached subscriber. Returns an idempotent unsubscribe handle.
+- **On-demand RPCs:** `getBlock(tag)`, `getFeeHistory(blockCount, percentiles)`,
+  `getMempoolSnapshot()` (returns the normalized form), `getReceipt(hash)`,
+  `getTransaction(hash)`. Each follows the `safeRequest`-returns-null
+  posture — never throws across the boundary.
+- **`probeCapabilities(client)`** + cached `capabilities()` accessor.
+  The probe runs eagerly at construction; `await source.ready()`
+  guarantees the cached snapshot is populated before reading.
+  Per-method discrimination (`newHeads` / `newPendingTransactions` /
+  `txpoolContent` / `receiptByHash`) honors the "no silent downgrade"
+  invariant from §2.2 of the spec.
+- **`Subscriptions<E>`** — hand-rolled typed pub/sub primitive,
+  browser/mobile-safe (no Node `events` dependency). Per-subscriber
+  throws are swallowed so a single bad consumer cannot affect
+  delivery to the others; emit fans out to a snapshot of subscribers
+  taken at the start of the call so mid-emit registration changes
+  are deferred to the next emit.
+- **Type re-exports** of `BlockResult`, `Capabilities`, `EventSource`,
+  `FeeHistoryResult`, `NormalizedMempool`, `PollOptions`, `RawTx`,
+  `TransactionReceipt`, `TxPoolContent`. These are the wire-format
+  contracts used by `@valve-tech/gas-oracle` and `@valve-tech/tx-tracker`
+  in their v0.3.x migrations.
+- **Additive method on the spec'd interface: `pollOnce()`**. Drives one
+  cycle out-of-band; useful for serverless / manual-refresh flows and
+  for deterministic test setups that don't want to engage fake
+  timers.
+
+### Changed
+
+- **`subscribeBlocks` now dedups by `block.hash`.** Previously, every
+  successful tick fanned out to block subscribers regardless of
+  whether the head had advanced; on a static head that meant an emit
+  every `pollIntervalMs`. The stream now only emits when the observed
+  block hash differs from the last one delivered. Hash-based (not
+  number-based) so a same-height reorg surfaces as a fresh
+  observation. Dedup state resets on `stop()` — a paused-then-resumed
+  source emits a current snapshot to its consumers on first re-tick
+  rather than waiting for the next chain block. `subscribeMempool` is
+  intentionally not deduped — txs come and go between blocks even on
+  a static head, so every successful snapshot remains fresh data.
+- **The poll cycle now head-probe-gates the full block fetch.** Each
+  tick runs a cheap `eth_blockNumber` probe in parallel with the
+  mempool fetch; only when the probe shows the head has advanced (or
+  the probe failed and we're falling through defensively) does the
+  cycle issue the expensive `eth_getBlockByNumber('latest', true)`
+  (1–5MB on busy chains). On a static head with the default 10 s
+  interval, the per-tick RPC weight drops from "full block + mempool
+  + probe" to "probe + mempool". Mempool fetch still runs every
+  cycle. Closes the efficiency-regression risk for the upcoming
+  gas-oracle migration to consume `ChainSource` (the soon-to-be-
+  deprecated `gas-oracle.blockGatedPolling` option had this behavior
+  in v0.5.0; it now lives at the source layer where every consumer
+  benefits).
+
+### Notes
+
+- WebSocket push subscriptions (`eth_subscribe('newHeads')` /
+  `eth_subscribe('newPendingTransactions')`) are not yet wired in this
+  release. The capability probe discloses what the transport
+  *structurally* supports, but the source always uses its interval
+  poll cycle in this revision. A future release adds the push path
+  without changing the consumer-facing surface.
+- `gas-oracle` and `tx-tracker` migrations to consume `ChainSource`
+  land in subsequent PRs of the same v0.3.x track. Until those merge,
+  this package is consumable directly but its sibling packages keep
+  their v0.3.0 standalone behavior.
+
 ## [0.5.0] — 2026-05-05
 
 ### Notes

package/README.md

@@ -1,10 +1,5 @@
 # @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
@@ -12,35 +7,98 @@ 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.
 
+See [`docs/tx-tracker-spec.md`](https://github.com/valve-tech/evm-toolkit/blob/main/docs/tx-tracker-spec.md)
+§3 for the full design contract.
+
+## 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
+```
+
+## Quick start
+
 ```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'
+import { createChainSource } from '@valve-tech/chain-source'
 
 const client = createPublicClient({ chain: mainnet, transport: http() })
 const source = createChainSource({ client })
+
+source.subscribeBlocks((block) => {
+  console.log('new block', block.number)
+})
+
+source.subscribeMempool((snapshot) => {
+  console.log('pending senders', Object.keys(snapshot.pending).length)
+})
+
 source.start()
 
-source.subscribeBlocks((block) => { /* ... */ })
-source.subscribeMempool((snapshot) => { /* ... */ })
+// On-demand RPCs (don't go through the poll cycle):
 const receipt = await source.getReceipt('0xabc...')
+const tx      = await source.getTransaction('0xabc...')
+
+// Stop when done — preserves the subscriber registry across restarts.
+source.stop()
 ```
 
-## Why this exists
+## API surface
 
-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.
+```ts
+interface ChainSource {
+  start(): void
+  stop(): void
+  pollOnce(): Promise<void>
+  ready(): Promise<void>
 
-## Install
+  subscribeBlocks(cb: (block: BlockResult) => void): () => void
+  subscribeMempool(cb: (snapshot: NormalizedMempool) => void): () => void
 
-```bash
-yarn add @valve-tech/chain-source viem
+  getBlock(tag: 'latest' | bigint): Promise<BlockResult | null>
+  getFeeHistory(blockCount: number, percentiles: number[]): Promise<FeeHistoryResult | null>
+  getMempoolSnapshot(): Promise<NormalizedMempool | null>
+  getReceipt(hash: string): Promise<TransactionReceipt | null>
+  getTransaction(hash: string): Promise<RawTx | null>
+
+  capabilities(): Capabilities
+}
+```
+
+The capability probe runs eagerly at construction. `capabilities()`
+returns a conservative default (everything `unavailable` / `gated`)
+for the brief window before the probe lands; `await source.ready()`
+guarantees the real values are cached.
+
+## Multi-subscriber semantics
+
+`subscribeBlocks` and `subscribeMempool` are first-class
+multi-subscriber streams. One upstream RPC poll cycle, regardless of
+how many derived views attach:
+
+```ts
+const source  = createChainSource({ client })
+const oracle  = createGasOracle({ source, chainId: 1 })   // v0.3.x+ shape
+const tracker = createTxTracker({ source, chainId: 1 })   // v0.3.x+ shape
+
+source.start()
+oracle.start()
+tracker.start()
+// ↑ one shared poll cycle, two derived views, no double-polling.
 ```
 
+Stopping a derived view does not stop the source — the consumer that
+constructed the source is the one who calls `source.stop()`.
+
 ## License
 
 MIT

package/dist/capabilities.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Per-method capability probe. Run once at `source.start()`, exposed
+ * via `source.capabilities()`, and re-run on transport reconnect when
+ * the underlying transport supports reconnection signalling. The
+ * probe is the load-bearing place where the toolkit's "no silent
+ * downgrade" rule (spec §2.2) is honored — every event the source
+ * emits carries a `source` discriminator chosen against this matrix.
+ *
+ * The probe uses the existing `safeRequest`-returns-null pattern: a
+ * thrown error is treated as "method gated/unavailable", a `null`
+ * return is treated the same. The distinction between the four states
+ * (`subscription` / `poll-only` / `available` / `gated` /
+ * `unavailable`) lives in the per-method spec table (§7).
+ *
+ * **What this probe deliberately does NOT do:** issue a real
+ * `eth_subscribe` against the upstream. The viem transport's
+ * `subscribe` API surface varies across versions and engaging it just
+ * to immediately tear it down is wasteful + can leak handles on
+ * misbehaving providers. We detect WS-subscribe capability
+ * structurally (`typeof transport.subscribe === 'function'`) and let
+ * the actual subscribe attempt happen lazily when a consumer calls
+ * `source.subscribeBlocks` / `subscribeMempool`. If the runtime
+ * subscribe fails, the source emits a `signal-degraded`-shaped fact
+ * (or downstream consumers do — chain-source itself doesn't author
+ * editorial events). This is the v0.3.x posture; future revisions
+ * may upgrade to live-probing if a provider is found that lies
+ * structurally.
+ */
+import type { PublicClient } from 'viem';
+import type { Capabilities } from './types.js';
+interface ProbeOptions {
+    /** Same role as on `createChainSource` — sub-RPC failure sink. */
+    onError?: (method: string, err: unknown) => void;
+}
+/**
+ * Probe the upstream client's per-method capability. The result is a
+ * stable snapshot the source caches and exposes via
+ * `source.capabilities()`.
+ */
+export declare const probeCapabilities: (client: PublicClient, options?: ProbeOptions) => Promise<Capabilities>;
+export {};
+//# sourceMappingURL=capabilities.d.ts.map

package/dist/capabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../src/capabilities.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,MAAM,CAAA;AAGxC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAE9C,UAAU,YAAY;IACpB,kEAAkE;IAClE,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,KAAK,IAAI,CAAA;CACjD;AAsBD;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,GAC5B,QAAQ,YAAY,EACpB,UAAS,YAAiB,KACzB,OAAO,CAAC,YAAY,CAoDtB,CAAA"}

package/dist/capabilities.js

@@ -0,0 +1,98 @@
+/**
+ * Per-method capability probe. Run once at `source.start()`, exposed
+ * via `source.capabilities()`, and re-run on transport reconnect when
+ * the underlying transport supports reconnection signalling. The
+ * probe is the load-bearing place where the toolkit's "no silent
+ * downgrade" rule (spec §2.2) is honored — every event the source
+ * emits carries a `source` discriminator chosen against this matrix.
+ *
+ * The probe uses the existing `safeRequest`-returns-null pattern: a
+ * thrown error is treated as "method gated/unavailable", a `null`
+ * return is treated the same. The distinction between the four states
+ * (`subscription` / `poll-only` / `available` / `gated` /
+ * `unavailable`) lives in the per-method spec table (§7).
+ *
+ * **What this probe deliberately does NOT do:** issue a real
+ * `eth_subscribe` against the upstream. The viem transport's
+ * `subscribe` API surface varies across versions and engaging it just
+ * to immediately tear it down is wasteful + can leak handles on
+ * misbehaving providers. We detect WS-subscribe capability
+ * structurally (`typeof transport.subscribe === 'function'`) and let
+ * the actual subscribe attempt happen lazily when a consumer calls
+ * `source.subscribeBlocks` / `subscribeMempool`. If the runtime
+ * subscribe fails, the source emits a `signal-degraded`-shaped fact
+ * (or downstream consumers do — chain-source itself doesn't author
+ * editorial events). This is the v0.3.x posture; future revisions
+ * may upgrade to live-probing if a provider is found that lies
+ * structurally.
+ */
+import { safeRequest, zeroHash } from './transport.js';
+/**
+ * Inspect the client's transport surface to decide whether push
+ * subscriptions are possible. The capability is structural — the
+ * subscribe attempt itself is deferred to the actual subscribeBlocks /
+ * subscribeMempool call so we don't pay an early eth_subscribe just
+ * to learn the answer.
+ *
+ * Returns `'subscription'` when the transport exposes a `subscribe`
+ * function (canonical viem WS shape), `'unavailable'` otherwise.
+ * `'poll-only'` is reserved for the future live-probe variant where
+ * we can distinguish "transport supports subscribe but upstream
+ * rejected this method" from "transport doesn't subscribe at all."
+ */
+const probeSubscribeShape = (client) => {
+    const transport = client.transport;
+    return typeof transport.subscribe === 'function' ? 'subscription' : 'unavailable';
+};
+/**
+ * Probe the upstream client's per-method capability. The result is a
+ * stable snapshot the source caches and exposes via
+ * `source.capabilities()`.
+ */
+export const probeCapabilities = async (client, options = {}) => {
+    const subscribeShape = probeSubscribeShape(client);
+    // 1. txpool_content — distinguishes 'available' / 'gated'. Many
+    // public RPCs return 405 / method-not-found for this method.
+    const txpoolResult = await safeRequest(client, 'txpool_content', [], options.onError ? (err) => options.onError('txpool_content', err) : undefined);
+    const txpoolContent = txpoolResult === null ? 'gated' : 'available';
+    // 2. eth_getTransactionReceipt against the zero hash. Per spec §7.2,
+    // most providers return null for the zero hash but should not throw.
+    // A throw is taken as "method unavailable." Use direct request rather
+    // than safeRequest so the throw path is observable.
+    let receiptByHash = 'available';
+    try {
+        await client.request({
+            method: 'eth_getTransactionReceipt',
+            params: [zeroHash],
+        });
+    }
+    catch (err) {
+        receiptByHash = 'unavailable';
+        if (options.onError)
+            options.onError('eth_getTransactionReceipt', err);
+    }
+    // 3. WS-subscribe capability is the same answer for both newHeads
+    // and newPendingTransactions — the discriminator there is whether
+    // the upstream supports the *channel*, not the method. Mid-session
+    // method-specific failure surfaces via `signal-degraded` events on
+    // downstream consumers (the source itself doesn't author editorial
+    // events; see §3.2 of the spec).
+    return {
+        newHeads: subscribeShape,
+        newPendingTransactions: 
+        // If subscribe is unavailable, fall back to whether txpool_content
+        // is available (poll fallback for mempool watch). If both are
+        // unavailable, mempool watch isn't possible at all.
+        subscribeShape === 'subscription'
+            ? 'subscription'
+            : txpoolContent === 'available'
+                ? 'poll-only'
+                : 'unavailable',
+        txpoolContent,
+        receiptByHash,
+        // WS transports are the ones that reconnect; HTTP has no persistent
+        // connection so reprobe-on-reconnect is meaningless.
+        reprobeOnReconnect: subscribeShape === 'subscription',
+    };
+};
+//# sourceMappingURL=capabilities.js.map

package/dist/capabilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.js","sourceRoot":"","sources":["../src/capabilities.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAIH,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AAQtD;;;;;;;;;;;;GAYG;AACH,MAAM,mBAAmB,GAAG,CAC1B,MAAoB,EACY,EAAE;IAClC,MAAM,SAAS,GAAG,MAAM,CAAC,SAAoC,CAAA;IAC7D,OAAO,OAAO,SAAS,CAAC,SAAS,KAAK,UAAU,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,aAAa,CAAA;AACnF,CAAC,CAAA;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,KAAK,EACpC,MAAoB,EACpB,UAAwB,EAAE,EACH,EAAE;IACzB,MAAM,cAAc,GAAG,mBAAmB,CAAC,MAAM,CAAC,CAAA;IAElD,gEAAgE;IAChE,6DAA6D;IAC7D,MAAM,YAAY,GAAG,MAAM,WAAW,CACpC,MAAM,EACN,gBAAgB,EAChB,EAAE,EACF,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,GAAY,EAAE,EAAE,CAAC,OAAO,CAAC,OAAQ,CAAC,gBAAgB,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CACxF,CAAA;IACD,MAAM,aAAa,GACjB,YAAY,KAAK,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,WAAW,CAAA;IAE/C,qEAAqE;IACrE,qEAAqE;IACrE,sEAAsE;IACtE,oDAAoD;IACpD,IAAI,aAAa,GAAgC,WAAW,CAAA;IAC5D,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,OAAO,CAAC;YACnB,MAAM,EAAE,2BAA2B;YACnC,MAAM,EAAE,CAAC,QAAQ,CAAC;SACV,CAAC,CAAA;IACb,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,aAAa,GAAG,aAAa,CAAA;QAC7B,IAAI,OAAO,CAAC,OAAO;YAAE,OAAO,CAAC,OAAO,CAAC,2BAA2B,EAAE,GAAG,CAAC,CAAA;IACxE,CAAC;IAED,kEAAkE;IAClE,kEAAkE;IAClE,mEAAmE;IACnE,mEAAmE;IACnE,mEAAmE;IACnE,iCAAiC;IACjC,OAAO;QACL,QAAQ,EAAE,cAAc;QACxB,sBAAsB;QACpB,mEAAmE;QACnE,8DAA8D;QAC9D,oDAAoD;QACpD,cAAc,KAAK,cAAc;YAC/B,CAAC,CAAC,cAAc;YAChB,CAAC,CAAC,aAAa,KAAK,WAAW;gBAC7B,CAAC,CAAC,WAAW;gBACb,CAAC,CAAC,aAAa;QACrB,aAAa;QACb,aAAa;QACb,oEAAoE;QACpE,qDAAqD;QACrD,kBAAkB,EAAE,cAAc,KAAK,cAAc;KACtD,CAAA;AACH,CAAC,CAAA"}

package/dist/index.d.ts

@@ -1,15 +1,33 @@
 /**
- * @valve-tech/chain-source — placeholder for v0.0.1.
+ * `@valve-tech/chain-source` — canonical EVM chain-observation primitive
+ * for the `valve-tech/evm-toolkit` synchronized release line.
  *
- * 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.
+ * The package is the *foundation* layer for every derived view of
+ * chain state in the toolkit. 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 cycles.
+ * One upstream RPC stream feeds every consumer that attaches.
  *
- * 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.
+ * See `docs/tx-tracker-spec.md` §3 for the full design contract.
  *
- * Until v0.1.0 is published, no symbols are exported.
+ * @example
+ *   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 })
+ *
+ *   source.subscribeBlocks((block) => {
+ *     console.log('block', block.number)
+ *   })
+ *   source.start()
  */
-export {};
+export { createChainSource } from './source.js';
+export type { ChainSource, CreateChainSourceOptions } from './source.js';
+export { Subscriptions } from './subscriptions.js';
+export { normalizeMempool } from './mempool.js';
+export { probeCapabilities } from './capabilities.js';
+export { safeRequest, fetchBlock, fetchHeadBlockNumber, fetchFeeHistory, fetchTxPool, fetchReceipt, fetchTransaction, zeroHash, } from './transport.js';
+export type { BlockResult, Capabilities, EventSource, FeeHistoryResult, NormalizedMempool, PollOptions, RawTx, TransactionReceipt, TxPoolContent, } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAC/C,YAAY,EAAE,WAAW,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAA;AAExE,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAElD,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AAE/C,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AAErD,OAAO,EACL,WAAW,EACX,UAAU,EACV,oBAAoB,EACpB,eAAe,EACf,WAAW,EACX,YAAY,EACZ,gBAAgB,EAChB,QAAQ,GACT,MAAM,gBAAgB,CAAA;AAEvB,YAAY,EACV,WAAW,EACX,YAAY,EACZ,WAAW,EACX,gBAAgB,EAChB,iBAAiB,EACjB,WAAW,EACX,KAAK,EACL,kBAAkB,EAClB,aAAa,GACd,MAAM,YAAY,CAAA"}

package/dist/index.js

@@ -1,2 +1,31 @@
-export {};
+/**
+ * `@valve-tech/chain-source` — canonical EVM chain-observation primitive
+ * for the `valve-tech/evm-toolkit` synchronized release line.
+ *
+ * The package is the *foundation* layer for every derived view of
+ * chain state in the toolkit. 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 cycles.
+ * One upstream RPC stream feeds every consumer that attaches.
+ *
+ * See `docs/tx-tracker-spec.md` §3 for the full design contract.
+ *
+ * @example
+ *   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 })
+ *
+ *   source.subscribeBlocks((block) => {
+ *     console.log('block', block.number)
+ *   })
+ *   source.start()
+ */
+export { createChainSource } from './source.js';
+export { Subscriptions } from './subscriptions.js';
+export { normalizeMempool } from './mempool.js';
+export { probeCapabilities } from './capabilities.js';
+export { safeRequest, fetchBlock, fetchHeadBlockNumber, fetchFeeHistory, fetchTxPool, fetchReceipt, fetchTransaction, zeroHash, } from './transport.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAG/C,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAElD,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AAE/C,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AAErD,OAAO,EACL,WAAW,EACX,UAAU,EACV,oBAAoB,EACpB,eAAe,EACf,WAAW,EACX,YAAY,EACZ,gBAAgB,EAChB,QAAQ,GACT,MAAM,gBAAgB,CAAA"}

package/dist/mempool.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Mempool normalization. The single transformation pass that takes a
+ * `txpool_content` response into a canonical `NormalizedMempool` whose
+ * outer keys (sender address, nonce) are predictable.
+ *
+ * Why normalize once at ingest, not on every lookup?
+ *
+ *   - Upstream clients are inconsistent about address case (geth /
+ *     reth use EIP-55 mixed case, others lowercase, some checksum
+ *     only some hex chars).
+ *   - Nonce is also inconsistent — some clients hex-encode (`'0x5'`),
+ *     some decimal-encode (`'5'`).
+ *   - A consumer doing direct `pool.pending[address][nonce]` lookups
+ *     would need a case-fold + format-fold fallback walk on every
+ *     access. That's both slow and a class of latent bugs (forget
+ *     the fallback, miss a hit).
+ *
+ * Normalize once at the source's ingest point, then every lookup is
+ * an O(1) two-key access against keys whose form is known. The
+ * `NormalizedMempool` type alias signals the invariant.
+ */
+import type { NormalizedMempool, TxPoolContent } from './types.js';
+/**
+ * Run the upstream `txpool_content` payload through one normalization
+ * pass: every sender address key is lowercased, every nonce key is
+ * coerced to its canonical decimal form. The inner `RawTx` values
+ * are passed through by reference unchanged — pool normalization is
+ * for the OUTER keys only; downstream tx-field comparisons (hash,
+ * from, nonce) do their own case-folding.
+ *
+ * Idempotent — re-normalizing a `NormalizedMempool` returns an
+ * equivalent `NormalizedMempool`. Pass `null` / `undefined` to get
+ * empty subpools back; this lets callers store the result without
+ * `null`-checking on every lookup.
+ */
+export declare const normalizeMempool: (pool: TxPoolContent | null | undefined) => NormalizedMempool;
+//# sourceMappingURL=mempool.d.ts.map

package/dist/mempool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mempool.d.ts","sourceRoot":"","sources":["../src/mempool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAS,aAAa,EAAE,MAAM,YAAY,CAAA;AAmBzE;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,gBAAgB,GAC3B,MAAM,aAAa,GAAG,IAAI,GAAG,SAAS,KACrC,iBAGD,CAAA"}

package/dist/mempool.js

@@ -0,0 +1,54 @@
+/**
+ * Mempool normalization. The single transformation pass that takes a
+ * `txpool_content` response into a canonical `NormalizedMempool` whose
+ * outer keys (sender address, nonce) are predictable.
+ *
+ * Why normalize once at ingest, not on every lookup?
+ *
+ *   - Upstream clients are inconsistent about address case (geth /
+ *     reth use EIP-55 mixed case, others lowercase, some checksum
+ *     only some hex chars).
+ *   - Nonce is also inconsistent — some clients hex-encode (`'0x5'`),
+ *     some decimal-encode (`'5'`).
+ *   - A consumer doing direct `pool.pending[address][nonce]` lookups
+ *     would need a case-fold + format-fold fallback walk on every
+ *     access. That's both slow and a class of latent bugs (forget
+ *     the fallback, miss a hit).
+ *
+ * Normalize once at the source's ingest point, then every lookup is
+ * an O(1) two-key access against keys whose form is known. The
+ * `NormalizedMempool` type alias signals the invariant.
+ */
+const normalizeSubpool = (sub) => {
+    if (!sub)
+        return {};
+    const out = {};
+    for (const [address, byNonce] of Object.entries(sub)) {
+        const normalizedByNonce = {};
+        for (const [nonce, tx] of Object.entries(byNonce)) {
+            // BigInt() accepts both '5' and '0x5'; .toString() gives the
+            // canonical decimal form. Idempotent on already-decimal keys.
+            normalizedByNonce[BigInt(nonce).toString()] = tx;
+        }
+        out[address.toLowerCase()] = normalizedByNonce;
+    }
+    return out;
+};
+/**
+ * Run the upstream `txpool_content` payload through one normalization
+ * pass: every sender address key is lowercased, every nonce key is
+ * coerced to its canonical decimal form. The inner `RawTx` values
+ * are passed through by reference unchanged — pool normalization is
+ * for the OUTER keys only; downstream tx-field comparisons (hash,
+ * from, nonce) do their own case-folding.
+ *
+ * Idempotent — re-normalizing a `NormalizedMempool` returns an
+ * equivalent `NormalizedMempool`. Pass `null` / `undefined` to get
+ * empty subpools back; this lets callers store the result without
+ * `null`-checking on every lookup.
+ */
+export const normalizeMempool = (pool) => ({
+    pending: normalizeSubpool(pool?.pending),
+    queued: normalizeSubpool(pool?.queued),
+});
+//# sourceMappingURL=mempool.js.map

package/dist/mempool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mempool.js","sourceRoot":"","sources":["../src/mempool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,MAAM,gBAAgB,GAAG,CACvB,GAAsD,EACf,EAAE;IACzC,IAAI,CAAC,GAAG;QAAE,OAAO,EAAE,CAAA;IACnB,MAAM,GAAG,GAA0C,EAAE,CAAA;IACrD,KAAK,MAAM,CAAC,OAAO,EAAE,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QACrD,MAAM,iBAAiB,GAA0B,EAAE,CAAA;QACnD,KAAK,MAAM,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;YAClD,6DAA6D;YAC7D,8DAA8D;YAC9D,iBAAiB,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,QAAQ,EAAE,CAAC,GAAG,EAAE,CAAA;QAClD,CAAC;QACD,GAAG,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,GAAG,iBAAiB,CAAA;IAChD,CAAC;IACD,OAAO,GAAG,CAAA;AACZ,CAAC,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAC9B,IAAsC,EACnB,EAAE,CAAC,CAAC;IACvB,OAAO,EAAE,gBAAgB,CAAC,IAAI,EAAE,OAAO,CAAC;IACxC,MAAM,EAAE,gBAAgB,CAAC,IAAI,EAAE,MAAM,CAAC;CACvC,CAAC,CAAA"}