@toon-protocol/sdk 2.0.1 → 2.2.0

package/dist/index.d.ts

@@ -4,8 +4,8 @@ import { NostrEvent, UnsignedEvent } from 'nostr-tools/pure';
 import { ToonRoutingMeta } from '@toon-protocol/core/toon';
 import { TransportConfig } from '@toon-protocol/connector';
 export { TransportConfig } from '@toon-protocol/connector';
-import { A as AccumulatedClaim } from './swap-DF4ghKio.js';
-export { D as DecryptFulfillClaimParams, E as EncryptFulfillClaimParams, a as EncryptFulfillClaimResult, P as PacketProgress, R as RateMonitorCallback, S as StreamSwapController, b as StreamSwapParams, c as StreamSwapResult, U as UnwrapSwapPacketFromToonParams, d as UnwrapSwapPacketParams, e as UnwrapSwapPacketResult, W as WrapSwapPacketParams, f as WrapSwapPacketResult, g as WrapSwapPacketToToonParams, h as WrapSwapPacketToToonResult, _ as __streamSwapTesting, i as decryptFulfillClaim, j as encryptFulfillClaim, s as streamSwap, k as streamSwapControlled, u as unwrapSwapPacket, l as unwrapSwapPacketFromToon, w as wrapSwapPacket, m as wrapSwapPacketToToon } from './swap-DF4ghKio.js';
+import { R as ReceiptSessionStoreLike, A as AccumulatedClaim } from './swap-PFQTJZA7.js';
+export { a as AdaptiveDeltaController, b as AdaptiveDeltaControllerConfig, B as BoundedReceiptSessions, D as DEFAULT_RECEIPT_SESSIONS_CAP, c as DecryptFulfillClaimParams, E as EncryptFulfillClaimParams, d as EncryptFulfillClaimResult, I as InMemorySwapControllerStateStore, J as JsonFileSwapControllerStateStore, P as PacketObservation, e as PacketProgress, f as PacketResolution, g as RateMonitorCallback, h as ReceiptAddResult, i as ReceiptChainTracker, j as ReceiptSessionState, S as STREAM_RECEIPT_SIGNING_TAG, k as STREAM_RECEIPT_VERSION, l as StreamReceipt, m as StreamReceiptChain, n as StreamReceiptFields, o as StreamSwapAdaptiveController, p as StreamSwapController, q as StreamSwapParams, r as StreamSwapResult, s as SwapControllerError, t as SwapControllerState, u as SwapControllerStateStore, U as UnwrapSwapPacketFromToonParams, v as UnwrapSwapPacketParams, w as UnwrapSwapPacketResult, W as WrapSwapPacketParams, x as WrapSwapPacketResult, y as WrapSwapPacketToToonParams, z as WrapSwapPacketToToonResult, _ as __streamSwapTesting, C as decryptFulfillClaim, F as encodeReceiptSigningPayload, G as encryptFulfillClaim, H as isSwapControllerState, K as isValidStreamNonce, L as issueSessionReceipt, M as parseStreamReceipt, N as serializeReceiptChain, O as signStreamReceipt, Q as streamSwap, T as streamSwapControlled, V as swapControllerStateKey, X as unwrapSwapPacket, Y as unwrapSwapPacketFromToon, Z as verifyStreamReceipt, $ as wrapSwapPacket, a0 as wrapSwapPacketToToon } from './swap-PFQTJZA7.js';
 
 /**
  * Unified identity module for @toon-protocol/sdk.
@@ -1462,6 +1462,21 @@ interface ApplyRateParams {
     /** Decimal-string rate (target whole-units per source whole-unit). */
     rate: string;
 }
+/**
+ * A fresh quote returned by a {@link CreateSwapHandlerConfig.rateProvider}
+ * hook (issue #82, rolling-swap quote tape).
+ *
+ * `rateTimestamp` is the unix-ms time at which the maker's rate SOURCE
+ * produced this quote (its feed tick), not the time the handler resolved it.
+ * Both fields are echoed verbatim into the FULFILL accept-metadata so the
+ * sender can read the quote tape `(R_1, t_1), (R_2, t_2), …` off the fills.
+ */
+interface RateQuote {
+    /** Decimal-string rate matching `SwapPair.rate` format: /^(0|[1-9]\d*)(\.\d+)?$/. */
+    rate: string;
+    /** Unix ms timestamp when the rate source produced this quote. Positive integer. */
+    rateTimestamp: number;
+}
 /** Minimal pino-compatible logger interface. */
 interface SwapHandlerLogger {
     debug: (...args: unknown[]) => void;
@@ -1490,10 +1505,18 @@ interface CreateSwapHandlerConfig {
     claimIssuer: ClaimIssuer;
     /**
      * Optional live-rate override hook. When provided, the handler calls this per
-     * packet instead of reading `pair.rate`. MUST return a decimal string matching
-     * `SwapPair.rate` format: /^(0|[1-9]\d*)(\.\d+)?$/.
+     * packet instead of reading `pair.rate`. This is the rolling-swap fresh-quote
+     * seam (issue #82): the resolved rate `R_i` and its quote timestamp are
+     * emitted on every FULFILL's accept-metadata as the quote tape.
+     *
+     * MAY return either:
+     * - a decimal string matching `SwapPair.rate` format
+     *   /^(0|[1-9]\d*)(\.\d+)?$/ (legacy shape; the handler stamps
+     *   `rateTimestamp` with its own resolution time), or
+     * - a {@link RateQuote} `{ rate, rateTimestamp }` so the rate source's own
+     *   tick time travels on the tape.
      */
-    rateProvider?: (pair: SwapPair) => string | Promise<string>;
+    rateProvider?: (pair: SwapPair) => string | RateQuote | Promise<string | RateQuote>;
     /**
      * Optional replay-protection set. When provided, the handler uses it
      * VERBATIM (operator-owned — bounding/persistence is the operator's
@@ -1504,6 +1527,27 @@ interface CreateSwapHandlerConfig {
      * satisfies the contract.
      */
     seenPacketIds?: SeenPacketIdsLike;
+    /**
+     * Optional dedicated receipt signing key (issue #84, rfc-0039 stream
+     * receipts; rolling-swap spec §7.2). 32-byte secp256k1 secret key used to
+     * BIP-340-sign the per-fulfill {@link StreamReceipt}. When OMITTED,
+     * receipts are signed with `recipientSecretKey` — the maker's Nostr
+     * identity key — so senders verify against the `swapPubkey` they already
+     * discovered via kind:10032. Provide a separate key when the receipt
+     * signer should be provisioned independently of the identity key (e.g.
+     * the swap#47 coupled engine binding receipts to the chain-B claim
+     * signer); senders then verify via `StreamSwapParams.receiptPubkey`.
+     */
+    receiptSecretKey?: Uint8Array;
+    /**
+     * Optional receipt session store (issue #84). Tracks per-`streamNonce`
+     * `{seq, cumulativeDelivered}` so receipt totals are monotone within a
+     * session. Defaults to a {@link BoundedReceiptSessions} in-memory LRU.
+     * Operators that persist claims should back this with the same storage so
+     * receipt state survives restarts alongside the claim stream (a lost
+     * session restarts at seq 1, which senders reject as a forked chain).
+     */
+    receiptSessions?: ReceiptSessionStoreLike;
     /** Optional pino-compatible logger. Defaults to a no-op logger. */
     logger?: SwapHandlerLogger;
 }
@@ -1957,4 +2001,4 @@ interface StoreHealthResponse {
     jobsRecent: StoreJobsRecent;
 }
 
-export { AccumulatedClaim, type AddChunkResult, type ApplyRateParams, type ArweaveDvmConfig, type ArweaveUploadAdapter, type BuildSettlementTxParams, type BuildSettlementTxResult, type BuildSkillDescriptorConfig, ChunkManager, type ChunkManagerConfig, type ClaimIssuer, type CreateHandlerContextOptions, type CreateSwapHandlerConfig, type FromMnemonicOptions, GiftWrapError, type Handler, type HandlerContext, HandlerError, HandlerRegistry, type HandlerResponse, IdentityError, type IssueClaimParams, type IssueClaimResult, type MinaIdentity, type MinaSignerClientLike, type NodeConfig, NodeError, type NodeIdentity, type PaymentHandlerBridgeConfig, type PaymentRequest, type PaymentResponse, type PrefixClaimHandlerOptions, PricingError, type PricingValidationResult, type PricingValidatorConfig, type PublishEventResult, type PublishableNode, SWAP_HANDLER_REJECT_CODES, SWAP_HANDLER_REJECT_MESSAGES, type ServiceNode, type SettlementBundle, SettlementTxError, type SolanaIdentity, type StartResult, type StoreHealthResponse, type StoreJobsByKindEntry, type StoreJobsByStatus, type StoreJobsRecent, StreamSwapError, SwapHandlerError, type SwapHandlerLogger, type SwapSignerConfig, SwarmCoordinator, type SwarmCoordinatorOptions, type SwarmState, type ToonIdentity, TurboUploadAdapter, type UploadBlobChunkedOptions, type UploadBlobOptions, VerificationError, type VerificationPipelineConfig, type VerificationResult, type WorkflowEventStore, WorkflowOrchestrator, type WorkflowOrchestratorOptions, type WorkflowState, applyRate, base58Decode, base58Encode, buildSettlementTx, buildSkillDescriptor, createArweaveDvmHandler, createEventStorageHandler, createHandlerContext, createNode, createPaymentHandlerBridge, createPrefixClaimHandler, createPricingValidator, createSwapHandler, createVerificationPipeline, fillEvmSettlementTxGas, findSwapPair, fromMnemonic, fromMnemonicFull, fromSecretKey, generateMnemonic, generateSolanaKeypair, loadMinaSignerClient, uploadBlob, uploadBlobChunked, verifyAccumulatedClaim, verifyEd25519Signature, verifyMinaSignature };
+export { AccumulatedClaim, type AddChunkResult, type ApplyRateParams, type ArweaveDvmConfig, type ArweaveUploadAdapter, type BuildSettlementTxParams, type BuildSettlementTxResult, type BuildSkillDescriptorConfig, ChunkManager, type ChunkManagerConfig, type ClaimIssuer, type CreateHandlerContextOptions, type CreateSwapHandlerConfig, type FromMnemonicOptions, GiftWrapError, type Handler, type HandlerContext, HandlerError, HandlerRegistry, type HandlerResponse, IdentityError, type IssueClaimParams, type IssueClaimResult, type MinaIdentity, type MinaSignerClientLike, type NodeConfig, NodeError, type NodeIdentity, type PaymentHandlerBridgeConfig, type PaymentRequest, type PaymentResponse, type PrefixClaimHandlerOptions, PricingError, type PricingValidationResult, type PricingValidatorConfig, type PublishEventResult, type PublishableNode, type RateQuote, ReceiptSessionStoreLike, SWAP_HANDLER_REJECT_CODES, SWAP_HANDLER_REJECT_MESSAGES, type ServiceNode, type SettlementBundle, SettlementTxError, type SolanaIdentity, type StartResult, type StoreHealthResponse, type StoreJobsByKindEntry, type StoreJobsByStatus, type StoreJobsRecent, StreamSwapError, SwapHandlerError, type SwapHandlerLogger, type SwapSignerConfig, SwarmCoordinator, type SwarmCoordinatorOptions, type SwarmState, type ToonIdentity, TurboUploadAdapter, type UploadBlobChunkedOptions, type UploadBlobOptions, VerificationError, type VerificationPipelineConfig, type VerificationResult, type WorkflowEventStore, WorkflowOrchestrator, type WorkflowOrchestratorOptions, type WorkflowState, applyRate, base58Decode, base58Encode, buildSettlementTx, buildSkillDescriptor, createArweaveDvmHandler, createEventStorageHandler, createHandlerContext, createNode, createPaymentHandlerBridge, createPrefixClaimHandler, createPricingValidator, createSwapHandler, createVerificationPipeline, fillEvmSettlementTxGas, findSwapPair, fromMnemonic, fromMnemonicFull, fromSecretKey, generateMnemonic, generateSolanaKeypair, loadMinaSignerClient, uploadBlob, uploadBlobChunked, verifyAccumulatedClaim, verifyEd25519Signature, verifyMinaSignature };

package/dist/index.js

@@ -1,9 +1,14 @@
 import {
+  BoundedReceiptSessions,
+  DEFAULT_RECEIPT_SESSIONS_CAP,
   GiftWrapError,
   HandlerError,
   IdentityError,
   NodeError,
   PricingError,
+  ReceiptChainTracker,
+  STREAM_RECEIPT_SIGNING_TAG,
+  STREAM_RECEIPT_VERSION,
   SWAP_HANDLER_REJECT_CODES,
   SWAP_HANDLER_REJECT_MESSAGES,
   SettlementTxError,
@@ -16,6 +21,7 @@ import {
   base58Encode,
   createSwapHandler,
   decryptFulfillClaim,
+  encodeReceiptSigningPayload,
   encryptFulfillClaim,
   findSwapPair,
   fromMnemonic,
@@ -23,13 +29,19 @@ import {
   fromSecretKey,
   generateMnemonic,
   generateSolanaKeypair,
+  isValidStreamNonce,
+  issueSessionReceipt,
+  parseStreamReceipt,
+  serializeReceiptChain,
+  signStreamReceipt,
   streamSwap,
   streamSwapControlled,
   unwrapSwapPacket,
   unwrapSwapPacketFromToon,
+  verifyStreamReceipt,
   wrapSwapPacket,
   wrapSwapPacketToToon
-} from "./chunk-Z6S56VPV.js";
+} from "./chunk-RAZRWSJF.js";
 import "./chunk-UP2VWCW5.js";
 
 // src/handler-context.ts
@@ -1997,6 +2009,360 @@ async function uploadBlobChunked(node, blob, destination, options) {
   return lastResult.eventId;
 }
 
+// src/adaptive-controller.ts
+import { ToonError as ToonError3 } from "@toon-protocol/core";
+var SwapControllerError = class extends ToonError3 {
+  constructor(message, cause) {
+    super(message, "SWAP_CONTROLLER_ERROR", cause);
+    this.name = "SwapControllerError";
+  }
+};
+var DECIMAL_UINT_REGEX = /^(0|[1-9]\d*)$/;
+function isSwapControllerState(value) {
+  if (!value || typeof value !== "object") return false;
+  const s = value;
+  return s["v"] === 1 && typeof s["delta"] === "string" && DECIMAL_UINT_REGEX.test(s["delta"]) && typeof s["W"] === "number" && Number.isInteger(s["W"]) && s["W"] >= 1 && typeof s["vEwma"] === "number" && Number.isFinite(s["vEwma"]) && s["vEwma"] >= 0 && typeof s["tauEwma"] === "number" && Number.isFinite(s["tauEwma"]) && s["tauEwma"] >= 0 && typeof s["cleanStreak"] === "number" && Number.isInteger(s["cleanStreak"]) && s["cleanStreak"] >= 0 && typeof s["everShrunk"] === "boolean" && (s["lastWidened"] === "delta" || s["lastWidened"] === "window") && typeof s["updatedAt"] === "number";
+}
+function swapControllerStateKey(params) {
+  const { makerPubkey, pair } = params;
+  const from = `${pair.from.assetCode}@${pair.from.chain}`;
+  const to = `${pair.to.assetCode}@${pair.to.chain}`;
+  return `${pair.from.chain}:${makerPubkey}:${from}:${to}`;
+}
+var InMemorySwapControllerStateStore = class {
+  states = /* @__PURE__ */ new Map();
+  async load(key) {
+    const hit = this.states.get(key);
+    return hit === void 0 ? void 0 : { ...hit };
+  }
+  async save(key, state) {
+    this.states.set(key, { ...state });
+  }
+};
+var JsonFileSwapControllerStateStore = class {
+  constructor(filePath) {
+    this.filePath = filePath;
+    if (typeof filePath !== "string" || filePath.length === 0) {
+      throw new SwapControllerError(
+        "JsonFileSwapControllerStateStore requires a non-empty filePath"
+      );
+    }
+  }
+  async readAll() {
+    const fs = await import("fs/promises");
+    let raw;
+    try {
+      raw = await fs.readFile(this.filePath, "utf8");
+    } catch (err) {
+      if (err.code === "ENOENT") return {};
+      throw new SwapControllerError(
+        `Failed to read controller state file ${this.filePath}`,
+        err instanceof Error ? err : void 0
+      );
+    }
+    try {
+      const parsed = JSON.parse(raw);
+      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+        return parsed;
+      }
+    } catch {
+    }
+    return {};
+  }
+  async load(key) {
+    const all = await this.readAll();
+    const candidate = all[key];
+    return isSwapControllerState(candidate) ? { ...candidate } : void 0;
+  }
+  async save(key, state) {
+    const fs = await import("fs/promises");
+    const path = await import("path");
+    const all = await this.readAll();
+    all[key] = { ...state };
+    const dir = path.dirname(this.filePath);
+    await fs.mkdir(dir, { recursive: true });
+    const tmp = `${this.filePath}.${process.pid}.${Date.now()}.tmp`;
+    await fs.writeFile(tmp, JSON.stringify(all, null, 2), "utf8");
+    await fs.rename(tmp, this.filePath);
+  }
+};
+var DEFAULT_EPSILON_HALF_SPREAD_FRACTION = 0.5;
+var DEFAULT_MAX_WINDOW = 8;
+var DEFAULT_CLEAN_STREAK_LENGTH = 16;
+var DEFAULT_COLD_START_DIVISOR = 256;
+var DEFAULT_EWMA_ALPHA = 0.2;
+var CAP_SCALE = 1000000000000n;
+var CAP_SCALE_NUM = 1e12;
+function rateToNumber(rate) {
+  const n = Number(rate);
+  return Number.isFinite(n) && n > 0 ? n : NaN;
+}
+var AdaptiveDeltaController = class _AdaptiveDeltaController {
+  /** Persistence key for this tuple (see {@link swapControllerStateKey}). */
+  key;
+  store;
+  pair;
+  epsilon;
+  maxPacketAmount;
+  minPacketAmount;
+  maxWindow;
+  cleanStreakLength;
+  coldStartDivisor;
+  alpha;
+  now;
+  stateInternal;
+  /** δ in-memory as bigint (mirrors `stateInternal.delta`). */
+  delta;
+  /** Cold-start δ_0 — also the additive widen increment. Set on first nextDelta(). */
+  delta0 = null;
+  /** Previous tape entry for the per-second volatility measurement. */
+  lastRate = null;
+  lastRateTimestamp = null;
+  constructor(config, key, store, state) {
+    this.key = key;
+    this.store = store;
+    this.pair = config.pair;
+    const epsilonFraction = config.epsilonHalfSpreadFraction ?? DEFAULT_EPSILON_HALF_SPREAD_FRACTION;
+    this.epsilon = epsilonFraction * (config.advertisedSpread / 2);
+    this.maxPacketAmount = config.maxPacketAmount;
+    this.minPacketAmount = config.minPacketAmount ?? 1n;
+    this.maxWindow = config.maxWindow ?? DEFAULT_MAX_WINDOW;
+    this.cleanStreakLength = config.cleanStreakLength ?? DEFAULT_CLEAN_STREAK_LENGTH;
+    this.coldStartDivisor = BigInt(
+      config.coldStartDivisor ?? DEFAULT_COLD_START_DIVISOR
+    );
+    this.alpha = config.ewmaAlpha ?? DEFAULT_EWMA_ALPHA;
+    this.now = config.now ?? Date.now;
+    this.stateInternal = state;
+    this.delta = BigInt(state.delta);
+  }
+  /**
+   * Create a controller for one swap session: loads the persisted state for
+   * the tuple from the store, or starts cold (`δ` unset until the first
+   * `nextDelta()`, `W = 1`).
+   */
+  static async create(config) {
+    validateConfig(config);
+    const key = swapControllerStateKey({
+      makerPubkey: config.makerPubkey,
+      pair: config.pair
+    });
+    const store = config.store ?? new InMemorySwapControllerStateStore();
+    const now = config.now ?? Date.now;
+    const loaded = await store.load(key);
+    const state = isSwapControllerState(loaded) ? loaded : {
+      v: 1,
+      delta: "0",
+      W: 1,
+      vEwma: 0,
+      tauEwma: 0,
+      cleanStreak: 0,
+      everShrunk: false,
+      // 'window' so the FIRST widen step hits δ (alternation starts on δ).
+      lastWidened: "window",
+      updatedAt: now()
+    };
+    return new _AdaptiveDeltaController(config, key, store, state);
+  }
+  /** Defensive snapshot of the current controller state. */
+  get state() {
+    return { ...this.stateInternal, delta: this.delta.toString() };
+  }
+  /** Current in-flight window W. */
+  get window() {
+    return this.stateInternal.W;
+  }
+  /**
+   * Current `delta_cap = ε/(v·τ)` as a fraction of remaining notional.
+   * `Infinity` while `v·τ` has no measurement yet (cold tape) — the
+   * cold-start `δ_0` and absolute caps bound δ in that regime.
+   */
+  get deltaCapFraction() {
+    const vTau = this.stateInternal.vEwma * this.stateInternal.tauEwma;
+    if (!(vTau > 0)) return Infinity;
+    return this.epsilon / vTau;
+  }
+  /** `delta_cap` in absolute source micro-units for a given remaining notional. */
+  deltaCapAbsolute(remaining) {
+    const frac = this.deltaCapFraction;
+    if (!Number.isFinite(frac) || frac >= 1) return remaining;
+    if (frac <= 0) return this.minPacketAmount;
+    const scaled = BigInt(Math.floor(frac * CAP_SCALE_NUM));
+    return remaining * scaled / CAP_SCALE;
+  }
+  /**
+   * Decide the next packet size (source micro-units) for a session with
+   * `remaining` notional left. Enforces, in order: the measured
+   * `delta_cap = ε/(v·τ)` bound, the absolute `maxPacketAmount` cap, the
+   * remaining notional, and the `minPacketAmount` floor. Seeds the
+   * cold-start `δ_0 = min(delta_cap, notional/256, maxPacketAmount)` on
+   * first call.
+   */
+  nextDelta(remaining) {
+    if (typeof remaining !== "bigint" || remaining <= 0n) return 0n;
+    if (this.delta0 === null) {
+      let d0 = remaining / this.coldStartDivisor;
+      const capAbs2 = this.deltaCapAbsolute(remaining);
+      if (d0 > capAbs2) d0 = capAbs2;
+      if (this.maxPacketAmount !== void 0 && d0 > this.maxPacketAmount) {
+        d0 = this.maxPacketAmount;
+      }
+      if (d0 < this.minPacketAmount) d0 = this.minPacketAmount;
+      this.delta0 = d0;
+      if (this.delta <= 0n) {
+        this.delta = d0;
+        this.stateInternal.delta = d0.toString();
+      }
+    }
+    let d = this.delta;
+    const capAbs = this.deltaCapAbsolute(remaining);
+    if (d > capAbs) d = capAbs;
+    if (this.maxPacketAmount !== void 0 && d > this.maxPacketAmount) {
+      d = this.maxPacketAmount;
+    }
+    if (d > remaining) d = remaining;
+    const floor = this.minPacketAmount < remaining ? this.minPacketAmount : remaining;
+    if (d < floor) d = floor;
+    return d;
+  }
+  /**
+   * Feed one packet observation: updates the measured EWMAs (`v`, `τ`),
+   * applies at most ONE knob adjustment (asymmetric: multiplicative shrink /
+   * additive widen), and persists the state.
+   */
+  async observe(observation) {
+    const s = this.stateInternal;
+    if (typeof observation.rttMs === "number" && Number.isFinite(observation.rttMs) && observation.rttMs > 0) {
+      const tauSec = observation.rttMs / 1e3;
+      s.tauEwma = s.tauEwma === 0 ? tauSec : this.alpha * tauSec + (1 - this.alpha) * s.tauEwma;
+    }
+    if (typeof observation.rate === "string" && typeof observation.rateTimestamp === "number" && Number.isFinite(observation.rateTimestamp)) {
+      const r = rateToNumber(observation.rate);
+      if (!Number.isNaN(r)) {
+        if (this.lastRate !== null && this.lastRateTimestamp !== null && observation.rateTimestamp > this.lastRateTimestamp) {
+          const dtSec = (observation.rateTimestamp - this.lastRateTimestamp) / 1e3;
+          const inst = Math.abs(r - this.lastRate) / this.lastRate / dtSec;
+          if (Number.isFinite(inst)) {
+            s.vEwma = s.vEwma === 0 ? inst : this.alpha * inst + (1 - this.alpha) * s.vEwma;
+          }
+        }
+        if (this.lastRateTimestamp === null || observation.rateTimestamp >= this.lastRateTimestamp) {
+          this.lastRate = r;
+          this.lastRateTimestamp = observation.rateTimestamp;
+        }
+      }
+    }
+    const slip = this.realizedSlip(observation);
+    const isShrink = observation.resolution !== "fulfill" || slip > this.epsilon;
+    if (isShrink) {
+      if (observation.resolution === "timeout") {
+        s.W = Math.max(1, Math.ceil(s.W / 2));
+      } else {
+        let d = this.delta / 2n;
+        if (d < this.minPacketAmount) d = this.minPacketAmount;
+        this.delta = d;
+        s.delta = d.toString();
+      }
+      s.cleanStreak = 0;
+      s.everShrunk = true;
+    } else {
+      s.cleanStreak += 1;
+      if (s.cleanStreak >= this.cleanStreakLength) {
+        s.cleanStreak = 0;
+        const knob = s.lastWidened === "delta" ? "window" : "delta";
+        if (knob === "window") {
+          s.W = Math.min(this.maxWindow, s.W + 1);
+        } else {
+          const increment = this.delta0 ?? this.minPacketAmount;
+          let d = s.everShrunk ? this.delta + increment : this.delta * 2n;
+          if (this.maxPacketAmount !== void 0 && d > this.maxPacketAmount) {
+            d = this.maxPacketAmount;
+          }
+          if (observation.remaining !== void 0 && observation.remaining > 0n) {
+            const capAbs = this.deltaCapAbsolute(observation.remaining);
+            if (d > capAbs) d = capAbs;
+          }
+          if (d < this.minPacketAmount) d = this.minPacketAmount;
+          if (d < this.delta) d = this.delta;
+          this.delta = d;
+          s.delta = d.toString();
+        }
+        s.lastWidened = knob;
+      }
+    }
+    s.updatedAt = this.now();
+    await this.store.save(this.key, { ...s });
+  }
+  /**
+   * Realized per-packet slip as a fraction: shortfall of the delivered
+   * target amount vs the amount implied by the packet's own tape rate `R_i`
+   * (spec §7.1 `Δcumulative` vs `⌊δ · R_i⌋` cross-check). `0` when the
+   * inputs are unavailable or delivery met the tape.
+   */
+  realizedSlip(observation) {
+    if (observation.resolution !== "fulfill" || observation.rate === void 0 || observation.sourceAmount === void 0 || observation.targetAmount === void 0 || observation.sourceAmount <= 0n) {
+      return 0;
+    }
+    let expected;
+    try {
+      expected = applyRate({
+        sourceAmount: observation.sourceAmount,
+        fromScale: this.pair.from.assetScale,
+        toScale: this.pair.to.assetScale,
+        rate: observation.rate
+      });
+    } catch {
+      return 0;
+    }
+    if (expected <= 0n || observation.targetAmount >= expected) return 0;
+    const shortfall = expected - observation.targetAmount;
+    return Number(shortfall * 1000000n / expected) / 1e6;
+  }
+};
+function validateConfig(config) {
+  if (typeof config.makerPubkey !== "string" || config.makerPubkey.length === 0) {
+    throw new SwapControllerError("makerPubkey must be a non-empty string");
+  }
+  if (!config.pair || typeof config.pair !== "object" || !config.pair.from || !config.pair.to || typeof config.pair.from.chain !== "string" || typeof config.pair.to.chain !== "string") {
+    throw new SwapControllerError(
+      "pair must be a SwapPair with from/to chain descriptors"
+    );
+  }
+  if (typeof config.advertisedSpread !== "number" || !Number.isFinite(config.advertisedSpread) || config.advertisedSpread <= 0) {
+    throw new SwapControllerError(
+      `advertisedSpread must be a positive finite fraction, got ${String(
+        config.advertisedSpread
+      )}`
+    );
+  }
+  if (config.epsilonHalfSpreadFraction !== void 0 && (typeof config.epsilonHalfSpreadFraction !== "number" || !Number.isFinite(config.epsilonHalfSpreadFraction) || config.epsilonHalfSpreadFraction <= 0)) {
+    throw new SwapControllerError(
+      "epsilonHalfSpreadFraction must be a positive finite number"
+    );
+  }
+  if (config.maxPacketAmount !== void 0 && (typeof config.maxPacketAmount !== "bigint" || config.maxPacketAmount <= 0n)) {
+    throw new SwapControllerError("maxPacketAmount must be a positive bigint");
+  }
+  if (config.minPacketAmount !== void 0 && (typeof config.minPacketAmount !== "bigint" || config.minPacketAmount <= 0n)) {
+    throw new SwapControllerError("minPacketAmount must be a positive bigint");
+  }
+  if (config.minPacketAmount !== void 0 && config.maxPacketAmount !== void 0 && config.minPacketAmount > config.maxPacketAmount) {
+    throw new SwapControllerError("minPacketAmount must be <= maxPacketAmount");
+  }
+  if (config.maxWindow !== void 0 && (!Number.isInteger(config.maxWindow) || config.maxWindow < 1)) {
+    throw new SwapControllerError("maxWindow must be an integer >= 1");
+  }
+  if (config.cleanStreakLength !== void 0 && (!Number.isInteger(config.cleanStreakLength) || config.cleanStreakLength < 1)) {
+    throw new SwapControllerError("cleanStreakLength must be an integer >= 1");
+  }
+  if (config.coldStartDivisor !== void 0 && (!Number.isInteger(config.coldStartDivisor) || config.coldStartDivisor < 1)) {
+    throw new SwapControllerError("coldStartDivisor must be an integer >= 1");
+  }
+  if (config.ewmaAlpha !== void 0 && (typeof config.ewmaAlpha !== "number" || !(config.ewmaAlpha > 0) || config.ewmaAlpha > 1)) {
+    throw new SwapControllerError("ewmaAlpha must be in (0, 1]");
+  }
+}
+
 // src/settlement/evm.ts
 import { secp256k1 } from "@noble/curves/secp256k1.js";
 import { keccak_256 } from "@noble/hashes/sha3.js";
@@ -3039,17 +3405,26 @@ function verifyAccumulatedClaim(claim, signer, minaSignerClient) {
   };
 }
 export {
+  AdaptiveDeltaController,
+  BoundedReceiptSessions,
   ChunkManager,
+  DEFAULT_RECEIPT_SESSIONS_CAP,
   GiftWrapError,
   HandlerError,
   HandlerRegistry,
   IdentityError,
+  InMemorySwapControllerStateStore,
+  JsonFileSwapControllerStateStore,
   NodeError,
   PricingError,
+  ReceiptChainTracker,
+  STREAM_RECEIPT_SIGNING_TAG,
+  STREAM_RECEIPT_VERSION,
   SWAP_HANDLER_REJECT_CODES,
   SWAP_HANDLER_REJECT_MESSAGES,
   SettlementTxError,
   StreamSwapError,
+  SwapControllerError,
   SwapHandlerError,
   SwarmCoordinator,
   TurboUploadAdapter,
@@ -3076,6 +3451,7 @@ export {
   createSwapHandler,
   createVerificationPipeline,
   decryptFulfillClaim,
+  encodeReceiptSigningPayload,
   encryptFulfillClaim,
   fillEvmSettlementTxGas,
   findSwapPair,
@@ -3085,10 +3461,17 @@ export {
   generateMnemonic,
   generateSolanaKeypair,
   hexToBytes2 as hexToBytes,
+  isSwapControllerState,
+  isValidStreamNonce,
+  issueSessionReceipt,
   loadMinaSignerClient,
   minaHashToField,
+  parseStreamReceipt,
+  serializeReceiptChain,
+  signStreamReceipt,
   streamSwap,
   streamSwapControlled,
+  swapControllerStateKey,
   unwrapSwapPacket,
   unwrapSwapPacketFromToon,
   uploadBlob,
@@ -3096,6 +3479,7 @@ export {
   verifyAccumulatedClaim,
   verifyEd25519Signature,
   verifyMinaSignature,
+  verifyStreamReceipt,
   wrapSwapPacket,
   wrapSwapPacketToToon
 };