@kestrelfi/lyc-sdk 1.0.1

package/dist/sdks/long-yield-carry/src/client/builders/rebalanceTokenBuilder.js

@@ -0,0 +1,255 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RebalanceTokenBuilder = void 0;
+const core_1 = require("@anchor-lang/core");
+const common_1 = require("common");
+const oracle_1 = require("oracle");
+const lending_platforms_1 = require("lending-platforms");
+const utils_1 = require("../../utils");
+const base_1 = require("./base");
+const general_1 = require("../../constants/general");
+const refreshYieldingBankBuilder_1 = require("./refreshYieldingBankBuilder");
+const createCpiPlanBuilder_1 = require("./createCpiPlanBuilder");
+class RebalanceTokenBuilder extends base_1.LongYieldCarryBuilderBase {
+    async getIx(args) {
+        const tokenData = await this.account.fetchToken(args.token);
+        return this.program.methods
+            .rebalanceToken({
+            lpIndex: args.params.lpIndex,
+            destinationDebtOracleType: args.params.destinationDebtOracleType,
+            flashFeeAmount: args.params.flashFeeAmount,
+            repayAmount: args.params.repayAmount,
+        })
+            .accountsPartial({
+            manager: this.resolveTokenManager(tokenData.data),
+            cpiPlan: args.params.cpiPlan,
+        })
+            .remainingAccounts(args.params.remainingAccounts.map(common_1.toWeb3AccountMeta))
+            .instruction()
+            .then(common_1.toKitInstruction);
+    }
+    async getTx(args) {
+        const tokenData = await this.account.fetchToken(args.token);
+        const { lpIndex, destinationDebtMint } = args.params;
+        const position = tokenData.data.lendingPositions[lpIndex];
+        if (!position) {
+            throw new Error(`rebalance_token: no lending position at index ${lpIndex}`);
+        }
+        const txId = args.params.txId ?? `rebalance-token-${Date.now()}`;
+        const yieldingBank = args.params.yieldingBank ?? (await tokenData.resolveFirstYieldingBankAddress(this.pda));
+        const lpClient = this.getLendingPlatformClient(position);
+        const pool = (0, common_1.fromWeb3Pk)(position.pool);
+        const withdrawAll = args.params.uiAmount === "all";
+        const collateralUiAmount = args.params.uiAmount === "all"
+            ? (0, common_1.toUiAmount)(position.accounting.collateral, tokenData.data.collateral.decimals)
+            : args.params.uiAmount;
+        // Fetch source debt reserve (by address), supply reserve (by address), and
+        // destination debt reserve (by mint, since the position currently holds the old mint).
+        const [sourceDebtReserve, supplyReserve, destDebtReserve] = await Promise.all([
+            lpClient.data.fetchReserve(pool, (0, common_1.fromWeb3Pk)(position.debtReserve)),
+            lpClient.data.fetchReserve(pool, (0, common_1.fromWeb3Pk)(position.collateralReserve)),
+            lpClient.data.fetchReserveByMint(pool, destinationDebtMint),
+        ]);
+        if (!sourceDebtReserve || !supplyReserve || !destDebtReserve) {
+            throw new Error("rebalance_token: failed to fetch one or more lending-position reserves");
+        }
+        const manager = this.resolveTokenManager(tokenData.data);
+        const flashLoan = lpClient.getFlashLoan();
+        const userAccount = (0, common_1.fromWeb3Pk)(position.protocolUserAcc);
+        // Both legs operate on the same position: supply never moves, only debt mint changes.
+        const flashContext = {
+            source: {
+                lendingIx: lpClient.ix,
+                supplyReserve,
+                debtReserve: sourceDebtReserve,
+                pool,
+                userAccount,
+            },
+            destination: {
+                lendingIx: lpClient.ix,
+                supplyReserve,
+                debtReserve: destDebtReserve,
+                pool,
+                userAccount,
+            },
+            flashLoan,
+            swap: this.swap,
+            user: args.token,
+            payer: manager,
+            txId,
+            environment: this.environment,
+        };
+        const flash = await this.buildFlashRebalanceOrSkip(flashContext, {
+            collateralUiAmount,
+            sourceTargetUtilizationRateBps: position.config.targetUtilizationRateBps,
+            destinationMaxUtilizationRateBps: this.maxPostRebalanceUtilizationBps(position),
+            swapSlippageBps: args.params.swapSlippageBps,
+            maxSwapCostBps: args.params.maxSwapCostBps,
+            maxMarketBasisBps: args.params.maxMarketBasisBps,
+            withdrawAll,
+        });
+        const destDebtOracleData = oracle_1.oracle.getOracleData(destinationDebtMint);
+        if (!destDebtOracleData) {
+            throw new Error(`rebalance_token: no oracle registered for destination debt mint ${destinationDebtMint}`);
+        }
+        const destDebtOracle = destDebtOracleData.oracle;
+        const destDebtOracleType = (0, common_1.enumToOracleType)(destDebtOracleData.oracleType);
+        const initialAccounts = await this.account.getRebalanceTokenInitialAccounts(args.token, yieldingBank, lpIndex, destDebtOracle, args.params.lpPosition);
+        // Pack all inner CPIs into one remaining-accounts pool that starts with
+        // the rebalance-token initial accounts. CPIs that reference the token,
+        // yielding bank, ATAs, or LP refresh accounts deduplicate against these
+        // fixed slots — shrinking the transaction's account list.
+        // The new debt reserve is tracked in the borrow ref (tracked[0]) so the
+        // on-chain handler can update the destination lending position's
+        // debt_reserve in place without an extra instruction parameter.
+        const cpiGroups = this.collectFlashCpiGroups(flash);
+        const { accounts: remainingAccounts, refsGroups, lookupTables, } = (0, common_1.createMultiCpiRefs)(cpiGroups.groups, {
+            initialAccounts,
+            trackAddresses: [destDebtReserve.address, destinationDebtMint],
+        });
+        const refs = cpiGroups.indices;
+        const planRefs = [
+            refsGroups[refs.sourceRepay],
+            refsGroups[refs.destinationBorrow],
+            refsGroups[refs.swap],
+        ];
+        const { instructions: ataCreationIxs, postSuccessCacheInvalidations: ataPostSuccess } = await (0, common_1.getCreateAtaInstructions)(this.rpc, manager, remainingAccounts);
+        // The Kamino destination borrow CPI sets `user_destination_liquidity` to
+        // the token PDA's destination-debt ATA. When the token has never held
+        // that mint, the ATA is missing and Kamino fails with
+        // `AccountNotInitialized` (Anchor 3012). The borrow's account meta does
+        // carry an `isRequiredAta` seed, but `buildDeduplicatedPool` only
+        // preserves the first occurrence's flag — if the same address shows up
+        // earlier without seeds, the create-ATA pass above silently skips it.
+        // Add an explicit idempotent create here so the destination debt ATA is
+        // guaranteed to exist before the rebalance ix runs.
+        // TODO: fix `buildDeduplicatedPool` to merge `isRequiredAta` flags
+        // across duplicate occurrences instead of keeping only the first, then
+        // remove this per-builder workaround. We resolve the mint's
+        // token program through the same `mints` registry Kamino's
+        // `reserveInteractionDetails` uses (kamino.ts → `liquidityMintTokenProgram`)
+        // so the ATA address we create matches the one Kamino derives.
+        const destDebtMintInfo = common_1.mints.get(destinationDebtMint);
+        if (!destDebtMintInfo) {
+            throw new Error(`RebalanceTokenBuilder: destination debt mint ${destinationDebtMint} not found in mint registry`);
+        }
+        const { instruction: destDebtAtaIx, postSuccessCacheInvalidations: destDebtAtaPostSuccess } = await (0, common_1.getCreateAtaIxIfNeeded)(this.rpc, manager, destinationDebtMint, args.token, destDebtMintInfo.tokenProgram);
+        // The on-chain handler calls `verify_price_is_fresh` on the bank, so we
+        // only need to prepend a refresh when the cached `lastRefreshedTs` is
+        // outside the staleness window.
+        const yieldingBankAccount = await this.account.fetchYieldingBank(yieldingBank);
+        const refreshYieldingBankInstructions = yieldingBankAccount.isStale
+            ? (await new refreshYieldingBankBuilder_1.RefreshYieldingBankBuilder(this.context).getTx({
+                signer: manager,
+                yieldingBank,
+            })).instructions
+            : [];
+        // For a full-position move (`withdrawAll`), send Kamino's `u64::MAX`
+        // "repay all" sentinel so the on-chain `RepayObligationLiquidityV2` CPI
+        // clears the obligation's actual debt exactly — interest accrual between
+        // the off-chain snapshot and bundle landing can't leave dust that trips
+        // `NetValueRemainingTooSmall` (klend error 6092). The flash-borrow is
+        // over-borrowed by 5 bps in `LeverageService.buildFlashRebalance` to
+        // cover that drift; the post-repay surplus is swept into the yielding
+        // bank.
+        //
+        // For a partial rebalance, the flash-borrow only covers `sourceRepay`
+        // (sized to bring source utilization back to target) — sending
+        // `u64::MAX` would tell Kamino to repay the full obligation debt and
+        // the ATA would underfund the SPL transfer (custom 0x1 insufficient
+        // funds). Repay exactly what we flash-borrowed so the ATA balance
+        // matches the requested CPI amount.
+        const repayAllSentinel = lpClient.getRepayAllSentinel();
+        if (withdrawAll && !repayAllSentinel) {
+            throw new Error("RebalanceTokenBuilder: source lending platform does not expose a repay-all sentinel; cannot build a withdrawAll rebalance");
+        }
+        const repayAmount = withdrawAll && repayAllSentinel ? repayAllSentinel : flash.flashBorrowAmountBaseUnits;
+        const cpiPlanCreatedTs = new core_1.BN(Math.floor(Date.now() / 1000));
+        const [cpiPlan] = await this.pda.deriveCpiPlanPda(args.token, BigInt(cpiPlanCreatedTs.toString()));
+        const createCpiPlanIx = await new createCpiPlanBuilder_1.CreateCpiPlanBuilder(this.context).getIx({
+            manager,
+            cpiPlan,
+            params: {
+                uniqueId: args.token,
+                createdTs: cpiPlanCreatedTs,
+                refs: planRefs,
+            },
+        });
+        const rebalanceIx = await this.getIx({
+            token: args.token,
+            params: {
+                lpIndex,
+                destinationDebtOracleType: destDebtOracleType,
+                flashFeeAmount: flash.flashFeeBaseUnits,
+                repayAmount,
+                cpiPlan,
+                remainingAccounts,
+            },
+        });
+        const mergedLookupTables = (0, utils_1.mergeLycLookupTables)(this.context.environment, args.token, lookupTables ?? []);
+        const preambleInstructions = [
+            ...flash.preInstructions,
+            ...ataCreationIxs,
+            ...(destDebtAtaIx ? [destDebtAtaIx] : []),
+            ...refreshYieldingBankInstructions,
+        ];
+        // The flash group must ride atomically in one tx — Kamino's flash-borrow
+        // introspects its own tx's instructions sysvar to find the matching
+        // flash-repay (`flash_ixs.rs:NoFlashRepayFound`). We also need its
+        // position inside that tx to be predictable so the `borrowInstructionIndex`
+        // we encode here matches what Kamino sees at runtime. Marking the group
+        // as one indivisible segment AND forcing it to start a fresh bin pins
+        // the borrow at index 1 (after the heap-frame ix at index 0), regardless
+        // of how the preamble packs.
+        const flashBorrowIxIndex = 1;
+        const flashRepayIx = await lending_platforms_1.LeverageService.buildFlashRepayIx(flashContext, flash, flashBorrowIxIndex);
+        const flashGroup = [
+            (0, common_1.requestHeapFrameIx)(general_1.MAX_HEAP_FRAME_BYTES),
+            flash.flashBorrowIx,
+            rebalanceIx,
+            flashRepayIx,
+        ];
+        // Each preamble ix is its own segment (length 1), followed by the CPI plan
+        // creation, followed by the flash cycle as one indivisible segment of
+        // length 4. Scope refresh-price instructions must remain first in their tx,
+        // so the CPI plan creation cannot precede lending-platform pre-instructions.
+        const segmentLengths = [...preambleInstructions.map(() => 1), 1, flashGroup.length];
+        const flashSegmentIndex = preambleInstructions.length + 1;
+        return {
+            instructions: [...preambleInstructions, createCpiPlanIx, ...flashGroup],
+            lookupTables: mergedLookupTables,
+            segmentLengths,
+            freshBinSegments: [flashSegmentIndex],
+            postSuccessCacheInvalidations: [
+                (0, utils_1.getTokenCacheInvalidation)(args.token),
+                (0, utils_1.getYieldingBankCacheInvalidation)(yieldingBank),
+                ...ataPostSuccess,
+                ...destDebtAtaPostSuccess,
+                ...flash.postSuccessCacheInvalidations,
+            ],
+        };
+    }
+    maxPostRebalanceUtilizationBps(position) {
+        return (position.config.targetUtilizationRateBps + position.config.maxDeviationAboveTargetUtilBps);
+    }
+    async buildFlashRebalanceOrSkip(context, params) {
+        return await lending_platforms_1.LeverageService.buildFlashRebalance(context, params);
+    }
+    collectFlashCpiGroups(flash) {
+        // Each op's prereqs (reserve + obligation refreshes) stay bundled with
+        // that op. Kamino marks both the obligation AND any written reserves
+        // stale after a write op, so the next op's RefreshObligation needs all
+        // its referenced reserves re-refreshed before it can pass — we can't
+        // dedup `RefreshReserve` CPIs across bundles, even within a single slot.
+        const groups = [];
+        const indices = {};
+        indices.sourceRepay = groups.length;
+        groups.push(flash.sourceRepayCpis);
+        indices.destinationBorrow = groups.length;
+        groups.push(flash.destinationBorrowCpis);
+        indices.swap = groups.length;
+        groups.push(flash.swapCpis);
+        return { groups, indices };
+    }
+}
+exports.RebalanceTokenBuilder = RebalanceTokenBuilder;

package/dist/sdks/long-yield-carry/src/client/builders/rebalanceYieldingBankBuilder.d.ts

@@ -0,0 +1,8 @@
+import type { Instruction } from "@solana/kit";
+import type { LongYieldCarryTransactionPlan } from "../types";
+import { LongYieldCarryBuilderBase } from "./base";
+import type { RebalanceYieldingBankIxArgs, RebalanceYieldingBankTxArgs } from "./args";
+export declare class RebalanceYieldingBankBuilder extends LongYieldCarryBuilderBase<RebalanceYieldingBankIxArgs, RebalanceYieldingBankTxArgs> {
+    getIx(args: RebalanceYieldingBankIxArgs): Promise<Instruction>;
+    getTx(args: RebalanceYieldingBankTxArgs): Promise<LongYieldCarryTransactionPlan>;
+}

package/dist/sdks/long-yield-carry/src/client/builders/rebalanceYieldingBankBuilder.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RebalanceYieldingBankBuilder = void 0;
+const base_1 = require("./base");
+const common_1 = require("common");
+const utils_1 = require("../../utils");
+const createYieldingBankAllocationBuilder_1 = require("./createYieldingBankAllocationBuilder");
+class RebalanceYieldingBankBuilder extends base_1.LongYieldCarryBuilderBase {
+    async getIx(args) {
+        const bankData = await this.account.fetchYieldingBank(args.yieldingBank);
+        return this.program.methods
+            .rebalanceYieldingBank(args.params.ixRefs)
+            .accountsPartial({
+            manager: this.resolveYieldingBankManager(bankData.data),
+            yieldingBank: args.yieldingBank,
+        })
+            .remainingAccounts(args.params.remainingAccounts.map(common_1.toWeb3AccountMeta))
+            .instruction()
+            .then(common_1.toKitInstruction);
+    }
+    async getTx(args) {
+        const bankData = await this.account.fetchYieldingBank(args.yieldingBank);
+        const manager = this.resolveYieldingBankManager(bankData.data);
+        const resolvedCpiData = [...(args.params.cpiData ?? [])];
+        if (args.params.swaps?.length) {
+            const swapCpiData = await Promise.all(args.params.swaps.map(async (swap) => {
+                const swapClient = swap.swapClient ?? this.swap;
+                const quote = await swapClient.getQuote({
+                    inputMint: swap.inputMint,
+                    outputMint: swap.outputMint,
+                    amount: swap.amount,
+                    slippageBps: swap.slippageBps ?? 50,
+                });
+                return swapClient.getSwapCpiData(quote, args.yieldingBank, { payer: manager });
+            }));
+            resolvedCpiData.push(...swapCpiData);
+        }
+        const { externalLiquiditySources, postSuccessCacheInvalidations: refreshCacheInvalidations } = await this.externalLiquidityResolver.resolveYieldingBankRefreshExternalLiquidity(this.account, args.yieldingBank, resolvedCpiData);
+        const oracleAccounts = await this.account.getYieldingBankRefreshAccounts(args.yieldingBank, args.params.newAllocation?.config, externalLiquiditySources);
+        const { accounts: remainingAccounts, refs: ixRefs, lookupTables, } = (0, common_1.createCpiRefs)(resolvedCpiData, {
+            initialAccounts: [...oracleAccounts, common_1.SYSTEM_PROGRAM_META],
+        });
+        const preamble = [];
+        if (args.params.newAllocation) {
+            preamble.push(await new createYieldingBankAllocationBuilder_1.CreateYieldingBankAllocationBuilder(this.context).getIx({
+                yieldingBank: args.yieldingBank,
+                config: args.params.newAllocation.config,
+            }));
+        }
+        const { instructions, postSuccessCacheInvalidations } = await (0, common_1.getCreateAtaInstructions)(this.rpc, manager, remainingAccounts);
+        const swapPreInstructions = resolvedCpiData.flatMap((cpi) => cpi.preInstructions ?? []);
+        return {
+            instructions: [
+                ...swapPreInstructions,
+                ...instructions,
+                ...preamble,
+                await this.getIx({
+                    yieldingBank: args.yieldingBank,
+                    params: {
+                        ixRefs,
+                        remainingAccounts,
+                    },
+                }),
+            ],
+            lookupTables: this.getTxLookupTables(undefined, lookupTables ?? []),
+            postSuccessCacheInvalidations: [
+                (0, utils_1.getYieldingBankCacheInvalidation)(args.yieldingBank),
+                ...resolvedCpiData.flatMap((cpi) => cpi.postSuccessCacheInvalidations ?? []),
+                ...refreshCacheInvalidations,
+                ...postSuccessCacheInvalidations,
+            ],
+        };
+    }
+}
+exports.RebalanceYieldingBankBuilder = RebalanceYieldingBankBuilder;

package/dist/sdks/long-yield-carry/src/client/builders/recollateralizeLossBuilder.d.ts

@@ -0,0 +1,12 @@
+import type { Instruction } from "@solana/kit";
+import type { LongYieldCarryTransactionPlan } from "../types";
+import { LongYieldCarryBuilderBase } from "./base";
+import type { RecollateralizeLossIxArgs, RecollateralizeLossTxArgs } from "./args";
+export declare class RecollateralizeLossBuilder extends LongYieldCarryBuilderBase<RecollateralizeLossIxArgs, RecollateralizeLossTxArgs, LongYieldCarryTransactionPlan[]> {
+    getIx(args: RecollateralizeLossIxArgs): Promise<Instruction>;
+    getTx(args: RecollateralizeLossTxArgs): Promise<LongYieldCarryTransactionPlan[]>;
+    private selectRecollateralizationTarget;
+    private buildRecollateralizationSwapPlan;
+    private buildOptionalDecreaseCarryPhase;
+    private buildRecollateralizePhase;
+}

package/dist/sdks/long-yield-carry/src/client/builders/recollateralizeLossBuilder.js

@@ -0,0 +1,220 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RecollateralizeLossBuilder = void 0;
+const web3_js_1 = require("@solana/web3.js");
+const base_1 = require("./base");
+const errors_1 = require("../../errors");
+const decreaseCarryPositionBuilder_1 = require("./decreaseCarryPositionBuilder");
+const common_1 = require("common");
+const lending_platforms_1 = require("lending-platforms");
+const general_1 = require("../../constants/general");
+const carry_1 = require("../../services/carry");
+const utils_1 = require("../../utils");
+// Extra repay (bps of the measured deficit) to offset swap costs and oracle
+// drift, which also scale with the swap size. On-chain only requires the
+// deficit to strictly shrink, so an undershoot just leaves a dust residual
+// for the next run; any surplus (carry > debt) must stay within the on-chain
+// RECOLLATERALIZE_LOSS_THRESHOLD_BPS (20 bps of debt) ceiling.
+const RECOLLATERALIZE_LOSS_OVERSHOOT_BUFFER_BPS = BigInt(10);
+class RecollateralizeLossBuilder extends base_1.LongYieldCarryBuilderBase {
+    async getIx(args) {
+        const tokenData = await this.account.fetchToken(args.token);
+        const collateralMint = (0, common_1.fromWeb3Pk)(tokenData.data.collateral.mint);
+        const collateralOracle = (0, common_1.fromWeb3Pk)(tokenData.data.collateral.oracle);
+        const secondaryCollateralOracle = this.resolveOptionalSecondaryCollateralOracle(tokenData.data.collateral);
+        const collateralTokenProgram = (0, common_1.resolveTokenProgram)(tokenData.data.collateral.tokenProgram);
+        const collateralTokenAccount = await (0, common_1.getAtaAddress)(collateralMint, args.token, collateralTokenProgram);
+        const lpIdx = args.params.lendingPositionIndex;
+        const position = tokenData.data.lendingPositions[lpIdx];
+        // Position may be missing (out-of-bounds) or inactive (zeroed debt mint).
+        // Fall back to an active position so the instruction can reach the on-chain
+        // InvalidLendingPosition check rather than failing on account validation.
+        const isActive = position && !position.accounting.debt.mint.equals(web3_js_1.PublicKey.default);
+        const refPositionEntry = isActive
+            ? { index: lpIdx, data: position }
+            : tokenData.activeLendingPositions[0];
+        const refPosition = refPositionEntry?.data ?? tokenData.data.lendingPositions[0];
+        const debtMint = (0, common_1.fromWeb3Pk)(refPosition.accounting.debt.mint);
+        const debtTokenProgram = (0, common_1.resolveTokenProgram)(refPosition.accounting.debt.tokenProgram);
+        const yieldingBank = args.params.yieldingBank ?? args.token;
+        const [tokenLpDebtTa, yieldingBankTa] = await Promise.all([
+            (0, common_1.getAtaAddress)(debtMint, args.token, debtTokenProgram),
+            (0, common_1.getAtaAddress)(debtMint, yieldingBank, debtTokenProgram),
+        ]);
+        // For out-of-bounds indices (position === undefined), use the ref position's
+        // accounts so the instruction can be built. The on-chain bounds check fires
+        // first and rejects it with InvalidLendingPosition before accounts matter.
+        const lpPositionAccountIdx = isActive ? lpIdx : (refPositionEntry?.index ?? 0);
+        const builtIx = await this.program.methods
+            .recollateralizeLoss({
+            prerequisiteCpis: args.params.prerequisiteCpis ?? null,
+            ixRefs: args.params.ixRefs,
+            lendingPositionIndex: args.params.lendingPositionIndex,
+        })
+            .accountsStrict({
+            manager: this.resolveTokenManager(tokenData.data),
+            token: args.token,
+            collateralMint,
+            collateralTokenAccount,
+            collateralOracle,
+            secondaryCollateralOracle,
+            lpPosition: this.account.getTokenLendingPositionRefreshAccounts(tokenData.data, lpPositionAccountIdx, args.params.lpPosition),
+            collateralTokenProgram,
+            yieldingBank,
+            debtMint,
+            tokenLpDebtTa,
+            yieldingBankTa,
+            debtTokenProgram,
+        })
+            .remainingAccounts(args.params.remainingAccounts.map(common_1.toWeb3AccountMeta))
+            .instruction();
+        return (0, common_1.toKitInstruction)(builtIx);
+    }
+    async getTx(args) {
+        const tokenData = await this.account.fetchToken(args.token, { fresh: true });
+        const txId = args.params.txId ?? `recollateralize-loss-${Date.now()}`;
+        const slippageBps = args.params.swapSlippageBps ?? general_1.DEFAULT_RECOLLATERALIZE_LOSS_SLIPPAGE_BPS;
+        const target = await this.selectRecollateralizationTarget(tokenData);
+        const swapPlan = await this.buildRecollateralizationSwapPlan(target, slippageBps);
+        const dcpPhase = await this.buildOptionalDecreaseCarryPhase(args, target, swapPlan, txId);
+        const recollateralizePhase = await this.buildRecollateralizePhase(args, target, swapPlan, txId);
+        return dcpPhase ? [dcpPhase, recollateralizePhase] : [recollateralizePhase];
+    }
+    async selectRecollateralizationTarget(tokenData) {
+        const totalDebtUsd = tokenData.activeLendingPositions.reduce((sum, { data: lp }) => sum + (0, common_1.toBigInt)(lp.accounting.debt.tvlUsd), BigInt(0));
+        const totalCarryUsd = tokenData.activeCarryPositions.reduce((sum, { data: carry }) => sum + (0, common_1.toBigInt)(carry.tvlUsd), BigInt(0));
+        if (totalDebtUsd <= totalCarryUsd) {
+            throw new errors_1.NoOpTransactionError("Recollateralization not needed: debt does not exceed carry");
+        }
+        const bestLp = tokenData.activeLendingPositions.reduce((best, current) => (0, common_1.toBigInt)(current.data.accounting.collateral) > (0, common_1.toBigInt)(best.data.accounting.collateral)
+            ? current
+            : best);
+        const bestCarry = tokenData.activeCarryPositions.reduce((best, current) => (0, common_1.toBigInt)(current.data.tvlUsd) > (0, common_1.toBigInt)(best.data.tvlUsd) ? current : best);
+        const yieldingBank = await tokenData.deriveYieldingBankAddressForDebtCarryIndex(bestCarry.index, this.pda);
+        return {
+            tokenData,
+            totalDebtUsd,
+            totalCarryUsd,
+            lendingPositionIndex: bestLp.index,
+            position: bestLp.data,
+            yieldingBank,
+        };
+    }
+    async buildRecollateralizationSwapPlan(target, slippageBps) {
+        const { tokenData, position, totalDebtUsd, totalCarryUsd } = target;
+        const debtExcessUsd = totalDebtUsd - totalCarryUsd;
+        const overshootBuffer = (debtExcessUsd * RECOLLATERALIZE_LOSS_OVERSHOOT_BUFFER_BPS) / BigInt(10000);
+        const targetRepayUsd = debtExcessUsd + overshootBuffer;
+        const collateralPrice = (0, common_1.toBigInt)(tokenData.data.collateral.price);
+        if (collateralPrice === BigInt(0)) {
+            throw new Error("Collateral price is zero — refresh the token state first");
+        }
+        const collateralInputAmount = (0, common_1.tvlUsdToBaseUnits)(targetRepayUsd, collateralPrice, tokenData.data.collateral.decimals);
+        if (collateralInputAmount === BigInt(0)) {
+            throw new errors_1.NoOpTransactionError("Collateral input rounds to zero — no recollateralization needed");
+        }
+        const swapQuote = await this.swap.getQuote({
+            inputMint: tokenData.collateralMint,
+            outputMint: (0, common_1.fromWeb3Pk)(position.accounting.debt.mint),
+            amount: Number(collateralInputAmount),
+            slippageBps,
+        });
+        // Minimum guaranteed output after slippage; on-chain repays exactly this amount.
+        // Any surplus from the actual swap sits in the debt ATA and gets deposited to the
+        // yielding bank by the on-chain handler.
+        const repayBaseUnits = (swapQuote.outputAmount * BigInt(10000 - slippageBps)) / BigInt(10000);
+        return {
+            collateralToWithdrawUi: (0, common_1.toUiAmount)(swapQuote.inputAmount, tokenData.data.collateral.decimals),
+            repayUiAmount: (0, common_1.toUiAmount)(repayBaseUnits, position.accounting.debt.decimals),
+            repayBaseUnits,
+            swapQuote,
+        };
+    }
+    async buildOptionalDecreaseCarryPhase(args, target, swapPlan, txId) {
+        const { position, lendingPositionIndex, yieldingBank } = target;
+        const lpClient = this.getLendingPlatformClient(position);
+        lpClient.ix.clearCacheEntry(lpClient.ix.data.userAccountCatKey, (0, common_1.fromWeb3Pk)(position.protocolUserAcc));
+        const lycLendingPositionManager = await carry_1.LycLendingPositionManager.create(lpClient.data, position);
+        const postWithdrawalUtilBps = await lycLendingPositionManager.calcPostWithdrawalUtilizationRateBps(swapPlan.collateralToWithdrawUi);
+        if (postWithdrawalUtilBps <= position.config.targetUtilizationRateBps) {
+            return undefined;
+        }
+        const preWithdrawalTargetBps = await lycLendingPositionManager.calcPreWithdrawalTargetUtilizationRateBps(swapPlan.collateralToWithdrawUi);
+        return new decreaseCarryPositionBuilder_1.DecreaseCarryPositionBuilder(this.context).buildTx(this.resolveTokenManager(target.tokenData.data), args.token, {
+            lendingPositionIndex,
+            yieldingBank,
+            sourceMint: args.params.sourceMint,
+            swapSlippageBps: args.params.swapSlippageBps,
+            repaySteering: {
+                mode: "explicitTargetUtilization",
+                targetUtilizationRateBps: preWithdrawalTargetBps,
+            },
+            txId,
+        }, { includePreInstructions: true });
+    }
+    async buildRecollateralizePhase(args, target, swapPlan, txId) {
+        const { position, lendingPositionIndex } = target;
+        const manager = this.resolveTokenManager(target.tokenData.data);
+        const lpClient = this.getLendingPlatformClient(position);
+        const withdrawCpiData = await this.getLendingOperationCpiData(args.token, manager, position, txId, "withdraw", swapPlan.collateralToWithdrawUi);
+        const swapCpiData = await this.swap.getSwapCpiData(swapPlan.swapQuote, args.token, {
+            payer: manager,
+        });
+        const repayCpiData = await this.getLendingOperationCpiData(args.token, manager, position, txId, "repay", swapPlan.repayUiAmount);
+        const prerequisiteCpiGroup = [...withdrawCpiData.prerequisiteCpis];
+        const executionCpiGroup = [
+            ...withdrawCpiData.cpis,
+            swapCpiData,
+            ...repayCpiData.prerequisiteCpis,
+            ...repayCpiData.cpis,
+        ];
+        const { accounts: remainingAccounts, refsGroups, lookupTables, } = (0, common_1.createMultiCpiRefs)(prerequisiteCpiGroup.length ? [prerequisiteCpiGroup, executionCpiGroup] : [executionCpiGroup]);
+        const prerequisiteCpis = prerequisiteCpiGroup.length ? refsGroups[0] : undefined;
+        const ixRefs = refsGroups[prerequisiteCpiGroup.length ? 1 : 0];
+        const preInstructions = await lpClient.ix.getPreInstructions(txId);
+        const carryTradeAccounts = await this.account.getCarryTradeAccounts(args.token, target.yieldingBank, lendingPositionIndex);
+        const [{ instructions, postSuccessCacheInvalidations }, { instructions: debtAtaInstructions, postSuccessCacheInvalidations: debtAtaInvalidations },] = await Promise.all([
+            (0, common_1.getCreateAtaInstructions)(this.rpc, manager, remainingAccounts),
+            (0, common_1.getCreateAtaInstructions)(this.rpc, manager, carryTradeAccounts),
+        ]);
+        const recollateralizeIx = await this.getIx({
+            token: args.token,
+            params: {
+                prerequisiteCpis,
+                ixRefs,
+                lendingPositionIndex,
+                remainingAccounts,
+                yieldingBank: target.yieldingBank,
+                lpPosition: args.params.lpPosition,
+            },
+        });
+        const setupInstructions = [
+            ...preInstructions,
+            ...(swapCpiData.preInstructions ?? []),
+            ...debtAtaInstructions,
+            ...instructions,
+        ];
+        return {
+            instructions: [
+                ...setupInstructions,
+                // The heap frame applies only to this transaction. Keep it with the
+                // CPI-heavy instruction while allowing refresh and ATA setup to move
+                // into earlier transactions in the same atomic bundle.
+                (0, common_1.requestHeapFrameIx)(general_1.MAX_HEAP_FRAME_BYTES),
+                recollateralizeIx,
+            ],
+            lookupTables: this.getTxLookupTables(args.token, lookupTables ?? []),
+            segmentLengths: [...setupInstructions.map(() => 1), 2],
+            postSuccessCacheInvalidations: [
+                (0, utils_1.getTokenCacheInvalidation)(args.token),
+                (0, lending_platforms_1.getLendingUserAccountCacheInvalidation)((0, common_1.fromWeb3Pk)(position.protocolUserAcc)),
+                ...postSuccessCacheInvalidations,
+                ...debtAtaInvalidations,
+                ...withdrawCpiData.postSuccessCacheInvalidations,
+                ...repayCpiData.postSuccessCacheInvalidations,
+                ...(swapCpiData.postSuccessCacheInvalidations ?? []),
+            ],
+        };
+    }
+}
+exports.RecollateralizeLossBuilder = RecollateralizeLossBuilder;

package/dist/sdks/long-yield-carry/src/client/builders/refreshTokenStateBuilder.d.ts

@@ -0,0 +1,9 @@
+import type { Instruction } from "@solana/kit";
+import type { LongYieldCarryTransactionPlan } from "../types";
+import { LongYieldCarrySingleInstructionBuilderService } from "./base";
+import type { RefreshTokenStateIxArgs } from "./args";
+export declare class RefreshTokenStateBuilder extends LongYieldCarrySingleInstructionBuilderService<RefreshTokenStateIxArgs> {
+    getIx(args: RefreshTokenStateIxArgs): Promise<Instruction>;
+    getTx(args: RefreshTokenStateIxArgs): Promise<LongYieldCarryTransactionPlan>;
+    private getRefreshTokenStateParams;
+}