@rhinestone/service-sdk 0.2.15 → 0.2.17

package/README.md

@@ -2,7 +2,7 @@
 
 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.
+fee estimation, graceful-shutdown plumbing, 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).
@@ -25,6 +25,7 @@ bun add @rhinestone/service-sdk
 |---|---|
 | `@rhinestone/service-sdk` | Re-exports `./serialization` only |
 | `@rhinestone/service-sdk/chains` | Chain-aware gas fee estimation |
+| `@rhinestone/service-sdk/lifecycle` | Termination signals, crashes and explicit aborts as one channel |
 | `@rhinestone/service-sdk/opentelemetry` | SDK setup, tracing/metrics helpers, propagation, integrations |
 | `@rhinestone/service-sdk/serialization` | BigInt-safe JSON serialization |
 
@@ -105,6 +106,50 @@ from the value alone.
 
 ---
 
+## Lifecycle
+
+```ts
+import {
+  installTerminationHandlers,
+  terminationExitCode,
+  describeReason,
+} from '@rhinestone/service-sdk/lifecycle'
+
+const termination = installTerminationHandlers()
+
+const reason = await Promise.race([serve(termination), termination.waitForTermination()])
+
+logger.info(`shutting down: ${describeReason(reason)}`)
+await teardownInOrder()
+process.exit(terminationExitCode(reason))
+```
+
+Folds every way a process can be asked to stop into one channel: `SIGTERM` / `SIGINT`, an
+uncaught exception, an unhandled rejection, and an explicit `terminate(reason)` from code
+that found a broken invariant. `waitForTermination()` resolves once with a discriminated
+`TerminationReason`, so the caller can log it and pick an exit code instead of every call
+site inventing its own.
+
+**The first reason wins; later ones are dropped.** That is the point rather than a detail:
+sockets closing during a shutdown routinely orphan promises, and those rejections must not
+restart the shutdown or flip a clean stop to a failure.
+
+`isTerminating()` is the same state as a synchronous boolean, for the callers that can't
+await — readiness probes returning 503 the instant a signal lands, admission gates refusing
+new work while in-flight work drains.
+
+Two things to know:
+
+- **Registering an `uncaughtException` / `unhandledRejection` listener stops Node exiting on
+  either.** The caller *must* exit once teardown is done, or a crashed process lingers.
+- Nothing is registered at import time, and each install is independent. The install call is
+  the only thing that touches `process`, and `dispose()` removes exactly what it added, so
+  tests get a fresh one and own its disposal.
+
+This module logs nothing itself; reporting is the owner's job, once the promise resolves.
+
+---
+
 ## OpenTelemetry
 
 ### Setup

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/dist/lifecycle.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Process termination as one observable event.
+ *
+ * A shutdown needs two different things, and a bare promise only gives the
+ * first: an *ordered* teardown (release this, then close that), and an
+ * *immediate* answer to "should I still take on new work?" for readiness probes
+ * and admission gates. Handing those callers a promise means each of them keeps
+ * its own boolean in sync with it, which is the bug this shape avoids.
+ *
+ * Every way a process can be asked to stop lands in the same channel:
+ *
+ * - an external signal — SIGTERM from an orchestrator, SIGINT from a terminal
+ * - an uncaught exception or an unhandled rejection
+ * - an explicit `terminate()` from code that found a broken invariant
+ *
+ * The first reason wins; anything after it is dropped. That is what keeps a
+ * crash *during* shutdown from restarting the shutdown or changing its exit
+ * code — orphaned promises rejecting as sockets close is normal, and must not
+ * turn a clean stop into a failed one.
+ *
+ * Nothing is registered at import time. `installTerminationHandlers` is the only
+ * thing that touches `process`, and `dispose()` undoes exactly what it added.
+ */
+/** Why the process was asked to stop. */
+export type TerminationReason = {
+    kind: 'signal';
+    signal: NodeJS.Signals;
+} | {
+    kind: 'uncaughtException';
+    error: Error;
+} | {
+    kind: 'unhandledRejection';
+    reason: unknown;
+} | {
+    kind: 'explicit';
+    reason: string | Error | object;
+};
+export interface Termination {
+    /**
+     * Resolves once, with whatever asked the process to stop. Never rejects, and
+     * safe to await from several places; awaiting after the fact returns the
+     * reason that already settled. Reporting the reason is the owner's job — this
+     * module logs nothing.
+     */
+    waitForTermination(): Promise<TerminationReason>;
+    /**
+     * True from the instant a reason arrives. For readiness gates and admission
+     * checks that must answer synchronously, long before teardown finishes.
+     */
+    isTerminating(): boolean;
+    /**
+     * Ask the process to stop: an invariant broke and it must not keep running.
+     * The reason is carried through to the awaiting caller — an `Error` where
+     * there is one, or a string / context object where the caller has facts
+     * rather than a throw. First caller wins.
+     */
+    terminate(reason: string | Error | object): void;
+    /** Remove the process listeners this install added. Idempotent. */
+    dispose(): void;
+}
+/**
+ * Register the process listeners and return the channel they feed.
+ *
+ * Each call is independent: it installs its own listeners and owns its own
+ * reason, so two installs in one process both fire. That is deliberate — tests
+ * want a fresh one — and it means the caller is responsible for `dispose()`.
+ *
+ * Registering an `uncaughtException` / `unhandledRejection` listener stops Node
+ * from exiting on either, so **the caller must exit itself** once teardown is
+ * done. Use `terminationExitCode` for the code.
+ */
+export declare function installTerminationHandlers(): Termination;
+/**
+ * The exit code to leave with: 0 for a signal, 1 for everything else.
+ *
+ * A handled SIGTERM means the process did what it was asked, so a clean 0 —
+ * exiting non-zero there makes an orderly rollout look like a failed one.
+ */
+export declare function terminationExitCode(reason: TerminationReason): number;
+/** One-line description of a reason, for the owner's shutdown log. */
+export declare function describeReason(reason: TerminationReason): string;
+//# sourceMappingURL=lifecycle.d.ts.map

package/dist/lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../src/lifecycle.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,yCAAyC;AACzC,MAAM,MAAM,iBAAiB,GACzB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC,OAAO,CAAA;CAAE,GAC1C;IAAE,IAAI,EAAE,mBAAmB,CAAC;IAAC,KAAK,EAAE,KAAK,CAAA;CAAE,GAC3C;IAAE,IAAI,EAAE,oBAAoB,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE,GAC/C;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,MAAM,EAAE,MAAM,GAAG,KAAK,GAAG,MAAM,CAAA;CAAE,CAAA;AAEzD,MAAM,WAAW,WAAW;IAC1B;;;;;OAKG;IACH,kBAAkB,IAAI,OAAO,CAAC,iBAAiB,CAAC,CAAA;IAChD;;;OAGG;IACH,aAAa,IAAI,OAAO,CAAA;IACxB;;;;;OAKG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,KAAK,GAAG,MAAM,GAAG,IAAI,CAAA;IAChD,mEAAmE;IACnE,OAAO,IAAI,IAAI,CAAA;CAChB;AAKD;;;;;;;;;;GAUG;AACH,wBAAgB,0BAA0B,IAAI,WAAW,CA2CxD;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,CAErE;AAED,sEAAsE;AACtE,wBAAgB,cAAc,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,CAWhE"}

package/dist/lifecycle.js

@@ -0,0 +1,96 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.installTerminationHandlers = installTerminationHandlers;
+exports.terminationExitCode = terminationExitCode;
+exports.describeReason = describeReason;
+const serialization_1 = require("./serialization");
+/** SIGTERM from orchestrators, SIGINT from terminals. */
+const SIGNALS = ['SIGTERM', 'SIGINT'];
+/**
+ * Register the process listeners and return the channel they feed.
+ *
+ * Each call is independent: it installs its own listeners and owns its own
+ * reason, so two installs in one process both fire. That is deliberate — tests
+ * want a fresh one — and it means the caller is responsible for `dispose()`.
+ *
+ * Registering an `uncaughtException` / `unhandledRejection` listener stops Node
+ * from exiting on either, so **the caller must exit itself** once teardown is
+ * done. Use `terminationExitCode` for the code.
+ */
+function installTerminationHandlers() {
+    let settledReason;
+    let resolve;
+    const reasonPromise = new Promise((r) => {
+        resolve = r;
+    });
+    const accept = (next) => {
+        if (settledReason !== undefined)
+            return;
+        settledReason = next;
+        resolve(next);
+    };
+    const onSignal = (signal) => {
+        accept({ kind: 'signal', signal });
+    };
+    const onUncaughtException = (error) => {
+        accept({ kind: 'uncaughtException', error });
+    };
+    const onUnhandledRejection = (reason) => {
+        accept({ kind: 'unhandledRejection', reason });
+    };
+    for (const signal of SIGNALS) {
+        process.on(signal, onSignal);
+    }
+    process.on('uncaughtException', onUncaughtException);
+    process.on('unhandledRejection', onUnhandledRejection);
+    return {
+        waitForTermination: () => reasonPromise,
+        isTerminating: () => settledReason !== undefined,
+        terminate: (reason) => {
+            accept({ kind: 'explicit', reason });
+        },
+        dispose: () => {
+            for (const signal of SIGNALS) {
+                process.off(signal, onSignal);
+            }
+            process.off('uncaughtException', onUncaughtException);
+            process.off('unhandledRejection', onUnhandledRejection);
+        },
+    };
+}
+/**
+ * The exit code to leave with: 0 for a signal, 1 for everything else.
+ *
+ * A handled SIGTERM means the process did what it was asked, so a clean 0 —
+ * exiting non-zero there makes an orderly rollout look like a failed one.
+ */
+function terminationExitCode(reason) {
+    return reason.kind === 'signal' ? 0 : 1;
+}
+/** One-line description of a reason, for the owner's shutdown log. */
+function describeReason(reason) {
+    switch (reason.kind) {
+        case 'signal':
+            return `signal ${reason.signal}`;
+        case 'uncaughtException':
+            return `uncaught exception: ${formatValue(reason.error)}`;
+        case 'unhandledRejection':
+            return `unhandled rejection: ${formatValue(reason.reason)}`;
+        case 'explicit':
+            return `explicit termination: ${formatValue(reason.reason)}`;
+    }
+}
+function formatValue(value) {
+    if (value instanceof Error)
+        return value.stack ?? value.message;
+    if (typeof value === 'string')
+        return value;
+    try {
+        // Guards bigints and circular references, both plausible in a context
+        // object assembled at the point an invariant broke.
+        return (0, serialization_1.stringifyBigIntFields)(value);
+    }
+    catch {
+        return String(value);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rhinestone/service-sdk",
-  "version": "0.2.15",
+  "version": "0.2.17",
   "description": "Shared SDK for Rhinestone services",
   "author": {
     "name": "Rhinestone",
@@ -18,6 +18,7 @@
   "exports": {
     ".": "./dist/index.js",
     "./chains": "./dist/chains.js",
+    "./lifecycle": "./dist/lifecycle.js",
     "./opentelemetry": "./dist/opentelemetry/index.js",
     "./serialization": "./dist/serialization.js"
   },
@@ -26,6 +27,9 @@
       "chains": [
         "dist/chains.d.ts"
       ],
+      "lifecycle": [
+        "dist/lifecycle.d.ts"
+      ],
       "opentelemetry": [
         "dist/opentelemetry/index.d.ts"
       ],