@kestrelfi/lyc-sdk 1.0.1

package/dist/sdks/long-yield-carry/src/services/allocation/allocationService.js

@@ -0,0 +1,589 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AllocationService = void 0;
+const common_1 = require("common");
+const lending_platforms_1 = require("lending-platforms");
+/**
+ * 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"];
+const USDC_MINT = common_1.mints.get("USDC").address;
+const USD_STAR_MINT = common_1.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;
+// ─── 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, debtReserveAddress) {
+    const emode = collateralReserve.emodes?.find((e) => e.debtReserve === debtReserveAddress);
+    return emode?.ltvPct ?? collateralReserve.ltvPct;
+}
+// ─── Log formatters ────────────────────────────────────────────────────────
+function mintSymbol(mint) {
+    return common_1.mints.get(mint)?.symbol ?? `${mint.slice(0, 6)}…`;
+}
+function tokenLabel(pos) {
+    return pos.token.label ?? pos.token.address.slice(0, 6);
+}
+function positionTag(pos) {
+    return `${tokenLabel(pos)}#${pos.lendingPositionIndex}`;
+}
+function formatApy(x) {
+    return `${(x * 100).toFixed(3)}%`;
+}
+function formatApyDelta(x) {
+    const sign = x >= 0 ? "+" : "";
+    return `${sign}${(x * 100).toFixed(3)}%`;
+}
+function formatAmount(x) {
+    return x.toLocaleString(undefined, { maximumFractionDigits: 2 });
+}
+function formatIncentive(inc) {
+    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}`);
+}
+class AllocationService {
+    constructor(lpData, options = {}) {
+        this.lpData = lpData;
+        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, collateralReserve, token) {
+        const biasTowardUsdc = token ? this.tokenUsesUsdStarYieldingBank(token) : false;
+        const candidates = await Promise.all(BORROW_TOKEN_SYMBOLS.map(async (symbol) => {
+            const info = common_1.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 === lending_platforms_1.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 !== 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) {
+        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 = [];
+        for (const [pool, group] of poolGroups) {
+            const groupReallocations = await this.processPoolGroup(pool, group);
+            reallocations.push(...groupReallocations);
+        }
+        return reallocations;
+    }
+    // ─── Position resolution ─────────────────────────────────────────────────
+    async resolveAllPositions(tokens) {
+        const maybePositions = await Promise.all(tokens.flatMap((token) => token.activeLendingPositions.map((lp) => this.resolvePosition(token, lp))));
+        return maybePositions.filter((p) => p !== null);
+    }
+    async resolvePosition(token, { index, data: lp }) {
+        const pool = (0, common_1.fromWeb3Pk)(lp.pool);
+        const debtAmountUi = (0, common_1.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, (0, common_1.fromWeb3Pk)(lp.collateralReserve)),
+            this.lpData.fetchReserve(pool, (0, common_1.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 === lending_platforms_1.KAMINO_MAIN_MARKET
+                ? debtReserve.borrowAPY()
+                : debtReserve.borrowAPY(collateralReserve.address),
+            currentEffectiveBorrowApy: pool === lending_platforms_1.KAMINO_MAIN_MARKET
+                ? debtReserve.borrowAPY()
+                : debtReserve.borrowAPY(collateralReserve.address) -
+                    (collateralReserve.supplyAPY(debtReserve.address) - collateralReserve.supplyAPY()),
+            biasTowardUsdc: this.tokenUsesUsdStarYieldingBank(token),
+        };
+    }
+    tokenUsesUsdStarYieldingBank(token) {
+        // 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 === (0, common_1.fromWeb3Pk)(carry.yieldingBaseMint) &&
+            bank.id === carry.yieldingBankId &&
+            bank.findAssetHolding(USD_STAR_MINT) !== null));
+    }
+    applyUsdcBias(effectiveBorrowApy, mint, enabled) {
+        return enabled && mint === USDC_MINT
+            ? effectiveBorrowApy - USDC_BORROW_APY_BIAS
+            : effectiveBorrowApy;
+    }
+    groupByPool(positions) {
+        const groups = new Map();
+        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 ────────────────────────────────────────────────
+    async processPoolGroup(pool, group) {
+        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 = [];
+        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.
+     *
+     */
+    evaluatePosition(pos, candidates) {
+        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 === 10000;
+        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 = 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 === lending_platforms_1.KAMINO_MAIN_MARKET;
+        const baseSupplyApy = pos.collateralReserve.supplyAPY();
+        const primaryMints = new Set(targets.map((t) => t.mint));
+        const fallbackTargets = 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: 10000,
+                },
+            };
+        })
+            .filter((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).
+     */
+    logCandidates(group, candidates) {
+        const collateralReserves = new Map();
+        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);
+    }
+    logBorrowRateMatrix(collateralReserves, candidates) {
+        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("  "));
+        }
+    }
+    aggregateExistingDebtByMint(group) {
+        const existingDebtByMint = new Map();
+        for (const pos of group) {
+            existingDebtByMint.set(pos.debtMint, (existingDebtByMint.get(pos.debtMint) ?? 0) + pos.debtAmountUi);
+        }
+        return existingDebtByMint;
+    }
+    async resolveGroupCandidates(pool, group, existingDebtByMint) {
+        // Reuse already-fetched reserves where possible to avoid redundant RPC calls
+        const fetchedByMint = new Map(group.map((p) => [p.debtMint, p.debtReserve]));
+        const results = await Promise.all(BORROW_TOKEN_SYMBOLS.map(async (symbol) => {
+            const info = common_1.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(),
+            };
+        }));
+        return results.filter((c) => Boolean(c));
+    }
+    async fetchOptionalReserveByMint(pool, mint) {
+        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.
+     */
+    optimizePosition(pos, candidates) {
+        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 === lending_platforms_1.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 = 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) * 10000),
+                borrowApy,
+                supplyIncentiveApy,
+                effectiveBorrowApy,
+                selectionBorrowApy,
+            };
+        })
+            .filter((m) => m.weightBps > 0);
+        return { mints: mintAllocs, blendedEffectiveBorrowApy, blendedSelectionBorrowApy };
+    }
+    runDp(costGrid, numCandidates, K, maxStepsPerCandidate) {
+        let dp = 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 = 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;
+    }
+}
+exports.AllocationService = AllocationService;

package/dist/sdks/long-yield-carry/src/services/allocation/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./allocationService";
+export * from "./types";

package/dist/sdks/long-yield-carry/src/services/allocation/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./allocationService"), exports);
+__exportStar(require("./types"), exports);

package/dist/sdks/long-yield-carry/src/services/allocation/types.d.ts

@@ -0,0 +1,25 @@
+import type { Address } from "@solana/kit";
+export interface DebtAllocationTarget {
+    mint: Address;
+    amountUi: number;
+    /** Proportion of total debt allocated here, in basis points (0–10000) */
+    weightBps: number;
+}
+export interface DebtReallocation {
+    token: Address;
+    lendingPositionIndex: number;
+    currentDebtMint: Address;
+    currentDebtAmountUi: number;
+    currentBorrowApy: number;
+    /** Supply APY that the collateral earns as a pair incentive from the current debt token. */
+    currentSupplyIncentiveApy: number;
+    projectedBorrowApy: number;
+    targets: DebtAllocationTarget[];
+    /**
+     * Ordered list of single-mint fallback options to try if the primary targets
+     * fail at execution time (e.g. insufficient borrow capacity or swap liquidity).
+     * Each entry is a full-position allocation to a single mint, ranked by
+     * effective borrow APY ascending.
+     */
+    fallbackTargets: DebtAllocationTarget[][];
+}

package/dist/sdks/long-yield-carry/src/services/allocation/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });