@strkfarm/sdk 2.0.0-dev.27 → 2.0.0-dev.28

package/src/strategies/vesu-extended-strategy/services/extended-vesu-state-manager.ts

@@ -0,0 +1,2941 @@
+import { ContractAddr, Web3Number } from "@/dataTypes";
+import { IConfig, TokenInfo } from "@/interfaces";
+import { PricerBase } from "@/modules/pricerBase";
+import { ERC20 } from "@/modules";
+import { assert, logger } from "@/utils";
+import { ExtendedAdapter } from "../../universal-adapters/extended-adapter";
+import { VesuMultiplyAdapter } from "../../universal-adapters/vesu-multiply-adapter";
+import { AssetOperationType, AssetOperationStatus } from "@/modules/ExtendedWrapperSDk";
+import { USDC_TOKEN_DECIMALS } from "../utils/constants";
+import {
+  calculateDeltaDebtAmount,
+  calculateExtendedLevergae,
+  calculateVesuLeverage,
+} from "../utils/helper";
+
+// ─── State types ───────────────────────────────────────────────────────────────
+
+/**
+ * Snapshot of a single Vesu pool's position: collateral, debt, and their prices.
+ */
+export interface VesuPoolState {
+  poolId: ContractAddr;
+  collateralToken: TokenInfo;
+  debtToken: TokenInfo;
+  collateralAmount: Web3Number;
+  collateralUsdValue: number;
+  debtAmount: Web3Number;
+  debtUsdValue: number;
+  collateralPrice: number;
+  debtPrice: number;
+}
+
+/**
+ * Snapshot of a single Extended exchange open position.
+ */
+export interface ExtendedPositionState {
+  instrument: string;
+  side: string;
+  size: Web3Number;
+  valueUsd: Web3Number;
+  leverage: string;
+}
+
+/**
+ * Snapshot of the Extended exchange account-level balance.
+ */
+export interface ExtendedBalanceState {
+  equity: Web3Number;
+  availableForTrade: Web3Number;
+  availableForWithdrawal: Web3Number;
+  unrealisedPnl: Web3Number;
+  balance: Web3Number;
+  /**
+   * Funds in transit to/from Extended.
+   * Positive = deposit in transit (funds left wallet, not yet credited on Extended).
+   * Negative = withdrawal in transit (funds left Extended, not yet received in wallet).
+   */
+  pendingDeposit: Web3Number;
+}
+
+/**
+ * Generic token balance with USD valuation.
+ */
+export interface TokenBalance {
+  token: TokenInfo;
+  amount: Web3Number;
+  usdValue: number;
+}
+
+// ─── Solve result types ────────────────────────────────────────────────────────
+
+/**
+ * Per-position exposure change on the Extended exchange.
+ * Positive delta = increase position size, negative = reduce.
+ */
+export interface ExtendedPositionDelta {
+  instrument: string;
+  delta: Web3Number;
+}
+
+/**
+ * Per-pool position change on Vesu.
+ * debtDelta: positive = borrow more, negative = repay.
+ * collateralDelta: positive = add collateral, negative = remove.
+ */
+export interface VesuPoolDelta {
+  poolId: ContractAddr;
+  collateralToken: TokenInfo;
+  debtToken: TokenInfo;
+  debtDelta: Web3Number;
+  collateralDelta: Web3Number;
+  collateralPrice: number;
+  debtPrice: number;
+}
+
+// ─── ExecutionRoute types ───────────────────────────────────────────────────────────────
+
+/**
+ * Enumerates all possible fund-routing paths used during execution.
+ */
+export enum RouteType {
+  /** P1: Deposit USDC.e from operator wallet directly to Extended exchange */
+  WALLET_TO_EXTENDED = 'WALLET_TO_EXTENDED',
+  /** P2: USDC from vault allocator → swap to USDC.e → deposit to Extended */
+  VA_TO_EXTENDED = 'VA_TO_EXTENDED',
+  /** Withdraw from Extended exchange → operator wallet */
+  EXTENDED_TO_WALLET = 'EXTENDED_TO_WALLET',
+  /** Swap USDC → BTC to deposit to Vesu */
+  AVNU_DEPOSIT_SWAP = 'AVNU_DEPOSIT_SWAP',
+  /** Increase leverage on Vesu i.e. deposit on vesu, borrow, in one go to create lever */
+  VESU_MULTIPLY_INCREASE_LEVER = 'VESU_MULTIPLY_INCREASE_LEVER',
+  /** Decrease leverage on Vesu i.e. withdraw from vesu, repay, in one go to reduce leverage */
+  VESU_MULTIPLY_DECREASE_LEVER = 'VESU_MULTIPLY_DECREASE_LEVER',
+  /** Swap BTC → USDC to withdraw from Vesu */
+  AVNU_WITHDRAW_SWAP = 'AVNU_WITHDRAW_SWAP',
+  /** Borrow additional USDC from Vesu (when wallet + VA insufficient for Extended) */
+  VESU_BORROW = 'VESU_BORROW',
+  /** Repay USDC debt to Vesu (debtDelta < 0) */
+  VESU_REPAY = 'VESU_REPAY',
+  /** Transfer USDC.e from operator wallet to vault allocator */
+  WALLET_TO_VA = 'WALLET_TO_VA',
+  /** Realize PnL on Extended exchange */
+  REALISE_PNL = 'REALISE_PNL',
+  /** Increase leverage on Extended exchange i.e. deposit on extended, in one go to create lever */
+  EXTENDED_INCREASE_LEVER = 'EXTENDED_INCREASE_LEVER',
+  /** Decrease leverage on Extended exchange i.e. withdraw from extended, in one go to reduce leverage */
+  EXTENDED_DECREASE_LEVER = 'EXTENDED_DECREASE_LEVER',
+
+  /** Increase leverage on Extended exchange to max leverage (e.g. 4x from 3x) */
+  CRISIS_INCREASE_EXTENDED_MAX_LEVERAGE = 'CRISIS_INCREASE_EXTENDER_MAX_LEVERAGE',
+  /** Undo max leverage on Extended exchange to reduce leverage (e.g. 4x to 3x) */
+  CRISIS_UNDO_EXTENDED_MAX_LEVERAGE = 'CRISIS_UNDO_EXTENDED_MAX_LEVERAGE',
+
+  /** Borrow beyyond target HF (e.g. 1.2 from 1.4) */
+  CRISIS_BORROW_BEYOND_TARGET_HF = 'CRISIS_BORROW_BEYOND_TARGET_HF',
+
+  /** Bring liquidity from vault allocator to vault contract (for user withdrawals) */
+  BRING_LIQUIDITY = 'BRING_LIQUIDITY',
+
+  // often a bridge tx is involved. when the solve cycle runs again
+  // bridges funds shall be handled again
+  RETURN_TO_WAIT = 'RETURN_TO_WAIT',
+}
+
+// ─── Per-route-type metadata ─────────────────────────────────────────────────
+
+/** Common fields shared by every route variant */
+interface RouteBase {
+  /** Execution order — lower values execute first */
+  priority: number;
+}
+
+/** Simple fund-transfer routes: WALLET_TO_EXTENDED, VA_TO_EXTENDED, EXTENDED_TO_WALLET, WALLET_TO_VA */
+export interface TransferRoute extends RouteBase {
+  type:
+  | RouteType.WALLET_TO_EXTENDED
+  | RouteType.VA_TO_EXTENDED
+  | RouteType.EXTENDED_TO_WALLET
+  | RouteType.WALLET_TO_VA;
+  /** Amount to transfer */
+  amount: Web3Number;
+}
+
+/** AVNU swap routes: AVNU_DEPOSIT_SWAP (USDC→BTC), AVNU_WITHDRAW_SWAP (BTC→USDC) */
+export interface SwapRoute extends RouteBase {
+  type: RouteType.AVNU_DEPOSIT_SWAP | RouteType.AVNU_WITHDRAW_SWAP;
+  /** Source token symbol */
+  fromToken: string;
+  /** Source amount */
+  fromAmount: Web3Number;
+  /** Destination token symbol */
+  toToken: string;
+  /** Exact output amount (if known; otherwise undefined means best-effort) */
+  toAmount?: Web3Number;
+}
+
+/** Vesu multiply lever routes: deposit+borrow or withdraw+repay in one go */
+export interface VesuMultiplyRoute extends RouteBase {
+  type: RouteType.VESU_MULTIPLY_INCREASE_LEVER | RouteType.VESU_MULTIPLY_DECREASE_LEVER;
+  /** Pool to interact with */
+  poolId: ContractAddr;
+  /** Collateral token info */
+  collateralToken: TokenInfo;
+  /** Collateral amount delta (positive = deposit, negative = withdraw) */
+  marginAmount: Web3Number; // in collateral token units
+  swappedCollateralAmount: Web3Number; // debt swapped, in collateral token units
+  /** Debt token info */
+  debtToken: TokenInfo;
+  /** Debt amount delta (positive = borrow, negative = repay) */
+  debtAmount: Web3Number;
+}
+
+/** Vesu single-side borrow / repay routes */
+export interface VesuDebtRoute extends RouteBase {
+  type: RouteType.VESU_BORROW | RouteType.VESU_REPAY;
+  /** Pool to interact with */
+  poolId: ContractAddr;
+  /** Amount to borrow (positive) or repay (negative) */
+  amount: Web3Number;
+  /** Collateral token info */
+  collateralToken: TokenInfo;
+  /** Debt token info */
+  debtToken: TokenInfo;
+}
+
+/** Realise PnL on Extended exchange */
+export interface RealisePnlRoute extends RouteBase {
+  type: RouteType.REALISE_PNL;
+  /** Amount of PnL to realise (the shortfall beyond available-to-withdraw) */
+  amount: Web3Number;
+  /** Extended instrument name (e.g. "BTC-USD") */
+  instrument: string;
+}
+
+/** Increase / decrease leverage on Extended exchange */
+export interface ExtendedLeverRoute extends RouteBase {
+  type: RouteType.EXTENDED_INCREASE_LEVER | RouteType.EXTENDED_DECREASE_LEVER;
+  /** Change in exposure denominated in the exposure token */
+  amount: Web3Number;
+  /** Extended instrument name (e.g. "BTC-USD") */
+  instrument: string;
+}
+
+/** Crisis: temporarily increase / undo max leverage on Extended — no args for now */
+export interface CrisisExtendedLeverRoute extends RouteBase {
+  type: RouteType.CRISIS_INCREASE_EXTENDED_MAX_LEVERAGE | RouteType.CRISIS_UNDO_EXTENDED_MAX_LEVERAGE;
+}
+
+/** Crisis: borrow beyond the normal target HF */
+export interface CrisisBorrowRoute extends RouteBase {
+  type: RouteType.CRISIS_BORROW_BEYOND_TARGET_HF;
+  /** Pool to borrow from */
+  poolId: ContractAddr;
+  /** Token being borrowed */
+  token: string;
+  /** Amount to borrow */
+  amount: Web3Number;
+}
+
+/** Bring liquidity from vault allocator to vault contract for user withdrawals */
+export interface BringLiquidityRoute extends RouteBase {
+  type: RouteType.BRING_LIQUIDITY;
+  /** Amount to bring */
+  amount: Web3Number;
+}
+
+/** Control routes: RETURN_TO_WAIT (stop execution, resume in next cycle) */
+export interface WaitRoute extends RouteBase {
+  type: RouteType.RETURN_TO_WAIT;
+}
+
+/**
+ * A single step in the execution plan produced by the solver.
+ * Discriminated union keyed on `type` — each variant carries only
+ * the metadata that specific route needs.
+ */
+export type ExecutionRoute =
+  | TransferRoute
+  | SwapRoute
+  | VesuMultiplyRoute
+  | VesuDebtRoute
+  | RealisePnlRoute
+  | ExtendedLeverRoute
+  | CrisisExtendedLeverRoute
+  | CrisisBorrowRoute
+  | BringLiquidityRoute
+  | WaitRoute;
+
+// ─── Case classification types ──────────────────────────────────────────────────
+
+/**
+ * Broad category of a detected case. Multiple categories may apply simultaneously.
+ */
+export enum CaseCategory {
+  LTV_REBALANCE = 'LTV_REBALANCE',
+  NEW_DEPOSITS = 'NEW_DEPOSITS',
+  WITHDRAWAL = 'WITHDRAWAL',
+  EXPOSURE_IMBALANCE = 'EXPOSURE_IMBALANCE',
+  MARGIN_CRISIS = 'MARGIN_CRISIS',
+}
+
+/**
+ * Specific case IDs corresponding to the situations defined in cases.json.
+ */
+export enum CaseId {
+  // LTV Rebalance
+  LTV_VESU_LOW_TO_EXTENDED = 'LTV_VESU_LOW_TO_EXTENDED',
+  LTV_EXTENDED_PROFITABLE_AVAILABLE = 'LTV_EXTENDED_PROFITABLE_AVAILABLE',
+  LTV_EXTENDED_PROFITABLE_REALIZE = 'LTV_EXTENDED_PROFITABLE_REALIZE',
+  LTV_VESU_HIGH_USE_VA_OR_WALLET = 'LTV_VESU_HIGH_USE_VA_OR_WALLET',
+  LTV_EXTENDED_HIGH_USE_VA_OR_WALLET = 'LTV_EXTENDED_HIGH_USE_VA_OR_WALLET',
+
+  // New Deposits / Excess Funds
+  DEPOSIT_FRESH_VAULT = 'DEPOSIT_FRESH_VAULT',
+  DEPOSIT_EXTENDED_AVAILABLE = 'DEPOSIT_EXTENDED_AVAILABLE',
+  DEPOSIT_VESU_BORROW_CAPACITY = 'DEPOSIT_VESU_BORROW_CAPACITY',
+  DEPOSIT_COMBINATION = 'DEPOSIT_COMBINATION',
+  // Withdrawal
+  WITHDRAWAL_SIMPLE = 'WITHDRAWAL_SIMPLE',
+  // Margin Crisis
+  MARGIN_CRISIS_EXTENDED = 'MARGIN_CRISIS_EXTENDED',
+  MARGIN_CRISIS_VESU = 'MARGIN_CRISIS_VESU',
+  // Exposure Imbalance
+  IMBALANCE_EXTENDED_EXCESS_SHORT_NO_FUNDS = 'IMBALANCE_EXTENDED_EXCESS_SHORT_NO_FUNDS',
+  IMBALANCE_EXTENDED_EXCESS_SHORT_HAS_FUNDS = 'IMBALANCE_EXTENDED_EXCESS_SHORT_HAS_FUNDS',
+  IMBALANCE_VESU_EXCESS_LONG_NO_FUNDS = 'IMBALANCE_VESU_EXCESS_LONG_NO_FUNDS',
+  IMBALANCE_VESU_EXCESS_LONG_HAS_FUNDS = 'IMBALANCE_VESU_EXCESS_LONG_HAS_FUNDS',
+}
+
+/**
+ * A detected case describing the current system state and the
+ * high-level steps required to resolve it.
+ */
+export interface SolveCase {
+  id: CaseId;
+  category: CaseCategory;
+  title: string;
+  description: string;
+  /** High-level steps describing what needs to happen for this case */
+  steps: string[];
+}
+
+/** Minimum USD amount to consider a case significant */
+const CASE_THRESHOLD_USD = 5;
+const CASE_MIN_BRIDING_USD = 10;
+/** Decimal places for rounding collateral / exposure deltas in token terms (e.g. BTC) */
+const COLLATERAL_PRECISION = 4;
+
+/** Safely create a Web3Number from a float, avoiding >15 significant digit errors */
+function safeUsdcWeb3Number(value: number): Web3Number {
+  return new Web3Number(value.toFixed(USDC_TOKEN_DECIMALS), USDC_TOKEN_DECIMALS);
+}
+
+/**
+ * A single detected case with its metadata, amounts, and the execution
+ * routes that belong to this case.
+ */
+export interface SolveCaseEntry {
+  case: SolveCase;
+  additionalArgs: { amount?: Web3Number };
+  routes: ExecutionRoute[];
+}
+
+/**
+ * Maps each CaseId to the RouteTypes that are relevant for resolving it.
+ * Used to filter the global route list into per-case route subsets.
+ */
+export const CASE_ROUTE_TYPES: Record<CaseId, RouteType[]> = {
+  // LTV Rebalance — Vesu side
+  [CaseId.LTV_VESU_HIGH_USE_VA_OR_WALLET]: [RouteType.WALLET_TO_VA, RouteType.VESU_REPAY], // use wallet to va if wallet has and va doesnt have enough
+  [CaseId.LTV_EXTENDED_PROFITABLE_AVAILABLE]: [RouteType.EXTENDED_TO_WALLET, RouteType.RETURN_TO_WAIT, RouteType.WALLET_TO_VA, RouteType.VESU_REPAY],
+  [CaseId.LTV_EXTENDED_PROFITABLE_REALIZE]: [RouteType.REALISE_PNL, RouteType.EXTENDED_TO_WALLET, RouteType.RETURN_TO_WAIT, RouteType.WALLET_TO_VA, RouteType.VESU_REPAY],
+  // LTV Rebalance — Extended side
+  [CaseId.LTV_EXTENDED_HIGH_USE_VA_OR_WALLET]: [RouteType.VA_TO_EXTENDED, RouteType.WALLET_TO_EXTENDED],
+  [CaseId.LTV_VESU_LOW_TO_EXTENDED]: [RouteType.VESU_BORROW, RouteType.VA_TO_EXTENDED],
+
+  // New Deposits
+  // @dev, when handling routes, after VA_TO_EXTENDED and/or WALLET_TO_EXTENDED, return. bcz, funds take time to reach extended. Anyways, in next cycle, these funds will be computed to increase lever
+  // Sequence: fund-movement transfers first (WALLET_TO_EXTENDED, VA_TO_EXTENDED, WALLET_TO_VA, EXTENDED_TO_WALLET),
+  //           then RETURN_TO_WAIT, then optional second WALLET_TO_VA + RETURN_TO_WAIT, then lever routes.
+  [CaseId.DEPOSIT_FRESH_VAULT]: [RouteType.WALLET_TO_EXTENDED, RouteType.VA_TO_EXTENDED, RouteType.WALLET_TO_VA, RouteType.EXTENDED_TO_WALLET, RouteType.RETURN_TO_WAIT, RouteType.WALLET_TO_VA, RouteType.AVNU_DEPOSIT_SWAP, RouteType.VESU_MULTIPLY_INCREASE_LEVER, RouteType.EXTENDED_INCREASE_LEVER],
+  [CaseId.DEPOSIT_EXTENDED_AVAILABLE]: [RouteType.EXTENDED_TO_WALLET, RouteType.RETURN_TO_WAIT, RouteType.WALLET_TO_VA, RouteType.AVNU_DEPOSIT_SWAP, RouteType.VESU_MULTIPLY_INCREASE_LEVER, RouteType.EXTENDED_INCREASE_LEVER],
+  [CaseId.DEPOSIT_VESU_BORROW_CAPACITY]: [RouteType.VESU_BORROW, RouteType.VA_TO_EXTENDED, RouteType.RETURN_TO_WAIT, RouteType.AVNU_DEPOSIT_SWAP, RouteType.VESU_MULTIPLY_INCREASE_LEVER, RouteType.EXTENDED_INCREASE_LEVER],
+  [CaseId.DEPOSIT_COMBINATION]: [], // exroutes to be computed on the fly based on above sub routes and where deposit is available
+  // Withdrawal
+  // Sequence: transfer out first (EXTENDED_TO_WALLET, RETURN_TO_WAIT, WALLET_TO_VA), then unwind lever, then BRING_LIQUIDITY
+  [CaseId.WITHDRAWAL_SIMPLE]: [RouteType.EXTENDED_TO_WALLET, RouteType.RETURN_TO_WAIT, RouteType.WALLET_TO_VA, RouteType.VESU_MULTIPLY_DECREASE_LEVER, RouteType.AVNU_WITHDRAW_SWAP, RouteType.EXTENDED_DECREASE_LEVER, RouteType.BRING_LIQUIDITY],
+
+  // Margin Crisis
+  // amounts must be chosen such that, when decresing lever, the LTV reached should be adequate, not high not low.
+  [CaseId.MARGIN_CRISIS_EXTENDED]: [RouteType.CRISIS_BORROW_BEYOND_TARGET_HF, RouteType.VA_TO_EXTENDED, RouteType.RETURN_TO_WAIT, RouteType.VESU_MULTIPLY_DECREASE_LEVER, RouteType.EXTENDED_DECREASE_LEVER, RouteType.CRISIS_UNDO_EXTENDED_MAX_LEVERAGE],
+  [CaseId.MARGIN_CRISIS_VESU]: [RouteType.CRISIS_INCREASE_EXTENDED_MAX_LEVERAGE, RouteType.EXTENDED_TO_WALLET, RouteType.WALLET_TO_VA, RouteType.VESU_MULTIPLY_DECREASE_LEVER, RouteType.EXTENDED_DECREASE_LEVER, RouteType.CRISIS_UNDO_EXTENDED_MAX_LEVERAGE],
+
+  // Exposure Imbalance
+  // try to use available funds in VA/Wallet to increase lever in vesu. if not possible, reduce lever on extended for remaining
+  [CaseId.IMBALANCE_EXTENDED_EXCESS_SHORT_HAS_FUNDS]: [RouteType.AVNU_DEPOSIT_SWAP, RouteType.VESU_MULTIPLY_INCREASE_LEVER, RouteType.EXTENDED_DECREASE_LEVER],
+
+  // no available funds in VA/Wallet to increase lever in vesu. reduce lever on extended for remaining
+  [CaseId.IMBALANCE_EXTENDED_EXCESS_SHORT_NO_FUNDS]: [RouteType.EXTENDED_DECREASE_LEVER],
+
+  // try to use available funds in VA/Wallet to increase lever in extended. if not possible, reduce lever on vesu for remaining
+  [CaseId.IMBALANCE_VESU_EXCESS_LONG_HAS_FUNDS]: [RouteType.VA_TO_EXTENDED, RouteType.WALLET_TO_EXTENDED, RouteType.RETURN_TO_WAIT, RouteType.EXTENDED_INCREASE_LEVER, RouteType.RETURN_TO_WAIT, RouteType.VESU_MULTIPLY_DECREASE_LEVER],
+
+  // no available funds in VA/Wallet to increase lever in extended. reduce lever on vesu for remaining
+  [CaseId.IMBALANCE_VESU_EXCESS_LONG_NO_FUNDS]: [RouteType.VESU_MULTIPLY_DECREASE_LEVER],
+};
+
+/** Minimum exposure imbalance fraction to flag an imbalance case */
+const IMBALANCE_THRESHOLD_FRACTION = 0.0002; // 0.02%
+
+/**
+ * Static case definitions derived from cases.json.
+ * Each entry maps a CaseId to its metadata and descriptive steps.
+ */
+const CASE_DEFINITIONS: Record<CaseId, SolveCase> = {
+  [CaseId.LTV_VESU_LOW_TO_EXTENDED]: {
+    id: CaseId.LTV_VESU_LOW_TO_EXTENDED,
+    category: CaseCategory.LTV_REBALANCE,
+    title: 'LTV Rebalance: Vesu Low LTV → Extended (No BTC Imbalance)',
+    description: 'Exposures are balanced on both sides, but Vesu has low LTV (can borrow more). Extended needs additional margin.',
+    steps: [
+      'Borrow additional USDC from Vesu (up to target LTV)',
+      'Vault → Extended: Deposit borrowed USDC as margin',
+    ],
+  },
+  [CaseId.LTV_EXTENDED_PROFITABLE_AVAILABLE]: {
+    id: CaseId.LTV_EXTENDED_PROFITABLE_AVAILABLE,
+    category: CaseCategory.LTV_REBALANCE,
+    title: 'LTV Rebalance: Extended Profitable → Vesu (Funds Available to Withdraw)',
+    description: 'Exposures balanced. Extended is profitable with sufficient available-to-withdraw funds. Vesu needs more collateral.',
+    steps: [
+      'Withdraw USDC from Extended to Wallet',
+      'Wallet → Vault: Transfer USDC',
+      'Vault → Vesu: Deposit USDC to repay',
+    ],
+  },
+  [CaseId.LTV_EXTENDED_PROFITABLE_REALIZE]: {
+    id: CaseId.LTV_EXTENDED_PROFITABLE_REALIZE,
+    category: CaseCategory.LTV_REBALANCE,
+    title: 'LTV Rebalance: Extended Profitable → Vesu (Need to Realize PnL)',
+    description: 'Exposures balanced. Extended is profitable but available-to-withdraw is insufficient. Unrealized PnL needs to be realized.',
+    steps: [
+      'Partially close short BTC position on Extended (realize PnL)',
+      'Immediately reopen short BTC position on Extended (maintain exposure)',
+      'Withdraw realized USDC from Extended to Wallet',
+      'Wallet → Vault: Transfer USDC',
+      'Vault → Vesu: Deposit USDC as collateral',
+    ],
+  },
+  [CaseId.LTV_VESU_HIGH_USE_VA_OR_WALLET]: {
+    id: CaseId.LTV_VESU_HIGH_USE_VA_OR_WALLET,
+    category: CaseCategory.LTV_REBALANCE,
+    title: 'LTV Rebalance: Vesu High LTV (Use VA or Wallet)',
+    description: 'Vesu has high LTV (can repay debt). funds available in VA and/or Wallet can be used to repay debt.',
+    steps: [
+      'Wallet → Vesu -> Vesu: Repay using USDC',
+    ],
+  },
+  [CaseId.LTV_EXTENDED_HIGH_USE_VA_OR_WALLET]: {
+    id: CaseId.LTV_EXTENDED_HIGH_USE_VA_OR_WALLET,
+    category: CaseCategory.LTV_REBALANCE,
+    title: 'LTV Rebalance: Extended High LTV (Use VA or Wallet)',
+    description: 'Extended has high LTV (can borrow more). funds available in VA and/or Wallet can be used to add margin',
+    steps: [
+      'VA or Wallet → Extended -> Extended: Borrow using USDC',
+    ],
+  },
+  [CaseId.DEPOSIT_FRESH_VAULT]: {
+    id: CaseId.DEPOSIT_FRESH_VAULT,
+    category: CaseCategory.NEW_DEPOSITS,
+    title: 'New Deposits/Excess Funds: Fresh USDC in Vault',
+    description: 'Fresh USDC deposits received in Vault contract.',
+    steps: [
+      'Unused funds in Vault or in Wallet',
+      'Calculate allocation amounts for Extended and Vesu',
+      'Vault and/or Wallet → Extended: Deposit allocated USDC',
+      'Once extended receives the funds, open short BTC position',
+      'Vault and/or Wallet → Vesu: Deposit allocated USDC, borrow USDC, open long BTC position',
+    ],
+  },
+  [CaseId.DEPOSIT_EXTENDED_AVAILABLE]: {
+    id: CaseId.DEPOSIT_EXTENDED_AVAILABLE,
+    category: CaseCategory.NEW_DEPOSITS,
+    title: 'New Deposits/Excess Funds: Available to Withdraw from Extended',
+    description: 'Extended has excess available-to-withdraw funds that can be deployed without LTV rebalancing or BTC imbalance concerns.',
+    steps: [
+      'Calculate position increase amounts for both protocols',
+      'Withdraw portion of funds from Extended to Wallet (if needed for Vesu). If part of the required funds are in unrealised PnL, convert to realised PnL.',
+      'Once wallet receives the funds, use available funds on Extended to increase short BTC position',
+      'Wallet → Vault → Vesu: Deposit USDC as collateral',
+      'Borrow USDC from Vesu, open additional long BTC position',
+    ],
+  },
+  [CaseId.DEPOSIT_VESU_BORROW_CAPACITY]: {
+    id: CaseId.DEPOSIT_VESU_BORROW_CAPACITY,
+    category: CaseCategory.NEW_DEPOSITS,
+    title: 'New Deposits/Excess Funds: Available Borrowing Capacity on Vesu',
+    description: 'Vesu has low LTV with excess borrowing capacity that can be deployed for position expansion.',
+    steps: [
+      'Borrow additional USDC from Vesu (within safe LTV limits)',
+      'Calculate allocation for position expansion',
+      'Deposit portion of funds on Extended',
+      'Once extended receives the funds, open short BTC position',
+      'Use portion to open additional long BTC position on Vesu',
+    ],
+  },
+  [CaseId.DEPOSIT_COMBINATION]: {
+    id: CaseId.DEPOSIT_COMBINATION,
+    category: CaseCategory.NEW_DEPOSITS,
+    title: 'New Deposits/Excess Funds: Combination case',
+    description: 'Combination of new deposits/excess funds on vault/extended/vesu.',
+    steps: [
+      'Optimally distribute funds from multiple sources and create new positions. Avoid unnecessary routes.',
+    ],
+  },
+  [CaseId.WITHDRAWAL_SIMPLE]: {
+    id: CaseId.WITHDRAWAL_SIMPLE,
+    category: CaseCategory.WITHDRAWAL,
+    title: 'User Withdrawal: Simple Position Reduction',
+    description: 'User requests withdrawal with sufficient available funds to close positions proportionally.',
+    steps: [
+      'First check if any available funds can be used to settle the withdrawal (vault, available to withdraw or borrowing from vesu)',
+      'If yes, do necessary transfers such that funds are available in vault',
+      'If not or if more required, calculate position sizes to close on both sides',
+      'Close long BTC position on Vesu (partially or fully)',
+      'Repay borrowed USDC on Vesu',
+      'Withdraw collateral from Vesu to Vault',
+      'Close short BTC position on Extended',
+      'Withdraw margin from Extended to Wallet',
+      'Wallet → Vault: Transfer USDC',
+      'Vault → User: Process withdrawal',
+    ],
+  },
+  [CaseId.MARGIN_CRISIS_EXTENDED]: {
+    id: CaseId.MARGIN_CRISIS_EXTENDED,
+    category: CaseCategory.MARGIN_CRISIS,
+    title: 'Margin Crisis: LTV rebalance requires more funds than available, margin required on Extended',
+    description: 'LTV rebalance requires more funds than available on vault/extended/vesu. Extended needs margin urgently.',
+    steps: [
+      'Calculate required position reduction in vesu and extended',
+      'Borrow more on vesu such that HF can go max up to 1.2',
+      'Use the borrowed funds to settle margin requirements on Extended (vault to extended)',
+      'Once funds reach on extended, close portion of long BTC position on Vesu',
+      'Convert BTC to USDC',
+      'Repay portion of borrowed USDC on Vesu such that HF can go back to target',
+      'Close corresponding short BTC position on Extended (match reduced exposure)',
+    ],
+  },
+  [CaseId.MARGIN_CRISIS_VESU]: {
+    id: CaseId.MARGIN_CRISIS_VESU,
+    category: CaseCategory.MARGIN_CRISIS,
+    title: 'Margin Crisis: LTV rebalance requires more funds than available, margin required on Vesu',
+    description: 'LTV rebalance requires more funds than available on vault/extended/vesu. Vesu needs margin urgently.',
+    steps: [
+      'Calculate required position reduction in extended',
+      'Update leverage to 4x and try to use available to withdraw funds on extended',
+      'Wait until funds reach on wallet',
+      'Close portion of short BTC position on Extended',
+      'Move wallet to vault and use the USDC to repay on vesu',
+      'Reduce long position to match the short position on extended',
+    ],
+  },
+  [CaseId.IMBALANCE_EXTENDED_EXCESS_SHORT_NO_FUNDS]: {
+    id: CaseId.IMBALANCE_EXTENDED_EXCESS_SHORT_NO_FUNDS,
+    category: CaseCategory.EXPOSURE_IMBALANCE,
+    title: 'BTC Imbalance: Extended Has Excess Short (No funds to match)',
+    description: 'Extended has more short BTC exposure than Vesu long. No funds available to increase Vesu long.',
+    steps: [
+      'Reduce short BTC position on Extended to match the long position on Vesu',
+    ],
+  },
+  [CaseId.IMBALANCE_EXTENDED_EXCESS_SHORT_HAS_FUNDS]: {
+    id: CaseId.IMBALANCE_EXTENDED_EXCESS_SHORT_HAS_FUNDS,
+    category: CaseCategory.EXPOSURE_IMBALANCE,
+    title: 'BTC Imbalance: Extended Has Excess Short (Vault/Wallet Has Funds)',
+    description: 'Extended has more short BTC exposure than Vesu long. Use available funds to increase long on Vesu.',
+    steps: [
+      'Use available funds to increase long on Vesu as much as possible',
+      'If still not matched, reduce short BTC position on Extended to match the long position on Vesu',
+    ],
+  },
+  [CaseId.IMBALANCE_VESU_EXCESS_LONG_NO_FUNDS]: {
+    id: CaseId.IMBALANCE_VESU_EXCESS_LONG_NO_FUNDS,
+    category: CaseCategory.EXPOSURE_IMBALANCE,
+    title: 'BTC Imbalance: Vesu Has Excess Long (No funds to match)',
+    description: 'Vesu has more long BTC exposure than Extended short. Extended does not have enough available to trade funds.',
+    steps: [
+      'Reduce long BTC position on Vesu to match the short position on Extended',
+    ],
+  },
+  [CaseId.IMBALANCE_VESU_EXCESS_LONG_HAS_FUNDS]: {
+    id: CaseId.IMBALANCE_VESU_EXCESS_LONG_HAS_FUNDS,
+    category: CaseCategory.EXPOSURE_IMBALANCE,
+    title: 'BTC Imbalance: Vesu Has Excess Long (Extended has funds)',
+    description: 'Vesu has more long BTC exposure than Extended short. Extended has available to trade funds to match.',
+    steps: [
+      'Use available funds to increase short on Extended as much as possible',
+      'If still not matched, reduce long BTC position on Vesu to match the short position on Extended',
+    ],
+  },
+};
+
+/**
+ * Complete output from the solver describing all needed state changes.
+ *
+ * - cases:                    detected cases describing the system state and needed actions.
+ * - extendedDeposit:          positive = deposit USDC into Extended, negative = withdraw.
+ * - extendedPositionDeltas:   per-instrument exposure changes (with instrument id).
+ * - vesuDeltas:               per-pool debt & collateral changes (with pool id and token pair).
+ * - vesuAllocationUsd:        USDC directed to Vesu side (negative = unwind from Vesu).
+ * - extendedAllocationUsd:    USDC directed to Extended side (negative = withdraw from Extended).
+ * - bringLiquidityAmount:     amount VA should send via bringLiquidity to the vault
+ *                             (= withdrawAmount input; 0 during investment cycles).
+ */
+export interface SolveResult {
+  /** Detected cases describing the current situation, amounts, and per-case routes */
+  cases: SolveCaseEntry[];
+  extendedDeposit: Web3Number;
+  extendedPositionDeltas: ExtendedPositionDelta[];
+  vesuDepositAmount: Web3Number;
+  vesuDeltas: VesuPoolDelta[];
+  vesuAllocationUsd: Web3Number;
+  extendedAllocationUsd: Web3Number;
+  bringLiquidityAmount: Web3Number;
+  /**
+   * Net pending deposit for Extended.
+   * Positive = deposit in transit (wallet → Extended), negative = withdrawal in transit.
+   * Used by ExecutionService to avoid double-sending transfers.
+   */
+  pendingDeposit: Web3Number;
+}
+
+// ─── Config ────────────────────────────────────────────────────────────────────
+
+export interface StateManagerConfig {
+  pricer: PricerBase;
+  networkConfig: IConfig;
+  vesuAdapters: VesuMultiplyAdapter[];
+  extendedAdapter: ExtendedAdapter;
+  vaultAllocator: ContractAddr;
+  walletAddress: string;
+  assetToken: TokenInfo;
+  /** USDC.e token for wallet balance checks during route computation */
+  usdceToken: TokenInfo;
+  /** Collateral token (e.g. WBTC) for wallet balance checks */
+  collateralToken: TokenInfo;
+  limitBalanceBufferFactor: number;
+}
+
+// ─── ExecutionRoute helpers ──────────────────────────────────────────────────────────────
+
+/**
+ * Returns a short human-readable summary of a route's key fields for logging.
+ */
+export function routeSummary(r: ExecutionRoute): string {
+  switch (r.type) {
+    case RouteType.WALLET_TO_EXTENDED:
+    case RouteType.VA_TO_EXTENDED:
+    case RouteType.EXTENDED_TO_WALLET:
+    case RouteType.WALLET_TO_VA:
+      return `${r.amount.toNumber()}`;
+    case RouteType.AVNU_DEPOSIT_SWAP:
+    case RouteType.AVNU_WITHDRAW_SWAP:
+      return `${r.fromAmount.toNumber()} ${r.fromToken}→${r.toToken}`;
+    case RouteType.VESU_MULTIPLY_INCREASE_LEVER:
+    case RouteType.VESU_MULTIPLY_DECREASE_LEVER:
+      return `coll=${r.marginAmount.toNumber()} [${r.marginAmount.decimals}] debt=${r.debtAmount.toNumber()} [${r.debtAmount.decimals}] (swapped ${r.swappedCollateralAmount.toNumber()} [${r.swappedCollateralAmount.decimals}]) pool=${r.poolId.shortString()}`;
+    case RouteType.VESU_BORROW:
+    case RouteType.VESU_REPAY:
+      return `${r.amount.toNumber()} ${r.debtToken.symbol} pool=${r.poolId.shortString()} [Collateral: ${r.collateralToken.symbol}]`;
+    case RouteType.REALISE_PNL:
+      return `${r.amount.toNumber()} ${r.instrument}`;
+    case RouteType.EXTENDED_INCREASE_LEVER:
+    case RouteType.EXTENDED_DECREASE_LEVER:
+      return `${r.amount.toNumber()} ${r.instrument}`;
+    case RouteType.CRISIS_INCREASE_EXTENDED_MAX_LEVERAGE:
+    case RouteType.CRISIS_UNDO_EXTENDED_MAX_LEVERAGE:
+      return '(no args)';
+    case RouteType.CRISIS_BORROW_BEYOND_TARGET_HF:
+      return `${r.amount.toNumber()} ${r.token} pool=${r.poolId.shortString()}`;
+    case RouteType.BRING_LIQUIDITY:
+      return `${r.amount.toNumber()}`;
+    case RouteType.RETURN_TO_WAIT:
+      return '(control)';
+    default:
+      return '';
+  }
+}
+
+// ─── Solve Budget ───────────────────────────────────────────────────────────────
+
+/**
+ * Single source of truth for all mutable state during a solve() call.
+ *
+ * Holds both the refreshed on-chain/off-chain state snapshots AND the
+ * budget-tracking values consumed by sub-classifiers.  Spend methods
+ * automatically keep `totalUnused` in sync.  State-mutation methods
+ * (`applyVesuDelta`, `applyExtendedExposureDelta`, `applyExtendedBalanceChange`)
+ * update the underlying snapshots so that downstream classifiers always
+ * see the most up-to-date picture.
+ */
+export class SolveBudget {
+  // ── Refreshed state (mutable during solve) ──────────────────────────
+  unusedBalance: TokenBalance[];
+  walletBalance: TokenBalance | null;
+  vaultBalance: TokenBalance | null;
+  extendedPositions: ExtendedPositionState[];
+  extendedBalance: ExtendedBalanceState | null;
+  vesuPoolStates: VesuPoolState[];
+  vesuPerPoolDebtDeltasToBorrow: Web3Number[];
+  shouldVesuRebalance: boolean[]; // should be same length as vesuPerPoolDebtDeltasToBorrow
+
+  // ── Budget tracking (populated by initBudget) ──────────────────────
+  private _vaUsd: number = 0;
+  private _walletUsd: number = 0;
+  private _extAvailWithdraw: number = 0;
+  private _extAvailUpnl: number = 0;
+  private _extAvailTrade: number = 0;
+  private _extPendingDeposit: number = 0;
+  private _vesuBorrowCapacity: number = 0;
+  private _totalUnused: number = 0;
+
+  constructor(state: {
+    limitBalanceBufferFactor: number;
+    unusedBalance: TokenBalance[];
+    walletBalance: TokenBalance | null;
+    vaultBalance: TokenBalance | null;
+    extendedPositions: ExtendedPositionState[];
+    extendedBalance: ExtendedBalanceState | null;
+    vesuPoolStates: VesuPoolState[];
+  }) {
+    const buffer = state.limitBalanceBufferFactor;
+    this.unusedBalance = state.unusedBalance.map((item) => {
+      return {
+        ...item,
+        amount: item.amount.multipliedBy(1 - buffer),
+        usdValue: item.usdValue * (1 - buffer),
+      };
+    });
+    this.walletBalance = state.walletBalance ? {
+      ...state.walletBalance,
+      amount: state.walletBalance.amount.multipliedBy(1 - buffer),
+      usdValue: state.walletBalance.usdValue * (1 - buffer),
+    } : null;
+    this.vaultBalance = state.vaultBalance ? {
+      ...state.vaultBalance,
+      amount: state.vaultBalance.amount.multipliedBy(1 - buffer),
+      usdValue: state.vaultBalance.usdValue * (1 - buffer),
+    } : null;
+    this.extendedPositions = state.extendedPositions;
+    this.extendedBalance = state.extendedBalance ? {
+      ...state.extendedBalance,
+      availableForTrade: state.extendedBalance.availableForTrade.multipliedBy(1 - buffer),
+      availableForWithdrawal: state.extendedBalance.availableForWithdrawal.multipliedBy(1 - buffer),
+      unrealisedPnl: state.extendedBalance.unrealisedPnl.multipliedBy(1 - buffer),
+      balance: state.extendedBalance.balance.multipliedBy(1 - buffer),
+    } : null;
+    this.vesuPoolStates = state.vesuPoolStates;
+    const vesuPerPoolDebtDeltasToBorrow = this._computeperPoolDebtDeltasToBorrow();
+    assert(vesuPerPoolDebtDeltasToBorrow.length === this.vesuPoolStates.length, 'vesuPerPoolDebtDeltasToBorrow length must match vesuPoolStates length');
+    this.vesuPerPoolDebtDeltasToBorrow = vesuPerPoolDebtDeltasToBorrow.map((item) => item.deltaDebt);
+    this.shouldVesuRebalance = vesuPerPoolDebtDeltasToBorrow.map((item) => item.shouldRebalance);
+  }
+
+  /**
+   * Initialise budget-tracking values from the current state snapshot.
+   * Must be called after state is populated and debt deltas are computed.
+   *
+   * Accounts for pendingDeposit:
+   * - pendingDeposit > 0: funds in transit TO Extended → increase effective Extended available-for-trade
+   * - pendingDeposit < 0: funds in transit FROM Extended → increase effective wallet balance
+   */
+  initBudget(): void {
+    const debtDeltaNum = this.vesuPerPoolDebtDeltasToBorrow.reduce((a, b) => a + b.toNumber(), 0);
+    let totalUnusedUsd = this.unusedBalance.reduce((a, b) => a + b.usdValue, 0);
+    if (debtDeltaNum > 0) totalUnusedUsd += debtDeltaNum;
+    const extAvailTrade = this.extendedBalance?.availableForTrade?.toNumber() ?? 0;
+    if (extAvailTrade > 0) totalUnusedUsd += extAvailTrade;
+    if (debtDeltaNum > 0) totalUnusedUsd += debtDeltaNum;
+
+    this._vaUsd = this.vaultBalance?.usdValue ?? 0;
+    this._walletUsd = this.walletBalance?.usdValue ?? 0;
+    this._extAvailWithdraw = this.extendedBalance?.availableForWithdrawal?.toNumber() ?? 0;
+    this._extAvailUpnl = this.extendedBalance?.unrealisedPnl?.toNumber() ?? 0;
+    this._extAvailTrade = extAvailTrade;
+    this._extPendingDeposit = this.extendedBalance?.pendingDeposit?.toNumber() ?? 0;
+    this._vesuBorrowCapacity = debtDeltaNum;
+    this._totalUnused = totalUnusedUsd;
+
+    // ! cannot assume like this. the assumpotion, raher is opposite. also, be
+    const pendingDeposit = this.extendedBalance?.pendingDeposit?.toNumber() ?? 0;
+    if (pendingDeposit > 0) {
+      this._extAvailTrade += pendingDeposit;
+      this._totalUnused += pendingDeposit;
+      logger.debug(`SolveBudget::initBudget pendingDeposit=${pendingDeposit} -> increased extAvailTrade`);
+    } else if (pendingDeposit < 0) {
+      const inTransit = Math.abs(pendingDeposit);
+      this._walletUsd += inTransit;
+      this._totalUnused += inTransit;
+      logger.debug(`SolveBudget::initBudget pendingDeposit=${pendingDeposit} -> increased walletUsd by ${inTransit}`);
+    }
+  }
+
+  // ── Read-only getters ────────────────────────────────────────────────
+
+  get vaUsd(): number { return this._vaUsd; }
+  get walletUsd(): number { return this._walletUsd; }
+  get vaWalletUsd(): number { return this._vaUsd + this._walletUsd; }
+  get extAvailWithdraw(): number { return this._extAvailWithdraw; }
+  get extAvailUpnl(): number { return this._extAvailUpnl; }
+  get extAvailTrade(): number { return this._extAvailTrade; }
+  get vesuBorrowCapacity(): number { return this._vesuBorrowCapacity; }
+  get totalUnused(): number { return this._totalUnused; }
+  get extPendingDeposit(): number { return this._extPendingDeposit; }
+
+  // ── Spend methods (return amount consumed, auto-decrement totalUnused) ─
+
+  spendVA(desired: number): number {
+    const used = Math.min(this._vaUsd, Math.max(0, desired));
+    this._vaUsd -= used;
+    this._totalUnused -= used;
+    logger.debug(`SolveBudget::spendVA used=${used}, vaUsd=${this._vaUsd}, totalUnused=${this._totalUnused}`);
+    return used;
+  }
+
+  addToVA(amount: number): void {
+    assert(amount >= 0, 'SolveBudget::addToVA amount must be positive');
+    this._vaUsd += amount;
+    this._totalUnused += amount;
+    logger.debug(`SolveBudget::addToVA amount=${amount}, vaUsd=${this._vaUsd}, totalUnused=${this._totalUnused}`);
+  }
+
+  spendWallet(desired: number): number {
+    const used = Math.min(this._walletUsd, Math.max(0, desired));
+    this._walletUsd -= used;
+    this._totalUnused -= used;
+    logger.debug(`SolveBudget::spendWallet used=${used}, walletUsd=${this._walletUsd}, totalUnused=${this._totalUnused}`);
+    return used;
+  }
+
+  addToWallet(amount: number): void {
+    assert(amount >= 0, 'SolveBudget::addToWallet amount must be positive');
+    this._walletUsd += amount;
+    this._totalUnused += amount;
+    logger.debug(`SolveBudget::addToWallet amount=${amount}, walletUsd=${this._walletUsd}, totalUnused=${this._totalUnused}`);
+  }
+
+  spendVAWallet(desired: number): number {
+    let remaining = Math.max(0, desired);
+    const vaSpent = this.spendVA(remaining);
+    remaining -= vaSpent;
+    const walletSpent = this.spendWallet(remaining);
+    return vaSpent + walletSpent;
+  }
+
+  private _updateExtAvailWithdraw(desired: number, isSpend: boolean): number {
+    let amount = desired;
+    assert(amount > 0, 'SolveBudget::_updateExtAvailWithdraw amount must be positive');
+    if (isSpend) {
+      amount = Math.min(this._extAvailWithdraw, Math.max(0, desired));
+      amount = -amount; // invert sign
+    }
+    this._extAvailWithdraw += amount;
+    this._totalUnused += amount;
+    this._extAvailTrade += amount;
+
+    // update extended balances
+    if (this.extendedBalance) {
+      this.extendedBalance.availableForWithdrawal = safeUsdcWeb3Number(this.extendedBalance.availableForWithdrawal.toNumber() + amount);
+      this.extendedBalance.availableForTrade = safeUsdcWeb3Number(this.extendedBalance.availableForTrade.toNumber() + amount);
+      this.extendedBalance.balance = safeUsdcWeb3Number(this.extendedBalance.balance.toNumber() + amount);
+      this.extendedBalance.equity = safeUsdcWeb3Number(this.extendedBalance.equity.toNumber() + amount);
+    }
+    logger.debug(`SolveBudget::updateExtAvailWithdraw amount=${amount}, extAvailWithdraw=${this._extAvailWithdraw}, totalUnused=${this._totalUnused}`);
+    return amount;
+  }
+
+  private _updateExtAvailUpnl(desired: number, isSpend: boolean): number {
+    let amount = desired;
+    assert(amount > 0, 'SolveBudget::_updateExtAvailUpnl amount must be positive');
+    if (isSpend) {
+      amount = Math.min(this._extAvailUpnl, Math.max(0, desired));
+      amount = -amount; // invert sign
+    }
+    this._extAvailUpnl += amount;
+    this._totalUnused += amount;
+
+    // update extended balances
+    if (this.extendedBalance) {
+      this.extendedBalance.unrealisedPnl = safeUsdcWeb3Number(this.extendedBalance.unrealisedPnl.toNumber() + amount);
+      this.extendedBalance.balance = safeUsdcWeb3Number(this.extendedBalance.balance.toNumber() + amount);
+      this.extendedBalance.equity = safeUsdcWeb3Number(this.extendedBalance.equity.toNumber() + amount);
+      this.extendedBalance.availableForTrade = safeUsdcWeb3Number(this.extendedBalance.availableForTrade.toNumber() + amount);
+    }
+    logger.debug(`SolveBudget::updateExtAvailUpnl amount=${amount}, extAvailUpnl=${this._extAvailUpnl}, totalUnused=${this._totalUnused}`);
+    return amount;
+  }
+
+  spendExtAvailTrade(desired: number): number {
+    const used = this._updateExtAvailWithdraw(desired, true);
+    const usedUpnl = this._updateExtAvailUpnl(desired, true);
+    logger.debug(`SolveBudget::updateExtAvailTrade amount=${used + usedUpnl}, extAvailTrade=${this._extAvailTrade}, totalUnused=${this._totalUnused}`);
+    return used + usedUpnl;
+  }
+
+  spendExtAvailUpnl(desired: number): number {
+    return this._updateExtAvailUpnl(desired, true);
+  }
+
+  addToExtAvailTrade(amount: number): void {
+    this._updateExtAvailWithdraw(amount, false);
+    logger.debug(`SolveBudget::addToExtAvailTrade amount=${amount}, extAvailTrade=${this._extAvailTrade}, totalUnused=${this._totalUnused}`);
+  }
+
+  spendVesuBorrowCapacity(desired: number): { used: number, spendsByPool: Omit<VesuDebtRoute, 'priority' | 'type'>[] } {
+    const used = Math.min(this._vesuBorrowCapacity, Math.max(0, desired));
+    this._vesuBorrowCapacity -= used;
+    // todo check this function is used correctly
+    this._totalUnused -= used; // we assume only borrowed till ideal LTV
+
+    let spendsByPool: Omit<VesuDebtRoute, 'priority' | 'type'>[] = [];
+    // reduce the debt delta for the pool
+    for (let index = 0; index < this.vesuPerPoolDebtDeltasToBorrow.length; index++) {
+      const d = this.vesuPerPoolDebtDeltasToBorrow[index];
+      if (d.toNumber() <= CASE_THRESHOLD_USD) continue;
+      const borrowed = Math.min(d.toNumber(), used);
+      this.vesuPerPoolDebtDeltasToBorrow[index] = d.minus(safeUsdcWeb3Number(borrowed));
+      this.vesuPoolStates[index].debtAmount = safeUsdcWeb3Number(this.vesuPoolStates[index].debtAmount.toNumber() + borrowed);
+      this.vesuPoolStates[index].debtUsdValue = this.vesuPoolStates[index].debtAmount.toNumber() * this.vesuPoolStates[index].debtPrice;
+      spendsByPool.push({ poolId: this.vesuPoolStates[index].poolId, amount: safeUsdcWeb3Number(borrowed), collateralToken: this.vesuPoolStates[index].collateralToken, debtToken: this.vesuPoolStates[index].debtToken });
+    }
+
+    logger.debug(`SolveBudget::spendVesuBorrowCapacity used=${used}, vesuBorrowCapacity=${this._vesuBorrowCapacity}, totalUnused=${this._totalUnused}`);
+    return { used, spendsByPool };
+  }
+
+  repayVesuBorrowCapacity(desired: number): { used: number, spendsByPool: Omit<VesuDebtRoute, 'priority' | 'type'>[] } {
+    assert(desired > 0, 'SolveBudget::repayVesuBorrowCapacity desired must be positive');
+    // const used = Math.min(this._vesuBorrowCapacity, Math.max(0, desired));
+    const used = desired;
+    // todo check this function is used correctly
+    this._vesuBorrowCapacity += used;
+    // wont increase total unused because we are repaying debt
+
+    const spendsByPool: Omit<VesuDebtRoute, 'priority' | 'type'>[] = [];
+    for (let index = 0; index < this.vesuPerPoolDebtDeltasToBorrow.length; index++) {
+      const d = this.vesuPerPoolDebtDeltasToBorrow[index];
+      if (d.toNumber() >= -CASE_THRESHOLD_USD) continue; // positive means, dont repay
+      const repaid = Math.min(Math.abs(d.toNumber()), used);
+      this.vesuPerPoolDebtDeltasToBorrow[index] = d.plus(safeUsdcWeb3Number(repaid));
+      this.vesuPoolStates[index].debtAmount = safeUsdcWeb3Number(this.vesuPoolStates[index].debtAmount.toNumber() - repaid);
+      spendsByPool.push({ poolId: this.vesuPoolStates[index].poolId, amount: safeUsdcWeb3Number(-repaid), collateralToken: this.vesuPoolStates[index].collateralToken, debtToken: this.vesuPoolStates[index].debtToken });
+    }
+
+    logger.debug(`SolveBudget::repayVesuBorrowCapacity used=${used}, vesuBorrowCapacity=${this._vesuBorrowCapacity}, totalUnused=${this._totalUnused}`);
+    return { used, spendsByPool };
+  }
+
+  // ── State mutation ──────────────────────────────────────────────────
+
+  /** Update a Vesu pool's collateral and debt after a lever / borrow / repay route. */
+  applyVesuDelta(poolId: ContractAddr, collToken: TokenInfo, debtToken: TokenInfo, collDelta: Web3Number, debtDelta: Web3Number): void {
+    const pool = this.vesuPoolStates.find(
+      (p) => p.poolId.toString() === poolId.toString() && p.collateralToken.symbol === collToken.symbol && p.debtToken.symbol === debtToken.symbol,
+    );
+    if (!pool) throw new Error(`SolveBudget::applyVesuDelta pool not found: poolId=${poolId.toString()}, collToken=${collToken.symbol}, debtToken=${debtToken.symbol}`);
+    pool.collateralAmount = new Web3Number(
+      pool.collateralAmount.plus(collDelta).toFixed(pool.collateralToken.decimals),
+      pool.collateralToken.decimals,
+    );
+    pool.collateralUsdValue = pool.collateralAmount.toNumber() * pool.collateralPrice;
+    pool.debtAmount = new Web3Number(
+      pool.debtAmount.plus(debtDelta).toFixed(pool.debtToken.decimals),
+      pool.debtToken.decimals,
+    );
+    pool.debtUsdValue = pool.debtAmount.toNumber() * pool.debtPrice;
+
+    // recompute per pool deltas here
+    const vesuPerPoolDebtDeltasToBorrow = this._computeperPoolDebtDeltasToBorrow();
+    this.vesuPerPoolDebtDeltasToBorrow = vesuPerPoolDebtDeltasToBorrow.map((item) => item.deltaDebt);
+    const sum = this.vesuPerPoolDebtDeltasToBorrow.reduce((a, b) => a.plus(b), new Web3Number(0, USDC_TOKEN_DECIMALS));
+    this._vesuBorrowCapacity = sum.toNumber();
+    this.shouldVesuRebalance = vesuPerPoolDebtDeltasToBorrow.map((item) => item.shouldRebalance);
+  }
+
+  /** Update an Extended position's size after a lever route. Creates the position if new. */
+  applyExtendedExposureDelta(instrument: string, sizeDelta: Web3Number): void {
+    const pos = this.extendedPositions.find((p) => p.instrument === instrument);
+    if (pos) {
+      pos.size = new Web3Number(pos.size.plus(sizeDelta).toFixed(8), 8);
+    } else if (sizeDelta.toNumber() !== 0) {
+      this.extendedPositions.push({
+        instrument,
+        side: 'SHORT',
+        size: sizeDelta,
+        valueUsd: new Web3Number(0, USDC_TOKEN_DECIMALS),
+        leverage: '0',
+      });
+    }
+  }
+
+
+  /**
+   * For each Vesu pool, computes the debt delta needed to bring the position
+   * back to the target health factor.
+   *
+   * Positive = can borrow more, negative = need to repay.
+   */
+  private _computeperPoolDebtDeltasToBorrow(): { deltaDebt: Web3Number, shouldRebalance: boolean }[] {
+    const output = this.vesuPoolStates.map((pool) =>
+      calculateDeltaDebtAmount(
+        pool.collateralAmount,
+        pool.debtAmount,
+        pool.debtPrice,
+        pool.collateralPrice,
+      ),
+    );
+
+    // assert al pools share same collateral and debt tokens
+    const collateralToken = this.vesuPoolStates[0].collateralToken;
+    const debtToken = this.vesuPoolStates[0].debtToken;
+    for (const pool of this.vesuPoolStates) {
+      if (pool.collateralToken.symbol !== collateralToken.symbol || pool.debtToken.symbol !== debtToken.symbol) {
+        // not yet handled in code with multiple pool types. will be handled in future.
+        throw new Error(`SolveBudget::_computeperPoolDebtDeltasToBorrow: All pools must share same collateral and debt tokens`);
+      }
+    }
+    return output;
+  }
+}
+
+// ─── State Manager ─────────────────────────────────────────────────────────────
+
+/**
+ * Reads all on-chain / off-chain state for the Extended + SVK + Vesu strategy,
+ * then solves for the optimal rebalancing deltas.
+ *
+ * Usage:
+ *   const manager = new ExtendedSVKVesuStateManager(config);
+ *   const result  = await manager.solve();
+ */
+export class ExtendedSVKVesuStateManager {
+  private readonly _config: StateManagerConfig;
+  private readonly _tag = "ExtendedSVKVesuStateManager";
+
+  /** Single mutable state holder — initialised by _refresh(), budget by initBudget(). */
+  private _budget!: SolveBudget;
+
+  constructor(config: StateManagerConfig) {
+    this._config = config;
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // Public API
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  /**
+   * Main entry point. Refreshes all state, then computes and returns
+   * the optimal deltas for rebalancing the strategy.
+   *
+   * @param withdrawAmount — amount (in vault asset, e.g. USDC) the user wants
+   *   to withdraw. When > 0 the solver shrinks protocol allocations so that the
+   *   vault allocator ends up with enough balance to execute bringLiquidity.
+   *   Pass 0 (default) for normal investment / rebalancing cycles.
+   */
+  async solve(
+    withdrawAmount: Web3Number = new Web3Number(0, USDC_TOKEN_DECIMALS),
+  ): Promise<SolveResult | null> {
+    await this._refresh();
+    if (Math.abs(this._budget.extPendingDeposit) > 0) {
+      logger.warn(`${this._tag}::solve extPendingDeposit=${this._budget.extPendingDeposit}`);
+      return null;
+    }
+    this._validateRefreshedState();
+
+    // // Step 1: For each Vesu pool, compute debt delta needed for LTV maintenance
+    // const perPoolDebtDeltasToBorrow = this._computeperPoolDebtDeltasToBorrow();
+
+    // // Step 2: Determine distributable capital after debt and withdrawal adjustments
+    // const distributableAmount = this._computeDistributableAmount(
+    //   perPoolDebtDeltasToBorrow,
+    //   withdrawAmount,
+    // );
+
+    // // Step 3: Split distributable capital between Vesu and Extended allocations
+    // const { vesuAllocationUsd, extendedAllocationUsd } =
+    //   this._computeAllocationSplit(distributableAmount, perPoolDebtDeltasToBorrow);
+
+    // // Step 4: Convert Vesu allocation to per-pool collateral deltas
+    // const vesuDeltas =
+    //   this._computePerPoolCollateralDeltas(vesuAllocationUsd, perPoolDebtDeltasToBorrow);
+
+    // // Step 5: Compute Extended position deltas for delta-neutral matching
+    // const extendedPositionDeltas =
+    //   this._computeExtendedPositionDeltas(vesuDeltas);
+    // console.log({ extendedPositionDeltas: extendedPositionDeltas.map((delta) => ({
+    //   instrument: delta.instrument,
+    //   delta: delta.delta.toNumber(),
+    // })) });
+
+    // // Step 6: Compute net deposit/withdrawal change for Extended platform
+    // const extendedDeposit =
+    //   this._computeExtendedDepositDelta(extendedAllocationUsd);
+    // console.log({ extendedDeposit: extendedDeposit.toNumber() });
+
+    // // Step 7: compute vesu deposit amount (i.e. collateral required to open position may be)
+    // const vesuDepositAmount =
+    //   this._computeVesuDepositAmount(vesuDeltas);
+
+    // // Step 7: Compute bringLiquidity amount (= withdrawAmount for the vault)
+    // const bringLiquidityAmount =
+    //   this._computeBringLiquidityAmount(withdrawAmount);
+    // console.log({ bringLiquidityAmount: bringLiquidityAmount.toNumber() });
+
+    // Step 8: Classify state into actionable cases — each case carries
+    //   its own routes with amounts and state info.
+    const cases = this._classifyCases(withdrawAmount);
+
+    const result: SolveResult = {
+      cases,
+      // ignore these fields for now. only cases are relevant.
+      extendedDeposit: safeUsdcWeb3Number(0),
+      extendedPositionDeltas: [],
+      vesuDepositAmount: safeUsdcWeb3Number(0),
+      vesuDeltas: [],
+      vesuAllocationUsd: safeUsdcWeb3Number(0),
+      extendedAllocationUsd: safeUsdcWeb3Number(0),
+      bringLiquidityAmount: safeUsdcWeb3Number(0),
+      pendingDeposit: this._budget.extendedBalance?.pendingDeposit ?? new Web3Number(0, USDC_TOKEN_DECIMALS),
+    };
+
+    this._logSolveResult(result);
+    return result;
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // Private — state refresh
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  /**
+   * Reads all on-chain and off-chain state in parallel and stores
+   * results in private instance variables.
+   */
+  private async _refresh(): Promise<void> {
+    logger.info(`${this._tag}::_refresh starting`);
+
+    const [
+      vaultAllocatorBalance,
+      walletBalance,
+      vesuPoolStates,
+      extendedBalance,
+      extendedPositions,
+    ] = await Promise.all([
+      this._fetchVaultAllocatorBalance(),
+      this._fetchWalletBalances(),
+      this._fetchAllVesuPoolStates(),
+      this._fetchExtendedBalance(),
+      this._fetchExtendedPositions(),
+    ]);
+
+    logger.verbose(`_refresh vaultAllocatorBalance: ${vaultAllocatorBalance.usdValue}, walletBalance: ${walletBalance.usdValue}`);
+    const unusedBalance = this._computeUnusedBalances(
+      vaultAllocatorBalance,
+      walletBalance,
+    );
+
+    this._budget = new SolveBudget({
+      limitBalanceBufferFactor: this._config.limitBalanceBufferFactor,
+      unusedBalance,
+      walletBalance,
+      vaultBalance: vaultAllocatorBalance,
+      extendedPositions,
+      extendedBalance,
+      vesuPoolStates,
+    });
+
+    const totalUnusedUsd = unusedBalance.reduce(
+      (acc, b) => acc + b.usdValue,
+      0,
+    );
+    logger.info(
+      `${this._tag}::_refresh completed — ` +
+      `unusedBalances: ${unusedBalance.length} tokens, ` +
+      `totalUnusedUsd: ${totalUnusedUsd.toFixed(2)}, ` +
+      `extendedPositions: ${extendedPositions.length}, ` +
+      `vesuPools: ${vesuPoolStates.length} - ` +
+      `availableForTrade: ${extendedBalance?.availableForTrade.toNumber()} - ` +
+      `availableForWithdrawal: ${extendedBalance?.availableForWithdrawal.toNumber()} - ` +
+      `unrealisedPnl: ${extendedBalance?.unrealisedPnl.toNumber()} - ` +
+      `extendedBalance::balance: ${extendedBalance?.balance.toNumber()} - ` +
+      `extendedBalance::pendingDeposit: ${extendedBalance?.pendingDeposit.toNumber()} - ` +
+      `extendedBalance::equity: ${extendedBalance?.equity.toNumber()}`,
+    );
+  }
+
+  // todo add communication check with python server of extended. if not working, throw error in solve function.
+
+  /**
+   * Reads the asset-token balance sitting idle in the vault allocator contract.
+   */
+  private async _fetchVaultAllocatorBalance(): Promise<TokenBalance> {
+    const { assetToken, vaultAllocator, networkConfig, pricer } = this._config;
+    const balance = await new ERC20(networkConfig).balanceOf(
+      assetToken.address,
+      vaultAllocator,
+      assetToken.decimals,
+    );
+    const price = await pricer.getPrice(assetToken.symbol);
+    const usdValue =
+      Number(balance.toFixed(assetToken.decimals)) * price.price;
+
+    return { token: assetToken, amount: balance, usdValue };
+  }
+
+  /**
+   * Merges the vault-allocator balance and wallet balances into a
+   * deduplicated array of TokenBalance entries keyed by token address.
+   *
+   * e.g. VA has USDC, wallet has USDC + USDC.e → returns
+   *   [{ token: USDC, amount: VA+wallet, usdValue: … },
+   *    { token: USDC.e, amount: wallet, usdValue: … }]
+   */
+  private _computeUnusedBalances(
+    vaultAllocatorBalance: TokenBalance,
+    walletBalance: TokenBalance,
+  ): TokenBalance[] {
+    const balanceMap = new Map<string, TokenBalance>();
+
+    // Seed with vault-allocator balance
+    balanceMap.set(vaultAllocatorBalance.token.address.toString(), {
+      token: vaultAllocatorBalance.token,
+      amount: vaultAllocatorBalance.amount,
+      usdValue: vaultAllocatorBalance.usdValue,
+    });
+
+    // Merge wallet balances by token address
+    const key = walletBalance.token.address.toString();
+    const existing = balanceMap.get(key);
+    if (existing) {
+      existing.amount = new Web3Number(
+        existing.amount.plus(walletBalance.amount).toFixed(existing.token.decimals),
+        existing.token.decimals,
+      );
+      existing.usdValue += walletBalance.usdValue;
+    } else {
+      balanceMap.set(key, {
+        token: walletBalance.token,
+        amount: walletBalance.amount,
+        usdValue: walletBalance.usdValue,
+      });
+    }
+
+    return Array.from(balanceMap.values());
+  }
+
+  /**
+   * Reads the operator wallet's balances for the asset token (USDC.e) and
+   * USDC.e (needed for route computation — P1 vs P2 decision for Extended deposits).
+   */
+  private async _fetchWalletBalances(): Promise<TokenBalance> {
+    const {
+      networkConfig,
+      pricer,
+      walletAddress,
+      assetToken,
+      usdceToken,
+    } = this._config;
+    const erc20 = new ERC20(networkConfig);
+
+    const [usdceBalance, usdcePrice] =
+      await Promise.all([
+        erc20.balanceOf(
+          usdceToken.address,
+          walletAddress,
+          usdceToken.decimals,
+        ),
+        pricer.getPrice(usdceToken.priceProxySymbol || usdceToken.symbol),
+      ]);
+
+    return {
+      token: usdceToken,
+      amount: usdceBalance,
+      usdValue:
+        Number(usdceBalance.toFixed(usdceToken.decimals)) * usdcePrice.price,
+    };
+  }
+
+  /**
+   * Reads the Extended exchange account-level balance (equity, available for
+   * trade/withdrawal, etc.). Returns null if the API call fails.
+   */
+  private async _fetchExtendedBalance(): Promise<ExtendedBalanceState | null> {
+    const [holdings, pendingDeposit] = await Promise.all([
+      this._config.extendedAdapter.getExtendedDepositAmount(),
+      this._fetchPendingDeposit(),
+    ]);
+    if (!holdings) return null;
+
+    return {
+      equity: new Web3Number(holdings.equity, USDC_TOKEN_DECIMALS),
+      availableForTrade: new Web3Number(
+        holdings.availableForTrade,
+        USDC_TOKEN_DECIMALS,
+      ),
+      availableForWithdrawal: new Web3Number(
+        holdings.availableForWithdrawal,
+        USDC_TOKEN_DECIMALS,
+      ),
+      unrealisedPnl: new Web3Number(holdings.unrealisedPnl, USDC_TOKEN_DECIMALS),
+      balance: new Web3Number(holdings.balance, USDC_TOKEN_DECIMALS),
+      pendingDeposit,
+    };
+  }
+
+  /**
+   * Computes the net pending deposit by subtracting pending withdrawals from
+   * pending deposits. Uses the Extended exchange asset operations API.
+   *
+   * Positive = deposit in transit (wallet → Extended).
+   * Negative = withdrawal in transit (Extended → wallet).
+   */
+  private async _fetchPendingDeposit(): Promise<Web3Number> {
+    try {
+      const client = this._config.extendedAdapter.client;
+      const [pendingDeposits, pendingWithdrawals] = await Promise.all([
+        client.getAssetOperations({
+          operationsType: [AssetOperationType.DEPOSIT],
+          operationsStatus: [AssetOperationStatus.IN_PROGRESS],
+        }),
+        client.getAssetOperations({
+          operationsType: [AssetOperationType.WITHDRAWAL],
+          operationsStatus: [AssetOperationStatus.IN_PROGRESS],
+        }),
+      ]);
+
+      const depositTotal = pendingDeposits.data.reduce(
+        (sum, op) => sum + parseFloat(op.amount || '0'), 0,
+      );
+      const withdrawTotal = pendingWithdrawals.data.reduce(
+        (sum, op) => sum + parseFloat(op.amount || '0'), 0,
+      );
+
+      const net = depositTotal - withdrawTotal;
+      logger.info(
+        `${this._tag}::_fetchPendingDeposit deposits=${depositTotal}, withdrawals=${withdrawTotal}, net=${net}`,
+      );
+      return new Web3Number(net.toFixed(USDC_TOKEN_DECIMALS), USDC_TOKEN_DECIMALS);
+    } catch (err) {
+      logger.error(`${this._tag}::_fetchPendingDeposit error: ${err}`);
+      return new Web3Number(0, USDC_TOKEN_DECIMALS);
+    }
+  }
+
+  /**
+   * Reads all open positions on the Extended exchange. Each position
+   * includes instrument, side, size, USD value, and leverage.
+   */
+  private async _fetchExtendedPositions(): Promise<ExtendedPositionState[]> {
+    const positions =
+      await this._config.extendedAdapter.getAllOpenPositions();
+    if (!positions) return [];
+
+    return positions.map((position) => ({
+      instrument: position.market,
+      side: position.side,
+      size: new Web3Number(position.size, USDC_TOKEN_DECIMALS), // though in different token terms, this wont matter from DEX perspective, hence 6decimals is ok
+      valueUsd: new Web3Number(position.value, USDC_TOKEN_DECIMALS),
+      leverage: position.leverage,
+    }));
+  }
+
+  /**
+   * Reads a single Vesu pool's position data: collateral amount/price,
+   * debt amount/price.
+   */
+  private async _fetchSingleVesuPoolState(
+    adapter: VesuMultiplyAdapter,
+  ): Promise<VesuPoolState> {
+    const assetPrices = await adapter._vesuAdapter.getAssetPrices();
+    return {
+      poolId: adapter.config.poolId,
+      collateralToken: adapter.config.collateral,
+      debtToken: adapter.config.debt,
+      collateralAmount: assetPrices.collateralTokenAmount,
+      collateralUsdValue: assetPrices.collateralUSDAmount,
+      debtAmount: assetPrices.debtTokenAmount,
+      debtUsdValue: assetPrices.debtUSDAmount,
+      collateralPrice: assetPrices.collateralPrice,
+      debtPrice: assetPrices.debtPrice,
+    };
+  }
+
+  /**
+   * Reads all Vesu pool states in parallel (one per configured adapter).
+   */
+  private async _fetchAllVesuPoolStates(): Promise<VesuPoolState[]> {
+    return Promise.all(
+      this._config.vesuAdapters.map((adapter) =>
+        this._fetchSingleVesuPoolState(adapter),
+      ),
+    );
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // Private — validation
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  /**
+   * Validates that all critical refreshed state is present and contains
+   * finite, sensible values. Throws on invalid state.
+   */
+  private _validateRefreshedState(): void {
+    if (this._budget.unusedBalance.length === 0) {
+      throw new Error(
+        `${this._tag}: unusedBalance is empty after refresh`,
+      );
+    }
+    for (const balance of this._budget.unusedBalance) {
+      this._validateTokenBalanceOrThrow(
+        balance,
+        `unusedBalance[${balance.token.symbol}]`,
+      );
+    }
+    this._validateVesuPoolPricesOrThrow();
+    this._validateExtendedBalanceOrThrow();
+  }
+
+  private _validateTokenBalanceOrThrow(
+    balance: TokenBalance | null,
+    label: string,
+  ): void {
+    if (!balance) {
+      throw new Error(`${this._tag}: ${label} is null after refresh`);
+    }
+    if (!Number.isFinite(balance.usdValue) || balance.usdValue < 0) {
+      throw new Error(
+        `${this._tag}: ${label} has invalid usdValue: ${balance.usdValue}`,
+      );
+    }
+  }
+
+  private _validateVesuPoolPricesOrThrow(): void {
+    for (const pool of this._budget.vesuPoolStates) {
+      const poolLabel = pool.poolId.shortString();
+      this._assertPositiveFinite(
+        pool.collateralPrice,
+        `Vesu pool ${poolLabel} collateralPrice`,
+      );
+      this._assertPositiveFinite(
+        pool.debtPrice,
+        `Vesu pool ${poolLabel} debtPrice`,
+      );
+    }
+  }
+
+  private _validateExtendedBalanceOrThrow(): void {
+    if (!this._budget.extendedBalance) return; // null is acceptable; treated as zero
+
+    const { equity, availableForTrade } = this._budget.extendedBalance;
+    if (
+      !Number.isFinite(equity.toNumber()) ||
+      !Number.isFinite(availableForTrade.toNumber())
+    ) {
+      throw new Error(
+        `${this._tag}: Extended balance contains non-finite values — ` +
+        `equity: ${equity.toNumber()}, availableForTrade: ${availableForTrade.toNumber()}`,
+      );
+    }
+  }
+
+  private _assertPositiveFinite(value: number, label: string): void {
+    if (!Number.isFinite(value) || value <= 0) {
+      throw new Error(
+        `${this._tag}: ${label} is invalid (${value}). Expected finite positive number.`,
+      );
+    }
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // Private — solve step 1: per-pool debt deltas (LTV maintenance)
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // Private — solve step 2: distributable amount
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  /**
+   * Computes total distributable capital by combining idle vault balance
+   * and Extended available balance, then adjusting for aggregate debt
+   * delta and any pending withdrawal.
+   *
+   * When withdrawAmount > 0 the distributable pool shrinks, forcing the
+   * allocation split to produce smaller (or negative) allocations — which
+   * in turn causes protocol positions to unwind and free capital for the
+   * vault allocator to execute bringLiquidity.
+   */
+  private _computeDistributableAmount(
+    perPoolDebtDeltasToBorrow: Web3Number[],
+    withdrawAmount: Web3Number,
+  ): Web3Number {
+    const totalInvestable = this._computeTotalInvestableAmount();
+    const aggregateDebtAdjustment = this._sumDebtDeltas(perPoolDebtDeltasToBorrow);
+    return new Web3Number(
+      totalInvestable
+        .plus(aggregateDebtAdjustment)
+        .minus(withdrawAmount)
+        .toFixed(USDC_TOKEN_DECIMALS),
+      USDC_TOKEN_DECIMALS,
+    );
+  }
+
+  /**
+   * Total investable = vault allocator balance + Extended available-for-trade,
+   * both reduced by the configured buffer percentage.
+   */
+  private _computeTotalInvestableAmount(): Web3Number {
+    const totalUnusedUsd = this._budget.unusedBalance.reduce(
+      (acc, b) => acc + b.usdValue,
+      0,
+    );
+    logger.debug(
+      `${this._tag}::_computeTotalInvestableAmount unusedBalances=` +
+      `${JSON.stringify(this._budget.unusedBalance.map((b) => ({ token: b.token.symbol, amount: b.amount.toNumber(), usdValue: b.usdValue })))}`,
+    );
+    const extendedAvailable =
+      this._budget.extendedBalance?.availableForTrade ??
+      new Web3Number(0, USDC_TOKEN_DECIMALS);
+    logger.verbose(`_computeTotalInvestableAmount totalUnusedUsd: ${totalUnusedUsd}, extendedAvailable: ${extendedAvailable.toNumber()}`);
+    return new Web3Number(totalUnusedUsd.toFixed(USDC_TOKEN_DECIMALS), USDC_TOKEN_DECIMALS)
+      .plus(extendedAvailable)
+  }
+
+  private _sumDebtDeltas(deltas: Web3Number[]): Web3Number {
+    return deltas.reduce(
+      (sum, delta) => sum.plus(delta),
+      new Web3Number(0, USDC_TOKEN_DECIMALS),
+    );
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // Private — solve step 3: allocation split
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  /**
+   * Splits distributable capital between Vesu and Extended using leverage
+   * ratios and existing exposure to match delta-neutral targets.
+   *
+   * Formula (from existing strategy):
+   *   ExtendedAlloc = (vL * distributable + vesuExposure - extendedExposure) / (vL + eL)
+   *   VesuAlloc     = distributable - ExtendedAlloc
+   */
+  private _computeAllocationSplit(distributableAmount: Web3Number, deltaVesuCollateral = 0, deltaExtendedCollateral = 0, isRecursive = false): {
+    vesuAllocationUsd: Web3Number;
+    extendedAllocationUsd: Web3Number;
+    vesuPositionDelta: number;
+    extendedPositionDelta: number;
+  } {
+    if (this._hasNoVesuAdapters()) {
+      throw new Error(`${this._tag}: No Vesu adapters found`);
+    }
+
+    const vesuLeverage = calculateVesuLeverage();
+    const extendedLeverage = calculateExtendedLevergae();
+    const denominator = vesuLeverage + extendedLeverage;
+
+    if (denominator === 0) {
+      throw new Error(`${this._tag}: Denominator is zero`);
+    }
+
+    // get long/short exposures on both sides
+    const collateralPrice = this._budget.vesuPoolStates[0]?.collateralPrice ?? 0;
+    const totalVesuExposureUsd = this._totalVesuCollateralUsd().plus(new Web3Number((deltaVesuCollateral * collateralPrice).toFixed(6), USDC_TOKEN_DECIMALS));
+    const totalExtendedExposureUsd = this._totalExtendedExposureUsd().plus(new Web3Number((deltaExtendedCollateral * collateralPrice).toFixed(6), USDC_TOKEN_DECIMALS));
+
+    const numerator =
+      vesuLeverage * distributableAmount.toNumber() +
+      totalVesuExposureUsd.toNumber() -
+      totalExtendedExposureUsd.toNumber();
+
+    const extendedAllocationUsd = new Web3Number(
+      (numerator / denominator).toFixed(USDC_TOKEN_DECIMALS),
+      USDC_TOKEN_DECIMALS,
+    );
+    let vesuAllocationUsd = new Web3Number(
+      distributableAmount
+        .minus(extendedAllocationUsd)
+        .toFixed(USDC_TOKEN_DECIMALS),
+      USDC_TOKEN_DECIMALS,
+    );
+
+    // add debt repayments to vesu allocation (-1 to convert to repay amount)
+    const perPoolDebtDeltasToBorrow = this._budget.vesuPerPoolDebtDeltasToBorrow;
+    vesuAllocationUsd = vesuAllocationUsd.plus(this._sumDebtDeltas(perPoolDebtDeltasToBorrow).multipliedBy(-1));
+
+    let vesuPositionDelta = Number((new Web3Number((vesuAllocationUsd.toNumber() * (vesuLeverage) / collateralPrice).toFixed(6), 6)).toFixedRoundDown(COLLATERAL_PRECISION));
+    let extendedPositionDelta = Number((new Web3Number((extendedAllocationUsd.toNumber() * (extendedLeverage) / collateralPrice).toFixed(6), 6)).toFixedRoundDown(COLLATERAL_PRECISION));
+
+    // for the first call, reconsider the newly created position delta to actually recompute the allocation split
+    if (!isRecursive) {
+      return this._computeAllocationSplit(distributableAmount, vesuPositionDelta, extendedPositionDelta, true);
+    }
+
+    // subtract any deltas passed
+    // throw new Error(`${this._tag}: Recursive allocation vesuPositionDelta: ${vesuPositionDelta}, extendedPositionDelta: ${extendedPositionDelta}, vesuAllocationUsd: ${vesuAllocationUsd.toNumber()}, extendedAllocationUsd: ${extendedAllocationUsd.toNumber()}`);
+    return { vesuAllocationUsd, extendedAllocationUsd, vesuPositionDelta, extendedPositionDelta };
+  }
+
+  private _hasNoVesuAdapters(): boolean {
+    return this._config.vesuAdapters.length === 0;
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // Private — solve step 4: per-pool collateral deltas
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  /**
+   * Distributes the total Vesu USD allocation across pools proportionally
+   * by existing collateral value, then converts each share to collateral
+   * token units.
+   */
+  private _computePerPoolCollateralDeltas(
+    vesuAllocationUsd: Web3Number, perPoolDebtDeltasToBorrow: Web3Number[]
+  ): VesuPoolDelta[] {
+    const vesuLeverage = calculateVesuLeverage();
+
+    // remove any repayments from the vesu allocation
+    const availableVesuCollateralAllocationUsd = vesuAllocationUsd.plus(this._sumDebtDeltas(perPoolDebtDeltasToBorrow));
+    const postLeverageAllocationUsd = availableVesuCollateralAllocationUsd.multipliedBy(vesuLeverage);
+    const totalCollateralExisting = this._totalVesuCollateral();
+
+    return this._budget.vesuPoolStates.map((pool, index) => {
+      const _postLeverageAllocation = postLeverageAllocationUsd.dividedBy(pool.collateralPrice);
+
+      const postLeverageAllocation = new Web3Number(((_postLeverageAllocation.plus(totalCollateralExisting)).toFixed(COLLATERAL_PRECISION)), pool.collateralToken.decimals).minus(totalCollateralExisting);
+      const _poolCollateralDelta = this._computePoolCollateralShare(
+        pool,
+        totalCollateralExisting,
+        postLeverageAllocation,
+      );
+      const poolCollateralDelta = new Web3Number(
+        _poolCollateralDelta.toFixed(COLLATERAL_PRECISION),
+        pool.collateralToken.decimals,
+      );
+
+      // the excess collateral should come from debt.
+      const newDebt = postLeverageAllocationUsd.minus(availableVesuCollateralAllocationUsd).dividedBy(pool.debtPrice);
+      return {
+        poolId: pool.poolId,
+        collateralToken: pool.collateralToken,
+        debtToken: pool.debtToken,
+        debtDelta: perPoolDebtDeltasToBorrow[index].plus(newDebt),
+        collateralDelta: poolCollateralDelta,
+        collateralPrice: pool.collateralPrice,
+        debtPrice: pool.debtPrice,
+      };
+    });
+  }
+
+  /**
+   * Determines how much of the total Vesu allocation goes to a single pool.
+   * Single-pool or zero-total cases get the entire allocation.
+   * Multi-pool cases split proportionally by current collateral USD value.
+   */
+  private _computePoolCollateralShare(
+    pool: VesuPoolState,
+    totalCollateral: Web3Number,
+    totalVesuAllocation: Web3Number,
+  ): Web3Number {
+    const isSinglePoolOrZeroTotal =
+      this._budget.vesuPoolStates.length === 1 ||
+      totalCollateral.toNumber() === 0;
+
+    if (isSinglePoolOrZeroTotal) return totalVesuAllocation;
+
+    const poolWeight = pool.collateralAmount.dividedBy(totalCollateral);
+
+    return new Web3Number(
+      totalVesuAllocation
+        .multipliedBy(poolWeight)
+        .toFixed(USDC_TOKEN_DECIMALS),
+      USDC_TOKEN_DECIMALS,
+    );
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // Private — solve step 6: extended position deltas
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  /**
+   * Computes per-position exposure deltas for delta neutrality.
+   * Target: total Extended short exposure = total projected Vesu collateral
+   * exposure (current + collateral deltas).
+   */
+  private _computeExtendedPositionDeltas(
+    vesuDeltas: VesuPoolDelta[],
+  ): ExtendedPositionDelta[] {
+    const targetExposure =
+      this._computeTargetExtendedExposure(vesuDeltas);
+    const currentExposure = this._totalExtendedExposure();
+    logger.debug(
+      `${this._tag}::_computeExtendedPositionDeltas targetExposure=${targetExposure.toNumber()}, currentExposure=${currentExposure.toNumber()}`,
+    );
+    const totalExposureDelta = new Web3Number(
+      targetExposure
+        .minus(currentExposure)
+        .toFixed(USDC_TOKEN_DECIMALS),
+      USDC_TOKEN_DECIMALS,
+    );
+
+    if (this._hasNoExtendedPositions()) {
+      return this._singleInstrumentDelta(totalExposureDelta);
+    }
+
+    return this._distributeExposureDeltaAcrossPositions(totalExposureDelta);
+  }
+
+  /**
+   * Target Extended exposure = sum of (current collateral + collateralDelta)
+   * * price, across all Vesu pools.
+   */
+  private _computeTargetExtendedExposure(
+    vesuDeltas: VesuPoolDelta[],
+  ): Web3Number {
+    let totalExposureCollateral = new Web3Number(0, USDC_TOKEN_DECIMALS); // just some decimals is ok
+
+    for (let i = 0; i < this._budget.vesuPoolStates.length; i++) {
+      const pool = this._budget.vesuPoolStates[i];
+      const delta = vesuDeltas[i];
+      logger.debug(
+        `${this._tag}::_computeTargetExtendedExposure poolId=${pool.poolId.toString()}, collateralAmount=${pool.collateralAmount.toNumber()}, collateralDelta=${delta.collateralDelta.toNumber()}`,
+      );
+      const projectedCollateral = pool.collateralAmount.plus(
+        delta.collateralDelta,
+      );
+      totalExposureCollateral = totalExposureCollateral.plus(
+        projectedCollateral,
+      );
+    }
+
+    return new Web3Number(
+      totalExposureCollateral.toFixed(USDC_TOKEN_DECIMALS),
+      USDC_TOKEN_DECIMALS,
+    );
+  }
+
+  private _hasNoExtendedPositions(): boolean {
+    return this._budget.extendedPositions.length === 0;
+  }
+
+  /**
+   * Creates a single-element delta array for the default instrument
+   * when no Extended positions currently exist.
+   */
+  private _singleInstrumentDelta(
+    delta: Web3Number,
+  ): ExtendedPositionDelta[] {
+    return [
+      {
+        instrument: this._config.extendedAdapter.config.extendedMarketName,
+        delta: new Web3Number(
+          delta.toFixed(COLLATERAL_PRECISION),
+          USDC_TOKEN_DECIMALS,
+        ),
+      },
+    ];
+  }
+
+  /**
+   * Distributes a total exposure delta proportionally across existing
+   * positions by their current USD value share.
+   */
+  private _distributeExposureDeltaAcrossPositions(
+    totalDelta: Web3Number,
+  ): ExtendedPositionDelta[] {
+    const totalExposure = this._totalExtendedExposure();
+
+    return this._budget.extendedPositions.map((position) => {
+      const share = this._positionExposureShareFraction(
+        position,
+        totalExposure,
+      );
+      return {
+        instrument: position.instrument,
+        delta: new Web3Number(
+          totalDelta.multipliedBy(share).toFixed(COLLATERAL_PRECISION),
+          USDC_TOKEN_DECIMALS,
+        ),
+      };
+    });
+  }
+
+  /**
+   * Returns the fraction (0–1) of total Extended exposure held by
+   * a single position. Returns 1 when there is only one position
+   * or when total exposure is zero.
+   */
+  private _positionExposureShareFraction(
+    position: ExtendedPositionState,
+    totalExposure: Web3Number,
+  ): number {
+    const isSingleOrZero =
+      totalExposure.toNumber() === 0 ||
+      this._budget.extendedPositions.length === 1;
+    if (isSingleOrZero) return 1;
+    return position.valueUsd.dividedBy(totalExposure).toNumber();
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // Private — solve step 7: extended deposit delta
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  /**
+   * Net deposit change = allocation target − currently available for trade.
+   * Positive = need to deposit more, negative = can withdraw excess.
+   */
+  private _computeExtendedDepositDelta(
+    extendedAllocationUsd: Web3Number,
+  ): Web3Number {
+    const currentAvailableForTrade =
+      this._budget.extendedBalance?.availableForTrade ??
+      new Web3Number(0, USDC_TOKEN_DECIMALS);
+
+    return new Web3Number(
+      extendedAllocationUsd
+        .minus(currentAvailableForTrade)
+        .toFixed(USDC_TOKEN_DECIMALS),
+      USDC_TOKEN_DECIMALS,
+    );
+  }
+
+  private _computeVesuDepositAmount(vesuDeltas: VesuPoolDelta[]): Web3Number {
+    let totalVesuCollateral = new Web3Number(0, USDC_TOKEN_DECIMALS); // just some decimals is ok
+    for (let i = 0; i < this._budget.vesuPoolStates.length; i++) {
+      const pool = this._budget.vesuPoolStates[i];
+      const delta = vesuDeltas[i];
+      totalVesuCollateral = totalVesuCollateral.plus(delta.collateralDelta.multipliedBy(pool.collateralPrice));
+      totalVesuCollateral = totalVesuCollateral.minus(delta.debtDelta.multipliedBy(pool.debtPrice));
+    }
+    return totalVesuCollateral;
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // Private — solve step 8: wallet delta
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  /**
+   * The wallet is a pass-through for USDC flows between the vault allocator
+   * and the Extended exchange.
+   *
+   * Positive = vault allocator → wallet → Extended (deposit)
+   * Negative = Extended → wallet → vault allocator (withdrawal)
+   */
+  private _deriveWalletDelta(extendedDeposit: Web3Number): Web3Number {
+    return extendedDeposit;
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // Private — solve step 9: bring liquidity
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  /**
+   * The bringLiquidity amount is the USDC that the vault allocator must
+   * transfer back to the vault contract for the user's withdrawal.
+   * Equals the withdrawAmount passed into solve(); 0 during investment cycles.
+   */
+  private _computeBringLiquidityAmount(
+    withdrawAmount: Web3Number,
+  ): Web3Number {
+    return withdrawAmount;
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // Private — case classification (modular)
+  //
+  // Cases are the source of truth. Each case carries its own routes
+  // with amounts and state info. There is no global routes array —
+  // consumers flatten case routes as needed.
+  // ═══════════════════════════════════════════════════════════════════════════
+
+
+  // ── ExecutionRoute-building helpers ─────────────────────────────────────────────
+
+  // ── Atomic route builders ────────────────────────────────────────────
+
+  private _buildVesuRepayRoutes(totalUsd: number, routes: ExecutionRoute[]): void {
+    const { used, spendsByPool } = this._budget.repayVesuBorrowCapacity(totalUsd);
+    for (const route of spendsByPool) {
+      routes.push({ type: RouteType.VESU_REPAY as const, ...route, priority: routes.length });
+    }
+
+    this._budget.spendVA(used);
+  }
+
+  private _buildVesuBorrowRoutes(totalUsd: number, routes: ExecutionRoute[]): { routes: ExecutionRoute[], remaining: number } {
+    let borrowable = this._budget.vesuBorrowCapacity;
+    if (totalUsd <= CASE_THRESHOLD_USD) return { routes, remaining: totalUsd };
+    if (borrowable <= CASE_THRESHOLD_USD) return { routes, remaining: totalUsd };
+
+    const { used, spendsByPool } = this._budget.spendVesuBorrowCapacity(totalUsd);
+    for (const route of spendsByPool) {
+      routes.push({ type: RouteType.VESU_BORROW as const, ...route, priority: routes.length });
+    }
+
+    this._budget.addToVA(used);
+    return { routes, remaining: totalUsd - used };
+  }
+
+  // private _buildExtendedDepositRoutes(totalUsd: number): TransferRoute[] {
+  //   const routes: TransferRoute[] = [];
+  //   let rem = totalUsd;
+  //   const walletBal = this._budget.walletBalance?.amount?.toNumber() ?? 0;
+  //   if (walletBal > 0 && rem > 0) {
+  //     const use = Math.min(walletBal, rem);
+  //     routes.push({ type: RouteType.WALLET_TO_EXTENDED, amount: safeUsdcWeb3Number(use), priority: routes.length });
+  //     this._budget.applyExtendedBalanceChange(use);
+  //     rem -= use;
+  //   }
+  //   if (rem > 0) {
+  //     routes.push({ type: RouteType.VA_TO_EXTENDED, amount: safeUsdcWeb3Number(rem), priority: routes.length });
+  //     this._budget.applyExtendedBalanceChange(rem);
+  //   }
+  //   return routes;
+  // }
+
+  // private _buildVesuIncreaseLeverRoutes(vesuDeltas: VesuPoolDelta[]): VesuMultiplyRoute[] {
+  //   return vesuDeltas
+  //     .filter((d) => d.collateralDelta.greaterThan(0))
+  //     .map((d) => {
+  //       this._budget.applyVesuDelta(d.poolId, d.collateralDelta, d.debtDelta);
+  //       return {
+  //         type: RouteType.VESU_MULTIPLY_INCREASE_LEVER as const,
+  //         poolId: d.poolId,
+  //         collateralToken: d.collateralToken,
+  //         collateralAmount: d.collateralDelta,
+  //         debtToken: d.debtToken,
+  //         debtAmount: d.debtDelta,
+  //         priority: 0,
+  //       };
+  //     });
+  // }
+
+  // private _buildVesuDecreaseLeverRoutes(vesuDeltas: Web3Number[]): VesuMultiplyRoute[] {
+  //   return vesuDeltas
+  //     .filter((d) => d.collateralDelta.isNegative())
+  //     .map((d) => {
+  //       this._budget.applyVesuDelta(d.poolId, d.collateralDelta, d.debtDelta);
+  //       return {
+  //         type: RouteType.VESU_MULTIPLY_DECREASE_LEVER as const,
+  //         poolId: d.poolId,
+  //         collateralToken: d.collateralToken,
+  //         collateralAmount: d.collateralDelta,
+  //         debtToken: d.debtToken,
+  //         debtAmount: d.debtDelta,
+  //         priority: 0,
+  //       };
+  //     });
+  // }
+
+  private _getWalletToVARoute(tryAmount: number, routes: ExecutionRoute[]): { routes: ExecutionRoute[], remaining: number } {
+    const usableAmount = Math.min(tryAmount, this._budget.walletUsd);
+    if (usableAmount > CASE_THRESHOLD_USD) {
+      const walletUsed = this._budget.spendWallet(usableAmount);
+      this._budget.addToVA(walletUsed);
+      const route: TransferRoute = { type: RouteType.WALLET_TO_VA, amount: safeUsdcWeb3Number(walletUsed), priority: routes.length };
+      routes.push(route);
+      return { routes, remaining: tryAmount - walletUsed };
+    }
+    return { routes, remaining: tryAmount };
+  }
+
+  private _getWalletToEXTENDEDRoute(tryAmount: number, routes: ExecutionRoute[], shouldAddWaitRoute = true): { routes: ExecutionRoute[], remaining: number } {
+    const usableAmount = Math.min(tryAmount, this._budget.walletUsd);
+    if (usableAmount > CASE_THRESHOLD_USD) {
+      const walletUsed = this._budget.spendWallet(usableAmount);
+      this._budget.addToExtAvailTrade(walletUsed);
+      routes.push({ type: RouteType.WALLET_TO_EXTENDED, amount: safeUsdcWeb3Number(walletUsed), priority: routes.length } as TransferRoute);
+
+      if (shouldAddWaitRoute) {
+        routes.push({ type: RouteType.RETURN_TO_WAIT, priority: routes.length });
+      }
+      return { routes, remaining: tryAmount - walletUsed };
+    }
+    return { routes, remaining: tryAmount };
+  }
+
+  private _getVAToEXTENDEDRoute(tryAmount: number, routes: ExecutionRoute[], shouldAddWaitRoute = true): { routes: ExecutionRoute[], remaining: number } {
+    const usableAmount = Math.min(tryAmount, this._budget.vaUsd);
+    if (usableAmount > CASE_THRESHOLD_USD) {
+      const vaUsed = this._budget.spendVA(usableAmount);
+      this._budget.addToExtAvailTrade(vaUsed);
+
+      // add extended deposit route
+      const route: TransferRoute = { type: RouteType.VA_TO_EXTENDED, amount: safeUsdcWeb3Number(vaUsed), priority: routes.length };
+      routes.push(route);
+
+      // should follow up by a returning to wait route
+      if (shouldAddWaitRoute) {
+        routes.push({ type: RouteType.RETURN_TO_WAIT, priority: routes.length });
+      }
+      return { routes, remaining: tryAmount - vaUsed };
+    }
+    return { routes, remaining: tryAmount };
+  }
+
+  private _getExtendedToWalletRoute(tryAmount: number, routes: ExecutionRoute[], shouldAddWaitRoute = true): { routes: ExecutionRoute[], remaining: number } {
+    if (tryAmount <= CASE_THRESHOLD_USD) return { routes, remaining: tryAmount };
+    assert(tryAmount <= this._budget.extAvailWithdraw, `tryAmount is greater than extAvailTrade, tryAmount: ${tryAmount}, extAvailWithdraw: ${this._budget.extAvailWithdraw}`);
+    const extWithdrawUsed = this._budget.spendExtAvailTrade(tryAmount);
+    this._budget.addToWallet(Math.abs(extWithdrawUsed));
+    const route: TransferRoute = { type: RouteType.EXTENDED_TO_WALLET, amount: safeUsdcWeb3Number(Math.abs(extWithdrawUsed)), priority: routes.length };
+    routes.push(route);
+
+    if (shouldAddWaitRoute) {
+      routes.push({ type: RouteType.RETURN_TO_WAIT, priority: routes.length });
+    }
+    return { routes, remaining: tryAmount - Math.abs(extWithdrawUsed) };
+  }
+
+  private _getWALLETToVARoute(tryAmount: number, routes: ExecutionRoute[]): { routes: ExecutionRoute[], remaining: number } {
+    if (tryAmount <= CASE_THRESHOLD_USD) return { routes, remaining: tryAmount };
+    const usableAmount = Math.min(tryAmount, this._budget.walletUsd);
+    if (usableAmount <= CASE_THRESHOLD_USD) return { routes, remaining: tryAmount };
+    // assert(tryAmount <= this._budget.walletUsd, `tryAmount is greater than walletUsd, tryAmount: ${tryAmount}, walletUsd: ${this._budget.walletUsd}`);
+    const walletUsed = this._budget.spendWallet(tryAmount);
+    this._budget.addToVA(walletUsed);
+    const route: TransferRoute = { type: RouteType.WALLET_TO_VA, amount: safeUsdcWeb3Number(walletUsed), priority: routes.length };
+    routes.push(route);
+    return { routes, remaining: tryAmount - walletUsed };
+  }
+
+  private _getUpnlRoute(tryAmount: number, routes: ExecutionRoute[]): { routes: ExecutionRoute[], remaining: number } {
+    const upnl = this._budget.extendedBalance?.unrealisedPnl?.toNumber() ?? 0;
+    const usableAmount = Math.min(tryAmount, upnl);
+    if (usableAmount <= CASE_THRESHOLD_USD) return { routes, remaining: tryAmount };
+
+    // if fails, ensure there is a way to choose the positio to use to create realised pnl
+    // until then, only 1 position is supported
+    const upnlUsed = this._budget.spendExtAvailUpnl(usableAmount); // removes from upnl
+    this._budget.addToExtAvailTrade(upnlUsed); // adds to available-for-withdrawal
+    assert(this._budget.extendedPositions.length == 1, 'SolveBudget::_getUpnlRoute: extendedPositions length must be 1');
+    routes.push({
+      type: RouteType.REALISE_PNL,
+      amount: safeUsdcWeb3Number(upnlUsed),
+      instrument: this._budget.extendedPositions[0].instrument,
+      priority: routes.length,
+    } as RealisePnlRoute);
+    return { routes, remaining: tryAmount - upnlUsed };
+  }
+
+  // ── Sub-classifiers ────────────────────────────────────────────────────
+  // Each sub-classifier builds routes directly from contextual data.
+
+  /**
+  * 1. Withdrawal — source funds in priority order:
+  *    1) VA balance  2) Wallet  3) Vesu borrow capacity
+  *    4) Extended available-for-withdrawal + unrealised PnL
+  *    5) Unwind positions on both sides (freed funds handled next cycle)
+  */
+  private _classifyWithdrawal(
+    withdrawAmount: Web3Number
+  ): SolveCaseEntry[] {
+    if (!withdrawAmount.greaterThan(CASE_THRESHOLD_USD)) return [];
+
+    const instrument = this._config.extendedAdapter.config.extendedMarketName ?? 'BTC-USD';
+    const routes: ExecutionRoute[] = [];
+    let remaining = withdrawAmount.toNumber();
+
+    // ── Step 1: VA balance ────────────────────────────────────────────────
+    // VA funds are already in the vault allocator — no transfer route needed.
+    const vaUsed = this._budget.spendVA(Math.min(this._budget.vaUsd, remaining));
+    remaining -= vaUsed;
+
+    let totalExtUsed = 0;
+
+    // ── Step 2: Wallet balance → VA ──────────────────────────────────────
+    if (remaining > CASE_THRESHOLD_USD) {
+      const { remaining: walletToVaRemaining } = this._getWALLETToVARoute(remaining, routes);
+      remaining = walletToVaRemaining;
+    }
+
+    // ── Step 3: Borrow from Vesu (positive debt delta = borrowable) ──────
+    if (remaining > CASE_THRESHOLD_USD) {
+      const { remaining: borrowRemaining } = this._buildVesuBorrowRoutes(remaining, routes);
+      remaining = borrowRemaining;
+    }
+
+    // ── Step 4: Extended available-for-withdrawal, then unrealised PnL ───
+    if (remaining > CASE_THRESHOLD_USD) {
+      const usableWithrawAmount = Math.min(remaining, this._budget.extAvailWithdraw);
+      remaining -= usableWithrawAmount;
+
+      let upnlUsed = 0;
+      if (remaining > CASE_THRESHOLD_USD) {
+        const { remaining: upnlRemaining } = this._getUpnlRoute(remaining, routes);
+        upnlUsed = remaining - upnlRemaining;
+        remaining = upnlRemaining;
+      }
+
+      // keep track of total extended used
+      totalExtUsed = usableWithrawAmount + upnlUsed;
+    }
+
+    // ── Step 5: Unwind positions on both sides ───────────────────────────
+    // Decrease Vesu lever + Extended exposure by equal BTC amounts to
+    // maintain delta neutrality. Freed funds are picked up next cycle.
+    if (remaining > CASE_THRESHOLD_USD) {
+      const avgCollPrice = this._budget.vesuPoolStates[0]?.collateralPrice ?? 1;
+      assert(this._budget.vesuPoolStates.length == 1, 'SolveBudget::_classifyWithdrawal: vesuPoolStates length must be 1');
+      // below function doesnt handle multiple pools yet
+      const { vesuPositionDelta, extendedPositionDelta, vesuAllocationUsd, extendedAllocationUsd } = this._computeAllocationSplit(new Web3Number((-remaining).toFixed(6), USDC_TOKEN_DECIMALS));
+
+      if (vesuPositionDelta < 0) {
+        const vesuAdapter = this._config.vesuAdapters[0];
+        const debtDelta = Math.min(0, vesuPositionDelta * avgCollPrice - vesuAllocationUsd.toNumber());
+        const withdrawAmount = vesuAllocationUsd.dividedBy(avgCollPrice);
+        withdrawAmount.decimals = vesuAdapter.config.collateral.decimals;
+        routes.push({
+          type: RouteType.VESU_MULTIPLY_DECREASE_LEVER,
+          poolId: vesuAdapter.config.poolId,
+          collateralToken: vesuAdapter.config.collateral,
+          marginAmount: withdrawAmount,
+          swappedCollateralAmount: (new Web3Number(vesuPositionDelta, vesuAdapter.config.collateral.decimals)).minus(withdrawAmount),
+          debtToken: vesuAdapter.config.debt,
+          debtAmount: new Web3Number(debtDelta, USDC_TOKEN_DECIMALS),
+          priority: routes.length,
+        } as VesuMultiplyRoute);
+        this._budget.applyVesuDelta(vesuAdapter.config.poolId, vesuAdapter.config.collateral, vesuAdapter.config.debt, new Web3Number(vesuPositionDelta, USDC_TOKEN_DECIMALS), new Web3Number(debtDelta, USDC_TOKEN_DECIMALS));
+
+        // Swap freed BTC → USDC (exact amount determined at runtime)
+        if (vesuAllocationUsd.toNumber() < -CASE_THRESHOLD_USD) {
+          const swapAmount = new Web3Number(((vesuAllocationUsd.toNumber() / avgCollPrice) * 0.998).toFixed(6), USDC_TOKEN_DECIMALS);
+          routes.push({
+            type: RouteType.AVNU_WITHDRAW_SWAP,
+            fromToken: vesuAdapter.config.collateral.symbol,
+            // add buffer to avoid rounding errors
+            fromAmount: swapAmount,
+            toToken: vesuAdapter.config.debt.symbol,
+            priority: routes.length,
+          } as SwapRoute);
+          this._budget.addToVA(vesuAllocationUsd.abs().toNumber());
+        }
+      }
+
+
+      if (extendedPositionDelta < 0) {
+        // Decrease Extended exposure by the same BTC amount
+        routes.push({
+          type: RouteType.EXTENDED_DECREASE_LEVER,
+          amount: safeUsdcWeb3Number(extendedPositionDelta),
+          instrument,
+          priority: routes.length,
+        });
+        this._budget.applyExtendedExposureDelta(instrument, safeUsdcWeb3Number(extendedPositionDelta));
+        this._budget.addToExtAvailTrade(extendedAllocationUsd.abs().toNumber());
+        totalExtUsed += extendedAllocationUsd.abs().toNumber();
+      }
+    }
+
+    if (totalExtUsed > CASE_THRESHOLD_USD) {
+      this._getExtendedToWalletRoute(totalExtUsed, routes);
+      this._getWALLETToVARoute(totalExtUsed, routes);
+    }
+
+    // ── Bring liquidity for whatever was sourced in steps 1-4 ────────────
+    routes.push({
+      type: RouteType.BRING_LIQUIDITY,
+      amount: withdrawAmount,
+      priority: routes.length,
+    });
+    this._budget.spendVA(withdrawAmount.toNumber() - vaUsed);
+
+    routes.forEach((r, i) => { r.priority = i; });
+
+    return [{
+      case: CASE_DEFINITIONS[CaseId.WITHDRAWAL_SIMPLE],
+      additionalArgs: { amount: withdrawAmount },
+      routes,
+    }];
+  }
+
+  /**
+   * 2a. LTV Rebalance — Vesu side
+   *
+   * Triggered when vesuPerPoolDebtDeltasToBorrow sum is negative (high LTV, needs repayment).
+   * Sources funds to VA so the subsequent deposit classifier can build the correct lever routes.
+   *
+   * Priority: 1) VA + Wallet (no routes)  2) Extended available-for-withdrawal
+   *           3) Extended uPnL  4) Margin crisis (future)
+   *
+   * Design: accumulate all ext-to-wallet moves, add transfer routes at the end (principle #3).
+   */
+  private _classifyLtvVesu(): SolveCaseEntry[] {
+    const debtDeltaSum = this._budget.vesuPerPoolDebtDeltasToBorrow.reduce(
+      (a, b) => a + b.toNumber(), 0,
+    );
+    logger.info(`${this._tag}::_classifyLtvVesu debtDeltaSum: ${debtDeltaSum}`);
+
+    // todo, even if sum is positive, but in a multi-pool situation,
+    // even if one bad, its problem. need to handle this.
+    const allHealthLTVs = this._budget.shouldVesuRebalance.every(shouldReb => !shouldReb)
+    if (debtDeltaSum >= -CASE_THRESHOLD_USD || allHealthLTVs) return [];
+
+    const needed = Math.abs(debtDeltaSum);
+    const routes: ExecutionRoute[] = [];
+    let remaining = needed;
+    let totalExtUsed = 0;
+    let caseId: CaseId = CaseId.LTV_VESU_HIGH_USE_VA_OR_WALLET;
+
+    // ── Step 1: VA + Wallet balance ─────────────────────────────────────
+    // VA funds already in VA — no transfer route needed.
+    const vaUsed = this._budget.spendVA(Math.min(this._budget.vaUsd, remaining));
+    remaining -= vaUsed;
+
+    // ── Step 2: Wallet balance → VA ──────────────────────────────────────
+    if (remaining > CASE_THRESHOLD_USD) {
+      const { remaining: walletToVaRemaining } = this._getWALLETToVARoute(remaining, routes);
+      remaining = walletToVaRemaining;
+    }
+
+    // ── Step 3: Extended available-for-withdrawal, then uPnL ────────────
+    if (remaining > CASE_THRESHOLD_USD) {
+      const usableWithdrawAmount = Math.min(remaining, this._budget.extAvailWithdraw);
+      remaining -= usableWithdrawAmount;
+
+      let upnlUsed = 0;
+      if (remaining > CASE_THRESHOLD_USD) {
+        const { remaining: upnlRemaining } = this._getUpnlRoute(remaining, routes);
+        upnlUsed = remaining - upnlRemaining;
+        remaining = upnlRemaining;
+        caseId = CaseId.LTV_EXTENDED_PROFITABLE_REALIZE;
+      } else {
+        caseId = CaseId.LTV_EXTENDED_PROFITABLE_AVAILABLE;
+      }
+
+      totalExtUsed = usableWithdrawAmount + upnlUsed;
+    }
+
+    if (remaining > CASE_THRESHOLD_USD) {
+      throw new Error(`${this._tag}: Insufficient funds to cover margin needs`);
+    }
+
+    // ── Deferred: Extended→Wallet + Wallet→VA ───────────────────────────
+    if (totalExtUsed > CASE_THRESHOLD_USD) {
+      this._getExtendedToWalletRoute(totalExtUsed, routes);
+      this._getWALLETToVARoute(totalExtUsed, routes);
+    }
+
+    // add routes linked to VESU repay
+    this._buildVesuRepayRoutes(needed - remaining, routes);
+
+    routes.forEach((r, i) => { r.priority = i; });
+
+    return [{
+      case: CASE_DEFINITIONS[caseId],
+      additionalArgs: { amount: safeUsdcWeb3Number(needed) },
+      routes,
+    }];
+  }
+
+  // ── LTV Vesu route builders ───────────────────────────────────────────
+
+  /**
+   * LTV_EXTENDED_PROFITABLE_AVAILABLE:
+   * Extended has enough available-to-withdraw → withdraw, move to VA, repay Vesu.
+   * Routes: [EXTENDED_TO_WALLET, WALLET_TO_VA, VESU_REPAY]
+   */
+  // private _buildLtvVesuRepayFromExtendedRoutes(amountUsd: number, vesuDeltas: Web3Number[]): ExecutionRoute[] {
+  //   const routes: ExecutionRoute[] = [];
+  //   const amt = safeUsdcWeb3Number(amountUsd);
+
+  //   // Withdraw from Extended → operator wallet
+  //   routes.push({ type: RouteType.EXTENDED_TO_WALLET, amount: amt, priority: routes.length });
+  //   this._budget.applyExtendedBalanceChange(-amountUsd);
+
+  //   // Wait for Extended withdrawal to settle before using wallet funds
+  //   routes.push({ type: RouteType.RETURN_TO_WAIT, priority: routes.length });
+
+  //   // Operator wallet → VA
+  //   routes.push({ type: RouteType.WALLET_TO_VA, amount: amt, priority: routes.length });
+
+  //   // Repay Vesu debt from VA funds
+  //   routes.push(...this._buildVesuRepayRoutesss(amountUsd, vesuDeltas)); // wrong
+
+  //   routes.forEach((r, i) => { r.priority = i; });
+  //   return routes;
+  // }
+
+  /**
+   * LTV_EXTENDED_PROFITABLE_REALIZE:
+   * Extended has unrealised PnL → realise it first, then withdraw + repay.
+   * Routes: [REALISE_PNL, EXTENDED_TO_WALLET, WALLET_TO_VA, VESU_REPAY]
+   */
+  // private _buildLtvVesuRepayRealiseRoutes(amountUsd: number, availWithdrawUsd: number, vesuDeltas: Web3Number[]): ExecutionRoute[] {
+  //   const routes: ExecutionRoute[] = [];
+  //   const amt = safeUsdcWeb3Number(amountUsd);
+  //   const instrument = this._config.extendedAdapter.config.extendedMarketName ?? 'BTC-USD';
+  //   const upnlRequired = amountUsd - availWithdrawUsd;
+
+  //   // Realise PnL to make funds available for withdrawal
+  //   routes.push({ type: RouteType.REALISE_PNL, amount: safeUsdcWeb3Number(upnlRequired), instrument, priority: routes.length });
+
+  //   // Withdraw realised funds from Extended → operator wallet
+  //   routes.push({ type: RouteType.EXTENDED_TO_WALLET, amount: amt, priority: routes.length });
+  //   this._budget.applyExtendedBalanceChange(-amountUsd);
+
+  //   // Wait for Extended withdrawal to settle
+  //   routes.push({ type: RouteType.RETURN_TO_WAIT, priority: routes.length });
+
+  //   // Operator wallet → VA
+  //   routes.push({ type: RouteType.WALLET_TO_VA, amount: amt, priority: routes.length });
+
+  //   // Repay Vesu debt from VA funds
+  //   routes.push(...this._buildVesuRepayRoutesss(amountUsd, vesuDeltas)); // wrong
+
+  //   routes.forEach((r, i) => { r.priority = i; });
+  //   return routes;
+  // }
+
+  /**
+   * MARGIN_CRISIS_VESU:
+   * Neither VA/Wallet nor Extended withdrawal covers the shortfall.
+   * Temporarily increase Extended leverage to free margin, withdraw to VA, then
+   * decrease Vesu lever to bring LTV back in range.
+   * Routes: [CRISIS_INCREASE_EXTENDED_MAX_LEVERAGE, EXTENDED_TO_WALLET, WALLET_TO_VA,
+   *          VESU_MULTIPLY_DECREASE_LEVER, EXTENDED_DECREASE_LEVER, CRISIS_UNDO_EXTENDED_MAX_LEVERAGE]
+   */
+  // private _buildMarginCrisisVesuRoutes(neededUsd: number, vesuDeltas: Web3Number[]): ExecutionRoute[] {
+  //   const routes: ExecutionRoute[] = [];
+  //   const amt = safeUsdcWeb3Number(neededUsd);
+  //   const instrument = this._config.extendedAdapter.config.extendedMarketName ?? 'BTC-USD';
+
+  //   // Temporarily boost Extended leverage to free margin
+  //   routes.push({ type: RouteType.CRISIS_INCREASE_EXTENDED_MAX_LEVERAGE, priority: routes.length });
+
+  //   // Withdraw freed margin from Extended → wallet
+  //   routes.push({ type: RouteType.EXTENDED_TO_WALLET, amount: amt, priority: routes.length });
+  //   this._budget.applyExtendedBalanceChange(-neededUsd);
+
+  //   // Wallet → VA
+  //   routes.push({ type: RouteType.WALLET_TO_VA, amount: amt, priority: routes.length });
+
+  //   // Decrease Vesu leverage to reduce LTV
+  //   // todo to verify if this is correct.
+  //   routes.push(...this._buildVesuDecreaseLeverRoutes(vesuDeltas));
+
+  //   // Decrease Extended exposure to match reduced Vesu position
+  //   // ! todo incorrect, to fix
+  //   routes.push({ type: RouteType.EXTENDED_DECREASE_LEVER, amount: safeUsdcWeb3Number(0), instrument, priority: routes.length });
+  //   this._budget.applyExtendedExposureDelta(instrument, safeUsdcWeb3Number(0));
+
+  //   // Revert Extended leverage back to normal
+  //   routes.push({ type: RouteType.CRISIS_UNDO_EXTENDED_MAX_LEVERAGE, priority: routes.length });
+
+  //   routes.forEach((r, i) => { r.priority = i; });
+  //   return routes;
+  // }
+
+  /** 2b. LTV Rebalance — Extended side */
+  /**
+   * 2b. LTV Rebalance — Extended side
+   *
+   * Triggered when Extended equity is below the required margin for current positions.
+   * Sources funds to Extended via VA/Wallet or Vesu borrow.
+   *
+   * Priority: 1) VA/Wallet → Extended  2) Vesu borrow → VA → Extended
+   */
+  private _classifyLtvExtended(): SolveCaseEntry[] {
+    const totalExtPosUsd = this._totalExtendedExposureUsd().toNumber();
+    const extEquity = this._budget.extendedBalance?.equity?.toNumber() ?? 0;
+    const lev = calculateExtendedLevergae();
+    const marginNeeded = lev > 0 ? totalExtPosUsd / lev - extEquity : 0;
+    if (marginNeeded <= CASE_THRESHOLD_USD) return [];
+
+    let caseId: CaseId = CaseId.LTV_EXTENDED_HIGH_USE_VA_OR_WALLET;
+    let remaining = marginNeeded;
+    const routes: ExecutionRoute[] = [];
+
+    // ── Step 1: VA + Wallet → Extended ──────────────────────────────────
+    if (this._budget.vaWalletUsd > CASE_THRESHOLD_USD && remaining > CASE_THRESHOLD_USD) {
+      const use = Math.min(this._budget.vaWalletUsd, remaining);
+
+      // VA first, then wallet
+      if (this._budget.vaUsd > CASE_THRESHOLD_USD) {
+        const { remaining: vaRem } = this._getVAToEXTENDEDRoute(remaining, routes, false);
+        remaining = vaRem;
+      }
+      if (remaining > CASE_THRESHOLD_USD) {
+        const { remaining: walletRem } = this._getWalletToEXTENDEDRoute(remaining, routes, false);
+        remaining = walletRem;
+      }
+    }
+
+    // ── Step 2: Vesu borrow → VA → Extended ─────────────────────────────
+    if (remaining > CASE_THRESHOLD_USD && this._budget.vesuBorrowCapacity > CASE_THRESHOLD_USD) {
+      const { remaining: borrowRem } = this._buildVesuBorrowRoutes(Math.min(remaining, this._budget.vesuBorrowCapacity), routes);
+      const borrowed = remaining - borrowRem;
+      if (remaining != borrowRem) {
+        const { remaining: vaRem } = this._getVAToEXTENDEDRoute(borrowed, routes, false);
+      }
+      remaining = borrowRem;
+      routes.forEach((r, i) => { r.priority = i; });
+      remaining -= borrowed;
+      caseId = CaseId.LTV_VESU_LOW_TO_EXTENDED;
+    }
+
+    if (remaining > CASE_THRESHOLD_USD) {
+      throw new Error(`${this._tag}: Insufficient funds to cover margin needs`);
+    }
+
+    routes.forEach((r, i) => { r.priority = i; });
+
+    return [{
+      case: CASE_DEFINITIONS[caseId],
+      additionalArgs: { amount: safeUsdcWeb3Number(marginNeeded) },
+      routes,
+    }];
+  }
+
+  // ── LTV Extended route builders ───────────────────────────────────────
+
+  /**
+   * LTV_EXTENDED_HIGH_USE_VA_OR_WALLET:
+   * VA/Wallet has funds → route them to Extended.
+   * Routes: [VA_TO_EXTENDED, WALLET_TO_EXTENDED] (wallet-first, then VA for remainder)
+   */
+  // private _buildLtvExtendedDepositFromVARoutes(amountUsd: number): ExecutionRoute[] {
+  //   const routes: ExecutionRoute[] = this._buildExtendedDepositRoutes(amountUsd);
+  //   routes.forEach((r, i) => { r.priority = i; });
+  //   return routes;
+  // }
+
+  /**
+   * LTV_VESU_LOW_TO_EXTENDED:
+   * Borrow USDC from Vesu, route through VA to Extended.
+   * Routes: [VESU_BORROW, VA_TO_EXTENDED]
+   */
+  // private _buildLtvExtendedBorrowFromVesuRoutes(borrowUsd: number, vesuDeltas: Web3Number[]): ExecutionRoute[] {
+  //   const routes: ExecutionRoute[] = [];
+  //   const amt = safeUsdcWeb3Number(borrowUsd);
+
+  //   // Borrow USDC from Vesu (lands in VA)
+  //   const { routes: borrowRoutes } = this._buildVesuBorrowRoutes(borrowUsd, vesuDeltas);
+  //   routes.push(...borrowRoutes);
+
+  //   // VA → Extended
+  //   routes.push({ type: RouteType.VA_TO_EXTENDED, amount: amt, priority: routes.length });
+  //   this._budget.applyExtendedBalanceChange(borrowUsd);
+
+  //   routes.forEach((r, i) => { r.priority = i; });
+  //   return routes;
+  // }
+
+  /**
+   * MARGIN_CRISIS_EXTENDED:
+   * Borrow beyond target HF on Vesu to free USDC, deposit to Extended,
+   * then decrease Vesu/Extended lever, undo crisis leverage.
+   * Routes: [CRISIS_BORROW_BEYOND_TARGET_HF, VA_TO_EXTENDED,
+   *          VESU_MULTIPLY_DECREASE_LEVER, EXTENDED_DECREASE_LEVER,
+   *          CRISIS_UNDO_EXTENDED_MAX_LEVERAGE]
+   */
+  // private _buildMarginCrisisExtendedRoutes(neededUsd: number, vesuDeltas: VesuPoolDelta[]): ExecutionRoute[] {
+  //   // ! todo need to verify this case properly
+
+  //   const routes: ExecutionRoute[] = [];
+  //   const amt = safeUsdcWeb3Number(neededUsd);
+  //   const instrument = this._config.extendedAdapter.config.extendedMarketName ?? 'BTC-USD';
+
+  //   // Borrow beyond normal target HF to free USDC
+  //   const pool = vesuDeltas.find((d) => d.debtDelta.greaterThan(0)) ?? vesuDeltas[0];
+  //   routes.push({
+  //     type: RouteType.CRISIS_BORROW_BEYOND_TARGET_HF,
+  //     poolId: pool?.poolId ?? ('' as unknown as ContractAddr),
+  //     token: pool?.debtToken?.symbol ?? this._config.assetToken.symbol,
+  //     amount: amt,
+  //     priority: routes.length,
+  //   });
+
+  //   // Borrowed USDC (now in VA) → Extended
+  //   routes.push({ type: RouteType.VA_TO_EXTENDED, amount: amt, priority: routes.length });
+  //   this._budget.applyExtendedBalanceChange(neededUsd);
+
+  //   // Wait for Extended deposit to be credited
+  //   routes.push({ type: RouteType.RETURN_TO_WAIT, priority: routes.length });
+
+  //   // Decrease Vesu leverage
+  //   routes.push(...this._buildVesuDecreaseLeverRoutes(vesuDeltas));
+
+  //   // Decrease Extended exposure to match
+  //   routes.push({ type: RouteType.EXTENDED_DECREASE_LEVER, amount: amt, instrument, priority: routes.length });
+  //   this._budget.applyExtendedExposureDelta(instrument, new Web3Number(amt.negated().toFixed(USDC_TOKEN_DECIMALS), USDC_TOKEN_DECIMALS));
+
+  //   // Revert crisis leverage
+  //   routes.push({ type: RouteType.CRISIS_UNDO_EXTENDED_MAX_LEVERAGE, priority: routes.length });
+
+  //   routes.forEach((r, i) => { r.priority = i; });
+  //   return routes;
+  // }
+
+  // ! todo implement max lever amount per execution cycle
+
+  /**
+   * 3. New Deposits / Excess Funds
+   *
+   * Computes how much exposure to create on Vesu and Extended, then
+   * distributes available funds using shortest-path priority chains:
+   *   Extended margin:  Wallet → VA → Vesu borrow
+   *   Vesu margin:      VA → Wallet → Extended
+   */
+  /**
+   * 3. New Deposits / Excess Funds
+   *
+   * Computes allocation split between Vesu and Extended, then sources
+   * funds and creates lever-increase routes.
+   *
+   * Fund flow (principle #3 — accumulate transfers, defer wait):
+   *   Phase A: fund Extended (wallet→ext, VA→ext, vesu-borrow→VA→ext)
+   *   Phase B: fund Vesu VA shortfall (wallet→VA, ext→wallet + wallet→VA)
+   *   Phase C: RETURN_TO_WAIT (if any transfer to Extended occurred)
+   *   Phase D: lever routes (VESU_MULTIPLY, EXTENDED_INCREASE) near each other (#4)
+   */
+  private _classifyDeposits(withdrawAmount: Web3Number): SolveCaseEntry[] {
+    if (withdrawAmount.toNumber() > CASE_THRESHOLD_USD) return [];
+
+    const distributableAmount = this._computeDistributableAmount(
+      this._budget.vesuPerPoolDebtDeltasToBorrow, withdrawAmount,
+    );
+    if (distributableAmount.toNumber() <= CASE_THRESHOLD_USD) return [];
+
+    const { vesuAllocationUsd, extendedAllocationUsd } =
+      this._computeAllocationSplit(distributableAmount);
+
+    const vesuDeltas = this._computePerPoolCollateralDeltas(
+      vesuAllocationUsd, this._budget.vesuPerPoolDebtDeltasToBorrow,
+    );
+
+    const extendedPositionDeltas = this._computeExtendedPositionDeltas(vesuDeltas);
+    const extendedDepositDelta = this._computeExtendedDepositDelta(extendedAllocationUsd);
+    const vesuDepositAmount = this._computeVesuDepositAmount(vesuDeltas);
+
+    const routes: ExecutionRoute[] = [];
+    let needsWait = false;
+
+    // ── Phase A: Fund Extended ──────────────────────────────────────────
+    if (extendedDepositDelta.toNumber() > CASE_THRESHOLD_USD) {
+      let rem = extendedDepositDelta.toNumber();
+
+      // Wallet → Extended
+      if (rem > CASE_THRESHOLD_USD) {
+        const { remaining } = this._getWalletToEXTENDEDRoute(rem, routes, false);
+        if (remaining < rem) needsWait = true;
+        rem = remaining;
+      }
+
+      // VA → Extended
+      if (rem > CASE_THRESHOLD_USD) {
+        const { remaining } = this._getVAToEXTENDEDRoute(rem, routes, false);
+        if (remaining < rem) needsWait = true;
+        rem = remaining;
+      }
+
+      // Vesu borrow → VA → Extended
+      if (rem > CASE_THRESHOLD_USD && this._budget.vesuBorrowCapacity > CASE_THRESHOLD_USD) {
+        const { remaining: borrowRem } = this._buildVesuBorrowRoutes(rem, routes);
+        const borrowed = rem - borrowRem;
+        if (borrowRem != rem) {
+          this._getVAToEXTENDEDRoute(borrowed, routes, false);
+          needsWait = true;
+          rem = borrowRem;
+        }
+      }
+    }
+
+    // ── Phase B: Fund Vesu VA shortfall ─────────────────────────────────
+    if (vesuDepositAmount.toNumber() > CASE_THRESHOLD_USD) {
+      const vaShortfall = vesuDepositAmount.toNumber() - this._budget.vaUsd;
+      if (vaShortfall > CASE_THRESHOLD_USD) {
+        let rem = vaShortfall;
+
+        // Wallet → VA
+        if (rem > CASE_THRESHOLD_USD && this._budget.walletUsd > CASE_THRESHOLD_USD) {
+          const { remaining } = this._getWalletToVARoute(Math.min(this._budget.walletUsd, rem), routes);
+          rem = remaining;
+        }
+
+        // check if withdrawal is enough to cover the shortfall
+        // if not, we visit upnl first
+        const isWithdrawalEnough = rem <= this._budget.extAvailWithdraw;
+        if (!isWithdrawalEnough && rem > CASE_THRESHOLD_USD) {
+          const { remaining: upnlRem } = this._getUpnlRoute(rem, routes);
+          rem = upnlRem;
+        }
+
+        // Extended → Wallet → VA (needs wait)
+        if (rem > CASE_THRESHOLD_USD && this._budget.extAvailWithdraw > CASE_THRESHOLD_USD) {
+          const extUse = Math.min(rem, this._budget.extAvailWithdraw);
+          this._getExtendedToWalletRoute(extUse, routes);
+          this._getWALLETToVARoute(extUse, routes);
+          rem -= extUse;
+          needsWait = false; // _getExtendedToWalletRoute already added RETURN_TO_WAIT
+        }
+      }
+    }
+
+    // ── Phase C: Wait for transfers to settle ───────────────────────────
+    if (needsWait) {
+      routes.push({ type: RouteType.RETURN_TO_WAIT, priority: routes.length });
+    }
+
+    // ── Phase D: Vesu lever increase ────────────────────────────────────
+    for (const vesuDelta of vesuDeltas) {
+      if (vesuDepositAmount.toNumber() > CASE_THRESHOLD_USD) {
+        // add avnu deposit swap route
+        // routes.push({
+        //   type: RouteType.AVNU_DEPOSIT_SWAP,
+        //   priority: routes.length,
+        //   fromToken: vesuDelta.collateralToken.symbol,
+        //   fromAmount: vesuDepositAmount,
+        //   toToken: vesuDelta.debtToken.symbol,
+        // });
+      }
+      if (vesuDelta.collateralDelta.toNumber() > 0) {
+        const swappedAmount = new Web3Number((vesuDepositAmount.toNumber() * vesuDelta.debtPrice / (vesuDelta.collateralPrice ?? 0)).toFixed(6), vesuDelta.collateralToken.decimals);
+        routes.push({
+          type: RouteType.VESU_MULTIPLY_INCREASE_LEVER,
+          priority: routes.length,
+          collateralToken: vesuDelta.collateralToken,
+          debtToken: vesuDelta.debtToken,
+          marginAmount: swappedAmount, // should be the swapped amount as per vesu multiply adapter
+          swappedCollateralAmount: vesuDelta.collateralDelta.minus(swappedAmount),
+          debtAmount: vesuDelta.debtDelta,
+          poolId: vesuDelta.poolId,
+        } as VesuMultiplyRoute);
+      }
+    }
+
+    // ── Phase D: Extended lever increase ────────────────────────────────
+    for (const epDelta of extendedPositionDeltas) {
+      if (epDelta.delta.toNumber() > 0) {
+        routes.push({
+          type: RouteType.EXTENDED_INCREASE_LEVER,
+          priority: routes.length,
+          instrument: epDelta.instrument,
+          amount: epDelta.delta,
+        } as ExtendedLeverRoute);
+      }
+    }
+
+    if (routes.length === 0) return [];
+    routes.forEach((r, i) => { r.priority = i; });
+    return [{
+      case: CASE_DEFINITIONS[CaseId.DEPOSIT_FRESH_VAULT],
+      additionalArgs: {
+        amount: safeUsdcWeb3Number(distributableAmount.toNumber()),
+      },
+      routes,
+    }];
+  }
+
+  /** 4. Exposure Imbalance */
+  // private _classifyImbalance(
+  //   vesuDeltas: VesuPoolDelta[],
+  // ): SolveCaseEntry[] {
+  //   const extBtc = this._totalExtendedExposure().toNumber();
+  //   const vesuBtc = this._totalVesuCollateral().toNumber();
+  //   const maxBtc = Math.max(extBtc, vesuBtc);
+  //   if (maxBtc <= 0) return [];
+  //   const imb = extBtc - vesuBtc;
+  //   if (Math.abs(imb) / maxBtc <= IMBALANCE_THRESHOLD_FRACTION) return [];
+  //   const exposureDiffBtc = Math.abs(imb);
+  //   const rem = this._budget.totalUnused;
+
+  //   if (imb > 0) {
+  //     // Extended excess short → need more Vesu collateral
+  //     if (rem > CASE_THRESHOLD_USD) {
+  //       return [{
+  //         case: CASE_DEFINITIONS[CaseId.IMBALANCE_EXTENDED_EXCESS_SHORT_HAS_FUNDS],
+  //         additionalArgs: {},
+  //         routes: this._buildImbalanceExtExcessShortHasFundsRoutes(rem, exposureDiffBtc, vesuDeltas),
+  //       }];
+  //     }
+  //     return [{
+  //       case: CASE_DEFINITIONS[CaseId.IMBALANCE_EXTENDED_EXCESS_SHORT_NO_FUNDS],
+  //       additionalArgs: {},
+  //       routes: this._buildImbalanceExtExcessShortNoFundsRoutes(exposureDiffBtc),
+  //     }];
+  //   }
+
+  //   // Vesu excess long → need more Extended exposure
+  //   if (rem > CASE_THRESHOLD_USD) {
+  //     return [{
+  //       case: CASE_DEFINITIONS[CaseId.IMBALANCE_VESU_EXCESS_LONG_HAS_FUNDS],
+  //       additionalArgs: {},
+  //       routes: this._buildImbalanceVesuExcessLongHasFundsRoutes(rem, exposureDiffBtc, vesuDeltas),
+  //     }];
+  //   }
+  //   return [{
+  //     case: CASE_DEFINITIONS[CaseId.IMBALANCE_VESU_EXCESS_LONG_NO_FUNDS],
+  //     additionalArgs: {},
+  //     routes: this._buildImbalanceVesuExcessLongNoFundsRoutes(vesuDeltas),
+  //   }];
+  // }
+
+  // ── Imbalance route builders ──────────────────────────────────────────
+
+  /**
+   * IMBALANCE_EXTENDED_EXCESS_SHORT_HAS_FUNDS:
+   * Extended has too much short exposure vs Vesu. Use VA/Wallet funds to
+   * add Vesu collateral and reduce Extended exposure.
+   *
+   * The new Vesu collateral covers part of the imbalance; the remaining
+   * gap is closed by reducing Extended short exposure.
+   *
+   * Routes: [AVNU_DEPOSIT_SWAP, VESU_MULTIPLY_INCREASE_LEVER, EXTENDED_DECREASE_LEVER]
+   */
+  // private _buildImbalanceExtExcessShortHasFundsRoutes(
+  //   fundsUsd: number, exposureDiffBtc: number, vesuDeltas: VesuPoolDelta[],
+  // ): ExecutionRoute[] {
+  //   const routes: ExecutionRoute[] = [];
+  //   const collSym = this._config.collateralToken.symbol;
+  //   const debtSym = this._config.assetToken.symbol;
+  //   const instrument = this._config.extendedAdapter.config.extendedMarketName ?? 'BTC-USD';
+
+  //   // Swap USDC → BTC for Vesu collateral
+  //   routes.push({
+  //     type: RouteType.AVNU_DEPOSIT_SWAP,
+  //     fromToken: debtSym,
+  //     fromAmount: safeUsdcWeb3Number(fundsUsd),
+  //     toToken: collSym,
+  //     priority: routes.length,
+  //   } as SwapRoute);
+
+  //   // Increase Vesu lever (deposit collateral + borrow)
+  //   routes.push(...this._buildVesuIncreaseLeverRoutes(vesuDeltas));
+
+  //   // New Vesu collateral covers part of the imbalance
+  //   const newVesuCollBtc = vesuDeltas
+  //     .filter((d) => d.collateralDelta.greaterThan(0))
+  //     .reduce((sum, d) => sum + d.collateralDelta.toNumber(), 0);
+
+  //   // Remaining imbalance that needs to be closed on Extended
+  //   const extDecreaseExposureBtc = Math.max(0, exposureDiffBtc - newVesuCollBtc);
+
+  //   if (extDecreaseExposureBtc > 0) {
+  //     const decDelta = new Web3Number(extDecreaseExposureBtc.toFixed(COLLATERAL_PRECISION), USDC_TOKEN_DECIMALS);
+  //     routes.push({
+  //       type: RouteType.EXTENDED_DECREASE_LEVER,
+  //       amount: decDelta,
+  //       instrument,
+  //       priority: routes.length,
+  //     });
+  //     this._budget.applyExtendedExposureDelta(instrument, new Web3Number(decDelta.negated().toFixed(COLLATERAL_PRECISION), USDC_TOKEN_DECIMALS));
+
+  //   }
+
+  //   routes.forEach((r, i) => { r.priority = i; });
+  //   return routes;
+  // }
+
+  /**
+   * IMBALANCE_EXTENDED_EXCESS_SHORT_NO_FUNDS:
+   * No available funds to add Vesu collateral → reduce Extended exposure
+   * by the full imbalance amount.
+   * Routes: [EXTENDED_DECREASE_LEVER]
+   */
+  private _buildImbalanceExtExcessShortNoFundsRoutes(exposureDiffBtc: number): ExecutionRoute[] {
+    const instrument = this._config.extendedAdapter.config.extendedMarketName ?? 'BTC-USD';
+    const decDelta = new Web3Number(exposureDiffBtc.toFixed(COLLATERAL_PRECISION), USDC_TOKEN_DECIMALS);
+    this._budget.applyExtendedExposureDelta(instrument, new Web3Number(decDelta.negated().toFixed(COLLATERAL_PRECISION), USDC_TOKEN_DECIMALS));
+    return [{
+      type: RouteType.EXTENDED_DECREASE_LEVER,
+      amount: decDelta,
+      instrument,
+      priority: 0,
+    }];
+  }
+
+  /**
+   * IMBALANCE_VESU_EXCESS_LONG_HAS_FUNDS:
+   * Vesu has too much long exposure vs Extended. Deposit funds on Extended
+   * to increase short exposure, and decrease Vesu lever for the remainder.
+   *
+   * Routes: [WALLET_TO_EXTENDED / VA_TO_EXTENDED, EXTENDED_INCREASE_LEVER,
+   *          VESU_MULTIPLY_DECREASE_LEVER]
+   */
+  // private _buildImbalanceVesuExcessLongHasFundsRoutes(
+  //   fundsUsd: number, exposureDiffBtc: number, vesuDeltas: VesuPoolDelta[],
+  // ): ExecutionRoute[] {
+  //   const routes: ExecutionRoute[] = [];
+  //   const instrument = this._config.extendedAdapter.config.extendedMarketName ?? 'BTC-USD';
+
+  //   // ExecutionRoute funds to Extended (wallet-first, then VA)
+  //   routes.push(...this._buildExtendedDepositRoutes(fundsUsd));
+
+  //   // Compute how much new Extended exposure the deposited funds create
+  //   const extLeverage = calculateExtendedLevergae();
+  //   const newExtExposureUsd = fundsUsd * extLeverage;
+  //   const avgCollPrice = this._budget.vesuPoolStates[0]?.collateralPrice ?? 1;
+  //   const newExtExposureBtc = avgCollPrice > 0 ? newExtExposureUsd / avgCollPrice : 0;
+
+  //   // Increase Extended lever by the new exposure (capped to imbalance)
+  //   const extIncreaseBtc = Math.min(newExtExposureBtc, exposureDiffBtc);
+  //   if (extIncreaseBtc > 0) {
+  //     const incDelta = new Web3Number(extIncreaseBtc.toFixed(COLLATERAL_PRECISION), USDC_TOKEN_DECIMALS);
+  //     routes.push({
+  //       type: RouteType.EXTENDED_INCREASE_LEVER,
+  //       amount: incDelta,
+  //       instrument,
+  //       priority: routes.length,
+  //     });
+  //     this._budget.applyExtendedExposureDelta(instrument, incDelta);
+  //   }
+
+  //   // Remaining imbalance closed by decreasing Vesu lever
+  //   const vesuDecreaseBtc = Math.max(0, exposureDiffBtc - extIncreaseBtc);
+  //   if (vesuDecreaseBtc > 0) {
+  //     routes.push(...this._buildVesuDecreaseLeverRoutes(vesuDeltas));
+  //   }
+
+  //   routes.forEach((r, i) => { r.priority = i; });
+  //   return routes;
+  // }
+
+  /**
+   * IMBALANCE_VESU_EXCESS_LONG_NO_FUNDS:
+   * No funds to increase Extended → decrease Vesu lever by the full imbalance.
+   * Routes: [VESU_MULTIPLY_DECREASE_LEVER]
+   */
+  // private _buildImbalanceVesuExcessLongNoFundsRoutes(vesuDeltas: VesuPoolDelta[]): ExecutionRoute[] {
+  //   const routes: ExecutionRoute[] = this._buildVesuDecreaseLeverRoutes(vesuDeltas);
+  //   routes.forEach((r, i) => { r.priority = i; });
+  //   return routes;
+  // }
+
+  // ── Main classifier (orchestrator) ─────────────────────────────────────
+
+  /**
+   * Classifies the current state into actionable cases. Each case carries
+   * its own execution routes with amounts and state info.
+   */
+  private _classifyCases(withdrawAmount: Web3Number): SolveCaseEntry[] {
+    this._budget.initBudget();
+
+    // withdrawal is simply about available funds and unwinding positions.
+    const withdrawalCases = this._classifyWithdrawal(withdrawAmount);
+
+    // 2. LTV Rebalance — Vesu high LTV (fund movement to VA)
+    const ltvVesuCases = this._classifyLtvVesu();
+
+    // 3. LTV Rebalance — Extended low margin
+    const ltvExtendedCases = this._classifyLtvExtended();
+
+    // 4. New Deposits — allocate remaining budget to lever operations
+    const depositCases = this._classifyDeposits(withdrawAmount);
+
+    //   ...this._classifyImbalance(vesuDeltas),
+
+    return [
+      ...withdrawalCases,
+      ...ltvVesuCases,
+      ...ltvExtendedCases,
+      ...depositCases,
+    ];
+  }
+
+
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // Private — aggregation helpers
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  private _totalVesuCollateral(): Web3Number {
+    return this._budget.vesuPoolStates.reduce(
+      (acc, pool) =>
+        acc.plus(
+          pool.collateralAmount,
+        ),
+      new Web3Number(0, USDC_TOKEN_DECIMALS),
+    );
+  }
+
+  private _totalVesuCollateralUsd(): Web3Number {
+    return this._budget.vesuPoolStates.reduce(
+      (acc, pool) =>
+        acc.plus(
+          pool.collateralAmount.multipliedBy(pool.collateralPrice),
+        ),
+      new Web3Number(0, USDC_TOKEN_DECIMALS),
+    );
+  }
+
+  private _totalExtendedExposure(): Web3Number {
+    return this._budget.extendedPositions.reduce(
+      (acc, position) => acc.plus(position.size),
+      new Web3Number(0, USDC_TOKEN_DECIMALS),
+    );
+  }
+
+  private _totalExtendedExposureUsd(): Web3Number {
+    return this._budget.extendedPositions.reduce(
+      (acc, position) => acc.plus(position.valueUsd),
+      new Web3Number(0, USDC_TOKEN_DECIMALS),
+    );
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // Private — logging
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  private _logSolveResult(result: SolveResult): void {
+    // Log detected cases
+    logger.info(
+      `${this._tag}::solve detected ${result.cases.length} case(s): ` +
+      result.cases
+        .map((c) => `[${c.case.category}] ${c.case.id}`)
+        .join(', '),
+    );
+    for (const entry of result.cases) {
+      logger.info(
+        `${this._tag}::solve case "${entry.case.title}" — ` +
+        `steps: ${entry.case.steps.length}`,
+      );
+    }
+
+    logger.info(
+      `${this._tag}::solve result — ` +
+      `extendedDeposit: ${result.extendedDeposit.toNumber()}, ` +
+      `vesuAllocUsd: ${result.vesuAllocationUsd.toNumber()}, ` +
+      `extAllocUsd: ${result.extendedAllocationUsd.toNumber()}, ` +
+      `bringLiquidity: ${result.bringLiquidityAmount.toNumber()}`,
+    );
+
+    for (let i = 0; i < result.vesuDeltas.length; i++) {
+      const delta = result.vesuDeltas[i];
+      logger.info(
+        `${this._tag}::solve vesu[${i}] ` +
+        `pool=${delta.poolId.shortString()} ` +
+        `debtDelta=${delta.debtDelta.toNumber()} ` +
+        `collateralDelta=${delta.collateralDelta.toNumber()}`,
+      );
+    }
+
+    for (let i = 0; i < result.extendedPositionDeltas.length; i++) {
+      const delta = result.extendedPositionDeltas[i];
+      logger.info(
+        `${this._tag}::solve extended[${i}] ` +
+        `instrument=${delta.instrument} ` +
+        `delta=${delta.delta.toNumber()}`,
+      );
+    }
+
+    for (const entry of result.cases) {
+      const caseRoutes = entry.routes;
+      logger.info(
+        `${this._tag}::solve case "${entry.case.id}" routes (${caseRoutes.length}): ` +
+        caseRoutes
+          .map((r) => `[${r.priority}] ${r.type} ${routeSummary(r)}`)
+          .join(' → '),
+      );
+    }
+  }
+}