@rhinestone/service-sdk 0.2.16 → 0.2.18

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 |
 
@@ -46,26 +47,28 @@ orchestrator **bills** `maxFeePerGas`, but on-chain a transaction only ever pays
 
 **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
+- **Windowed `eth_feeHistory`** (mainnet, sepolia, plasma, bsc) — 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
+  for a volatile base fee (the L1s), a broken tip oracle (plasma, whose
+  `eth_maxPriorityFeePerGas` reports ~3.5x what fills actually clear at), or a floor-pinned
+  one (bsc, whose oracle reports the 0.05 gwei chain-min even when blocks are 98% full and
+  clearing at 0.1).
+- **viem's estimate with a tip floor** (base, 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.
+(optimism, soneium, sonic, avalanche). Cap and floor can both be set for one chain, in
+which case the cap applies first and the floor last, so a floor is never undercut. No cap
+applies on the windowed path: a chain moves there precisely so its bid can follow the market.
 
 `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).
+(1.30x sepolia, 1.60x mainnet, 2.00x plasma, 1.00x bsc whose base fee is 0).
 
 **`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
@@ -105,6 +108,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.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;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"}
+{"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;AAqZD;;;;;;;;;;;;;;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

@@ -12,7 +12,12 @@ const viemDefaults_1 = require("./viemDefaults");
 //    made the latest-block-only read jumpy;
 //  - broken-tip-oracle chains (Plasma): eth_maxPriorityFeePerGas over-prices
 //    the tip by orders of magnitude vs the chain's real rewards, and this path
-//    never consults the oracle — see FEE_CONFIG_OVERRIDES for the specifics.
+//    never consults the oracle — see FEE_CONFIG_OVERRIDES for the specifics;
+//  - floor-pinned-oracle chains (BSC): the oracle reports the validators'
+//    configured minimum no matter how full blocks are, because geth's GPO
+//    samples the cheapest tx per block and a few min-price txs squeeze into
+//    every block. A static floor+cap around that number can never follow a
+//    congested market; only the rewards of included txs can (RHI-6956).
 // Other chains stay on viem's default (some with a tip-floor overlay, see
 // TIP_FLOOR_WEI): their base fee is stable or sequencer-pinned, so windowing
 // adds nothing.
@@ -20,6 +25,7 @@ const HISTORICAL_FEE_CHAINS = new Set([
     chains_1.sepolia.id,
     chains_1.mainnet.id,
     chains_1.plasma.id,
+    chains_1.bsc.id,
 ]);
 const DEFAULT_FEE_CONFIG = {
     historyBlocks: 20, // Geth FullNodeGPO window
@@ -140,6 +146,43 @@ const FEE_CONFIG_OVERRIDES = {
         // every lag from 1 to 50 blocks. The floor only sets what we CHARGE.
         tipFloorWei: 1400000n,
     },
+    // BSC is on the historical path because its oracle is pinned to the chain-min,
+    // not because its base is volatile (base fee is 0, so the tip IS the bid).
+    //
+    // Incident 2026-09-10 (RHI-6956): blocks ran 97-98% full for ~2h with
+    // feeHistory rewards at 0.1 gwei from p10 up, while eth_gasPrice and
+    // eth_maxPriorityFeePerGas kept reporting the 0.05 chain-min. The previous
+    // viem-path config (static floor 0.05, static cap 0.055 — "realized 0.0542,
+    // market p50 0.052", measured 2026-07) could not bid above 0.055 whatever the
+    // market did, so every fill sat unmined for 5-8 minutes per nonce and landed
+    // 20+ minutes late, reverted. The tip cap does not apply on this path, which
+    // is the point: the bid follows the included-tx rewards.
+    //
+    // Percentiles simulated against live feeHistory at 8 points over the prior
+    // week (20-block windows, nearest-rank p50 across the window):
+    //
+    //   window                 ratio  p10/p25   p25/p50   p50/p75
+    //   crunch (2026-09-10)    0.97   0.100     0.100     0.100
+    //   onset  (~2h earlier)   0.97   0.053     0.073     0.100
+    //   busy   (3 days prior)  0.56   0.050     0.057     0.117
+    //   calm   (2 samples)     0.21   0.050     0.050     0.050-0.051
+    //
+    // p25/p50 (mainnet's config) reacts at onset and never exceeds the market
+    // median; p50/p75 doubles the price on merely-busy days. BSC crosses the 0.5
+    // congestion ratio routinely, so the congested column is the common case.
+    [chains_1.bsc.id]: {
+        // Base fee is 0 on BSC, so this is inert; 100 states that rather than
+        // inheriting a headroom figure that means nothing here.
+        baseFeeMultiplierPct: 100n,
+        tipPercentile: 25,
+        congestedTipPercentile: 50,
+        // 0.05 gwei — the post-Maxwell chain-min. Carried over from the old static
+        // floor (probed 2026-07-13): it guards an upstream that reports 0 rewards,
+        // which on a zero-base chain would zero the ENTIRE bid. The shared 0.1 gwei
+        // default would double every calm-market BSC quote, where all included txs
+        // pay exactly the min and every percentile reads 0.05.
+        tipFloorWei: 50000000n,
+    },
 };
 // Chains where viem's default base-fee estimate is fine but its tip oracle
 // (eth_maxPriorityFeePerGas) under-prices the priority fee versus the real
@@ -149,7 +192,6 @@ const FEE_CONFIG_OVERRIDES = {
 // RHI-4468 audit and subsequent fill-tracker probes; each entry dated).
 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
     // 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
@@ -200,8 +242,8 @@ const WINDOWED_TIP_CHAINS = new Set([chains_1.polygon.id, chains_1.base.id]);
 // 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:
+// often enough for our own realized tip to mean something (Optimism, Soneium)
+// 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
@@ -217,7 +259,9 @@ const TIP_CAP_WEI = {
     [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
+    // BSC's 0.055 cap was removed 2026-09-10 (RHI-6956): it doubled as the ceiling
+    // of what the relayer could bid, and held fills at 0.055 while the market
+    // cleared at 0.1. BSC now prices from feeHistory rewards (HISTORICAL_FEE_CHAINS).
 };
 const WINDOWED_TIP_HISTORY_BLOCKS = 20;
 // Stays at p50 for both windowed chains. Polygon looked like a candidate for a
@@ -545,14 +589,16 @@ function recordDegradedEstimate(chainId, reason) {
     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.
+ * Cap for the windowed estimator when eth_feeHistory could not supply a base
+ * fee (answered without one, or failed outright). 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.
+ * Takes viem's `fees` rather than the client so a caller that already read them
+ * (the outage path, which also needs the oracle tip) does not read them twice.
+ * Deliberately does NOT adopt viem's tip — see the call sites.
  */
-async function viemFallbackCap(client, config, priorityFee) {
-    const fees = await client.estimateFeesPerGas();
+function viemFallbackCap(fees, client, config, priorityFee) {
     const oracleTip = fees.maxPriorityFeePerGas;
     const viemCap = fees.maxFeePerGas + (priorityFee - oracleTip);
     let cap = viemCap;
@@ -575,12 +621,32 @@ async function estimateFeeHistoryGasFees(client, chainId, config, tipPercentileO
     // #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: overridden
-            ? [tipPercentileOverride]
-            : [config.tipPercentile, config.congestedTipPercentile],
-    });
+    let feeHistory;
+    try {
+        feeHistory = await client.getFeeHistory({
+            blockCount: config.historyBlocks,
+            rewardPercentiles: overridden
+                ? [tipPercentileOverride]
+                : [config.tipPercentile, config.congestedTipPercentile],
+        });
+    }
+    catch {
+        // eth_feeHistory failed outright. A feeHistory outage must never become a
+        // quote outage (CLAUDE.md), and until RHI-6956 this path had no fallback —
+        // the viem paths always did. There is no window to price from, so the only
+        // tip source left is viem's oracle, floored: on BSC that is exactly the
+        // pre-RHI-6956 pricing (chain-min), on Plasma it is the ~3.5x over-priced
+        // oracle this path exists to avoid — degraded, and recorded as such, but a
+        // quote. The base is recovered from viem's cap as in the missing-base case.
+        recordDegradedEstimate(chainId, 'feehistory_error');
+        const fees = await client.estimateFeesPerGas();
+        const priorityFee = (0, tipClamp_1.clampTip)(fees.maxPriorityFeePerGas, config.tipFloorWei, undefined);
+        return {
+            maxFeePerGas: viemFallbackCap(fees, client, config, priorityFee),
+            maxPriorityFeePerGas: priorityFee,
+            baseFeePerGas: null,
+        };
+    }
     const ratios = feeHistory.gasUsedRatio ?? [];
     const meanRatio = ratios.length > 0
         ? ratios.reduce((sum, r) => sum + r, 0) / ratios.length
@@ -613,8 +679,9 @@ async function estimateFeeHistoryGasFees(client, chainId, config, tipPercentileO
         // carrying the most fills through our pricing. The tip we already computed
         // is the calibrated one.
         recordDegradedEstimate(chainId, 'feehistory_missing_base');
+        const fees = await client.estimateFeesPerGas();
         return {
-            maxFeePerGas: await viemFallbackCap(client, config, priorityFee),
+            maxFeePerGas: viemFallbackCap(fees, client, config, priorityFee),
             maxPriorityFeePerGas: priorityFee,
             baseFeePerGas: null,
         };

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.16",
+  "version": "0.2.18",
   "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"
       ],