@rhinestone/service-sdk 0.2.13 → 0.2.15

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

@@ -13,6 +13,27 @@ export type EstimateGasFeesOptions = {
      */
     mode?: 'legacy';
 };
+/**
+ * {@link estimateGasFees}' result: viem's EIP-1559 fee values plus the next
+ * block's base fee, when it could be read.
+ *
+ * `baseFeePerGas` is surfaced because `maxFeePerGas` is a submission CAP
+ * (`base * baseFeeMultiplierPct + tip`) — the price we are willing to bid up to,
+ * not the price a transaction pays (`base + tip`). Billing the cap is correct
+ * where a relayer must stay covered if the base fee climbs before inclusion; it
+ * is wrong to REPORT to a consumer that compares it against other relayers.
+ * Exposing the base fee lets a caller derive the expected price WITHOUT a second
+ * eth_feeHistory round trip — every path here already reads it and used to
+ * discard it (RHI-4992).
+ *
+ * `null` when the base fee was unavailable: a non-1559 chain, `mode: 'legacy'`,
+ * or a degraded read (already recorded via `recordDegradedEstimate`). Callers
+ * must treat null as "unknown" and fall back — never as zero, which would price
+ * a cap at the tip alone.
+ */
+export type EstimatedGasFees = FeeValuesEIP1559 & {
+    baseFeePerGas: bigint | null;
+};
 /**
  * Estimates gas fees for a chain and returns EIP-1559-shaped fee values.
  *
@@ -28,5 +49,5 @@ export type EstimateGasFeesOptions = {
  * zero. This changes fee estimation only; it does not select a transaction
  * type.
  */
-export declare function estimateGasFees(client: FeeEstimationClient, chainId: number, options?: EstimateGasFeesOptions): Promise<FeeValuesEIP1559>;
+export declare function estimateGasFees(client: FeeEstimationClient, chainId: number, options?: EstimateGasFeesOptions): Promise<EstimatedGasFees>;
 //# sourceMappingURL=chains.d.ts.map

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;AAyUD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,mBAAmB,EAC3B,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,sBAAsB,GAC/B,OAAO,CAAC,gBAAgB,CAAC,CA2C3B"}
+{"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"}

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
@@ -311,7 +343,12 @@ async function estimateGasFees(client, chainId, options) {
         // Equal caps preserve gasPrice as the effective-price ceiling. If a
         // no-priority local fork reports baseFee == gasPrice, the max-fee cap means
         // the actual paid tip remains zero despite this priority-fee allowance.
-        return { maxFeePerGas: gasPrice, maxPriorityFeePerGas: gasPrice };
+        // Legacy has no base-fee component to report.
+        return {
+            maxFeePerGas: gasPrice,
+            maxPriorityFeePerGas: gasPrice,
+            baseFeePerGas: null,
+        };
     }
     if (HISTORICAL_FEE_CHAINS.has(chainId)) {
         const config = { ...DEFAULT_FEE_CONFIG, ...FEE_CONFIG_OVERRIDES[chainId] };
@@ -335,6 +372,7 @@ async function estimateGasFees(client, chainId, options) {
     return {
         maxFeePerGas: cappedMaxFeePerGas(client, fees, baseFee, chainId, tip, oracleTip),
         maxPriorityFeePerGas: tip,
+        baseFeePerGas: baseFee,
     };
 }
 // viem's oracle tip, lifted to an absolute floor — and, for windowed-tip chains,
@@ -375,6 +413,7 @@ async function estimateViemFeesWithTipFloor(client, chainId, tipFloorWei) {
     return {
         maxFeePerGas: cappedMaxFeePerGas(client, fees, history.baseFee, chainId, tip, oracleTip),
         maxPriorityFeePerGas: tip,
+        baseFeePerGas: history.baseFee,
     };
 }
 /**
@@ -557,10 +596,15 @@ async function estimateFeeHistoryGasFees(client, chainId, config) {
         return {
             maxFeePerGas: await viemFallbackCap(client, config, priorityFee),
             maxPriorityFeePerGas: priorityFee,
+            baseFeePerGas: null,
         };
     }
     const maxFeePerGas = (baseFee * config.baseFeeMultiplierPct) / 100n + priorityFee;
-    return { maxFeePerGas, maxPriorityFeePerGas: priorityFee };
+    return {
+        maxFeePerGas,
+        maxPriorityFeePerGas: priorityFee,
+        baseFeePerGas: baseFee,
+    };
 }
 // Nearest-rank percentile over a bigint sample. Empty sample → 0n.
 function percentileBigInt(values, percentile) {

package/package.json

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