@valve-tech/gas-oracle 0.2.3 → 0.2.5

package/AGENTS.md

@@ -0,0 +1,216 @@
+# AGENTS.md
+
+Terse reference for AI agents (Claude Code, Cursor, Aider, etc.) integrating
+`@valve-tech/gas-oracle`. 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
+
+Multi-tier gas-fee oracle for EVM chains. Polls block + mempool data,
+computes `slow` / `standard` / `fast` / `instant` priority-fee
+recommendations from a gas-weighted percentile distribution, and serves
+them via an in-memory cache. Pass it a viem `PublicClient` and call
+`oracle.getState()` for sub-millisecond reads.
+
+Zero runtime dependencies. `viem ^2.0.0` is the only peer dependency.
+
+## Public API
+
+All exports live under `src/index.ts`. Default subpath is the canonical
+oracle constructor; two named subpaths add viem integration.
+
+```ts
+import {
+  createGasOracle,                   // primary constructor
+  normalizeMempool,                  // pure helper
+  findByHash, findByAddressNonce, findInMempool,  // mempool lookups
+  tipForBlockPosition,               // discriminated block-position query
+  // types
+  type GasOracle,
+  type CreateCreateGasOracleOptions,
+  type GasGasOracleState,
+  type TierRecommendation,
+  type RawTx,
+  type NormalizedMempool,
+  type MempoolHit,
+  type TxIdentifier,
+  type BlockPositionQuery,
+  type BlockPositionResult,
+} from '@valve-tech/gas-oracle'
+```
+
+```ts
+import { gasOracleActions } from '@valve-tech/gas-oracle/viem-actions'
+// client.extend(gasOracleActions({ oracle }))
+```
+
+```ts
+import { withGasOracle } from '@valve-tech/gas-oracle/viem-transport'
+// withGasOracle(transport, { oracle, intercept: ['eth_gasFeeEstimate', ...] })
+```
+
+## Five types you must know
+
+| Type | What it is |
+|---|---|
+| `CreateGasOracleOptions` | Constructor config. Required: `client`, `chainId`. Tuneables: `priorityFeeDecayCap`, `priorityModel`, `baseFeeLivenessBlocks`, `poll`, `keepMempoolSnapshot`. |
+| `GasOracleState` | What `oracle.getState()` returns. Holds the four-tier `tiers` map plus latest `baseFee`, `bufferedBaseFee`, mempool snapshot if enabled. |
+| `TierRecommendation` | Per-tier struct: `{ maxPriorityFeePerGas, maxFeePerGas, gasPrice, maxFeePerBlobGas }`. All `bigint`. |
+| `RawTx` | One mempool entry: `{ hash, from, to, nonce, value, maxPriorityFeePerGas, maxFeePerGas, gas, ... }`. Nullable fields for fields the chain may not expose. |
+| `BlockPositionQuery` | Discriminated union — five mutually-exclusive shapes (see below). |
+
+## The discriminated `BlockPositionQuery`
+
+This is the API surface most likely to confuse — it's deliberately shaped
+to make impossible queries unrepresentable. The `kind` field discriminates;
+TypeScript will narrow the rest of the fields per branch.
+
+```ts
+type BlockPositionQuery =
+  | { kind: 'rank'; rank: number }              // "tip to land in top N"
+  | { kind: 'percentile'; percentile: number }  // "tip to land at p_X"
+  | { kind: 'gasFromTop'; gas: bigint }         // "tip to land within G gas of leader"
+  | { kind: 'aheadOf'; tx: TxIdentifier }       // "tip to leapfrog this tx"
+  | { kind: 'behind'; tx: TxIdentifier }        // "tip to slip in just behind this tx"
+```
+
+`TxIdentifier` is `{ hash: string } | { address: string; nonce: number | bigint | string }`.
+Both forms resolve against the latest mempool snapshot. The result is a
+`BlockPositionResult`:
+
+```ts
+{
+  requiredTip: bigint        // min tip-per-gas to land at the position
+  pivot: TipSample | null    // the boundary sample, or null if out of range
+  rank: number               // approximate 0-indexed rank from top
+  gasFromTop: bigint         // approximate gas-from-top
+}
+```
+
+## Configuration patterns by chain class
+
+| Chain class | `priorityModel` | `baseFeeLivenessBlocks` | Notes |
+|---|---|---|---|
+| Ethereum mainnet, Base, Arbitrum, OP | `'eip1559'` | 6 | Validators burn base fee; tip is the only revenue. |
+| PulseChain (mainnet + testnet) | `'flat'` | 6 | Validators charge tips instead of burning. Type-2 vs legacy distinction is meaningless on flat-fee chains. |
+| Anything where you're unsure | `'flat'` | 6 | More conservative — never under-counts spam. |
+
+`priorityFeeDecayCap`: default is `WAD / 8` (12.5%/block) which matches
+EIP-1559's natural decay. Tighten to `WAD / 20` for very low-volatility
+chains; loosen to `null` for chains where you want the published tip to
+free-fall during quiet windows.
+
+## Three integration shapes (pick one)
+
+### 1. Direct (no viem wrapper)
+
+```ts
+const oracle = createGasOracle({ client, chainId: 1, priorityModel: 'eip1559' })
+oracle.start()
+const tier = oracle.getState()?.tiers.fast
+```
+
+### 2. viem-actions extension (recommended for app code)
+
+```ts
+const client = createPublicClient({ chain: mainnet, transport: http() })
+  .extend(gasOracleActions({ chainId: 1, priorityModel: 'eip1559' }))
+
+await client.getGasTiers()                       // GasOracleState
+await client.getGasTier('fast')                  // TierRecommendation
+await client.findTxInMempool({ hash: '0x...' })  // MempoolHit | null
+await client.tipForBlockPosition({ kind: 'rank', rank: 50 })  // BlockPositionResult
+client.stopGasOracle()                           // teardown
+```
+
+`gasOracleActions(options)` accepts the same options as `createGasOracle`
+(minus `client`, which it gets from the viem client at extension time)
+plus `lifecycle: 'eager' | 'lazy'`. Default `'eager'` starts polling on
+extension; `'lazy'` defers until the first read.
+
+### 3. viem-transport interception (drop-in for existing wagmi/viem code)
+
+Default intercepts only `eth_gasFeeEstimate` (a Valve-specific multi-tier
+RPC extension). Standard methods stay unintercepted unless opted in:
+
+```ts
+const transport = withGasOracle(http(), {
+  chainId: 1,
+  priorityModel: 'eip1559',
+  intercept: {
+    eth_gasFeeEstimate: true,        // default
+    eth_gasPrice: 'standard',        // tier-required opt-in (no boolean default)
+    eth_maxPriorityFeePerGas: 'fast',
+  },
+  lifecycle: 'lazy',                 // optional: defer poll until first intercept
+})
+
+// Tearing down (e.g. test/HMR): cast back to GasOracleTransport
+;(transport as GasOracleTransport).stopGasOracle()
+```
+
+`eth_gasPrice` and `eth_maxPriorityFeePerGas` reject a boolean for the
+intercept config — a tier choice is required so that the returned number
+doesn't silently depend on the package version's default.
+
+## Pitfalls (read these)
+
+1. **Don't poll `oracle.getState()` in a tight loop.** It's O(1) but you're
+   wasting CPU. Subscribe via `oracle.subscribe(callback)` for change
+   notifications and read state inside the callback.
+
+2. **One oracle per chain, ever.** Module-scope the oracle in your code so
+   it's started once. Construct + `start()` per request and you're paying
+   the warmup cost (~3-5 blocks of `eth_feeHistory` polling) every time.
+
+3. **`oracle.start()` returns immediately but tiers aren't populated until
+   the first poll completes.** `oracle.getState()` returns `null` during
+   warmup. Either handle the null case at the call site, or call
+   `await oracle.pollOnce()` once after `start()` to force a synchronous
+   first poll.
+
+4. **Mempool snapshot is opt-in.** `keepMempoolSnapshot: false` (the
+   default) means `findByHash`/`findInMempool`/`tipForBlockPosition` queries
+   that take a `TxIdentifier` will throw. Set `true` if you need them.
+
+5. **`findInMempool({ hash })` resolution costs a snapshot scan.** Cache
+   the result if you're calling it repeatedly for the same hash —
+   memoize or use a local map.
+
+6. **PulseChain RPCs may not honor `txpool_content`.** If
+   `oracle.getMempoolSnapshot()` returns `[]` consistently on a chain you
+   know has live txs, the upstream RPC is rejecting the namespace.
+   Verify with `curl -X POST <rpc> -H 'content-type: application/json' \
+   --data '{"jsonrpc":"2.0","method":"txpool_content","params":[],"id":1}'`.
+
+## Examples
+
+Runnable scripts in `examples/`:
+
+- `examples/01-basic-tiers.ts` — minimal `createGasOracle` + read tier
+- `examples/02-mempool-snapshot.ts` — `keepMempoolSnapshot: true` + `findByHash`
+- `examples/03-block-position.ts` — all five `tipForBlockPosition` query forms
+- `examples/04-viem-actions.ts` — `client.extend(gasOracleActions(...))`
+- `examples/05-viem-transport.ts` — `withGasOracle(transport, ...)` interception
+
+Run any of them with `yarn tsx examples/01-basic-tiers.ts`.
+
+## Skills (for AI agents)
+
+`skills/` directory 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/gas-oracle/skills/SKILL.md` for trigger conditions
+and integration recipes that go deeper than this file.
+
+## Verifying provenance
+
+v0.2.3+ ships with SLSA provenance attestation:
+
+```bash
+npm view @valve-tech/gas-oracle@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

@@ -0,0 +1,113 @@
+# Changelog
+
+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
+- `CHANGELOG.md` (this file).
+- `AGENTS.md` at repo root — terse, AI-first companion to README. Lists the
+  public API, the discriminated query shape for `tipForBlockPosition`, and
+  pitfalls.
+- `examples/` directory with 5 runnable scripts covering basic tier reads,
+  mempool snapshots, block-position queries, and both viem subpaths.
+- `skills/` directory shipped in the npm tarball — Claude Code / Cursor / etc.
+  agents consuming `node_modules/@valve-tech/gas-oracle/skills/` get grounded
+  context about when and how to use the package.
+- README badges (npm version, types-included, SLSA provenance).
+- ESLint configuration with `@typescript-eslint/no-explicit-any` enforced as
+  an error. The codebase was incidentally `any`-free; this makes the rule a
+  hard constraint.
+- `lint` script wired into the CI workflow.
+
+### Changed
+- `files` field in `package.json` now includes `CHANGELOG.md`, `AGENTS.md`,
+  and `skills/` so consumers get the docs and skill files in their
+  `node_modules/`.
+
+## [0.2.3] — 2026-05-02
+
+### Added
+- First release published via npm trusted-publisher OIDC. SLSA provenance
+  attestation now ships with the tarball; consumers can verify with
+  `npm audit signatures`.
+
+### Fixed
+- Aligned the release workflow with the known-working pattern used by other
+  OIDC-publishing repos: removed the `environment:` block from the publish
+  job, pinned `npm` to `11.5.1` before install. Without this, the OIDC PUT
+  to npm 404'd despite the trusted-publisher record being correctly
+  configured. See repo commit `de6c5bb` for the diagnostic.
+
+## [0.2.2] — *unpublished*
+
+Tagged but never published. OIDC publish failed; abandoned in favor of
+v0.2.3 which carries the workflow fix.
+
+## [0.2.1] — 2026-05-02
+
+### Fixed
+- Top-level `main`, `types`, and `exports` now point at `dist/*` instead of
+  `src/*.ts`. The `publishConfig` override pattern that previously rewrote
+  these fields at publish time is deprecated in npm 11 and didn't apply
+  correctly during the v0.2.0 manual publish — that release shipped a
+  tarball whose `package.json` pointed at non-existent `src/` paths.
+- Added `prepare: yarn build` to scripts so consumers using workspace
+  symlinks or `git+` installs get a built `dist/` automatically.
+
+### Removed
+- The `publishConfig` block (deprecated; replaced by aligning top-level
+  fields with the published shape).
+
+## [0.2.0] — 2026-05-02
+
+First public release. Tarball had a packaging bug — see [0.2.1] for the
+fix. Consumers should install `@valve-tech/gas-oracle@^0.2.1` or later.
+
+### Added
+- `priorityFeeDecayCap: bigint | null` config (wad; null = uncapped;
+  default `WAD/8` = 12.5%/block, EIP-1559 parity).
+- `priorityModel: 'flat' | 'eip1559'` for chains whose validators charge
+  tips instead of burning them (`flat`) versus chains that honor
+  EIP-1559 ordering (`eip1559`).
+- `baseFeeLivenessBlocks: number` — compounded 9/8 buffer over N blocks
+  so `maxFeePerGas` survives sustained worst-case base-fee growth.
+- `poll: { feeHistory?, mempool? }` toggles for chains that don't expose
+  one or both endpoints.
+- `keepMempoolSnapshot: boolean` + `oracle.getMempoolSnapshot()` for
+  Phase B stuck-tx detection.
+- Pure helpers: `normalizeMempool`, `findByHash`, `findByAddressNonce`,
+  `findInMempool`.
+- `tipForBlockPosition` — discriminated query over `rank` / `percentile`
+  / `gasFromTop` and `aheadOf` / `behind` a `TxIdentifier`.
+- `@valve-tech/gas-oracle/viem-actions` subpath for
+  `client.extend(gasOracleActions(...))` integration.
+- `@valve-tech/gas-oracle/viem-transport` subpath for `withGasOracle(transport, ...)`
+  drop-in interception.
+
+[0.2.4]: https://github.com/valve-tech/gas-oracle/releases/tag/v0.2.4
+[0.2.3]: https://github.com/valve-tech/gas-oracle/releases/tag/v0.2.3
+[0.2.1]: https://github.com/valve-tech/gas-oracle/releases/tag/v0.2.1
+[0.2.0]: https://github.com/valve-tech/gas-oracle/releases/tag/v0.2.0

package/README.md

@@ -1,5 +1,10 @@
 # @valve-tech/gas-oracle
 
+[![npm version](https://img.shields.io/npm/v/@valve-tech/gas-oracle)](https://www.npmjs.com/package/@valve-tech/gas-oracle)
+[![Types Included](https://img.shields.io/npm/types/@valve-tech/gas-oracle)](https://www.npmjs.com/package/@valve-tech/gas-oracle)
+[![SLSA Provenance](https://img.shields.io/badge/SLSA-provenance-blue)](https://docs.npmjs.com/generating-provenance-statements)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
 Multi-tier gas-fee oracle for EVM chains. Pass it a viem `PublicClient`
 and it polls block + mempool data, computes `slow` / `standard` /
 `fast` / `instant` tier recommendations, and serves them via an
@@ -8,6 +13,10 @@ aware EIP-1559 priority cutoff, and EIP-4844 blob-fee handling.
 
 Zero runtime dependencies. `viem` is the only peer dependency.
 
+> **AI agents:** see [`AGENTS.md`](AGENTS.md) for a terse, AI-first reference,
+> and [`skills/`](skills/) for Claude Code / Cursor skill files shipped in
+> `node_modules/`.
+
 ## Install
 
 ```bash
@@ -258,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.3",
+  "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",
@@ -42,12 +42,17 @@
   },
   "files": [
     "dist",
+    "skills",
     "README.md",
+    "AGENTS.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "scripts": {
     "build": "tsc -p .",
     "typecheck": "tsc -p . --noEmit",
+    "typecheck:examples": "tsc -p examples",
+    "lint": "eslint src",
     "test": "vitest run",
     "test:watch": "vitest",
     "prepare": "yarn build"
@@ -57,7 +62,11 @@
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.59.1",
+    "@typescript-eslint/parser": "^8.59.1",
+    "eslint": "^10.3.0",
     "typescript": "^6.0.2",
+    "typescript-eslint": "^8.59.1",
     "viem": "^2.21.0",
     "vitest": "^4.1.4"
   }

package/skills/gas-oracle-integration/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: gas-oracle-integration
+description: Integrate `@valve-tech/gas-oracle` into an EVM dapp or backend. Use when the user wants gas-tier recommendations (`slow` / `standard` / `fast` / `instant`), needs to set `maxPriorityFeePerGas` and `maxFeePerGas` for a transaction, hits stuck-tx detection requirements, or asks "how do I price a transaction" against a viem `PublicClient`. Also use when seeing imports from `@valve-tech/gas-oracle` and the user asks for help configuring it per chain (Ethereum, Base, Arbitrum, OP, PulseChain), or asks about `priorityFeeDecayCap`, `priorityModel`, `tipForBlockPosition`, viem-actions, or viem-transport.
+---
+
+# Integrating `@valve-tech/gas-oracle`
+
+Multi-tier gas-fee oracle for EVM chains. This skill is for AI agents
+working in a project that imports the package — it grounds you in the
+right configuration choices for the user's chain and the right
+integration shape for their codebase.
+
+## Decision tree: which integration to use
+
+```
+Is the user already passing a viem PublicClient around?
+├── Yes — use viem-actions (`client.extend(gasOracleActions(...))` or
+│         the direct invocation `gasOracleActions(opts)(client)`).
+│         Most ergonomic for app code.
+└── No — does the user have wagmi/viem code that already calls
+         `client.getGasPrice()` / `eth_maxPriorityFeePerGas`?
+         ├── Yes — use viem-transport (`withGasOracle(transport, ...)`)
+         │         to intercept those methods at the RPC layer. Drop-in.
+         │         No call-site changes.
+         └── No — use the direct constructor `createGasOracle(opts)`.
+                  Simplest. Read tiers via `oracle.getState()?.tiers`.
+```
+
+## Per-chain config (always required)
+
+| Chain | `chainId` | `priorityModel` | `baseFeeLivenessBlocks` | Notes |
+|---|---|---|---|---|
+| Ethereum mainnet | 1 | `'eip1559'` | 6 | Validators burn base fee. |
+| Base | 8453 | `'eip1559'` | 6 | Same as ETH. |
+| Arbitrum One | 42161 | `'eip1559'` | 6 | |
+| Optimism | 10 | `'eip1559'` | 6 | |
+| PulseChain mainnet | 369 | `'flat'` | 6 | Validators charge tips. |
+| PulseChain testnet v4 | 943 | `'flat'` | 6 | |
+| Unknown / unsure | — | `'flat'` | 6 | Conservative; never under-counts. |
+
+`priorityFeeDecayCap`: leave at default (`WAD/8` = 12.5%/block, EIP-1559
+parity) unless you have a specific reason to tighten/loosen.
+
+## Anti-patterns to flag
+
+When reviewing user code, watch for these and suggest fixes:
+
+1. **Multiple oracles per chain in the same process.** Construct once,
+   module-scope it. Each oracle runs a poll interval and holds state.
+   Two oracles for chain 1 = double the RPC traffic, no benefit.
+
+2. **`oracle.getState()` in a hot path that runs every render / every
+   request.** It's O(1) but you're wasting cache lines. Either subscribe
+   via `oracle.subscribe(cb)` and store the latest state in a module
+   variable, or cache the result yourself with a short TTL.
+
+3. **Reading `oracle.getState()` immediately after `oracle.start()`
+   without handling null.** First poll hasn't completed yet; tiers will
+   be missing. Fix: `await oracle.pollOnce()` after `start()` to seed
+   state synchronously, then it's safe to call `getState()`.
+
+4. **Using `priorityModel: 'eip1559'` on PulseChain or other tip-charging
+   chains.** Cuts the distribution to type-2+ samples only, but
+   PulseChain validators don't honor the type byte — they sort by tip
+   regardless. Result: under-published tier values, your tx loses to
+   legacy spam.
+
+5. **`keepMempoolSnapshot: true` on a chain whose RPC gates
+   `txpool_content`** (most public RPCs). Wastes a poll cycle's RPC
+   budget on a request that always errors. Set `false` until you have
+   a node you operate.
+
+6. **Calling `findTxInMempool` with a hash that's been confirmed.**
+   Confirmed txs are NOT in the mempool snapshot (it's pending+queued
+   only). Check `eth_getTransactionByHash` instead.
+
+## How to recognize this package in the user's code
+
+```ts
+// Direct constructor
+import { createGasOracle } from '@valve-tech/gas-oracle'
+
+// viem-actions extension
+import { gasOracleActions } from '@valve-tech/gas-oracle/viem-actions'
+
+// viem-transport interception
+import { withGasOracle } from '@valve-tech/gas-oracle/viem-transport'
+```
+
+`package.json` will show `"@valve-tech/gas-oracle": "^0.2.x"` in dependencies.
+
+## Where to find more
+
+- Full API + types: `node_modules/@valve-tech/gas-oracle/AGENTS.md`
+- Runnable examples: `node_modules/@valve-tech/gas-oracle/examples/`
+- Human-facing docs: `node_modules/@valve-tech/gas-oracle/README.md`
+- Source (when types alone aren't enough): `node_modules/@valve-tech/gas-oracle/dist/`
+  (compiled JS + .d.ts) — sources aren't shipped, only built output.