@rhinestone/service-sdk 0.2.14 → 0.2.16

package/README.md

@@ -1,22 +1,205 @@
-# service-sdk
+# @rhinestone/service-sdk
+
+Shared TypeScript utilities for Rhinestone backend services — the pieces every service
+needs and none of them should reimplement: OpenTelemetry setup and helpers, chain-aware gas
+fee estimation, and BigInt-safe JSON serialization.
+
+Published to npm and consumed by `orchestrator`, `relayer`, `deposit-service-processor`,
+`route-stats`, `back-office` (api), and `1auth` (passkey, recovery-signer).
+
+Deliberately not a home for domain logic. The one module that encodes real judgement —
+`chains` — earns it by being pure pricing arithmetic that several services must agree on;
+everything else is glue.
+
+## Install
+
+```sh
+bun add @rhinestone/service-sdk
+```
+
+`viem` is a peer dependency (`^2.40.1`), needed only for the `chains` entry point.
+
+## Entry points
+
+| Import | What |
+|---|---|
+| `@rhinestone/service-sdk` | Re-exports `./serialization` only |
+| `@rhinestone/service-sdk/chains` | Chain-aware gas fee estimation |
+| `@rhinestone/service-sdk/opentelemetry` | SDK setup, tracing/metrics helpers, propagation, integrations |
+| `@rhinestone/service-sdk/serialization` | BigInt-safe JSON serialization |
+
+---
 
 ## Gas fee estimation
 
 ```ts
 import { estimateGasFees } from '@rhinestone/service-sdk/chains'
 
-const fees = await estimateGasFees(client, chainId)
-const legacyFees = await estimateGasFees(client, chainId, { mode: 'legacy' })
+const { maxFeePerGas, maxPriorityFeePerGas, baseFeePerGas } =
+  await estimateGasFees(client, chainId)
 ```
 
-With no options, `estimateGasFees` retains its chain-aware fee estimation
-behavior. Legacy mode takes precedence over all chain-specific logic and calls
-`client.estimateFeesPerGas({ type: 'legacy' })` without requesting fee history.
-
-The return type remains EIP-1559-shaped in both modes. Legacy `gasPrice` is
-normalized to
-`{ maxFeePerGas: gasPrice, maxPriorityFeePerGas: gasPrice }`. Equal caps
-preserve the legacy effective-price ceiling when the result is used as EIP-1559
-fees. On a no-priority local fork where `baseFee == gasPrice`, the max-fee cap
-means the actual paid tip is still zero. The mode selects the estimation source
-only; it does not select or modify a transaction type.
+`estimateGasFees` returns EIP-1559-shaped fees for every chain and every mode. The whole
+module exists because viem's default estimator systematically mis-prices our fills: the
+orchestrator **bills** `maxFeePerGas`, but on-chain a transaction only ever pays
+`base + tip`, so unused headroom is charged to the user rather than spent.
+
+**Three estimation strategies**, selected per chain:
+
+- **Windowed `eth_feeHistory`** (mainnet, sepolia, plasma) — pools tips across a 20-block
+  window and prices the base from the *next* block, escalating to a higher reward
+  percentile when the window's mean `gasUsedRatio` shows congestion. Chains land here
+  either for a volatile base fee (the L1s) or a broken tip oracle (plasma, whose
+  `eth_maxPriorityFeePerGas` reports ~3.5x what fills actually clear at).
+- **viem's estimate with a tip floor** (base, bsc, polygon, gnosis, hyperEVM, monad) — for
+  chains whose base fee is stable but whose tip oracle *under*-reports. Polygon and base
+  additionally window the feeHistory tip, since their real tip drifts above a static floor.
+- **viem's estimate plain** — everything else.
+
+On both viem paths a per-chain tip **cap** also applies where the oracle *over*-reports
+(optimism, soneium, sonic, avalanche, bsc). Cap and floor can both be set for one chain —
+bsc is — in which case the cap applies first and the floor last, so a floor is never
+undercut.
+
+`maxFeePerGas` is rebuilt as `nextBlockBaseFee * multiplier + tip` — the next block's base,
+not the latest mined one, which is where most of the over-charge disappears. The multiplier
+is per-chain and each path has its own table: 1.05x by default on the viem paths (overridden
+for hyperEVM, gnosis, avalanche), and part of the per-chain fee config on the windowed path
+(1.30x sepolia, 1.60x mainnet, 2.00x plasma).
+
+**`baseFeePerGas` in the result** lets a caller derive the expected price without a second
+`eth_feeHistory` round trip. It matters because `maxFeePerGas` is a submission *cap* — right
+to bill, wrong to report to a consumer comparing relayers. It is `null` — never `0n` — when
+the base was unavailable (non-1559 chain, legacy mode, or a degraded read). Treat `null` as
+unknown and fall back; treating it as zero would price a cap at the tip alone.
+
+### Legacy mode
+
+```ts
+const fees = await estimateGasFees(client, chainId, { mode: 'legacy' })
+```
+
+Takes precedence over all chain-specific logic and calls
+`client.estimateFeesPerGas({ type: 'legacy' })` without requesting fee history. The legacy
+`gasPrice` is normalized to `{ maxFeePerGas: gasPrice, maxPriorityFeePerGas: gasPrice }` —
+equal caps preserve the legacy effective-price ceiling for EIP-1559 consumers. On a
+no-priority local fork where `baseFee == gasPrice`, the max-fee cap keeps the paid tip at
+zero. The mode selects the estimation *source* only; it does not select a transaction type.
+
+### When the RPC degrades
+
+Every fallback here is silent by design — an `eth_feeHistory` outage must never become a
+quote outage. Because that would otherwise revert a chain to exactly the pricing this module
+removes, with nothing to show for it, the degraded paths annotate the **active span**
+(`gas.estimate.degraded`, `gas.estimate.degraded_reason`, `gas.estimate.chain_id`) rather
+than a logger. `@opentelemetry/api` is a no-op without a registered SDK, so this costs
+nothing for uninstrumented consumers.
+
+### Changing the per-chain numbers
+
+Every floor, cap and multiplier in `src/chains.ts` is annotated with the evidence it came
+from — measured clearing prices, block replays, dated probes — and several encode a
+deliberate trade rather than an optimum. **Read the comment before changing the number**;
+these values price real fills on seven services, and the reasoning is not reconstructible
+from the value alone.
+
+---
+
+## OpenTelemetry
+
+### Setup
+
+```ts
+import { setupSDK, configFromEnv, shutdownOpentelemetry } from '@rhinestone/service-sdk/opentelemetry'
+
+setupSDK({ serviceName: 'my-service', ...configFromEnv() })
+```
+
+`setupSDK` is idempotent and wires the whole stack in one call: an `AsyncLocalStorage`
+context manager, gzip'd OTLP/gRPC trace and metric exporters, a tuned `BatchSpanProcessor`,
+host metrics, and a `startup_time` gauge used as a deploy marker. It also registers a
+`beforeExit` flush, so a clean shutdown exports what is still queued.
+
+`configFromEnv()` reads `VERSION` and `DEPLOYMENT_ENV`. The OTLP endpoint comes from the
+standard `OTEL_EXPORTER_OTLP_ENDPOINT`.
+
+**Bundled instrumentations**, all enabled by `setupSDK`: `http` (WebSocket upgrades ignored,
+so a long-lived connection can't produce an enormous span), `express` (captures referer and
+request body on handler spans), `amqplib`, `prisma`, `pino` (log *correlation* only —
+sending is disabled), and `viem` (parent-span-gated, capturing operation results).
+
+### Tracing
+
+```ts
+import { withSpan, currentSpan, currentTraceId, addSpanAttributes, recordSpanError, CreateSpan } from '@rhinestone/service-sdk/opentelemetry'
+```
+
+`withSpan(name, fn, options?)` runs `fn` in an active span, handling sync and async
+identically: it records the exception, sets `ERROR` status and ends the span on a throw or
+rejection, then rethrows. `CreateSpan(name?)` is the decorator form for class methods.
+`withRootContext(fn)` detaches from the ambient context to start a fresh trace.
+`currentSpan`, `currentContext`, `currentTraceId`, `addSpanAttributes` and `recordSpanError`
+operate on whatever span is active.
+
+### Metrics
+
+`createCounter`, `createHistogram`, `createGauge` and `createObservableGauge`, each taking
+an optional `MetricOptions`. `SpanStatusCode`, `ValueType` and the OTel API types are
+re-exported so consumers need no direct `@opentelemetry/api` dependency.
+
+### Propagation
+
+`getTraceHeaders()` returns W3C `traceparent`/`tracestate` as a plain object for axios or
+generic HTTP. `injectTraceHeaders` is the viem `onFetchRequest` hook form, propagating trace
+context into outgoing RPC calls.
+
+---
+
+## Serialization
+
+```ts
+import { convertBigIntFields, stringifyBigIntFields, bigintReplacer } from '@rhinestone/service-sdk/serialization'
+```
+
+`BigInt` has no JSON representation, so an un-converted payload makes `JSON.stringify`
+throw. These convert it to decimal strings.
+
+- `convertBigIntFields(value, options?)` — returns a converted copy.
+- `stringifyBigIntFields(value, options?)` — stringifies directly, preserving
+  `JSON.stringify`'s `toJSON` semantics (so a `Date` still becomes an ISO string).
+- `bigintReplacer` — the bare replacer, with no guards, for use with `JSON.stringify`.
+
+Both guarded functions **throw** on circular references and past `maxDepth`
+(`DEFAULT_BIGINT_CONVERSION_MAX_DEPTH`, 100) rather than emitting lossy placeholders.
+`convertFiniteNumbers: true` additionally encodes finite numbers as strings, for
+canonical-signing payloads.
+
+---
+
+## Development
+
+```sh
+bun install
+bun run build      # clean + tsc
+bun run test
+bun run check      # biome (src only — see below)
+bun run check:fix
+```
+
+Dependency installs are gated on a 3-day release age (`bunfig.toml`,
+`minimumReleaseAge`) as a supply-chain mitigation, so a freshly published — or freshly
+compromised — version is not picked up immediately.
+
+Note that biome is scoped to `src/**`, so `test/**` is neither linted nor format-checked.
+
+## Releasing
+
+Publishing is automated. Cut a **GitHub Release** with tag `vX.Y.Z`; `release.yml` builds and
+publishes to npm via OIDC trusted publishing.
+
+The **tag is the version**. `package.json` says `0.0.1` and is never bumped — the workflow
+overwrites it at publish time from the tag name. Don't try to keep it in sync.
+
+Consumers pin a mix of exact versions and caret ranges, so **a `0.2.x` release reaches
+every caret consumer on its next install, with no PR in that service**. Treat any change to
+gas pricing as shipping to production on that basis.

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;AAyUD;;;;;;;;;;;;;;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

@@ -41,19 +41,51 @@ const DEFAULT_FEE_CONFIG = {
 // Per-chain overrides for the windowed feeHistory path; any omitted field falls
 // back to DEFAULT_FEE_CONFIG.
 const FEE_CONFIG_OVERRIDES = {
-    // 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.
+    // Sepolia's reward distribution is a STEP FUNCTION, not a gradient. Replayed 300
+    // blocks / 38,746 txs on 2026-08-10:
+    //
+    //   realised priority fee   p1-p10 0.001   p25 0.0012   p50 0.354   p75 1.000
+    //   per-block MINIMUM included tip: 0.001 gwei in essentially every block
+    //
+    // So a mass sits at 0.001 and another at 1.0 with almost nothing between, and the
+    // percentile choice is the whole price. p50 lands ON the cliff (0.22 gwei live) and
+    // p75 lands past it (1.16) — against a price that demonstrably clears at 0.001.
+    //
+    // This chain was billing ~1000x that clearing price. Paired against live feeHistory
+    // 12 times, our tip tracked p75 at ratio 0.98 while the median block was only 36%
+    // full: sepolia has 4-6 completely full blocks per 20-block window, and the
+    // congestion predicate takes the MEAN gasUsedRatio, so those outliers alone hold it
+    // on the 0.5 threshold (sampled means 0.499-0.541, escalating in 5 of 8 samples).
+    // The quote therefore oscillated between a 0.22 and a 1.16 gwei tip minute to minute.
+    //
+    // MEASURED effect, simulated against live feeHistory 10x with both configs side by
+    // side rather than derived on paper (the paper number was wrong):
+    //
+    //   tip  1.1124 -> 0.1300 gwei   (9x lower)
+    //   cap  2.49   -> 1.51   gwei   (1.68x cheaper, at a ~1.0 gwei base fee)
+    //
+    // Note WHICH knob does the work. Congestion fired in 10 of 10 samples, so sepolia
+    // effectively never reads `tipPercentile` at all — `congestedTipPercentile` is the
+    // live lever, and 75 -> 50 is what buys the 9x. The 50 -> 25 only starts to bite once
+    // the mean-based predicate below is fixed, at which point this gets cheaper again
+    // (p25 reads 0.0011 gwei). Reported by an external consumer as 3.3x over spot
+    // (RHI-5618).
+    //
+    // NOTE the mean-based congestion predicate is a SEPARATE defect and is deliberately
+    // NOT fixed here: mainnet sits on the same 0.5 knife-edge (measured mean 0.475-0.502,
+    // flipping), so switching it to a median would silently re-tune mainnet's tip too.
+    // That needs its own A/C measurement — see RHI-5618.
     [chains_1.sepolia.id]: {
+        // Unchanged. The base multiplier was already lowered 2.0x -> 1.3x and was never
+        // the dominant term here; the tip was.
         baseFeeMultiplierPct: 130n,
-        tipPercentile: 50,
-        congestedTipPercentile: 75,
-        tipFloorWei: 0n,
+        tipPercentile: 25,
+        congestedTipPercentile: 50,
+        // 0.001 gwei — the price sepolia inclusion demonstrably clears at, from the replay
+        // above. Was 0n: a zero floor lets a percentile read of 0 price the tip at nothing,
+        // and testnet inclusion is already flaky, so the floor is doing real work now that
+        // we sample low enough to hit it.
+        tipFloorWei: 1000000n,
     },
     // Mainnet's reward distribution is inflated by MEV-boost blocks — searchers
     // pay enormous priority fees, so the feeHistory p50 prices our plain fills
@@ -303,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({
@@ -320,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) {
@@ -526,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.14",
+  "version": "0.2.16",
   "description": "Shared SDK for Rhinestone services",
   "author": {
     "name": "Rhinestone",