@valve-tech/chain-source 0.5.0 → 0.7.0

package/dist/transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.js","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAYH,uEAAuE;AACvE,MAAM,CAAC,MAAM,QAAQ,GAAG,KAAK,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,CAAA;AAE9C;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,KAAK,EAC9B,MAAoB,EACpB,MAAc,EACd,MAAiB,EACjB,OAAgC,EACb,EAAE;IACrB,IAAI,CAAC;QACH,+DAA+D;QAC/D,8DAA8D;QAC9D,yDAAyD;QACzD,MAAM,MAAM,GAAG,CAAC,MAAM,MAAM,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,EAAW,CAAC,CAAM,CAAA;QACvE,OAAO,MAAM,IAAI,IAAI,CAAA;IACvB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,OAAO;YAAE,OAAO,CAAC,GAAG,CAAC,CAAA;QACzB,OAAO,IAAI,CAAA;IACb,CAAC;AACH,CAAC,CAAA;AAED,MAAM,UAAU,GAAG,CAAC,GAAsB,EAAU,EAAE,CACpD,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAA;AAEvD;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,KAAK,EACvC,MAAoB,EACpB,OAAgC,EACR,EAAE;IAC1B,MAAM,IAAI,GAAG,MAAM,WAAW,CAAS,MAAM,EAAE,iBAAiB,EAAE,EAAE,EAAE,OAAO,CAAC,CAAA;IAC9E,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,IAAI,CAAA;IAC9B,IAAI,CAAC;QACH,OAAO,MAAM,CAAC,IAAI,CAAC,CAAA;IACrB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAA;IACb,CAAC;AACH,CAAC,CAAA;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,KAAK,EAC7B,MAAoB,EACpB,GAAsB,EACtB,OAAgC,EACH,EAAE,CAC/B,WAAW,CACT,MAAM,EACN,sBAAsB,EACtB,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC,EACvB,OAAO,CACR,CAAA;AAEH;;;;GAIG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,KAAK,EAClC,MAAoB,EACpB,UAAkB,EAClB,WAAqB,EACrB,OAAgC,EACE,EAAE,CACpC,WAAW,CACT,MAAM,EACN,gBAAgB,EAChB,CAAC,KAAK,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,EAAE,QAAQ,EAAE,WAAW,CAAC,EACvD,OAAO,CACR,CAAA;AAEH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,KAAK,EAC9B,MAAoB,EACpB,OAAgC,EACD,EAAE,CACjC,WAAW,CAAgB,MAAM,EAAE,gBAAgB,EAAE,EAAE,EAAE,OAAO,CAAC,CAAA;AAEnE;;;;GAIG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,KAAK,EAC/B,MAAoB,EACpB,IAAY,EACZ,OAAgC,EACI,EAAE,CACtC,WAAW,CACT,MAAM,EACN,2BAA2B,EAC3B,CAAC,IAAI,CAAC,EACN,OAAO,CACR,CAAA;AAEH;;;;GAIG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,KAAK,EACnC,MAAoB,EACpB,IAAY,EACZ,OAAgC,EACT,EAAE,CACzB,WAAW,CAAQ,MAAM,EAAE,0BAA0B,EAAE,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC,CAAA"}

package/dist/types.d.ts

@@ -0,0 +1,161 @@
+/**
+ * Canonical wire-shape types for `@valve-tech/chain-source`. Pure data
+ * shapes — no deps, no runtime behavior.
+ *
+ * **Wire format note.** Numeric fields that come from the EVM (block
+ * numbers, gas, fees, timestamps) are kept as `bigint` once decoded.
+ * The boundary types (`BlockResult`, `TxPoolContent`, `FeeHistoryResult`)
+ * keep them as hex strings because that is what `eth_getBlockByNumber`
+ * et al. return — the source decodes at the point of use, then returns
+ * `bigint`-typed objects to consumers (oracle, tracker). `JSON.stringify`
+ * 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.
+ */
+/**
+ * Minimal tx shape extracted from `eth_getBlockByNumber(latest, true)`
+ * or `txpool_content`. Hash, sender (`from`), and `nonce` support
+ * mempool lookups (`findInMempool`-style helpers downstream); fee
+ * fields drive any downstream tip math; other tx fields
+ * (to/value/data/etc.) are not required by the source.
+ *
+ * The three identity fields (`hash`, `from`, `nonce`) are nominally
+ * optional because tests may construct fixtures with only the bits
+ * they exercise. In practice every modern EVM client populates all
+ * three on both `eth_getBlockByNumber(_, true)` and `txpool_content`.
+ */
+export interface RawTx {
+    maxPriorityFeePerGas?: string;
+    maxFeePerGas?: string;
+    gasPrice?: string;
+    gas?: string;
+    type?: string;
+    hash?: string;
+    from?: string;
+    nonce?: string;
+}
+/**
+ * Result shape returned by `eth_feeHistory`. Hex-encoded numbers; the
+ * source decodes at the point of use.
+ */
+export interface FeeHistoryResult {
+    baseFeePerGas: string[];
+    reward?: string[][];
+    gasUsedRatio: number[];
+    oldestBlock: string;
+}
+/**
+ * Result shape returned by `eth_getBlockByNumber` with
+ * `fullTransactions=true`. Hex-encoded numbers; consumers
+ * (oracle, tracker) decode the fields they need.
+ */
+export interface BlockResult {
+    number: string;
+    hash?: string;
+    parentHash?: string;
+    timestamp: string;
+    baseFeePerGas: string;
+    gasLimit: string;
+    gasUsed: string;
+    transactions: RawTx[];
+    excessBlobGas?: string;
+    blobGasUsed?: string;
+}
+/**
+ * Result shape returned by `txpool_content`. Two-level map: sender
+ * address → nonce → RawTx, split into `pending` (next-in-line) and
+ * `queued` (gap txs that can't mine yet).
+ *
+ * Upstream clients are inconsistent about address case (geth/reth use
+ * EIP-55 checksum; some clients lowercase) and nonce encoding (hex vs
+ * decimal). Pass through `normalizeMempool` once at ingest to get a
+ * canonical `NormalizedMempool` (lowercase addresses, decimal nonces);
+ * lookup helpers expect that form.
+ */
+export interface TxPoolContent {
+    pending: Record<string, Record<string, RawTx>>;
+    queued: Record<string, Record<string, RawTx>>;
+}
+/**
+ * `TxPoolContent` after a single normalization pass — every sender
+ * address key is lowercase ASCII, every nonce key is a decimal string.
+ * Structural alias of `TxPoolContent`; the type name signals the
+ * invariant to downstream lookup helpers.
+ */
+export type NormalizedMempool = TxPoolContent;
+/**
+ * Single full-block fetch shape. viem's `getTransactionReceipt` returns
+ * a richer object than this minimal type captures; consumers cast as
+ * needed. Source-level shape is loose because `txpool_content` /
+ * receipts vary slightly across clients and we don't want a strict
+ * shape rejecting a working response.
+ */
+export interface TransactionReceipt {
+    transactionHash: string;
+    blockHash: string;
+    blockNumber: string;
+    status?: string;
+    [key: string]: unknown;
+}
+/**
+ * Producer-side toggles: which RPCs the source's poll loop fans out
+ * each cycle. Fields default to `true`. `eth_getBlockByNumber` is
+ * intentionally not toggleable — without a block neither downstream
+ * consumer can do anything.
+ *
+ * - `feeHistory: false` — drops `eth_feeHistory`. Downstream consumers
+ *                          relying on multi-block trend detection lose
+ *                          fidelity (single-element fallback is
+ *                          conservative).
+ * - `mempool: false`    — drops `txpool_content`. Mempool subscribers
+ *                          never receive snapshots; `getMempoolSnapshot`
+ *                          returns `null`. Useful when the upstream
+ *                          provider gates the method.
+ */
+export interface PollOptions {
+    feeHistory?: boolean;
+    mempool?: boolean;
+}
+/**
+ * How the source observed a particular fact. Discriminates the
+ * authority of any downstream-built event. The same chain-state can
+ * legitimately be observed via four paths; consumers that need hard
+ * guarantees filter to `'subscription'`.
+ *
+ * `'block-poll'` and `'mempool-snapshot'` indicate the source's
+ * own poll cycle pulled the data via `eth_getBlockByNumber` /
+ * `txpool_content` respectively. `'receipt-poll'` is reserved for
+ * downstream consumers (tx-tracker) that fall back to per-hash
+ * receipt polling when a higher-authority path is missing.
+ */
+export type EventSource = 'subscription' | 'block-poll' | 'mempool-snapshot' | 'receipt-poll';
+/**
+ * Per-method capability snapshot. Probed once on `source.start()` and
+ * re-probed on transport reconnect when the underlying transport
+ * supports reconnection signals.
+ *
+ * Intentionally per-method, not per-transport — real-world providers
+ * gate `txpool_content` while allowing `eth_subscribe('newHeads')`,
+ * and chains expose `txpool_content` while never offering
+ * `newPendingTransactions`. A single "ws-or-http" knob would elide
+ * cases the toolkit needs to cover.
+ */
+export interface Capabilities {
+    /** `eth_subscribe('newHeads')` push-based new-block events. */
+    newHeads: 'subscription' | 'poll-only' | 'unavailable';
+    /** `eth_subscribe('newPendingTransactions')` push-based mempool ingress. */
+    newPendingTransactions: 'subscription' | 'poll-only' | 'unavailable';
+    /** `txpool_content` support — many public RPCs gate this method. */
+    txpoolContent: 'available' | 'gated';
+    /** `eth_getTransactionReceipt` fallback path for inclusion watch. */
+    receiptByHash: 'available' | 'unavailable';
+    /** Whether transport reconnection re-probes (WS reconnect, etc.). */
+    reprobeOnReconnect: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +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"}

package/dist/types.js

@@ -0,0 +1,22 @@
+/**
+ * Canonical wire-shape types for `@valve-tech/chain-source`. Pure data
+ * shapes — no deps, no runtime behavior.
+ *
+ * **Wire format note.** Numeric fields that come from the EVM (block
+ * numbers, gas, fees, timestamps) are kept as `bigint` once decoded.
+ * The boundary types (`BlockResult`, `TxPoolContent`, `FeeHistoryResult`)
+ * keep them as hex strings because that is what `eth_getBlockByNumber`
+ * et al. return — the source decodes at the point of use, then returns
+ * `bigint`-typed objects to consumers (oracle, tracker). `JSON.stringify`
+ * 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.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@valve-tech/chain-source",
-  "version": "0.5.0",
+  "version": "0.7.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",