@varla/sdk 2.15.0 → 2.16.0

package/src/leverage/index.ts

@@ -65,6 +65,9 @@ export {
   prepareApprovePositionsTokenIfNeeded,
   readErc1155IsApprovedForAll,
 } from "./preflight.js";
+export type { ReceiptRetryOptions } from "./receipt.js";
+// Receipt retry
+export { DEFAULT_RECEIPT_RETRY, waitForReceiptWithRetry } from "./receipt.js";
 // Types + constants
 export type {
   BuyResult,
@@ -84,5 +87,6 @@ export {
   DEFAULT_MIN_STEP_COLLATERAL,
   PRICE_E8,
   pow10,
+  SlippageExceededError,
   WAD,
 } from "./types.js";

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/receipt.ts

@@ -0,0 +1,143 @@
+// Note: explicit .js extension is required for Node ESM resolution.
+
+/**
+ * Robust transaction receipt waiting with exponential backoff.
+ *
+ * Polygon (and other L2s) occasionally drop RPC connections or return
+ * "receipt not found" transiently — even for successfully broadcast txs.
+ * This helper retries `waitForTransactionReceipt` so a single flaky RPC
+ * call doesn't abort a multi-step leverage/deleverage loop.
+ */
+
+import type { Hash, PublicClient, TransactionReceipt } from "viem";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type ReceiptRetryOptions = {
+  /** Maximum number of retry attempts (default: 5). */
+  maxRetries?: number;
+  /** Base delay in ms for first retry (default: 2_000). */
+  baseDelayMs?: number;
+  /** Maximum delay cap in ms (default: 32_000). */
+  maxDelayMs?: number;
+  /** Multiplier applied each retry (default: 2). */
+  backoffMultiplier?: number;
+};
+
+export const DEFAULT_RECEIPT_RETRY: Required<ReceiptRetryOptions> = {
+  maxRetries: 5,
+  baseDelayMs: 2_000,
+  maxDelayMs: 32_000,
+  backoffMultiplier: 2,
+};
+
+// ---------------------------------------------------------------------------
+// Helper
+// ---------------------------------------------------------------------------
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Classify whether an error from `waitForTransactionReceipt` is transient
+ * (worth retrying) vs permanent (should be thrown immediately).
+ */
+function isTransientReceiptError(error: unknown): boolean {
+  if (!(error instanceof Error)) return true; // unknown shape → retry
+  const msg = error.message.toLowerCase();
+
+  // Permanent: tx reverted on-chain → retrying won't help.
+  if (msg.includes("reverted") || msg.includes("execution reverted")) return false;
+
+  // Transient: receipt not found, timeout, network issues.
+  if (
+    msg.includes("not found") ||
+    msg.includes("could not be found") ||
+    msg.includes("timeout") ||
+    msg.includes("timed out") ||
+    msg.includes("econnrefused") ||
+    msg.includes("econnreset") ||
+    msg.includes("network") ||
+    msg.includes("fetch") ||
+    msg.includes("502") ||
+    msg.includes("503") ||
+    msg.includes("504") ||
+    msg.includes("rate limit")
+  ) {
+    return true;
+  }
+
+  // Default: retry (better to retry once too many than abort a valid tx).
+  return true;
+}
+
+// ---------------------------------------------------------------------------
+// Main export
+// ---------------------------------------------------------------------------
+
+/**
+ * Wait for a transaction receipt with automatic retry and exponential backoff.
+ *
+ * This wraps `publicClient.waitForTransactionReceipt` and handles the common
+ * failure modes seen on Polygon:
+ * - "Transaction receipt not found" (RPC hasn't indexed the block yet)
+ * - Timeouts and connection drops
+ * - 502/503/504 gateway errors
+ *
+ * @throws The original error after all retries are exhausted.
+ */
+export async function waitForReceiptWithRetry(params: {
+  publicClient: Pick<PublicClient, "waitForTransactionReceipt">;
+  hash: Hash;
+  confirmations?: number;
+  retry?: ReceiptRetryOptions;
+}): Promise<TransactionReceipt> {
+  const { publicClient, hash, confirmations = 1 } = params;
+  const opts = { ...DEFAULT_RECEIPT_RETRY, ...params.retry };
+
+  let lastError: unknown;
+
+  for (let attempt = 0; attempt <= opts.maxRetries; attempt++) {
+    try {
+      const receipt = await (publicClient as any).waitForTransactionReceipt({
+        hash,
+        confirmations,
+      });
+      return receipt as TransactionReceipt;
+    } catch (error) {
+      lastError = error;
+
+      // Don't retry permanent errors (e.g. on-chain revert).
+      if (!isTransientReceiptError(error)) {
+        throw error;
+      }
+
+      // Don't retry if we've exhausted attempts.
+      if (attempt >= opts.maxRetries) {
+        break;
+      }
+
+      // Exponential backoff with cap.
+      const delay = Math.min(opts.baseDelayMs * opts.backoffMultiplier ** attempt, opts.maxDelayMs);
+
+      // No-op in production; useful for debugging.
+      // console.debug(`[receipt-retry] attempt ${attempt + 1}/${opts.maxRetries} for ${hash}, waiting ${delay}ms`);
+
+      await sleep(delay);
+    }
+  }
+
+  // Wrap with a descriptive message so the caller knows retries were exhausted.
+  const cause = lastError instanceof Error ? lastError : new Error(String(lastError));
+  const wrapped = new Error(
+    `Transaction receipt not found for ${hash} after ${opts.maxRetries + 1} attempts (${opts.maxRetries} retries). ` +
+      `The transaction was broadcast successfully — it may still confirm. ` +
+      `Original error: ${cause.message}`,
+  );
+  (wrapped as any).cause = cause;
+  (wrapped as any).hash = hash;
+  throw wrapped;
+}

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;
+  }
+}