@kestrelfi/lyc-sdk 1.0.1 → 1.0.3

package/src/services/allocation/allocationService.ts

@@ -1,823 +0,0 @@
-import { type Address } from "@solana/kit";
-import { fromWeb3Pk, mints, toUiAmount } from "common";
-import { KAMINO_MAIN_MARKET } from "lending-platforms";
-import type { LendingPlatformData, ReserveBase, TokenIncentiveBase } from "lending-platforms";
-import type { IndexedLendingPosition, LYCToken } from "../../models/lycToken";
-import type { LYCYieldingBank } from "../../models/yieldingBank";
-import type { DebtAllocationTarget, DebtReallocation } from "./types";
-
-/**
- * Supported borrow tokens by registry symbol. Addresses are taken from
- * `mints` (common mint registry) when resolving candidates.
- */
-const BORROW_TOKEN_SYMBOLS = ["USDC", "PYUSD", "USDT", "CASH", "USDG", "USDS"] as const;
-const USDC_MINT = mints.get("USDC")!.address;
-const USD_STAR_MINT = mints.get("USD*")!.address;
-
-/**
- * Selection-only discount applied to USDC's effective borrow APY when the
- * token's yielding bank holds USD*. Borrowing USDC avoids the otherwise
- * required debt-mint → USDC swap and its occasional execution loss.
- */
-const USDC_BORROW_APY_BIAS = 0.005;
-
-/**
- * Discrete allocation steps for the per-position DP grid. 20 → 5% increments.
- * Complexity is O(positions × candidates × K²) — all synchronous, negligible.
- */
-const ALLOCATION_STEPS = 20;
-
-/**
- * Minimum borrow-APY improvement that justifies emitting a reallocation. Below
- * this, the rebalance is skipped — on-chain costs (flash-loan fee + swap
- * slippage + tx fees) eat marginal gains, and thrashing positions for a few
- * basis points adds noise without value. 0.025 = 250 bps on the position's APY.
- */
-const MIN_REALLOC_APY_IMPROVEMENT = 0.025;
-
-/**
- * Positions with debt below this threshold (in the borrowed token's UI units)
- * are dust — typically idle or near-closed slots — and are excluded from
- * optimization. Without this filter, dust slots generate phantom reallocations
- * with zero economic effect but real on-chain transaction costs.
- */
-const DUST_DEBT_THRESHOLD = 1.0;
-
-// ─── Internal types ────────────────────────────────────────────────────────
-
-interface ResolvedPosition {
-  pool: Address;
-  token: LYCToken;
-  lendingPositionIndex: number;
-  debtMint: Address;
-  debtAmountUi: number;
-  collateralReserve: ReserveBase;
-  debtReserve: ReserveBase;
-  currentBorrowApy: number;
-  /** Borrow APY minus the supply incentive the collateral earns from this debt token. */
-  currentEffectiveBorrowApy: number;
-  /** Whether USDC should receive the selection-only borrow-rate discount. */
-  biasTowardUsdc: boolean;
-}
-
-interface GroupCandidate {
-  mint: Address;
-  reserve: ReserveBase;
-  /** Total debt already borrowed from this reserve across all positions in the group. */
-  existingGroupDebt: number;
-  /** Available borrow capacity in UI units — caps per-position allocations in the DP. */
-  liquidityAvailableUi: number;
-}
-
-interface PositionMintAlloc {
-  mint: Address;
-  reserve: ReserveBase;
-  amountUi: number;
-  weightBps: number;
-  borrowApy: number;
-  supplyIncentiveApy: number;
-  effectiveBorrowApy: number;
-  selectionBorrowApy: number;
-}
-
-interface PositionOptimum {
-  mints: PositionMintAlloc[];
-  /** Debt-weighted average effective borrow APY (borrow − supply incentive) across all mints. */
-  blendedEffectiveBorrowApy: number;
-  /** Effective borrow APY after applying selection-only mint biases. */
-  blendedSelectionBorrowApy: number;
-}
-
-// ─── LTV helpers ───────────────────────────────────────────────────────────
-
-/**
- * Returns the LTV (as a decimal) for a collateral/debt pair, using the
- * e-mode config if one exists for the pair, otherwise the base LTV.
- */
-function getPairLtv(collateralReserve: ReserveBase, debtReserveAddress: Address): number {
-  const emode = collateralReserve.emodes?.find((e) => e.debtReserve === debtReserveAddress);
-  return emode?.ltvPct ?? collateralReserve.ltvPct;
-}
-
-// ─── Log formatters ────────────────────────────────────────────────────────
-
-function mintSymbol(mint: Address): string {
-  return mints.get(mint)?.symbol ?? `${mint.slice(0, 6)}…`;
-}
-
-function tokenLabel(pos: ResolvedPosition): string {
-  return pos.token.label ?? pos.token.address.slice(0, 6);
-}
-
-function positionTag(pos: ResolvedPosition): string {
-  return `${tokenLabel(pos)}#${pos.lendingPositionIndex}`;
-}
-
-function formatApy(x: number): string {
-  return `${(x * 100).toFixed(3)}%`;
-}
-
-function formatApyDelta(x: number): string {
-  const sign = x >= 0 ? "+" : "";
-  return `${sign}${(x * 100).toFixed(3)}%`;
-}
-
-function formatAmount(x: number): string {
-  return x.toLocaleString(undefined, { maximumFractionDigits: 2 });
-}
-
-function formatIncentive(inc: TokenIncentiveBase): string {
-  const pair = inc.config.requiresPairReserve
-    ? `pair=${inc.config.requiresPairReserve.slice(0, 6)}…`
-    : "pair=none";
-  const active = inc.active() ? "active" : "inactive";
-  return (
-    `type=${inc.config.incentiveType} ${pair} ` +
-    `reward=${mintSymbol(inc.config.rewardMint)} apy=${formatApy(inc.apy())} ${active}`
-  );
-}
-
-// ─── Service ───────────────────────────────────────────────────────────────
-
-export interface AllocationServiceOptions {
-  /**
-   * Receives diagnostic log messages. When omitted, the service is silent
-   * (used by unit tests). Pass `console.log` from scripts to inspect per-pool
-   * candidate evaluation, incentive eligibility, and the chosen allocation.
-   */
-  logger?: (message: string) => void;
-  /**
-   * Yielding-bank state used to identify tokens whose active bank holds USD*.
-   * Without this data, allocation remains unbiased.
-   */
-  yieldingBanks?: readonly LYCYieldingBank[];
-}
-
-export class AllocationService {
-  private readonly log: (message: string) => void;
-  private readonly yieldingBanks: readonly LYCYieldingBank[];
-
-  constructor(
-    private readonly lpData: LendingPlatformData,
-    options: AllocationServiceOptions = {}
-  ) {
-    this.log = options.logger ?? (() => {});
-    this.yieldingBanks = options.yieldingBanks ?? [];
-  }
-
-  /**
-   * Returns the debt mint with the highest pair-adjusted net APY
-   * (supplyAPY − borrowAPY) for a given pool and collateral reserve.
-   *
-   * Use this when creating a new lending position to pick the optimal debt
-   * mint rather than hardcoding a default.
-   */
-  async findOptimalDebtMint(
-    pool: Address,
-    collateralReserve: ReserveBase,
-    token?: LYCToken
-  ): Promise<{ mint: Address; symbol: string; borrowApy: number } | null> {
-    const biasTowardUsdc = token ? this.tokenUsesUsdStarYieldingBank(token) : false;
-    const candidates = await Promise.all(
-      BORROW_TOKEN_SYMBOLS.map(async (symbol) => {
-        const info = mints.get(symbol);
-        if (!info) return null;
-        const reserve = await this.fetchOptionalReserveByMint(pool, info.address);
-        if (!reserve) return null;
-        // TODO: revert to pair-adjusted rates once Kamino main-market incentive distortions are resolved.
-        // Revert to:
-        //   const pairedBorrowApy = reserve.borrowAPY(collateralReserve.address);
-        //   const supplyIncentiveApy = collateralReserve.supplyAPY(reserve.address) - collateralReserve.supplyAPY();
-        const isKaminoMain = pool === KAMINO_MAIN_MARKET;
-        const pairedBorrowApy = isKaminoMain
-          ? reserve.borrowAPY()
-          : reserve.borrowAPY(collateralReserve.address);
-        const supplyIncentiveApy = isKaminoMain
-          ? 0
-          : collateralReserve.supplyAPY(reserve.address) - collateralReserve.supplyAPY();
-        const effectiveBorrowApy = pairedBorrowApy - supplyIncentiveApy;
-        const selectionBorrowApy = this.applyUsdcBias(
-          effectiveBorrowApy,
-          info.address,
-          biasTowardUsdc
-        );
-        const incentiveNote =
-          supplyIncentiveApy > 0
-            ? ` − ${formatApy(supplyIncentiveApy)} incentive = ${formatApy(effectiveBorrowApy)} effective`
-            : "";
-        const biasNote =
-          selectionBorrowApy !== effectiveBorrowApy
-            ? ` − ${formatApy(USDC_BORROW_APY_BIAS)} USDC bias = ${formatApy(selectionBorrowApy)} selection`
-            : "";
-        this.log(
-          `  [findOptimalDebtMint] ${symbol.padEnd(6)} borrow ${formatApy(pairedBorrowApy)}${incentiveNote}${biasNote}`
-        );
-        return {
-          mint: info.address,
-          symbol,
-          pairedBorrowApy,
-          effectiveBorrowApy,
-          selectionBorrowApy,
-        };
-      })
-    );
-
-    const valid = candidates.filter((c): c is NonNullable<typeof c> => c !== null);
-    if (valid.length === 0) return null;
-
-    valid.sort((a, b) => a.selectionBorrowApy - b.selectionBorrowApy);
-    const best = valid[0];
-    this.log(
-      `  [findOptimalDebtMint] → ${best.symbol}` +
-        ` (borrow ${formatApy(best.pairedBorrowApy)} effective ${formatApy(best.effectiveBorrowApy)}` +
-        (best.selectionBorrowApy !== best.effectiveBorrowApy
-          ? ` selection ${formatApy(best.selectionBorrowApy)}`
-          : "") +
-        `)`
-    );
-    return { mint: best.mint, symbol: best.symbol, borrowApy: best.effectiveBorrowApy };
-  }
-
-  /**
-   * Groups all active lending positions by pool, then for each position in a
-   * pool finds the allocation across supported borrow mints that minimises
-   * that position's pair-adjusted borrow cost. Positions are optimised
-   * independently — pair-incentive eligibility is keyed on the position's
-   * (debt, collateral) pair, so positions with different collaterals can have
-   * different optimal debt mints. (Utilization coupling between positions on
-   * the same reserve is not modelled; pair-incentive deltas dominate marginal
-   * utilization deltas at typical position sizes.)
-   *
-   * Returns one entry per position whose allocation would change.
-   */
-  async computeOptimalAllocations(tokens: LYCToken[]): Promise<DebtReallocation[]> {
-    const positions = await this.resolveAllPositions(tokens);
-    const poolGroups = this.groupByPool(positions);
-    this.log(
-      `[AllocationService] ${positions.length} active position${positions.length === 1 ? "" : "s"} across ${poolGroups.size} pool${poolGroups.size === 1 ? "" : "s"}`
-    );
-    const reallocations: DebtReallocation[] = [];
-
-    for (const [pool, group] of poolGroups) {
-      const groupReallocations = await this.processPoolGroup(pool, group);
-      reallocations.push(...groupReallocations);
-    }
-
-    return reallocations;
-  }
-
-  // ─── Position resolution ─────────────────────────────────────────────────
-
-  private async resolveAllPositions(tokens: LYCToken[]): Promise<ResolvedPosition[]> {
-    const maybePositions = await Promise.all(
-      tokens.flatMap((token) =>
-        token.activeLendingPositions.map((lp) => this.resolvePosition(token, lp))
-      )
-    );
-    return maybePositions.filter((p): p is ResolvedPosition => p !== null);
-  }
-
-  private async resolvePosition(
-    token: LYCToken,
-    { index, data: lp }: IndexedLendingPosition
-  ): Promise<ResolvedPosition | null> {
-    const pool = fromWeb3Pk(lp.pool);
-    const debtAmountUi = toUiAmount(lp.accounting.debt.amount, lp.accounting.debt.decimals);
-
-    // Skip dust slots — idle positions whose debt is too small for a
-    // reallocation to recover its on-chain transaction cost.
-    if (debtAmountUi < DUST_DEBT_THRESHOLD) return null;
-
-    const [collateralReserve, debtReserve] = await Promise.all([
-      this.lpData.fetchReserve(pool, fromWeb3Pk(lp.collateralReserve)),
-      this.lpData.fetchReserve(pool, fromWeb3Pk(lp.debtReserve)),
-    ]);
-
-    if (!collateralReserve || !debtReserve) return null;
-
-    return {
-      pool,
-      token,
-      lendingPositionIndex: index,
-      // `lp.accounting.debt.mint` is set at position creation and is NOT
-      // updated when the debt is rebalanced into a different mint. The
-      // debt reserve, by contrast, reflects the live borrow on-chain — so
-      // that's the source of truth for which token is actually borrowed.
-      debtMint: debtReserve.mint.mint,
-      debtAmountUi,
-      collateralReserve,
-      debtReserve,
-      // TODO: revert to pair-adjusted rates once Kamino main-market incentive distortions are resolved.
-      // Revert to:
-      //   currentBorrowApy: debtReserve.borrowAPY(collateralReserve.address),
-      //   currentEffectiveBorrowApy:
-      //     debtReserve.borrowAPY(collateralReserve.address) -
-      //     (collateralReserve.supplyAPY(debtReserve.address) - collateralReserve.supplyAPY()),
-      currentBorrowApy:
-        pool === KAMINO_MAIN_MARKET
-          ? debtReserve.borrowAPY()
-          : debtReserve.borrowAPY(collateralReserve.address),
-      currentEffectiveBorrowApy:
-        pool === KAMINO_MAIN_MARKET
-          ? debtReserve.borrowAPY()
-          : debtReserve.borrowAPY(collateralReserve.address) -
-            (collateralReserve.supplyAPY(debtReserve.address) - collateralReserve.supplyAPY()),
-      biasTowardUsdc: this.tokenUsesUsdStarYieldingBank(token),
-    };
-  }
-
-  private tokenUsesUsdStarYieldingBank(token: LYCToken): boolean {
-    // A yielding-bank PDA is identified by its base mint + id. Match both so a
-    // USD* holding in an unrelated global bank cannot influence this token.
-    // `activeCarryPositions` also ensures the token has real shares in the bank,
-    // rather than merely retaining an initialized but unused carry slot.
-    return token.activeCarryPositions.some(({ data: carry }) =>
-      this.yieldingBanks.some(
-        (bank) =>
-          bank.baseMint === fromWeb3Pk(carry.yieldingBaseMint) &&
-          bank.id === carry.yieldingBankId &&
-          bank.findAssetHolding(USD_STAR_MINT) !== null
-      )
-    );
-  }
-
-  private applyUsdcBias(effectiveBorrowApy: number, mint: Address, enabled: boolean): number {
-    return enabled && mint === USDC_MINT
-      ? effectiveBorrowApy - USDC_BORROW_APY_BIAS
-      : effectiveBorrowApy;
-  }
-
-  private groupByPool(positions: ResolvedPosition[]): Map<Address, ResolvedPosition[]> {
-    const groups = new Map<Address, ResolvedPosition[]>();
-    for (const pos of positions) {
-      if (!groups.has(pos.pool)) groups.set(pos.pool, []);
-      groups.get(pos.pool)!.push(pos);
-    }
-    return groups;
-  }
-
-  // ─── Pool group processing ────────────────────────────────────────────────
-
-  private async processPoolGroup(
-    pool: Address,
-    group: ResolvedPosition[]
-  ): Promise<DebtReallocation[]> {
-    this.log(`\n${"═".repeat(70)}`);
-    this.log(
-      `Pool ${pool.slice(0, 6)}…  (${group.length} position${group.length === 1 ? "" : "s"})`
-    );
-    this.log(`${"─".repeat(70)}`);
-    for (const pos of group) {
-      this.log(
-        `  ${positionTag(pos).padEnd(14)}` +
-          ` collateral=${mintSymbol(pos.collateralReserve.mint.mint)}` +
-          `  debt=${mintSymbol(pos.debtMint)}  $${formatAmount(pos.debtAmountUi)}` +
-          `  borrow ${formatApy(pos.currentBorrowApy)}`
-      );
-    }
-
-    const existingDebtByMint = this.aggregateExistingDebtByMint(group);
-    const candidates = await this.resolveGroupCandidates(pool, group, existingDebtByMint);
-    if (candidates.length === 0) {
-      this.log("  no borrow-token candidates resolved on this pool; skipping");
-      return [];
-    }
-
-    this.logCandidates(group, candidates);
-
-    const reallocations: DebtReallocation[] = [];
-    for (const pos of group) {
-      const realloc = this.evaluatePosition(pos, candidates);
-      if (realloc !== null) reallocations.push(realloc);
-    }
-    return reallocations;
-  }
-
-  /**
-   * Optimises a single position against the candidate set, logs the result,
-   * applies the minimum-improvement gate, and returns a reallocation if one
-   * should be emitted. Returns `null` when the position is already optimal,
-   * the optimum doesn't beat current, or the gain is below threshold.
-   *
-   */
-  private evaluatePosition(
-    pos: ResolvedPosition,
-    candidates: GroupCandidate[]
-  ): DebtReallocation | null {
-    const tag = positionTag(pos);
-    const {
-      mints: optimumMints,
-      blendedEffectiveBorrowApy: optimumEffectiveBorrowApy,
-      blendedSelectionBorrowApy: optimumSelectionBorrowApy,
-    } = this.optimizePosition(pos, candidates);
-    const currentSelectionBorrowApy = this.applyUsdcBias(
-      pos.currentEffectiveBorrowApy,
-      pos.debtMint,
-      pos.biasTowardUsdc
-    );
-
-    this.log(`\n  ── ${tag} ──`);
-    const currentSupplyIncentive =
-      pos.collateralReserve.supplyAPY(pos.debtReserve.address) - pos.collateralReserve.supplyAPY();
-    const currentEffectiveNote =
-      currentSupplyIncentive > 0
-        ? ` − ${formatApy(currentSupplyIncentive)} incentive = ${formatApy(pos.currentEffectiveBorrowApy)} effective`
-        : "";
-    this.log(
-      `     Current:  ${mintSymbol(pos.debtMint)}  $${formatAmount(pos.debtAmountUi)}` +
-        `  borrow ${formatApy(pos.currentBorrowApy)}${currentEffectiveNote}`
-    );
-    this.log(
-      `     Optimum:  effective borrow ${formatApy(optimumEffectiveBorrowApy)}` +
-        (optimumSelectionBorrowApy !== optimumEffectiveBorrowApy
-          ? `  selection ${formatApy(optimumSelectionBorrowApy)}`
-          : "")
-    );
-    for (const m of optimumMints) {
-      const incentiveNote =
-        m.supplyIncentiveApy > 0
-          ? ` − ${formatApy(m.supplyIncentiveApy)} incentive = ${formatApy(m.effectiveBorrowApy)} effective`
-          : "";
-      const biasNote =
-        m.selectionBorrowApy !== m.effectiveBorrowApy
-          ? ` − ${formatApy(USDC_BORROW_APY_BIAS)} USDC bias = ${formatApy(m.selectionBorrowApy)} selection`
-          : "";
-      this.log(
-        `       ${mintSymbol(m.mint).padEnd(6)} ${(m.weightBps / 100).toFixed(0).padStart(3)}%` +
-          `  $${formatAmount(m.amountUi)}  borrow ${formatApy(m.borrowApy)}${incentiveNote}${biasNote}`
-      );
-    }
-
-    const isAlreadyOptimal =
-      optimumMints.length === 1 &&
-      optimumMints[0].mint === pos.debtMint &&
-      optimumMints[0].weightBps === 10_000;
-    if (isAlreadyOptimal) {
-      this.log(`     → No change (already optimal)`);
-      return null;
-    }
-
-    if (optimumSelectionBorrowApy >= currentSelectionBorrowApy) {
-      this.log(`     → No change (optimum effective borrow rate does not beat current)`);
-      return null;
-    }
-
-    const improvement = currentSelectionBorrowApy - optimumSelectionBorrowApy;
-    if (improvement < MIN_REALLOC_APY_IMPROVEMENT) {
-      this.log(
-        `     → No change (improvement ${formatApyDelta(improvement)}` +
-          ` below ${formatApyDelta(MIN_REALLOC_APY_IMPROVEMENT)} threshold)`
-      );
-      return null;
-    }
-    this.log(
-      `     → Rebalancing (effective borrow rate improves by ${formatApyDelta(improvement)})`
-    );
-
-    const targets: DebtAllocationTarget[] = optimumMints.map((m) => ({
-      mint: m.mint,
-      amountUi: m.amountUi,
-      weightBps: m.weightBps,
-    }));
-
-    // Build fallback single-mint options: every candidate that beats current,
-    // sorted by effective borrow APY ascending, excluding the primary target
-    // mint(s) already in `targets`.
-    const isKaminoMain = pos.pool === KAMINO_MAIN_MARKET;
-    const baseSupplyApy = pos.collateralReserve.supplyAPY();
-    const primaryMints = new Set(targets.map((t) => t.mint));
-    const fallbackTargets: DebtAllocationTarget[][] = candidates
-      .map(({ mint, reserve }) => {
-        if (primaryMints.has(mint)) return null;
-        const supplyIncentiveApy = isKaminoMain
-          ? 0
-          : pos.collateralReserve.supplyAPY(reserve.address) - baseSupplyApy;
-        const borrowApy = isKaminoMain
-          ? reserve.simulateNewBorrowAPY({ debtChange: pos.debtAmountUi })
-          : reserve.simulateNewBorrowAPY(
-              { debtChange: pos.debtAmountUi },
-              pos.collateralReserve.address
-            );
-        const effectiveBorrowApy = borrowApy - supplyIncentiveApy;
-        const selectionBorrowApy = this.applyUsdcBias(effectiveBorrowApy, mint, pos.biasTowardUsdc);
-        if (selectionBorrowApy >= currentSelectionBorrowApy) return null;
-        return {
-          selectionBorrowApy,
-          target: {
-            mint,
-            amountUi: pos.debtAmountUi,
-            weightBps: 10_000,
-          } satisfies DebtAllocationTarget,
-        };
-      })
-      .filter((x): x is NonNullable<typeof x> => x !== null)
-      .sort((a, b) => a.selectionBorrowApy - b.selectionBorrowApy)
-      .map((x) => [x.target]);
-
-    return {
-      token: pos.token.address,
-      lendingPositionIndex: pos.lendingPositionIndex,
-      currentDebtMint: pos.debtMint,
-      currentDebtAmountUi: pos.debtAmountUi,
-      currentBorrowApy: pos.currentBorrowApy,
-      currentSupplyIncentiveApy: currentSupplyIncentive,
-      projectedBorrowApy: optimumEffectiveBorrowApy,
-      targets,
-      fallbackTargets,
-    };
-  }
-
-  /**
-   * Logs, in this order:
-   * 1. Each collateral reserve in the pool group + its incentives (once).
-   * 2. Each candidate debt reserve: base borrow APY, utilization, and its
-   *    borrow-side incentives (once).
-   * 3. A net-APY matrix (candidate rows × collateral columns) showing the
-   *    pair-adjusted supply APY, borrow APY, and net APY = supply − borrow.
-   *    The matrix answers "should I borrow USDS or USDG against cbBTC?" at a
-   *    glance — compare rows within the cbBTC column.
-   *
-   * The matrix uses `supplyAPY(debtReserve)` and `borrowAPY(supplyReserve)`,
-   * which include pair-gated incentives. A `★` marks rows where a pair
-   * incentive activates (supplyApy or borrowApy differs from the base).
-   */
-  private logCandidates(group: ResolvedPosition[], candidates: GroupCandidate[]) {
-    const collateralReserves = new Map<Address, ReserveBase>();
-    for (const pos of group) {
-      collateralReserves.set(pos.collateralReserve.address, pos.collateralReserve);
-    }
-
-    this.log(`\nCollateral reserves:`);
-    for (const r of collateralReserves.values()) {
-      const activeIncentives = (r.incentives ?? []).filter((i) => i.active());
-      const inactiveCount = (r.incentives ?? []).length - activeIncentives.length;
-      this.log(
-        `  ${mintSymbol(r.mint.mint).padEnd(8)} base supply ${formatApy(r.supplyAPY())}` +
-          (activeIncentives.length > 0
-            ? `  +${activeIncentives.length} active incentive${activeIncentives.length === 1 ? "" : "s"}`
-            : "") +
-          (inactiveCount > 0 ? `  (${inactiveCount} inactive)` : "")
-      );
-      for (const inc of activeIncentives) {
-        this.log(`    ${formatIncentive(inc)}`);
-      }
-    }
-
-    this.log(`\nDebt candidates:`);
-    for (const c of candidates) {
-      const activeIncentives = (c.reserve.incentives ?? []).filter((i) => i.active());
-      const inactiveCount = (c.reserve.incentives ?? []).length - activeIncentives.length;
-      this.log(
-        `  ${mintSymbol(c.mint).padEnd(8)} borrow ${formatApy(c.reserve.borrowAPY())}` +
-          `  util ${(c.reserve.utilizationRatePct() * 100).toFixed(1)}%` +
-          `  capacity $${formatAmount(c.liquidityAvailableUi)}` +
-          `  group debt $${formatAmount(c.existingGroupDebt)}` +
-          (activeIncentives.length > 0
-            ? `  +${activeIncentives.length} active incentive${activeIncentives.length === 1 ? "" : "s"}`
-            : "  no incentives") +
-          (inactiveCount > 0 ? `  (${inactiveCount} inactive)` : "")
-      );
-      for (const inc of activeIncentives) {
-        this.log(`    ${formatIncentive(inc)}`);
-      }
-    }
-
-    this.logBorrowRateMatrix(collateralReserves, candidates);
-  }
-
-  private logBorrowRateMatrix(
-    collateralReserves: Map<Address, ReserveBase>,
-    candidates: GroupCandidate[]
-  ) {
-    const collateralList = [...collateralReserves.values()];
-    const symW = 8;
-    const borrowW = 8;
-    const cellW = 9;
-
-    this.log(`\nBorrow rate matrix  (pair-adjusted  ★ = pair incentive changes rate)`);
-    const header =
-      `  ${"Debt".padEnd(symW)}  ${"Base".padStart(borrowW)}` +
-      collateralList.map((r) => `vs ${mintSymbol(r.mint.mint)}`.padStart(cellW + 3)).join("");
-    this.log(header);
-
-    for (const c of candidates) {
-      const baseBorrow = c.reserve.borrowAPY();
-      const cells = collateralList.map((coll) => {
-        const pairedBorrow = c.reserve.borrowAPY(coll.address);
-        const pairedSupply = coll.supplyAPY(c.reserve.address);
-        const pairActive = pairedBorrow !== baseBorrow || pairedSupply !== coll.supplyAPY();
-        return `${formatApy(pairedBorrow).padStart(cellW)} ${pairActive ? "★" : " "}`;
-      });
-      this.log(
-        `  ${mintSymbol(c.mint).padEnd(symW)}  ${formatApy(baseBorrow).padStart(borrowW)}` +
-          cells.join("  ")
-      );
-    }
-  }
-
-  private aggregateExistingDebtByMint(group: ResolvedPosition[]): Map<Address, number> {
-    const existingDebtByMint = new Map<Address, number>();
-    for (const pos of group) {
-      existingDebtByMint.set(
-        pos.debtMint,
-        (existingDebtByMint.get(pos.debtMint) ?? 0) + pos.debtAmountUi
-      );
-    }
-    return existingDebtByMint;
-  }
-
-  private async resolveGroupCandidates(
-    pool: Address,
-    group: ResolvedPosition[],
-    existingDebtByMint: Map<Address, number>
-  ): Promise<GroupCandidate[]> {
-    // Reuse already-fetched reserves where possible to avoid redundant RPC calls
-    const fetchedByMint = new Map<Address, ReserveBase>(
-      group.map((p) => [p.debtMint, p.debtReserve])
-    );
-
-    const results = await Promise.all(
-      BORROW_TOKEN_SYMBOLS.map(async (symbol) => {
-        const info = mints.get(symbol);
-        if (!info) {
-          throw new Error(
-            `AllocationService: borrow token symbol "${symbol}" not found in mint registry`
-          );
-        }
-        const mint = info.address;
-        const reserve =
-          fetchedByMint.get(mint) ?? (await this.fetchOptionalReserveByMint(pool, mint));
-        if (!reserve) return;
-        return {
-          mint,
-          reserve,
-          existingGroupDebt: existingDebtByMint.get(mint) ?? 0,
-          liquidityAvailableUi: reserve.liquidityAvailable(),
-        } satisfies GroupCandidate;
-      })
-    );
-
-    return results.filter((c): c is GroupCandidate => Boolean(c));
-  }
-
-  private async fetchOptionalReserveByMint(
-    pool: Address,
-    mint: Address
-  ): Promise<ReserveBase | null> {
-    try {
-      return await this.lpData.fetchReserveByMint(pool, mint);
-    } catch (error) {
-      if (error instanceof Error && error.message === `Unable to find reserve by mint ${mint}`) {
-        this.log(`  (${mintSymbol(mint)} not listed on this pool — skipping)`);
-        return null;
-      }
-      throw error;
-    }
-  }
-
-  // ─── Per-position DP optimization ─────────────────────────────────────────
-
-  /**
-   * Finds the allocation of `pos.debtAmountUi` across `candidates` that
-   * MAXIMISES this position's pair-adjusted net APY (supplyApy − borrowApy)
-   * using DP over a discrete grid of size K = ALLOCATION_STEPS.
-   *
-   * Both legs are pair-adjusted with this position's own collateral reserve,
-   * since incentive eligibility is keyed on the (debt, collateral) pair. This
-   * matters because some pair incentives (e.g. USDG★cbBTC) act on the supply
-   * side — minimising borrow cost alone would miss them.
-   *
-   * For candidate `i` at step `n`:
-   *   target      = n × stepSize
-   *   posExisting = pos.debtAmountUi if pos.debtMint == candidate.mint else 0
-   *   debtChange  = target − posExisting
-   *   borrowApy   = simulateNewBorrowAPY({debtChange}, pos.collateralReserve)
-   *   supplyApy   = pos.collateralReserve.supplyAPY(reserve.address)
-   *
-   * The DP minimises Σ target × (borrowApy − supplyApy) — equivalent to
-   * maximising debt-weighted net APY. Utilization coupling with sibling
-   * positions is not modelled; the simulator only sees this position's
-   * marginal change.
-   */
-  private optimizePosition(pos: ResolvedPosition, candidates: GroupCandidate[]): PositionOptimum {
-    const K = ALLOCATION_STEPS;
-    const stepSize = pos.debtAmountUi / K;
-
-    const baseSupplyApy = pos.collateralReserve.supplyAPY();
-
-    // TODO: revert to pair-adjusted rates once Kamino main-market incentive distortions are resolved.
-    // In costGrid: revert borrowApy to reserve.simulateNewBorrowAPY({ debtChange }, pos.collateralReserve.address)
-    //              and supplyIncentiveApy to pos.collateralReserve.supplyAPY(reserve.address) - baseSupplyApy.
-    // In mintAllocs: same reversions for borrowApy and supplyIncentiveApy.
-    const isKaminoMain = pos.pool === KAMINO_MAIN_MARKET;
-    const costGrid = candidates.map(({ reserve, mint }) => {
-      const posExisting = mint === pos.debtMint ? pos.debtAmountUi : 0;
-      const supplyIncentiveApy = isKaminoMain
-        ? 0
-        : pos.collateralReserve.supplyAPY(reserve.address) - baseSupplyApy;
-      return Array.from({ length: K + 1 }, (_, n) => {
-        const target = n * stepSize;
-        const debtChange = target - posExisting;
-        const borrowApy = isKaminoMain
-          ? reserve.simulateNewBorrowAPY({ debtChange })
-          : reserve.simulateNewBorrowAPY({ debtChange }, pos.collateralReserve.address);
-        const effectiveBorrowApy = borrowApy - supplyIncentiveApy;
-        return target * this.applyUsdcBias(effectiveBorrowApy, mint, pos.biasTowardUsdc);
-      });
-    });
-
-    // Cap each candidate's DP steps by:
-    // 1. Reserve liquidity (can't borrow more than what's available)
-    // 2. LTV-ratio feasibility: if the candidate pair has lower LTV than the
-    //    current pair, the position can only hold (candidateLtv/currentLtv)
-    //    of its current debt in that token. posExisting offsets the cap since
-    //    existing debt in the same token needs no new capacity.
-    const currentPairLtv = getPairLtv(pos.collateralReserve, pos.debtReserve.address);
-    const maxStepsPerCandidate = candidates.map(({ mint, reserve, liquidityAvailableUi }) => {
-      const posExisting = mint === pos.debtMint ? pos.debtAmountUi : 0;
-      const candidateLtv = getPairLtv(pos.collateralReserve, reserve.address);
-      // Max debt in candidate token = current_debt * (candidateLtv / currentLtv),
-      // assuming position is at current LTV and both tokens have ~equal price.
-      const ltvCapUi =
-        currentPairLtv > 0 ? (pos.debtAmountUi * candidateLtv) / currentPairLtv : pos.debtAmountUi;
-      const effectiveCap = posExisting + Math.min(ltvCapUi, liquidityAvailableUi);
-      return Math.min(K, Math.floor(effectiveCap / stepSize));
-    });
-    const optimalSteps = this.runDp(costGrid, candidates.length, K, maxStepsPerCandidate);
-
-    // Keep the real APY separate from the biased selection score. The bias
-    // models avoided debt-mint → USDC swap losses; it is not an actual lending
-    // rate and therefore must not be reported as the projected borrow APY.
-    let blendedEffectiveBorrowApy = 0;
-    let blendedSelectionBorrowApy = 0;
-    const mintAllocs: PositionMintAlloc[] = optimalSteps
-      .map((n, i) => {
-        const { mint, reserve } = candidates[i];
-        const amountUi = n * stepSize;
-        const posExisting = mint === pos.debtMint ? pos.debtAmountUi : 0;
-        const borrowApy = isKaminoMain
-          ? reserve.simulateNewBorrowAPY({ debtChange: amountUi - posExisting })
-          : reserve.simulateNewBorrowAPY(
-              { debtChange: amountUi - posExisting },
-              pos.collateralReserve.address
-            );
-        const supplyIncentiveApy = isKaminoMain
-          ? 0
-          : pos.collateralReserve.supplyAPY(reserve.address) - baseSupplyApy;
-        const effectiveBorrowApy = borrowApy - supplyIncentiveApy;
-        const selectionBorrowApy = this.applyUsdcBias(effectiveBorrowApy, mint, pos.biasTowardUsdc);
-        if (pos.debtAmountUi > 0) {
-          blendedEffectiveBorrowApy += (amountUi / pos.debtAmountUi) * effectiveBorrowApy;
-          blendedSelectionBorrowApy += (amountUi / pos.debtAmountUi) * selectionBorrowApy;
-        }
-        return {
-          mint,
-          reserve,
-          amountUi,
-          weightBps: Math.round((n / K) * 10_000),
-          borrowApy,
-          supplyIncentiveApy,
-          effectiveBorrowApy,
-          selectionBorrowApy,
-        };
-      })
-      .filter((m) => m.weightBps > 0);
-
-    return { mints: mintAllocs, blendedEffectiveBorrowApy, blendedSelectionBorrowApy };
-  }
-
-  private runDp(
-    costGrid: number[][],
-    numCandidates: number,
-    K: number,
-    maxStepsPerCandidate?: number[]
-  ): number[] {
-    type DPState = { minCost: number; steps: number[] };
-
-    let dp: DPState[] = Array.from({ length: K + 1 }, (_, s) =>
-      s === 0 ? { minCost: 0, steps: [] } : { minCost: Infinity, steps: [] }
-    );
-
-    for (let i = 0; i < numCandidates; i++) {
-      const maxN = maxStepsPerCandidate ? maxStepsPerCandidate[i] : K;
-      const next: DPState[] = Array.from({ length: K + 1 }, () => ({
-        minCost: Infinity,
-        steps: [],
-      }));
-
-      for (let s = 0; s <= K; s++) {
-        if (dp[s].minCost === Infinity) continue;
-        for (let n = 0; n <= Math.min(maxN, K - s); n++) {
-          const cost = dp[s].minCost + costGrid[i][n];
-          if (cost < next[s + n].minCost) {
-            next[s + n] = { minCost: cost, steps: [...dp[s].steps, n] };
-          }
-        }
-      }
-
-      dp = next;
-    }
-
-    return dp[K].steps;
-  }
-}