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

package/src/strategies/vesu-extended-strategy/services/executionService.ts

@@ -0,0 +1,2251 @@
+import { Account, Call, uint256 } from "starknet";
+import { ContractAddr, Web3Number } from "@/dataTypes";
+import { IConfig, TokenInfo, Protocols } from "@/interfaces";
+import { PricerBase } from "@/modules/pricerBase";
+import { ERC20 } from "@/modules";
+import { logger, StandardMerkleTree, StarknetCallParser } from "@/utils";
+import { ExtendedAdapter } from "../../universal-adapters/extended-adapter";
+import { VesuMultiplyAdapter } from "../../universal-adapters/vesu-multiply-adapter";
+import {
+  VesuModifyPositionAdapter,
+  VesuModifyPositionDepositParams,
+  VesuModifyPositionWithdrawParams,
+} from "../../universal-adapters/vesu-modify-position-adapter";
+import { AvnuAdapter } from "../../universal-adapters/avnu-adapter";
+import { UsdcToUsdceAdapter } from "../../universal-adapters/usdc<>usdce-adapter";
+import { ManageCall, SwapPriceInfo } from "../../universal-adapters/baseAdapter";
+import { OpenOrder, OrderSide, OrderStatus } from "@/modules/ExtendedWrapperSDk";
+import {
+  SolveResult,
+  ExecutionRoute,
+  RouteType,
+  SolveCaseEntry,
+  TransferRoute,
+  SwapRoute,
+  VesuMultiplyRoute,
+  VesuDebtRoute,
+  RealisePnlRoute,
+  ExtendedLeverRoute,
+  CrisisBorrowRoute,
+  BringLiquidityRoute,
+  routeSummary,
+} from "./extended-vesu-state-manager";
+import {
+  CycleType,
+  TransactionResult,
+  ExecutionEventType,
+  ExecutionEventMetadata,
+  ExecutionCallback,
+} from "../types/transaction-metadata";
+import {
+  calculatePositionToCloseToWithdrawAmount,
+  calculateExtendedLevergae,
+} from "../utils/helper";
+import { TokenTransferAdapter } from "@/strategies/universal-adapters/token-transfer-adapter";
+
+// ─── Constants ──────────────────────────────────────────────────────────────────
+
+/** Buffer factor applied to AVNU swap amounts (0.1% less) to account for slippage */
+const AVNU_BUFFER_FACTOR = 0.999;
+
+/** Extended crisis max leverage */
+const CRISIS_MAX_LEVERAGE = "4";
+
+/** Default acceptable slippage for Extended limit orders (basis points) */
+const DEFAULT_EXTENDED_SLIPPAGE_BPS = 10; // 0.1%
+
+/** Default max price divergence between Extended and Vesu execution prices (basis points) */
+const DEFAULT_MAX_PRICE_DIVERGENCE_BPS = 50; // 0.5%
+
+/** Max retries for Extended limit order status polling */
+const MAX_ORDER_STATUS_RETRIES = 3;
+
+/** Delay between order status poll retries (ms) */
+const ORDER_STATUS_RETRY_DELAY_MS = 5000;
+
+/** Default timeout for Extended fill in coordinated dual-exchange mode (ms) */
+const DEFAULT_EXTENDED_FILL_TIMEOUT_MS = 3000;
+
+// ─── Config ────────────────────────────────────────────────────────────────────
+
+export interface ExecutionConfig {
+  networkConfig: IConfig;
+  pricer: PricerBase;
+  vesuAdapter: VesuMultiplyAdapter;
+  vesuModifyPositionAdapter: VesuModifyPositionAdapter;
+  extendedAdapter: ExtendedAdapter;
+  avnuAdapter: AvnuAdapter;
+  usdcToUsdceAdapter: UsdcToUsdceAdapter;
+  usdceTransferAdapter: TokenTransferAdapter
+  vaultAllocator: ContractAddr;
+  walletAddress: string;
+  wbtcToken: TokenInfo;
+  usdcToken: TokenInfo;
+  usdceToken: TokenInfo;
+
+  /**
+   * Returns the strategy's merkle tree (built from all leaf adapters).
+   * Used to generate proofs for adapter manage calls.
+   */
+  getMerkleTree: () => StandardMerkleTree;
+
+  /**
+   * Combines merkle proofs and ManageCall[] into a single on-chain Call
+   * that invokes `manage_vault_with_merkle_verification` on the manager contract.
+   */
+  getManageCall: (proofs: string[][], manageCalls: ManageCall[]) => Call;
+
+  /**
+   * Callback to get the bring-liquidity call from the strategy.
+   */
+  getBringLiquidityCall: (params: { amount: Web3Number }) => Promise<Call>;
+
+  /**
+   * Optional callback invoked on key execution lifecycle events.
+   * Use to persist state to DB, send alerts, etc.
+   */
+  onExecutionEvent?: ExecutionCallback;
+
+  /**
+   * Acceptable slippage for Extended limit orders in basis points.
+   * E.g. 10 = 0.1%. Default: 10 (0.1%).
+   * For BUY orders: limitPrice = midPrice * (1 + slippage)
+   * For SELL orders: limitPrice = midPrice * (1 - slippage)
+   */
+  extendedAcceptableSlippageBps?: number;
+
+  /**
+   * Maximum acceptable price divergence between Extended and Vesu
+   * execution prices in basis points. Default: 50 (0.5%).
+   *
+   * During increase exposure (extended SHORT + vesu LONG):
+   *   (extendedPrice - vesuPrice) / vesuPrice must be > -maxDivergence
+   * During decrease exposure (extended BUY + vesu decrease):
+   *   (extendedPrice - vesuPrice) / vesuPrice must be < +maxDivergence
+   */
+  maxPriceDivergenceBps?: number;
+
+  /**
+   * Max time (ms) to wait for Extended limit order fill in coordinated
+   * dual-exchange mode. Default: 3000 (3 seconds).
+   */
+  extendedFillTimeoutMs?: number;
+}
+
+interface ExtendedCancelResolution {
+  outcome: "filled" | "cancelled" | "failed";
+  order: OpenOrder | null;
+}
+
+// ─── Execution Service ─────────────────────────────────────────────────────────
+
+/**
+ * Processes a {@link SolveResult} and translates each case's {@link ExecutionRoute}s into
+ * concrete on-chain transaction calls (batched) or off-chain API operations.
+ *
+ * Key design principles:
+ *
+ * 1. **Case-based execution**: Cases are processed sequentially. Within each
+ *    case, routes execute in priority order.
+ *
+ * 2. **RETURN_TO_WAIT**: When encountered, all pending on-chain calls are
+ *    flushed and execution halts. The remaining routes will be re-computed
+ *    in the next solve cycle once async operations (bridge, deposit credit) settle.
+ *
+ * 3. **On-chain batching**: Consecutive on-chain routes (Starknet calls) are
+ *    accumulated into a single multicall batch. Off-chain routes (Extended API)
+ *    flush the batch, execute independently, then resume accumulation.
+ *
+ * 4. **pendingDeposit awareness**: Transfers to Extended are reduced by any
+ *    amount already in transit, avoiding double-sends.
+ *
+ * 5. **AVNU buffer**: Swap amounts use a 0.1% buffer to account for slippage.
+ *
+ * Usage:
+ *   const executor = new ExecutionService(config);
+ *   const results  = await executor.execute(solveResult);
+ */
+export class ExecutionService {
+  private readonly _config: ExecutionConfig;
+  private readonly _tag = "ExecutionService";
+  private readonly _tokenSymbols: Record<string, string>;
+  private readonly _tokenDecimals: Record<string, number>;
+  private readonly _poolNames: Record<string, string>;
+
+  /**
+   * Remaining pending deposit budget (consumed during execution to avoid double-sends).
+   * Initialised from SolveResult.pendingDeposit at the start of execute().
+   */
+  private _pendingDepositRemaining: number = 0;
+
+  /**
+   * Starknet account used for on-chain estimation in coordinated mode.
+   * Set at the start of execute() and valid for the duration of the call.
+   */
+  private _account: Account | null = null;
+
+  constructor(config: ExecutionConfig) {
+    this._config = config;
+    const avnuTokens = config.avnuAdapter.config.supportedPositions.map(
+      (position) => position.asset,
+    );
+    this._tokenSymbols = StarknetCallParser.buildTokenSymbolLookup([
+      config.wbtcToken,
+      config.usdcToken,
+      config.usdceToken,
+      config.vesuAdapter.config.baseToken,
+      config.vesuAdapter.config.collateral,
+      config.vesuAdapter.config.debt,
+      config.vesuAdapter.config.marginToken,
+      config.vesuModifyPositionAdapter.config.collateral,
+      config.vesuModifyPositionAdapter.config.debt,
+      ...avnuTokens,
+    ]);
+    this._tokenDecimals = StarknetCallParser.buildTokenDecimalsLookup([
+      config.wbtcToken,
+      config.usdcToken,
+      config.usdceToken,
+      config.vesuAdapter.config.baseToken,
+      config.vesuAdapter.config.collateral,
+      config.vesuAdapter.config.debt,
+      config.vesuAdapter.config.marginToken,
+      config.vesuModifyPositionAdapter.config.collateral,
+      config.vesuModifyPositionAdapter.config.debt,
+      ...avnuTokens,
+    ]);
+    this._poolNames = StarknetCallParser.buildPoolNameLookup([
+      {
+        poolId: config.vesuAdapter.config.poolId.toBigInt(),
+        name: `${config.vesuAdapter.config.collateral.symbol}/${config.vesuAdapter.config.debt.symbol}`,
+      },
+      {
+        poolId: config.vesuModifyPositionAdapter.config.poolId.toBigInt(),
+        name: `${config.vesuModifyPositionAdapter.config.collateral.symbol}/${config.vesuModifyPositionAdapter.config.debt.symbol}`,
+      },
+    ]);
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // Internal helpers — manage call building, event emission, limit orders
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  /**
+   * Emits a lifecycle event via the configured callback (if present).
+   * Safe to call even when no callback is configured.
+   */
+  private async _emitEvent(
+    eventType: ExecutionEventType,
+    metadata: ExecutionEventMetadata,
+  ): Promise<void> {
+    try {
+      await this._config.onExecutionEvent?.(eventType, metadata);
+    } catch (err) {
+      logger.error(`${this._tag}::_emitEvent callback threw: ${err}`);
+    }
+  }
+
+  private _getProofGroupsForManageCalls(manageCalls: ManageCall[]): string[][] {
+    const tree = this._config.getMerkleTree();
+    const proofByReadableId = new Map<string, string[]>();
+    for (const [i, v] of tree.entries()) {
+      if (proofByReadableId.has(v.readableId)) {
+        throw new Error(`${this._tag}::_getProofGroupsForManageCalls duplicate readableId: ${v.readableId}`);
+      }
+      proofByReadableId.set(v.readableId, tree.getProof(i));
+    }
+
+    return manageCalls.map((manageCall, index) => {
+      if (!manageCall.proofReadableId) {
+        throw new Error(`${this._tag}::_getProofGroupsForManageCalls missing proofReadableId at index ${index}`);
+      }
+      const proof = proofByReadableId.get(manageCall.proofReadableId);
+      if (!proof) {
+        throw new Error(`${this._tag}::_getProofGroupsForManageCalls proof not found for readableId=${manageCall.proofReadableId}`);
+      }
+      return proof;
+    });
+  }
+
+  /**
+   * Builds a single manage call (manage_vault_with_merkle_verification) for an adapter.
+   *
+   * Pattern:
+   *  1. Calls adapter.getDepositCall / getWithdrawCall to get ManageCall[]
+   *  2. Gets merkle proofs for the adapter's leaves
+   *  3. Combines via getManageCall into a single on-chain Call
+   *
+   * Use this for any VA-routed operation that needs merkle proof verification.
+   */
+  private async _buildAdapterManageCall<T extends { amount: Web3Number } = { amount: Web3Number }>(
+    adapter: {
+      getDepositCall: (params: T) => Promise<ManageCall[]>;
+      getWithdrawCall: (params: T) => Promise<ManageCall[]>;
+    },
+    isDeposit: boolean,
+    params: T,
+  ): Promise<Call> {
+    const manageCalls = isDeposit
+      ? await adapter.getDepositCall(params)
+      : await adapter.getWithdrawCall(params);
+    if (manageCalls.length === 0) {
+      throw new Error(
+        `${this._tag}::_buildAdapterManageCall adapter returned empty ManageCall[] ` +
+        `(isDeposit=${isDeposit}, amount=${params.amount.toNumber()})`,
+      );
+    }
+    StarknetCallParser.logManageCallsSummary(
+      `${this._tag}::_buildAdapterManageCall decoded manageCalls`,
+      manageCalls,
+      {
+        tokenSymbols: this._tokenSymbols,
+        tokenDecimals: this._tokenDecimals,
+        poolNames: this._poolNames,
+      },
+      (message) => logger.debug(message),
+    );
+
+    return this._config.getManageCall(
+      this._getProofGroupsForManageCalls(manageCalls),
+      manageCalls,
+    );
+  }
+
+  private async _getExtendedMidPrice(): Promise<number | null> {
+    const { bid, ask } = await this._config.extendedAdapter.fetchOrderBookFromExtended();
+    if (
+      !bid ||
+      !ask ||
+      bid.lessThanOrEqualTo(0) ||
+      ask.lessThanOrEqualTo(0)
+    ) {
+      logger.error(
+        `${this._tag}::_executeExtendedLimitOrder invalid orderbook: ` +
+        `bid=${bid?.toNumber()}, ask=${ask?.toNumber()}`,
+      );
+      return null;
+    }
+
+    const midPrice = ask.plus(bid).div(2);
+    return midPrice.toNumber();
+  }
+
+  /**
+   * Executes a limit order on Extended with acceptable slippage from mid spot price.
+   *
+   * Flow:
+   *  1. Set leverage on the market
+   *  2. Fetch orderbook → compute mid price
+   *  3. Apply configured slippage to derive limit price
+   *  4. Place IOC limit order at that price
+   *  5. Poll for fill status with retries
+   *
+   * Returns execution details including the fill price, or null on failure.
+   */
+  private async _executeExtendedLimitOrder(
+    btcAmount: number,
+    idealPrice: number,
+    side: OrderSide,
+    maxAttempts: number = 1,
+    options?: {
+      onOrderCreated?: (orderId: string) => void;
+    },
+  ): Promise<{
+    position_id: string;
+    btc_exposure: string;
+    executionPrice: number;
+  } | null> {
+    const adapter = this._config.extendedAdapter;
+    const marketName = adapter.config.extendedMarketName;
+    logger.info(`${this._tag}::_executeExtendedLimitOrder idealPrice=${idealPrice} side=${side} btcAmount=${btcAmount} maxAttempts=${maxAttempts}`);
+
+    // const setLevResult = await adapter.setLeverage(leverage, marketName);
+    // if (!setLevResult) {
+    //   logger.error(
+    //     `${this._tag}::_executeExtendedLimitOrder failed to set leverage`,
+    //   );
+    //   return null;
+    // }
+
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+      //   const { bid, ask } = await adapter.fetchOrderBookFromExtended();
+      //   if (
+      //     !bid ||
+      //     !ask ||
+      //     bid.lessThanOrEqualTo(0) ||
+      //     ask.lessThanOrEqualTo(0)
+      //   ) {
+      //     logger.error(
+      //       `${this._tag}::_executeExtendedLimitOrder invalid orderbook: ` +
+      //       `bid=${bid?.toNumber()}, ask=${ask?.toNumber()}`,
+      //     );
+      //     return null;
+      //   }
+
+      //   const midPrice = ask.plus(bid).div(2);
+      //   const slippageBps =
+      //     this._config.extendedAcceptableSlippageBps ??
+      //     DEFAULT_EXTENDED_SLIPPAGE_BPS;
+      //   const slippageFactor = slippageBps / 10000;
+
+      const limitPrice = Number((
+        side === OrderSide.BUY
+          ? idealPrice * (1 + 0.005)
+          : idealPrice * (1 - 0.005)).toFixed(2));
+
+      const amountInToken = (btcAmount).toFixed(
+        adapter.config.extendedPrecision,
+      );
+
+      logger.info(
+        `${this._tag}::_executeExtendedLimitOrder idealPrice=${idealPrice} ` +
+        `side=${side} amount=${amountInToken} ` +
+        `limitPrice=${limitPrice.toFixed(0)}`,
+      );
+
+      await this._emitEvent(ExecutionEventType.INITIATED, {
+        routeType: `EXTENDED_LIMIT_${side}`,
+        protocol: 'EXTENDED',
+        amount: amountInToken,
+        limitPrice: limitPrice,
+      });
+
+      const result = await adapter.createExtendedPositon(
+        adapter.client,
+        marketName,
+        amountInToken,
+        limitPrice.toFixed(0),
+        side,
+      );
+
+      if (!result || !result.position_id) {
+        logger.error(
+          `${this._tag}::_executeExtendedLimitOrder order creation failed (attempt ${attempt})`,
+        );
+        if (attempt < maxAttempts) {
+          await new Promise((r) => setTimeout(r, 2000 * attempt));
+          continue;
+        }
+        await this._emitEvent(ExecutionEventType.FAILURE, {
+          routeType: `EXTENDED_LIMIT_${side}`,
+          error: 'Order creation failed after max attempts',
+        });
+        return null;
+      }
+      options?.onOrderCreated?.(result.position_id);
+
+      // Poll order status
+      let openOrder = await adapter.getOrderStatus(
+        result.position_id,
+        marketName,
+      );
+      if (!openOrder) {
+        for (let sr = 1; sr <= MAX_ORDER_STATUS_RETRIES; sr++) {
+          await new Promise((r) => setTimeout(r, ORDER_STATUS_RETRY_DELAY_MS));
+          openOrder = await adapter.getOrderStatus(
+            result.position_id,
+            marketName,
+          );
+          if (openOrder) break;
+        }
+      }
+
+      if (openOrder && openOrder.status === OrderStatus.FILLED) {
+        const executionPrice = parseFloat(
+          openOrder.average_price || openOrder.price || '0',
+        );
+        logger.info(
+          `${this._tag}::_executeExtendedLimitOrder FILLED orderId=${result.position_id} ` +
+          `qty=${openOrder.qty} execPrice=${executionPrice}`,
+        );
+        await this._emitEvent(ExecutionEventType.SUCCESS, {
+          routeType: `EXTENDED_LIMIT_${side}`,
+          orderId: result.position_id,
+          amount: openOrder.qty,
+          executionPrice,
+          limitPrice: limitPrice,
+        });
+        return {
+          position_id: result.position_id,
+          btc_exposure: openOrder.qty,
+          executionPrice,
+        };
+      }
+
+      if (openOrder && openOrder.status !== OrderStatus.FILLED) {
+        logger.warn(
+          `${this._tag}::_executeExtendedLimitOrder order ${result.position_id} ` +
+          `status=${openOrder.status}, not FILLED — retrying`,
+        );
+        if (attempt < maxAttempts) {
+          await new Promise((r) => setTimeout(r, 2000 * attempt));
+          continue;
+        }
+      }
+
+      // Order exists but status unknown after retries (API delay)
+      if (!openOrder) {
+        logger.warn(
+          `${this._tag}::_executeExtendedLimitOrder order ${result.position_id} ` +
+          `status unknown after ${MAX_ORDER_STATUS_RETRIES} retries — returning position_id`,
+        );
+        return {
+          position_id: result.position_id,
+          btc_exposure: amountInToken,
+          executionPrice: limitPrice,
+        };
+      }
+    }
+
+    await this._emitEvent(ExecutionEventType.FAILURE, {
+      routeType: `EXTENDED_LIMIT_${side}`,
+      error: `Max attempts (${maxAttempts}) reached without fill`,
+    });
+    return null;
+  }
+
+  private async _fetchExtendedOrderStatusWithRetries(
+    orderId: string,
+  ): Promise<OpenOrder | null> {
+    const adapter = this._config.extendedAdapter;
+    const marketName = adapter.config.extendedMarketName;
+
+    let openOrder = await adapter.getOrderStatus(orderId, marketName);
+    if (openOrder) return openOrder;
+
+    for (let sr = 1; sr <= MAX_ORDER_STATUS_RETRIES; sr++) {
+      await new Promise((r) => setTimeout(r, ORDER_STATUS_RETRY_DELAY_MS));
+      openOrder = await adapter.getOrderStatus(orderId, marketName);
+      logger.debug(
+        `${this._tag}::_fetchExtendedOrderStatusWithRetries order=${orderId} status=${openOrder?.status} retry=${sr}`,
+      );
+      if (openOrder) return openOrder;
+    }
+    return null;
+  }
+
+  private async _cancelExtendedOrderIfOpen(
+    orderId: string,
+    knownOrder?: OpenOrder | null,
+  ): Promise<ExtendedCancelResolution> {
+    const adapter = this._config.extendedAdapter;
+    const marketName = adapter.config.extendedMarketName;
+    const latestOrder = knownOrder ?? await this._fetchExtendedOrderStatusWithRetries(orderId);
+
+    if (latestOrder?.status === OrderStatus.FILLED) {
+      logger.info(
+        `${this._tag}::_cancelExtendedOrderIfOpen order ${orderId} already FILLED — skip cancel`,
+      );
+      return { outcome: "filled", order: latestOrder };
+    }
+
+    if (
+      latestOrder &&
+      (
+        latestOrder.status === OrderStatus.CANCELLED ||
+        latestOrder.status === OrderStatus.EXPIRED ||
+        latestOrder.status === OrderStatus.REJECTED
+      )
+    ) {
+      logger.info(
+        `${this._tag}::_cancelExtendedOrderIfOpen order ${orderId} already ${latestOrder.status}`,
+      );
+      return { outcome: "cancelled", order: latestOrder };
+    }
+
+    const numericOrderId = Number(orderId);
+    if (!Number.isFinite(numericOrderId)) {
+      logger.warn(
+        `${this._tag}::_cancelExtendedOrderIfOpen invalid orderId="${orderId}" — cannot cancel`,
+      );
+      return { outcome: "failed", order: latestOrder ?? null };
+    }
+
+    try {
+      const cancelResult = await adapter.client.cancelOrderById(numericOrderId);
+      if (cancelResult.status !== "OK") {
+        logger.error(
+          `${this._tag}::_cancelExtendedOrderIfOpen cancel failed for order ${orderId}: ${cancelResult.message}`,
+        );
+        return { outcome: "failed", order: latestOrder ?? null };
+      }
+    } catch (err) {
+      logger.error(
+        `${this._tag}::_cancelExtendedOrderIfOpen cancel threw for order ${orderId}: ${err}`,
+      );
+      return { outcome: "failed", order: latestOrder ?? null };
+    }
+
+    const afterCancel = await this._fetchExtendedOrderStatusWithRetries(orderId);
+    if (!afterCancel) {
+      logger.warn(
+        `${this._tag}::_cancelExtendedOrderIfOpen no status after cancel for order ${orderId} on ${marketName}`,
+      );
+      return { outcome: "cancelled", order: null };
+    }
+
+    if (afterCancel.status === OrderStatus.FILLED) {
+      logger.warn(
+        `${this._tag}::_cancelExtendedOrderIfOpen order ${orderId} became FILLED during cancel`,
+      );
+      return { outcome: "filled", order: afterCancel };
+    }
+
+    if (afterCancel.status === OrderStatus.CANCELLED) {
+      logger.info(
+        `${this._tag}::_cancelExtendedOrderIfOpen cancelled order ${orderId} successfully`,
+      );
+      return { outcome: "cancelled", order: afterCancel };
+    }
+
+    logger.warn(
+      `${this._tag}::_cancelExtendedOrderIfOpen order ${orderId} status after cancel=${afterCancel.status}`,
+    );
+    return { outcome: "failed", order: afterCancel };
+  }
+
+  private async _executeExtendedLimitOrderWithRecovery(
+    btcAmount: number,
+    idealPrice: number,
+    side: OrderSide,
+    options?: {
+      maxAttempts?: number;
+      timeoutMs?: number;
+      contextTag?: string;
+    },
+  ): Promise<{
+    position_id: string;
+    btc_exposure: string;
+    executionPrice: number;
+  } | null> {
+    const maxAttempts = options?.maxAttempts ?? 1;
+    const contextTag = options?.contextTag ?? "_executeExtendedLimitOrderWithRecovery";
+    let createdOrderId: string | null = null;
+
+    const fillPromise = this._executeExtendedLimitOrder(
+      btcAmount,
+      idealPrice,
+      side,
+      maxAttempts,
+      {
+        onOrderCreated: (orderId) => {
+          createdOrderId = orderId;
+        },
+      },
+    );
+
+    let extResult: {
+      position_id: string;
+      btc_exposure: string;
+      executionPrice: number;
+    } | null = null;
+
+    if (options?.timeoutMs && options.timeoutMs > 0) {
+      const timeoutPromise = new Promise<null>((resolve) =>
+        setTimeout(() => resolve(null), options.timeoutMs),
+      );
+      logger.info(
+        `${this._tag}::${contextTag} racing Extended fill against ${options.timeoutMs}ms timeout`,
+      );
+      extResult = await Promise.race([fillPromise, timeoutPromise]);
+    } else {
+      extResult = await fillPromise;
+    }
+
+    if (extResult) {
+      return extResult;
+    }
+
+    if (!createdOrderId) {
+      logger.error(
+        `${this._tag}::${contextTag} no order created after fill attempt`,
+      );
+      return null;
+    }
+
+    logger.info(
+      `${this._tag}::${contextTag} fetching order status for order ${createdOrderId}`,
+    );
+    const knownOrder = await this._fetchExtendedOrderStatusWithRetries(createdOrderId);
+    if (knownOrder?.status === OrderStatus.FILLED) {
+      const executionPrice = parseFloat(
+        knownOrder.average_price || knownOrder.price || '0',
+      );
+      logger.info(
+        `${this._tag}::${contextTag} order ${createdOrderId} confirmed FILLED after assumed failure`,
+      );
+      return {
+        position_id: createdOrderId,
+        btc_exposure: knownOrder.qty,
+        executionPrice,
+      };
+    }
+
+    const cancelResolution = await this._cancelExtendedOrderIfOpen(
+      createdOrderId,
+      knownOrder,
+    );
+
+    if (cancelResolution.outcome === "filled") {
+      const filledOrder = cancelResolution.order;
+      const executionPrice = parseFloat(
+        filledOrder?.average_price || filledOrder?.price || '0',
+      );
+      logger.info(
+        `${this._tag}::${contextTag} order ${createdOrderId} filled during cancel path`,
+      );
+      return {
+        position_id: createdOrderId,
+        btc_exposure: filledOrder?.qty || btcAmount.toString(),
+        executionPrice,
+      };
+    }
+
+    if (cancelResolution.outcome === "failed") {
+      logger.warn(
+        `${this._tag}::${contextTag} failed to confirm cancel for order ${createdOrderId}`,
+      );
+    }
+    return null;
+  }
+
+  /** ExecutionRoute types that change BTC exposure (on-chain or off-chain). */
+  private static readonly EXPOSURE_CHANGING_ROUTES = new Set([
+    RouteType.AVNU_DEPOSIT_SWAP,
+    RouteType.AVNU_WITHDRAW_SWAP,
+    RouteType.VESU_MULTIPLY_INCREASE_LEVER,
+    RouteType.VESU_MULTIPLY_DECREASE_LEVER,
+    RouteType.EXTENDED_INCREASE_LEVER,
+    RouteType.EXTENDED_DECREASE_LEVER,
+  ]);
+
+  /** ExecutionRoute types that correspond to increasing delta-neutral exposure. */
+  private static readonly INCREASE_EXPOSURE_ROUTES = new Set([
+    RouteType.AVNU_DEPOSIT_SWAP,
+    RouteType.VESU_MULTIPLY_INCREASE_LEVER,
+    RouteType.EXTENDED_INCREASE_LEVER,
+  ]);
+
+  /** On-chain route types that change BTC exposure (Vesu side). */
+  private static readonly ON_CHAIN_EXPOSURE_ROUTES = new Set([
+    RouteType.AVNU_DEPOSIT_SWAP,
+    RouteType.AVNU_WITHDRAW_SWAP,
+    RouteType.VESU_MULTIPLY_INCREASE_LEVER,
+    RouteType.VESU_MULTIPLY_DECREASE_LEVER,
+  ]);
+
+  /** Off-chain Extended route types that change BTC exposure. */
+  private static readonly EXTENDED_EXPOSURE_ROUTES = new Set([
+    RouteType.EXTENDED_INCREASE_LEVER,
+    RouteType.EXTENDED_DECREASE_LEVER,
+  ]);
+
+  /**
+   * Validates that the price divergence between Extended (orderbook mid) and
+   * AVNU (actual on-chain swap price) is within acceptable limits.
+   *
+   * Mirrors the check from `checkPriceDifferenceBetweenAvnuAndExtended` in the
+   * strategy — see investmentOrchestrator.ts for the call-site pattern.
+   *
+   * For OPEN (increasing exposure): we SELL on Extended (short) and BUY on AVNU (long).
+   *   → Extended price should not be too far below AVNU price.
+   *   → (extendedMid − avnuPrice) / avnuPrice must be > −maxDivergence
+   *
+   * For CLOSE (decreasing exposure): we BUY on Extended (close short) and SELL on AVNU.
+   *   → Extended price should not be too far above AVNU price.
+   *   → (extendedMid − avnuPrice) / avnuPrice must be < +maxDivergence
+   *
+   * @param isIncreasingExposure true when opening/increasing delta-neutral position
+   * @throws if divergence exceeds configured maxPriceDivergenceBps
+   */
+  private async _validatePriceDivergence(
+    isIncreasingExposure: boolean,
+    executionPrice: number,
+  ): Promise<void> {
+    const { extendedAdapter } = this._config;
+
+    // 1. Extended mid price from orderbook
+    const { bid, ask } = await extendedAdapter.fetchOrderBookFromExtended();
+    if (bid.lessThanOrEqualTo(0) || ask.lessThanOrEqualTo(0)) {
+      logger.warn(
+        `${this._tag}::_validatePriceDivergence could not fetch valid orderbook — skipping check`,
+      );
+      return;
+    }
+    const extendedMidPrice = ask.plus(bid).div(2);
+
+    // 2. Compute divergence against actual execution price from adapter quotes
+    const priceDiff = extendedMidPrice.minus(executionPrice.toFixed(6)).toNumber();
+    const priceDiffPct = priceDiff / executionPrice;
+    const maxBps =
+      this._config.maxPriceDivergenceBps ?? DEFAULT_MAX_PRICE_DIVERGENCE_BPS;
+    const maxPctAllowed = maxBps / 10000;
+
+    // todo price is more subject to direction.
+    logger.info(
+      `${this._tag}::_validatePriceDivergence extendedMid=${extendedMidPrice.toNumber()} ` +
+      `vesuExecutionPrice=${executionPrice} diff=${priceDiff.toFixed(2)} ` +
+      `pct=${(priceDiffPct * 100).toFixed(3)}% maxAllowed=±${(maxPctAllowed * 100).toFixed(1)}% ` +
+      `isIncrease=${isIncreasingExposure}`,
+    );
+
+    if (isIncreasingExposure && priceDiffPct < -maxPctAllowed) {
+      throw new Error(
+        `Price divergence too large for OPEN: extendedMid − executionPrice = ${priceDiff.toFixed(2)} ` +
+        `(${(priceDiffPct * 100).toFixed(3)}%, limit: -${(maxPctAllowed * 100).toFixed(1)}%). ` +
+        `Extended=${extendedMidPrice.toNumber()}, executionPrice=${executionPrice}`,
+      );
+    }
+    if (!isIncreasingExposure && priceDiffPct > maxPctAllowed) {
+      throw new Error(
+        `Price divergence too large for CLOSE: extendedMid − executionPrice = ${priceDiff.toFixed(2)} ` +
+        `(${(priceDiffPct * 100).toFixed(3)}%, limit: +${(maxPctAllowed * 100).toFixed(1)}%). ` +
+        `Extended=${extendedMidPrice.toNumber()}, executionPrice=${executionPrice}`,
+      );
+    }
+  }
+
+  /**
+   * Computes the net weighted execution price (USDC per BTC) across all adapters
+   * that have a stored SwapPriceInfo from the most recent call build.
+   *
+   * For deposit (USDC→BTC): price = sum(USDC sold) / sum(BTC bought)
+   * For withdraw (BTC→USDC): price = sum(USDC bought) / sum(BTC sold)
+   */
+  private _getNetExecutionPrice(isDeposit: boolean): number | null {
+    const prices: SwapPriceInfo[] = [
+      this._config.avnuAdapter.lastSwapPriceInfo,
+      this._config.vesuAdapter.lastSwapPriceInfo,
+    ].filter((p): p is SwapPriceInfo => p !== null);
+
+    if (prices.length === 0) return null;
+
+    if (isDeposit) {
+      const totalUsdc = prices.reduce((s, p) => s + p.fromAmount, 0);
+      const totalBtc = prices.reduce((s, p) => s + p.toAmount, 0);
+      return totalBtc !== 0 ? totalUsdc / totalBtc : null;
+    } else {
+      const totalUsdc = prices.reduce((s, p) => s + p.toAmount, 0);
+      const totalBtc = prices.reduce((s, p) => s + p.fromAmount, 0);
+      return totalBtc !== 0 ? totalUsdc / totalBtc : null;
+    }
+  }
+
+  /** Clears cached swap price info on all adapters to prevent stale data across cycles. */
+  private _clearAdapterPriceInfo(): void {
+    this._config.avnuAdapter.lastSwapPriceInfo = null;
+    this._config.vesuAdapter.lastSwapPriceInfo = null;
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // Public API
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  /**
+   * Main entry point: takes a SolveResult and executes all cases in order,
+   * building the necessary transaction calls.
+   *
+   * - Cases are processed sequentially.
+   * - Within a case, on-chain calls are batched; off-chain calls flush the batch.
+   * - Dual-exchange exposure cases use the coordinated path (construct → estimate → fill Extended → send on-chain).
+   * - RETURN_TO_WAIT halts execution for the current case and all subsequent cases.
+   * - Execution stops on the first route failure.
+   *
+   * @param account Starknet account used for on-chain fee estimation in coordinated mode.
+   * @returns Ordered list of TransactionResults (one per batch/off-chain op).
+   */
+  async execute(solveResult: SolveResult, account: Account): Promise<TransactionResult[]> {
+    this._account = account;
+    this._pendingDepositRemaining = solveResult.pendingDeposit?.toNumber() ?? 0;
+    const results: TransactionResult[] = [];
+
+    if (solveResult.cases.length > 0) {
+      logger.info(
+        `${this._tag}::execute detected ${solveResult.cases.length} case(s): ` +
+        solveResult.cases.map((c) => `[${c.case.category}] ${c.case.id}`).join(', '),
+      );
+    }
+
+    for (const caseEntry of solveResult.cases) {
+      logger.info(
+        `${this._tag}::execute processing case "${caseEntry.case.id}" ` +
+        `(${caseEntry.routes.length} routes)`,
+      );
+
+      const caseResults = await this._executeCase(caseEntry);
+      results.push(...caseResults);
+
+      if (caseResults.some((r) => !r.status)) {
+        logger.error(
+          `${this._tag}::execute case "${caseEntry.case.id}" failed — stopping`,
+        );
+        break;
+      }
+
+      if (this._caseHitReturnToWait(caseEntry.routes)) {
+        logger.info(
+          `${this._tag}::execute case "${caseEntry.case.id}" hit RETURN_TO_WAIT — stopping all execution`,
+        );
+        break;
+      }
+    }
+
+    const failedCount = results.filter((r) => !r.status).length;
+    logger.info(
+      `${this._tag}::execute completed cases=${solveResult.cases.length} results=${results.length} failed=${failedCount}`,
+    );
+
+    return results;
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // Private — case-level execution
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  /**
+   * Executes a single case's routes.
+   *
+   * First splits routes at the first RETURN_TO_WAIT into an "active window"
+   * (routes that will execute this cycle). If the active window contains both
+   * on-chain and off-chain exposure routes, delegates to the coordinated
+   * dual-exchange path. Otherwise, uses the standard route-by-route flow.
+   */
+  private async _executeCase(
+    caseEntry: SolveCaseEntry,
+  ): Promise<TransactionResult[]> {
+    const routes = [...caseEntry.routes].sort((a, b) => a.priority - b.priority);
+
+    // ── Split at first RETURN_TO_WAIT ─────────────────────────────────
+    const waitIdx = routes.findIndex((r) => r.type === RouteType.RETURN_TO_WAIT);
+    const activeRoutes = waitIdx >= 0 ? routes.slice(0, waitIdx) : routes;
+    const hasReturnToWait = waitIdx >= 0;
+
+    // ── Branch: coordinated dual-exchange path ────────────────────────
+    if (this._isDualExchangeCase(activeRoutes)) {
+      logger.info(
+        `${this._tag}::_executeCase case "${caseEntry.case.id}" → coordinated dual-exchange path` +
+        (hasReturnToWait ? ' (RETURN_TO_WAIT present, will halt after)' : ''),
+      );
+      return this._executeCoordinatedCase(caseEntry, activeRoutes);
+    }
+
+    // ── Standard route-by-route flow (unchanged) ─────────────────────
+    return this._executeStandardCase(caseEntry, routes);
+  }
+
+  /**
+   * Standard route-by-route execution for non-coordinated cases.
+   *
+   * On-chain routes are accumulated into a Call[] batch. When an off-chain
+   * route or RETURN_TO_WAIT is encountered, the batch is flushed first.
+   */
+  private async _executeStandardCase(
+    caseEntry: SolveCaseEntry,
+    routes: ExecutionRoute[],
+  ): Promise<TransactionResult[]> {
+    const results: TransactionResult[] = [];
+    this._clearAdapterPriceInfo();
+
+    try {
+      // ── Phase 1: Pre-build all on-chain calls (triggers quote fetches) ──
+      const prebuiltCalls = new Map<number, Call[]>();
+      for (let i = 0; i < routes.length; i++) {
+        const route = routes[i];
+        if (route.type === RouteType.RETURN_TO_WAIT) break;
+        if (this._isOnChainRoute(route)) {
+          try {
+            prebuiltCalls.set(i, await this._buildOnChainCalls(route));
+          } catch (err) {
+            logger.error(
+              `${this._tag}::_executeStandardCase on-chain build failed for ${route.type}: ${err}`,
+            );
+            results.push(this._failureResult(route));
+            return results;
+          }
+        }
+      }
+
+
+
+      // ── Phase 2: Execute routes using pre-built calls ──
+      let batchCalls: Call[] = [];
+
+      for (let i = 0; i < routes.length; i++) {
+        const route = routes[i];
+        logger.info(
+          `${this._tag}::_executeStandardCase route ${route.type} ${routeSummary(route)}`,
+        );
+
+        if (route.type === RouteType.RETURN_TO_WAIT) {
+          if (batchCalls.length > 0) {
+            results.push(this._onChainBatchResult(batchCalls));
+            batchCalls = [];
+          }
+          logger.info(
+            `${this._tag}::_executeStandardCase RETURN_TO_WAIT — halting case "${caseEntry.case.id}"`,
+          );
+          break;
+        }
+
+        if (this._isOnChainRoute(route)) {
+          const calls = prebuiltCalls.get(i);
+          if (calls) batchCalls.push(...calls);
+          continue;
+        }
+
+        // Off-chain route → flush batch, then execute
+        if (batchCalls.length > 0) {
+          const batchResult = this._onChainBatchResult(batchCalls);
+          results.push(batchResult);
+          await this._emitEvent(ExecutionEventType.INITIATED, {
+            routeSummary: `on-chain batch (${batchCalls.length} calls)`,
+            calls: batchCalls,
+          });
+          batchCalls = [];
+        }
+
+        try {
+          const result = await this._executeOffChainRoute(route);
+          if (result) {
+            results.push(result);
+            if (!result.status) return results;
+          }
+        } catch (err) {
+          logger.error(
+            `${this._tag}::_executeStandardCase off-chain route ${route.type} threw: ${err}`,
+          );
+          await this._emitEvent(ExecutionEventType.FAILURE, {
+            routeType: route.type,
+            error: `${err}`,
+          });
+          results.push(this._failureResult(route));
+          return results;
+        }
+      }
+
+      // Flush remaining on-chain calls
+      if (batchCalls.length > 0) {
+        const batchResult = this._onChainBatchResult(batchCalls);
+        results.push(batchResult);
+        await this._emitEvent(ExecutionEventType.INITIATED, {
+          routeSummary: `on-chain batch (${batchCalls.length} calls)`,
+          calls: batchCalls,
+        });
+      }
+
+      return results;
+    } finally {
+      this._clearAdapterPriceInfo();
+    }
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // Private — coordinated dual-exchange execution
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  /**
+   * Coordinated execution for cases that touch both Vesu (on-chain) and
+   * Extended (off-chain) exposure in the same case.
+   *
+   * Flow:
+   *  1. Partition active routes into on-chain vs Extended
+   *  2. Construct all on-chain calls in parallel
+   *  3. Estimate on-chain batch (dry-run via account.estimateInvokeFee)
+   *  4. Validate price divergence between Extended and AVNU
+   *  5. Race Extended limit order fill against timeout
+   *  6. If filled → return Extended result + on-chain batch
+   *     If timeout/failure → drop everything
+   *
+   * // TODO: If Extended fills but the orchestrator's on-chain multicall later
+   * // reverts, we have an unhedged Extended position. The orchestrator should
+   * // catch the on-chain failure, re-solve with updated state to recompute
+   * // necessary on-chain calls, and retry. This recovery is non-trivial and
+   * // should be implemented as a follow-up.
+   */
+  private async _executeCoordinatedCase(
+    caseEntry: SolveCaseEntry,
+    activeRoutes: ExecutionRoute[],
+  ): Promise<TransactionResult[]> {
+    const results: TransactionResult[] = [];
+    this._clearAdapterPriceInfo();
+
+    try {
+      // ── Step 1: Partition routes ──────────────────────────────────────
+      const onChainRoutes = activeRoutes.filter((r) => this._isOnChainRoute(r));
+      const extendedRoute = activeRoutes.find((r) =>
+        ExecutionService.EXTENDED_EXPOSURE_ROUTES.has(r.type),
+      ) as ExtendedLeverRoute | undefined;
+
+      if (!extendedRoute) {
+        logger.error(
+          `${this._tag}::_executeCoordinatedCase no Extended exposure route found ` +
+          `in case "${caseEntry.case.id}" — falling back to standard path`,
+        );
+        return this._executeStandardCase(caseEntry, activeRoutes);
+      }
+
+      // set extended leverage
+      const setLevResult = await this._config.extendedAdapter.setLeverage(calculateExtendedLevergae().toString(), this._config.extendedAdapter.config.extendedMarketName);
+      if (!setLevResult) {
+        logger.error(
+          `${this._tag}::_executeCoordinatedCase failed to set leverage`,
+        );
+        results.push(this._failureResult(extendedRoute));
+        return results;
+      }
+
+      const isIncrease = ExecutionService.INCREASE_EXPOSURE_ROUTES.has(
+        extendedRoute.type,
+      );
+      const side = isIncrease ? OrderSide.SELL : OrderSide.BUY;
+      const btcAmount = extendedRoute.amount.toNumber();
+
+      logger.info(
+        `${this._tag}::_executeCoordinatedCase case="${caseEntry.case.id}" ` +
+        `onChainRoutes=${onChainRoutes.length} extended=${extendedRoute.type} ` +
+        `side=${side} btcAmount=${btcAmount}`,
+      );
+
+      // ── Step 2: Construct all on-chain calls in parallel ─────────────
+      let onChainCalls: Call[];
+      try {
+        const callArrays = await Promise.all(
+          onChainRoutes.map(async (r) => {
+            const output = await this._buildOnChainCalls(r);
+            logger.verbose(`${this._tag}::_executeCoordinatedCase on-chain call construction output: ${r.type} ${JSON.stringify(output)}`);
+            return output;
+          }),
+        );
+        onChainCalls = callArrays.flat();
+      } catch (err) {
+        logger.error(
+          `${this._tag}::_executeCoordinatedCase on-chain call construction failed: ${err}`,
+        );
+        await this._emitEvent(ExecutionEventType.FAILURE, {
+          routeSummary: `coordinated on-chain build for case "${caseEntry.case.id}"`,
+          error: `${err}`,
+        });
+        results.push(this._failureResult(extendedRoute));
+        return results;
+      }
+
+      if (onChainCalls.length === 0) {
+        logger.warn(
+          `${this._tag}::_executeCoordinatedCase on-chain routes produced 0 calls — aborting`,
+        );
+        results.push(this._failureResult(extendedRoute));
+        return results;
+      }
+
+      // ── Step 3: Estimate on-chain batch ──────────────────────────────
+      try {
+        await this._account!.estimateInvokeFee(onChainCalls);
+        logger.info(
+          `${this._tag}::_executeCoordinatedCase on-chain estimation passed ` +
+          `(${onChainCalls.length} calls)`,
+        );
+      } catch (err) {
+        logger.error(
+          `${this._tag}::_executeCoordinatedCase on-chain estimation failed: ${err}`,
+        );
+        await this._emitEvent(ExecutionEventType.FAILURE, {
+          routeSummary: `coordinated estimation for case "${caseEntry.case.id}"`,
+          error: `${err}`,
+        });
+        results.push(this._failureResult(extendedRoute));
+        return results;
+      }
+
+      // ── Step 4: Resolve ideal execution price and validate divergence when swap is present ──
+      const hasVesuSwapRoute = onChainRoutes.some(
+        (r) =>
+          r.type === RouteType.VESU_MULTIPLY_INCREASE_LEVER ||
+          r.type === RouteType.VESU_MULTIPLY_DECREASE_LEVER
+      );
+      const netExecutionPrice = this._getNetExecutionPrice(isIncrease);
+      let executionPrice: number;
+
+      if (hasVesuSwapRoute) {
+        if (netExecutionPrice === null) {
+          const errMsg =
+            `Swap route present but execution price unavailable after on-chain call build`;
+          logger.error(`${this._tag}::_executeCoordinatedCase ${errMsg}`);
+          results.push(this._failureResult(extendedRoute));
+          return results;
+        }
+        executionPrice = netExecutionPrice;
+        try {
+          await this._validatePriceDivergence(isIncrease, executionPrice);
+        } catch (err) {
+          logger.error(
+            `${this._tag}::_executeCoordinatedCase price divergence check failed: ${err}`,
+          );
+          await this._emitEvent(ExecutionEventType.FAILURE, {
+            routeSummary: `coordinated price divergence for case "${caseEntry.case.id}"`,
+            error: `${err}`,
+          });
+          results.push(this._failureResult(extendedRoute));
+          return results;
+        }
+      } else {
+        const { bid, ask } = await this._config.extendedAdapter.fetchOrderBookFromExtended();
+        if (bid.lessThanOrEqualTo(0) || ask.lessThanOrEqualTo(0)) {
+          const errMsg =
+            `No AVNU swap route and invalid Extended orderbook for fallback price`;
+          logger.error(`${this._tag}::_executeCoordinatedCase ${errMsg}`);
+          results.push(this._failureResult(extendedRoute));
+          return results;
+        }
+        executionPrice = ask.plus(bid).div(2).toNumber();
+        logger.info(
+          `${this._tag}::_executeCoordinatedCase using Extended mid-price fallback=${executionPrice} (no AVNU swap route)`,
+        );
+      }
+
+      // debug
+      // if (1) throw new Error(`${this._tag}::_executeCoordinatedCase price divergence check passed, executionPrice: ${executionPrice}`);
+
+      // ── Step 5: Fill Extended with timeout ────────────────────────────
+      const timeoutMs =
+        this._config.extendedFillTimeoutMs ?? DEFAULT_EXTENDED_FILL_TIMEOUT_MS;
+      const extResult = await this._executeExtendedLimitOrderWithRecovery(
+        btcAmount,
+        executionPrice,
+        side,
+        {
+          maxAttempts: 1,
+          timeoutMs,
+          contextTag: "_executeCoordinatedCase",
+        },
+      );
+
+      if (!extResult) {
+        logger.error(
+          `${this._tag}::_executeCoordinatedCase Extended fill failed or timed out ` +
+          `— dropping all calls for case "${caseEntry.case.id}"`,
+        );
+        await this._emitEvent(ExecutionEventType.FAILURE, {
+          routeSummary: `coordinated Extended fill for case "${caseEntry.case.id}"`,
+          error: 'Extended fill failed or timed out',
+        });
+        results.push(this._failureResult(extendedRoute));
+        return results;
+      }
+
+      // ── Step 6: Extended filled — return results ─────────────────────
+      logger.info(
+        `${this._tag}::_executeCoordinatedCase Extended filled ` +
+        `orderId=${extResult.position_id} execPrice=${extResult.executionPrice} ` +
+        `— returning on-chain batch (${onChainCalls.length} calls)`,
+      );
+
+      await this._emitEvent(ExecutionEventType.SUCCESS, {
+        routeType: extendedRoute.type,
+        orderId: extResult.position_id,
+        amount: extResult.btc_exposure,
+        executionPrice: extResult.executionPrice,
+        protocol: 'EXTENDED',
+      });
+
+      const extendedTxResult = this._successResult(
+        [],
+        isIncrease ? Protocols.NONE.name : Protocols.EXTENDED.name,
+        isIncrease ? Protocols.EXTENDED.name : Protocols.NONE.name,
+        isIncrease ? "DEPOSIT" : "WITHDRAWAL",
+        extendedRoute.amount,
+        CycleType.INVESTMENT,
+      );
+      results.push(extendedTxResult);
+
+      const onChainBatchResult = this._onChainBatchResult(onChainCalls);
+      results.push(onChainBatchResult);
+      await this._emitEvent(ExecutionEventType.INITIATED, {
+        routeSummary: `coordinated on-chain batch (${onChainCalls.length} calls)`,
+        calls: onChainCalls,
+      });
+
+      return results;
+    } finally {
+      this._clearAdapterPriceInfo();
+    }
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // Private — route classification
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  /** Returns true if the route produces Starknet Call objects (on-chain tx). */
+  private _isOnChainRoute(route: ExecutionRoute): boolean {
+    switch (route.type) {
+      case RouteType.WALLET_TO_EXTENDED:
+      case RouteType.VA_TO_EXTENDED:
+      case RouteType.WALLET_TO_VA:
+      case RouteType.AVNU_DEPOSIT_SWAP:
+      case RouteType.AVNU_WITHDRAW_SWAP:
+      case RouteType.VESU_MULTIPLY_INCREASE_LEVER:
+      case RouteType.VESU_MULTIPLY_DECREASE_LEVER:
+      case RouteType.VESU_BORROW:
+      case RouteType.VESU_REPAY:
+      case RouteType.BRING_LIQUIDITY:
+      case RouteType.CRISIS_BORROW_BEYOND_TARGET_HF:
+        return true;
+      default:
+        return false;
+    }
+  }
+
+  /** Checks whether any route in the list is a RETURN_TO_WAIT sentinel. */
+  private _caseHitReturnToWait(routes: ExecutionRoute[]): boolean {
+    return routes.some((r) => r.type === RouteType.RETURN_TO_WAIT);
+  }
+
+  /**
+   * Returns true when the active window contains both on-chain exposure
+   * routes (Vesu/AVNU) and off-chain Extended exposure routes — meaning
+   * both exchanges participate in the same exposure change and should be
+   * executed via the coordinated (fill-or-abort) path.
+   */
+  private _isDualExchangeCase(activeRoutes: ExecutionRoute[]): boolean {
+    const hasOnChainExposure = activeRoutes.some((r) =>
+      ExecutionService.ON_CHAIN_EXPOSURE_ROUTES.has(r.type),
+    );
+    const hasExtendedExposure = activeRoutes.some((r) =>
+      ExecutionService.EXTENDED_EXPOSURE_ROUTES.has(r.type),
+    );
+    return hasOnChainExposure && hasExtendedExposure;
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // Private — on-chain call builders (return Call[])
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  /** Dispatches an on-chain route to the appropriate call builder. */
+  private async _buildOnChainCalls(route: ExecutionRoute): Promise<Call[]> {
+    switch (route.type) {
+      case RouteType.WALLET_TO_EXTENDED:
+        return this._buildWalletToExtendedCalls(route as TransferRoute);
+      case RouteType.VA_TO_EXTENDED:
+        return this._buildVAToExtendedCalls(route as TransferRoute);
+      case RouteType.WALLET_TO_VA:
+        return this._buildWalletToVACalls(route as TransferRoute);
+      case RouteType.AVNU_DEPOSIT_SWAP:
+        return this._buildAvnuDepositSwapCalls(route as SwapRoute);
+      case RouteType.AVNU_WITHDRAW_SWAP:
+        return this._buildAvnuWithdrawSwapCalls(route as SwapRoute);
+      case RouteType.VESU_MULTIPLY_INCREASE_LEVER:
+        return this._buildVesuIncreaseLeverCalls(route as VesuMultiplyRoute);
+      case RouteType.VESU_MULTIPLY_DECREASE_LEVER:
+        return this._buildVesuDecreaseLeverCalls(route as VesuMultiplyRoute);
+      case RouteType.VESU_BORROW:
+        return this._buildVesuBorrowCalls(route as VesuDebtRoute);
+      case RouteType.VESU_REPAY:
+        return this._buildVesuRepayCalls(route as VesuDebtRoute);
+      case RouteType.BRING_LIQUIDITY:
+        return this._buildBringLiquidityCalls(route as BringLiquidityRoute);
+      case RouteType.CRISIS_BORROW_BEYOND_TARGET_HF:
+        return this._buildCrisisBorrowCalls(route as CrisisBorrowRoute);
+      default:
+        logger.warn(
+          `${this._tag}::_buildOnChainCalls unhandled route type: ${route.type}`,
+        );
+        return [];
+    }
+  }
+
+  // ── Transfer routes ─────────────────────────────────────────────────────
+
+  /**
+   * WALLET_TO_EXTENDED: Deposit USDC.e from operator wallet directly to Extended.
+   *
+   * Builds raw approve + deposit calls (NOT through the manager/merkle system)
+   * because the wallet interacts with Extended directly, not via vault allocator.
+   *
+   * Adjusts amount by pending deposit to avoid double-sending.
+   */
+  private async _buildWalletToExtendedCalls(
+    route: TransferRoute,
+  ): Promise<Call[]> {
+    const amount = this._consumePendingDeposit(route.amount);
+    if (amount.lessThanOrEqualTo(0)) {
+      logger.info(
+        `${this._tag}::_buildWalletToExtendedCalls skipped — pending deposit covers amount`,
+      );
+      return [];
+    }
+
+    const { usdceToken, extendedAdapter } = this._config;
+    const extendedContract = extendedAdapter.config.extendedContract;
+    const vaultId = extendedAdapter.config.vaultIdExtended;
+    const salt = Math.floor(Math.random() * 10 ** usdceToken.decimals);
+    const uint256Amount = uint256.bnToUint256(amount.toWei());
+
+    const approveCall: Call = {
+      contractAddress: usdceToken.address.address,
+      entrypoint: "approve",
+      calldata: [
+        extendedContract.address,
+        uint256Amount.low.toString(),
+        uint256Amount.high.toString(),
+      ],
+    };
+
+    const depositCall: Call = {
+      contractAddress: extendedContract.address,
+      entrypoint: "deposit",
+      calldata: [
+        vaultId.toString(),
+        amount.toWei(),
+        salt.toString(),
+      ],
+    };
+
+    logger.info(
+      `${this._tag}::_buildWalletToExtendedCalls built raw approve+deposit ` +
+      `amount=${amount.toNumber()} to Extended contract=${extendedContract.shortString()}`,
+    );
+
+    return [approveCall, depositCall];
+  }
+
+  /**
+   * VA_TO_EXTENDED: Deposit USDC.e from vault allocator to Extended.
+   *
+   * Uses the extended adapter's getDepositCall to build ManageCalls,
+   * then wraps them in a merkle-verified manage call through the manager contract.
+   *
+   * Adjusts amount by pending deposit to avoid double-sending.
+   */
+  private async _buildVAToExtendedCalls(
+    route: TransferRoute,
+  ): Promise<Call[]> {
+    const amount = this._consumePendingDeposit(route.amount);
+    if (amount.lessThanOrEqualTo(0)) {
+      logger.info(
+        `${this._tag}::_buildVAToExtendedCalls skipped — pending deposit covers amount`,
+      );
+      return [];
+    }
+
+    // swap call (usdc to usdce)
+    const swapCall = await this._buildAdapterManageCall(
+      this._config.usdcToUsdceAdapter,
+      true,
+      { amount },
+    );
+    const manageCall = await this._buildAdapterManageCall(
+      this._config.extendedAdapter,
+      true,
+      { amount },
+    );
+    return [swapCall, manageCall];
+  }
+
+  /**
+   * WALLET_TO_VA: Transfer USDC.e from operator wallet to vault allocator.
+   * Caps amount by actual wallet balance.
+   */
+  private async _buildWalletToVACalls(
+    route: TransferRoute,
+  ): Promise<Call[]> {
+    const erc20 = new ERC20(this._config.networkConfig);
+    const { usdceToken, vaultAllocator, walletAddress } = this._config;
+
+    // checking balance could be unnecesary overhead. hence removed removed for now.
+
+    const transferAmount = route.amount;
+    if (transferAmount.lessThanOrEqualTo(0)) {
+      logger.warn(
+        `${this._tag}::_buildWalletToVACalls no USDC.e in wallet to transfer`,
+      );
+      return [];
+    }
+
+    // todo, give infinite approval to VA and extended contract
+    // for USDC.e for wallet account.
+
+    const transferCall = await this._buildAdapterManageCall(
+      this._config.usdceTransferAdapter,
+      false,
+      { amount: transferAmount },
+    );
+    // swap call (usdc to usdce)
+    const swapCall = await this._buildAdapterManageCall(
+      this._config.usdcToUsdceAdapter,
+      false,
+      { amount: transferAmount },
+    );
+    return [transferCall, swapCall];
+  }
+
+  // ── AVNU swap routes ────────────────────────────────────────────────────
+
+  /**
+   * AVNU_DEPOSIT_SWAP: Standalone USDC → BTC swap via AVNU.
+   *
+   * Uses avnu adapter's getDepositCall to build swap ManageCalls,
+   * then wraps in a merkle-verified manage call.
+   * Applies 0.1% buffer so downstream Vesu deposit has sufficient BTC.
+   */
+  private async _buildAvnuDepositSwapCalls(
+    route: SwapRoute,
+  ): Promise<Call[]> {
+    // @deprecated
+    // BCZ, we now use vesu multiply margin swap
+
+    // logger.verbose(`${this._tag}::_buildAvnuDepositSwapCalls fromAmount: ${route.fromAmount.toNumber()}`);
+    // const manageCall = await this._buildAdapterManageCall(
+    //   this._config.avnuAdapter,
+    //   true,
+    //   route.fromAmount,
+    // );
+    // return [manageCall];
+    return [];
+  }
+
+  /**
+   * AVNU_WITHDRAW_SWAP: Standalone BTC → USDC swap via AVNU.
+   *
+   * Uses avnu adapter's getWithdrawCall to build swap ManageCalls,
+   * then wraps in a merkle-verified manage call.
+   * Applies 0.1% buffer so Vesu-returned BTC is sufficient for the swap.
+   */
+  private async _buildAvnuWithdrawSwapCalls(
+    route: SwapRoute,
+  ): Promise<Call[]> {
+    // @deprecated
+    // BCZ, we now use vesu multiply withdraw swap
+
+    // const fromAmount =
+    //   route.fromAmount.toNumber() > 0
+    //     ? route.fromAmount
+    //     : new Web3Number(0, this._config.wbtcToken.decimals);
+    // if (fromAmount.lessThanOrEqualTo(0)) {
+    //   logger.warn(
+    //     `${this._tag}::_buildAvnuWithdrawSwapCalls fromAmount=0 — skipping`,
+    //   );
+    //   return [];
+    // }
+
+    // const bufferedAmount = this._applyAvnuBuffer(
+    //   fromAmount,
+    //   this._config.wbtcToken.decimals,
+    // );
+    // const manageCall = await this._buildAdapterManageCall(
+    //   this._config.avnuAdapter,
+    //   false,
+    //   bufferedAmount,
+    // );
+    // return [manageCall];
+    return [];
+  }
+
+  // ── Vesu multiply routes ───────────────────────────────────────────────
+
+  /**
+   * VESU_MULTIPLY_INCREASE_LEVER: Compound operation.
+   *  1. AVNU swap USDC → BTC (with 0.1% buffer on collateral amount)
+   *  2. Vesu multiply deposit — add BTC as collateral (triggers flash-loan leverage)
+   *
+   * Both steps go through the merkle-verified manager contract via their respective adapters.
+   */
+  private async _buildVesuIncreaseLeverCalls(
+    route: VesuMultiplyRoute,
+  ): Promise<Call[]> {
+    // const bufferedCollateral = this._applyAvnuBuffer(
+    //   route.collateralAmount,
+    //   route.collateralToken.decimals,
+    // );
+
+    const depositManageCall = await this._buildAdapterManageCall(
+      this._config.vesuAdapter,
+      true,
+      {
+        amount: route.marginAmount,
+        marginSwap: {
+          marginToken: this._config.vesuAdapter.config.marginToken, // todo, must be vault token
+        },
+        leverSwap: {
+          exactOutput: route.swappedCollateralAmount,
+        },
+      },
+    );
+    return [depositManageCall];
+  }
+
+  /**
+   * VESU_MULTIPLY_DECREASE_LEVER: Compound operation.
+   *  1. Vesu multiply withdraw — reduce BTC collateral (repays proportional debt via flash-loan)
+   *  2. AVNU swap BTC → USDC (with 0.1% buffer to account for slippage)
+   *
+   * Both steps go through the merkle-verified manager contract via their respective adapters.
+   */
+  private async _buildVesuDecreaseLeverCalls(
+    route: VesuMultiplyRoute,
+  ): Promise<Call[]> {
+    const collateralAmount = route.marginAmount.abs();
+
+    const withdrawManageCall = await this._buildAdapterManageCall(
+      this._config.vesuAdapter,
+      false,
+      {
+        amount: collateralAmount,
+        withdrawSwap: { outputToken: this._config.vesuAdapter.config.marginToken },
+      },
+    );
+    return [withdrawManageCall];
+  }
+
+  // ── Vesu debt routes ───────────────────────────────────────────────────
+
+  private _validateVesuDebtRoute(route: VesuDebtRoute): void {
+    const adapterConfig = this._config.vesuModifyPositionAdapter.config;
+    if (!adapterConfig.poolId.eq(route.poolId)) {
+      throw new Error(
+        `${this._tag}::_validateVesuDebtRoute pool mismatch: route=${route.poolId.shortString()} adapter=${adapterConfig.poolId.shortString()}`,
+      );
+    }
+    if (!adapterConfig.collateral.address.eq(route.collateralToken.address)) {
+      throw new Error(
+        `${this._tag}::_validateVesuDebtRoute collateral mismatch: route=${route.collateralToken.symbol} adapter=${adapterConfig.collateral.symbol}`,
+      );
+    }
+    if (!adapterConfig.debt.address.eq(route.debtToken.address)) {
+      throw new Error(
+        `${this._tag}::_validateVesuDebtRoute debt mismatch: route=${route.debtToken.symbol} adapter=${adapterConfig.debt.symbol}`,
+      );
+    }
+  }
+
+  /**
+   * VESU_BORROW: Borrow additional USDC from Vesu.
+   */
+  private async _buildVesuBorrowCalls(
+    route: VesuDebtRoute,
+  ): Promise<Call[]> {
+    this._validateVesuDebtRoute(route);
+    const debtAmount = route.amount.abs();
+    if (debtAmount.lessThanOrEqualTo(0)) {
+      logger.info(`${this._tag}::_buildVesuBorrowCalls skipped amount <= 0`);
+      return [];
+    }
+
+    const zeroCollateralAmount = new Web3Number(
+      0,
+      this._config.vesuModifyPositionAdapter.config.collateral.decimals,
+    );
+    const params: VesuModifyPositionDepositParams = {
+      amount: zeroCollateralAmount,
+      debtAmount,
+    };
+    const manageCall =
+      await this._buildAdapterManageCall<VesuModifyPositionDepositParams>(
+        this._config.vesuModifyPositionAdapter,
+        true,
+        params,
+      );
+    return [manageCall];
+  }
+
+  /**
+   * VESU_REPAY: Repay USDC debt to Vesu.
+   */
+  private async _buildVesuRepayCalls(
+    route: VesuDebtRoute,
+  ): Promise<Call[]> {
+    this._validateVesuDebtRoute(route);
+    const debtAmount = route.amount.abs();
+    if (debtAmount.lessThanOrEqualTo(0)) {
+      logger.info(`${this._tag}::_buildVesuRepayCalls skipped amount <= 0`);
+      return [];
+    }
+
+    const zeroCollateralAmount = new Web3Number(
+      0,
+      this._config.vesuModifyPositionAdapter.config.collateral.decimals,
+    );
+    const params: VesuModifyPositionWithdrawParams = {
+      amount: zeroCollateralAmount,
+      debtAmount,
+    };
+    const manageCall =
+      await this._buildAdapterManageCall<VesuModifyPositionWithdrawParams>(
+        this._config.vesuModifyPositionAdapter,
+        false,
+        params,
+      );
+    return [manageCall];
+  }
+
+  // ── Bring liquidity route ──────────────────────────────────────────────
+
+  /** BRING_LIQUIDITY: Transfer from VA to vault contract for user withdrawals. */
+  private async _buildBringLiquidityCalls(
+    route: BringLiquidityRoute,
+  ): Promise<Call[]> {
+    const bringLiquidityCall = await this._config.getBringLiquidityCall({
+      amount: route.amount,
+    });
+    return [bringLiquidityCall];
+  }
+
+  // ── Crisis routes ──────────────────────────────────────────────────────
+
+  /**
+   * CRISIS_BORROW_BEYOND_TARGET_HF: Borrow beyond normal target HF.
+   * TODO: Implement crisis borrow flow when needed.
+   */
+  private async _buildCrisisBorrowCalls(
+    _route: CrisisBorrowRoute,
+  ): Promise<Call[]> {
+    // TODO: Implement crisis borrow calls
+    throw new Error(
+      `${this._tag}::_buildCrisisBorrowCalls not yet implemented`,
+    );
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // Private — off-chain route executors
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  /** Dispatches an off-chain route to the appropriate executor. */
+  private async _executeOffChainRoute(
+    route: ExecutionRoute,
+  ): Promise<TransactionResult | null> {
+    switch (route.type) {
+      case RouteType.EXTENDED_TO_WALLET:
+        return this._executeExtendedToWallet(route as TransferRoute);
+      case RouteType.REALISE_PNL:
+        return this._executeRealisePnl(route as RealisePnlRoute);
+      case RouteType.EXTENDED_INCREASE_LEVER:
+        return this._executeExtendedIncreaseLever(route as ExtendedLeverRoute);
+      case RouteType.EXTENDED_DECREASE_LEVER:
+        return this._executeExtendedDecreaseLever(route as ExtendedLeverRoute);
+      case RouteType.CRISIS_INCREASE_EXTENDED_MAX_LEVERAGE:
+        return this._executeCrisisIncreaseLeverage();
+      case RouteType.CRISIS_UNDO_EXTENDED_MAX_LEVERAGE:
+        return this._executeCrisisUndoLeverage();
+      default:
+        logger.warn(
+          `${this._tag}::_executeOffChainRoute unhandled route type: ${route.type}`,
+        );
+        return null;
+    }
+  }
+
+  // ── Extended withdrawal ─────────────────────────────────────────────────
+
+  /**
+   * EXTENDED_TO_WALLET: Withdraw from Extended exchange to operator wallet.
+   *
+   * This initiates the off-chain withdrawal API call. When followed by
+   * RETURN_TO_WAIT, the executor will halt and the next solve cycle picks up
+   * once the withdrawal settles and wallet balance is updated.
+   *
+   * If a pending withdrawal is already in transit (pendingDeposit < 0),
+   * the amount is reduced accordingly.
+   */
+  private async _executeExtendedToWallet(
+    route: TransferRoute,
+  ): Promise<TransactionResult> {
+    let amount = route.amount;
+
+    if (this._pendingDepositRemaining < 0) {
+      const alreadyWithdrawing = Math.abs(this._pendingDepositRemaining);
+      const adjusted = amount.toNumber() - alreadyWithdrawing;
+      if (adjusted <= 0) {
+        logger.info(
+          `${this._tag}::_executeExtendedToWallet skipped — pending withdrawal covers ${route.amount.toNumber()}`,
+        );
+        this._pendingDepositRemaining += amount.toNumber();
+        return this._successResult(
+          [],
+          Protocols.EXTENDED.name,
+          Protocols.NONE.name,
+          "WITHDRAWAL",
+          route.amount,
+          CycleType.INVESTMENT,
+        );
+      }
+      this._pendingDepositRemaining = 0;
+      amount = new Web3Number(
+        adjusted.toFixed(this._config.usdcToken.decimals),
+        this._config.usdcToken.decimals,
+      );
+    }
+
+    await this._emitEvent(ExecutionEventType.INITIATED, {
+      routeType: RouteType.EXTENDED_TO_WALLET,
+      protocol: 'EXTENDED',
+      amount: amount.toNumber().toString(),
+      routeSummary: `withdraw ${amount.toNumber()} from Extended`,
+    });
+
+    const { status } =
+      await this._config.extendedAdapter.withdrawFromExtended(amount);
+
+    if (!status) {
+      logger.error(
+        `${this._tag}::_executeExtendedToWallet withdrawal request failed`,
+      );
+      await this._emitEvent(ExecutionEventType.FAILURE, {
+        routeType: RouteType.EXTENDED_TO_WALLET,
+        error: 'Withdrawal request failed',
+      });
+      return this._failureResult(route);
+    }
+
+    logger.info(
+      `${this._tag}::_executeExtendedToWallet initiated withdrawal of ${amount.toNumber()}`,
+    );
+
+    await this._emitEvent(ExecutionEventType.SUCCESS, {
+      routeType: RouteType.EXTENDED_TO_WALLET,
+      amount: amount.toNumber().toString(),
+      protocol: 'EXTENDED',
+    });
+
+    return this._successResult(
+      [],
+      Protocols.EXTENDED.name,
+      Protocols.NONE.name,
+      "WITHDRAWAL",
+      amount,
+      CycleType.INVESTMENT,
+    );
+  }
+
+  // ── Realise PnL ─────────────────────────────────────────────────────────
+
+  /**
+   * REALISE_PNL: Converts unrealised PnL to realised by closing a portion
+   * of the short position and immediately reopening it.
+   *
+   * Uses {@link calculatePositionToCloseToWithdrawAmount} to determine the
+   * minimal position size to close so that the required amount becomes
+   * available for withdrawal.
+   *
+   * Both close and reopen orders use limit pricing via _executeExtendedLimitOrder.
+   *
+   * Steps:
+   *  1. Close portion of short position (BUY limit order) → realises PnL
+   *  2. Immediately reopen same size (SELL limit order) → maintains exposure
+   */
+  private async _executeRealisePnl(
+    route: RealisePnlRoute,
+  ): Promise<TransactionResult> {
+    const adapter = this._config.extendedAdapter;
+
+    const [positions, holdings] = await Promise.all([
+      adapter.getAllOpenPositions(),
+      adapter.getExtendedDepositAmount(),
+    ]);
+
+    if (!positions?.length || !holdings) {
+      logger.error(
+        `${this._tag}::_executeRealisePnl could not fetch position/balance`,
+      );
+      return this._failureResult(route);
+    }
+
+    const position = positions.find((p) => p.market === route.instrument);
+    if (!position) {
+      logger.error(
+        `${this._tag}::_executeRealisePnl no position for ${route.instrument}`,
+      );
+      return this._failureResult(route);
+    }
+
+    const positionToClose = await calculatePositionToCloseToWithdrawAmount(
+      holdings,
+      position,
+      route.amount,
+    );
+
+    if (positionToClose.lessThanOrEqualTo(0)) {
+      logger.info(
+        `${this._tag}::_executeRealisePnl amount already available — no close needed`,
+      );
+      return this._successResult(
+        [],
+        Protocols.EXTENDED.name,
+        Protocols.EXTENDED.name,
+        "NONE",
+        route.amount,
+        CycleType.INVESTMENT,
+      );
+    }
+
+    // Step 1: Close portion of short (BUY limit order to realise PnL)
+    logger.info(
+      `${this._tag}::_executeRealisePnl closing ${positionToClose.toNumber()} on ${route.instrument}`,
+    );
+    await this._emitEvent(ExecutionEventType.INITIATED, {
+      routeType: RouteType.REALISE_PNL,
+      routeSummary: `close ${positionToClose.toNumber()} of short`,
+      protocol: 'EXTENDED',
+    });
+
+    const midPrice = await this._getExtendedMidPrice();
+    if (!midPrice) {
+      logger.error(
+        `${this._tag}::_executeRealisePnl could not get extended mid price`,
+      );
+      return this._failureResult(route);
+    }
+    const closeResult = await this._executeExtendedLimitOrderWithRecovery(
+      positionToClose.toNumber(),
+      midPrice,
+      OrderSide.BUY,
+    );
+    if (!closeResult) {
+      logger.error(
+        `${this._tag}::_executeRealisePnl close limit order failed`,
+      );
+      await this._emitEvent(ExecutionEventType.FAILURE, {
+        routeType: RouteType.REALISE_PNL,
+        error: 'Close limit order failed',
+      });
+      return this._failureResult(route);
+    }
+
+    // Step 2: Immediately reopen same position size (SELL limit order to maintain exposure)
+    logger.info(
+      `${this._tag}::_executeRealisePnl reopening ${positionToClose.toNumber()} on ${route.instrument}`,
+    );
+    // todo need to ensure this one passes for sure
+    const reopenResult = await this._executeExtendedLimitOrderWithRecovery(
+      positionToClose.toNumber(),
+      midPrice,
+      OrderSide.SELL,
+    );
+    if (!reopenResult) {
+      logger.error(
+        `${this._tag}::_executeRealisePnl reopen limit order failed — WARNING: exposure reduced`,
+      );
+      await this._emitEvent(ExecutionEventType.FAILURE, {
+        routeType: RouteType.REALISE_PNL,
+        error: 'Reopen limit order failed — exposure reduced',
+      });
+      return this._failureResult(route);
+    }
+
+    logger.info(
+      `${this._tag}::_executeRealisePnl realised PnL via close+reopen of ${positionToClose.toNumber()} ` +
+      `closePrice=${closeResult.executionPrice} reopenPrice=${reopenResult.executionPrice}`,
+    );
+
+    await this._emitEvent(ExecutionEventType.SUCCESS, {
+      routeType: RouteType.REALISE_PNL,
+      orderId: `close:${closeResult.position_id},reopen:${reopenResult.position_id}`,
+      amount: positionToClose.toNumber().toString(),
+      executionPrice: closeResult.executionPrice,
+    });
+
+    return this._successResult(
+      [],
+      Protocols.EXTENDED.name,
+      Protocols.EXTENDED.name,
+      "NONE",
+      route.amount,
+      CycleType.INVESTMENT,
+    );
+  }
+
+  // ── Extended lever routes ───────────────────────────────────────────────
+
+  /**
+   * EXTENDED_INCREASE_LEVER: Create a SHORT sell limit order on Extended to
+   * increase delta-neutral exposure.
+   *
+   * Uses limit pricing: limitPrice = midPrice * (1 - slippage) to prevent
+   * selling at unfavourable rates.
+   *
+   * Validates price divergence between Extended and Vesu before execution.
+   */
+  private async _executeExtendedIncreaseLever(
+    route: ExtendedLeverRoute,
+  ): Promise<TransactionResult> {
+    logger.info(
+      `${this._tag}::_executeExtendedIncreaseLever SHORT ${route.amount.toNumber()} on ${route.instrument}`,
+    );
+
+    const midPrice = await this._getExtendedMidPrice();
+    if (!midPrice) {
+      logger.error(
+        `${this._tag}::_executeExtendedIncreaseLever could not get extended mid price`,
+      );
+      return this._failureResult(route);
+    }
+    const result = await this._executeExtendedLimitOrderWithRecovery(
+      route.amount.toNumber(),
+      midPrice,
+      OrderSide.SELL,
+    );
+
+    if (!result) {
+      logger.error(
+        `${this._tag}::_executeExtendedIncreaseLever limit order failed`,
+      );
+      return this._failureResult(route);
+    }
+
+    await this._emitEvent(ExecutionEventType.SUCCESS, {
+      routeType: RouteType.EXTENDED_INCREASE_LEVER,
+      orderId: result.position_id,
+      amount: result.btc_exposure,
+      executionPrice: result.executionPrice,
+      protocol: 'EXTENDED',
+    });
+
+    return this._successResult(
+      [],
+      Protocols.NONE.name,
+      Protocols.EXTENDED.name,
+      "DEPOSIT",
+      route.amount,
+      CycleType.INVESTMENT,
+    );
+  }
+
+  /**
+   * EXTENDED_DECREASE_LEVER: Close portion of SHORT position on Extended
+   * by placing a BUY limit order.
+   *
+   * Uses limit pricing: limitPrice = midPrice * (1 + slippage) to prevent
+   * buying at unfavourable rates.
+   *
+   * Validates price divergence between Extended and Vesu before execution.
+   */
+  private async _executeExtendedDecreaseLever(
+    route: ExtendedLeverRoute,
+  ): Promise<TransactionResult> {
+    const leverage = calculateExtendedLevergae().toString();
+
+    logger.info(
+      `${this._tag}::_executeExtendedDecreaseLever BUY ${route.amount.toNumber()} on ${route.instrument}`,
+    );
+
+    const midPrice = await this._getExtendedMidPrice();
+    if (!midPrice) {
+      logger.error(
+        `${this._tag}::_executeExtendedDecreaseLever could not get extended mid price`,
+      );
+      return this._failureResult(route);
+    }
+    const result = await this._executeExtendedLimitOrderWithRecovery(
+      route.amount.toNumber(),
+      midPrice,
+      OrderSide.BUY,
+    );
+
+    if (!result) {
+      logger.error(
+        `${this._tag}::_executeExtendedDecreaseLever limit order failed`,
+      );
+      return this._failureResult(route);
+    }
+
+    await this._emitEvent(ExecutionEventType.SUCCESS, {
+      routeType: RouteType.EXTENDED_DECREASE_LEVER,
+      orderId: result.position_id,
+      amount: result.btc_exposure,
+      executionPrice: result.executionPrice,
+      protocol: 'EXTENDED',
+    });
+
+    return this._successResult(
+      [],
+      Protocols.EXTENDED.name,
+      Protocols.NONE.name,
+      "WITHDRAWAL",
+      route.amount,
+      CycleType.INVESTMENT,
+    );
+  }
+
+  // ── Crisis leverage routes ──────────────────────────────────────────────
+
+  /**
+   * CRISIS_INCREASE_EXTENDED_MAX_LEVERAGE: Temporarily increase Extended
+   * leverage to the crisis maximum (e.g. 4x) to free margin.
+   */
+  private async _executeCrisisIncreaseLeverage(): Promise<TransactionResult> {
+    const adapter = this._config.extendedAdapter;
+    const marketName = adapter.config.extendedMarketName;
+
+    logger.info(
+      `${this._tag}::_executeCrisisIncreaseLeverage setting leverage to ${CRISIS_MAX_LEVERAGE}`,
+    );
+    const success = await adapter.setLeverage(CRISIS_MAX_LEVERAGE, marketName);
+
+    if (!success) {
+      logger.error(
+        `${this._tag}::_executeCrisisIncreaseLeverage failed`,
+      );
+      return this._failureResult({
+        type: RouteType.CRISIS_INCREASE_EXTENDED_MAX_LEVERAGE,
+        priority: 0,
+      });
+    }
+
+    return this._successResult(
+      [],
+      Protocols.EXTENDED.name,
+      Protocols.EXTENDED.name,
+      "NONE",
+      new Web3Number(0, this._config.usdcToken.decimals),
+      CycleType.INVESTMENT,
+    );
+  }
+
+  /**
+   * CRISIS_UNDO_EXTENDED_MAX_LEVERAGE: Revert Extended leverage back to
+   * the normal calculated level.
+   */
+  private async _executeCrisisUndoLeverage(): Promise<TransactionResult> {
+    const adapter = this._config.extendedAdapter;
+    const normalLeverage = calculateExtendedLevergae().toString();
+    const marketName = adapter.config.extendedMarketName;
+
+    logger.info(
+      `${this._tag}::_executeCrisisUndoLeverage reverting leverage to ${normalLeverage}`,
+    );
+    const success = await adapter.setLeverage(normalLeverage, marketName);
+
+    if (!success) {
+      logger.error(
+        `${this._tag}::_executeCrisisUndoLeverage failed`,
+      );
+      return this._failureResult({
+        type: RouteType.CRISIS_UNDO_EXTENDED_MAX_LEVERAGE,
+        priority: 0,
+      });
+    }
+
+    return this._successResult(
+      [],
+      Protocols.EXTENDED.name,
+      Protocols.EXTENDED.name,
+      "NONE",
+      new Web3Number(0, this._config.usdcToken.decimals),
+      CycleType.INVESTMENT,
+    );
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // Private — pending deposit helpers
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  /**
+   * Adjusts a deposit-to-Extended amount by the remaining pending deposit
+   * budget. If pending deposit > 0, those funds are already in transit and
+   * shouldn't be re-sent.
+   *
+   * Mutates `_pendingDepositRemaining` as the budget is consumed.
+   */
+  private _consumePendingDeposit(amount: Web3Number): Web3Number {
+    if (this._pendingDepositRemaining <= 0) return amount;
+
+    const raw = amount.toNumber();
+    const adjusted = raw - this._pendingDepositRemaining;
+
+    if (adjusted <= 0) {
+      this._pendingDepositRemaining -= raw;
+      logger.info(
+        `${this._tag}::_consumePendingDeposit fully covered by pending (remaining: ${this._pendingDepositRemaining})`,
+      );
+      return new Web3Number(0, this._config.usdcToken.decimals);
+    }
+
+    this._pendingDepositRemaining = 0;
+    return new Web3Number(
+      adjusted.toFixed(this._config.usdcToken.decimals),
+      this._config.usdcToken.decimals,
+    );
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // Private — AVNU buffer helper
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  /**
+   * Applies a 0.1% buffer (AVNU_BUFFER_FACTOR) to an amount.
+   * This ensures the downstream consumer (Vesu deposit or AVNU swap)
+   * always has sufficient tokens despite minor slippage.
+   */
+  private _applyAvnuBuffer(amount: Web3Number, decimals: number): Web3Number {
+    return new Web3Number(
+      amount.multipliedBy(AVNU_BUFFER_FACTOR).toFixed(decimals),
+      decimals,
+    );
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // Private — result helpers
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  /**
+   * Creates a TransactionResult for a batch of on-chain calls.
+   * The caller is expected to send all calls in a single multicall transaction.
+   */
+  private _onChainBatchResult(calls: Call[]): TransactionResult {
+    StarknetCallParser.logCallsSummary(
+      `${this._tag}::_onChainBatchResult decoded calls`,
+      calls,
+      {
+        tokenSymbols: this._tokenSymbols,
+        tokenDecimals: this._tokenDecimals,
+        poolNames: this._poolNames,
+      },
+      (message) => logger.debug(message),
+    );
+    return {
+      calls,
+      status: true,
+      transactionMetadata: {
+        protocolFrom: "BATCH",
+        protocolTo: "BATCH",
+        transactionType: "NONE",
+        usdAmount: "0",
+        status: "PENDING",
+        cycleType: CycleType.INVESTMENT,
+      },
+    };
+  }
+
+  private _successResult(
+    calls: Call[],
+    from: string,
+    to: string,
+    txnType: "DEPOSIT" | "WITHDRAWAL" | "NONE",
+    amount: Web3Number,
+    cycleType: CycleType,
+  ): TransactionResult {
+    return {
+      calls,
+      status: true,
+      transactionMetadata: {
+        protocolFrom: from,
+        protocolTo: to,
+        transactionType: txnType,
+        usdAmount: amount.abs().toFixed(),
+        status: "PENDING",
+        cycleType,
+      },
+    };
+  }
+
+  private _failureResult(route: ExecutionRoute): TransactionResult {
+    return {
+      calls: [],
+      status: false,
+      transactionMetadata: {
+        protocolFrom: "",
+        protocolTo: "",
+        transactionType: "NONE",
+        usdAmount: "0",
+        status: "FAILED",
+        cycleType: CycleType.INVESTMENT,
+      },
+    };
+  }
+}