@varla/sdk 1.11.4 → 1.14.0

package/src/leverage/index.ts

@@ -0,0 +1,88 @@
+// Note: explicit .js extension is required for Node ESM resolution.
+
+/**
+ * @varla/sdk/leverage — Leverage loop planning, execution, and math helpers.
+ *
+ * This module abstracts the "recursive borrowing" pattern for leveraged
+ * long/short positions on prediction markets:
+ *
+ * ```
+ * buy tokens → deposit into VarlaCore → borrow collateral → buy more tokens → ...
+ * ```
+ *
+ * Architecture:
+ * - **math.ts**: Pure math (zero deps, zero I/O). Plan loops, compute P&L scenarios.
+ * - **plan.ts**: RPC-aware planners that read on-chain state then delegate to math.
+ * - **execute.ts**: Step executor that drives deposit/borrow txs with a callback for CLOB buys.
+ * - **types.ts**: Shared types and constants.
+ *
+ * The SDK handles all on-chain operations (deposit, borrow, approve).
+ * Off-chain CLOB trades are delegated to a consumer-provided callback.
+ */
+
+export type {
+  OnDeleverageProgress,
+  RunDeleverageLoopParams,
+  RunDeleverageLoopResult,
+} from "./deleverageExecute.js";
+export { runDeleverageLoop } from "./deleverageExecute.js";
+export type {
+  RunLeverageLoopParams,
+  RunLeverageLoopResult,
+} from "./execute.js";
+// Execution
+export { runLeverageLoop } from "./execute.js";
+export type {
+  LeverageScenario,
+  PlanDeleverageParams,
+  PlanLeverageLoopParams,
+} from "./math.js";
+// Pure math
+export {
+  collateralForTokens,
+  estimateLiquidationPrice,
+  leverageScenario,
+  maxLeverage,
+  planDeleverage,
+  planLeverageLoop,
+  tokensForCollateral,
+} from "./math.js";
+export type {
+  PlanDeleverageFromChainParams,
+  PlanLeverageFromChainParams,
+  PlanLeverageFromChainPreciseParams,
+} from "./plan.js";
+// RPC-aware planners
+export {
+  planDeleverageFromChain,
+  planLeverageFromChain,
+  planLeverageFromChainPrecise,
+  resolveLeveragePositionId,
+} from "./plan.js";
+export type { ReadErc1155IsApprovedForAllParams } from "./preflight.js";
+// Preflight
+export {
+  prepareApprovePositionsTokenIfNeeded,
+  readErc1155IsApprovedForAll,
+} from "./preflight.js";
+// Types + constants
+export type {
+  BuyResult,
+  DeleveragePlan,
+  DeleverageStep,
+  LeverageDirection,
+  LeveragePlan,
+  LeverageStep,
+  LeverageStepResult,
+  LeverageSummary,
+  OnLeverageProgress,
+  SellResult,
+} from "./types.js";
+export {
+  collateralForDollars,
+  DEFAULT_MAX_ITERATIONS,
+  DEFAULT_MIN_STEP_COLLATERAL,
+  PRICE_E8,
+  pow10,
+  WAD,
+} from "./types.js";

package/src/leverage/math.ts

@@ -0,0 +1,446 @@
+// Note: explicit .js extension is required for Node ESM resolution.
+
+/**
+ * Pure math helpers for leverage planning.
+ *
+ * All functions are deterministic and have zero side-effects (no RPC, no I/O).
+ * They operate on bigint with WAD (1e18) and PRICE_E8 (1e8) precision.
+ */
+
+import type {
+  DeleveragePlan,
+  DeleverageStep,
+  LeveragePlan,
+  LeverageStep,
+  LeverageSummary,
+} from "./types.js";
+import { DEFAULT_MAX_ITERATIONS, DEFAULT_MIN_STEP_COLLATERAL, PRICE_E8, WAD } from "./types.js";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** max(a, 0n) */
+function clampPositive(a: bigint): bigint {
+  return a > 0n ? a : 0n;
+}
+
+/**
+ * Floor division: a * b / c (bigint, no overflow risk in JS BigInt).
+ */
+function mulDiv(a: bigint, b: bigint, c: bigint): bigint {
+  if (c === 0n) throw new Error("mulDiv: division by zero");
+  return (a * b) / c;
+}
+
+/**
+ * Ceil division: (a * b + c - 1) / c.
+ */
+function mulDivUp(a: bigint, b: bigint, c: bigint): bigint {
+  if (c === 0n) throw new Error("mulDivUp: division by zero");
+  return (a * b + c - 1n) / c;
+}
+
+// ---------------------------------------------------------------------------
+// Public helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Maximum theoretical leverage for a given LTV.
+ *
+ * Formula: 1 / (1 - LTV)
+ */
+export function maxLeverage(ltvWad: bigint): bigint {
+  if (ltvWad <= 0n) return WAD; // 0% LTV → 1×
+  if (ltvWad >= WAD) throw new Error("LTV must be < 100%");
+  return mulDiv(WAD, WAD, WAD - ltvWad);
+}
+
+/**
+ * Estimated liquidation price for a leveraged position.
+ *
+ * HF = (tokens * price * LTV) / debt = 1.0
+ * → price = debt / (tokens * LTV)
+ */
+export function estimateLiquidationPrice(
+  totalTokens: bigint,
+  totalDebt: bigint,
+  ltvWad: bigint,
+): bigint {
+  if (totalTokens <= 0n) return 0n;
+  if (totalDebt <= 0n) return 0n;
+  if (ltvWad <= 0n) return 0n;
+
+  const numerator = totalDebt * PRICE_E8 * WAD;
+  const denominator = totalTokens * ltvWad;
+  if (denominator === 0n) return 0n;
+  // Round UP (conservative: liquidation happens sooner than estimated).
+  return (numerator + denominator - 1n) / denominator;
+}
+
+/**
+ * Compute how many outcome tokens you get for a given collateral amount at a given price.
+ *
+ * tokens = collateral * PRICE_E8 / price
+ */
+export function tokensForCollateral(collateralAmount: bigint, tokenPriceE8: bigint): bigint {
+  if (tokenPriceE8 <= 0n) throw new Error("Token price must be > 0");
+  return mulDiv(collateralAmount, PRICE_E8, tokenPriceE8);
+}
+
+/**
+ * Compute collateral value of a token amount at a given price.
+ *
+ * collateral = tokens * price / PRICE_E8
+ */
+export function collateralForTokens(tokenAmount: bigint, tokenPriceE8: bigint): bigint {
+  return mulDiv(tokenAmount, tokenPriceE8, PRICE_E8);
+}
+
+// ---------------------------------------------------------------------------
+// Leverage loop planner
+// ---------------------------------------------------------------------------
+
+export type PlanLeverageLoopParams = {
+  /** User's initial collateral capital (collateral base units). */
+  initialCapital: bigint;
+  /** Current token price (8 decimals). */
+  tokenPriceE8: bigint;
+  /** Effective LTV for this position (WAD). */
+  ltvWad: bigint;
+  /**
+   * Target leverage as WAD (e.g. 3e18 = 3.0×).
+   *
+   * NOTE: This planner targets leverage precisely under the assumption that:
+   * - all borrows are immediately spent at a constant price,
+   * - and there are no fees.
+   */
+  targetLeverageWad?: bigint;
+  /** Max iterations (default: 10). */
+  maxIterations?: number;
+  /** Minimum borrow per step to continue looping (default: DEFAULT_MIN_STEP_COLLATERAL). */
+  minStepBorrow?: bigint;
+  /** Starting deposited token amount already in Core (optional). */
+  startingTokens?: bigint;
+  /** Starting debt already owed to Core/Pool (optional). */
+  startingDebt?: bigint;
+  /** Optional absolute cap on total debt (collateral base units). */
+  maxTotalDebt?: bigint;
+};
+
+/**
+ * Plan a leverage loop (pure math, zero RPC).
+ *
+ * Output steps:
+ * - buy (off-chain)
+ * - deposit (on-chain)
+ * - borrow (on-chain)
+ * - repeat
+ *
+ * Important: the loop is designed so it **does not end with an unused borrow**.
+ * If `maxIterations` is hit, the final iteration ends at `deposit`.
+ */
+export function planLeverageLoop(params: PlanLeverageLoopParams): LeveragePlan {
+  const {
+    initialCapital,
+    tokenPriceE8,
+    ltvWad,
+    targetLeverageWad,
+    maxIterations = DEFAULT_MAX_ITERATIONS,
+    minStepBorrow = DEFAULT_MIN_STEP_COLLATERAL,
+    startingTokens = 0n,
+    startingDebt = 0n,
+    maxTotalDebt,
+  } = params;
+
+  if (initialCapital <= 0n) throw new Error("initialCapital must be > 0");
+  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 (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");
+
+  const maxLev = maxLeverage(ltvWad);
+
+  // Target leverage semantics:
+  // - undefined => run to max (bounded by maxIterations / minStepBorrow / caps)
+  // - <= 1× => treat as 1× (no borrowing)
+  // - > maxLev => clamp to maxLev
+  const effectiveTargetLev =
+    targetLeverageWad !== undefined
+      ? targetLeverageWad <= WAD
+        ? WAD
+        : targetLeverageWad > maxLev
+          ? maxLev
+          : targetLeverageWad
+      : undefined;
+
+  const steps: LeverageStep[] = [];
+  let totalTokens = startingTokens;
+  let totalDebt = startingDebt;
+  let collateralAvailable = initialCapital;
+
+  // Equity is invariant under constant price assumption.
+  const startingExposure = collateralForTokens(startingTokens, tokenPriceE8);
+  const baseEquity = clampPositive(startingExposure - startingDebt) + initialCapital;
+
+  // L = exposure / equity = 1 + debt / equity  =>  debtTarget = equity*(L-1)
+  const targetTotalDebt =
+    effectiveTargetLev !== undefined
+      ? effectiveTargetLev > WAD
+        ? mulDiv(baseEquity, effectiveTargetLev - WAD, WAD)
+        : 0n
+      : undefined;
+
+  for (let i = 0; i < maxIterations; i++) {
+    if (collateralAvailable <= 0n) break;
+
+    // buy
+    const spendCollateral = collateralAvailable;
+
+    const tokensBought = tokensForCollateral(spendCollateral, tokenPriceE8);
+    if (tokensBought <= 0n) break;
+
+    // Spend the available collateral for this iteration.
+    // The next iteration is funded *only* via the subsequent borrow.
+    collateralAvailable = 0n;
+
+    steps.push({
+      kind: "buy",
+      collateralAmount: spendCollateral,
+      expectedTokens: tokensBought,
+      iteration: i,
+    });
+    totalTokens += tokensBought;
+
+    // deposit
+    steps.push({ kind: "deposit", amount: tokensBought, iteration: i });
+
+    // If this is the last allowed iteration, do not borrow (would be unused).
+    if (i === maxIterations - 1) break;
+
+    // borrow
+    const exposure = collateralForTokens(totalTokens, tokenPriceE8);
+    const maxAdditionalBorrow = clampPositive(mulDiv(exposure, ltvWad, WAD) - totalDebt);
+    if (maxAdditionalBorrow <= 0n) break;
+
+    let borrowAmount = maxAdditionalBorrow;
+
+    // Targeting cap.
+    if (targetTotalDebt !== undefined) {
+      const remaining = clampPositive(targetTotalDebt - totalDebt);
+      borrowAmount = remaining < borrowAmount ? remaining : borrowAmount;
+    }
+
+    // Absolute cap on total debt (e.g., pool liquidity headroom).
+    if (maxTotalDebt !== undefined) {
+      const remaining = clampPositive(maxTotalDebt - totalDebt);
+      borrowAmount = remaining < borrowAmount ? remaining : borrowAmount;
+    }
+
+    if (borrowAmount <= 0n) break;
+    if (borrowAmount < minStepBorrow) break;
+
+    steps.push({ kind: "borrow", collateralAmount: borrowAmount, iteration: i });
+    totalDebt += borrowAmount;
+    collateralAvailable = borrowAmount;
+  }
+
+  // Compute summary.
+  const totalExposure = collateralForTokens(totalTokens, tokenPriceE8);
+  const netEquity = clampPositive(totalExposure - totalDebt);
+  const effectiveLeverageWad = netEquity > 0n ? mulDiv(totalExposure, WAD, netEquity) : 0n;
+  const estimatedLiquidationPriceE8 = estimateLiquidationPrice(totalTokens, totalDebt, ltvWad);
+
+  const iterations = steps.length > 0 ? steps[steps.length - 1]!.iteration + 1 : 0;
+
+  const summary: LeverageSummary = {
+    totalTokens,
+    totalDebt,
+    netEquity,
+    effectiveLeverageWad,
+    estimatedLiquidationPriceE8,
+    iterations,
+    maxLeverageWad: maxLev,
+  };
+
+  return {
+    steps,
+    summary,
+    params: {
+      initialCapital,
+      tokenPriceE8,
+      ltvWad,
+      targetLeverageWad,
+      maxIterations,
+      minStepBorrow,
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Deleverage planner
+// ---------------------------------------------------------------------------
+
+export type PlanDeleverageParams = {
+  /** Current deposited token balance in VarlaCore. */
+  depositedTokens: bigint;
+  /** Current collateral debt (collateral base units). */
+  currentDebt: bigint;
+  /** Current token price (8 decimals). */
+  tokenPriceE8: bigint;
+  /** Effective LTV for this position (WAD). */
+  ltvWad: bigint;
+  /**
+   * How much debt to reduce.
+   * Use "full" for complete unwind, or a bigint for partial deleverage.
+   */
+  targetDebtReduction: "full" | bigint;
+  /** Max iterations (default: 10). */
+  maxIterations?: number;
+  /** Minimum sell size (in collateral base units) to continue looping. */
+  minStepSell?: bigint;
+};
+
+/**
+ * Plan a deleverage (unwind) loop (pure math, zero RPC).
+ *
+ * Steps: withdraw → sell → repay → ...
+ */
+export function planDeleverage(params: PlanDeleverageParams): DeleveragePlan {
+  const {
+    depositedTokens,
+    currentDebt,
+    tokenPriceE8,
+    ltvWad,
+    targetDebtReduction,
+    maxIterations = DEFAULT_MAX_ITERATIONS,
+    minStepSell = DEFAULT_MIN_STEP_COLLATERAL,
+  } = 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");
+
+  const targetRepay = targetDebtReduction === "full" ? currentDebt : targetDebtReduction;
+  if (targetRepay <= 0n) {
+    return {
+      steps: [],
+      summary: {
+        tokensToSell: 0n,
+        totalRepayment: 0n,
+        tokensRemaining: depositedTokens,
+        collateralRemaining: 0n,
+        iterations: 0,
+      },
+    };
+  }
+
+  const steps: DeleverageStep[] = [];
+  let remainingTokens = depositedTokens;
+  let remainingDebt = currentDebt;
+  let totalSold = 0n;
+  let totalRepaid = 0n;
+
+  for (let i = 0; i < maxIterations; i++) {
+    if (remainingDebt <= 0n) break;
+    if (totalRepaid >= targetRepay) break;
+    if (remainingTokens <= 0n) break;
+
+    // How many tokens must remain to keep HF >= 1?
+    // HF = (tokens * price * ltv) / debt >= 1
+    // → tokens >= ceil(debt * PRICE_E8 * WAD / (price * ltv))
+    const minTokensForHealth =
+      remainingDebt > 0n ? mulDivUp(remainingDebt, PRICE_E8 * WAD, tokenPriceE8 * ltvWad) : 0n;
+
+    const withdrawable = clampPositive(remainingTokens - minTokensForHealth);
+    if (withdrawable <= 0n) break;
+
+    // Cap to remaining target repayment.
+    const remainingTarget = clampPositive(targetRepay - totalRepaid);
+    const tokensNeededForTarget = mulDivUp(remainingTarget, PRICE_E8, tokenPriceE8);
+    const tokensToWithdraw =
+      withdrawable < tokensNeededForTarget ? withdrawable : tokensNeededForTarget;
+    if (tokensToWithdraw <= 0n) break;
+
+    const collateralProceeds = collateralForTokens(tokensToWithdraw, tokenPriceE8);
+    if (collateralProceeds < minStepSell) break;
+
+    // withdraw
+    steps.push({ kind: "withdraw", amount: tokensToWithdraw, iteration: i });
+    remainingTokens -= tokensToWithdraw;
+
+    // sell
+    steps.push({
+      kind: "sell",
+      tokenAmount: tokensToWithdraw,
+      expectedCollateral: collateralProceeds,
+      iteration: i,
+    });
+    totalSold += tokensToWithdraw;
+
+    // repay
+    const repayAmount = collateralProceeds > remainingDebt ? remainingDebt : collateralProceeds;
+    steps.push({ kind: "repay", collateralAmount: repayAmount, iteration: i });
+    remainingDebt -= repayAmount;
+    totalRepaid += repayAmount;
+  }
+
+  const collateralRemaining = clampPositive(
+    collateralForTokens(remainingTokens, tokenPriceE8) - remainingDebt,
+  );
+  const iterations = steps.length > 0 ? steps[steps.length - 1]!.iteration + 1 : 0;
+
+  return {
+    steps,
+    summary: {
+      tokensToSell: totalSold,
+      totalRepayment: totalRepaid,
+      tokensRemaining: remainingTokens,
+      collateralRemaining,
+      iterations,
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// P&L scenario helper
+// ---------------------------------------------------------------------------
+
+export type LeverageScenario = {
+  /** Exit price (8 decimals). */
+  exitPriceE8: bigint;
+  /** Gross position value at exit. */
+  grossValue: bigint;
+  /** Profit/loss vs initial capital (can be negative). */
+  pnl: bigint;
+  /** Return as WAD (e.g. 2.5e18 = +250%). Negative for losses. */
+  returnWad: bigint;
+  /** Whether position would be liquidated at this price. */
+  isLiquidated: boolean;
+};
+
+/**
+ * Compute P&L for a leveraged position at a hypothetical exit price.
+ */
+export function leverageScenario(params: {
+  totalTokens: bigint;
+  totalDebt: bigint;
+  initialCapital: bigint;
+  exitPriceE8: bigint;
+  ltvWad: bigint;
+}): LeverageScenario {
+  const { totalTokens, totalDebt, initialCapital, exitPriceE8, ltvWad } = params;
+
+  const grossValue = collateralForTokens(totalTokens, exitPriceE8);
+  const pnl = grossValue - totalDebt - initialCapital;
+
+  const returnWad = initialCapital > 0n ? mulDiv(pnl, WAD, initialCapital) : 0n;
+
+  // HF = (tokens * price * ltv) / debt
+  const collateralValue = mulDiv(grossValue, ltvWad, WAD);
+  const isLiquidated = totalDebt > 0n && collateralValue < totalDebt;
+
+  return { exitPriceE8, grossValue, pnl, returnWad, isLiquidated };
+}