@kestrelfi/lyc-sdk 1.0.1

package/src/services/allocation/allocationService.ts

@@ -0,0 +1,823 @@
+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;
+  }
+}