@toon-protocol/sdk 2.0.0 → 2.1.0

package/dist/index.js

@@ -29,7 +29,7 @@ import {
   unwrapSwapPacketFromToon,
   wrapSwapPacket,
   wrapSwapPacketToToon
-} from "./chunk-Z6S56VPV.js";
+} from "./chunk-7LBYFU4L.js";
 import "./chunk-UP2VWCW5.js";
 
 // src/handler-context.ts
@@ -1997,6 +1997,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 +3393,21 @@ function verifyAccumulatedClaim(claim, signer, minaSignerClient) {
   };
 }
 export {
+  AdaptiveDeltaController,
   ChunkManager,
   GiftWrapError,
   HandlerError,
   HandlerRegistry,
   IdentityError,
+  InMemorySwapControllerStateStore,
+  JsonFileSwapControllerStateStore,
   NodeError,
   PricingError,
   SWAP_HANDLER_REJECT_CODES,
   SWAP_HANDLER_REJECT_MESSAGES,
   SettlementTxError,
   StreamSwapError,
+  SwapControllerError,
   SwapHandlerError,
   SwarmCoordinator,
   TurboUploadAdapter,
@@ -3085,10 +3443,12 @@ export {
   generateMnemonic,
   generateSolanaKeypair,
   hexToBytes2 as hexToBytes,
+  isSwapControllerState,
   loadMinaSignerClient,
   minaHashToField,
   streamSwap,
   streamSwapControlled,
+  swapControllerStateKey,
   unwrapSwapPacket,
   unwrapSwapPacketFromToon,
   uploadBlob,