@valve-tech/gas-oracle 0.6.0 → 0.8.0

package/CHANGELOG.md

@@ -5,6 +5,60 @@ All notable changes to `@valve-tech/gas-oracle` are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/).
 
+## [0.8.0] — 2026-05-06
+
+Consumes `@valve-tech/chain-source@0.8.0`'s WS-aware `ChainSource` transparently. Adds upstream helpers (replacement / classifyTip / inclusion labels), chain presets (PulseChain), const-namespace exports, and a bigint migration of public numeric fields.
+
+### Added
+
+- **Replacement helpers** (`replacement.ts`): `minimumReplacementFee(current, txType)`, `bumpForReplacement(currentGas, targetGas)`, `recommendBumpTier(snapshot, stuckTx, options?)` with three named strategies (`BumpStrategy.cheapestThatLands` / `oneStepFasterThanRecommended` / `instant`). Outpace correction via optional `stuckTx.identifier` reads `snapshot.mempoolSamples` to find the tip needed to outpace the stuck tx in the live distribution, on top of the EIP-1559 +10% protocol floor (verified against geth/reth/PulseChain go-pulse sources).
+- **`classifyTip(snapshot, tipWei)`** (`classify-tip.ts`): inverse of `tipForBlockPosition`. Returns `{ tier, requiredForNextTier, percentile, rank, gasFromTop }`.
+- **Inclusion labels** (`inclusion-labels.ts`): `defaultInclusionLabels` (Record<TierName, string>) and `inclusionLabel(tier, overrides?)` for locale/branded copy without forking.
+- **Chain presets** (`presets.ts`): `chainPresets.pulsechain` (chainId: 369, priorityModel: PriorityModel.flat) plus `presetForChainId(chainId)` runtime lookup.
+- **Const-namespace exports**: `PriorityModel`, `TierName`, `Trend`, `TxType` are now exported as both values (const namespaces) and types. Use `PriorityModel.flat` instead of `'flat'` etc. `TIER_LADDER` (canonical slow→instant ordering) also exported from `types.ts`.
+- **`mempoolSamples: TipSample[]`** on `GasOracleState`. Producer-local — wire publishers should strip before serializing (same convention as `ring`).
+
+### Changed
+
+- **`priorityModel` default flips from `'flat'` to `PriorityModel.eip1559`**. Most chains honor the EIP-2718 type byte and the EIP-1559 fee-market; the default is now correct for the majority case. PulseChain (chain 369) becomes the explicit exception — set `priorityModel: PriorityModel.flat` (or use `...chainPresets.pulsechain`).
+- **BigInt migration of public numeric fields**: `MempoolStats.pendingCount`, `MempoolStats.queuedCount`, `BlockPositionQuery.rank`, `BlockPositionQuery.percentile`, `BlockPositionResult.rank`, `CreateGasOracleOptions.pollIntervalMs` are now `bigint`. Identifier-like fields (`chainId`, EIP-2718 type bytes) stay `number`.
+
+### Migration notes
+
+- Examples that previously omitted `priorityModel` silently get `PriorityModel.eip1559` after upgrade. Verify against your target chain.
+- Math operations on the migrated bigint fields need `n` literals (`0n`, `1n`, etc.) and integer-floor division semantics.
+- `pollIntervalMs: 5000` becomes `pollIntervalMs: 5000n`.
+
+## [0.7.0] — 2026-05-06
+
+### Changed
+
+- **`skills/gas-oracle-integration/SKILL.md`** — appended a "Tx
+  tracking — composing with `@valve-tech/tx-tracker`" section that
+  redirects per-tx tracking questions to the sibling package and
+  documents the shared-`ChainSource` composition pattern. The skill
+  `description` trigger phrases now also catch composition questions,
+  but per-tx work explicitly defers to the tx-tracker skill. Ships
+  in the npm tarball.
+- **Coverage hardening pre-1.0.** Test suite up from 189 → 209 tests
+  (+20). New coverage: `sampleGasFees` one-shot snapshot path
+  (success + null + error-routing variants), `tipForBlockPosition`
+  with full mempool data (EIP-1559 + legacy + 0-headroom + no-gas
+  + no-fee branches in the mempool→TipSample translation),
+  `formatTier` for tx types 0/1/2/3 plus the no-type fallback —
+  with and without blob fees in tier state, `keepMempoolSnapshot:
+  true` retention, `pauseWhenIdle` re-subscribe inside the stale
+  window keeping the loop alive, `fetchHeadBlockNumber` happy /
+  null-from-RPC / throw / un-decodable variants. Eliminated dead
+  defensive arms in `math.ts` / `block-position.ts` sort
+  comparators (equal-key arms unreachable since duplicates are
+  filtered upstream) and in `oracle.ts` `attachToSource` (stale-
+  timer clear is unreachable because every detach path that sets
+  the timer also keeps `unsubBlocks !== null`, which makes
+  `attachToSource` early-return before the clear).
+- Coverage went **91.91% / 84.75% / 93.18% / 93.9%** stmts /
+  branches / funcs / lines → **98.26% / 93.47% / 100% / 99.8%**.
+
 ## [0.6.0] — 2026-05-05
 
 ### Added

package/README.md

@@ -28,7 +28,7 @@ yarn add @valve-tech/gas-oracle viem
 ```ts
 import { createPublicClient, http, parseEther } from 'viem'
 import { mainnet } from 'viem/chains'
-import { createGasOracle } from '@valve-tech/gas-oracle'
+import { createGasOracle, PriorityModel } from '@valve-tech/gas-oracle'
 
 const client = createPublicClient({ chain: mainnet, transport: http() })
 
@@ -36,7 +36,7 @@ const oracle = createGasOracle({
   client,
   chainId: 1,
   priorityFeeDecayCap: parseEther('0.125'), // 12.5%/block, EIP-1559 parity
-  priorityModel: 'eip1559',                 // 'flat' for chains whose validators charge tips instead of burning them
+  // priorityModel defaults to PriorityModel.eip1559 — explicit only if you need to override
 })
 
 oracle.subscribe((state) => {
@@ -73,7 +73,7 @@ Tier mapping in the gas-weighted percentile distribution:
 
 `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`/
+`PriorityModel.eip1559`, the paying-lane tiers (`standard`/`fast`/
 `instant`) draw from type-2+ samples only — legacy spam can't suppress
 them.
 
@@ -95,19 +95,32 @@ priorityFeeDecayCap: null                  // uncapped — track raw mempool
 Validated at construction; out-of-range values throw. Upside is always
 unclamped — real spikes propagate immediately.
 
-### `priorityModel`
+### Choosing `priorityModel`
 
-Where the chain's inclusion logic draws its priority cutoff in the
-EIP-2718 type space:
+The default is `PriorityModel.eip1559` and is correct for every chain whose validators honor the EIP-2718 type byte and the EIP-1559 fee-market shape. **You should only override this if you've verified your target chain's validators are extractive** — that is, they ignore the type byte and maximize fee per gas regardless of tx envelope.
 
-- `'flat'` — every tx contributes equally to the gas-weighted
+The canonical example is **PulseChain (chain 369)**: extractive validators mean the percentile math has to draw from the full tx distribution (`PriorityModel.flat`) instead of filtering to type-2+ samples. Setting the wrong model here silently under-prices, and your tx stalls.
+
+For chains we know about, the `chainPresets` entry-point handles this for you:
+
+```ts
+import { createGasOracle, chainPresets } from '@valve-tech/gas-oracle'
+
+const oracle = createGasOracle({
+  client,
+  ...chainPresets.pulsechain,   // chainId: 369, priorityModel: PriorityModel.flat
+})
+```
+
+Mechanics:
+
+- `PriorityModel.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).
+- `PriorityModel.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).
 
 ### `baseFeeLivenessBlocks`
 
@@ -240,12 +253,12 @@ For callers who need a single fee snapshot without a long-lived
 oracle (typical tx-submit flow):
 
 ```ts
-import { sampleGasFees } from '@valve-tech/gas-oracle'
+import { sampleGasFees, PriorityModel } from '@valve-tech/gas-oracle'
 
 const snapshot = await sampleGasFees({
   client,
   chainId: 1,
-  priorityModel: 'eip1559',
+  priorityModel: PriorityModel.eip1559,
 })
 const tip = snapshot?.tiers.fast.maxPriorityFeePerGas
 ```
@@ -309,6 +322,90 @@ the same union `computeTiers` reads. The viem-actions extension
 exposes `client.tipForBlockPosition(query)` which assembles this
 distribution for you from the oracle's state.
 
+## Replacement workflow
+
+When a tx gets stuck and you need to bump it past the EIP-1559 protocol
+replacement floor (and optionally past the live mempool distribution):
+
+```ts
+import {
+  createGasOracle,
+  recommendBumpTier,
+  bumpForReplacement,
+  BumpStrategy,
+} from '@valve-tech/gas-oracle'
+
+// 1. Pick a tier to bump to:
+const tier = recommendBumpTier(
+  state,
+  { priorityTip: stuckTx.maxPriorityFeePerGas, identifier: { hash: stuckTx.hash } },
+  { strategy: BumpStrategy.cheapestThatLands },
+)
+
+if (tier === null) {
+  // Stuck tx is already paying above the top of the tier ladder, or
+  // the snapshot has no tip data. Caller's call: hold, or push instant.
+  return
+}
+
+// 2. Compute the gas object that satisfies both the protocol floor and the target tier:
+const target = state.tiers[tier]
+const gas = bumpForReplacement(
+  { maxFeePerGas: stuckTx.maxFeePerGas, maxPriorityFeePerGas: stuckTx.maxPriorityFeePerGas },
+  { maxFeePerGas: target.maxFeePerGas, maxPriorityFeePerGas: target.maxPriorityFeePerGas },
+)
+
+// 3. Send the replacement
+walletClient.sendTransaction({ ...stuckTx, ...gas })
+```
+
+## Tip classification
+
+Inverse of `tipForBlockPosition`: given a tip, find where it lands in the
+live distribution and which named tier it falls in.
+
+```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
+```
+
+## UI labels
+
+```ts
+import { defaultInclusionLabels, inclusionLabel, TierName } from '@valve-tech/gas-oracle'
+
+defaultInclusionLabels[TierName.standard]   // 'Next block'
+
+// Locale / branded copy via partial overrides — no fork:
+const es = { [TierName.standard]: 'Próximo bloque' }
+inclusionLabel(TierName.standard, es)        // 'Próximo bloque'
+inclusionLabel(TierName.slow, es)            // falls back to default English
+```
+
+## Chain presets
+
+```ts
+import { createGasOracle, chainPresets, presetForChainId } from '@valve-tech/gas-oracle'
+
+// Static — direct preset access
+createGasOracle({ client, ...chainPresets.pulsechain })
+
+// Dynamic — runtime lookup by chainId
+const preset = presetForChainId(chainId)
+createGasOracle({ client, chainId, ...preset })
+```
+
+PulseChain (chain 369) is the only entry shipped today. Adding more
+requires verifying the chain's actual validator behavior against
+block-level data; the default (eip1559) is correct for every chain we
+haven't proven otherwise.
+
 ## viem integration
 
 ### Subpath: `@valve-tech/gas-oracle/viem-actions`
@@ -317,12 +414,13 @@ Extension surface for callers who want explicit access to tier shapes:
 
 ```ts
 import { gasOracleActions } from '@valve-tech/gas-oracle/viem-actions'
+import { PriorityModel } from '@valve-tech/gas-oracle'
 
 const client = createPublicClient({ chain: mainnet, transport: http() })
   .extend(gasOracleActions({
     chainId: 1,
     priorityFeeDecayCap: parseEther('0.125'),
-    priorityModel: 'eip1559',
+    priorityModel: PriorityModel.eip1559,
   }))
 
 await client.getGasTiers()                            // full snapshot
@@ -343,11 +441,12 @@ work better* — `useFeeData`, `walletClient.sendTransaction({...})`,
 
 ```ts
 import { withGasOracle } from '@valve-tech/gas-oracle/viem-transport'
+import { PriorityModel } from '@valve-tech/gas-oracle'
 
 const transport = withGasOracle(http(rpcUrl), {
   chainId: 1,
   priorityFeeDecayCap: parseEther('0.125'),
-  priorityModel: 'eip1559',
+  priorityModel: PriorityModel.eip1559,
   intercept: {
     eth_gasFeeEstimate: true,           // additive (default on)
     eth_maxPriorityFeePerGas: 'fast',   // tier required for standard methods

package/dist/block-position.d.ts

@@ -48,10 +48,10 @@ import type { TxIdentifier } from './mempool.js';
  */
 export type BlockPositionQuery = {
     kind: 'rank';
-    rank: number;
+    rank: bigint;
 } | {
     kind: 'percentile';
-    percentile: number;
+    percentile: bigint;
 } | {
     kind: 'gasFromTop';
     gas: bigint;
@@ -79,7 +79,7 @@ export interface BlockPositionResult {
      */
     pivot: TipSample | null;
     /** Approximate rank of the resolved position, 0-indexed from top. */
-    rank: number;
+    rank: bigint;
     /** Approximate gas-from-top of the resolved position. */
     gasFromTop: bigint;
 }

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

@@ -1 +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"}
+{"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;AAoDD;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB,GAC9B,SAAS,SAAS,EAAE,EACpB,OAAO,kBAAkB,KACxB,mBAiEF,CAAA"}

package/dist/block-position.js

@@ -20,7 +20,11 @@
  * 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 sortByTipDesc = (samples) => 
+// Equal-tip arm folded into the descending side — order between
+// equal-tip samples is unspecified and consumers shouldn't rely on
+// it (mempool ordering is provider-dependent anyway).
+[...samples].sort((a, b) => (a.tip > b.tip ? -1 : 1));
 const matchesIdentifier = (sample, id) => {
     if ('hash' in id) {
         return (typeof sample.hash === 'string' &&
@@ -35,31 +39,33 @@ const matchesIdentifier = (sample, id) => {
 /**
  * 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
+ * Returns -1n 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;
+        return 0n;
     let cumulative = 0n;
-    for (let i = 0; i < sorted.length; i += 1) {
-        cumulative += sorted[i].gas;
+    const len = BigInt(sorted.length);
+    for (let i = 0n; i < len; i += 1n) {
+        cumulative += sorted[Number(i)].gas;
         if (cumulative > targetGas)
             return i;
     }
-    return -1;
+    return -1n;
 };
 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;
+    const len = BigInt(sorted.length);
+    const upper = indexExclusive < len ? indexExclusive : len;
+    for (let i = 0n; i < upper; i += 1n)
+        g += sorted[Number(i)].gas;
     return g;
 };
 const empty = () => ({
     requiredTip: 0n,
     pivot: null,
-    rank: 0,
+    rank: 0n,
     gasFromTop: 0n,
 });
 /**
@@ -76,6 +82,7 @@ export const tipForBlockPosition = (samples, query) => {
     if (samples.length === 0)
         return empty();
     const sorted = sortByTipDesc(samples);
+    const len = BigInt(sorted.length);
     let pivotIndex;
     let beatPivot; // true = outbid (tip+1), false = undercut (tip-1)
     switch (query.kind) {
@@ -85,12 +92,16 @@ export const tipForBlockPosition = (samples, query) => {
             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);
+            // 0% = top of block (highest tip); 100% = bottom. Clamp to [0n, 100n].
+            const pct = query.percentile < 0n
+                ? 0n
+                : query.percentile > 100n
+                    ? 100n
+                    : query.percentile;
+            pivotIndex = (len * pct) / 100n;
             // Edge: percentile=100 lands at length, which is "below everything"
-            if (pivotIndex >= sorted.length)
-                pivotIndex = sorted.length - 1;
+            if (pivotIndex >= len)
+                pivotIndex = len - 1n;
             beatPivot = true;
             break;
         }
@@ -101,21 +112,22 @@ export const tipForBlockPosition = (samples, query) => {
         }
         case 'aheadOf':
         case 'behind': {
-            pivotIndex = sorted.findIndex((s) => matchesIdentifier(s, query.tx));
+            const found = sorted.findIndex((s) => matchesIdentifier(s, query.tx));
+            pivotIndex = found === -1 ? -1n : BigInt(found);
             beatPivot = query.kind === 'aheadOf';
             break;
         }
     }
-    if (pivotIndex < 0 || pivotIndex >= sorted.length) {
+    if (pivotIndex < 0n || pivotIndex >= len) {
         // 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),
+            rank: len,
+            gasFromTop: sumGasUpTo(sorted, len),
         };
     }
-    const pivot = sorted[pivotIndex];
+    const pivot = sorted[Number(pivotIndex)];
     const requiredTip = beatPivot
         ? pivot.tip + 1n
         : pivot.tip > 0n

package/dist/block-position.js.map

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

package/dist/classify-tip.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Inverse of `tipForBlockPosition`. Given a tip and a snapshot, find
+ * where the tip would land in the live distribution and which named
+ * tier it falls in. Pure: no I/O, no oracle dependency, no wall-clock.
+ *
+ * Useful for "you priced at the Xth percentile" UI affordances and for
+ * post-hoc "why is my tx slow" diagnostics.
+ */
+import { TierName, type GasOracleState } from './types.js';
+export interface ClassifyTipResult {
+    /**
+     * Named tier the tip falls in. `null` when below `TierName.slow`'s
+     * `maxPriorityFeePerGas` floor.
+     */
+    tier: TierName | null;
+    /**
+     * `maxPriorityFeePerGas` floor of the next tier above `tier`. `null`
+     * when `tier === TierName.instant` (already at top).
+     */
+    requiredForNextTier: bigint | null;
+    /**
+     * Approximate percentile in the live distribution (block ring tips +
+     * mempool samples), 0n..100n. `0n` = top of block (highest tip);
+     * `100n` = bottom. `0n` when distribution empty.
+     */
+    percentile: bigint;
+    /** Approximate rank, 0n-indexed from top. `0n` when distribution empty. */
+    rank: bigint;
+    /** Accumulated gas above this tip's position. `0n` when empty. */
+    gasFromTop: bigint;
+}
+export declare const classifyTip: (snapshot: GasOracleState, tipWei: bigint) => ClassifyTipResult;
+//# sourceMappingURL=classify-tip.d.ts.map

package/dist/classify-tip.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"classify-tip.d.ts","sourceRoot":"","sources":["../src/classify-tip.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAEL,QAAQ,EACR,KAAK,cAAc,EAEpB,MAAM,YAAY,CAAA;AAEnB,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,IAAI,EAAE,QAAQ,GAAG,IAAI,CAAA;IACrB;;;OAGG;IACH,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAA;IAClC;;;;OAIG;IACH,UAAU,EAAE,MAAM,CAAA;IAClB,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAA;IACZ,kEAAkE;IAClE,UAAU,EAAE,MAAM,CAAA;CACnB;AA4BD,eAAO,MAAM,WAAW,GACtB,UAAU,cAAc,EACxB,QAAQ,MAAM,KACb,iBA0BF,CAAA"}

package/dist/classify-tip.js

@@ -0,0 +1,52 @@
+/**
+ * Inverse of `tipForBlockPosition`. Given a tip and a snapshot, find
+ * where the tip would land in the live distribution and which named
+ * tier it falls in. Pure: no I/O, no oracle dependency, no wall-clock.
+ *
+ * Useful for "you priced at the Xth percentile" UI affordances and for
+ * post-hoc "why is my tx slow" diagnostics.
+ */
+import { TIER_LADDER, } from './types.js';
+const tierForTip = (tiers, tipWei) => {
+    for (let i = TIER_LADDER.length - 1; i >= 0; i -= 1) {
+        const tier = TIER_LADDER[i];
+        if (tipWei >= tiers[tier].maxPriorityFeePerGas)
+            return tier;
+    }
+    return null;
+};
+const requiredForNextTierAbove = (tiers, currentTier) => {
+    const currentIndex = currentTier ? TIER_LADDER.indexOf(currentTier) : -1;
+    const nextIndex = currentIndex + 1;
+    if (nextIndex >= TIER_LADDER.length)
+        return null;
+    return tiers[TIER_LADDER[nextIndex]].maxPriorityFeePerGas;
+};
+const collectDistribution = (snapshot) => [
+    ...snapshot.ring.flatMap((block) => block.tips),
+    ...snapshot.mempoolSamples,
+];
+export const classifyTip = (snapshot, tipWei) => {
+    const tier = tierForTip(snapshot.tiers, tipWei);
+    const requiredForNextTier = requiredForNextTierAbove(snapshot.tiers, tier);
+    const samples = collectDistribution(snapshot);
+    if (samples.length === 0) {
+        return { tier, requiredForNextTier, percentile: 0n, rank: 0n, gasFromTop: 0n };
+    }
+    // Sort by tip desc, equal-tip arm folded into descending side
+    // (matches block-position.ts convention).
+    const sorted = [...samples].sort((a, b) => (a.tip > b.tip ? -1 : 1));
+    const firstWeakerIndexNum = sorted.findIndex((s) => s.tip <= tipWei);
+    const samplesLen = BigInt(sorted.length);
+    const rank = firstWeakerIndexNum === -1
+        ? samplesLen
+        : BigInt(firstWeakerIndexNum);
+    // Round-half-away-from-zero percentile, all bigint. samplesLen >= 1n
+    // is guaranteed by the early-return on empty samples above.
+    const percentile = (rank * 100n + samplesLen / 2n) / samplesLen;
+    let gasFromTop = 0n;
+    for (let i = 0n; i < rank; i += 1n)
+        gasFromTop += sorted[Number(i)].gas;
+    return { tier, requiredForNextTier, percentile, rank, gasFromTop };
+};
+//# sourceMappingURL=classify-tip.js.map

package/dist/classify-tip.js.map

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

package/dist/inclusion-labels.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Default English UI copy mapping each tier to a user-facing inclusion
+ * label, plus a small helper that resolves a tier with optional partial
+ * overrides (locale or branded copy without forking the whole map).
+ *
+ * Conservative phrasing — labels describe relative position in the next
+ * block, not hard guarantees. Real inclusion is probabilistic.
+ */
+import { TierName } from './types.js';
+export declare const defaultInclusionLabels: Record<TierName, string>;
+/**
+ * Resolve a tier to its inclusion label, falling back to
+ * `defaultInclusionLabels` for any tier not present in `overrides`.
+ *
+ * Locale / branded-copy pattern (no fork required):
+ *
+ * ```ts
+ * const es: Partial<Record<TierName, string>> = {
+ *   [TierName.standard]: 'Próximo bloque',
+ *   [TierName.fast]: 'Cabeza del próximo bloque',
+ * }
+ * inclusionLabel(TierName.standard, es) // 'Próximo bloque'
+ * inclusionLabel(TierName.slow, es)     // falls back to default English
+ * ```
+ *
+ * Consumers can also fully replace the map by spreading:
+ * `const myLabels = { ...defaultInclusionLabels, ...partial }`.
+ */
+export declare const inclusionLabel: (tier: TierName, overrides?: Partial<Record<TierName, string>>) => string;
+//# sourceMappingURL=inclusion-labels.d.ts.map

package/dist/inclusion-labels.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inclusion-labels.d.ts","sourceRoot":"","sources":["../src/inclusion-labels.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAErC,eAAO,MAAM,sBAAsB,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAK3D,CAAA;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,cAAc,GACzB,MAAM,QAAQ,EACd,YAAY,OAAO,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,KAC5C,MAA2D,CAAA"}

package/dist/inclusion-labels.js

@@ -0,0 +1,35 @@
+/**
+ * Default English UI copy mapping each tier to a user-facing inclusion
+ * label, plus a small helper that resolves a tier with optional partial
+ * overrides (locale or branded copy without forking the whole map).
+ *
+ * Conservative phrasing — labels describe relative position in the next
+ * block, not hard guarantees. Real inclusion is probabilistic.
+ */
+import { TierName } from './types.js';
+export const defaultInclusionLabels = {
+    [TierName.slow]: 'Within a few blocks',
+    [TierName.standard]: 'Next block',
+    [TierName.fast]: 'Top of next block',
+    [TierName.instant]: 'Front of next block',
+};
+/**
+ * Resolve a tier to its inclusion label, falling back to
+ * `defaultInclusionLabels` for any tier not present in `overrides`.
+ *
+ * Locale / branded-copy pattern (no fork required):
+ *
+ * ```ts
+ * const es: Partial<Record<TierName, string>> = {
+ *   [TierName.standard]: 'Próximo bloque',
+ *   [TierName.fast]: 'Cabeza del próximo bloque',
+ * }
+ * inclusionLabel(TierName.standard, es) // 'Próximo bloque'
+ * inclusionLabel(TierName.slow, es)     // falls back to default English
+ * ```
+ *
+ * Consumers can also fully replace the map by spreading:
+ * `const myLabels = { ...defaultInclusionLabels, ...partial }`.
+ */
+export const inclusionLabel = (tier, overrides) => overrides?.[tier] ?? defaultInclusionLabels[tier];
+//# sourceMappingURL=inclusion-labels.js.map

package/dist/inclusion-labels.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inclusion-labels.js","sourceRoot":"","sources":["../src/inclusion-labels.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAErC,MAAM,CAAC,MAAM,sBAAsB,GAA6B;IAC9D,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,qBAAqB;IACtC,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,YAAY;IACjC,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,mBAAmB;IACpC,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,qBAAqB;CAC1C,CAAA;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAC5B,IAAc,EACd,SAA6C,EACrC,EAAE,CAAC,SAAS,EAAE,CAAC,IAAI,CAAC,IAAI,sBAAsB,CAAC,IAAI,CAAC,CAAA"}

package/dist/index.d.ts

@@ -16,9 +16,15 @@ export { createGasOracle, reducePollInputs, sampleGasFees, type CreateGasOracleO
 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, fetchHeadBlockNumber, 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 type { RawTx, TipPercentiles, TierRecommendation, MempoolStats, BlobStats, BlockSample, GasOracleState, TipSample, PollOptions, } from './types.js';
+export { PriorityModel, TierName, TIER_LADDER, Trend, TxType } 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';
+export { minimumReplacementFee, bumpForReplacement, recommendBumpTier, BumpStrategy, ReplacementBumpPercent, } from './replacement.js';
+export type { RecommendBumpTierOptions, ReplacementGas, } from './replacement.js';
+export { classifyTip, type ClassifyTipResult } from './classify-tip.js';
+export { defaultInclusionLabels, inclusionLabel } from './inclusion-labels.js';
+export { chainPresets, presetForChainId, type ChainPreset, } from './presets.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,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,oBAAoB,EACpB,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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,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,oBAAoB,EACpB,KAAK,gBAAgB,EACrB,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,gBAAgB,GACtB,MAAM,gBAAgB,CAAA;AAEvB,YAAY,EACV,KAAK,EACL,cAAc,EACd,kBAAkB,EAClB,YAAY,EACZ,SAAS,EACT,WAAW,EACX,cAAc,EACd,SAAS,EACT,WAAW,GACZ,MAAM,YAAY,CAAA;AAGnB,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AAGhF,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;AAG5B,OAAO,EACL,qBAAqB,EACrB,kBAAkB,EAClB,iBAAiB,EACjB,YAAY,EACZ,sBAAsB,GACvB,MAAM,kBAAkB,CAAA;AACzB,YAAY,EACV,wBAAwB,EACxB,cAAc,GACf,MAAM,kBAAkB,CAAA;AAGzB,OAAO,EAAE,WAAW,EAAE,KAAK,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AAGvE,OAAO,EAAE,sBAAsB,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAA;AAG9E,OAAO,EACL,YAAY,EACZ,gBAAgB,EAChB,KAAK,WAAW,GACjB,MAAM,cAAc,CAAA"}