@valve-tech/gas-oracle 0.6.0 → 0.8.0

package/dist/replacement.js

@@ -0,0 +1,114 @@
+/**
+ * Same-nonce EIP-1559 replacement helpers. Pure functions; no I/O.
+ *
+ * The protocol-replacement-floor math is verified against geth
+ * `core/txpool/legacypool/list.go:Add()`, geth `core/txpool/blobpool/
+ * config.go`, reth `crates/transaction-pool/src/config.rs`, and PulseChain
+ * `gitlab.com/pulsechaincom/go-pulse/master/core/txpool/legacypool/
+ * legacypool.go`. The `+1n` term in `minimumReplacementFee` is load-
+ * bearing for small `current` values where geth's integer-floor threshold
+ * collapses below the strict `old < tx` check.
+ */
+import { TIER_LADDER, TierName, TxType } from './types.js';
+import { tipForBlockPosition } from './block-position.js';
+export const ReplacementBumpPercent = {
+    /** geth `legacypool.DefaultConfig.PriceBump` — legacy / EIP-2930 / EIP-1559 / EIP-7702. */
+    default: 10n,
+    /** geth `blobpool.DefaultConfig.PriceBump` — EIP-4844 blob txs. */
+    blob: 100n,
+};
+/**
+ * Minimum fee required to replace a tx at a given current fee. Per-field
+ * primitive — apply once to `maxFeePerGas` and once to
+ * `maxPriorityFeePerGas` for an EIP-1559 replacement.
+ *
+ * Returns `(current * (100 + bump)) / 100 + 1`, where `bump` is `100n`
+ * for blob txs and `10n` otherwise. The `+1` clears geth's strict
+ * `old < tx` check at small `current` values where the integer-floor
+ * threshold collapses (e.g. `current=1`, `floor(1.1)=1`).
+ *
+ * Unknown future tx-type bytes default to the legacy/1559 +10% bump —
+ * the +100% rule is blob-specific.
+ */
+export const minimumReplacementFee = (current, txType) => {
+    const bump = txType === TxType.blob
+        ? ReplacementBumpPercent.blob
+        : ReplacementBumpPercent.default;
+    return (current * (100n + bump)) / 100n + 1n;
+};
+/**
+ * Compute (maxFeePerGas, maxPriorityFeePerGas) for replacing a 1559 tx.
+ * Per-field rule: max(target, protocolFloor). Final guard ensures
+ * `result.maxFeePerGas >= result.maxPriorityFeePerGas` so the result is
+ * a well-formed tx even on degenerate target inputs.
+ *
+ * 1559-scoped — for blob replacement use `minimumReplacementFee(_,
+ * TxType.blob)` directly per fee field.
+ */
+export const bumpForReplacement = (currentGas, targetGas) => {
+    const maxFeeFloor = minimumReplacementFee(currentGas.maxFeePerGas, TxType.eip1559);
+    const priorityFloor = minimumReplacementFee(currentGas.maxPriorityFeePerGas, TxType.eip1559);
+    const maxPriorityFeePerGas = targetGas.maxPriorityFeePerGas > priorityFloor
+        ? targetGas.maxPriorityFeePerGas
+        : priorityFloor;
+    let maxFeePerGas = targetGas.maxFeePerGas > maxFeeFloor ? targetGas.maxFeePerGas : maxFeeFloor;
+    if (maxFeePerGas < maxPriorityFeePerGas)
+        maxFeePerGas = maxPriorityFeePerGas;
+    return { maxFeePerGas, maxPriorityFeePerGas };
+};
+export const BumpStrategy = {
+    cheapestThatLands: 'cheapestThatLands',
+    oneStepFasterThanRecommended: 'oneStepFasterThanRecommended',
+    instant: 'instant',
+};
+/**
+ * Pick a tier to bump to for a same-nonce EIP-1559 replacement. The
+ * effective floor is `max(protocolFloor, outpaceFloor)`:
+ *   - protocolFloor = `minimumReplacementFee(stuckTx.priorityTip,
+ *     TxType.eip1559)` — the geth +10% rule.
+ *   - outpaceFloor = the tip required to be ranked strictly above every
+ *     tx currently ahead of `stuckTx.identifier` in
+ *     `snapshot.mempoolSamples`. Computed by locating stuck's rank via
+ *     `tipForBlockPosition({ kind: 'aheadOf', tx: identifier })` then
+ *     querying `{ kind: 'rank', rank: stuckRank - 1n }` to outbid the
+ *     tx currently just above stuck. When stuck is already at the top
+ *     of the distribution (or not present), this is `0n` and only the
+ *     protocol floor applies.
+ *
+ * Returns `null` when no tier clears the effective floor — the original
+ * was already paying above the top of the ladder, or the snapshot has
+ * no tip data.
+ */
+export const recommendBumpTier = (snapshot, stuckTx, options = {}) => {
+    const strategy = options.strategy ?? BumpStrategy.cheapestThatLands;
+    const protocolFloor = minimumReplacementFee(stuckTx.priorityTip, TxType.eip1559);
+    const outpaceFloor = stuckTx.identifier
+        ? (() => {
+            const stuckPosition = tipForBlockPosition(snapshot.mempoolSamples, {
+                kind: 'aheadOf',
+                tx: stuckTx.identifier,
+            });
+            // Stuck not in mempool, or stuck already at rank 0 (no one above).
+            if (stuckPosition.pivot === null || stuckPosition.rank === 0n)
+                return 0n;
+            // Outbid the tx at rank `stuckRank - 1` (the cheapest tx
+            // currently ahead of stuck) — landing here is sufficient to
+            // outpace every tx currently above stuck.
+            return tipForBlockPosition(snapshot.mempoolSamples, {
+                kind: 'rank',
+                rank: stuckPosition.rank - 1n,
+            }).requiredTip;
+        })()
+        : 0n;
+    const floor = protocolFloor > outpaceFloor ? protocolFloor : outpaceFloor;
+    const cheapestIndex = TIER_LADDER.findIndex((tier) => snapshot.tiers[tier].maxPriorityFeePerGas > floor);
+    if (cheapestIndex === -1)
+        return null;
+    if (strategy === BumpStrategy.cheapestThatLands)
+        return TIER_LADDER[cheapestIndex];
+    if (strategy === BumpStrategy.instant)
+        return TierName.instant;
+    // oneStepFasterThanRecommended
+    return TIER_LADDER[Math.min(cheapestIndex + 1, TIER_LADDER.length - 1)];
+};
+//# sourceMappingURL=replacement.js.map

package/dist/replacement.js.map

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

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.6.0",
+  "version": "0.8.0",
   "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.6.0"
+    "@valve-tech/chain-source": "^0.8.0"
   },
   "peerDependencies": {
     "viem": "^2.0.0"

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

@@ -1,6 +1,6 @@
 ---
 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.
+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, 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. Also fires when the user asks about composing the oracle with `@valve-tech/tx-tracker` over a shared `ChainSource` — but actual per-tx tracking work belongs in the tx-tracker skill, not here.
 ---
 
 # Integrating `@valve-tech/gas-oracle`
@@ -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`
@@ -96,3 +189,56 @@ import { withGasOracle } from '@valve-tech/gas-oracle/viem-transport'
 - 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.
+
+## Tx tracking — composing with `@valve-tech/tx-tracker`
+
+When the user asks to "track this transaction," "watch tx hash,"
+"know when my tx confirms," or "detect stuck transactions," redirect
+them to `@valve-tech/tx-tracker` (sibling package). The gas oracle
+does NOT track per-tx state — that's a separate concern with its own
+state machine, retention policy, and consumption shapes. See
+`node_modules/@valve-tech/tx-tracker/skills/tx-tracker-integration/SKILL.md`
+for the full integration recipe.
+
+The two packages are designed to share one upstream RPC stream:
+
+```ts
+import { createChainSource } from '@valve-tech/chain-source'
+import { createGasOracle }   from '@valve-tech/gas-oracle'
+import { createTxTracker }   from '@valve-tech/tx-tracker'
+
+const source  = createChainSource({ client })
+const oracle  = createGasOracle({ source, chainId: 1 })
+const tracker = createTxTracker({ source, chainId: 1 })
+
+source.start(); oracle.start(); tracker.start()
+```
+
+`ChainSource` owns the upstream poll cycle. The oracle reads it for
+tier reduction; the tracker reads it for per-tx observations. **One
+upstream RPC poll cycle, two derived views** (per spec §3.1). Each
+surface owns its own lifecycle — `oracle.stop()` does not stop the
+source or the tracker.
+
+### Anti-patterns when both are present
+
+7. **Constructing a private `ChainSource` for the tracker AND passing
+   `client` (not `source`) to `createGasOracle`.** That gives you two
+   independent sources for the same chain — double the RPC traffic
+   for no functional benefit. Either pass `source` to BOTH, or use
+   the `client` shorthand on BOTH (one private source on the oracle's
+   side, no tracker — meaningless if you want both).
+
+8. **Asking the gas oracle "is my tx confirmed?"** Wrong layer. The
+   oracle publishes tier recommendations; it does not observe per-tx
+   state. Use `tracker.getTxStatus(hash)` or
+   `tracker.subscribe(hash, cb)` from `@valve-tech/tx-tracker`.
+
+### Recognizing both packages in the user's code
+
+```ts
+import { createGasOracle } from '@valve-tech/gas-oracle'
+import { createTxTracker } from '@valve-tech/tx-tracker'
+// `package.json` will have both under dependencies, plus
+// `@valve-tech/chain-source` (the shared foundation both consume).
+```