@kestrelfi/lyc-sdk 1.0.1

package/dist/shared/lending-platforms/src/services/lendingPosition/lendingPositionManager.d.ts

@@ -0,0 +1,117 @@
+import { type Address } from "@solana/kit";
+import { type Environment } from "common";
+import { LendingPlatformData } from "../../data/platform/lpDataBase";
+import { ReserveBase } from "../../data/reserve/reserveBase";
+import { ReservesManager } from "../reservesManager";
+import type { CollateralPriceTriggerBand, LendingPositionInspectMetrics, LendingPositionState, LendingPositionUtilizationPrices, LendingPositionUtilizationRatesBps } from "./types";
+/**
+ * Manages a leveraged lending position (collateral/debt pair): sizing decisions,
+ * threshold triggers, and realtime/EMA-priced state. Wraps a {@link ReservesManager}.
+ *
+ * Generic across protocols — the constructor takes pool + user-account addresses
+ * directly. SDK-specific subclasses may add convenience wrappers that derive
+ * targets from their own on-chain config.
+ */
+export declare class LendingPositionManager {
+    readonly lpData: LendingPlatformData;
+    readonly pool: Address;
+    readonly userAccount: Address;
+    readonly reservesManager: ReservesManager;
+    constructor(lpData: LendingPlatformData, pool: Address, userAccount: Address, collateralReserve: ReserveBase, debtReserve: ReserveBase, environment?: Environment);
+    /**
+     * Calculates the UI debt amount change needed to reach the target LTV utilization
+     * rate. Positive values indicate borrowing; negative values indicate repaying.
+     */
+    calcDebtChangeAmount(targetUtilizationRateBps: number): Promise<number>;
+    /**
+     * Fetch current supply and debt position amounts in UI units.
+     */
+    getLendingPositionAmounts(): Promise<{
+        supplyUiAmount: number;
+        debtUiAmount: number;
+    }>;
+    /**
+     * Calculates the utilization rate the source position must reach before a
+     * collateral withdrawal so that, after the withdrawal, the position lands at
+     * the desired target utilization rate.
+     *
+     * Units:
+     * - current supply USD = supplied collateral before withdrawal
+     * - withdrawn USD = collateral requested for the rebalance move
+     * - post-withdraw target = desired utilization after collateral leaves the LP
+     *
+     * Formula:
+     * pre_withdraw_target = post_withdraw_target * (current_supply - withdrawn) / current_supply
+     *
+     * The result is floored to stay conservatively at or below the requested
+     * post-withdraw target once integer basis-point rounding is applied.
+     */
+    calcPreWithdrawalTargetUtilizationRateBps(withdrawUiCollateralAmount: number, postWithdrawalTargetUtilizationRateBps: number): Promise<number>;
+    /**
+     * Calculates the UI debt amount change needed before a collateral withdrawal
+     * so that the position lands at the desired utilization rate after the
+     * withdrawal completes.
+     */
+    calcDebtChangeAmountForCollateralWithdrawal(withdrawUiCollateralAmount: number, postWithdrawalTargetUtilizationRateBps: number): Promise<number>;
+    /**
+     * Calculates the utilization rate after withdrawing collateral while leaving
+     * debt unchanged.
+     */
+    calcPostWithdrawalUtilizationRateBps(withdrawUiCollateralAmount: number): Promise<number>;
+    /**
+     * For burn-token liquidity management: checks that a withdrawal of
+     * `collateralWithdrawalUiAmount` (collateral mint UI units) leaves strictly
+     * positive supplied collateral, matching the pre-withdraw math used in
+     * {@link calcPreWithdrawalTargetUtilizationRateBps}.
+     *
+     * Returns realtime LTV utilization in basis points when eligible; null when the
+     * obligation is missing, has no supply, prices are invalid, or the withdrawal
+     * would consume the full (or more than the full) collateral position.
+     */
+    getBurnUnwindEligibility(collateralWithdrawalUiAmount: number): Promise<{
+        utilizationRateBps: number;
+    } | null>;
+    /**
+     * Returns the collateral price levels that would place the position exactly on
+     * its lower and upper utilization trigger bands.
+     *
+     * The lower-band trigger uses EMA pricing (to mirror boost-trigger semantics),
+     * while the upper-band trigger uses realtime pricing (to mirror unwind-trigger
+     * semantics).
+     */
+    getCollateralPriceTriggerBand(params: {
+        lowerTargetUtilizationRateBps: number;
+        upperTargetUtilizationRateBps: number;
+    }): Promise<CollateralPriceTriggerBand>;
+    getUtilizationRatesBps(): Promise<LendingPositionUtilizationRatesBps | null>;
+    getUtilizationPrices(): Promise<LendingPositionUtilizationPrices | null>;
+    getInspectMetrics(params: {
+        lowerTargetUtilizationRateBps: number;
+        upperTargetUtilizationRateBps: number;
+    }): Promise<LendingPositionInspectMetrics | null>;
+    protected getPositionState(mode: "realtime" | "ema"): Promise<LendingPositionState | null>;
+    private calcPositionSupplyDebtUsd;
+    private selectPrice;
+    private getCollateralPriceTriggerLevel;
+    /**
+     * Solve for collateral price at a target utilization:
+     * utilization = debtUsd / (collateralAmount * collateralPrice * maxLtv).
+     */
+    private calcCollateralPriceForTargetUtilization;
+    private calcDebtChangeAmountFromState;
+    /**
+     * Quantize to the debt mint's base-unit precision. Borrows floor; repays round
+     * away from zero so deleveraging does not undershoot.
+     */
+    private quantizeDebtChangeUiAmount;
+    /** Cap positive borrows to obligation headroom when the platform exposes it. */
+    private capPositiveBorrowToProtocolHeadroom;
+    private calcPreWithdrawalTargetUtilizationRateBpsFromState;
+    private calcPostWithdrawalUtilizationRateBpsFromState;
+    protected assertValidUtilizationRateBps(value: number, field: string): void;
+    /**
+     * Unwind/boost trigger bands may exceed 100% LTV utilization (up to 10_500 bps
+     * on-chain). Debt-sizing paths still use {@link assertValidUtilizationRateBps}.
+     */
+    protected assertValidTriggerBandUtilizationRateBps(value: number, field: string): void;
+}

package/dist/shared/lending-platforms/src/services/lendingPosition/lendingPositionManager.js

@@ -0,0 +1,342 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LendingPositionManager = void 0;
+const core_1 = require("@anchor-lang/core");
+const common_1 = require("common");
+const lendingPosition_1 = require("../../constants/lendingPosition");
+const reservesManager_1 = require("../reservesManager");
+/**
+ * Manages a leveraged lending position (collateral/debt pair): sizing decisions,
+ * threshold triggers, and realtime/EMA-priced state. Wraps a {@link ReservesManager}.
+ *
+ * Generic across protocols — the constructor takes pool + user-account addresses
+ * directly. SDK-specific subclasses may add convenience wrappers that derive
+ * targets from their own on-chain config.
+ */
+class LendingPositionManager {
+    constructor(lpData, pool, userAccount, collateralReserve, debtReserve, environment) {
+        this.lpData = lpData;
+        this.pool = pool;
+        this.userAccount = userAccount;
+        this.reservesManager = new reservesManager_1.ReservesManager(collateralReserve, debtReserve, environment);
+    }
+    /**
+     * Calculates the UI debt amount change needed to reach the target LTV utilization
+     * rate. Positive values indicate borrowing; negative values indicate repaying.
+     */
+    async calcDebtChangeAmount(targetUtilizationRateBps) {
+        const state = await this.getPositionState("realtime");
+        if (!state)
+            return 0;
+        return this.calcDebtChangeAmountFromState(state, targetUtilizationRateBps);
+    }
+    /**
+     * Fetch current supply and debt position amounts in UI units.
+     */
+    async getLendingPositionAmounts() {
+        const state = await this.getPositionState("realtime");
+        if (!state)
+            return { supplyUiAmount: 0, debtUiAmount: 0 };
+        const supplyPrice = state.prices.supply.realtimePrice;
+        const debtPrice = state.prices.debt.realtimePrice;
+        return {
+            supplyUiAmount: supplyPrice > 0 ? state.supplyUsd / supplyPrice : 0,
+            debtUiAmount: debtPrice > 0 ? state.debtUsd / debtPrice : 0,
+        };
+    }
+    /**
+     * Calculates the utilization rate the source position must reach before a
+     * collateral withdrawal so that, after the withdrawal, the position lands at
+     * the desired target utilization rate.
+     *
+     * Units:
+     * - current supply USD = supplied collateral before withdrawal
+     * - withdrawn USD = collateral requested for the rebalance move
+     * - post-withdraw target = desired utilization after collateral leaves the LP
+     *
+     * Formula:
+     * pre_withdraw_target = post_withdraw_target * (current_supply - withdrawn) / current_supply
+     *
+     * The result is floored to stay conservatively at or below the requested
+     * post-withdraw target once integer basis-point rounding is applied.
+     */
+    async calcPreWithdrawalTargetUtilizationRateBps(withdrawUiCollateralAmount, postWithdrawalTargetUtilizationRateBps) {
+        const state = await this.getPositionState("realtime");
+        if (!state)
+            return 0;
+        return this.calcPreWithdrawalTargetUtilizationRateBpsFromState(state, withdrawUiCollateralAmount, postWithdrawalTargetUtilizationRateBps);
+    }
+    /**
+     * Calculates the UI debt amount change needed before a collateral withdrawal
+     * so that the position lands at the desired utilization rate after the
+     * withdrawal completes.
+     */
+    async calcDebtChangeAmountForCollateralWithdrawal(withdrawUiCollateralAmount, postWithdrawalTargetUtilizationRateBps) {
+        const state = await this.getPositionState("realtime");
+        if (!state)
+            return 0;
+        const preWithdrawalTargetUtilizationRateBps = this.calcPreWithdrawalTargetUtilizationRateBpsFromState(state, withdrawUiCollateralAmount, postWithdrawalTargetUtilizationRateBps);
+        return this.calcDebtChangeAmountFromState(state, preWithdrawalTargetUtilizationRateBps);
+    }
+    /**
+     * Calculates the utilization rate after withdrawing collateral while leaving
+     * debt unchanged.
+     */
+    async calcPostWithdrawalUtilizationRateBps(withdrawUiCollateralAmount) {
+        const state = await this.getPositionState("realtime");
+        if (!state)
+            return 0;
+        return this.calcPostWithdrawalUtilizationRateBpsFromState(state, withdrawUiCollateralAmount);
+    }
+    /**
+     * For burn-token liquidity management: checks that a withdrawal of
+     * `collateralWithdrawalUiAmount` (collateral mint UI units) leaves strictly
+     * positive supplied collateral, matching the pre-withdraw math used in
+     * {@link calcPreWithdrawalTargetUtilizationRateBps}.
+     *
+     * Returns realtime LTV utilization in basis points when eligible; null when the
+     * obligation is missing, has no supply, prices are invalid, or the withdrawal
+     * would consume the full (or more than the full) collateral position.
+     */
+    async getBurnUnwindEligibility(collateralWithdrawalUiAmount) {
+        if (!(collateralWithdrawalUiAmount > 0)) {
+            return null;
+        }
+        const state = await this.getPositionState("realtime");
+        if (!state) {
+            return null;
+        }
+        const collateralPrice = state.prices.supply.realtimePrice;
+        if (!(collateralPrice > 0)) {
+            return null;
+        }
+        const withdrawnCollateralUsd = collateralWithdrawalUiAmount * collateralPrice;
+        if (!(withdrawnCollateralUsd < state.supplyUsd)) {
+            return null;
+        }
+        const utilizationRateBps = this.reservesManager.calcLtvUtilizationRateBps(state.supplyUsd, state.debtUsd);
+        return { utilizationRateBps };
+    }
+    /**
+     * Returns the collateral price levels that would place the position exactly on
+     * its lower and upper utilization trigger bands.
+     *
+     * The lower-band trigger uses EMA pricing (to mirror boost-trigger semantics),
+     * while the upper-band trigger uses realtime pricing (to mirror unwind-trigger
+     * semantics).
+     */
+    async getCollateralPriceTriggerBand(params) {
+        const [lower, upper] = await Promise.all([
+            this.getCollateralPriceTriggerLevel("ema", params.lowerTargetUtilizationRateBps),
+            this.getCollateralPriceTriggerLevel("realtime", params.upperTargetUtilizationRateBps),
+        ]);
+        return { lower, upper };
+    }
+    async getUtilizationRatesBps() {
+        const [realtimeState, emaState] = await Promise.all([
+            this.getPositionState("realtime"),
+            this.getPositionState("ema"),
+        ]);
+        if (!realtimeState || !emaState) {
+            return null;
+        }
+        return {
+            realtime: this.reservesManager.calcLtvUtilizationRateBps(realtimeState.supplyUsd, realtimeState.debtUsd),
+            ema: this.reservesManager.calcLtvUtilizationRateBps(emaState.supplyUsd, emaState.debtUsd),
+        };
+    }
+    async getUtilizationPrices() {
+        const [realtimeState, emaState] = await Promise.all([
+            this.getPositionState("realtime"),
+            this.getPositionState("ema"),
+        ]);
+        if (!realtimeState || !emaState) {
+            return null;
+        }
+        return {
+            realtime: {
+                collateral: this.selectPrice(realtimeState.prices.supply, "realtime"),
+                debt: this.selectPrice(realtimeState.prices.debt, "realtime"),
+            },
+            ema: {
+                collateral: this.selectPrice(emaState.prices.supply, "ema"),
+                debt: this.selectPrice(emaState.prices.debt, "ema"),
+            },
+        };
+    }
+    async getInspectMetrics(params) {
+        const [utilizationRateBps, utilizationPrices, triggerBand] = await Promise.all([
+            this.getUtilizationRatesBps(),
+            this.getUtilizationPrices(),
+            this.getCollateralPriceTriggerBand(params),
+        ]);
+        if (!utilizationRateBps || !utilizationPrices) {
+            return null;
+        }
+        return { utilizationRateBps, utilizationPrices, triggerBand };
+    }
+    async getPositionState(mode) {
+        const position = await this.lpData.maybeFetchUserPositionInPool(this.pool, this.userAccount);
+        if (!position)
+            return null;
+        const prices = await this.reservesManager.prices();
+        const { supplyUsd, debtUsd } = this.calcPositionSupplyDebtUsd(position, prices, mode);
+        return { prices, supplyUsd, debtUsd };
+    }
+    calcPositionSupplyDebtUsd(position, prices, mode) {
+        const { supplyReserve, debtReserve } = this.reservesManager;
+        const deposit = position.deposits.find((d) => d.reserve === supplyReserve.address);
+        const borrow = position.borrows.find((b) => b.reserve === debtReserve.address);
+        const supplyAmount = deposit ? (0, common_1.toUiAmount)(deposit.amount, supplyReserve.mint.mintDecimals) : 0;
+        const debtAmount = borrow ? (0, common_1.toUiAmount)(borrow.amount, debtReserve.mint.mintDecimals) : 0;
+        return {
+            supplyUsd: supplyAmount * this.selectPrice(prices.supply, mode).value,
+            debtUsd: debtAmount * this.selectPrice(prices.debt, mode).value,
+        };
+    }
+    selectPrice(price, mode) {
+        if (mode === "realtime") {
+            return { value: price.realtimePrice, source: "realtime" };
+        }
+        if (price.emaPrice != null) {
+            return { value: price.emaPrice, source: "ema" };
+        }
+        return { value: price.realtimePrice, source: "ema_fallback_realtime" };
+    }
+    async getCollateralPriceTriggerLevel(mode, targetUtilizationRateBps) {
+        this.assertValidTriggerBandUtilizationRateBps(targetUtilizationRateBps, "targetUtilizationRateBps");
+        if (targetUtilizationRateBps === 0) {
+            return undefined;
+        }
+        const state = await this.getPositionState(mode);
+        if (!state) {
+            return undefined;
+        }
+        const currentCollateralPrice = mode === "ema"
+            ? (state.prices.supply.emaPrice ?? state.prices.supply.realtimePrice)
+            : state.prices.supply.realtimePrice;
+        if (currentCollateralPrice <= 0 || state.debtUsd < 0 || this.reservesManager.maxLtv <= 0) {
+            return undefined;
+        }
+        const uiSupplyAmount = state.supplyUsd / currentCollateralPrice;
+        if (uiSupplyAmount <= 0) {
+            return undefined;
+        }
+        const triggerCollateralPrice = this.calcCollateralPriceForTargetUtilization(state.debtUsd, uiSupplyAmount, targetUtilizationRateBps);
+        if (!Number.isFinite(triggerCollateralPrice) || triggerCollateralPrice < 0) {
+            return undefined;
+        }
+        return {
+            currentCollateralPrice,
+            triggerCollateralPrice,
+            targetUtilizationRateBps,
+            priceMode: mode,
+            priceChangePct: ((triggerCollateralPrice - currentCollateralPrice) / currentCollateralPrice) * 100,
+        };
+    }
+    /**
+     * Solve for collateral price at a target utilization:
+     * utilization = debtUsd / (collateralAmount * collateralPrice * maxLtv).
+     */
+    calcCollateralPriceForTargetUtilization(debtUsd, uiSupplyAmount, targetUtilizationRateBps) {
+        const targetUtilizationRate = targetUtilizationRateBps / 10000;
+        return debtUsd / (uiSupplyAmount * this.reservesManager.maxLtv * targetUtilizationRate);
+    }
+    async calcDebtChangeAmountFromState(state, targetUtilizationRateBps) {
+        this.assertValidUtilizationRateBps(targetUtilizationRateBps, "targetUtilizationRateBps");
+        if (state.prices.debt.realtimePrice <= 0) {
+            throw new Error("Debt reserve realtime price must be positive");
+        }
+        if (state.prices.supply.realtimePrice <= 0) {
+            throw new Error("Collateral reserve realtime price must be positive");
+        }
+        const debtAdjustmentUsd = await this.reservesManager.calcDebtAdjustmentUsd(state.supplyUsd / state.prices.supply.realtimePrice, state.debtUsd / state.prices.debt.realtimePrice, targetUtilizationRateBps, { positionChangeMode: "debtOnly" });
+        const debtChangeUiAmount = debtAdjustmentUsd / state.prices.debt.realtimePrice;
+        const debtDecimals = this.reservesManager.debtReserve.mint.mintDecimals;
+        let quantizedUiAmount = this.quantizeDebtChangeUiAmount(debtChangeUiAmount, debtDecimals);
+        if (quantizedUiAmount > 0) {
+            quantizedUiAmount = await this.capPositiveBorrowToProtocolHeadroom(quantizedUiAmount, state);
+        }
+        return debtChangeUiAmount < 0 ? -quantizedUiAmount : quantizedUiAmount;
+    }
+    /**
+     * Quantize to the debt mint's base-unit precision. Borrows floor; repays round
+     * away from zero so deleveraging does not undershoot.
+     */
+    quantizeDebtChangeUiAmount(debtChangeUiAmount, debtDecimals) {
+        if (debtChangeUiAmount === 0)
+            return 0;
+        const absUi = Math.abs(debtChangeUiAmount);
+        if (debtChangeUiAmount > 0) {
+            if (!(absUi > 0))
+                return 0;
+            const flooredBaseUnits = new core_1.BN(Math.floor(absUi * Math.pow(10, debtDecimals)));
+            return (0, common_1.toUiAmount)(flooredBaseUnits, debtDecimals);
+        }
+        const roundedAmount = (0, common_1.fromUiAmount)(absUi, debtDecimals);
+        let repayUi = (0, common_1.toUiAmount)(roundedAmount, debtDecimals);
+        if (repayUi < absUi) {
+            repayUi = (0, common_1.toUiAmount)(roundedAmount.addn(1), debtDecimals);
+        }
+        return repayUi;
+    }
+    /** Cap positive borrows to obligation headroom when the platform exposes it. */
+    async capPositiveBorrowToProtocolHeadroom(requestedUiAmount, state) {
+        const debtDecimals = this.reservesManager.debtReserve.mint.mintDecimals;
+        const position = await this.lpData.maybeFetchUserPositionInPool(this.pool, this.userAccount);
+        if (!position) {
+            return requestedUiAmount;
+        }
+        const maxUi = position.getMaxAdditionalBorrowUiAmount(state.prices.debt.realtimePrice, debtDecimals);
+        if (maxUi === undefined) {
+            return requestedUiAmount;
+        }
+        return Math.min(requestedUiAmount, maxUi);
+    }
+    calcPreWithdrawalTargetUtilizationRateBpsFromState(state, withdrawUiCollateralAmount, postWithdrawalTargetUtilizationRateBps) {
+        if (withdrawUiCollateralAmount <= 0) {
+            throw new Error("withdrawUiCollateralAmount must be greater than zero");
+        }
+        this.assertValidUtilizationRateBps(postWithdrawalTargetUtilizationRateBps, "postWithdrawalTargetUtilizationRateBps");
+        const collateralPrice = state.prices.supply.realtimePrice;
+        if (collateralPrice <= 0) {
+            throw new Error("Collateral reserve realtime price must be positive");
+        }
+        const withdrawnCollateralUsd = withdrawUiCollateralAmount * collateralPrice;
+        if (withdrawnCollateralUsd >= state.supplyUsd) {
+            throw new Error("withdrawUiCollateralAmount exceeds the current supplied collateral");
+        }
+        const preWithdrawalTargetUtilizationRateBps = Math.floor((postWithdrawalTargetUtilizationRateBps * (state.supplyUsd - withdrawnCollateralUsd)) /
+            state.supplyUsd);
+        return Math.max(0, Math.min(postWithdrawalTargetUtilizationRateBps, preWithdrawalTargetUtilizationRateBps));
+    }
+    calcPostWithdrawalUtilizationRateBpsFromState(state, withdrawUiCollateralAmount) {
+        if (withdrawUiCollateralAmount <= 0) {
+            throw new Error("withdrawUiCollateralAmount must be greater than zero");
+        }
+        const collateralPrice = state.prices.supply.realtimePrice;
+        if (collateralPrice <= 0) {
+            throw new Error("Collateral reserve realtime price must be positive");
+        }
+        const withdrawnCollateralUsd = withdrawUiCollateralAmount * collateralPrice;
+        if (withdrawnCollateralUsd >= state.supplyUsd) {
+            throw new Error("withdrawUiCollateralAmount exceeds the current supplied collateral");
+        }
+        return this.reservesManager.calcLtvUtilizationRateBps(state.supplyUsd - withdrawnCollateralUsd, state.debtUsd);
+    }
+    assertValidUtilizationRateBps(value, field) {
+        if (!Number.isFinite(value) || value < 0 || value > 10000) {
+            throw new Error(`${field} must be between 0 and 10000`);
+        }
+    }
+    /**
+     * Unwind/boost trigger bands may exceed 100% LTV utilization (up to 10_500 bps
+     * on-chain). Debt-sizing paths still use {@link assertValidUtilizationRateBps}.
+     */
+    assertValidTriggerBandUtilizationRateBps(value, field) {
+        if (!Number.isFinite(value) || value < 0 || value > lendingPosition_1.MAX_LENDING_POSITION_UPPER_UTIL_BPS) {
+            throw new Error(`${field} must be between 0 and ${lendingPosition_1.MAX_LENDING_POSITION_UPPER_UTIL_BPS}`);
+        }
+    }
+}
+exports.LendingPositionManager = LendingPositionManager;

package/dist/shared/lending-platforms/src/services/lendingPosition/types.d.ts

@@ -0,0 +1,40 @@
+import type { ReservesPrices } from "../reservesManager";
+export interface LendingPositionState {
+    prices: ReservesPrices;
+    supplyUsd: number;
+    debtUsd: number;
+}
+export interface CollateralPriceTriggerLevel {
+    currentCollateralPrice: number;
+    triggerCollateralPrice: number;
+    targetUtilizationRateBps: number;
+    priceMode: "realtime" | "ema";
+    priceChangePct: number;
+}
+export interface CollateralPriceTriggerBand {
+    lower?: CollateralPriceTriggerLevel;
+    upper?: CollateralPriceTriggerLevel;
+}
+export interface LendingPositionUtilizationRatesBps {
+    realtime: number;
+    ema: number;
+}
+export interface LendingPositionSelectedPrice {
+    value: number;
+    source: "realtime" | "ema" | "ema_fallback_realtime";
+}
+export interface LendingPositionUtilizationPrices {
+    realtime: {
+        collateral: LendingPositionSelectedPrice;
+        debt: LendingPositionSelectedPrice;
+    };
+    ema: {
+        collateral: LendingPositionSelectedPrice;
+        debt: LendingPositionSelectedPrice;
+    };
+}
+export interface LendingPositionInspectMetrics {
+    utilizationRateBps: LendingPositionUtilizationRatesBps;
+    utilizationPrices: LendingPositionUtilizationPrices;
+    triggerBand: CollateralPriceTriggerBand;
+}

package/dist/shared/lending-platforms/src/services/lendingPosition/types.js

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

package/dist/shared/lending-platforms/src/services/leverage/index.d.ts

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

package/dist/shared/lending-platforms/src/services/leverage/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("./leverageService"), exports);
+__exportStar(require("./types"), exports);

package/dist/shared/lending-platforms/src/services/leverage/leverageService.d.ts

@@ -0,0 +1,104 @@
+import type { Instruction } from "@solana/kit";
+import type { DecreaseLeverageParams, DecreaseLeverageResult, FlashRebalanceContext, FlashRebalanceParams, FlashRebalanceResult, IncreaseLeverageParams, IncreaseLeverageResult, LeverageContext } from "./types";
+/**
+ * Thrown by {@link LeverageService.buildFlashRebalance} when the quoted
+ * destination-debt → source-debt swap breaches a caller-set bound. The quote's
+ * total below-par gap is split into two components, each bounded separately:
+ *
+ * - `executionCostBps` — quote rate vs the oracle-fair cross rate: route fees
+ *   + price impact. Permanently lost value.
+ * - `marketBasisBps` — oracle-fair cross rate vs 1:1: genuine USD price
+ *   difference between the two stables. Charged to the token's carry-vs-debt
+ *   difference by the $1-pinned books at conversion time, but reverses on
+ *   unwind if the basis persists.
+ *
+ * `reason` names which bound was breached; both measured components are
+ * always populated for logging/telemetry.
+ */
+export declare class FlashRebalanceSwapCostExceededError extends Error {
+    readonly reason: "execution-cost" | "market-basis";
+    readonly executionCostBps: number;
+    readonly marketBasisBps: number;
+    readonly limitBps: number;
+    readonly inputAmount: bigint;
+    readonly outputAmount: bigint;
+    constructor(reason: "execution-cost" | "market-basis", executionCostBps: number, marketBasisBps: number, limitBps: number, inputAmount: bigint, outputAmount: bigint);
+}
+/**
+ * Stateless service that sizes and builds lending-protocol CPIs for leverage
+ * changes on a collateral/debt reserve pair.
+ *
+ * Inputs are generic lending-platform types (reserves, LP client, position
+ * identifiers). No program-specific types.
+ *
+ * - **Increase leverage** → calculates borrow amount to reach target, builds
+ *   borrow CPIs.
+ * - **Decrease leverage** → calculates repay amount to reach target, builds
+ *   repay CPIs, and assembles swap + repay CPI groups when the debt token must
+ *   be obtained via swap.
+ */
+export declare class LeverageService {
+    /**
+     * Calculate the borrow amount needed to reach the target utilization rate,
+     * then build the borrow CPIs.
+     */
+    static buildIncreaseLeverage(ctx: LeverageContext, params: IncreaseLeverageParams): Promise<IncreaseLeverageResult>;
+    /**
+     * Calculate the repay amount needed to reach the target utilization rate,
+     * build the repay CPIs, and assemble CPI groups with an optional swap
+     * prepended when the caller's debt-token balance is insufficient.
+     *
+     * The returned `repayUiAmount` is always non-negative. When the position is
+     * already at or below the target, the amount is zero and the CPI list is
+     * sized for a zero repay.
+     */
+    static buildDecreaseLeverage(ctx: LeverageContext, params: DecreaseLeverageParams): Promise<DecreaseLeverageResult>;
+    /**
+     * Assemble repay CPI groups, prepending a swap group whenever the bank is
+     * configured to source the debt mint via a swap. The on-chain handler
+     * decides whether to actually invoke the swap (via `perform_swap`) based on
+     * runtime balances; building it unconditionally keeps the tx resilient when
+     * the bank's debt-token balance changes between build and send.
+     */
+    private static assembleDecreaseLeverageCpis;
+    /**
+     * Quote a swap that converts a source asset into the debt mint,
+     * covering at least `shortfall` base units.
+     */
+    private static quoteDebtTopUpSwap;
+    /**
+     * Build a flash-loan-wrapped rebalance that moves collateral between two
+     * lending positions without decreasing any carry positions.
+     *
+     * The flow assembled here (inside a single transaction):
+     *   1. Top-level: flash-borrow source debt mint into the user's ATA.
+     *   2. CPI: repay flash-borrowed amount on source → frees collateral.
+     *   3. CPI: withdraw `collateralUiAmount` from source.
+     *   4. CPI: deposit that collateral on destination.
+     *   5. CPI: borrow destination debt mint (sized slightly above the swap
+     *      input needed to produce the flash repay, so post-slippage output
+     *      still covers it).
+     *   6. CPI: exact-in swap destination debt → source debt; the entire borrow
+     *      is consumed and worst-case output is at least the flash repay amount.
+     *   7. Top-level: flash-repay source debt mint.
+     *
+     * The exact-in over-borrow leaves a small **source-debt** excess in the
+     * token PDA's ATA after the swap; the on-chain handler sweeps this excess
+     * into the yielding bank before the top-level flash repay so exactly
+     * `flashRepayAmountBaseUnits` remains for the repay.
+     */
+    static buildFlashRebalance(ctx: FlashRebalanceContext, params: FlashRebalanceParams): Promise<FlashRebalanceResult>;
+    /**
+     * Build the top-level flash-repay instruction for a previously-built flash
+     * rebalance, given the final transaction index of its `flashBorrowIx`.
+     *
+     * Split from {@link buildFlashRebalance} because `borrowIxIndex` depends on
+     * the caller's full tx layout (pre-instructions + heap frame + ATA creations
+     * + flash-borrow position), which in turn depends on the ATA list derived
+     * from the plan's `remainingAccounts` — a chicken-and-egg the caller resolves
+     * by assembling the preamble before calling this.
+     */
+    static buildFlashRepayIx(ctx: FlashRebalanceContext, plan: Pick<FlashRebalanceResult, "flashBorrowAmountBaseUnits">, borrowIxIndex: number): Promise<Instruction>;
+    private static calcSourceRepayForWithdraw;
+    private static calcDestinationBorrowCapacityForDeposit;
+}