@valve-tech/gas-oracle 0.7.0 → 0.9.2

package/dist/types.d.ts

@@ -46,11 +46,29 @@ export interface TierRecommendation {
     gasPrice: bigint;
     maxFeePerBlobGas: bigint | null;
 }
-export type Trend = 'rising' | 'falling' | 'stable';
-export type TierName = 'slow' | 'standard' | 'fast' | 'instant';
+export declare const Trend: {
+    readonly rising: "rising";
+    readonly falling: "falling";
+    readonly stable: "stable";
+};
+export type Trend = (typeof Trend)[keyof typeof Trend];
+export declare const TierName: {
+    readonly slow: "slow";
+    readonly standard: "standard";
+    readonly fast: "fast";
+    readonly instant: "instant";
+};
+export type TierName = (typeof TierName)[keyof typeof TierName];
+/**
+ * Canonical tier ordering, slow → instant. Used by helpers that walk the
+ * tier ladder (e.g., `classifyTip` finds the highest tier whose floor a
+ * tip clears; `recommendBumpTier` finds the cheapest tier that clears
+ * the protocol floor + outpace floor). Ordering is load-bearing.
+ */
+export declare const TIER_LADDER: readonly TierName[];
 export interface MempoolStats {
-    pendingCount: number;
-    queuedCount: number;
+    pendingCount: bigint;
+    queuedCount: bigint;
     /** Sum of `tx.gas` across all pending txs — congestion proxy. */
     pendingGasDemand: bigint;
     /** Latest block's gas limit, useful for "pending demand vs. block capacity". */
@@ -104,7 +122,24 @@ export interface TipSample {
  * Future cutoffs can be added (e.g. `'eip4844'` for blob-only priority)
  * without re-interpreting existing values.
  */
-export type PriorityModel = 'flat' | 'eip1559';
+export declare const PriorityModel: {
+    readonly flat: "flat";
+    readonly eip1559: "eip1559";
+};
+export type PriorityModel = (typeof PriorityModel)[keyof typeof PriorityModel];
+/**
+ * EIP-2718 transaction type bytes. Identifier values — never participate
+ * in arithmetic, so they stay `number` per the package-wide bigint
+ * carve-out.
+ */
+export declare const TxType: {
+    readonly legacy: 0;
+    readonly eip2930: 1;
+    readonly eip1559: 2;
+    readonly blob: 3;
+    readonly setCodeAuthorization: 4;
+};
+export type TxType = (typeof TxType)[keyof typeof TxType];
 /**
  * Producer-side toggles: which RPCs the oracle calls upstream each cycle.
  *
@@ -162,6 +197,15 @@ export interface GasOracleState {
      * §7-§9.
      */
     ring: BlockSample[];
+    /**
+     * Live mempool samples used to compute this snapshot's tiers.
+     * Producer-local — wire publishers should strip before serializing
+     * (same convention as `ring`). Consumed by replacement / classification
+     * helpers (e.g., `recommendBumpTier`'s outpace correction) for live-
+     * distribution analysis without re-fetching mempool data. Each poll
+     * replaces this field; no cumulative growth.
+     */
+    mempoolSamples: TipSample[];
     lastPublishedTips?: Record<TierName, bigint>;
     lastPublishedBlockNumber?: bigint;
 }

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -7,5 +7,61 @@
  * bigint values. The caller owns that encoding — this package keeps the
  * canonical numeric form internally.
  */
-export {};
+export const Trend = {
+    rising: 'rising',
+    falling: 'falling',
+    stable: 'stable',
+};
+export const TierName = {
+    slow: 'slow',
+    standard: 'standard',
+    fast: 'fast',
+    instant: 'instant',
+};
+/**
+ * Canonical tier ordering, slow → instant. Used by helpers that walk the
+ * tier ladder (e.g., `classifyTip` finds the highest tier whose floor a
+ * tip clears; `recommendBumpTier` finds the cheapest tier that clears
+ * the protocol floor + outpace floor). Ordering is load-bearing.
+ */
+export const TIER_LADDER = [
+    TierName.slow,
+    TierName.standard,
+    TierName.fast,
+    TierName.instant,
+];
+/**
+ * Where the chain's inclusion logic draws its priority cutoff in the
+ * tx-type space.
+ *
+ * - `'flat'`     — chain ignores the EIP-2718 type byte for ordering.
+ *                  Tiers derive from a single gas-weighted distribution
+ *                  across all txs. Right for extractive validators
+ *                  (PulseChain et al.) where the only signal that matters
+ *                  is fee per gas, regardless of tx envelope.
+ * - `'eip1559'`  — type 2+ txs get priority. Paying-lane tiers
+ *                  (standard/fast/instant) derive from type-2+ samples
+ *                  only; `slow` still draws from the full distribution
+ *                  so legacy senders find their lane. Right for chains
+ *                  that honor the 1559 fee-market shape.
+ *
+ * Future cutoffs can be added (e.g. `'eip4844'` for blob-only priority)
+ * without re-interpreting existing values.
+ */
+export const PriorityModel = {
+    flat: 'flat',
+    eip1559: 'eip1559',
+};
+/**
+ * EIP-2718 transaction type bytes. Identifier values — never participate
+ * in arithmetic, so they stay `number` per the package-wide bigint
+ * carve-out.
+ */
+export const TxType = {
+    legacy: 0,
+    eip2930: 1,
+    eip1559: 2,
+    blob: 3,
+    setCodeAuthorization: 4,
+};
 //# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AA4CH,MAAM,CAAC,MAAM,KAAK,GAAG;IACnB,MAAM,EAAE,QAAQ;IAChB,OAAO,EAAE,SAAS;IAClB,MAAM,EAAE,QAAQ;CACR,CAAA;AAGV,MAAM,CAAC,MAAM,QAAQ,GAAG;IACtB,IAAI,EAAE,MAAM;IACZ,QAAQ,EAAE,UAAU;IACpB,IAAI,EAAE,MAAM;IACZ,OAAO,EAAE,SAAS;CACV,CAAA;AAGV;;;;;GAKG;AACH,MAAM,CAAC,MAAM,WAAW,GAAwB;IAC9C,QAAQ,CAAC,IAAI;IACb,QAAQ,CAAC,QAAQ;IACjB,QAAQ,CAAC,IAAI;IACb,QAAQ,CAAC,OAAO;CACR,CAAA;AA2CV;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,IAAI,EAAE,MAAM;IACZ,OAAO,EAAE,SAAS;CACV,CAAA;AAGV;;;;GAIG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG;IACpB,MAAM,EAAE,CAAC;IACT,OAAO,EAAE,CAAC;IACV,OAAO,EAAE,CAAC;IACV,IAAI,EAAE,CAAC;IACP,oBAAoB,EAAE,CAAC;CACf,CAAA"}

package/dist/viem-transport.d.ts

@@ -32,7 +32,7 @@
  */
 import { type Transport } from 'viem';
 import { type CreateGasOracleOptions } from './oracle.js';
-import type { TierName } from './types.js';
+import { TierName } from './types.js';
 export interface InterceptOptions {
     /**
      * Additive multi-tier read. Returns `{ baseFee, tiers: { slow, standard,

package/dist/viem-transport.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"viem-transport.d.ts","sourceRoot":"","sources":["../src/viem-transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,EAAU,KAAK,SAAS,EAAE,MAAM,MAAM,CAAA;AAE7C,OAAO,EAAmB,KAAK,sBAAsB,EAAkB,MAAM,aAAa,CAAA;AAC1F,OAAO,KAAK,EAAkB,QAAQ,EAAsB,MAAM,YAAY,CAAA;AAE9E,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAA;IAC5B;;;;;OAKG;IACH,YAAY,CAAC,EAAE,QAAQ,GAAG,KAAK,CAAA;IAC/B;;;OAGG;IACH,wBAAwB,CAAC,EAAE,QAAQ,GAAG,KAAK,CAAA;CAC5C;AAED,MAAM,WAAW,oBAAqB,SAAQ,IAAI,CAAC,sBAAsB,EAAE,QAAQ,CAAC;IAClF;;;;OAIG;IACH,SAAS,CAAC,EAAE,gBAAgB,CAAA;IAC5B;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,GAAG,MAAM,CAAA;CAC7B;AAED,MAAM,MAAM,kBAAkB,GAAG,SAAS,GAAG;IAAE,aAAa,EAAE,MAAM,IAAI,CAAA;CAAE,CAAA;AA8G1E;;;;;;;;;;GAUG;AACH,eAAO,MAAM,aAAa,GACxB,gBAAgB,SAAS,EACzB,SAAS,oBAAoB,KAC5B,kBAyCF,CAAA"}
+{"version":3,"file":"viem-transport.d.ts","sourceRoot":"","sources":["../src/viem-transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,EAAU,KAAK,SAAS,EAAE,MAAM,MAAM,CAAA;AAE7C,OAAO,EAAmB,KAAK,sBAAsB,EAAkB,MAAM,aAAa,CAAA;AAC1F,OAAO,EAAE,QAAQ,EAAwD,MAAM,YAAY,CAAA;AAE3F,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAA;IAC5B;;;;;OAKG;IACH,YAAY,CAAC,EAAE,QAAQ,GAAG,KAAK,CAAA;IAC/B;;;OAGG;IACH,wBAAwB,CAAC,EAAE,QAAQ,GAAG,KAAK,CAAA;CAC5C;AAED,MAAM,WAAW,oBAAqB,SAAQ,IAAI,CAAC,sBAAsB,EAAE,QAAQ,CAAC;IAClF;;;;OAIG;IACH,SAAS,CAAC,EAAE,gBAAgB,CAAA;IAC5B;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,GAAG,MAAM,CAAA;CAC7B;AAED,MAAM,MAAM,kBAAkB,GAAG,SAAS,GAAG;IAAE,aAAa,EAAE,MAAM,IAAI,CAAA;CAAE,CAAA;AAmH1E;;;;;;;;;;GAUG;AACH,eAAO,MAAM,aAAa,GACxB,gBAAgB,SAAS,EACzB,SAAS,oBAAoB,KAC5B,kBAyCF,CAAA"}

package/dist/viem-transport.js

@@ -32,6 +32,7 @@
  */
 import { custom } from 'viem';
 import { createGasOracle } from './oracle.js';
+import { TierName, TxType } from './types.js';
 /**
  * Sentinel returned by `dispatchIntercept` when no intercept matched
  * and the request should be passed through to the inner transport.
@@ -40,23 +41,28 @@ import { createGasOracle } from './oracle.js';
  */
 const PASSTHROUGH = Symbol('gas-oracle:passthrough');
 const toHex = (n) => '0x' + n.toString(16);
-const TIER_NAMES = ['instant', 'fast', 'standard', 'slow'];
+const TIER_NAMES = [
+    TierName.instant,
+    TierName.fast,
+    TierName.standard,
+    TierName.slow,
+];
 /**
  * Format a single tier for the `eth_gasFeeEstimate` response, scoped
  * to the requested tx type. Mirrors the relay's `gas-intercept.ts`
  * formatter so consumers of either surface get identical wire shapes.
  */
 const formatTier = (tier, txType) => {
-    if (txType === 0 || txType === 1) {
+    if (txType === TxType.legacy || txType === TxType.eip2930) {
         return { gasPrice: toHex(tier.gasPrice) };
     }
-    if (txType === 2 || txType === 4) {
+    if (txType === TxType.eip1559 || txType === TxType.setCodeAuthorization) {
         return {
             maxFeePerGas: toHex(tier.maxFeePerGas),
             maxPriorityFeePerGas: toHex(tier.maxPriorityFeePerGas),
         };
     }
-    if (txType === 3) {
+    if (txType === TxType.blob) {
         return {
             maxFeePerGas: toHex(tier.maxFeePerGas),
             maxPriorityFeePerGas: toHex(tier.maxPriorityFeePerGas),
@@ -85,7 +91,7 @@ const buildGasFeeEstimate = (state, params) => {
         baseFeeTrend: state.baseFeeTrend,
         blockNumber: toHex(state.blockNumber),
         lastUpdated: toHex(state.timestamp),
-        mempoolPendingCount: state.mempool.pendingCount,
+        mempoolPendingCount: Number(state.mempool.pendingCount),
         tiers,
     };
     if (state.blob)

package/dist/viem-transport.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@valve-tech/gas-oracle",
-  "version": "0.7.0",
+  "version": "0.9.2",
   "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/evm-toolkit/tree/main/packages/gas-oracle#readme",
@@ -59,7 +59,7 @@
     "prepare": "yarn build"
   },
   "dependencies": {
-    "@valve-tech/chain-source": "^0.7.0"
+    "@valve-tech/chain-source": "^0.9.2"
   },
   "peerDependencies": {
     "viem": "^2.0.0"

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

@@ -10,6 +10,8 @@ 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.
 
+> **v0.8.0 default change**: `priorityModel` now defaults to `PriorityModel.eip1559` (was `flat`). Examples that previously omitted the field silently get the new default. Set `PriorityModel.flat` explicitly for PulseChain (chain 369) — or use `...chainPresets.pulsechain`.
+
 ## Decision tree: which integration to use
 
 ```
@@ -30,13 +32,13 @@ Is the user already passing a viem PublicClient around?
 
 | 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. |
+| Ethereum mainnet | 1 | `PriorityModel.eip1559` (default) | 6 | Validators burn base fee. |
+| Base | 8453 | `PriorityModel.eip1559` (default) | 6 | Same as ETH. |
+| Arbitrum One | 42161 | `PriorityModel.eip1559` (default) | 6 | |
+| Optimism | 10 | `PriorityModel.eip1559` (default) | 6 | |
+| PulseChain mainnet | 369 | `PriorityModel.flat` | 6 | Validators charge tips. Use `...chainPresets.pulsechain`. |
+| PulseChain testnet v4 | 943 | `PriorityModel.flat` | 6 | |
+| Unknown / unsure | — | `PriorityModel.eip1559` (default) | 6 | Default is correct unless you've verified the chain is extractive. |
 
 `priorityFeeDecayCap`: leave at default (`WAD/8` = 12.5%/block, EIP-1559
 parity) unless you have a specific reason to tighten/loosen.
@@ -59,11 +61,12 @@ When reviewing user code, watch for these and suggest fixes:
    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.
+4. **Using `PriorityModel.eip1559` on PulseChain or other tip-charging
+   chains.** This is now the default — silent footgun on chain 369
+   unless you set `PriorityModel.flat` (or use `...chainPresets.pulsechain`).
+   It 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
@@ -89,6 +92,96 @@ import { withGasOracle } from '@valve-tech/gas-oracle/viem-transport'
 
 `package.json` will show `"@valve-tech/gas-oracle": "^0.2.x"` in dependencies.
 
+## Replacement workflow — bumping a stuck tx
+
+When the user has a stuck tx and asks how to bump / speed it up,
+recommend the `recommendBumpTier` + `bumpForReplacement` pair. This is
+the canonical caller pattern; don't roll your own +10% math:
+
+```ts
+import {
+  recommendBumpTier,
+  bumpForReplacement,
+  BumpStrategy,
+} from '@valve-tech/gas-oracle'
+
+const tier = recommendBumpTier(
+  state,
+  { priorityTip: stuck.maxPriorityFeePerGas, identifier: { hash: stuck.hash } },
+  { strategy: BumpStrategy.cheapestThatLands },  // default
+)
+if (tier === null) return  // already paying above top tier — caller's call
+
+const target = state.tiers[tier]
+const gas = bumpForReplacement(
+  { maxFeePerGas: stuck.maxFeePerGas, maxPriorityFeePerGas: stuck.maxPriorityFeePerGas },
+  { maxFeePerGas: target.maxFeePerGas, maxPriorityFeePerGas: target.maxPriorityFeePerGas },
+)
+walletClient.sendTransaction({ ...stuck, ...gas })
+```
+
+`recommendBumpTier` reads `state.mempoolSamples` to compute outpace
+correction (when an `identifier` is supplied) on top of the EIP-1559
++10% protocol floor. `bumpForReplacement` returns a gas object that
+satisfies BOTH the protocol floor and the target tier — never one or
+the other.
+
+## Tip classification
+
+Inverse of `tipForBlockPosition`. Given a tip, ask "where would this
+land?" instead of "what tip do I need to land here?":
+
+```ts
+import { classifyTip } from '@valve-tech/gas-oracle'
+
+const result = classifyTip(state, myTip)
+// result.tier                 — TierName | null (null if below slow)
+// result.requiredForNextTier  — bigint floor of next tier above (null at instant)
+// result.percentile           — bigint 0-100 (0 = top, 100 = bottom)
+// result.rank                 — bigint 0-indexed from top
+// result.gasFromTop           — bigint accumulated gas above this tip
+```
+
+Useful for "your fee is low — bump?" UX nudges and for showing a
+user where their existing in-flight tx sits vs. live competition.
+
+## UI labels
+
+Branded / localized inclusion-time copy without forking the package:
+
+```ts
+import { defaultInclusionLabels, inclusionLabel, TierName } from '@valve-tech/gas-oracle'
+
+defaultInclusionLabels[TierName.standard]   // 'Next block'
+
+const es = { [TierName.standard]: 'Próximo bloque' }
+inclusionLabel(TierName.standard, es)        // 'Próximo bloque'
+inclusionLabel(TierName.slow, es)            // falls back to default English
+```
+
+Pass partial overrides — anything not in the override map falls back
+to the package default.
+
+## Chain presets
+
+For PulseChain (and any future entries we ship), use the preset entry
+points instead of typing `chainId` + `priorityModel` by hand:
+
+```ts
+import { createGasOracle, chainPresets, presetForChainId } from '@valve-tech/gas-oracle'
+
+// Static — caller knows which chain at code-time:
+createGasOracle({ client, ...chainPresets.pulsechain })
+
+// Dynamic — caller has chainId at runtime (e.g. from wallet):
+const preset = presetForChainId(chainId)
+createGasOracle({ client, chainId, ...preset })
+```
+
+`presetForChainId` returns `undefined` for unknown chains; spreading
+`undefined` into the options object is a no-op, so the call still works
+on a chain we haven't preset (it just gets the package defaults).
+
 ## Where to find more
 
 - Full API + types: `node_modules/@valve-tech/gas-oracle/AGENTS.md`