@valve-tech/gas-oracle 0.2.4 → 0.2.5

package/CHANGELOG.md

@@ -5,6 +5,25 @@ All notable changes to `@valve-tech/gas-oracle` are documented in 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.2.5] — 2026-05-03
+
+### Added
+- README **RPC transport modes** section covering all four caller-side
+  configurations the package supports: HTTP-only, WS-only, both (via viem's
+  `fallback`), and "neither" (driving the pure `reducePollInputs` reducer
+  with pre-fetched `OraclePollInputs` — no live `PublicClient` needed).
+- `examples/06-reducer-only.ts` exercising the offline path end-to-end with
+  synthetic fixture inputs, surfacing the `fetchOracleInputs` /
+  `reducePollInputs` export split that enables it.
+
+### Notes
+- Documentation-only release. No API changes; behavior identical to v0.2.4.
+- Picking WS today buys nothing functional over HTTP — the oracle never
+  opens a subscription. The functional case for WS arrives when
+  subscription-using features (e.g., tx-tracking via `newHeads` /
+  `newPendingTransactions`) land. Choose WS now only if upstream is cheaper
+  or lower-latency on it.
+
 ## [0.2.4] — 2026-05-02
 
 ### Added

package/README.md

@@ -267,6 +267,72 @@ careful to avoid.
 synthesizing a historical-percentile array from oracle state is its
 own design problem. Always passes through to upstream.
 
+## RPC transport modes
+
+The package only ever calls `client.request({ method, params })` and
+never opens a subscription. That makes it transport-agnostic — any
+viem `Transport` works, and the four caller-side configurations below
+all run unchanged:
+
+### HTTP only
+
+```ts
+import { http } from 'viem'
+
+const client = createPublicClient({ chain: mainnet, transport: http(rpcUrl) })
+const oracle = createGasOracle({ client, chainId: 1 })
+```
+
+### WebSocket only
+
+```ts
+import { webSocket } from 'viem'
+
+const client = createPublicClient({ chain: mainnet, transport: webSocket(wsUrl) })
+const oracle = createGasOracle({ client, chainId: 1 })
+```
+
+WS works because the three RPCs the oracle issues (`eth_feeHistory`,
+`eth_getBlockByNumber`, `txpool_content`) are all request/response;
+viem's `webSocket` transport implements the same `request` interface
+as `http`. **Picking WS today buys nothing functional over HTTP** —
+the oracle still polls on its `pollIntervalMs`. The functional case
+for WS arrives when subscription-using features land (tx-tracking
+`newHeads` / `newPendingTransactions`); choose WS now only if your
+upstream is cheaper or lower-latency on it.
+
+### Both — `fallback` for resilience
+
+```ts
+import { fallback, http, webSocket } from 'viem'
+
+const transport = fallback([webSocket(wsUrl), http(rpcUrl)])
+const client = createPublicClient({ chain: mainnet, transport })
+const oracle = createGasOracle({ client, chainId: 1 })
+```
+
+viem handles failover transparently — if the WS drops, requests fall
+to HTTP without the oracle noticing.
+
+### Neither — pure reducer, no live RPC
+
+The oracle's I/O surface (`fetchOracleInputs`) and its math
+(`reducePollInputs`) are exported as separate top-level entries. That
+split is what enables the offline path: drive the reducer with
+`OraclePollInputs` from any source — fixture file, snapshot store,
+Kafka log, another service's API — and never touch a `PublicClient`.
+
+```ts
+import { reducePollInputs, type OraclePollInputs } from '@valve-tech/gas-oracle'
+
+const inputs: OraclePollInputs = await loadFromYourQueue()
+const state = reducePollInputs({ inputs, chainId: 1, prev: priorState })
+```
+
+Use cases: serverless / edge handlers, backtest harnesses replaying
+historical RPC payloads, tests asserting state shape from fixtures.
+See `examples/06-reducer-only.ts`.
+
 ## Wire format
 
 Every fee field is a `bigint`. Callers serializing across HTTP / Redis

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@valve-tech/gas-oracle",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "description": "Multi-tier gas-fee oracle for EVM chains. Computes slow/standard/fast/instant tier recommendations from block-included tips, mempool pending tips, and base-fee trend, with a configurable downside-decay cap and a chain-aware EIP-1559 priority cutoff. viem-native — pass it a PublicClient and it does the rest. Ships viem-actions and viem-transport subpaths for drop-in client extension and transport-wrapping.",
   "license": "MIT",
   "homepage": "https://github.com/valve-tech/gas-oracle#readme",