@strkfarm/sdk 2.0.0-dev.3 → 2.0.0-dev.30

package/src/strategies/vesu-extended-strategy/services/ltv-imbalance-rebalance-math.ts

@@ -0,0 +1,783 @@
+// ============================================================
+// rebalance.ts — Delta-Neutral Rebalancing Solver
+// ============================================================
+//
+// Manages two matched BTC positions across Extended (leveraged perp)
+// and Vesu (collateral/debt lending), ensuring:
+//   1. Margin health on both protocols
+//   2. Equal BTC exposure on both sides
+//
+// Architecture:
+//   Phase 1 — Try to fix margin deficits using 5 funding sources
+//   Phase 2 — Unified position + margin solver
+//             Simultaneously resolves position imbalance AND any
+//             remaining margin deficits from Phase 1 by finding
+//             the optimal common position F that satisfies both
+//             Extended margin and Vesu HF constraints.
+//
+// Key leverage mechanics:
+//   Extended: depositing $x of margin creates $x × leverage of position.
+//     → cost to create gapBtc = gapBtc × price / leverage
+//     → margin released by closing = closeBtc × price / leverage
+//
+//   Vesu: depositing $x of equity creates $x / (1 - targetLTV) of position.
+//     → cost to create gapBtc = gapBtc × price × (1 - targetLTV)
+//     → equity freed by closing = closeBtc × price × (1 - currentLTV)
+//       (because debt proportional to the close must be repaid first)
+//
+// All functions are pure except drawFunds which mutates the pool
+// to track remaining balances across sequential draws.
+// ============================================================
+
+import { logger } from "@/utils";
+
+// ---- Types ----
+
+export interface RebalanceConfig {
+  positionPrecision: number;  // decimal places for BTC rounding, e.g. 4
+  hfBuffer: number;           // HF tolerance before acting, e.g. 0.05
+  /**
+   * USD below this cannot be executed as a standalone transfer/borrow/repay step
+   * (matches execution-layer dust threshold). Default 0 keeps pure math tests unchanged.
+   */
+  minRoutableUsd?: number;
+}
+
+export interface ExtendedState {
+  positionBtc: number;       // current BTC position size
+  equity: number;            // current equity in USD
+  avlWithdraw: number;       // withdrawable surplus in USD (0 if equity < idealMargin)
+  upnl: number;              // unrealized PnL in USD (0 if equity < idealMargin)
+  leverage: number;          // target leverage, typically 3
+}
+
+export interface VesuState {
+  positionBtc: number;       // BTC collateral position
+  debt: number;              // outstanding debt in debt-token units
+  debtPrice: number;         // USD price per debt token
+  maxLTV: number;            // liquidation LTV threshold, e.g. 0.8
+  targetHF: number;          // target health factor, e.g. 1.25
+}
+
+/** Mutable pool of available funding sources, drawn in priority order. */
+export interface FundingPool {
+  vaUsd: number;             // yield aggregator (VA / Troves) balance
+  walletUsd: number;         // hot wallet balance
+  vesuBorrowCapacity: number; // remaining borrow headroom on Vesu, in USD
+  extAvlWithdraw: number;    // withdrawable from Extended
+  extUpnl: number;           // realizable UPNL from Extended
+}
+
+type FundKey = keyof FundingPool;
+
+interface RebalanceInputs {
+  ext: ExtendedState;
+  vesu: VesuState;
+  btcPrice: number;
+  funding: FundingPool;
+  config: RebalanceConfig;
+}
+
+/** All deltas are signed: negative = reducing/withdrawing, positive = increasing/depositing. */
+interface RebalanceDeltas {
+  dExtPosition: number;           // BTC change on Extended (negative = close)
+  dVesuPosition: number;          // BTC change on Vesu (negative = close)
+  dVesuDebt: number;              // debt-token change on Vesu (negative = repay)
+  dExtAvlWithdraw: number;        // USD change in Extended withdrawable equity
+  dExtUpnl: number;               // USD change in Extended UPNL (negative = realized)
+  dVaUsd: number;                 // USD change in VA balance (negative = withdrawn)
+  dWalletUsd: number;             // USD change in wallet (negative = withdrawn)
+  dVesuBorrowCapacity: number;    // USD change in Vesu borrow room (negative = used)
+  dTransferVesuToExt: number;     // net USD transferred from Vesu to Extended
+                                  //   positive = Vesu sends to Extended
+                                  //   negative = Extended sends to Vesu
+}
+
+// ---- Precision helpers ----
+
+/** Ceil a BTC amount up to `precision` decimal places (used when closing positions). */
+function ceilBtc(v: number, precision: number): number {
+  const f = 10 ** precision;
+  return Math.ceil(v * f) / f;
+}
+
+/** Floor a BTC amount down to `precision` decimal places (used for target positions). */
+function floorBtc(v: number, precision: number): number {
+  const f = 10 ** precision;
+  return Math.floor(v * f) / f;
+}
+
+/** Check if a BTC amount is below the smallest representable unit. */
+function isNegligible(btc: number, precision: number): boolean {
+  return Math.abs(btc) < 10 ** -precision;
+}
+
+// ---- Health computations ----
+
+/**
+ * Minimum equity required on Extended for a given position.
+ * idealMargin = positionValue / leverage
+ */
+function computeExtIdealMargin(posBtc: number, leverage: number, price: number): number {
+  return (posBtc * price) / leverage;
+}
+
+/**
+ * How much USD equity Extended is short of its ideal margin.
+ * Returns 0 if equity is sufficient.
+ */
+function computeExtDeficit(ext: ExtendedState, price: number): number {
+  return Math.max(0, computeExtIdealMargin(ext.positionBtc, ext.leverage, price) - ext.equity);
+}
+
+/**
+ * Vesu health factor: HF = maxLTV / currentLTV.
+ * Higher is healthier. Returns Infinity if no debt or no collateral.
+ */
+function computeVesuHF(vesu: VesuState, price: number): number {
+  const collateralUsd = vesu.positionBtc * price;
+  if (collateralUsd === 0) return Infinity;
+  const ltv = (vesu.debt * vesu.debtPrice) / collateralUsd;
+  if (ltv === 0) return Infinity;
+  return vesu.maxLTV / ltv;
+}
+
+/**
+ * Debt (in token units) that must be repaid to bring Vesu HF back to targetHF,
+ * assuming collateral position stays constant.
+ *
+ * Derivation: targetHF = maxLTV / targetLTV
+ *   → targetLTV = maxLTV / targetHF
+ *   → requiredDebt = targetLTV × collateralUsd / debtPrice
+ *   → repay = currentDebt - requiredDebt
+ */
+function computeVesuDebtRepay(vesu: VesuState, price: number): number {
+  const targetLTV = vesu.maxLTV / vesu.targetHF;
+  const collateralUsd = vesu.positionBtc * price;
+  const requiredDebt = (targetLTV * collateralUsd) / vesu.debtPrice;
+  return Math.max(0, vesu.debt - requiredDebt);
+}
+
+/**
+ * Compute the target LTV for Vesu based on its targetHF.
+ * targetLTV = maxLTV / targetHF
+ *
+ * This is the LTV we aim to maintain after any position changes.
+ * Used to compute equity costs, debt changes, and the unified solver.
+ */
+function computeVesuTargetLTV(vesu: VesuState): number {
+  return vesu.maxLTV / vesu.targetHF;
+}
+
+/**
+ * Compute the USD equity cost to grow Vesu position by `gapBtc`.
+ *
+ * Vesu is a leveraged lending position. Depositing $x as collateral,
+ * borrowing at targetLTV, recycling proceeds → converges to:
+ *
+ *   totalPosition = equity / (1 - targetLTV)
+ *   → equityCost = gapBtc × btcPrice × (1 - targetLTV)
+ */
+function computeVesuGrowthCost(gapBtc: number, vesu: VesuState, price: number): number {
+  const targetLTV = computeVesuTargetLTV(vesu);
+  return gapBtc * price * (1 - targetLTV);
+}
+
+/**
+ * Compute new debt (in token units) created when growing Vesu by `gapBtc`.
+ *   newDebtTokens = gapBtc × btcPrice × targetLTV / debtPrice
+ */
+function computeVesuGrowthDebt(gapBtc: number, vesu: VesuState, price: number): number {
+  const targetLTV = computeVesuTargetLTV(vesu);
+  return (gapBtc * price * targetLTV) / vesu.debtPrice;
+}
+
+/**
+ * Given available USD equity, compute max BTC position growth on Vesu.
+ *   gapBtc = equityUsd / (btcPrice × (1 - targetLTV))
+ */
+function computeVesuGrowthFromEquity(equityUsd: number, vesu: VesuState, price: number): number {
+  const targetLTV = computeVesuTargetLTV(vesu);
+  return equityUsd / (price * (1 - targetLTV));
+}
+
+// ---- Delta helpers ----
+
+function emptyDeltas(): RebalanceDeltas {
+  return {
+    dExtPosition: 0, dVesuPosition: 0, dVesuDebt: 0,
+    dExtAvlWithdraw: 0, dExtUpnl: 0, dVaUsd: 0,
+    dWalletUsd: 0, dVesuBorrowCapacity: 0, dTransferVesuToExt: 0,
+  };
+}
+
+/** Element-wise addition of two delta sets. */
+function mergeDeltas(a: RebalanceDeltas, b: RebalanceDeltas): RebalanceDeltas {
+  return {
+    dExtPosition:        a.dExtPosition        + b.dExtPosition,
+    dVesuPosition:       a.dVesuPosition       + b.dVesuPosition,
+    dVesuDebt:           a.dVesuDebt           + b.dVesuDebt,
+    dExtAvlWithdraw:     a.dExtAvlWithdraw     + b.dExtAvlWithdraw,
+    dExtUpnl:            a.dExtUpnl            + b.dExtUpnl,
+    dVaUsd:              a.dVaUsd              + b.dVaUsd,
+    dWalletUsd:          a.dWalletUsd          + b.dWalletUsd,
+    dVesuBorrowCapacity: a.dVesuBorrowCapacity + b.dVesuBorrowCapacity,
+    dTransferVesuToExt:  a.dTransferVesuToExt  + b.dTransferVesuToExt,
+  };
+}
+
+// ---- Fund drawing engine ----
+
+interface DrawResult {
+  draws: Partial<Record<FundKey, number>>; // how much was taken from each source
+  filled: number;                          // total USD successfully drawn
+  unmet: number;                           // remaining USD still needed
+}
+
+/**
+ * Portion of `need` we can take from `avail` such that execution can actually move it.
+ * Chunks at or below `minRoutable` are skipped (caller may satisfy `need` from another source
+ * or leave it unmet); matches VA/wallet/borrow dust rules in the state manager.
+ */
+function routableDrawAmount(avail: number, need: number, minRoutable: number): number {
+  if (avail <= 0 || need <= 0) return 0;
+  const raw = Math.min(avail, need);
+  if (raw <= 0) return 0;
+  if (minRoutable <= 0) return raw;
+  return raw > minRoutable ? raw : 0;
+}
+
+/**
+ * Draw `need` USD from funding sources in strict priority order.
+ * Mutates `pool` balances so subsequent draws see reduced availability.
+ * Each source contributes a routable amount (see {@link routableDrawAmount}).
+ */
+function drawFunds(need: number, keys: FundKey[], pool: FundingPool, minRoutable: number): DrawResult {
+  const draws: Partial<Record<FundKey, number>> = {};
+  let unmet = need;
+  for (const k of keys) {
+    if (unmet <= 0) break;
+    const avail = pool[k];
+    const take = routableDrawAmount(avail, unmet, minRoutable);
+    if (take <= 0) continue;
+    draws[k] = take;
+    pool[k] -= take;
+    unmet -= take;
+  }
+  return { draws, filled: need - unmet, unmet };
+}
+
+/**
+ * Withdraw + uPnL are separate buckets but execution moves them in one EXTENDED_TO_WALLET leg
+ * (waterfall inside the budget). Apply {@link routableDrawAmount} to their **sum**, then drain
+ * avl-withdraw first, then uPnL — matches spendExtAvailTrade in the state-manager budget.
+ */
+function drawExtendedAggregated(need: number, pool: FundingPool, minRoutable: number): DrawResult {
+  const draws: Partial<Record<FundKey, number>> = {};
+  if (need <= 0) return { draws, filled: 0, unmet: 0 };
+  const totalCap = Math.max(0, pool.extAvlWithdraw) + Math.max(0, pool.extUpnl);
+  const want = routableDrawAmount(totalCap, need, minRoutable);
+  if (want <= 0) return { draws, filled: 0, unmet: need };
+  const fromAvl = Math.min(Math.max(0, pool.extAvlWithdraw), want);
+  pool.extAvlWithdraw -= fromAvl;
+  const fromUpnl = Math.min(Math.max(0, pool.extUpnl), want - fromAvl);
+  pool.extUpnl -= fromUpnl;
+  if (fromAvl > 0) draws.extAvlWithdraw = fromAvl;
+  if (fromUpnl > 0) draws.extUpnl = fromUpnl;
+  const filled = fromAvl + fromUpnl;
+  return { draws, filled, unmet: need - filled };
+}
+
+/** Sum draw amounts for a subset of keys (e.g. all Extended-sourced draws). */
+function sumKeys(draws: Partial<Record<FundKey, number>>, keys: FundKey[]): number {
+  return keys.reduce((s, k) => s + (draws[k] ?? 0), 0);
+}
+
+/**
+ * Record fund draws as output deltas.
+ * sign = -1: sources are being drained (normal case).
+ * sign = +1: sources are being credited (e.g. freed margin returning).
+ */
+function applyDrawsToDeltas(d: RebalanceDeltas, draws: Partial<Record<FundKey, number>>, sign: number) {
+  d.dVaUsd              += sign * (draws.vaUsd              ?? 0);
+  d.dWalletUsd          += sign * (draws.walletUsd          ?? 0);
+  d.dVesuBorrowCapacity += sign * (draws.vesuBorrowCapacity ?? 0);
+  d.dExtAvlWithdraw     += sign * (draws.extAvlWithdraw     ?? 0);
+  d.dExtUpnl            += sign * (draws.extUpnl            ?? 0);
+}
+
+// ============================================================
+// PHASE 1: Margin health (best-effort from funding sources)
+// ============================================================
+//
+// Step 1a: Extended equity deficit → draw wallet → VA → vesuBorrowable
+// Step 1b: Vesu HF below threshold → repay debt from VA → wallet → extAvlWith → extUpnl
+//
+// Returns deltas + any unmet deficit amounts. Phase 2 handles the rest.
+// ============================================================
+
+interface Phase1Result {
+  deltas: RebalanceDeltas;
+  extDeficitRemaining: number;  // USD still needed for Extended margin
+  vesuRepayRemaining: number;   // USD still needed for Vesu debt repayment
+}
+
+/**
+ * Fix Extended margin deficit by drawing from external sources.
+ * Priority: wallet → VA → vesuBorrowCapacity.
+ * Funds received increase Extended equity (dExtAvlWithdraw).
+ */
+function fixExtMargin(ext: ExtendedState, price: number, pool: FundingPool, config: RebalanceConfig): { d: RebalanceDeltas; unmet: number } {
+  const d = emptyDeltas();
+  const deficit = computeExtDeficit(ext, price);
+  if (deficit <= 0) return { d, unmet: 0 };
+
+  const minR = config.minRoutableUsd ?? 0;
+  const { draws, filled, unmet } = drawFunds(deficit, ['walletUsd', 'vaUsd', 'vesuBorrowCapacity'], pool, minR);
+  applyDrawsToDeltas(d, draws, -1);
+
+  // All filled amount lands as Extended equity
+  d.dExtAvlWithdraw += filled;
+
+  // Funds borrowed from Vesu and sent to Extended = positive transfer
+  const fromVesu = draws.vesuBorrowCapacity ?? 0;
+  if (fromVesu > 0) d.dTransferVesuToExt += fromVesu;
+
+  return { d, unmet };
+}
+
+/**
+ * Fix Vesu health factor by repaying debt from available sources.
+ * Only triggers if HF < targetHF - hfBuffer (avoids churn near target).
+ * Priority: VA → wallet → extAvlWithdraw → extUpnl.
+ * Repaid amount reduces Vesu debt (dVesuDebt).
+ */
+function fixVesuMargin(vesu: VesuState, price: number, pool: FundingPool, hfBuffer: number, config: RebalanceConfig): { d: RebalanceDeltas; unmet: number } {
+  const d = emptyDeltas();
+  const hf = computeVesuHF(vesu, price);
+
+  // Only act if HF is meaningfully below target (buffer prevents churn)
+  if (hf >= vesu.targetHF - hfBuffer) return { d, unmet: 0 };
+
+  const repayTokens = computeVesuDebtRepay(vesu, price);
+  const repayUsd = repayTokens * vesu.debtPrice;
+
+  const minR = config.minRoutableUsd ?? 0;
+  const rMain = drawFunds(repayUsd, ['vaUsd', 'walletUsd'], pool, minR);
+  applyDrawsToDeltas(d, rMain.draws, -1);
+  const rExt = drawExtendedAggregated(rMain.unmet, pool, minR);
+  applyDrawsToDeltas(d, rExt.draws, -1);
+  const filled = rMain.filled + rExt.filled;
+  const unmet = rExt.unmet;
+
+  // Convert filled USD back to debt tokens for the repayment delta
+  d.dVesuDebt -= filled / vesu.debtPrice;
+
+  // Funds withdrawn from Extended and sent to Vesu = negative transfer
+  const fromExt = sumKeys(rExt.draws, ['extAvlWithdraw', 'extUpnl']);
+  if (fromExt > 0) d.dTransferVesuToExt -= fromExt;
+
+  return { d, unmet };
+}
+
+/**
+ * Phase 1 orchestrator: fix Extended margin, then Vesu margin.
+ * Extended draws wallet/VA first; Vesu draws from remaining pool.
+ * Returns combined deltas and any unresolved deficits.
+ */
+function phase1(ext: ExtendedState, vesu: VesuState, price: number, pool: FundingPool, config: RebalanceConfig): Phase1Result {
+  const extResult = fixExtMargin(ext, price, pool, config);
+  const vesuResult = fixVesuMargin(vesu, price, pool, config.hfBuffer, config);
+  return {
+    deltas: mergeDeltas(extResult.d, vesuResult.d),
+    extDeficitRemaining: extResult.unmet,
+    vesuRepayRemaining: vesuResult.unmet,
+  };
+}
+
+// ============================================================
+// PHASE 2: Unified position + margin solver
+// ============================================================
+//
+// This phase simultaneously resolves:
+//   a) Position imbalance (extPos ≠ vesuPos)
+//   b) Any remaining margin deficits from Phase 1
+//
+// It works by finding F, the optimal final common position for both
+// sides, such that both Extended margin and Vesu HF are satisfied.
+//
+// The approach has two steps:
+//   Step 1: Try to close the gap using available funding sources
+//           (grow the lagging side toward the leading side).
+//   Step 2: Whatever gap or deficit remains, solve for F using the
+//           unified equation that accounts for both protocols'
+//           leverage, existing positions, and existing equity/debt.
+//
+// ---- DERIVATION OF THE UNIFIED EQUATION ----
+//
+// After Phase 1, we have effective state:
+//   extPos, vesuPos   — BTC positions
+//   extEquity         — Extended equity in USD
+//   vesuDebt          — Vesu debt in token units
+//
+// We want to find F (final common position) such that both sides
+// can sustain it. Both dx = F - extPos and dy = F - vesuPos can
+// be positive (grow) or negative (shrink).
+//
+// CONSTRAINT 1 — Position equality:
+//   extPos + dx = vesuPos + dy = F   (by definition)
+//
+// CONSTRAINT 2 — Extended margin health:
+//   The equity available to Extended after the rebalance must cover
+//   the ideal margin on the final position.
+//
+//   extEquity + T ≥ F × price / extLeverage
+//
+//   Where T is the net transfer from Vesu to Extended.
+//   - If T > 0: Vesu sends surplus equity to Extended
+//   - If T < 0: Extended sends surplus margin to Vesu
+//
+// CONSTRAINT 3 — Vesu LTV at target:
+//   After the rebalance, remaining debt on remaining collateral
+//   must be at targetLTV:
+//
+//   (vesuDebt - debtRepay) × debtPrice = targetLTV × F × price
+//
+//   Solving for debtRepay:
+//   debtRepay = vesuDebt - (targetLTV × F × price / debtPrice)
+//
+// CONSTRAINT 4 — Vesu fund conservation:
+//   When Vesu position changes by dy, the collateral value change
+//   must balance between debt change and transfer:
+//
+//   (vesuPos - F) × price = debtRepay × debtPrice + T
+//
+//   This says: collateral freed (if closing) = debt repaid + transfer out.
+//   (If growing, both sides flip sign and it still holds.)
+//
+// SOLVING:
+//   Substitute debtRepay from C3 into C4:
+//
+//   T = (vesuPos - F) × price - (vesuDebt - targetLTV × F × price / debtPrice) × debtPrice
+//   T = (vesuPos - F) × price - vesuDebt × debtPrice + targetLTV × F × price
+//   T = vesuPos × price - F × price - vesuDebt × debtPrice + targetLTV × F × price
+//   T = vesuPos × price - vesuDebt × debtPrice - F × price × (1 - targetLTV)
+//
+//   Now substitute T into C2 (as equality for the optimal F):
+//
+//   extEquity + vesuPos × price - vesuDebt × debtPrice - F × price × (1 - targetLTV)
+//     = F × price / extLeverage
+//
+//   extEquity + vesuPos × price - vesuDebt × debtPrice
+//     = F × price × (1 - targetLTV + 1/extLeverage)
+//
+//   Let k = 1 - targetLTV + 1/extLeverage
+//
+//   F = (extEquity + vesuPos × price - vesuDebt × debtPrice) / (price × k)
+//
+// INTUITION:
+//   The numerator is the total "real equity" in the system:
+//     extEquity (what Extended actually owns)
+//     + vesuPos × price (Vesu collateral value)
+//     - vesuDebt × debtPrice (minus what Vesu owes)
+//   This is the combined net worth across both protocols.
+//
+//   The denominator (price × k) represents the "equity cost per BTC
+//   of matched position" — maintaining 1 BTC on Extended costs
+//   price/leverage in margin, and maintaining 1 BTC on Vesu costs
+//   price × (1 - targetLTV) in equity. Together: price × k.
+//
+//   So F = totalEquity / costPerBtc — the maximum matched position
+//   the system can afford.
+//
+// DERIVED QUANTITIES:
+//   Once F is known:
+//     dx = F - extPos             (Extended position change)
+//     dy = F - vesuPos            (Vesu position change)
+//     debtRepay = vesuDebt - targetLTV × F × price / debtPrice
+//     T = vesuPos × price - vesuDebt × debtPrice - F × price × (1 - targetLTV)
+//
+//   If debtRepay < 0, Vesu takes on more debt (position grew).
+//   If T < 0, Extended sends funds to Vesu.
+//   dx and dy can each be positive or negative independently.
+// ============================================================
+
+/**
+ * Solve for the optimal final common position F.
+ *
+ * F = (extEquity + vesuPos × price - vesuDebt × debtPrice) / (price × k)
+ * where k = 1 - targetLTV + 1/extLeverage
+ *
+ * This is the largest matched position that both protocols can sustain
+ * given their combined net equity.
+ */
+function solveUnifiedF(
+  extPos: number, vesuPos: number, extEquity: number,
+  vesuDebt: number, vesu: VesuState, extLev: number, price: number,
+): number {
+  const targetLTV = computeVesuTargetLTV(vesu);
+
+  // k = equity cost per BTC of matched position, divided by price
+  // Extended needs price/lev per BTC, Vesu needs price×(1-tLTV) per BTC
+  const k = 1 - targetLTV + 1 / extLev;
+
+  // Numerator = total real equity across both protocols
+  const totalEquity = extEquity + vesuPos * price - vesuDebt * vesu.debtPrice;
+
+  return totalEquity / (price * k);
+}
+
+/**
+ * Compute the net transfer T given the final position F.
+ *
+ * T = vesuPos × price - vesuDebt × debtPrice - F × price × (1 - targetLTV)
+ *
+ * Positive T means Vesu sends surplus to Extended.
+ * Negative T means Extended sends surplus to Vesu.
+ */
+function solveTransfer(
+  vesuPos: number, vesuDebt: number, F: number,
+  vesu: VesuState, price: number,
+): number {
+  const targetLTV = computeVesuTargetLTV(vesu);
+  return vesuPos * price - vesuDebt * vesu.debtPrice - F * price * (1 - targetLTV);
+}
+
+/**
+ * Compute the debt repayment (in token units) for the final position F.
+ *
+ * debtRepay = vesuDebt - targetLTV × F × price / debtPrice
+ *
+ * Positive = debt repaid. Negative = new debt taken on (position grew).
+ */
+function solveDebtRepay(
+  vesuDebt: number, F: number,
+  vesu: VesuState, price: number,
+): number {
+  const targetLTV = computeVesuTargetLTV(vesu);
+  return vesuDebt - (targetLTV * F * price / vesu.debtPrice);
+}
+
+/**
+ * Apply rounding to the final position F.
+ *
+ * For positions that shrink: ceil the close amount (close slightly more, safer).
+ * For positions that grow: floor the growth (grow slightly less, safer).
+ *
+ * After rounding, both sides must still land on the same final position.
+ * If rounding causes mismatch, align to the more conservative (smaller) value.
+ */
+function roundFinalPosition(
+  extPos: number, vesuPos: number, rawF: number, precision: number,
+): number {
+  // If F < extPos (Extended shrinks), the close amount is ceiled,
+  // so effective F is reduced: extPos - ceil(extPos - F)
+  // If F < vesuPos (Vesu shrinks), same logic.
+  // If F > a position (growth), floor the growth.
+
+  let fFromExt: number;
+  if (rawF < extPos) {
+    const closeExt = ceilBtc(extPos - rawF, precision);
+    fFromExt = extPos - closeExt;
+  } else {
+    const growExt = floorBtc(rawF - extPos, precision);
+    fFromExt = extPos + growExt;
+  }
+
+  let fFromVesu: number;
+  if (rawF < vesuPos) {
+    const closeVesu = ceilBtc(vesuPos - rawF, precision);
+    fFromVesu = vesuPos - closeVesu;
+  } else {
+    const growVesu = floorBtc(rawF - vesuPos, precision);
+    fFromVesu = vesuPos + growVesu;
+  }
+
+  // Align to the more conservative (smaller) final position
+  return Math.max(0, Math.min(fFromExt, fFromVesu));
+}
+
+/**
+ * Phase 2: Unified position + margin solver.
+ *
+ * First tries to close the position gap using available funding sources.
+ * Then solves the unified equation for any remaining gap + margin deficits.
+ *
+ * The function handles all combinations:
+ *   - Gap only (margins healthy): grows lagging side from funds, or converges
+ *   - Deficit only (positions matched): equally reduces both sides
+ *   - Both gap and deficit: finds F that resolves both simultaneously
+ */
+function phase2(
+  extPos: number, vesuPos: number, extEquity: number,
+  vesuDebt: number, vesu: VesuState, extLev: number, price: number,
+  pool: FundingPool, config: RebalanceConfig,
+): RebalanceDeltas {
+  const d = emptyDeltas();
+  const precision = config.positionPrecision;
+  const minR = config.minRoutableUsd ?? 0;
+  const targetLTV = computeVesuTargetLTV(vesu);
+
+  // ---- Step 1: Try to close gap using available funding sources ----
+  //
+  // Attempt to grow the lagging side to match the leading side,
+  // drawing from the funding pool. This is the "easy" path —
+  // if funds are sufficient, no position reduction needed.
+
+  const imbalance = extPos - vesuPos;  // positive = Extended is larger
+  let fundedGrowthBtc = 0;             // how much the lagging side actually grew
+
+  if (!isNegligible(imbalance, precision)) {
+    if (imbalance > 0) {
+      // Extended is larger — try to grow Vesu
+      // Vesu growth is leveraged: equity cost = gapBtc × price × (1 - targetLTV)
+      const equityCostUsd = computeVesuGrowthCost(imbalance, vesu, price);
+      const rMain = drawFunds(equityCostUsd, ['vaUsd', 'walletUsd'], pool, minR);
+      applyDrawsToDeltas(d, rMain.draws, -1);
+      const rExt = drawExtendedAggregated(rMain.unmet, pool, minR);
+      applyDrawsToDeltas(d, rExt.draws, -1);
+      const filled = rMain.filled + rExt.filled;
+
+      // Convert filled equity into leveraged position growth
+      const grownBtc = computeVesuGrowthFromEquity(filled, vesu, price);
+      d.dVesuPosition += grownBtc;
+      fundedGrowthBtc = grownBtc;
+
+      // New debt created alongside the leveraged growth
+      d.dVesuDebt += computeVesuGrowthDebt(grownBtc, vesu, price);
+
+      // Track ext → vesu fund movement
+      const fromExt = sumKeys(rExt.draws, ['extAvlWithdraw', 'extUpnl']);
+      if (fromExt > 0) d.dTransferVesuToExt -= fromExt;
+
+    } else {
+      // Vesu is larger — try to grow Extended
+      // Extended growth is leveraged: margin cost = gapBtc × price / extLeverage
+      const absImbalance = -imbalance;
+      const marginCostUsd = absImbalance * price / extLev;
+      const { draws, filled } = drawFunds(marginCostUsd, ['walletUsd', 'vaUsd', 'vesuBorrowCapacity'], pool, minR);
+      applyDrawsToDeltas(d, draws, -1);
+
+      // Each $1 of margin creates extLeverage/price BTC of position
+      const grownBtc = filled * extLev / price;
+      d.dExtPosition += grownBtc;
+      fundedGrowthBtc = grownBtc;
+
+      // Track vesu → ext fund movement
+      const fromVesu = draws.vesuBorrowCapacity ?? 0;
+      if (fromVesu > 0) d.dTransferVesuToExt += fromVesu;
+    }
+  }
+
+  // ---- Step 2: Solve unified equation for remaining gap + deficits ----
+  //
+  // After Step 1, compute the effective state. There may still be:
+  //   a) Remaining position imbalance (funds weren't enough to fully close gap)
+  //   b) Margin deficits (carried over from Phase 1)
+  //   c) Both
+  //
+  // The unified equation solves for the optimal F that handles everything.
+  // If Step 1 fully resolved the gap AND margins were already healthy,
+  // F will equal the current (now-matched) position and no further action needed.
+
+  const effExtPos = extPos + d.dExtPosition;
+  const effVesuPos = vesuPos + d.dVesuPosition;
+  const effExtEquity = extEquity;   // equity hasn't changed (draws came from pool, not equity)
+  const effVesuDebt = vesuDebt + d.dVesuDebt;
+
+  // Compute what F the system can actually sustain
+  const rawF = solveUnifiedF(effExtPos, effVesuPos, effExtEquity, effVesuDebt, vesu, extLev, price);
+
+  // If F ≥ both effective positions, everything is already healthy — no reduction needed.
+  // F might even be larger (meaning we could grow more, but we've exhausted funding sources).
+  // Cap F at the larger of the two effective positions (can't grow without funds).
+  const cappedF = Math.min(rawF, Math.max(effExtPos, effVesuPos));
+
+  // Also cap F at the smaller of the two if there's no remaining imbalance to close
+  // (if positions are matched, F can't grow either side without funds)
+  const maxGrowableTo = Math.max(effExtPos, effVesuPos);
+  const targetF = Math.max(0, Math.min(cappedF, maxGrowableTo));
+
+  // Check if further action is needed
+  const remainingImbalance = effExtPos - effVesuPos;
+  const extNeedsMore = effExtEquity < computeExtIdealMargin(effExtPos, extLev, price);
+  const vesuCurrentLTV = effVesuPos > 0
+    ? (effVesuDebt * vesu.debtPrice) / (effVesuPos * price)
+    : 0;
+  const vesuNeedsMore = vesuCurrentLTV > targetLTV;
+
+  const needsFurtherAction = !isNegligible(remainingImbalance, precision) || extNeedsMore || vesuNeedsMore;
+
+  if (!needsFurtherAction) {
+    return d;
+  }
+
+  // Apply rounding to F
+  const F = roundFinalPosition(effExtPos, effVesuPos, targetF, precision);
+
+  // Compute position changes relative to effective (post-Step 1) positions
+  const dx = F - effExtPos;  // Extended position change (negative = shrink)
+  const dy = F - effVesuPos; // Vesu position change (negative = shrink)
+
+  if (isNegligible(dx, precision) && isNegligible(dy, precision)) {
+    return d;
+  }
+
+  d.dExtPosition += dx;
+  d.dVesuPosition += dy;
+
+  // Compute debt change: positive debtRepay = debt reduced
+  // debtRepay = currentDebt - targetLTV × F × price / debtPrice
+  const debtRepay = solveDebtRepay(effVesuDebt, F, vesu, price);
+  d.dVesuDebt -= debtRepay;  // negative debtRepay means new debt (dVesuDebt increases)
+
+  // Compute transfer: positive = Vesu → Extended
+  const T = solveTransfer(effVesuPos, effVesuDebt, F, vesu, price);
+  d.dTransferVesuToExt += T;
+
+  // Record the transfer's effect on Extended equity
+  // T > 0: Extended receives funds → equity increases
+  // T < 0: Extended sends funds → equity decreases
+  d.dExtAvlWithdraw += T;
+
+  return d;
+}
+
+// ============================================================
+// ORCHESTRATOR
+// ============================================================
+
+/**
+ * Main entry point.
+ *
+ * Phase 1: best-effort margin repair from funding sources.
+ * Phase 2: unified solver for position matching + remaining deficits.
+ *
+ * The funding pool is cloned so the caller's data is not mutated.
+ * Phase 1 drains from the pool; Phase 2 draws from whatever remains,
+ * then solves the unified equation for anything left.
+ */
+function rebalance(inputs: RebalanceInputs): RebalanceDeltas {
+  logger.info(`ltv-imbalance-rebalance-math::rebalance inputs=${JSON.stringify(inputs)}`);
+  const { ext, vesu, btcPrice, config } = inputs;
+  const pool: FundingPool = { ...inputs.funding };
+
+  // Phase 1: best-effort margin repair from funding sources
+  const p1 = phase1(ext, vesu, btcPrice, pool, config);
+
+  // Phase 2: unified position + margin solver
+  // Uses effective state after Phase 1, plus remaining pool for gap-closing
+  const effExtPos = ext.positionBtc + p1.deltas.dExtPosition;
+  const effVesuPos = vesu.positionBtc + p1.deltas.dVesuPosition;
+  const effExtEquity = ext.equity + p1.deltas.dExtAvlWithdraw + p1.deltas.dExtUpnl;
+  const effVesuDebt = vesu.debt + p1.deltas.dVesuDebt;
+
+  const p2 = phase2(
+    effExtPos, effVesuPos, effExtEquity, effVesuDebt,
+    vesu, ext.leverage, btcPrice, pool, config,
+  );
+
+  return mergeDeltas(p1.deltas, p2);
+}
+
+export { rebalance, RebalanceInputs, RebalanceDeltas, routableDrawAmount };