@valve-tech/gas-oracle 0.2.0

package/dist/math.d.ts

@@ -0,0 +1,148 @@
+/**
+ * Pure math primitives for the gas oracle. No I/O, no state — every
+ * function is referentially transparent and exhaustively unit-testable.
+ *
+ * The math is the load-bearing wall: tier recommendations are only as
+ * trustworthy as `effectiveTip` and `cappedTip`, so every edge case
+ * (legacy txs, EIP-1559 with zero headroom, cold-start cap, post-EIP-4844
+ * blob fee) is handled here rather than at higher layers.
+ */
+import type { PriorityModel, RawTx, TierRecommendation, TierName, TipPercentiles, TipSample, Trend } from './types.js';
+/** Default priority-fee decay cap = 12.5% / block (EIP-1559 parity). */
+export declare const DEFAULT_PRIORITY_FEE_DECAY_CAP: bigint;
+/**
+ * Effective per-gas tip a validator sees for one transaction.
+ *
+ * EIP-1559 (has both maxPriority + maxFee):
+ *   tip = min(maxPriorityFeePerGas, maxFeePerGas - baseFee)
+ * Legacy (gasPrice only):
+ *   tip = gasPrice - baseFee   (clamped at 0)
+ *
+ * Returns 0n when fee fields are missing or the math would go negative.
+ */
+export declare const effectiveTip: (tx: RawTx, baseFee: bigint) => bigint;
+/**
+ * p10/p25/p50/p75/p90 from a pre-sorted ascending bigint array. Empty
+ * input returns all-zeros so callers can treat absence-of-data the same
+ * way as a quiet block.
+ */
+export declare const computePercentiles: (sorted: bigint[]) => TipPercentiles;
+/**
+ * Sort a tx array by effective tip (ascending) and return the bigints.
+ * Convenience wrapper so callers don't have to remember the comparator.
+ */
+export declare const sortedTips: (txs: RawTx[], baseFee: bigint) => bigint[];
+/**
+ * Classify a base-fee history as rising, falling, or stable. Threshold
+ * is ±10% comparing first to last value. Single-element or empty input
+ * returns 'stable'.
+ */
+export declare const detectTrend: (history: bigint[]) => Trend;
+/**
+ * Clamp a tip from below by the previously-published tip, decayed at
+ * `decayCap` per block of elapsed time. Upside is unclamped (a real
+ * spike propagates immediately).
+ *
+ * `decayCap` is expressed wad: `parseEther('0.125')` is 12.5% (EIP-1559
+ * parity). `null` disables capping entirely — every cycle publishes the
+ * raw tip with no anchor. `0n` means no decay allowed (last published
+ * is the floor in perpetuity until upside breaks it). `WAD` (1e18)
+ * means full collapse permitted after one block (effectively no floor).
+ *
+ * Pure integer math:
+ *   retention factor per block = (WAD - decayCap) / WAD
+ *   floor = lastPublished * retention^nBlocks
+ *
+ * Cold start (no history) returns `rawTip` verbatim. Same-block
+ * duplicate polls hold the previous value (n ≤ 0 case).
+ */
+export declare const cappedTip: (rawTip: bigint, nowBlockNumber: bigint, lastPublished: bigint | undefined, lastPublishedBlockNumber: bigint | undefined, decayCap?: bigint | null) => bigint;
+/**
+ * Gas-weighted percentile of a tip distribution. Each sample is one
+ * tx's effective tip + its declared gas; gas is the weight. Sort by tip
+ * ascending, walk cumulative gas, return the tip of the first sample
+ * whose running gas crosses `totalGas * p / 100`.
+ *
+ * Why gas-weight rather than count-weight? A 21k-gas spam tx and a
+ * 2M-gas swap exert very different pressure on validator inclusion
+ * choices; treating them as one count each understates the paying
+ * lane's share. The unit miners actually maximize is total tip * gas,
+ * so the gas-weighted distribution is the one our tier recommendations
+ * should reflect.
+ *
+ * Edge cases:
+ *   - Empty samples: every requested percentile returns 0n.
+ *   - totalGas === 0n (only zero-gas samples): same as empty, every
+ *     percentile is 0n.
+ *   - Single sample: every percentile is that sample's tip.
+ *
+ * Bigint-only. No floating-point math; the gas target uses integer
+ * division and is monotone in `p`.
+ */
+export declare const gasWeightedPercentiles: (samples: TipSample[], percentiles: number[]) => Record<number, bigint>;
+/** Default liveness window — one block ahead, matching pre-v0.2 behavior. */
+export declare const DEFAULT_BASE_FEE_LIVENESS_BLOCKS = 1;
+/**
+ * Concatenate ring + mempool samples into one gas-weighted distribution
+ * and read the four tier percentiles from it. Each tier's raw tip is
+ * then clamped from below by the dynamic decay cap (`cappedTip`) so a
+ * single quiet block can't drop the published number off a cliff.
+ *
+ * Why one merged distribution rather than `max(blockTier, mempoolTier)`?
+ * The competitive environment a customer's tx has to clear is the
+ * union of paying-lane txs that just landed and paying-lane txs queued
+ * for the next block. Taking percentiles from each source separately
+ * and `max()`-ing them double-counts spam-lane bias on whichever side
+ * happens to have less gas-weight in the paying lane on a given tick;
+ * gas-weighting the union resolves that without per-source magic.
+ *
+ * `priorityModel: 'eip1559'` further filters the paying-lane tiers
+ * (standard/fast/instant) down to type-2+ samples so legacy spam can't
+ * suppress the recommendation on chains that honor the 1559 cutoff.
+ * `slow` keeps drawing from the full union — it's the lane legacy txs
+ * actually live in, and excluding them would mis-report it.
+ *
+ * `maxFeePerGas` = bufferedBaseFee + cappedTip. `gasPrice` (legacy
+ * fallback) = baseFee + cappedTip. `maxFeePerBlobGas` is null when the
+ * chain doesn't expose `excessBlobGas`.
+ *
+ * Returns the tier objects (for the published snapshot) and the
+ * cappedTip values keyed by tier name (for the producer to persist as
+ * `lastPublishedTips` for the next cycle's cap anchor).
+ */
+export declare const computeTiers: (input: {
+    ringSamples: TipSample[];
+    mempoolSamples: TipSample[];
+    baseFee: bigint;
+    baseFeeTrend: Trend;
+    blob: {
+        blobBaseFee: bigint;
+        trend: Trend;
+    } | null;
+    blockNumber: bigint;
+    lastPublishedTips: Record<TierName, bigint> | undefined;
+    lastPublishedBlockNumber: bigint | undefined;
+    priorityFeeDecayCap?: bigint | null;
+    priorityModel?: PriorityModel;
+    baseFeeLivenessBlocks?: number;
+}) => {
+    tiers: Record<TierName, TierRecommendation>;
+    publishedTips: Record<TierName, bigint>;
+};
+/**
+ * EIP-4844 blob base fee from `excessBlobGas`. Implements the
+ * fake_exponential approximation: `output = factor * e^(num/den)` via
+ * iterative summation until the term goes to zero. Integer-only.
+ *
+ *   MIN_BLOB_BASE_FEE = 1
+ *   BLOB_BASE_FEE_UPDATE_FRACTION = 3338477
+ */
+export declare const computeBlobBaseFee: (excessBlobGas: bigint) => bigint;
+/**
+ * Geth/Reth `txpool_content` returns `pending` and `queued`, each keyed
+ * by sender → nonce → tx. This flattens to a tx array; queued is
+ * usually ignored for tip math (those txs aren't competing for the
+ * next block).
+ */
+export declare const flattenTxPool: (pool: Record<string, Record<string, RawTx>> | undefined | null) => RawTx[];
+//# sourceMappingURL=math.d.ts.map

package/dist/math.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"math.d.ts","sourceRoot":"","sources":["../src/math.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EACV,aAAa,EACb,KAAK,EACL,kBAAkB,EAClB,QAAQ,EACR,cAAc,EACd,SAAS,EACT,KAAK,EACN,MAAM,YAAY,CAAA;AAcnB,wEAAwE;AACxE,eAAO,MAAM,8BAA8B,QAAW,CAAA;AAEtD;;;;;;;;;GASG;AACH,eAAO,MAAM,YAAY,GAAI,IAAI,KAAK,EAAE,SAAS,MAAM,KAAG,MAezD,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,GAAI,QAAQ,MAAM,EAAE,KAAG,cASrD,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,UAAU,GAAI,KAAK,KAAK,EAAE,EAAE,SAAS,MAAM,KAAG,MAAM,EAGhB,CAAA;AAEjD;;;;GAIG;AACH,eAAO,MAAM,WAAW,GAAI,SAAS,MAAM,EAAE,KAAG,KAS/C,CAAA;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,SAAS,GACpB,QAAQ,MAAM,EACd,gBAAgB,MAAM,EACtB,eAAe,MAAM,GAAG,SAAS,EACjC,0BAA0B,MAAM,GAAG,SAAS,EAC5C,WAAU,MAAM,GAAG,IAAqC,KACvD,MAgBF,CAAA;AAeD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,sBAAsB,GACjC,SAAS,SAAS,EAAE,EACpB,aAAa,MAAM,EAAE,KACpB,MAAM,CAAC,MAAM,EAAE,MAAM,CAkCvB,CAAA;AAED,6EAA6E;AAC7E,eAAO,MAAM,gCAAgC,IAAI,CAAA;AAqDjD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,YAAY,GAAI,OAAO;IAClC,WAAW,EAAE,SAAS,EAAE,CAAA;IACxB,cAAc,EAAE,SAAS,EAAE,CAAA;IAC3B,OAAO,EAAE,MAAM,CAAA;IACf,YAAY,EAAE,KAAK,CAAA;IACnB,IAAI,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,KAAK,CAAA;KAAE,GAAG,IAAI,CAAA;IAClD,WAAW,EAAE,MAAM,CAAA;IACnB,iBAAiB,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,GAAG,SAAS,CAAA;IACvD,wBAAwB,EAAE,MAAM,GAAG,SAAS,CAAA;IAC5C,mBAAmB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACnC,aAAa,CAAC,EAAE,aAAa,CAAA;IAC7B,qBAAqB,CAAC,EAAE,MAAM,CAAA;CAC/B,KAAG;IACF,KAAK,EAAE,MAAM,CAAC,QAAQ,EAAE,kBAAkB,CAAC,CAAA;IAC3C,aAAa,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAA;CA4DxC,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,GAAI,eAAe,MAAM,KAAG,MAY1D,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,aAAa,GACxB,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,GAAG,SAAS,GAAG,IAAI,KAC7D,KAAK,EAOP,CAAA"}

package/dist/math.js

@@ -0,0 +1,343 @@
+/**
+ * Pure math primitives for the gas oracle. No I/O, no state — every
+ * function is referentially transparent and exhaustively unit-testable.
+ *
+ * The math is the load-bearing wall: tier recommendations are only as
+ * trustworthy as `effectiveTip` and `cappedTip`, so every edge case
+ * (legacy txs, EIP-1559 with zero headroom, cold-start cap, post-EIP-4844
+ * blob fee) is handled here rather than at higher layers.
+ */
+const TREND_RISING_THRESHOLD_PCT = 10n;
+const TREND_FALLING_THRESHOLD_PCT = -10n;
+/**
+ * 1e18, the EVM-native fixed-point scale. All caller-facing fractional
+ * config knobs are bigints expressed against this scale — i.e.
+ * `parseEther('0.125')` for 12.5%. Internal-only; the public surface
+ * teaches callers to construct values via viem's `parseEther`, not via
+ * a valve-specific WAD export.
+ */
+const WAD = 1000000000000000000n;
+/** Default priority-fee decay cap = 12.5% / block (EIP-1559 parity). */
+export const DEFAULT_PRIORITY_FEE_DECAY_CAP = WAD / 8n;
+/**
+ * Effective per-gas tip a validator sees for one transaction.
+ *
+ * EIP-1559 (has both maxPriority + maxFee):
+ *   tip = min(maxPriorityFeePerGas, maxFeePerGas - baseFee)
+ * Legacy (gasPrice only):
+ *   tip = gasPrice - baseFee   (clamped at 0)
+ *
+ * Returns 0n when fee fields are missing or the math would go negative.
+ */
+export const effectiveTip = (tx, baseFee) => {
+    if (tx.maxFeePerGas && tx.maxPriorityFeePerGas) {
+        const maxFee = BigInt(tx.maxFeePerGas);
+        const maxPriority = BigInt(tx.maxPriorityFeePerGas);
+        const headroom = maxFee - baseFee;
+        if (headroom <= 0n)
+            return 0n;
+        return maxPriority < headroom ? maxPriority : headroom;
+    }
+    if (tx.gasPrice) {
+        const price = BigInt(tx.gasPrice);
+        return price > baseFee ? price - baseFee : 0n;
+    }
+    return 0n;
+};
+/**
+ * p10/p25/p50/p75/p90 from a pre-sorted ascending bigint array. Empty
+ * input returns all-zeros so callers can treat absence-of-data the same
+ * way as a quiet block.
+ */
+export const computePercentiles = (sorted) => {
+    if (sorted.length === 0) {
+        return { p10: 0n, p25: 0n, p50: 0n, p75: 0n, p90: 0n };
+    }
+    const at = (pct) => {
+        const idx = Math.min(Math.floor(sorted.length * pct), sorted.length - 1);
+        return sorted[idx];
+    };
+    return { p10: at(0.1), p25: at(0.25), p50: at(0.5), p75: at(0.75), p90: at(0.9) };
+};
+/**
+ * Sort a tx array by effective tip (ascending) and return the bigints.
+ * Convenience wrapper so callers don't have to remember the comparator.
+ */
+export const sortedTips = (txs, baseFee) => txs
+    .map((tx) => effectiveTip(tx, baseFee))
+    .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+/**
+ * Classify a base-fee history as rising, falling, or stable. Threshold
+ * is ±10% comparing first to last value. Single-element or empty input
+ * returns 'stable'.
+ */
+export const detectTrend = (history) => {
+    if (history.length < 2)
+        return 'stable';
+    const first = history[0];
+    const last = history[history.length - 1];
+    if (first === 0n)
+        return last > 0n ? 'rising' : 'stable';
+    const change = ((last - first) * 100n) / first;
+    if (change > TREND_RISING_THRESHOLD_PCT)
+        return 'rising';
+    if (change < TREND_FALLING_THRESHOLD_PCT)
+        return 'falling';
+    return 'stable';
+};
+/**
+ * Clamp a tip from below by the previously-published tip, decayed at
+ * `decayCap` per block of elapsed time. Upside is unclamped (a real
+ * spike propagates immediately).
+ *
+ * `decayCap` is expressed wad: `parseEther('0.125')` is 12.5% (EIP-1559
+ * parity). `null` disables capping entirely — every cycle publishes the
+ * raw tip with no anchor. `0n` means no decay allowed (last published
+ * is the floor in perpetuity until upside breaks it). `WAD` (1e18)
+ * means full collapse permitted after one block (effectively no floor).
+ *
+ * Pure integer math:
+ *   retention factor per block = (WAD - decayCap) / WAD
+ *   floor = lastPublished * retention^nBlocks
+ *
+ * Cold start (no history) returns `rawTip` verbatim. Same-block
+ * duplicate polls hold the previous value (n ≤ 0 case).
+ */
+export const cappedTip = (rawTip, nowBlockNumber, lastPublished, lastPublishedBlockNumber, decayCap = DEFAULT_PRIORITY_FEE_DECAY_CAP) => {
+    if (decayCap === null)
+        return rawTip;
+    if (lastPublished === undefined || lastPublishedBlockNumber === undefined) {
+        return rawTip;
+    }
+    const nBlocks = nowBlockNumber - lastPublishedBlockNumber;
+    if (nBlocks <= 0n) {
+        return rawTip > lastPublished ? rawTip : lastPublished;
+    }
+    const retain = WAD - decayCap;
+    let factor = WAD;
+    for (let i = 0n; i < nBlocks; i += 1n) {
+        factor = (factor * retain) / WAD;
+    }
+    const downsideFloor = (lastPublished * factor) / WAD;
+    return rawTip > downsideFloor ? rawTip : downsideFloor;
+};
+/**
+ * Tier → percentile target, in the [0, 100] integer space used by
+ * `gasWeightedPercentiles`. `standard` is p50 (the median) so the
+ * recommended tip lands inside the paying lane on bimodal chains rather
+ * than chasing the spam lane at p25.
+ */
+const TIER_PERCENTILE = [
+    ['slow', 10],
+    ['standard', 50],
+    ['fast', 75],
+    ['instant', 90],
+];
+/**
+ * Gas-weighted percentile of a tip distribution. Each sample is one
+ * tx's effective tip + its declared gas; gas is the weight. Sort by tip
+ * ascending, walk cumulative gas, return the tip of the first sample
+ * whose running gas crosses `totalGas * p / 100`.
+ *
+ * Why gas-weight rather than count-weight? A 21k-gas spam tx and a
+ * 2M-gas swap exert very different pressure on validator inclusion
+ * choices; treating them as one count each understates the paying
+ * lane's share. The unit miners actually maximize is total tip * gas,
+ * so the gas-weighted distribution is the one our tier recommendations
+ * should reflect.
+ *
+ * Edge cases:
+ *   - Empty samples: every requested percentile returns 0n.
+ *   - totalGas === 0n (only zero-gas samples): same as empty, every
+ *     percentile is 0n.
+ *   - Single sample: every percentile is that sample's tip.
+ *
+ * Bigint-only. No floating-point math; the gas target uses integer
+ * division and is monotone in `p`.
+ */
+export const gasWeightedPercentiles = (samples, percentiles) => {
+    const out = {};
+    if (samples.length === 0) {
+        for (const p of percentiles)
+            out[p] = 0n;
+        return out;
+    }
+    // Don't mutate the caller's array.
+    const sorted = [...samples].sort((a, b) => a.tip < b.tip ? -1 : a.tip > b.tip ? 1 : 0);
+    let totalGas = 0n;
+    for (const s of sorted)
+        totalGas += s.gas;
+    if (totalGas === 0n) {
+        for (const p of percentiles)
+            out[p] = 0n;
+        return out;
+    }
+    for (const p of percentiles) {
+        const target = (totalGas * BigInt(p)) / 100n;
+        let cumulative = 0n;
+        let chosen = sorted[sorted.length - 1].tip;
+        for (const s of sorted) {
+            cumulative += s.gas;
+            if (cumulative >= target) {
+                chosen = s.tip;
+                break;
+            }
+        }
+        out[p] = chosen;
+    }
+    return out;
+};
+/** Default liveness window — one block ahead, matching pre-v0.2 behavior. */
+export const DEFAULT_BASE_FEE_LIVENESS_BLOCKS = 1;
+/**
+ * Buffer multiplier applied to base fee when computing `maxFeePerGas`.
+ *
+ * EIP-1559 lets base fee change by up to ±12.5% per block, so the
+ * worst-case upper-bound trajectory over `N` blocks is `(9/8)^N`.
+ * Callers who want their published recommendation to remain includable
+ * for longer than one block (e.g. wallets sending into a UI where the
+ * user might take 60+ seconds to confirm) raise `livenessBlocks` to
+ * compound headroom proportionally.
+ *
+ * - Rising markets:  `(9/8)^N * 10/9` — adds an 11% extra margin on
+ *                    top of the worst-case rise (preserves the old
+ *                    1.25:1.125 ratio at N=1).
+ * - Stable markets:  `(9/8)^N` — exact worst-case EIP-1559 trajectory.
+ * - Falling markets: `1×` regardless of N. Base fee will continue to
+ *                    drop, headroom is wasted.
+ *
+ * At `N=1` this matches the pre-v0.2 hardcoded values (1.25 / 1.125 / 1).
+ */
+const baseFeeBufferMultiplier = (trend, livenessBlocks) => {
+    if (trend === 'falling')
+        return { num: 1n, den: 1n };
+    let num = 1n;
+    let den = 1n;
+    for (let i = 0; i < livenessBlocks; i += 1) {
+        num *= 9n;
+        den *= 8n;
+    }
+    if (trend === 'rising') {
+        num *= 10n;
+        den *= 9n;
+    }
+    return { num, den };
+};
+/**
+ * `priorityModel` cutoff: which tx types count as "paying lane."
+ *
+ * A sample is in the paying lane iff its `txType >= EIP1559_TYPE_CUTOFF`
+ * (≥ 2). Samples without a captured `txType` are excluded from the
+ * paying-lane filter — better to under-count than to mis-bucket a
+ * legacy tx into the priority lane and pull the recommendation up.
+ */
+const EIP1559_TYPE_CUTOFF = 2;
+const isPayingLaneSample = (sample) => sample.txType !== undefined && sample.txType >= EIP1559_TYPE_CUTOFF;
+/**
+ * Concatenate ring + mempool samples into one gas-weighted distribution
+ * and read the four tier percentiles from it. Each tier's raw tip is
+ * then clamped from below by the dynamic decay cap (`cappedTip`) so a
+ * single quiet block can't drop the published number off a cliff.
+ *
+ * Why one merged distribution rather than `max(blockTier, mempoolTier)`?
+ * The competitive environment a customer's tx has to clear is the
+ * union of paying-lane txs that just landed and paying-lane txs queued
+ * for the next block. Taking percentiles from each source separately
+ * and `max()`-ing them double-counts spam-lane bias on whichever side
+ * happens to have less gas-weight in the paying lane on a given tick;
+ * gas-weighting the union resolves that without per-source magic.
+ *
+ * `priorityModel: 'eip1559'` further filters the paying-lane tiers
+ * (standard/fast/instant) down to type-2+ samples so legacy spam can't
+ * suppress the recommendation on chains that honor the 1559 cutoff.
+ * `slow` keeps drawing from the full union — it's the lane legacy txs
+ * actually live in, and excluding them would mis-report it.
+ *
+ * `maxFeePerGas` = bufferedBaseFee + cappedTip. `gasPrice` (legacy
+ * fallback) = baseFee + cappedTip. `maxFeePerBlobGas` is null when the
+ * chain doesn't expose `excessBlobGas`.
+ *
+ * Returns the tier objects (for the published snapshot) and the
+ * cappedTip values keyed by tier name (for the producer to persist as
+ * `lastPublishedTips` for the next cycle's cap anchor).
+ */
+export const computeTiers = (input) => {
+    const livenessBlocks = input.baseFeeLivenessBlocks ?? DEFAULT_BASE_FEE_LIVENESS_BLOCKS;
+    const { num: baseNum, den: baseDen } = baseFeeBufferMultiplier(input.baseFeeTrend, livenessBlocks);
+    const bufferedBase = (input.baseFee * baseNum) / baseDen;
+    const blobFee = (() => {
+        if (!input.blob)
+            return null;
+        const { num, den } = baseFeeBufferMultiplier(input.blob.trend, livenessBlocks);
+        return (input.blob.blobBaseFee * num) / den;
+    })();
+    const decayCap = input.priorityFeeDecayCap === undefined
+        ? DEFAULT_PRIORITY_FEE_DECAY_CAP
+        : input.priorityFeeDecayCap;
+    const priorityModel = input.priorityModel ?? 'flat';
+    const combined = [...input.ringSamples, ...input.mempoolSamples];
+    const targets = TIER_PERCENTILE.map(([, p]) => p);
+    // Full-distribution percentiles always exist — `slow` reads from them
+    // regardless of model, so legacy txs find their lane.
+    const fullPercentiles = gasWeightedPercentiles(combined, targets);
+    // Paying-lane percentiles only computed when the model demands them;
+    // saves one pass on the much-more-common 'flat' path.
+    const payingLanePercentiles = priorityModel === 'eip1559'
+        ? gasWeightedPercentiles(combined.filter(isPayingLaneSample), targets)
+        : null;
+    const tiers = {};
+    const publishedTips = {};
+    for (const [name, percentileTarget] of TIER_PERCENTILE) {
+        const useFiltered = payingLanePercentiles !== null && name !== 'slow';
+        const source = useFiltered ? payingLanePercentiles : fullPercentiles;
+        const rawTip = source[percentileTarget];
+        const tip = cappedTip(rawTip, input.blockNumber, input.lastPublishedTips?.[name], input.lastPublishedBlockNumber, decayCap);
+        publishedTips[name] = tip;
+        tiers[name] = {
+            maxPriorityFeePerGas: tip,
+            maxFeePerGas: bufferedBase + tip,
+            gasPrice: input.baseFee + tip,
+            maxFeePerBlobGas: blobFee,
+        };
+    }
+    return { tiers, publishedTips };
+};
+/**
+ * EIP-4844 blob base fee from `excessBlobGas`. Implements the
+ * fake_exponential approximation: `output = factor * e^(num/den)` via
+ * iterative summation until the term goes to zero. Integer-only.
+ *
+ *   MIN_BLOB_BASE_FEE = 1
+ *   BLOB_BASE_FEE_UPDATE_FRACTION = 3338477
+ */
+export const computeBlobBaseFee = (excessBlobGas) => {
+    const BLOB_BASE_FEE_UPDATE_FRACTION = 3338477n;
+    if (excessBlobGas === 0n)
+        return 1n;
+    let output = 0n;
+    let accum = BLOB_BASE_FEE_UPDATE_FRACTION;
+    let i = 1n;
+    while (accum > 0n) {
+        output += accum;
+        accum = (accum * excessBlobGas) / (BLOB_BASE_FEE_UPDATE_FRACTION * i);
+        i += 1n;
+    }
+    return output / BLOB_BASE_FEE_UPDATE_FRACTION;
+};
+/**
+ * Geth/Reth `txpool_content` returns `pending` and `queued`, each keyed
+ * by sender → nonce → tx. This flattens to a tx array; queued is
+ * usually ignored for tip math (those txs aren't competing for the
+ * next block).
+ */
+export const flattenTxPool = (pool) => {
+    if (!pool)
+        return [];
+    const txs = [];
+    for (const byNonce of Object.values(pool)) {
+        for (const tx of Object.values(byNonce))
+            txs.push(tx);
+    }
+    return txs;
+};
+//# sourceMappingURL=math.js.map

package/dist/math.js.map

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

package/dist/mempool.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Pure mempool-inspection helpers.
+ *
+ * `txpool_content` returns a two-level map: sender → nonce → RawTx,
+ * split into `pending` (next-in-line for inclusion) and `queued` (gap
+ * txs that can't mine yet). These helpers find a specific tx in either
+ * sub-pool.
+ *
+ * **Normalize once.** Upstream clients serialize sender addresses
+ * inconsistently — geth/reth use EIP-55 checksum, others lowercase,
+ * some checksum a few hex chars and not others. Doing the case-fold
+ * (and the hex/decimal nonce coercion) on every lookup wastes work
+ * and invites case-mismatch bugs. Instead, callers run
+ * `normalizeMempool(pool)` ONCE at ingest, then pass the normalized
+ * form to every subsequent lookup. Lookups then become direct O(1)
+ * map accesses with no string-case fallback walks.
+ *
+ * The `NormalizedMempool` type signals that contract structurally —
+ * functionally identical to `TxPoolContent`, but the type alias names
+ * the invariant.
+ */
+import type { TxPoolContent } from './transport.js';
+import type { RawTx } from './types.js';
+/**
+ * `TxPoolContent` after a single normalization pass — every sender
+ * address key is lowercase ASCII, every nonce key is a decimal string.
+ * All lookup helpers expect this form; pass raw `TxPoolContent` through
+ * `normalizeMempool` first.
+ */
+export type NormalizedMempool = TxPoolContent;
+/**
+ * Discriminated identifier for a single tx — either by its hash, or by
+ * sender + nonce. Re-used across mempool lookups (`findInMempool`) and
+ * block-position queries (`tipForBlockPosition`) so callers think in
+ * one consistent shape.
+ */
+export type TxIdentifier = {
+    hash: string;
+} | {
+    address: string;
+    nonce: number | bigint | string;
+};
+/** Which sub-pool a hit was found in. */
+export type MempoolBucket = 'pending' | 'queued';
+export interface MempoolHit {
+    /** The tx as returned by `txpool_content`. */
+    tx: RawTx;
+    /** Which sub-pool the tx was found in. */
+    bucket: MempoolBucket;
+    /** Sender address, lowercased. */
+    address: string;
+    /** Tx nonce as a decimal string. */
+    nonce: string;
+}
+/**
+ * Run the upstream `txpool_content` payload through one normalization
+ * pass: lowercase every sender address, decimal-ify every nonce key.
+ * Idempotent — re-normalizing a NormalizedMempool returns an
+ * equivalent NormalizedMempool. Pass `null`/`undefined` to get an
+ * empty NormalizedMempool back (lookup helpers handle null too, but
+ * always-having-a-shape simplifies callers that store the snapshot).
+ */
+export declare const normalizeMempool: (pool: TxPoolContent | null | undefined) => NormalizedMempool;
+/**
+ * Find a tx in `pending` or `queued` by hash. Searches `pending` first
+ * — the common "is my tx going to mine?" question is most often
+ * answered there. Hash comparison is case-insensitive (tx.hash on the
+ * stored RawTx may still be checksum-mixed-case from upstream; we
+ * don't rewrite per-tx fields during pool normalization, only the
+ * outer keys).
+ */
+export declare const findByHash: (pool: NormalizedMempool | null | undefined, hash: string) => MempoolHit | null;
+/**
+ * Find a tx by sender address + nonce. Direct two-key lookup — no
+ * scan, no case-walk, because the pool is normalized at ingest.
+ * `nonce` accepts a number, a decimal string (`'5'`), a hex string
+ * (`'0x5'`), or a bigint. Returns `null` when the pool is null/empty,
+ * the address has no entries, or the address is present but the nonce
+ * isn't.
+ */
+export declare const findByAddressNonce: (pool: NormalizedMempool | null | undefined, address: string, nonce: number | bigint | string) => MempoolHit | null;
+/**
+ * Single-call lookup that takes a discriminated `TxIdentifier`. Use
+ * when you don't statically know which dimension you're querying on
+ * (e.g. wiring up a UI that lets the user paste either a hash or an
+ * address + nonce).
+ */
+export declare const findInMempool: (pool: NormalizedMempool | null | undefined, id: TxIdentifier) => MempoolHit | null;
+//# sourceMappingURL=mempool.d.ts.map

package/dist/mempool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mempool.d.ts","sourceRoot":"","sources":["../src/mempool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AACnD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAEvC;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GAAG,aAAa,CAAA;AAE7C;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GACpB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAA;CAAE,CAAA;AAExD,yCAAyC;AACzC,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,QAAQ,CAAA;AAEhD,MAAM,WAAW,UAAU;IACzB,8CAA8C;IAC9C,EAAE,EAAE,KAAK,CAAA;IACT,0CAA0C;IAC1C,MAAM,EAAE,aAAa,CAAA;IACrB,kCAAkC;IAClC,OAAO,EAAE,MAAM,CAAA;IACf,oCAAoC;IACpC,KAAK,EAAE,MAAM,CAAA;CACd;AAiBD;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,GAC3B,MAAM,aAAa,GAAG,IAAI,GAAG,SAAS,KACrC,iBAGD,CAAA;AAqBF;;;;;;;GAOG;AACH,eAAO,MAAM,UAAU,GACrB,MAAM,iBAAiB,GAAG,IAAI,GAAG,SAAS,EAC1C,MAAM,MAAM,KACX,UAAU,GAAG,IAKf,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,GAC7B,MAAM,iBAAiB,GAAG,IAAI,GAAG,SAAS,EAC1C,SAAS,MAAM,EACf,OAAO,MAAM,GAAG,MAAM,GAAG,MAAM,KAC9B,UAAU,GAAG,IAiBf,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,aAAa,GACxB,MAAM,iBAAiB,GAAG,IAAI,GAAG,SAAS,EAC1C,IAAI,YAAY,KACf,UAAU,GAAG,IAGf,CAAA"}