@varla/sdk 2.11.0 → 2.13.0

package/src/views/core.ts

@@ -1664,6 +1664,103 @@ export async function readHypotheticalBorrowCapacity(params: {
   };
 }
 
+// ---------------------------------------------------------------------------
+// Current leverage helpers
+// ---------------------------------------------------------------------------
+
+export type ComputeCurrentLeverageResult = {
+  /**
+   * Current leverage as a WAD value (1e18 = 1.0×, 2e18 = 2.0×, etc.).
+   *
+   * - `WAD` (1e18) when the account has no debt (unleveraged).
+   * - `0n` when the account is underwater (debt ≥ portfolioValue).
+   */
+  leverageWad: bigint;
+  /**
+   * Whether the account is currently leveraged.
+   *
+   * `true` when both `debt > 0` and `portfolioValue > 0`.
+   */
+  isLeveraged: boolean;
+};
+
+/**
+ * Pure-math current leverage computation (zero RPC, zero side-effects).
+ *
+ * Formula:
+ * ```
+ * leverage = portfolioValue / (portfolioValue − debt)
+ * ```
+ *
+ * Edge cases:
+ * - No debt → 1.0× (`WAD`), `isLeveraged: false`.
+ * - No portfolio → 1.0× (`WAD`), `isLeveraged: false`.
+ * - Underwater (debt ≥ portfolioValue) → `0n`, `isLeveraged: true`.
+ */
+export function computeCurrentLeverage(params: {
+  portfolioValue: bigint;
+  debt: bigint;
+}): ComputeCurrentLeverageResult {
+  const { portfolioValue, debt } = params;
+
+  // No debt → unleveraged (1.0×).
+  if (debt <= 0n) return { leverageWad: _WAD, isLeveraged: false };
+  // No portfolio → unleveraged (1.0×).
+  if (portfolioValue <= 0n) return { leverageWad: _WAD, isLeveraged: false };
+  // Underwater or exactly at zero equity → degenerate.
+  if (portfolioValue <= debt) return { leverageWad: 0n, isLeveraged: true };
+
+  const equity = portfolioValue - debt;
+  const leverageWad = (portfolioValue * _WAD) / equity;
+  return { leverageWad, isLeveraged: true };
+}
+
+export type ReadCurrentLeverage = ComputeCurrentLeverageResult & {
+  /** Raw portfolio value from Core (collateral base units). */
+  portfolioValue: bigint;
+  /** Raw debt from Core (collateral base units). */
+  debt: bigint;
+};
+
+/**
+ * Reads on-chain state and computes the current leverage for a borrower.
+ *
+ * Intended for frontend portfolio cards showing "Current Leverage: 2.5×".
+ *
+ * Delegates to {@link readAccountSnapshot} for on-chain data, then applies
+ * the pure-math {@link computeCurrentLeverage}.
+ *
+ * @example
+ * ```ts
+ * import { readCurrentLeverage } from "@varla/sdk/views";
+ *
+ * const lev = await readCurrentLeverage({ core: c.core, user: "0x..." });
+ * if (lev.isLeveraged) {
+ *   console.log(`Leverage: ${Number(lev.leverageWad) / 1e18}×`);
+ * }
+ * ```
+ */
+// wraps: VarlaCore.getAccountSummary
+export async function readCurrentLeverage(params: {
+  core: {
+    read: {
+      getAccountSummary: (args: readonly [Address]) => Promise<unknown>;
+    };
+  };
+  user: Address;
+}): Promise<ReadCurrentLeverage> {
+  const snap = await readAccountSnapshot({ core: params.core as any, user: params.user });
+  const result = computeCurrentLeverage({
+    portfolioValue: snap.portfolioValue,
+    debt: snap.debt,
+  });
+  return {
+    ...result,
+    portfolioValue: snap.portfolioValue,
+    debt: snap.debt,
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Liquidation price helpers
 // ---------------------------------------------------------------------------