@rhinestone/service-sdk 0.2.15 → 0.2.16

package/dist/chains.d.ts

@@ -12,6 +12,54 @@ export type EstimateGasFeesOptions = {
      * Omit this option to retain the chain-aware EIP-1559 estimation strategy.
      */
     mode?: 'legacy';
+    /**
+     * Samples the per-block tip at this percentile instead of the chain's
+     * configured `tipPercentile`/`congestedTipPercentile`, for a caller that must
+     * deliberately price against something other than our own calibration.
+     *
+     * The one caller today is the Safe GTF gas-price feed (RHI-4992). Safe
+     * benchmarks that feed against Gelato's `relayer_getFeeData` and asked us to
+     * match its mainnet buffer, having previously used Gelato for the same
+     * self-pay flow. Gelato fits to `base + tip`, 20-block window, NO multiplier —
+     * the same shape as our windowed path, so tracking them is a percentile and
+     * nothing else. Which percentile, measured on 314 paired live samples over 95
+     * minutes (2026-08-10, mainnet):
+     *
+     *   pctl   model/gelato p10   median      p90   mean|err| gwei
+     *   p50               0.479    0.669    0.889          0.15124
+     *   p60               0.624    0.879    1.085          0.10221
+     *   p65               0.725    1.045    1.264          0.08906   <- parity
+     *   p70               0.985    1.411    1.793          0.16159
+     *
+     * MEASURE IT OVER HOURS, NOT MINUTES. Two short fits of this same quantity, on
+     * the same day, gave p60 at 0.982 (25 samples / 100s) and 0.785 (40 samples /
+     * 4 min) — and the 314-sample answer is 0.879. Even the CUMULATIVE median
+     * inside the long run wandered 1.006 -> 0.844 -> 0.929 -> 0.881 as it filled
+     * up. A 5-percentile step moves the median 19-35%, so a short window can
+     * "prove" almost any percentile. An older fit also needed a x1.17 multiplier;
+     * that is gone. Re-fit against live data before trusting any number here.
+     *
+     * DELIBERATELY NOT the chain default. Our own mainnet calibration is p25 plus
+     * a realized-clearing floor. p65 sits on the steep face of mainnet's tip cliff
+     * and prices at ~1.5x what a transaction actually costs (Gelato itself: 1.494x
+     * median, p10 1.125 / p90 2.089 — they swing because they stand on the same
+     * cliff). This override exists so ONE surface can opt into a competitor's
+     * pricing without moving intent pricing, which shares this function.
+     *
+     * The cliff MOVES, which is why it is a cliff and not a constant: a 120-block
+     * replay read a realized p50 tip of 0.0094 gwei (39,312 txs) in the morning
+     * and 0.148 gwei (34,314 txs) a few hours later — 16x — with p75 going
+     * 0.25 -> 1.00 gwei over the same span.
+     *
+     * Applies to the windowed feeHistory path only (`HISTORICAL_FEE_CHAINS`).
+     * Ignored on the viem path, where the tip does not come from a percentile we
+     * choose. Mainnet — the only chain that needs it — is on the windowed path.
+     *
+     * Requests a single reward column and pins the read to it, so congestion
+     * escalation cannot silently move the sampled percentile somewhere else — the
+     * caller asked to track one number.
+     */
+    tipPercentileOverride?: number;
 };
 /**
  * {@link estimateGasFees}' result: viem's EIP-1559 fee values plus the next

package/dist/chains.d.ts.map

@@ -1 +1 @@
-{"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;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,gBAAgB,GAAG,gBAAgB,GAAG;IAChD,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;CAC7B,CAAA;AAyWD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,mBAAmB,EAC3B,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,sBAAsB,GAC/B,OAAO,CAAC,gBAAgB,CAAC,CAiD3B"}
+{"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;IACf;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8CG;IACH,qBAAqB,CAAC,EAAE,MAAM,CAAA;CAC/B,CAAA;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,gBAAgB,GAAG,gBAAgB,GAAG;IAChD,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;CAC7B,CAAA;AAyWD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,mBAAmB,EAC3B,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,sBAAsB,GAC/B,OAAO,CAAC,gBAAgB,CAAC,CAqE3B"}

package/dist/chains.js

@@ -335,6 +335,16 @@ async function nextBlockBaseFee(client, chainId) {
  * type.
  */
 async function estimateGasFees(client, chainId, options) {
+    // Validated HERE, at the public entry, rather than where it is used. A bad value
+    // otherwise surfaces as an opaque provider error from eth_feeHistory — and only on the
+    // chains that take the windowed path, so the same argument would throw on mainnet and
+    // be silently ignored on Base. This is a locally decidable input; fail locally and say
+    // what was wrong. (Copilot, PR #24.)
+    const override = options?.tipPercentileOverride;
+    if (override !== undefined &&
+        (!Number.isFinite(override) || override < 0 || override > 100)) {
+        throw new Error(`tipPercentileOverride must be a finite number in [0, 100], got ${override}`);
+    }
     if (options?.mode === 'legacy') {
         const legacyClient = client;
         const { gasPrice } = await legacyClient.estimateFeesPerGas({
@@ -352,7 +362,7 @@ async function estimateGasFees(client, chainId, options) {
     }
     if (HISTORICAL_FEE_CHAINS.has(chainId)) {
         const config = { ...DEFAULT_FEE_CONFIG, ...FEE_CONFIG_OVERRIDES[chainId] };
-        return estimateFeeHistoryGasFees(client, chainId, config);
+        return estimateFeeHistoryGasFees(client, chainId, config, options?.tipPercentileOverride);
     }
     const tipFloorWei = TIP_FLOOR_WEI[chainId];
     if (tipFloorWei !== undefined) {
@@ -558,17 +568,27 @@ async function viemFallbackCap(client, config, priorityFee) {
     }
     return cap > priorityFee ? cap : priorityFee;
 }
-async function estimateFeeHistoryGasFees(client, chainId, config) {
+async function estimateFeeHistoryGasFees(client, chainId, config, tipPercentileOverride) {
+    // An override asks for ONE percentile, so ask the RPC for one column. It
+    // cannot be requested as [p, p]: geth rejects a reward-percentile list that is
+    // not strictly increasing — "invalid reward percentile: #0:60.000000 >=
+    // #1:60.000000", verified live 2026-08-10 against publicnode and 1rpc — so the
+    // duplicate form is an RPC error, not a pricing choice.
+    const overridden = tipPercentileOverride !== undefined;
     const feeHistory = await client.getFeeHistory({
         blockCount: config.historyBlocks,
-        rewardPercentiles: [config.tipPercentile, config.congestedTipPercentile],
+        rewardPercentiles: overridden
+            ? [tipPercentileOverride]
+            : [config.tipPercentile, config.congestedTipPercentile],
     });
     const ratios = feeHistory.gasUsedRatio ?? [];
     const meanRatio = ratios.length > 0
         ? ratios.reduce((sum, r) => sum + r, 0) / ratios.length
         : 0;
-    // Under load, read the per-block tip from the higher percentile column.
-    const column = meanRatio > config.congestionRatio ? 1 : 0;
+    // Under load, read the per-block tip from the higher percentile column. With
+    // an override there is only column 0, and escalating is not wanted anyway —
+    // the caller asked to track one percentile, so congestion must not move it.
+    const column = !overridden && meanRatio > config.congestionRatio ? 1 : 0;
     const perBlockTips = (feeHistory.reward ?? []).map((r) => r?.[column] ?? 0n);
     const windowedTip = percentileBigInt(perBlockTips, config.windowTipPercentile);
     const priorityFee = windowedTip > config.tipFloorWei ? windowedTip : config.tipFloorWei;

package/package.json

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