@rhinestone/service-sdk 0.2.11 → 0.2.12

package/dist/chains.d.ts

@@ -1,6 +1,6 @@
 import type { FeeValuesEIP1559, PublicClient } from 'viem';
 /** Client methods required to estimate gas fees. */
-export type FeeEstimationClient = Pick<PublicClient, 'estimateFeesPerGas' | 'getFeeHistory'>;
+export type FeeEstimationClient = Pick<PublicClient, 'estimateFeesPerGas' | 'getFeeHistory'> & Partial<Pick<PublicClient, 'chain'>>;
 /** Options for {@link estimateGasFees}. */
 export type EstimateGasFeesOptions = {
     /**
@@ -16,6 +16,11 @@ export type EstimateGasFeesOptions = {
 /**
  * Estimates gas fees for a chain and returns EIP-1559-shaped fee values.
  *
+ * `maxFeePerGas` is built from the NEXT block's base fee (not the last mined
+ * one) times a per-chain multiplier, plus the priority fee. The orchestrator
+ * bills this number, so unused headroom is charged to the user — see
+ * BASE_FEE_MULTIPLIER_PCT.
+ *
  * Pass `{ mode: 'legacy' }` to source the estimate from the RPC's legacy gas
  * price. The price is used for both EIP-1559 fee caps so it remains the
  * effective-price ceiling. On a no-priority local fork where the base fee

package/dist/chains.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chains.d.ts","sourceRoot":"","sources":["../src/chains.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAmB,YAAY,EAAE,MAAM,MAAM,CAAA;AAa3E,oDAAoD;AACpD,MAAM,MAAM,mBAAmB,GAAG,IAAI,CACpC,YAAY,EACZ,oBAAoB,GAAG,eAAe,CACvC,CAAA;AAED,2CAA2C;AAC3C,MAAM,MAAM,sBAAsB,GAAG;IACnC;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE,QAAQ,CAAA;CAChB,CAAA;AA8GD;;;;;;;;;GASG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,mBAAmB,EAC3B,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,sBAAsB,GAC/B,OAAO,CAAC,gBAAgB,CAAC,CAsB3B"}
+{"version":3,"file":"chains.d.ts","sourceRoot":"","sources":["../src/chains.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAmB,YAAY,EAAE,MAAM,MAAM,CAAA;AAmB3E,oDAAoD;AAMpD,MAAM,MAAM,mBAAmB,GAAG,IAAI,CACpC,YAAY,EACZ,oBAAoB,GAAG,eAAe,CACvC,GACC,OAAO,CAAC,IAAI,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC,CAAA;AAEtC,2CAA2C;AAC3C,MAAM,MAAM,sBAAsB,GAAG;IACnC;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE,QAAQ,CAAA;CAChB,CAAA;AAyTD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,mBAAmB,EAC3B,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,sBAAsB,GAC/B,OAAO,CAAC,gBAAgB,CAAC,CA2C3B"}

package/dist/chains.js

@@ -1,7 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.estimateGasFees = estimateGasFees;
+const api_1 = require("@opentelemetry/api");
 const chains_1 = require("viem/chains");
+const tipClamp_1 = require("./tipClamp");
+const viemDefaults_1 = require("./viemDefaults");
 // Chains that price fees from a windowed eth_feeHistory instead of viem's
 // default estimator. Two membership rationales:
 //  - volatile-base L1s (mainnet, sepolia): windowing the next-block base fee
@@ -20,35 +23,74 @@ const HISTORICAL_FEE_CHAINS = new Set([
 ]);
 const DEFAULT_FEE_CONFIG = {
     historyBlocks: 20, // Geth FullNodeGPO window
-    baseFeeMultiplier: 2n, // ~6 blocks / ~70s headroom (cap only — free)
-    tipPercentile: 50, // calm-market per-block tip (real mainnet p50 ≈ 0.03 gwei)
+    // Matches the viem-path default rather than the old 2.0x. Every chain on the
+    // historical path overrides this today (and Plasma's base fee is 0, so it is
+    // inert there), but leaving 2.0x here would silently hand the next chain added
+    // to HISTORICAL_FEE_CHAINS exactly the over-charge this PR removes.
+    baseFeeMultiplierPct: 105n,
+    tipPercentile: 50, // calm-market per-block tip; per-chain blocks override it
     congestedTipPercentile: 75, // escalate to p75 under load (not p90 — ~45x cost)
     congestionRatio: 0.5, // "gasUsedRatio trends > 0.5"
     windowTipPercentile: 50, // nearest-rank p50 across the window's per-block tips
     // 0.1 gwei. Enough to clear the zero-tip stall (the tip is the only builder
-    // incentive — base fee is burned), without over-buffering: real mainnet p50 is
-    // ~0.03 gwei, so this is ~3x the median, while 1 gwei would be ~30x.
+    // incentive — base fee is burned) without over-buffering. Chains that fill
+    // often enough to measure set their own floor from realized data; this is the
+    // fallback for one that does not.
     tipFloorWei: 100000000n,
 };
 // Per-chain overrides for the windowed feeHistory path; any omitted field falls
 // back to DEFAULT_FEE_CONFIG.
 const FEE_CONFIG_OVERRIDES = {
-    // Testnet — not real money: aggressive percentile, no floor.
+    // Testnet: no tip floor — testnet inclusion is
+    // flaky and the tip is self-consistent (we bid it, we pay it, so it does not
+    // skew charged-vs-actual). The base multiplier is the part that was
+    // over-charging: billing 2.0x base while paying 1.0x put sepolia at A/C 0.70,
+    // the same defect as every other chain. Its measured base dispersion is 1.33x,
+    // so 1.30x sits just under the observed max rather than on the mean. The tip came
+    // down from p75 for the same reason: a 7d block replay puts sepolia's p75 at
+    // 1.0 gwei against a 0.0375 market p50, which alone held it at A/C 0.50.
     [chains_1.sepolia.id]: {
-        tipPercentile: 75,
-        congestedTipPercentile: 90,
+        baseFeeMultiplierPct: 130n,
+        tipPercentile: 50,
+        congestedTipPercentile: 75,
         tipFloorWei: 0n,
     },
-    // Plasma is here for its broken tip oracle, not a volatile base: base fee ~0
-    // and rewards flat at the chain-min (probed 2026-07-06, matching the RHI-4468
-    // audit). Floor at the chain-min instead of the 0.1 gwei default — that
-    // default is a 20x overpay at this chain's fee scale — so a quiet/empty
-    // reward window can't stall a tx while flat markets are never overpaid.
-    // Percentiles stay on defaults: the reward distribution is flat in calm
-    // markets, so they only bite during real congestion, where the p50→p75
-    // escalation is the wanted behavior.
+    // Mainnet's reward distribution is inflated by MEV-boost blocks — searchers
+    // pay enormous priority fees, so the feeHistory p50 prices our plain fills
+    // against searcher competition: 7d prod shows charged tip 0.152 gwei vs
+    // 0.011 realized (13.8x). Sample p25 and floor at the realized clearing
+    // price (the floor still clears the zero-tip stall — the tip is the only
+    // builder incentive on L1). Base is separate, and mainnet is the one chain
+    // where quote-time base is a poor predictor of fill-time base: 7d prod shows a
+    // charged base of 0.2199 at the old 2.0x (so a 0.110 base at quote) against a
+    // 0.1647 realized base — a measured 1.50x drift between quote and fill. The
+    // multiplier has to cover that drift, not the next block: 1.60x sits above the
+    // 1.50x mean so the cap still clears at fill time, and lands at A/C 0.95.
+    [chains_1.mainnet.id]: {
+        baseFeeMultiplierPct: 160n,
+        tipPercentile: 25,
+        congestedTipPercentile: 50,
+        tipFloorWei: 11000000n, // 0.011 gwei — the realized clearing tip; ~2x the 0.0054 market p50
+    },
+    // Plasma is on the historical path for its broken tip oracle, not a volatile
+    // base (its base fee is 0). Its reward distribution is a step function, not a
+    // gradient — probed live 2026-07-24 over 40 blocks:
+    //   p1..p10 = 0        p15..p50 = 0.005 gwei
+    // so every percentile from 15 up reports the same 0.005, while real fills
+    // clear at ~0.0015 (third-party solvers are included on-chain at that price,
+    // so it demonstrably clears). Sampling anywhere above p10 therefore prices at
+    // 0.005 and the floor never binds — the tip must be read at p10, where the
+    // window median is genuinely 0, so the measured floor below sets the price.
     [chains_1.plasma.id]: {
-        tipFloorWei: 5000000n, // 0.005 gwei chain-min priority fee
+        // Explicit, not inherited. Plasma's base fee is ~0 almost always, so this
+        // multiplier is free — but "almost" matters: a 7d block replay puts 0.4% of
+        // quotes under the base fee one block later at 1.05x, and 1.5% ten blocks
+        // later, against 0% at 2.0x. On 69k fills/wk that is real. Inheriting the
+        // shared default would silently re-introduce it.
+        baseFeeMultiplierPct: 200n,
+        tipPercentile: 10,
+        congestedTipPercentile: 25,
+        tipFloorWei: 1700000n, // 0.0017 gwei — measured clearing price (2026-07-24)
     },
 };
 // Chains where viem's default base-fee estimate is fine but its tip oracle
@@ -61,21 +103,182 @@ const TIP_FLOOR_WEI = {
     [chains_1.base.id]: 3000000n, // 0.003 gwei — oracle ~0.001 (network ~p25); real fills ~0.003-0.0036 (probed 2026-07-08)
     [chains_1.bsc.id]: 50000000n, // 0.05 gwei — post-Maxwell chain-min; oracle intermittently returns 0 through some upstreams, and with BSC's zero base fee that zeroes the ENTIRE bid (probed 2026-07-13)
     [chains_1.polygon.id]: 45000000000n, // 45 gwei — Bor min 30 gwei x1.5; real p50 tip ~200 gwei
-    [chains_1.gnosis.id]: 1000000000n, // 1.0 gwei — viem oracle ~21 wei; real p90 inclusion ~1.0 gwei (re-probed 2026-06-25)
-    [chains_1.hyperEvm.id]: 150000000n, // 0.15 gwei — oracle returns 0; realized p50 tip ~0.15 gwei
-    [chains_1.monad.id]: 22000000000n, // 22 gwei — oracle 2 gwei; competitive tip p50/mode ~22 gwei
+    // 100 wei. Gnosis operates at a scale where gwei is the wrong unit to think
+    // in: its median base fee is 118 WEI (p10 24, p90 278k), and included-tx tips
+    // are 0 at p50 and p75. The old 1.0 gwei floor was ~8,500,000x the median base
+    // fee; an earlier revision of this PR cut it to 100_000 wei, which was still
+    // 850x the base and left the floor as the dominant term in the whole quote —
+    // it alone pinned Gnosis at A/C 0.00 no matter what the base multiplier did.
+    //
+    // 21 wei — viem's own oracle reading on this chain, so the floor effectively
+    // never binds and simply guards a zero-reporting upstream. Note the BSC
+    // failure mode (a 0 oracle zeroing the ENTIRE bid) cannot occur here: Gnosis'
+    // base fee is nonzero, so `base * mult` alone keeps the bid includable.
+    //
+    // Deliberately NOT sized for congestion. Gnosis does have busy episodes
+    // needing ~263,000 wei, but no static floor is the right tool — it would
+    // over-charge the calm majority without covering the tail. If that tail ever
+    // matters (it does not at 3 fills/wk), the fix is moving Gnosis to
+    // HISTORICAL_FEE_CHAINS for the windowed path's congestion escalation, not a
+    // bigger floor.
+    [chains_1.gnosis.id]: 21n,
+    // Left at its existing value deliberately. HyperEVM over-charges the tip by
+    // ~16x (0.158 charged vs 0.00953 realized) but under-charges the base (0.189
+    // charged vs 0.354 realized), and the two errors cancel to an overall A/C of
+    // 1.05. Correcting only the tip would turn that balance into a ~1.65
+    // under-charge, so the tip stays and the base carries the correction instead
+    // — see BASE_FEE_MULTIPLIER_PCT_OVERRIDES. Revisit with a fill-side base probe.
+    [chains_1.hyperEvm.id]: 150000000n, // 0.15 gwei
+    // 3 gwei — feeHistory p50 2.0 / p75 3.0 of included txs, over 2,100 blocks
+    // spanning 5.1d (2026-07-24). This contradicts the previous comment's
+    // "competitive tip p50/mode ~22 gwei" (2026-06-25); both claim a p50 and they
+    // differ 7x. The old figure is not reproducible against current chain data.
+    // Monad rides the shared 1.05x base multiplier with no cushion, so an error
+    // here surfaces directly; the lag replay puts it at 0% under-capped at every
+    // lag tested.
+    [chains_1.monad.id]: 3000000000n,
 };
 // Chains whose real tip drifts above the static floor in busy markets — also
 // window the feeHistory tip and take the max with the floor. Polygon: real tip
 // runs ~6.7x its oracle. Base: realized tip drifts above the floor while the
 // oracle stays pinned — see TIP_FLOOR_WEI for the measured values. Both have
-// stable base fees, so the base stays on viem's default.
+// stable base fees, but the base still gets the shared next-block treatment.
 const WINDOWED_TIP_CHAINS = new Set([chains_1.polygon.id, chains_1.base.id]);
+// Upper bound on the priority fee, per chain.
+//
+// The counterpart to TIP_FLOOR_WEI: a floor can only ever RAISE a tip, so there
+// was previously no way to correct a chain whose eth_maxPriorityFeePerGas
+// OVER-reports. Several do, by a wide margin — the oracle quotes a price far
+// above what transactions on that chain actually pay to get included.
+//
+// Each value is set from the strongest evidence that chain has. Where we fill
+// often enough for our own realized tip to mean something (Optimism, Soneium,
+// BSC) the cap sits at that realized price. Where we do not (Sonic, Avalanche:
+// 3-5 fills/wk, too few to be anything but noise — Gnosis' realized price over
+// 3 fills came out BELOW its own base fee, which is impossible) it is set from
+// eth_feeHistory rewards, the tips included transactions actually paid, at
+// roughly the market p75/p90 — demonstrably enough to be included, never the
+// median.
+const TIP_CAP_WEI = {
+    // Arbitrum, Unichain and Katana are deliberately absent: their charged tip
+    // already matches realized. Unichain and Katana sit at A/C 0.94/0.91, so a cap
+    // there would under-charge; Arbitrum's oracle returns 0 outright (38,387
+    // samples over 7d, all zero — it has no priority-fee auction), so a cap there
+    // would simply be a no-op.
+    [chains_1.optimism.id]: 400000n, // 0.0004 gwei — realized tip 0.00038 vs a flat 0.001 oracle quote
+    [chains_1.soneium.id]: 700000n, // 0.0007 gwei — realized tip 0.000706 across 1198 fills/wk (so this clamps a hair under realized), vs a flat 0.001 oracle quote
+    [chains_1.sonic.id]: 100000n, // 0.0001 gwei — deliberately 5x the 0.00002 market p90, since 3 fills/wk is too thin to trust; still a ~5000x cut from the 0.525 the oracle drove
+    [chains_1.avalanche.id]: 1000000n, // 0.001 gwei — market p75/p90; charged tip was 0.0117
+    [chains_1.bsc.id]: 55000000n, // 0.055 gwei — realized tip 0.0542, market p50 0.052; the oracle drifts to 0.0629 above the 0.05 chain-min
+};
 const WINDOWED_TIP_HISTORY_BLOCKS = 20;
+// Stays at p50 for both windowed chains. Polygon looked like a candidate for a
+// lower percentile, but its market p25 (167 gwei, probed 2026-07-24) is ABOVE
+// what we already charge (~154) while our own fills clear at ~85 — our fills
+// price below the entire included-tx distribution, which no percentile of that
+// distribution can express.
 const WINDOWED_TIP_PERCENTILE = 50; // p50 per block, nearest-rank across the window
+// Base-fee headroom applied on the viem estimator path, as a percentage.
+//
+// This is pure CAP headroom against a base fee that rises between quote and
+// submission: on-chain you only ever pay `base + tip`, so unused headroom is
+// never spent — but the orchestrator BILLS this number (and sizes gas-refund
+// ceilings and bridged native reserves from it), so over-buffering is charged
+// to the user.
+//
+// It is applied to the NEXT block's base fee, which eth_feeHistory reports
+// directly (the historical path has always used it). That matters: viem's own
+// estimate scales the LATEST MINED block's base by 1.2x, and since EIP-1559
+// allows the base to grow at most 12.5% per block, viem's 1.2x is really
+// "one worst-case block (1.125x) plus ~6% margin" — not 20% of slack. Pricing
+// off the next block's actual base instead of that worst case is where the
+// over-charge disappears: 7d of prod fills show the stable-base chains on this
+// path billing exactly 1.20x what they pay (Base 0.00602 charged vs 0.00501
+// realized; Arbitrum 0.02412 vs 0.02008), because their blocks are not full
+// and the worst case never materialises.
+//
+// 1.05x of the real next-block base keeps genuine headroom while removing that
+// systematic over-charge. If the base outruns it, the relayer's tx queue
+// re-prices and bumps unbounded (relayer/src/tx_queue/nonce-slot.ts, reprice /
+// bumpedFees) — a latency cost, not an inclusion failure.
+//
+// That unbounded bump is a phase-1 posture, not a permanent property: the
+// relayer omits `feeCeiling` and `gasPriceCap` "isn't wired from the intent
+// yet" (relayer/src/tx_queue/config.ts). Once it is, `exceedsCap` flips the
+// slot to `flipToCancelTx` and the fill is ABANDONED rather than delayed — and
+// since that cap derives from the quoted maxFeePerGas, shrinking headroom
+// shrinks the abandon threshold with it. Revisit this multiplier then.
+const BASE_FEE_MULTIPLIER_PCT = 105n;
+// Per-chain base-fee multiplier for the viem paths. Only HyperEVM needs one: its
+// realized base runs ~2.25x the base quoted to us (0.354 vs 0.157, 7d prod),
+// which no next-block reading can see. It is also the one chain whose two errors
+// currently cancel — the tip over-charges ~16x and the base under-charges, netting
+// A/C 1.05 — so dropping it to the shared 1.05 would unbalance it to 1.12. The
+// tip is deliberately left alone for the same reason; 1.30x restores A/C ~1.00.
+// Sized from a 7d block replay measuring, per chain, the share of quotes whose
+// cap falls below the base fee of the block they would land in at a 1-5 block
+// lag. The shared 1.05x holds every chain at 0% except these two.
+const BASE_FEE_MULTIPLIER_PCT_OVERRIDES = {
+    [chains_1.hyperEvm.id]: 130n,
+    // Gnosis' tip is ~0 in calm markets (market p50 AND p75 are both zero), so
+    // its A/C is bounded almost entirely by this multiplier — we bill the cap, so
+    // A/C ~= 1/mult. That makes the multiplier the only real lever, and the
+    // question is how little headroom its base movement actually needs.
+    //
+    // Measured over 7d: 1.15x leaves 0% of quotes under-capped at one block, 1.7%
+    // at five and 4.3% at ten, at A/C 0.98. The shared 1.05x would be 14%/28%,
+    // which is why Gnosis needs an override at all.
+    //
+    // Be clear that this IS a trade, not a free win. main is 0% under-capped at
+    // every lag — but only because its 1.0 gwei tip floor (8,500,000x this chain's
+    // median base fee) accidentally supplied enormous cap headroom while pinning
+    // A/C at 0.00. Removing that floor is what surfaces the exposure. What we are
+    // buying: A/C 0.00 -> 0.98. What we are paying: a relayer re-price on roughly
+    // 1.7% of quotes, on a chain filling ~3x/week — about one bump every seven
+    // months, and a re-price is latency, not a lost fill.
+    //
+    // 1.30x is the conservative alternative: A/C 0.88 at 0.1%/0.2%. Prefer it if
+    // Gnosis volume ever becomes non-trivial.
+    [chains_1.gnosis.id]: 115n,
+    // 0.9% under-capped at one block and 8.1% at five, against 0% today. 1.15x
+    // returns it to 0% through a ten-block lag while still improving A/C from
+    // 0.70 to 0.86 — better than today on both axes, which 1.05x is not.
+    [chains_1.avalanche.id]: 115n,
+};
+const baseFeeMultiplierPct = (chainId) => BASE_FEE_MULTIPLIER_PCT_OVERRIDES[chainId] ?? BASE_FEE_MULTIPLIER_PCT;
+/**
+ * Next-block base fee, as reported by eth_feeHistory (last entry).
+ *
+ * Returns `null` — never 0n — when the RPC omits it or returns an empty array:
+ * a 0 base would silently price the cap at the tip alone, which under-prices
+ * on every chain with a nonzero base. `null` routes the caller to viem's own
+ * (strictly more conservative) cap instead.
+ */
+async function nextBlockBaseFee(client, chainId) {
+    const feeHistory = await client.getFeeHistory({
+        blockCount: 1,
+        rewardPercentiles: [],
+    });
+    const baseFee = feeHistory.baseFeePerGas?.at(-1);
+    if (baseFee === undefined) {
+        // Recorded HERE rather than at the caller's `.catch`, because this is a
+        // SUCCESSFUL response carrying no base fee — it never throws, so the catch
+        // does not see it. That is the same failure class the windowed path records
+        // as `feehistory_missing_base`, and leaving it out would make the one case
+        // viem's transport retries cannot absorb the one case with no signal.
+        recordDegradedEstimate(chainId, 'feehistory_missing_base');
+        return null;
+    }
+    return baseFee;
+}
 /**
  * Estimates gas fees for a chain and returns EIP-1559-shaped fee values.
  *
+ * `maxFeePerGas` is built from the NEXT block's base fee (not the last mined
+ * one) times a per-chain multiplier, plus the priority fee. The orchestrator
+ * bills this number, so unused headroom is charged to the user — see
+ * BASE_FEE_MULTIPLIER_PCT.
+ *
  * Pass `{ mode: 'legacy' }` to source the estimate from the RPC's legacy gas
  * price. The price is used for both EIP-1559 fee caps so it remains the
  * effective-price ceiling. On a no-priority local fork where the base fee
@@ -96,47 +299,151 @@ async function estimateGasFees(client, chainId, options) {
     }
     if (HISTORICAL_FEE_CHAINS.has(chainId)) {
         const config = { ...DEFAULT_FEE_CONFIG, ...FEE_CONFIG_OVERRIDES[chainId] };
-        return estimateFeeHistoryGasFees(client, config);
+        return estimateFeeHistoryGasFees(client, chainId, config);
     }
     const tipFloorWei = TIP_FLOOR_WEI[chainId];
     if (tipFloorWei !== undefined) {
         return estimateViemFeesWithTipFloor(client, chainId, tipFloorWei);
     }
-    return client.estimateFeesPerGas();
+    const [fees, baseFee] = await Promise.all([
+        client.estimateFeesPerGas(),
+        nextBlockBaseFee(client, chainId).catch(() => {
+            recordDegradedEstimate(chainId, 'feehistory_error');
+            return null;
+        }),
+    ]);
+    const oracleTip = fees.maxPriorityFeePerGas;
+    // The cap applies here too: the chains whose oracle over-reports (Optimism,
+    // Soneium, Sonic, Avalanche) have no tip floor, so this is their only path.
+    const tip = (0, tipClamp_1.clampTip)(oracleTip, undefined, TIP_CAP_WEI[chainId]);
+    return {
+        maxFeePerGas: cappedMaxFeePerGas(client, fees, baseFee, chainId, tip, oracleTip),
+        maxPriorityFeePerGas: tip,
+    };
 }
-// viem's default fee estimate (base fee + oracle tip), with the priority fee
-// lifted to an absolute floor — and, for windowed-tip chains, to the windowed
-// feeHistory tip. The maxFeePerGas cap is raised by the same delta so the lifted
-// tip is never clipped. The tip is only ever raised, never lowered, so this
-// preserves viem's estimate whenever it already exceeds the floor.
+// viem's oracle tip, lifted to an absolute floor — and, for windowed-tip chains,
+// to the windowed feeHistory tip — then clamped down to any TIP_CAP_WEI. The tip
+// is therefore raised OR lowered here; the cap applies first and the floor
+// last, so a floor is never undercut by a cap.
+//
+// maxFeePerGas is rebuilt from the next block's base fee rather than adjusted
+// off viem's, falling back to viem's own cap plus the tip delta when the base
+// read fails.
 async function estimateViemFeesWithTipFloor(client, chainId, tipFloorWei) {
-    const fees = await client.estimateFeesPerGas();
+    // Windowed chains get their tip AND the next-block base from one 20-block
+    // feeHistory response: that response already carries `baseFeePerGas` with the
+    // next block's base as its last entry, so a second blockCount:1 call would
+    // re-fetch a number we are holding. Everyone else reads the base alone.
+    //
+    // Best-effort throughout: a feeHistory outage must never turn into a quote
+    // outage. On failure the tip falls back to max(oracle, floor) — exactly the
+    // pre-overlay pricing — and the cap to viem's own, which is strictly more
+    // conservative, never less.
+    const [fees, history] = await Promise.all([
+        client.estimateFeesPerGas(),
+        (WINDOWED_TIP_CHAINS.has(chainId)
+            ? windowedFeeHistoryTip(client, chainId)
+            : nextBlockBaseFee(client, chainId).then((baseFee) => ({
+                tip: 0n,
+                baseFee,
+            }))).catch(() => {
+            recordDegradedEstimate(chainId, 'feehistory_error');
+            return { tip: 0n, baseFee: null };
+        }),
+    ]);
     const oracleTip = fees.maxPriorityFeePerGas;
     let tip = oracleTip;
-    if (WINDOWED_TIP_CHAINS.has(chainId)) {
-        // Best-effort: the windowed overlay refines the tip but must never turn a
-        // feeHistory outage into a quote outage — on failure, fall back to
-        // max(oracle, floor), which is exactly the pre-overlay pricing.
-        const windowedTip = await windowedFeeHistoryTip(client).catch(() => 0n);
-        if (windowedTip > tip)
-            tip = windowedTip;
-    }
-    if (tipFloorWei > tip)
-        tip = tipFloorWei;
+    if (history.tip > tip)
+        tip = history.tip;
+    tip = (0, tipClamp_1.clampTip)(tip, tipFloorWei, TIP_CAP_WEI[chainId]);
     return {
-        maxFeePerGas: fees.maxFeePerGas + (tip - oracleTip),
+        maxFeePerGas: cappedMaxFeePerGas(client, fees, history.baseFee, chainId, tip, oracleTip),
         maxPriorityFeePerGas: tip,
     };
 }
-// Nearest-rank p50 across the window's per-block p50 tips — used to track a busy
-// market that the static oracle/floor lags.
-async function windowedFeeHistoryTip(client) {
+/**
+ * The base-fee multiplier viem ACTUALLY applied, as a percentage, read from the
+ * client's own chain config exactly as viem reads it
+ * (`chain?.fees?.baseFeeMultiplier ?? 1.2`). Used to invert viem's cap on the
+ * degraded path, so the reconstruction cannot drift from the viem the CONSUMER
+ * is running (viem is a `^2` peer range, so it need not match the version CI
+ * pins) or from a consumer that sets a custom multiplier on its chain.
+ *
+ * Falls back to {@link VIEM_DEFAULT_BASE_FEE_MULTIPLIER_PCT} only when the value
+ * is not a plain number — i.e. absent, or viem's function form, which viem
+ * evaluates with a block/request context this path does not have. No supported
+ * chain uses the function form, and that fallback is exactly today's behaviour,
+ * so it is a no-op regression-wise.
+ */
+function viemBaseFeeMultiplierPct(client) {
+    const m = client.chain?.fees?.baseFeeMultiplier;
+    // Number.isFinite, not just `>= 1`: Infinity passes `>= 1` and would make
+    // BigInt(Math.round(m * 100)) throw, crashing the estimate on a degraded path.
+    // (NaN is already excluded by `>= 1` being false, but this states it.) An
+    // invalid multiplier falls back to the pinned default rather than crashing.
+    if (typeof m === 'number' && Number.isFinite(m) && m >= 1) {
+        return BigInt(Math.round(m * 100));
+    }
+    return viemDefaults_1.VIEM_DEFAULT_BASE_FEE_MULTIPLIER_PCT;
+}
+/**
+ * Cap = nextBlockBaseFee * multiplier + tip.
+ *
+ * When the base fee could not be read, falls back to viem's own cap — but only
+ * where that is genuinely more conservative. viem builds its cap as
+ * `latestBase * 1.2 + tip`, so it is more conservative ONLY for chains whose
+ * multiplier is at or below 1.2x. For the ones above it (Gnosis 2.0x, HyperEVM
+ * 1.30x) viem's cap is LOWER than intended — measured at 62% and 93% of the
+ * healthy cap — which on Gnosis reopens exactly the under-capping its 2.0x
+ * override exists to close, precisely when the RPC is unhealthy and base fees
+ * move. For those chains we recover viem's implied base and re-apply our own
+ * multiplier, taking whichever cap is higher.
+ */
+function cappedMaxFeePerGas(client, fees, baseFee, chainId, tip, oracleTip) {
+    const pct = baseFeeMultiplierPct(chainId);
+    if (baseFee === null) {
+        const viemPct = viemBaseFeeMultiplierPct(client);
+        const viemCap = fees.maxFeePerGas + (tip - oracleTip);
+        let cap = viemCap;
+        if (pct > viemPct) {
+            const impliedBase = ((fees.maxFeePerGas - oracleTip) * 100n) / viemPct;
+            const scaled = (impliedBase * pct) / 100n + tip;
+            if (scaled > cap)
+                cap = scaled;
+        }
+        // Never return below the tip itself. viem's default guarantees
+        // maxFeePerGas >= oracleTip, so `viemCap` is non-negative and this cannot
+        // bind today — but the guarantee is viem's, not ours, and an estimator that
+        // broke it would otherwise make BOTH arms negative (a `maxFeePerGas <=
+        // oracleTip` precondition would not help: it routes to viemCap, which is
+        // exactly the negative value).
+        return cap > tip ? cap : tip;
+    }
+    return (baseFee * pct) / 100n + tip;
+}
+/**
+ * Nearest-rank p50 across the window's per-block p50 tips — used to track a busy
+ * market that the static oracle/floor lags — plus the next block's base fee,
+ * which the same response already carries as the last `baseFeePerGas` entry.
+ *
+ * `baseFee` is `null`, never `0n`, when that array is missing or empty, for the
+ * same reason as {@link nextBlockBaseFee}: a 0 base would price the cap at the
+ * tip alone.
+ */
+async function windowedFeeHistoryTip(client, chainId) {
     const feeHistory = await client.getFeeHistory({
         blockCount: WINDOWED_TIP_HISTORY_BLOCKS,
         rewardPercentiles: [WINDOWED_TIP_PERCENTILE],
     });
     const perBlockTips = (feeHistory.reward ?? []).map((r) => r?.[0] ?? 0n);
-    return percentileBigInt(perBlockTips, WINDOWED_TIP_PERCENTILE);
+    const baseFee = feeHistory.baseFeePerGas?.at(-1);
+    if (baseFee === undefined) {
+        recordDegradedEstimate(chainId, 'feehistory_missing_base');
+    }
+    return {
+        tip: percentileBigInt(perBlockTips, WINDOWED_TIP_PERCENTILE),
+        baseFee: baseFee ?? null,
+    };
 }
 // Windowed eth_feeHistory estimator:
 //   tip          = `windowTipPercentile` across the last N blocks' per-block
@@ -144,8 +451,59 @@ async function windowedFeeHistoryTip(client) {
 //                  (or `congestedTipPercentile` when the window's mean
 //                  gasUsedRatio exceeds `congestionRatio`), floored at
 //                  `tipFloorWei`.
-//   maxFeePerGas = nextBlockBaseFee * baseFeeMultiplier + tip
-async function estimateFeeHistoryGasFees(client, config) {
+//   maxFeePerGas = nextBlockBaseFee * baseFeeMultiplierPct / 100 + tip
+/**
+ * Records that a quote was produced by a DEGRADED path — eth_feeHistory failed
+ * or answered without a base fee, so the cap came from viem rather than from the
+ * next block's actual base.
+ *
+ * This exists because the degradation is otherwise invisible. Every fallback
+ * here is deliberately silent at the call site (a feeHistory outage must never
+ * become a quote outage), which means a broken upstream would quietly revert
+ * these chains to viem's 1.2x-of-latest pricing — the exact over-charge this
+ * module exists to remove — and nothing would say so. The estimate would still
+ * look healthy; it would just be wrong.
+ *
+ * Written to the active span rather than a logger: this package cannot reach
+ * the orchestrator's logger, and the orchestrator already wraps these calls in
+ * `withSpan('getGasFeeComponents')`, so the attributes land in Tempo without any
+ * wiring. `@opentelemetry/api` is a no-op when no SDK is registered, so this
+ * costs nothing for consumers who do not instrument.
+ */
+function recordDegradedEstimate(chainId, reason) {
+    const span = api_1.trace.getActiveSpan();
+    if (!span)
+        return;
+    span.setAttribute('gas.estimate.degraded', true);
+    span.setAttribute('gas.estimate.degraded_reason', reason);
+    span.setAttribute('gas.estimate.chain_id', chainId);
+    span.addEvent('gas.estimate.degraded', { reason, 'chain.id': chainId });
+}
+/**
+ * Cap for the windowed estimator when eth_feeHistory answered without a base
+ * fee. Recovers the base implied by viem's own estimate and re-applies this
+ * chain's multiplier, never returning less than viem's cap or the tip itself.
+ *
+ * Deliberately does NOT adopt viem's tip — see the call site.
+ */
+async function viemFallbackCap(client, config, priorityFee) {
+    const fees = await client.estimateFeesPerGas();
+    const oracleTip = fees.maxPriorityFeePerGas;
+    const viemCap = fees.maxFeePerGas + (priorityFee - oracleTip);
+    let cap = viemCap;
+    if (fees.maxFeePerGas > oracleTip) {
+        // Same reconstruction as cappedMaxFeePerGas: invert by the multiplier viem
+        // ACTUALLY applied for this consumer, not the pinned default — viem is a
+        // peer range and a consumer chain may set its own baseFeeMultiplier.
+        const viemPct = viemBaseFeeMultiplierPct(client);
+        const impliedBase = ((fees.maxFeePerGas - oracleTip) * 100n) / viemPct;
+        const scaled = (impliedBase * config.baseFeeMultiplierPct) / 100n;
+        if (scaled + priorityFee > cap)
+            cap = scaled + priorityFee;
+    }
+    return cap > priorityFee ? cap : priorityFee;
+}
+async function estimateFeeHistoryGasFees(client, chainId, config) {
     const feeHistory = await client.getFeeHistory({
         blockCount: config.historyBlocks,
         rewardPercentiles: [config.tipPercentile, config.congestedTipPercentile],
@@ -161,8 +519,30 @@ async function estimateFeeHistoryGasFees(client, config) {
     const priorityFee = windowedTip > config.tipFloorWei ? windowedTip : config.tipFloorWei;
     // baseFeePerGas has historyBlocks + 1 entries; the last is the *next* block's
     // base fee (the one our tx lands in), not the latest mined block's.
-    const baseFee = feeHistory.baseFeePerGas.at(-1) ?? 0n;
-    const maxFeePerGas = baseFee * config.baseFeeMultiplier + priorityFee;
+    //
+    // Optional chaining, not a bare `.at()`: an absent array would otherwise throw
+    // a TypeError here rather than reaching the fallback below.
+    const baseFee = feeHistory.baseFeePerGas?.at(-1);
+    if (baseFee === undefined) {
+        // The RPC answered without telling us the base fee. Defaulting to 0n would
+        // price the cap at the tip alone — on mainnet an unincludable bid AND a ~20x
+        // under-charge, silently — so that is not an option. Throwing is not a good
+        // one either: this is a successful HTTP 200 carrying bad data, so viem's
+        // transport retries never fire, and the chains on this path include Plasma
+        // at ~69k fills/wk. So fall back for the BASE only.
+        //
+        // Keeping `priorityFee` is the point. These chains are on the windowed path
+        // precisely because their tip oracle is untrustworthy (Plasma's reports
+        // 0.005 gwei against a measured 0.0015), so falling back to viem wholesale
+        // would trade a hard failure for a silent ~3x overcharge on our
+        // highest-volume chain. The tip we already computed is the calibrated one.
+        recordDegradedEstimate(chainId, 'feehistory_missing_base');
+        return {
+            maxFeePerGas: await viemFallbackCap(client, config, priorityFee),
+            maxPriorityFeePerGas: priorityFee,
+        };
+    }
+    const maxFeePerGas = (baseFee * config.baseFeeMultiplierPct) / 100n + priorityFee;
     return { maxFeePerGas, maxPriorityFeePerGas: priorityFee };
 }
 // Nearest-rank percentile over a bigint sample. Empty sample → 0n.

package/dist/tipClamp.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Applies a chain's tip cap and floor, in the order that makes the FLOOR win.
+ *
+ * The cap is measured from what included transactions actually pay, so it is
+ * the tighter evidence of what a chain requires. The floor is a safety guard,
+ * and on BSC it is the chain's post-Maxwell protocol MINIMUM — a bid below it
+ * is rejected outright. So the cap applies first and the floor last, making
+ * `result >= floor` hold for any cap value, including a cap below the floor.
+ *
+ * No chain has a cap below its floor today (BSC is the only chain in both
+ * tables: cap 0.055, floor 0.05), which is exactly why this ordering has to be
+ * pinned by a test rather than by the current data.
+ *
+ * This lives in its own module rather than in `chains.ts` because `./chains` is
+ * a public package export — anything exported from there becomes SDK API, and
+ * consumers must not be able to depend on cap/floor ordering internals. This
+ * module has no `exports` subpath, so it is importable by the test and not by
+ * consumers.
+ */
+export declare function clampTip(tip: bigint, floorWei: bigint | undefined, capWei: bigint | undefined): bigint;
+//# sourceMappingURL=tipClamp.d.ts.map

package/dist/tipClamp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tipClamp.d.ts","sourceRoot":"","sources":["../src/tipClamp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,QAAQ,CACtB,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,MAAM,EAAE,MAAM,GAAG,SAAS,GACzB,MAAM,CAKR"}

package/dist/tipClamp.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.clampTip = clampTip;
+/**
+ * Applies a chain's tip cap and floor, in the order that makes the FLOOR win.
+ *
+ * The cap is measured from what included transactions actually pay, so it is
+ * the tighter evidence of what a chain requires. The floor is a safety guard,
+ * and on BSC it is the chain's post-Maxwell protocol MINIMUM — a bid below it
+ * is rejected outright. So the cap applies first and the floor last, making
+ * `result >= floor` hold for any cap value, including a cap below the floor.
+ *
+ * No chain has a cap below its floor today (BSC is the only chain in both
+ * tables: cap 0.055, floor 0.05), which is exactly why this ordering has to be
+ * pinned by a test rather than by the current data.
+ *
+ * This lives in its own module rather than in `chains.ts` because `./chains` is
+ * a public package export — anything exported from there becomes SDK API, and
+ * consumers must not be able to depend on cap/floor ordering internals. This
+ * module has no `exports` subpath, so it is importable by the test and not by
+ * consumers.
+ */
+function clampTip(tip, floorWei, capWei) {
+    let clamped = tip;
+    if (capWei !== undefined && capWei < clamped)
+        clamped = capWei;
+    if (floorWei !== undefined && floorWei > clamped)
+        clamped = floorWei;
+    return clamped;
+}

package/dist/viemDefaults.d.ts

@@ -0,0 +1,20 @@
+/**
+ * viem's default base-fee multiplier, as a percentage.
+ *
+ * viem builds its EIP-1559 estimate as `base * baseFeeMultiplier + tip`, with
+ * `baseFeeMultiplier` defaulting to 1.2 (actions/public/estimateFeesPerGas.js:
+ * `chain?.fees?.baseFeeMultiplier ?? 1.2`).
+ *
+ * We depend on that value in exactly one place: the degraded path in
+ * `cappedMaxFeePerGas`, which runs viem's formula BACKWARDS to recover the base
+ * fee when eth_feeHistory could not supply one. If viem ever changes this
+ * default, that division silently mis-scales the two chains whose own
+ * multiplier exceeds it (Gnosis, HyperEVM) — no error, just a wrong number.
+ *
+ * Lives in its own module, rather than in `chains.ts`, so the test that pins it
+ * against viem's real behaviour can import the same constant the code uses
+ * instead of a copy that could drift. `./chains` is a public package export;
+ * this module has no `exports` subpath, so it stays internal.
+ */
+export declare const VIEM_DEFAULT_BASE_FEE_MULTIPLIER_PCT = 120n;
+//# sourceMappingURL=viemDefaults.d.ts.map

package/dist/viemDefaults.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"viemDefaults.d.ts","sourceRoot":"","sources":["../src/viemDefaults.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,oCAAoC,OAAO,CAAA"}

package/dist/viemDefaults.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VIEM_DEFAULT_BASE_FEE_MULTIPLIER_PCT = void 0;
+/**
+ * viem's default base-fee multiplier, as a percentage.
+ *
+ * viem builds its EIP-1559 estimate as `base * baseFeeMultiplier + tip`, with
+ * `baseFeeMultiplier` defaulting to 1.2 (actions/public/estimateFeesPerGas.js:
+ * `chain?.fees?.baseFeeMultiplier ?? 1.2`).
+ *
+ * We depend on that value in exactly one place: the degraded path in
+ * `cappedMaxFeePerGas`, which runs viem's formula BACKWARDS to recover the base
+ * fee when eth_feeHistory could not supply one. If viem ever changes this
+ * default, that division silently mis-scales the two chains whose own
+ * multiplier exceeds it (Gnosis, HyperEVM) — no error, just a wrong number.
+ *
+ * Lives in its own module, rather than in `chains.ts`, so the test that pins it
+ * against viem's real behaviour can import the same constant the code uses
+ * instead of a copy that could drift. `./chains` is a public package export;
+ * this module has no `exports` subpath, so it stays internal.
+ */
+exports.VIEM_DEFAULT_BASE_FEE_MULTIPLIER_PCT = 120n;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rhinestone/service-sdk",
-  "version": "0.2.11",
+  "version": "0.2.12",
   "description": "Shared SDK for Rhinestone services",
   "author": {
     "name": "Rhinestone",