@valve-tech/gas-oracle 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Valve Tech
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,270 @@
+# @valve-tech/gas-oracle
+
+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
+in-memory cache. Includes a configurable downside-decay cap, a chain-
+aware EIP-1559 priority cutoff, and EIP-4844 blob-fee handling.
+
+Zero runtime dependencies. `viem` is the only peer dependency.
+
+## Install
+
+```bash
+yarn add @valve-tech/gas-oracle viem
+```
+
+## Quick start
+
+```ts
+import { createPublicClient, http, parseEther } from 'viem'
+import { mainnet } from 'viem/chains'
+import { createGasOracle } from '@valve-tech/gas-oracle'
+
+const client = createPublicClient({ chain: mainnet, transport: http() })
+
+const oracle = createGasOracle({
+  client,
+  chainId: 1,
+  priorityFeeDecayCap: parseEther('0.125'), // 12.5%/block, EIP-1559 parity
+  priorityModel: 'eip1559',                 // 'flat' for extractive networks
+})
+
+oracle.subscribe((state) => {
+  console.log('fast tier:', state.tiers.fast.maxPriorityFeePerGas)
+})
+
+oracle.start()
+
+// Sub-millisecond read, no RPC roundtrip:
+const tier = oracle.getState()?.tiers.standard
+```
+
+## Tier semantics
+
+Each tier is one `TierRecommendation`:
+
+```ts
+interface TierRecommendation {
+  maxPriorityFeePerGas: bigint
+  maxFeePerGas: bigint        // bufferedBaseFee + maxPriorityFeePerGas
+  gasPrice: bigint            // baseFee + maxPriorityFeePerGas (legacy)
+  maxFeePerBlobGas: bigint | null   // null on chains without EIP-4844
+}
+```
+
+Tier mapping in the gas-weighted percentile distribution:
+
+| Tier       | Percentile | Use for                                                      |
+|------------|------------|--------------------------------------------------------------|
+| `slow`     | p10        | Background / non-time-sensitive ops (claims, batched writes) |
+| `standard` | p50        | Default for most user actions                                |
+| `fast`     | p75        | Trades, swaps, anything competing with bots                  |
+| `instant`  | p90        | Auctions, MEV-adjacent, opt-out-of-mempool deals             |
+
+`slow` always reads from the full distribution (legacy + 1559) so legacy
+senders can still find the lane they actually live in. Under
+`priorityModel: 'eip1559'`, the paying-lane tiers (`standard`/`fast`/
+`instant`) draw from type-2+ samples only — legacy spam can't suppress
+them.
+
+## Configuration
+
+### `priorityFeeDecayCap`
+
+How fast the published priority-fee tip is allowed to drop, expressed
+wad (1e18 = 100%). Use `parseEther` for the human-readable form:
+
+```ts
+priorityFeeDecayCap: parseEther('0.125')   // 12.5%/block (EIP-1559 parity)
+priorityFeeDecayCap: parseEther('0.05')    // 5%/block (smoother)
+priorityFeeDecayCap: parseEther('0')       // no decay allowed (sticky floor)
+priorityFeeDecayCap: parseEther('1')       // full collapse after one block
+priorityFeeDecayCap: null                  // uncapped — track raw mempool
+```
+
+Validated at construction; out-of-range values throw. Upside is always
+unclamped — real spikes propagate immediately.
+
+### `priorityModel`
+
+Where the chain's inclusion logic draws its priority cutoff in the
+EIP-2718 type space:
+
+- `'flat'` — every tx contributes equally to the gas-weighted
+  distribution. Right for extractive validators (PulseChain, etc.)
+  that ignore the type byte and just maximize fee per gas.
+- `'eip1559'` — type 2+ samples drive the paying-lane tiers (standard/
+  fast/instant); `slow` still draws from the full distribution. Right
+  for chains that honor EIP-1559 ordering (Ethereum, most L2s).
+
+Default `'flat'` (most conservative — never under-counts spam).
+
+### `baseFeeLivenessBlocks`
+
+How many blocks the published recommendation should survive in the
+worst case. The buffered base fee underpinning `maxFeePerGas` becomes
+`baseFee × (9/8)^N` (the EIP-1559 worst-case rise compounded over N
+blocks), so a tx submitted with the snapshot still lands within `N`
+blocks even if every intervening block is full.
+
+```ts
+baseFeeLivenessBlocks: 1   // default; one block of headroom (= old behavior)
+baseFeeLivenessBlocks: 6   // ~1.5 minutes on Ethereum, ~2 minutes on PulseChain
+baseFeeLivenessBlocks: 30  // generous cushion for slow human approvals
+```
+
+`falling` markets stay at 1× regardless of N (base fee will continue
+to drop, headroom is wasted).
+
+### `poll`
+
+Producer-side toggles for upstream RPC calls:
+
+```ts
+poll: {
+  feeHistory: true,   // eth_feeHistory; powers trend detection
+  mempool: true,      // txpool_content; powers pending-pressure signal
+}
+```
+
+Both default `true`. Setting either to `false` skips that RPC entirely
+each cycle. Useful when the upstream provider gates the method (many
+public RPCs return 405 on `txpool_content`) or when you want a
+minimum-RPC-budget oracle. `eth_getBlockByNumber` is not toggleable.
+
+### `keepMempoolSnapshot`
+
+When `true`, the oracle retains the latest normalized mempool snapshot
+and exposes it via `oracle.getMempoolSnapshot()`. The snapshot powers
+`findInMempool` / `tipForBlockPosition({ kind: 'aheadOf' })`-style
+lookups without a second RPC roundtrip. Memory cost is the size of one
+`txpool_content` payload (5–15MB on busy ETH mainnet); leave off in
+browser/mobile contexts. Default `false`.
+
+## Mempool inspection
+
+Two ways into the same data: pure helpers that take a normalized pool
+(if you already have one) or oracle-backed actions (if you're already
+running a `GasOracle`).
+
+```ts
+import {
+  normalizeMempool,
+  findByHash,
+  findByAddressNonce,
+  findInMempool,
+} from '@valve-tech/gas-oracle'
+
+// Normalize once at ingest — case-folds sender addresses and
+// decimalizes nonce keys. All lookups expect the normalized form.
+const pool = normalizeMempool(rawPoolFromTxpoolContent)
+
+findByHash(pool, '0xdeadbeef…')                    // MempoolHit | null
+findByAddressNonce(pool, '0xabc…', 5)              // MempoolHit | null
+findInMempool(pool, { hash: '0xdeadbeef…' })       // discriminated form
+findInMempool(pool, { address: '0xabc…', nonce: 5n })
+```
+
+`MempoolHit` carries the matched `tx`, the `bucket` (`'pending'` /
+`'queued'`), and the canonicalized `address` + `nonce`.
+
+## Block-position calculations
+
+Compute the priority fee required to land at a target position in the
+next block. The query is a discriminated union — each `kind` carries
+exactly the fields it needs:
+
+```ts
+import { tipForBlockPosition } from '@valve-tech/gas-oracle'
+
+// Absolute targeting
+tipForBlockPosition(samples, { kind: 'rank', rank: 0 })          // top of block
+tipForBlockPosition(samples, { kind: 'percentile', percentile: 5 }) // top 5%
+tipForBlockPosition(samples, { kind: 'gasFromTop', gas: 1_000_000n }) // first 1M gas
+
+// Relative targeting — beat or undercut a specific tx
+tipForBlockPosition(samples, { kind: 'aheadOf', tx: { hash: '0xabc…' } })
+tipForBlockPosition(samples, { kind: 'behind', tx: { address: '0xabc…', nonce: 5 } })
+```
+
+Returns `{ requiredTip, pivot, rank, gasFromTop }`. `requiredTip` is
+the *minimum* tip — pivot.tip + 1 wei to outbid, or pivot.tip - 1 wei
+to undercut. Add your own buffer for finality.
+
+`samples` is typically the merged ring + mempool tip distribution —
+the same union `computeTiers` reads. The viem-actions extension
+exposes `client.tipForBlockPosition(query)` which assembles this
+distribution for you from the oracle's state.
+
+## viem integration
+
+### Subpath: `@valve-tech/gas-oracle/viem-actions`
+
+Extension surface for callers who want explicit access to tier shapes:
+
+```ts
+import { gasOracleActions } from '@valve-tech/gas-oracle/viem-actions'
+
+const client = createPublicClient({ chain: mainnet, transport: http() })
+  .extend(gasOracleActions({
+    chainId: 1,
+    priorityFeeDecayCap: parseEther('0.125'),
+    priorityModel: 'eip1559',
+  }))
+
+await client.getGasTiers()                            // full snapshot
+await client.getGasTier('fast')                       // one tier
+await client.findTxInMempool({ hash: '0xabc…' })       // mempool lookup
+await client.tipForBlockPosition({                    // position targeting
+  kind: 'aheadOf',
+  tx: { address: '0xabc…', nonce: 5 },
+})
+client.stopGasOracle()                                 // shutdown hook
+```
+
+### Subpath: `@valve-tech/gas-oracle/viem-transport`
+
+Drop-in replacement for callers who want viem's existing API to *just
+work better* — `useFeeData`, `walletClient.sendTransaction({...})`,
+`estimateMaxPriorityFeePerGas`, and so on:
+
+```ts
+import { withGasOracle } from '@valve-tech/gas-oracle/viem-transport'
+
+const transport = withGasOracle(http(rpcUrl), {
+  chainId: 1,
+  priorityFeeDecayCap: parseEther('0.125'),
+  priorityModel: 'eip1559',
+  intercept: {
+    eth_gasFeeEstimate: true,           // additive (default on)
+    eth_maxPriorityFeePerGas: 'fast',   // tier required for standard methods
+  },
+})
+
+const client = createPublicClient({ chain: mainnet, transport })
+```
+
+Default `intercept` is `{ eth_gasFeeEstimate: true }` only — the
+additive method that returns multi-tier shape. Standard methods
+(`eth_gasPrice`, `eth_maxPriorityFeePerGas`) pass through to upstream
+unless explicitly opted in **with a tier name**. Boolean opt-in on the
+standard methods is intentionally not accepted: a default tier choice
+would silently make the method's number depend on the package version,
+and that's the silently-pick-a-percentile foot-gun this design is
+careful to avoid.
+
+`eth_feeHistory` is intentionally NOT in the intercept config —
+synthesizing a historical-percentile array from oracle state is its
+own design problem. Always passes through to upstream.
+
+## Wire format
+
+Every fee field is a `bigint`. Callers serializing across HTTP / Redis
+/ WebSocket should hex-encode (`'0x' + n.toString(16)`) since JSON has
+no native bigint and `JSON.stringify` will throw on raw bigint values.
+The package keeps the canonical numeric form internally.
+
+## License
+
+MIT

package/dist/block-position.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Block-position calculator.
+ *
+ * Validators include txs in *gas-weighted tip-descending order* — high
+ * tip-per-gas at the top of the block, low tip-per-gas at the bottom.
+ * "Position in the block" therefore has two natural axes:
+ *
+ *   1. **Rank** — count from the top. Position 0 is the highest-tip tx.
+ *   2. **Gas offset** — accumulated gas consumed by all higher-tip txs.
+ *      Position is "I want my tx mined within the first 1M gas of the
+ *      block" → walk samples in tip-desc order, sum gas, find the
+ *      pivot whose cumulative cross 1M.
+ *
+ * Both axes resolve to the same machinery — pick a pivot in the
+ * sorted-by-tip-desc sample list, return the tip you'd need to pay to
+ * outbid it.
+ *
+ * `tipForBlockPosition` returns the *minimum* tip to land at the
+ * requested position; callers should add their own buffer for finality.
+ * Equality at the same tip is validator-policy-dependent and not
+ * guaranteed, so "outbid by 1 wei" is the honest minimum.
+ */
+import type { TipSample } from './types.js';
+import type { TxIdentifier } from './mempool.js';
+/**
+ * What position to target in the gas-weighted, tip-descending order
+ * of a block. Discriminated by `kind`:
+ *
+ * - `'rank'`         — `rank` is 0-indexed from the top (highest tip).
+ *                      `rank: 0` → land at the very top; `rank: 4` →
+ *                      land in 5th place.
+ * - `'percentile'`   — `percentile` is `[0, 100]` from the top.
+ *                      `percentile: 5` → I want to be in the top 5%.
+ * - `'gasFromTop'`   — `gas` is a bigint of cumulative gas from the
+ *                      block top. `gas: 1_000_000n` → land within the
+ *                      first 1M gas of the block.
+ * - `'aheadOf'`      — beat out a specific tx in the distribution.
+ *                      Useful for MEV-style "I just need to outrank
+ *                      this swap" targeting.
+ * - `'behind'`       — be just behind a specific tx (still mine in the
+ *                      same block, but pay less). Useful for piggybacking
+ *                      on a high-tip tx that's already going to displace
+ *                      pressure.
+ *
+ * Discriminated-union over flat-options-with-mode: per project style,
+ * fields whose presence depends on the kind belong inside the kind's
+ * variant, not flattened with `?`-marks.
+ */
+export type BlockPositionQuery = {
+    kind: 'rank';
+    rank: number;
+} | {
+    kind: 'percentile';
+    percentile: number;
+} | {
+    kind: 'gasFromTop';
+    gas: bigint;
+} | {
+    kind: 'aheadOf';
+    tx: TxIdentifier;
+} | {
+    kind: 'behind';
+    tx: TxIdentifier;
+};
+export interface BlockPositionResult {
+    /**
+     * Minimum tip-per-gas to definitively land at the requested position.
+     * For `aheadOf` and `gasFromTop`/`rank`/`percentile` queries, this is
+     * `pivot.tip + 1n` (one wei above the tx at the boundary). For
+     * `behind`, this is `max(pivot.tip - 1n, 0n)`. Returns `0n` when the
+     * distribution is empty or the position is below everyone.
+     */
+    requiredTip: bigint;
+    /**
+     * The sample at the boundary — the tx you're outbidding (or
+     * undercutting). `null` when the requested position is outside the
+     * distribution (e.g. `rank: 1000` in a 50-tx block) or the
+     * distribution is empty.
+     */
+    pivot: TipSample | null;
+    /** Approximate rank of the resolved position, 0-indexed from top. */
+    rank: number;
+    /** Approximate gas-from-top of the resolved position. */
+    gasFromTop: bigint;
+}
+/**
+ * Compute the tip required to land at the requested position in the
+ * next block, given a sample distribution (typically the merged ring
+ * + mempool samples that `computeTiers` consumes, but any
+ * `TipSample[]` works — pass just block samples for "would I have
+ * landed in the last block?" hindsight).
+ *
+ * Pure: no I/O, no oracle dependency, no wall-clock. Test by feeding
+ * fixture samples and asserting the returned shape.
+ */
+export declare const tipForBlockPosition: (samples: TipSample[], query: BlockPositionQuery) => BlockPositionResult;
+//# sourceMappingURL=block-position.d.ts.map

package/dist/block-position.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"block-position.d.ts","sourceRoot":"","sources":["../src/block-position.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAC3C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAEhD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,MAAM,kBAAkB,GAC1B;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC9B;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GAC1C;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GACnC;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,EAAE,EAAE,YAAY,CAAA;CAAE,GACrC;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,EAAE,EAAE,YAAY,CAAA;CAAE,CAAA;AAExC,MAAM,WAAW,mBAAmB;IAClC;;;;;;OAMG;IACH,WAAW,EAAE,MAAM,CAAA;IACnB;;;;;OAKG;IACH,KAAK,EAAE,SAAS,GAAG,IAAI,CAAA;IACvB,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAA;IACZ,yDAAyD;IACzD,UAAU,EAAE,MAAM,CAAA;CACnB;AA+CD;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB,GAC9B,SAAS,SAAS,EAAE,EACpB,OAAO,kBAAkB,KACxB,mBA0DF,CAAA"}

package/dist/block-position.js

@@ -0,0 +1,131 @@
+/**
+ * Block-position calculator.
+ *
+ * Validators include txs in *gas-weighted tip-descending order* — high
+ * tip-per-gas at the top of the block, low tip-per-gas at the bottom.
+ * "Position in the block" therefore has two natural axes:
+ *
+ *   1. **Rank** — count from the top. Position 0 is the highest-tip tx.
+ *   2. **Gas offset** — accumulated gas consumed by all higher-tip txs.
+ *      Position is "I want my tx mined within the first 1M gas of the
+ *      block" → walk samples in tip-desc order, sum gas, find the
+ *      pivot whose cumulative cross 1M.
+ *
+ * Both axes resolve to the same machinery — pick a pivot in the
+ * sorted-by-tip-desc sample list, return the tip you'd need to pay to
+ * outbid it.
+ *
+ * `tipForBlockPosition` returns the *minimum* tip to land at the
+ * requested position; callers should add their own buffer for finality.
+ * Equality at the same tip is validator-policy-dependent and not
+ * guaranteed, so "outbid by 1 wei" is the honest minimum.
+ */
+const sortByTipDesc = (samples) => [...samples].sort((a, b) => (a.tip > b.tip ? -1 : a.tip < b.tip ? 1 : 0));
+const matchesIdentifier = (sample, id) => {
+    if ('hash' in id) {
+        return (typeof sample.hash === 'string' &&
+            sample.hash.toLowerCase() === id.hash.toLowerCase());
+    }
+    if (sample.address === undefined || sample.nonce === undefined)
+        return false;
+    if (sample.address.toLowerCase() !== id.address.toLowerCase())
+        return false;
+    return sample.nonce === BigInt(id.nonce).toString();
+};
+/**
+ * Walk samples in tip-desc order accumulating gas; return the index
+ * (0-based from top) where cumulative gas first crosses `targetGas`.
+ * Returns -1 when the target exceeds the sum of all gas (the position
+ * is below the whole distribution).
+ */
+const indexAtGasOffset = (sorted, targetGas) => {
+    if (targetGas <= 0n)
+        return 0;
+    let cumulative = 0n;
+    for (let i = 0; i < sorted.length; i += 1) {
+        cumulative += sorted[i].gas;
+        if (cumulative > targetGas)
+            return i;
+    }
+    return -1;
+};
+const sumGasUpTo = (sorted, indexExclusive) => {
+    let g = 0n;
+    const upper = Math.min(indexExclusive, sorted.length);
+    for (let i = 0; i < upper; i += 1)
+        g += sorted[i].gas;
+    return g;
+};
+const empty = () => ({
+    requiredTip: 0n,
+    pivot: null,
+    rank: 0,
+    gasFromTop: 0n,
+});
+/**
+ * Compute the tip required to land at the requested position in the
+ * next block, given a sample distribution (typically the merged ring
+ * + mempool samples that `computeTiers` consumes, but any
+ * `TipSample[]` works — pass just block samples for "would I have
+ * landed in the last block?" hindsight).
+ *
+ * Pure: no I/O, no oracle dependency, no wall-clock. Test by feeding
+ * fixture samples and asserting the returned shape.
+ */
+export const tipForBlockPosition = (samples, query) => {
+    if (samples.length === 0)
+        return empty();
+    const sorted = sortByTipDesc(samples);
+    let pivotIndex;
+    let beatPivot; // true = outbid (tip+1), false = undercut (tip-1)
+    switch (query.kind) {
+        case 'rank': {
+            pivotIndex = query.rank;
+            beatPivot = true;
+            break;
+        }
+        case 'percentile': {
+            // 0% = top of block (highest tip); 100% = bottom. Clamp to [0, 100].
+            const pct = Math.min(100, Math.max(0, query.percentile));
+            pivotIndex = Math.floor((sorted.length * pct) / 100);
+            // Edge: percentile=100 lands at length, which is "below everything"
+            if (pivotIndex >= sorted.length)
+                pivotIndex = sorted.length - 1;
+            beatPivot = true;
+            break;
+        }
+        case 'gasFromTop': {
+            pivotIndex = indexAtGasOffset(sorted, query.gas);
+            beatPivot = true;
+            break;
+        }
+        case 'aheadOf':
+        case 'behind': {
+            pivotIndex = sorted.findIndex((s) => matchesIdentifier(s, query.tx));
+            beatPivot = query.kind === 'aheadOf';
+            break;
+        }
+    }
+    if (pivotIndex < 0 || pivotIndex >= sorted.length) {
+        // Position is below everyone (or pivot not found) — pay nothing in priority
+        return {
+            requiredTip: 0n,
+            pivot: null,
+            rank: sorted.length,
+            gasFromTop: sumGasUpTo(sorted, sorted.length),
+        };
+    }
+    const pivot = sorted[pivotIndex];
+    const requiredTip = beatPivot
+        ? pivot.tip + 1n
+        : pivot.tip > 0n
+            ? pivot.tip - 1n
+            : 0n;
+    return {
+        requiredTip,
+        pivot,
+        rank: pivotIndex,
+        gasFromTop: sumGasUpTo(sorted, pivotIndex),
+    };
+};
+//# sourceMappingURL=block-position.js.map

package/dist/block-position.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"block-position.js","sourceRoot":"","sources":["../src/block-position.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @valve-tech/gas-oracle — public API.
+ *
+ * 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 exposes them via a sub-millisecond in-memory
+ * read. Includes EIP-1559-style 12.5%/block downside cap so quiet blocks
+ * don't drop the published number off a cliff, and EIP-4844 blob fee
+ * for chains that support it.
+ *
+ * Zero runtime dependencies. viem is the only peer dependency, used to
+ * issue the underlying RPC calls (`eth_feeHistory`,
+ * `eth_getBlockByNumber`, `txpool_content`).
+ */
+export { createGasOracle, reducePollInputs, type CreateGasOracleOptions, type GasOracle, } from './oracle.js';
+export { effectiveTip, computePercentiles, detectTrend, cappedTip, computeTiers, computeBlobBaseFee, flattenTxPool, gasWeightedPercentiles, sortedTips, DEFAULT_PRIORITY_FEE_DECAY_CAP, DEFAULT_BASE_FEE_LIVENESS_BLOCKS, } from './math.js';
+export { blockToSample, mempoolToSamples, } from './samples.js';
+export { fetchOracleInputs, type FeeHistoryResult, type BlockResult, type TxPoolContent, type OraclePollInputs, } from './transport.js';
+export type { RawTx, TipPercentiles, TierRecommendation, TierName, Trend, MempoolStats, BlobStats, BlockSample, GasOracleState, TipSample, PriorityModel, PollOptions, } from './types.js';
+export { normalizeMempool, findByHash, findByAddressNonce, findInMempool, } from './mempool.js';
+export type { NormalizedMempool, TxIdentifier, MempoolBucket, MempoolHit, } from './mempool.js';
+export { tipForBlockPosition } from './block-position.js';
+export type { BlockPositionQuery, BlockPositionResult, } from './block-position.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,KAAK,sBAAsB,EAC3B,KAAK,SAAS,GACf,MAAM,aAAa,CAAA;AAEpB,OAAO,EACL,YAAY,EACZ,kBAAkB,EAClB,WAAW,EACX,SAAS,EACT,YAAY,EACZ,kBAAkB,EAClB,aAAa,EACb,sBAAsB,EACtB,UAAU,EACV,8BAA8B,EAC9B,gCAAgC,GACjC,MAAM,WAAW,CAAA;AAElB,OAAO,EACL,aAAa,EACb,gBAAgB,GACjB,MAAM,cAAc,CAAA;AAErB,OAAO,EACL,iBAAiB,EACjB,KAAK,gBAAgB,EACrB,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,gBAAgB,GACtB,MAAM,gBAAgB,CAAA;AAEvB,YAAY,EACV,KAAK,EACL,cAAc,EACd,kBAAkB,EAClB,QAAQ,EACR,KAAK,EACL,YAAY,EACZ,SAAS,EACT,WAAW,EACX,cAAc,EACd,SAAS,EACT,aAAa,EACb,WAAW,GACZ,MAAM,YAAY,CAAA;AAGnB,OAAO,EACL,gBAAgB,EAChB,UAAU,EACV,kBAAkB,EAClB,aAAa,GACd,MAAM,cAAc,CAAA;AACrB,YAAY,EACV,iBAAiB,EACjB,YAAY,EACZ,aAAa,EACb,UAAU,GACX,MAAM,cAAc,CAAA;AAGrB,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AACzD,YAAY,EACV,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,qBAAqB,CAAA"}

package/dist/index.js

@@ -0,0 +1,23 @@
+/**
+ * @valve-tech/gas-oracle — public API.
+ *
+ * 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 exposes them via a sub-millisecond in-memory
+ * read. Includes EIP-1559-style 12.5%/block downside cap so quiet blocks
+ * don't drop the published number off a cliff, and EIP-4844 blob fee
+ * for chains that support it.
+ *
+ * Zero runtime dependencies. viem is the only peer dependency, used to
+ * issue the underlying RPC calls (`eth_feeHistory`,
+ * `eth_getBlockByNumber`, `txpool_content`).
+ */
+export { createGasOracle, reducePollInputs, } from './oracle.js';
+export { effectiveTip, computePercentiles, detectTrend, cappedTip, computeTiers, computeBlobBaseFee, flattenTxPool, gasWeightedPercentiles, sortedTips, DEFAULT_PRIORITY_FEE_DECAY_CAP, DEFAULT_BASE_FEE_LIVENESS_BLOCKS, } from './math.js';
+export { blockToSample, mempoolToSamples, } from './samples.js';
+export { fetchOracleInputs, } from './transport.js';
+// Mempool inspection
+export { normalizeMempool, findByHash, findByAddressNonce, findInMempool, } from './mempool.js';
+// Block-position calculations
+export { tipForBlockPosition } from './block-position.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EACL,eAAe,EACf,gBAAgB,GAGjB,MAAM,aAAa,CAAA;AAEpB,OAAO,EACL,YAAY,EACZ,kBAAkB,EAClB,WAAW,EACX,SAAS,EACT,YAAY,EACZ,kBAAkB,EAClB,aAAa,EACb,sBAAsB,EACtB,UAAU,EACV,8BAA8B,EAC9B,gCAAgC,GACjC,MAAM,WAAW,CAAA;AAElB,OAAO,EACL,aAAa,EACb,gBAAgB,GACjB,MAAM,cAAc,CAAA;AAErB,OAAO,EACL,iBAAiB,GAKlB,MAAM,gBAAgB,CAAA;AAiBvB,qBAAqB;AACrB,OAAO,EACL,gBAAgB,EAChB,UAAU,EACV,kBAAkB,EAClB,aAAa,GACd,MAAM,cAAc,CAAA;AAQrB,8BAA8B;AAC9B,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA"}