@varla/sdk 2.14.0 → 2.15.1

package/src/leverage/math.ts

@@ -41,6 +41,21 @@ function mulDivUp(a: bigint, b: bigint, c: bigint): bigint {
   return (a * b + c - 1n) / c;
 }
 
+/** BPS base (100%). */
+const BPS_BASE = 10_000n;
+
+/**
+ * Adjust a price for slippage.
+ * - Buying: pay more per token → effective price goes UP.
+ * - Selling: receive less per token → effective price goes DOWN.
+ */
+function applySlippageToBuyPrice(price: bigint, slippageBps: bigint): bigint {
+  return slippageBps > 0n ? mulDivUp(price, BPS_BASE + slippageBps, BPS_BASE) : price;
+}
+function applySlippageToSellPrice(price: bigint, slippageBps: bigint): bigint {
+  return slippageBps > 0n ? mulDiv(price, BPS_BASE - slippageBps, BPS_BASE) : price;
+}
+
 // ---------------------------------------------------------------------------
 // Public helpers
 // ---------------------------------------------------------------------------
@@ -126,6 +141,12 @@ export type PlanLeverageLoopParams = {
   startingDebt?: bigint;
   /** Optional absolute cap on total debt (collateral base units). */
   maxTotalDebt?: bigint;
+  /**
+   * Assumed slippage/spread for CLOB buys (bps, e.g. 50 = 0.50%).
+   * Buys use an effectively higher price: `price * (10_000 + slippageBps) / 10_000`.
+   * Default: 0 (ideal execution).
+   */
+  slippageBps?: bigint;
 };
 
 /**
@@ -151,6 +172,7 @@ export function planLeverageLoop(params: PlanLeverageLoopParams): LeveragePlan {
     startingTokens = 0n,
     startingDebt = 0n,
     maxTotalDebt,
+    slippageBps = 0n,
   } = params;
 
   if (initialCapital <= 0n) throw new Error("initialCapital must be > 0");
@@ -159,8 +181,11 @@ export function planLeverageLoop(params: PlanLeverageLoopParams): LeveragePlan {
   if (maxIterations < 1) throw new Error("maxIterations must be >= 1");
   if (startingTokens < 0n) throw new Error("startingTokens must be >= 0");
   if (startingDebt < 0n) throw new Error("startingDebt must be >= 0");
+  if (slippageBps < 0n) throw new Error("slippageBps must be >= 0");
+  if (slippageBps >= BPS_BASE) throw new Error("slippageBps must be < 10_000");
 
   const maxLev = maxLeverage(ltvWad);
+  const effectiveBuyPrice = applySlippageToBuyPrice(tokenPriceE8, slippageBps);
 
   // Target leverage semantics:
   // - undefined => run to max (bounded by maxIterations / minStepBorrow / caps)
@@ -198,7 +223,8 @@ export function planLeverageLoop(params: PlanLeverageLoopParams): LeveragePlan {
     // buy
     const spendCollateral = collateralAvailable;
 
-    const tokensBought = tokensForCollateral(spendCollateral, tokenPriceE8);
+    // Use effective (slippage-adjusted) price for buy, but ideal price for expectedTokens display.
+    const tokensBought = tokensForCollateral(spendCollateral, effectiveBuyPrice);
     if (tokensBought <= 0n) break;
 
     // Spend the available collateral for this iteration.
@@ -262,6 +288,24 @@ export function planLeverageLoop(params: PlanLeverageLoopParams): LeveragePlan {
     estimatedLiquidationPriceE8,
     iterations,
     maxLeverageWad: maxLev,
+    assumedSlippageBps: slippageBps,
+    totalSlippageCost:
+      slippageBps > 0n
+        ? clampPositive(
+            // Ideal tokens - actual tokens, valued at mid price.
+            collateralForTokens(
+              steps
+                .filter((s): s is Extract<LeverageStep, { kind: "buy" }> => s.kind === "buy")
+                .reduce(
+                  (acc, s) => acc + tokensForCollateral(s.collateralAmount, tokenPriceE8),
+                  0n,
+                ) -
+                totalTokens +
+                startingTokens,
+              tokenPriceE8,
+            ),
+          )
+        : 0n,
   };
 
   return {
@@ -300,6 +344,12 @@ export type PlanDeleverageParams = {
   maxIterations?: number;
   /** Minimum sell size (in collateral base units) to continue looping. */
   minStepSell?: bigint;
+  /**
+   * Assumed slippage/spread for CLOB sells (bps, e.g. 50 = 0.50%).
+   * Sells use an effectively lower price: `price * (10_000 - slippageBps) / 10_000`.
+   * Default: 0 (ideal execution).
+   */
+  slippageBps?: bigint;
 };
 
 /**
@@ -316,12 +366,17 @@ export function planDeleverage(params: PlanDeleverageParams): DeleveragePlan {
     targetDebtReduction,
     maxIterations = DEFAULT_MAX_ITERATIONS,
     minStepSell = DEFAULT_MIN_STEP_COLLATERAL,
+    slippageBps = 0n,
   } = params;
 
   if (tokenPriceE8 <= 0n) throw new Error("tokenPriceE8 must be > 0");
   if (ltvWad <= 0n || ltvWad >= WAD) throw new Error("ltvWad must be in (0, 1e18)");
   if (depositedTokens < 0n) throw new Error("depositedTokens must be >= 0");
   if (currentDebt < 0n) throw new Error("currentDebt must be >= 0");
+  if (slippageBps < 0n) throw new Error("slippageBps must be >= 0");
+  if (slippageBps >= BPS_BASE) throw new Error("slippageBps must be < 10_000");
+
+  const effectiveSellPrice = applySlippageToSellPrice(tokenPriceE8, slippageBps);
 
   const targetRepay = targetDebtReduction === "full" ? currentDebt : targetDebtReduction;
   if (targetRepay <= 0n) {
@@ -333,6 +388,8 @@ export function planDeleverage(params: PlanDeleverageParams): DeleveragePlan {
         tokensRemaining: depositedTokens,
         collateralRemaining: 0n,
         iterations: 0,
+        assumedSlippageBps: slippageBps,
+        totalSlippageCost: 0n,
       },
     };
   }
@@ -342,6 +399,7 @@ export function planDeleverage(params: PlanDeleverageParams): DeleveragePlan {
   let remainingDebt = currentDebt;
   let totalSold = 0n;
   let totalRepaid = 0n;
+  let excessCollateral = 0n; // sell proceeds not used for repayment (returned to user)
 
   for (let i = 0; i < maxIterations; i++) {
     if (remainingDebt <= 0n) break;
@@ -364,7 +422,7 @@ export function planDeleverage(params: PlanDeleverageParams): DeleveragePlan {
       withdrawable < tokensNeededForTarget ? withdrawable : tokensNeededForTarget;
     if (tokensToWithdraw <= 0n) break;
 
-    const collateralProceeds = collateralForTokens(tokensToWithdraw, tokenPriceE8);
+    const collateralProceeds = collateralForTokens(tokensToWithdraw, effectiveSellPrice);
     if (collateralProceeds < minStepSell) break;
 
     // withdraw
@@ -385,11 +443,32 @@ export function planDeleverage(params: PlanDeleverageParams): DeleveragePlan {
     steps.push({ kind: "repay", collateralAmount: repayAmount, iteration: i });
     remainingDebt -= repayAmount;
     totalRepaid += repayAmount;
+    excessCollateral += collateralProceeds - repayAmount;
+  }
+
+  // Phase 2: After all debt is repaid, withdraw and sell remaining tokens.
+  // This ensures "full" close returns all collateral to the user, not just repays debt.
+  // Only fires when debt is fully repaid — if debt remains (underwater/stuck), skip.
+  if (targetDebtReduction === "full" && remainingDebt <= 0n && remainingTokens > 0n) {
+    const collateralProceeds = collateralForTokens(remainingTokens, tokenPriceE8);
+    const iteration = steps.length > 0 ? steps[steps.length - 1]!.iteration + 1 : 0;
+
+    steps.push({ kind: "withdraw", amount: remainingTokens, iteration });
+    steps.push({
+      kind: "sell",
+      tokenAmount: remainingTokens,
+      expectedCollateral: collateralProceeds,
+      iteration,
+    });
+
+    excessCollateral += collateralProceeds;
+    totalSold += remainingTokens;
+    remainingTokens = 0n;
   }
 
-  const collateralRemaining = clampPositive(
-    collateralForTokens(remainingTokens, tokenPriceE8) - remainingDebt,
-  );
+  const collateralRemaining =
+    excessCollateral +
+    clampPositive(collateralForTokens(remainingTokens, tokenPriceE8) - remainingDebt);
   const iterations = steps.length > 0 ? steps[steps.length - 1]!.iteration + 1 : 0;
 
   return {
@@ -400,6 +479,14 @@ export function planDeleverage(params: PlanDeleverageParams): DeleveragePlan {
       tokensRemaining: remainingTokens,
       collateralRemaining,
       iterations,
+      assumedSlippageBps: slippageBps,
+      totalSlippageCost:
+        slippageBps > 0n
+          ? clampPositive(
+              collateralForTokens(totalSold, tokenPriceE8) -
+                collateralForTokens(totalSold, effectiveSellPrice),
+            )
+          : 0n,
     },
   };
 }

package/src/leverage/types.ts

@@ -109,6 +109,10 @@ export type LeverageSummary = {
   iterations: number;
   /** Maximum theoretical leverage = 1 / (1 - LTV) as WAD. */
   maxLeverageWad: bigint;
+  /** Assumed slippage/spread used in planning (bps). 0 if not specified. */
+  assumedSlippageBps: bigint;
+  /** Total collateral lost to slippage across all buy steps (base units). */
+  totalSlippageCost: bigint;
 };
 
 /**
@@ -164,6 +168,10 @@ export type DeleveragePlan = {
     tokensRemaining: bigint;
     collateralRemaining: bigint;
     iterations: number;
+    /** Assumed slippage/spread used in planning (bps). 0 if not specified. */
+    assumedSlippageBps: bigint;
+    /** Total collateral lost to slippage across all sell steps (base units). */
+    totalSlippageCost: bigint;
   };
 };
 
@@ -202,3 +210,34 @@ export type OnLeverageProgress = (info: {
   step: LeverageStep;
   result: LeverageStepResult;
 }) => void;
+
+// ---------------------------------------------------------------------------
+// Slippage error
+// ---------------------------------------------------------------------------
+
+/**
+ * Thrown by executors when actual fill deviates beyond `maxSlippageBps`.
+ */
+export class SlippageExceededError extends Error {
+  readonly expected: bigint;
+  readonly actual: bigint;
+  readonly maxSlippageBps: bigint;
+  readonly side: "buy" | "sell";
+
+  constructor(params: {
+    expected: bigint;
+    actual: bigint;
+    maxSlippageBps: bigint;
+    side: "buy" | "sell";
+  }) {
+    const pct = (Number(params.maxSlippageBps) / 100).toFixed(2);
+    super(
+      `Slippage exceeded on ${params.side}: expected ${params.expected}, got ${params.actual} (max ${pct}%)`,
+    );
+    this.name = "SlippageExceededError";
+    this.expected = params.expected;
+    this.actual = params.actual;
+    this.maxSlippageBps = params.maxSlippageBps;
+    this.side = params.side;
+  }
+}