@valve-tech/chain-source 0.5.0 → 0.6.0

package/dist/source.d.ts

@@ -0,0 +1,128 @@
+/**
+ * `createChainSource` — the canonical chain-observation primitive
+ * for `@valve-tech/evm-toolkit`. Owns:
+ *
+ *   - the upstream poll cycle (block + mempool fan-out per tick)
+ *   - the per-method capability probe (run eagerly at construction)
+ *   - typed pub/sub for blocks and mempool snapshots, with
+ *     multiple-subscribers-per-stream as a first-class guarantee
+ *   - on-demand RPC passthroughs for individual blocks, fee history,
+ *     receipts, and transactions
+ *
+ * Sibling features (`@valve-tech/gas-oracle`, `@valve-tech/tx-tracker`)
+ * consume `ChainSource` and never re-implement the poll loop. One
+ * upstream RPC cycle, regardless of how many derived views attach.
+ *
+ * Lifecycle (per spec §14.1):
+ *
+ *   - `start()` begins interval-driven polling. Idempotent.
+ *   - `stop()` halts the interval; subscriber registry is preserved
+ *     so a `start() → stop() → start()` resume keeps existing
+ *     subscriptions alive.
+ *   - The capability probe runs eagerly at *construction*, not at
+ *     start(). By the time a consumer calls `capabilities()` after
+ *     any await, the probe has typically landed. For a brief window
+ *     immediately after `createChainSource()`, `capabilities()` returns
+ *     a conservative default (everything `unavailable` / `gated`).
+ *     Callers that need a guaranteed-fresh result can `await
+ *     source.ready()` before reading `capabilities()`.
+ *
+ * Push subscriptions (eth_subscribe) are not yet wired in v0.3.x —
+ * the `Capabilities.newHeads` / `newPendingTransactions` fields
+ * disclose what *would* be available structurally, but the source
+ * always falls back to its interval poll cycle in this revision.
+ * Future revisions add WS push without changing the consumer-facing
+ * `subscribeBlocks` / `subscribeMempool` shape.
+ */
+import type { PublicClient } from 'viem';
+import type { BlockResult, Capabilities, FeeHistoryResult, NormalizedMempool, PollOptions, RawTx, TransactionReceipt } from './types.js';
+export interface CreateChainSourceOptions {
+    /** viem PublicClient pointed at the upstream RPC. */
+    client: PublicClient;
+    /**
+     * Polling interval in ms when push subscriptions aren't available
+     * (or aren't preferred). Default 10_000.
+     */
+    pollIntervalMs?: number;
+    /**
+     * Producer-side toggles: which RPCs the source's tick fans out.
+     * Disabling `mempool` here disables `subscribeMempool` for every
+     * consumer; the source-level toggle is the single source of truth.
+     * `feeHistory` is currently informational — the source's tick does
+     * not fan out fee history; consumers fetch it on demand via
+     * `getFeeHistory`. The toggle is reserved for forward-compatibility.
+     */
+    poll?: PollOptions;
+    /**
+     * Optional error sink — called per-method when an RPC fails. Same
+     * role as on `createGasOracle`. Failures are otherwise swallowed
+     * (the source keeps running on partial data).
+     */
+    onError?: (method: string, err: unknown) => void;
+}
+export interface ChainSource {
+    /** Begin the poll loop. Idempotent. */
+    start: () => void;
+    /** Halt the poll loop. Subscribers preserved across stop/start. Idempotent. */
+    stop: () => void;
+    /**
+     * Run one poll cycle out-of-band. Useful for tests, manual
+     * refreshes, and serverless contexts where the interval timer
+     * isn't appropriate. Fans out to subscribers identically to a
+     * timer-driven tick.
+     *
+     * Additive over the design contract — the spec exposes only
+     * subscribe + on-demand methods, but pollOnce is a natural
+     * symmetric helper that keeps the test surface honest without
+     * depending on fake timers.
+     */
+    pollOnce: () => Promise<void>;
+    /**
+     * Resolve when the eager capability probe (kicked off at
+     * construction) has completed. After this resolves, `capabilities()`
+     * returns the real probed values rather than the conservative
+     * default.
+     */
+    ready: () => Promise<void>;
+    /** Subscribe to new-block events. Multiple subscribers allowed. */
+    subscribeBlocks: (cb: (block: BlockResult) => void) => () => void;
+    /** Subscribe to mempool snapshots. Multiple subscribers allowed. */
+    subscribeMempool: (cb: (snapshot: NormalizedMempool) => void) => () => void;
+    /** On-demand: fetch a single block (full transactions). */
+    getBlock: (tag: 'latest' | bigint) => Promise<BlockResult | null>;
+    /** On-demand: fee history. */
+    getFeeHistory: (blockCount: number, percentiles: number[]) => Promise<FeeHistoryResult | null>;
+    /**
+     * On-demand: fresh `txpool_content` snapshot, normalized. Returns
+     * `null` when the upstream gates the method. For continuous access,
+     * prefer `subscribeMempool` — that path reuses the source's poll
+     * cycle and avoids a fresh RPC per call.
+     */
+    getMempoolSnapshot: () => Promise<NormalizedMempool | null>;
+    /** On-demand: receipt by tx hash. */
+    getReceipt: (hash: string) => Promise<TransactionReceipt | null>;
+    /** On-demand: tx by hash (used by tx-tracker for replacement detection). */
+    getTransaction: (hash: string) => Promise<RawTx | null>;
+    /** Latest probed capability snapshot. */
+    capabilities: () => Capabilities;
+}
+/**
+ * Build a configured chain-source. The eager capability probe starts
+ * immediately; nothing else happens until `start()` is called.
+ *
+ * @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('new block', block.number))
+ *   source.start()
+ *
+ *   // ... later
+ *   source.stop()
+ */
+export declare const createChainSource: (options: CreateChainSourceOptions) => ChainSource;
+//# sourceMappingURL=source.d.ts.map

package/dist/source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source.d.ts","sourceRoot":"","sources":["../src/source.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,MAAM,CAAA;AAaxC,OAAO,KAAK,EACV,WAAW,EACX,YAAY,EACZ,gBAAgB,EAChB,iBAAiB,EACjB,WAAW,EACX,KAAK,EACL,kBAAkB,EACnB,MAAM,YAAY,CAAA;AAoBnB,MAAM,WAAW,wBAAwB;IACvC,qDAAqD;IACrD,MAAM,EAAE,YAAY,CAAA;IACpB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE,WAAW,CAAA;IAClB;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,KAAK,IAAI,CAAA;CACjD;AAED,MAAM,WAAW,WAAW;IAC1B,uCAAuC;IACvC,KAAK,EAAE,MAAM,IAAI,CAAA;IACjB,+EAA+E;IAC/E,IAAI,EAAE,MAAM,IAAI,CAAA;IAChB;;;;;;;;;;OAUG;IACH,QAAQ,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IAC7B;;;;;OAKG;IACH,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IAC1B,mEAAmE;IACnE,eAAe,EAAE,CAAC,EAAE,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,KAAK,MAAM,IAAI,CAAA;IACjE,oEAAoE;IACpE,gBAAgB,EAAE,CAAC,EAAE,EAAE,CAAC,QAAQ,EAAE,iBAAiB,KAAK,IAAI,KAAK,MAAM,IAAI,CAAA;IAC3E,2DAA2D;IAC3D,QAAQ,EAAE,CAAC,GAAG,EAAE,QAAQ,GAAG,MAAM,KAAK,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAA;IACjE,8BAA8B;IAC9B,aAAa,EAAE,CACb,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EAAE,KAClB,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAA;IACrC;;;;;OAKG;IACH,kBAAkB,EAAE,MAAM,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAAA;IAC3D,qCAAqC;IACrC,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAAA;IAChE,4EAA4E;IAC5E,cAAc,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC,CAAA;IACvD,yCAAyC;IACzC,YAAY,EAAE,MAAM,YAAY,CAAA;CACjC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,iBAAiB,GAC5B,SAAS,wBAAwB,KAChC,WAsJF,CAAA"}

package/dist/source.js

@@ -0,0 +1,198 @@
+/**
+ * `createChainSource` — the canonical chain-observation primitive
+ * for `@valve-tech/evm-toolkit`. Owns:
+ *
+ *   - the upstream poll cycle (block + mempool fan-out per tick)
+ *   - the per-method capability probe (run eagerly at construction)
+ *   - typed pub/sub for blocks and mempool snapshots, with
+ *     multiple-subscribers-per-stream as a first-class guarantee
+ *   - on-demand RPC passthroughs for individual blocks, fee history,
+ *     receipts, and transactions
+ *
+ * Sibling features (`@valve-tech/gas-oracle`, `@valve-tech/tx-tracker`)
+ * consume `ChainSource` and never re-implement the poll loop. One
+ * upstream RPC cycle, regardless of how many derived views attach.
+ *
+ * Lifecycle (per spec §14.1):
+ *
+ *   - `start()` begins interval-driven polling. Idempotent.
+ *   - `stop()` halts the interval; subscriber registry is preserved
+ *     so a `start() → stop() → start()` resume keeps existing
+ *     subscriptions alive.
+ *   - The capability probe runs eagerly at *construction*, not at
+ *     start(). By the time a consumer calls `capabilities()` after
+ *     any await, the probe has typically landed. For a brief window
+ *     immediately after `createChainSource()`, `capabilities()` returns
+ *     a conservative default (everything `unavailable` / `gated`).
+ *     Callers that need a guaranteed-fresh result can `await
+ *     source.ready()` before reading `capabilities()`.
+ *
+ * Push subscriptions (eth_subscribe) are not yet wired in v0.3.x —
+ * the `Capabilities.newHeads` / `newPendingTransactions` fields
+ * disclose what *would* be available structurally, but the source
+ * always falls back to its interval poll cycle in this revision.
+ * Future revisions add WS push without changing the consumer-facing
+ * `subscribeBlocks` / `subscribeMempool` shape.
+ */
+import { probeCapabilities } from './capabilities.js';
+import { normalizeMempool } from './mempool.js';
+import { Subscriptions } from './subscriptions.js';
+import { fetchBlock, fetchFeeHistory, fetchHeadBlockNumber, fetchReceipt, fetchTransaction, fetchTxPool, } from './transport.js';
+const DEFAULT_POLL_INTERVAL_MS = 10000;
+/**
+ * Conservative capability default returned by `capabilities()` before
+ * the eager probe completes. Every signal is treated as unavailable
+ * until proven otherwise — consumers reading capabilities in this
+ * window get the safest answer (no path is available, fall back to
+ * the most defensive flow). Once the probe lands, real values
+ * overwrite this.
+ */
+const PROBING_DEFAULT = {
+    newHeads: 'unavailable',
+    newPendingTransactions: 'unavailable',
+    txpoolContent: 'gated',
+    receiptByHash: 'unavailable',
+    reprobeOnReconnect: false,
+};
+/**
+ * Build a configured chain-source. The eager capability probe starts
+ * immediately; nothing else happens until `start()` is called.
+ *
+ * @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('new block', block.number))
+ *   source.start()
+ *
+ *   // ... later
+ *   source.stop()
+ */
+export const createChainSource = (options) => {
+    const pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    const fetchMempool = options.poll?.mempool !== false;
+    const blockSubs = new Subscriptions();
+    const mempoolSubs = new Subscriptions();
+    let timer = null;
+    let started = false;
+    let cachedCapabilities = PROBING_DEFAULT;
+    // Dedup key for the block stream — by hash, not number, so that a
+    // same-height reorg (different hash, same number) still surfaces as
+    // a fresh observation. Reset on stop() so a paused-then-resumed
+    // source emits a current snapshot to its consumers rather than
+    // waiting for the next chain block. Typed `string | undefined` to
+    // match `BlockResult.hash`'s optionality (real upstream blocks
+    // always carry a hash; the type stays permissive for test fixtures).
+    let lastEmittedBlockHash;
+    // Head-probe gate state — last `eth_blockNumber`-confirmed head we
+    // actually fetched a full block for. Lets the tick skip
+    // `eth_getBlockByNumber('latest', true)` (1–5MB on busy chains)
+    // when the head hasn't moved. Same lifecycle as the dedup hash —
+    // reset on stop() so a paused-then-resumed source defensively
+    // re-fetches even at the same height.
+    let lastSeenBlockNumber;
+    const errSink = (method) => options.onError ? (err) => options.onError(method, err) : undefined;
+    // Eager capability probe. Fire-and-forget; consumers that need a
+    // guaranteed-completed probe await source.ready().
+    const readyPromise = probeCapabilities(options.client, {
+        onError: options.onError,
+    }).then((caps) => {
+        cachedCapabilities = caps;
+    });
+    // One poll cycle. Cheap `eth_blockNumber` probe + (optionally)
+    // mempool fetch in parallel; if the probe shows the head has
+    // advanced (or the probe failed and we're falling through
+    // defensively), follow up with the expensive full-block fetch.
+    // Mempool emits every successful cycle; blocks emit only when the
+    // observed hash changes.
+    const tick = async () => {
+        const [head, txPool] = await Promise.all([
+            fetchHeadBlockNumber(options.client, errSink('eth_blockNumber')),
+            fetchMempool
+                ? fetchTxPool(options.client, errSink('txpool_content'))
+                : Promise.resolve(null),
+        ]);
+        // Head-probe gate: skip the full-block fetch when the probe says
+        // the head hasn't moved since we last observed it. A null probe
+        // (RPC method gated, transport error) falls through to fetch —
+        // we'd rather pay one extra block fetch than block on a flaky
+        // upstream that can't even report `eth_blockNumber`.
+        const headChanged = head === null ||
+            lastSeenBlockNumber === undefined ||
+            head !== lastSeenBlockNumber;
+        const block = headChanged
+            ? await fetchBlock(options.client, 'latest', errSink('eth_getBlockByNumber'))
+            : null;
+        if (block) {
+            // Update the gate state from the actually-fetched block, not
+            // from the probe's number — keeps the gate consistent with
+            // what consumers observed.
+            try {
+                lastSeenBlockNumber = BigInt(block.number);
+            }
+            catch {
+                // Block number didn't decode — leave gate state untouched so
+                // we re-fetch on the next tick rather than persist garbage.
+            }
+            if (block.hash !== lastEmittedBlockHash) {
+                lastEmittedBlockHash = block.hash;
+                blockSubs.emit(block);
+            }
+        }
+        // Mempool is intentionally not deduped — txs come and go between
+        // blocks even on a static head, so every successful snapshot is
+        // fresh data. Only the block stream dedups.
+        if (txPool && fetchMempool) {
+            mempoolSubs.emit(normalizeMempool(txPool));
+        }
+    };
+    return {
+        start: () => {
+            if (started)
+                return;
+            started = true;
+            // Fire the first tick immediately so consumers don't wait one
+            // full interval for their first event. The interval timer
+            // takes over from there.
+            void tick();
+            timer = setInterval(() => {
+                void tick();
+            }, pollIntervalMs);
+        },
+        stop: () => {
+            if (timer !== null) {
+                clearInterval(timer);
+                timer = null;
+            }
+            started = false;
+            // Subscriber registry is intentionally preserved across stop —
+            // a start/stop/start pattern keeps existing subscriptions
+            // alive, matching the gas-oracle convention. Block-dedup +
+            // head-probe-gate state ARE reset though: a consumer that
+            // paused and resumed should get a current snapshot on first
+            // re-tick rather than wait for the next chain block, and the
+            // gate must defensively re-fetch in case the chain advanced
+            // (or reorged) during the pause.
+            lastEmittedBlockHash = undefined;
+            lastSeenBlockNumber = undefined;
+        },
+        pollOnce: () => tick(),
+        ready: () => readyPromise,
+        subscribeBlocks: (cb) => blockSubs.subscribe(cb),
+        subscribeMempool: (cb) => mempoolSubs.subscribe(cb),
+        getBlock: (tag) => fetchBlock(options.client, tag, errSink('eth_getBlockByNumber')),
+        getFeeHistory: (blockCount, percentiles) => fetchFeeHistory(options.client, blockCount, percentiles, errSink('eth_feeHistory')),
+        getMempoolSnapshot: async () => {
+            const txPool = await fetchTxPool(options.client, errSink('txpool_content'));
+            return txPool ? normalizeMempool(txPool) : null;
+        },
+        getReceipt: (hash) => fetchReceipt(options.client, hash, errSink('eth_getTransactionReceipt')),
+        getTransaction: (hash) => fetchTransaction(options.client, hash, errSink('eth_getTransactionByHash')),
+        capabilities: () => cachedCapabilities,
+    };
+};
+//# sourceMappingURL=source.js.map

package/dist/source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"source.js","sourceRoot":"","sources":["../src/source.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAIH,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AACrD,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAClD,OAAO,EACL,UAAU,EACV,eAAe,EACf,oBAAoB,EACpB,YAAY,EACZ,gBAAgB,EAChB,WAAW,GACZ,MAAM,gBAAgB,CAAA;AAWvB,MAAM,wBAAwB,GAAG,KAAM,CAAA;AAEvC;;;;;;;GAOG;AACH,MAAM,eAAe,GAAiB;IACpC,QAAQ,EAAE,aAAa;IACvB,sBAAsB,EAAE,aAAa;IACrC,aAAa,EAAE,OAAO;IACtB,aAAa,EAAE,aAAa;IAC5B,kBAAkB,EAAE,KAAK;CAC1B,CAAA;AA6ED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAC/B,OAAiC,EACpB,EAAE;IACf,MAAM,cAAc,GAAG,OAAO,CAAC,cAAc,IAAI,wBAAwB,CAAA;IACzE,MAAM,YAAY,GAAG,OAAO,CAAC,IAAI,EAAE,OAAO,KAAK,KAAK,CAAA;IAEpD,MAAM,SAAS,GAAG,IAAI,aAAa,EAAe,CAAA;IAClD,MAAM,WAAW,GAAG,IAAI,aAAa,EAAqB,CAAA;IAE1D,IAAI,KAAK,GAA0C,IAAI,CAAA;IACvD,IAAI,OAAO,GAAG,KAAK,CAAA;IACnB,IAAI,kBAAkB,GAAiB,eAAe,CAAA;IACtD,kEAAkE;IAClE,oEAAoE;IACpE,gEAAgE;IAChE,+DAA+D;IAC/D,kEAAkE;IAClE,+DAA+D;IAC/D,qEAAqE;IACrE,IAAI,oBAAwC,CAAA;IAC5C,mEAAmE;IACnE,wDAAwD;IACxD,gEAAgE;IAChE,iEAAiE;IACjE,8DAA8D;IAC9D,sCAAsC;IACtC,IAAI,mBAAuC,CAAA;IAE3C,MAAM,OAAO,GAAG,CAAC,MAAc,EAAE,EAAE,CACjC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,GAAY,EAAE,EAAE,CAAC,OAAO,CAAC,OAAQ,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAA;IAE/E,iEAAiE;IACjE,mDAAmD;IACnD,MAAM,YAAY,GAAkB,iBAAiB,CAAC,OAAO,CAAC,MAAM,EAAE;QACpE,OAAO,EAAE,OAAO,CAAC,OAAO;KACzB,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE;QACf,kBAAkB,GAAG,IAAI,CAAA;IAC3B,CAAC,CAAC,CAAA;IAEF,+DAA+D;IAC/D,6DAA6D;IAC7D,0DAA0D;IAC1D,+DAA+D;IAC/D,kEAAkE;IAClE,yBAAyB;IACzB,MAAM,IAAI,GAAG,KAAK,IAAmB,EAAE;QACrC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;YACvC,oBAAoB,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,iBAAiB,CAAC,CAAC;YAChE,YAAY;gBACV,CAAC,CAAC,WAAW,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,gBAAgB,CAAC,CAAC;gBACxD,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC;SAC1B,CAAC,CAAA;QAEF,iEAAiE;QACjE,gEAAgE;QAChE,+DAA+D;QAC/D,8DAA8D;QAC9D,qDAAqD;QACrD,MAAM,WAAW,GACf,IAAI,KAAK,IAAI;YACb,mBAAmB,KAAK,SAAS;YACjC,IAAI,KAAK,mBAAmB,CAAA;QAC9B,MAAM,KAAK,GAAG,WAAW;YACvB,CAAC,CAAC,MAAM,UAAU,CAAC,OAAO,CAAC,MAAM,EAAE,QAAQ,EAAE,OAAO,CAAC,sBAAsB,CAAC,CAAC;YAC7E,CAAC,CAAC,IAAI,CAAA;QAER,IAAI,KAAK,EAAE,CAAC;YACV,6DAA6D;YAC7D,2DAA2D;YAC3D,2BAA2B;YAC3B,IAAI,CAAC;gBACH,mBAAmB,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAA;YAC5C,CAAC;YAAC,MAAM,CAAC;gBACP,6DAA6D;gBAC7D,4DAA4D;YAC9D,CAAC;YACD,IAAI,KAAK,CAAC,IAAI,KAAK,oBAAoB,EAAE,CAAC;gBACxC,oBAAoB,GAAG,KAAK,CAAC,IAAI,CAAA;gBACjC,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;YACvB,CAAC;QACH,CAAC;QACD,iEAAiE;QACjE,gEAAgE;QAChE,4CAA4C;QAC5C,IAAI,MAAM,IAAI,YAAY,EAAE,CAAC;YAC3B,WAAW,CAAC,IAAI,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC,CAAA;QAC5C,CAAC;IACH,CAAC,CAAA;IAED,OAAO;QACL,KAAK,EAAE,GAAG,EAAE;YACV,IAAI,OAAO;gBAAE,OAAM;YACnB,OAAO,GAAG,IAAI,CAAA;YACd,8DAA8D;YAC9D,0DAA0D;YAC1D,yBAAyB;YACzB,KAAK,IAAI,EAAE,CAAA;YACX,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE;gBACvB,KAAK,IAAI,EAAE,CAAA;YACb,CAAC,EAAE,cAAc,CAAC,CAAA;QACpB,CAAC;QAED,IAAI,EAAE,GAAG,EAAE;YACT,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;gBACnB,aAAa,CAAC,KAAK,CAAC,CAAA;gBACpB,KAAK,GAAG,IAAI,CAAA;YACd,CAAC;YACD,OAAO,GAAG,KAAK,CAAA;YACf,+DAA+D;YAC/D,0DAA0D;YAC1D,2DAA2D;YAC3D,0DAA0D;YAC1D,4DAA4D;YAC5D,6DAA6D;YAC7D,4DAA4D;YAC5D,iCAAiC;YACjC,oBAAoB,GAAG,SAAS,CAAA;YAChC,mBAAmB,GAAG,SAAS,CAAA;QACjC,CAAC;QAED,QAAQ,EAAE,GAAG,EAAE,CAAC,IAAI,EAAE;QAEtB,KAAK,EAAE,GAAG,EAAE,CAAC,YAAY;QAEzB,eAAe,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,SAAS,CAAC,SAAS,CAAC,EAAE,CAAC;QAEhD,gBAAgB,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,WAAW,CAAC,SAAS,CAAC,EAAE,CAAC;QAEnD,QAAQ,EAAE,CAAC,GAAG,EAAE,EAAE,CAChB,UAAU,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,EAAE,OAAO,CAAC,sBAAsB,CAAC,CAAC;QAElE,aAAa,EAAE,CAAC,UAAU,EAAE,WAAW,EAAE,EAAE,CACzC,eAAe,CACb,OAAO,CAAC,MAAM,EACd,UAAU,EACV,WAAW,EACX,OAAO,CAAC,gBAAgB,CAAC,CAC1B;QAEH,kBAAkB,EAAE,KAAK,IAAI,EAAE;YAC7B,MAAM,MAAM,GAAG,MAAM,WAAW,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAA;YAC3E,OAAO,MAAM,CAAC,CAAC,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAA;QACjD,CAAC;QAED,UAAU,EAAE,CAAC,IAAI,EAAE,EAAE,CACnB,YAAY,CAAC,OAAO,CAAC,MAAM,EAAE,IAAI,EAAE,OAAO,CAAC,2BAA2B,CAAC,CAAC;QAE1E,cAAc,EAAE,CAAC,IAAI,EAAE,EAAE,CACvB,gBAAgB,CAAC,OAAO,CAAC,MAAM,EAAE,IAAI,EAAE,OAAO,CAAC,0BAA0B,CAAC,CAAC;QAE7E,YAAY,EAAE,GAAG,EAAE,CAAC,kBAAkB;KACvC,CAAA;AACH,CAAC,CAAA"}

package/dist/subscriptions.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Hand-rolled typed pub/sub primitive. Browser/mobile-safe — does **not**
+ * import Node's `events` module, which would tie this package to a Node
+ * runtime and break browser / React Native / edge bundles. The primitive
+ * is small enough that the size cost is negligible compared to the
+ * portability win.
+ *
+ * Posture matches `oracle.subscribe` in `@valve-tech/gas-oracle`:
+ *
+ * - Per-subscriber throws are **swallowed**. A bad consumer cannot take
+ *   down the others — emit always reaches every subscriber that was
+ *   registered when the emit started.
+ * - The set fanned out for an `emit` call is the snapshot taken at the
+ *   start of the call. Subscribers added during the in-flight emit are
+ *   ignored for that emit and join the set for the next one. This is
+ *   the only safe iteration order — mutating the underlying set
+ *   mid-iteration would require defensive cloning that is more
+ *   expensive than always cloning once.
+ * - Unsubscribe handles are idempotent: calling the returned unsub
+ *   function twice is a no-op the second time.
+ * - Re-subscribing the same callback reference is a no-op (the backing
+ *   set deduplicates by reference). Callers that want "deliver twice"
+ *   register two distinct closures.
+ */
+export declare class Subscriptions<E> {
+    private subscribers;
+    /**
+     * Deliver `event` to every subscriber registered at the moment this
+     * call started. Per-subscriber throws are swallowed; a single bad
+     * consumer cannot affect delivery to the others.
+     */
+    emit(event: E): void;
+    /**
+     * Register `cb` for future emits. Returns an idempotent unsubscribe
+     * function — calling it once removes the callback; calling it again
+     * is a no-op.
+     */
+    subscribe(cb: (event: E) => void): () => void;
+    /** Number of currently-registered subscribers. */
+    size(): number;
+}
+//# sourceMappingURL=subscriptions.d.ts.map

package/dist/subscriptions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscriptions.d.ts","sourceRoot":"","sources":["../src/subscriptions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,aAAa,CAAC,CAAC;IAC1B,OAAO,CAAC,WAAW,CAAgC;IAEnD;;;;OAIG;IACH,IAAI,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI;IAgBpB;;;;OAIG;IACH,SAAS,CAAC,EAAE,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,GAAG,MAAM,IAAI;IAO7C,kDAAkD;IAClD,IAAI,IAAI,MAAM;CAGf"}

package/dist/subscriptions.js

@@ -0,0 +1,66 @@
+/**
+ * Hand-rolled typed pub/sub primitive. Browser/mobile-safe — does **not**
+ * import Node's `events` module, which would tie this package to a Node
+ * runtime and break browser / React Native / edge bundles. The primitive
+ * is small enough that the size cost is negligible compared to the
+ * portability win.
+ *
+ * Posture matches `oracle.subscribe` in `@valve-tech/gas-oracle`:
+ *
+ * - Per-subscriber throws are **swallowed**. A bad consumer cannot take
+ *   down the others — emit always reaches every subscriber that was
+ *   registered when the emit started.
+ * - The set fanned out for an `emit` call is the snapshot taken at the
+ *   start of the call. Subscribers added during the in-flight emit are
+ *   ignored for that emit and join the set for the next one. This is
+ *   the only safe iteration order — mutating the underlying set
+ *   mid-iteration would require defensive cloning that is more
+ *   expensive than always cloning once.
+ * - Unsubscribe handles are idempotent: calling the returned unsub
+ *   function twice is a no-op the second time.
+ * - Re-subscribing the same callback reference is a no-op (the backing
+ *   set deduplicates by reference). Callers that want "deliver twice"
+ *   register two distinct closures.
+ */
+export class Subscriptions {
+    constructor() {
+        this.subscribers = new Set();
+    }
+    /**
+     * Deliver `event` to every subscriber registered at the moment this
+     * call started. Per-subscriber throws are swallowed; a single bad
+     * consumer cannot affect delivery to the others.
+     */
+    emit(event) {
+        // Snapshot before iteration so a subscriber can't mutate the
+        // delivery set mid-fanout (e.g. by subscribing a new callback or
+        // unsubscribing a later one). The cost is one Set copy per emit;
+        // the alternative (iterating the live set) silently changes
+        // delivery semantics in subtle ways.
+        const snapshot = Array.from(this.subscribers);
+        for (const cb of snapshot) {
+            try {
+                cb(event);
+            }
+            catch {
+                /* swallow per-subscriber errors */
+            }
+        }
+    }
+    /**
+     * Register `cb` for future emits. Returns an idempotent unsubscribe
+     * function — calling it once removes the callback; calling it again
+     * is a no-op.
+     */
+    subscribe(cb) {
+        this.subscribers.add(cb);
+        return () => {
+            this.subscribers.delete(cb);
+        };
+    }
+    /** Number of currently-registered subscribers. */
+    size() {
+        return this.subscribers.size;
+    }
+}
+//# sourceMappingURL=subscriptions.js.map

package/dist/subscriptions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscriptions.js","sourceRoot":"","sources":["../src/subscriptions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,OAAO,aAAa;IAA1B;QACU,gBAAW,GAAG,IAAI,GAAG,EAAsB,CAAA;IAuCrD,CAAC;IArCC;;;;OAIG;IACH,IAAI,CAAC,KAAQ;QACX,6DAA6D;QAC7D,iEAAiE;QACjE,iEAAiE;QACjE,4DAA4D;QAC5D,qCAAqC;QACrC,MAAM,QAAQ,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,CAAA;QAC7C,KAAK,MAAM,EAAE,IAAI,QAAQ,EAAE,CAAC;YAC1B,IAAI,CAAC;gBACH,EAAE,CAAC,KAAK,CAAC,CAAA;YACX,CAAC;YAAC,MAAM,CAAC;gBACP,mCAAmC;YACrC,CAAC;QACH,CAAC;IACH,CAAC;IAED;;;;OAIG;IACH,SAAS,CAAC,EAAsB;QAC9B,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC,CAAA;QACxB,OAAO,GAAG,EAAE;YACV,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,EAAE,CAAC,CAAA;QAC7B,CAAC,CAAA;IACH,CAAC;IAED,kDAAkD;IAClD,IAAI;QACF,OAAO,IAAI,CAAC,WAAW,CAAC,IAAI,CAAA;IAC9B,CAAC;CACF"}

package/dist/transport.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Low-level RPC fan-out for `@valve-tech/chain-source`. One thin
+ * wrapper per JSON-RPC method the source needs:
+ *
+ *   - `eth_blockNumber`        — cheap head probe (block-gating).
+ *   - `eth_getBlockByNumber`   — full block (header + txs).
+ *   - `eth_feeHistory`         — base-fee history + percentile rewards.
+ *   - `txpool_content`         — pending + queued mempool snapshot.
+ *   - `eth_getTransactionReceipt` — inclusion-watch fallback.
+ *   - `eth_getTransactionByHash`  — replacement detection (from, nonce).
+ *
+ * Each wrapper uses the same `safeRequest` posture: turn errors,
+ * `null`, and `undefined` upstream responses into a `null` return —
+ * never throw across this layer. The higher-level source module
+ * decides what each `null` means (capability gated, transient
+ * upstream failure, no such tx).
+ *
+ * Why not viem's typed methods? Two reasons:
+ *
+ *   1. `txpool_content` is non-standard, so we'd be reaching for
+ *      `client.request` for it anyway. Doing every method through
+ *      the same shape keeps call sites symmetric.
+ *   2. Some fields of interest (`excessBlobGas`, `blobGasUsed`,
+ *      `parentHash`) are surfaced inconsistently across viem versions
+ *      in the typed `getBlock` shape. Going straight through
+ *      `client.request` gives us the wire response untouched and the
+ *      types we declare here describe exactly what we actually use.
+ */
+import type { PublicClient } from 'viem';
+import type { BlockResult, FeeHistoryResult, RawTx, TransactionReceipt, TxPoolContent } from './types.js';
+/** Canonical 32-byte zero hash. Used for the receipt-by-hash probe. */
+export declare const zeroHash: string;
+/**
+ * Issue an arbitrary JSON-RPC method through the client. A single
+ * failure (method-not-found, transport error, malformed response)
+ * becomes `null` rather than a thrown exception — the caller decides
+ * what each missing-data case means. This is the load-bearing
+ * convention for capability-gated methods like `txpool_content`.
+ */
+export declare const safeRequest: <T>(client: PublicClient, method: string, params: unknown[], onError?: (err: unknown) => void) => Promise<T | null>;
+/**
+ * Fetch the latest head block number as a `bigint`. Used by the
+ * source's block-gating optimization: when the head hasn't moved
+ * since the previous tick, the expensive cycle (full block + fee
+ * history + mempool) is skipped because no fee landscape change is
+ * possible without a new block.
+ *
+ * Returns `null` if the upstream `eth_blockNumber` fails or returns
+ * something that won't decode as a bigint.
+ */
+export declare const fetchHeadBlockNumber: (client: PublicClient, onError?: (err: unknown) => void) => Promise<bigint | null>;
+/**
+ * Fetch a block (full transactions). `tag` may be `'latest'` or an
+ * absolute block number as a `bigint`; the bigint is hex-encoded
+ * before the RPC call. Returns the raw `BlockResult` (hex-encoded
+ * numeric fields untouched) or `null` if the upstream failed.
+ */
+export declare const fetchBlock: (client: PublicClient, tag: "latest" | bigint, onError?: (err: unknown) => void) => Promise<BlockResult | null>;
+/**
+ * Fetch fee history. `blockCount` is hex-encoded per the spec; the
+ * latest block is the implicit upper bound. `percentiles` is passed
+ * through unchanged (RPC accepts a JSON number array).
+ */
+export declare const fetchFeeHistory: (client: PublicClient, blockCount: number, percentiles: number[], onError?: (err: unknown) => void) => Promise<FeeHistoryResult | null>;
+/**
+ * Fetch a `txpool_content` snapshot. `null` is the expected return
+ * when the provider gates the method (most public RPCs do). The
+ * source surfaces this via `capabilities().txpoolContent === 'gated'`
+ * so consumers can react.
+ */
+export declare const fetchTxPool: (client: PublicClient, onError?: (err: unknown) => void) => Promise<TxPoolContent | null>;
+/**
+ * Fetch a transaction receipt by hash. `null` covers both "no such
+ * tx" and "method not available." Distinguish the two via
+ * `capabilities().receiptByHash`.
+ */
+export declare const fetchReceipt: (client: PublicClient, hash: string, onError?: (err: unknown) => void) => Promise<TransactionReceipt | null>;
+/**
+ * Fetch a transaction by hash. Used by downstream tx-tracker for
+ * replacement detection (looks up the (from, nonce) pair so the
+ * tracker can detect a different hash with the same nonce mining).
+ */
+export declare const fetchTransaction: (client: PublicClient, hash: string, onError?: (err: unknown) => void) => Promise<RawTx | null>;
+//# sourceMappingURL=transport.d.ts.map

package/dist/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,MAAM,CAAA;AAExC,OAAO,KAAK,EACV,WAAW,EACX,gBAAgB,EAChB,KAAK,EACL,kBAAkB,EAClB,aAAa,EACd,MAAM,YAAY,CAAA;AAEnB,uEAAuE;AACvE,eAAO,MAAM,QAAQ,QAAyB,CAAA;AAE9C;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,GAAU,CAAC,EACjC,QAAQ,YAAY,EACpB,QAAQ,MAAM,EACd,QAAQ,OAAO,EAAE,EACjB,UAAU,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,KAC/B,OAAO,CAAC,CAAC,GAAG,IAAI,CAWlB,CAAA;AAKD;;;;;;;;;GASG;AACH,eAAO,MAAM,oBAAoB,GAC/B,QAAQ,YAAY,EACpB,UAAU,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,KAC/B,OAAO,CAAC,MAAM,GAAG,IAAI,CAQvB,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,UAAU,GACrB,QAAQ,YAAY,EACpB,KAAK,QAAQ,GAAG,MAAM,EACtB,UAAU,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,KAC/B,OAAO,CAAC,WAAW,GAAG,IAAI,CAM1B,CAAA;AAEH;;;;GAIG;AACH,eAAO,MAAM,eAAe,GAC1B,QAAQ,YAAY,EACpB,YAAY,MAAM,EAClB,aAAa,MAAM,EAAE,EACrB,UAAU,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,KAC/B,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAM/B,CAAA;AAEH;;;;;GAKG;AACH,eAAO,MAAM,WAAW,GACtB,QAAQ,YAAY,EACpB,UAAU,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,KAC/B,OAAO,CAAC,aAAa,GAAG,IAAI,CACoC,CAAA;AAEnE;;;;GAIG;AACH,eAAO,MAAM,YAAY,GACvB,QAAQ,YAAY,EACpB,MAAM,MAAM,EACZ,UAAU,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,KAC/B,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAMjC,CAAA;AAEH;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,GAC3B,QAAQ,YAAY,EACpB,MAAM,MAAM,EACZ,UAAU,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,KAC/B,OAAO,CAAC,KAAK,GAAG,IAAI,CACkD,CAAA"}

package/dist/transport.js

@@ -0,0 +1,106 @@
+/**
+ * Low-level RPC fan-out for `@valve-tech/chain-source`. One thin
+ * wrapper per JSON-RPC method the source needs:
+ *
+ *   - `eth_blockNumber`        — cheap head probe (block-gating).
+ *   - `eth_getBlockByNumber`   — full block (header + txs).
+ *   - `eth_feeHistory`         — base-fee history + percentile rewards.
+ *   - `txpool_content`         — pending + queued mempool snapshot.
+ *   - `eth_getTransactionReceipt` — inclusion-watch fallback.
+ *   - `eth_getTransactionByHash`  — replacement detection (from, nonce).
+ *
+ * Each wrapper uses the same `safeRequest` posture: turn errors,
+ * `null`, and `undefined` upstream responses into a `null` return —
+ * never throw across this layer. The higher-level source module
+ * decides what each `null` means (capability gated, transient
+ * upstream failure, no such tx).
+ *
+ * Why not viem's typed methods? Two reasons:
+ *
+ *   1. `txpool_content` is non-standard, so we'd be reaching for
+ *      `client.request` for it anyway. Doing every method through
+ *      the same shape keeps call sites symmetric.
+ *   2. Some fields of interest (`excessBlobGas`, `blobGasUsed`,
+ *      `parentHash`) are surfaced inconsistently across viem versions
+ *      in the typed `getBlock` shape. Going straight through
+ *      `client.request` gives us the wire response untouched and the
+ *      types we declare here describe exactly what we actually use.
+ */
+/** Canonical 32-byte zero hash. Used for the receipt-by-hash probe. */
+export const zeroHash = `0x${'00'.repeat(32)}`;
+/**
+ * Issue an arbitrary JSON-RPC method through the client. A single
+ * failure (method-not-found, transport error, malformed response)
+ * becomes `null` rather than a thrown exception — the caller decides
+ * what each missing-data case means. This is the load-bearing
+ * convention for capability-gated methods like `txpool_content`.
+ */
+export const safeRequest = async (client, method, params, onError) => {
+    try {
+        // viem's `request` typing is parameterized over a known method
+        // union; for non-standard methods (txpool_content, et al.) we
+        // cast through `as never` to bypass the union narrowing.
+        const result = (await client.request({ method, params }));
+        return result ?? null;
+    }
+    catch (err) {
+        if (onError)
+            onError(err);
+        return null;
+    }
+};
+const blockTagOf = (tag) => tag === 'latest' ? 'latest' : `0x${tag.toString(16)}`;
+/**
+ * Fetch the latest head block number as a `bigint`. Used by the
+ * source's block-gating optimization: when the head hasn't moved
+ * since the previous tick, the expensive cycle (full block + fee
+ * history + mempool) is skipped because no fee landscape change is
+ * possible without a new block.
+ *
+ * Returns `null` if the upstream `eth_blockNumber` fails or returns
+ * something that won't decode as a bigint.
+ */
+export const fetchHeadBlockNumber = async (client, onError) => {
+    const head = await safeRequest(client, 'eth_blockNumber', [], onError);
+    if (head === null)
+        return null;
+    try {
+        return BigInt(head);
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * Fetch a block (full transactions). `tag` may be `'latest'` or an
+ * absolute block number as a `bigint`; the bigint is hex-encoded
+ * before the RPC call. Returns the raw `BlockResult` (hex-encoded
+ * numeric fields untouched) or `null` if the upstream failed.
+ */
+export const fetchBlock = async (client, tag, onError) => safeRequest(client, 'eth_getBlockByNumber', [blockTagOf(tag), true], onError);
+/**
+ * Fetch fee history. `blockCount` is hex-encoded per the spec; the
+ * latest block is the implicit upper bound. `percentiles` is passed
+ * through unchanged (RPC accepts a JSON number array).
+ */
+export const fetchFeeHistory = async (client, blockCount, percentiles, onError) => safeRequest(client, 'eth_feeHistory', [`0x${blockCount.toString(16)}`, 'latest', percentiles], onError);
+/**
+ * Fetch a `txpool_content` snapshot. `null` is the expected return
+ * when the provider gates the method (most public RPCs do). The
+ * source surfaces this via `capabilities().txpoolContent === 'gated'`
+ * so consumers can react.
+ */
+export const fetchTxPool = async (client, onError) => safeRequest(client, 'txpool_content', [], onError);
+/**
+ * Fetch a transaction receipt by hash. `null` covers both "no such
+ * tx" and "method not available." Distinguish the two via
+ * `capabilities().receiptByHash`.
+ */
+export const fetchReceipt = async (client, hash, onError) => safeRequest(client, 'eth_getTransactionReceipt', [hash], onError);
+/**
+ * Fetch a transaction by hash. Used by downstream tx-tracker for
+ * replacement detection (looks up the (from, nonce) pair so the
+ * tracker can detect a different hash with the same nonce mining).
+ */
+export const fetchTransaction = async (client, hash, onError) => safeRequest(client, 'eth_getTransactionByHash', [hash], onError);
+//# sourceMappingURL=transport.js.map