@kestrelfi/lyc-sdk 1.0.1

package/dist/sdks/long-yield-carry/src/services/rebalance/yieldingBank/planner.js

@@ -0,0 +1,181 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RebalancePlanner = void 0;
+const web3_js_1 = require("@solana/web3.js");
+const common_1 = require("common");
+/** Minimum 6-decimal stablecoin amount worth swapping: 0.01 token (~$0.01). */
+const MIN_STABLE_SWAP_AMOUNT = 10000;
+/**
+ * Computes the swaps needed to move a yielding bank from its current
+ * asset distribution to a target allocation.
+ *
+ * The planner is stateless and performs no RPC — it operates entirely on
+ * the in-memory bank model and the strategy's target. This makes it
+ * straightforward to unit-test.
+ *
+ * ## How it works
+ *
+ * 1. The {@link AllocationStrategy} produces a {@link TargetAllocation}
+ *    (e.g. 25% USD*, 75% USD*-J).
+ * 2. The planner classifies every bank holding as either a **target**
+ *    (a mint the strategy manages) or an **idle source** (everything
+ *    else — the base asset, plus any non-target stablecoins that
+ *    arrived from borrows in other denominations).
+ * 3. Each idle source with a non-trivial balance gets its own
+ *    {@link YieldingBankRebalancePlan} that deploys its capital
+ *    proportionally across the targets according to their weights.
+ * 4. If existing target holdings are imbalanced relative to their
+ *    weights (overweight / underweight), a separate rebalance plan
+ *    routes through the base mint. The resulting swaps are sorted
+ *    sells-first so freed base-mint liquidity is available for
+ *    subsequent buy swaps.
+ *
+ * All swaps route through the bank's base mint as the common
+ * intermediate, matching how the on-chain `rebalance_yielding_bank`
+ * instruction processes CPI swaps.
+ */
+class RebalancePlanner {
+    constructor(strategy) {
+        this.strategy = strategy;
+    }
+    /**
+     * Plan the rebalance for a single yielding bank.
+     * Returns an empty array if no action is needed.
+     *
+     * Each element is an independent plan that can be sent as its own
+     * transaction. Separate plans are produced for:
+     * - Each idle source (base asset, or non-target stablecoins)
+     * - Target-to-target rebalancing (selling overweight, buying underweight)
+     */
+    plan(bank) {
+        const targets = this.strategy.computeTarget(bank);
+        const targetMints = new Set(targets.map((t) => t.mint));
+        const idleSources = this.discoverIdleSources(bank, targetMints);
+        const targetHoldings = this.snapshotTargetHoldings(bank, targetMints);
+        const plans = [];
+        for (const source of idleSources) {
+            const plan = this.buildDeploymentPlan(bank, targets, source);
+            if (plan)
+                plans.push(plan);
+        }
+        const rebalancePlan = this.buildTargetRebalancePlan(bank, targets, targetHoldings);
+        if (rebalancePlan)
+            plans.push(rebalancePlan);
+        return plans;
+    }
+    // ---------------------------------------------------------------------------
+    // Idle source discovery
+    // ---------------------------------------------------------------------------
+    /**
+     * Returns every holding on the bank that is NOT a strategy target.
+     * This includes the base asset and any non-target asset slots with
+     * a positive balance (e.g. a stablecoin that arrived from a
+     * non-base-mint borrow).
+     */
+    discoverIdleSources(bank, targetMints) {
+        const sources = [];
+        const baseAmount = (0, common_1.toBigInt)(bank.data.baseAsset.amount);
+        if (baseAmount > 0n) {
+            sources.push({ mint: bank.baseMint, amount: baseAmount });
+        }
+        for (const asset of bank.data.assets) {
+            if (asset.mint.equals(web3_js_1.PublicKey.default))
+                continue;
+            const mint = (0, common_1.fromWeb3Pk)(asset.mint);
+            if (targetMints.has(mint))
+                continue;
+            const amount = (0, common_1.toBigInt)(asset.amount);
+            if (amount > 0n) {
+                sources.push({ mint, amount });
+            }
+        }
+        return sources;
+    }
+    /** Snapshot only the holdings that ARE strategy targets. */
+    snapshotTargetHoldings(bank, targetMints) {
+        const result = [];
+        for (const asset of bank.data.assets) {
+            if (asset.mint.equals(web3_js_1.PublicKey.default))
+                continue;
+            const mint = (0, common_1.fromWeb3Pk)(asset.mint);
+            if (!targetMints.has(mint))
+                continue;
+            result.push({ mint, amount: (0, common_1.toBigInt)(asset.amount) });
+        }
+        return result;
+    }
+    // ---------------------------------------------------------------------------
+    // Plan builders
+    // ---------------------------------------------------------------------------
+    /**
+     * Build a plan that deploys a single idle source proportionally
+     * across the strategy's targets according to their weights.
+     */
+    buildDeploymentPlan(bank, targets, source) {
+        if (source.amount < BigInt(MIN_STABLE_SWAP_AMOUNT))
+            return null;
+        const swaps = [];
+        let newAllocation;
+        for (const alloc of targets) {
+            const share = (0, common_1.applyBps)(source.amount, alloc.weightBps);
+            if (Number(share) < MIN_STABLE_SWAP_AMOUNT)
+                continue;
+            swaps.push({
+                inputMint: source.mint,
+                outputMint: alloc.mint,
+                amount: Number(share),
+                slippageBps: alloc.slippageBps,
+            });
+            if (!newAllocation && bank.findAssetHolding(alloc.mint) === null) {
+                newAllocation = { config: alloc.allocationConfig };
+            }
+        }
+        if (swaps.length === 0 && !newAllocation)
+            return null;
+        return { swaps, newAllocation };
+    }
+    /**
+     * Build a plan that rebalances between existing target holdings when
+     * they've drifted from the strategy's desired weights. Overweight
+     * targets are sold back to the base mint; underweight targets are
+     * bought with the freed base.
+     */
+    buildTargetRebalancePlan(bank, targets, targetHoldings) {
+        const totalTargetValue = targetHoldings.reduce((sum, h) => sum + h.amount, 0n);
+        if (totalTargetValue <= 0n)
+            return null;
+        const swaps = [];
+        for (const alloc of targets) {
+            const desired = (0, common_1.applyBps)(totalTargetValue, alloc.weightBps);
+            const current = this.findCurrentAmount(targetHoldings, alloc.mint);
+            const delta = desired - current;
+            const absDelta = delta < 0n ? -delta : delta;
+            if (Number(absDelta) < MIN_STABLE_SWAP_AMOUNT)
+                continue;
+            if (delta < 0n) {
+                swaps.push({
+                    inputMint: alloc.mint,
+                    outputMint: bank.baseMint,
+                    amount: Number(absDelta),
+                    slippageBps: alloc.slippageBps,
+                });
+            }
+            else {
+                swaps.push({
+                    inputMint: bank.baseMint,
+                    outputMint: alloc.mint,
+                    amount: Number(delta),
+                    slippageBps: alloc.slippageBps,
+                });
+            }
+        }
+        if (swaps.length === 0)
+            return null;
+        swaps.sort((a, b) => (a.inputMint === bank.baseMint ? 1 : 0) - (b.inputMint === bank.baseMint ? 1 : 0));
+        return { swaps };
+    }
+    findCurrentAmount(holdings, mint) {
+        return holdings.find((h) => h.mint === mint)?.amount ?? 0n;
+    }
+}
+exports.RebalancePlanner = RebalancePlanner;

package/dist/sdks/long-yield-carry/src/services/rebalance/yieldingBank/strategy.d.ts

@@ -0,0 +1,26 @@
+import type { LYCYieldingBank } from "../../../models";
+import type { TargetAllocation } from "./types";
+/**
+ * Decides the target allocation for a yielding bank's non-base assets.
+ *
+ * Implementations receive the current bank state and return the desired
+ * distribution across yield-bearing assets. The {@link RebalancePlanner}
+ * then computes the delta (swaps) needed to reach that target.
+ *
+ * Strategies should be pure functions of the bank state (and any external
+ * data injected through the constructor). They must not perform RPC calls
+ * or side effects.
+ */
+export interface AllocationStrategy {
+    computeTarget(bank: LYCYieldingBank): TargetAllocation;
+}
+/**
+ * Default strategy: deploy 100% of idle base asset into USD*.
+ *
+ * This is the simplest possible allocation — all non-base value goes to
+ * a single Perena stablecoin. Replace with a multi-asset strategy when
+ * additional yield-bearing positions (e.g. USD*-J) are introduced.
+ */
+export declare class SimpleUsdStarStrategy implements AllocationStrategy {
+    computeTarget(_bank: LYCYieldingBank): TargetAllocation;
+}

package/dist/sdks/long-yield-carry/src/services/rebalance/yieldingBank/strategy.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SimpleUsdStarStrategy = void 0;
+const common_1 = require("common");
+const constants_1 = require("../../../constants");
+const USD_STAR = common_1.mints.get("USD*");
+/**
+ * Default strategy: deploy 100% of idle base asset into USD*.
+ *
+ * This is the simplest possible allocation — all non-base value goes to
+ * a single Perena stablecoin. Replace with a multi-asset strategy when
+ * additional yield-bearing positions (e.g. USD*-J) are introduced.
+ */
+class SimpleUsdStarStrategy {
+    computeTarget(_bank) {
+        return [
+            {
+                mint: USD_STAR.address,
+                weightBps: 10000,
+                slippageBps: 50,
+                allocationConfig: constants_1.usdStarAllocationConfig,
+            },
+        ];
+    }
+}
+exports.SimpleUsdStarStrategy = SimpleUsdStarStrategy;

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

@@ -0,0 +1,40 @@
+import type { Address } from "@solana/kit";
+import type { YieldingBankAllocationConfig, RebalanceSwapSpec } from "../../../client/types";
+/**
+ * A single allocation target: a mint and its desired weight in basis points.
+ * Weights across all targets in a {@link TargetAllocation} must sum to 10_000.
+ */
+export interface AllocationTarget {
+    mint: Address;
+    weightBps: number;
+    /** Slippage tolerance for swaps into/out of this asset (basis points). */
+    slippageBps: number;
+    /**
+     * Allocation config needed to register this asset on the yielding bank
+     * if it doesn't already have a holding slot. Required for first-time
+     * allocations; ignored when the bank already holds the asset.
+     */
+    allocationConfig: YieldingBankAllocationConfig;
+}
+/**
+ * The full target allocation for a yielding bank's non-base assets.
+ * Each entry describes one asset and its desired weight.
+ * Weights must sum to exactly 10_000 (100%).
+ */
+export type TargetAllocation = AllocationTarget[];
+/**
+ * The output of {@link RebalancePlanner.plan}: swaps to execute and any
+ * new asset holdings to create before the rebalance instruction fires.
+ */
+export interface YieldingBankRebalancePlan {
+    /** Swaps to execute (base → asset or asset → base). */
+    swaps: RebalanceSwapSpec[];
+    /**
+     * If a target allocation references a mint the bank has never held,
+     * the allocation must be registered first. This contains the config
+     * for that one-time setup. At most one new allocation per rebalance.
+     */
+    newAllocation?: {
+        config: YieldingBankAllocationConfig;
+    };
+}

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

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

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

@@ -0,0 +1,2 @@
+export { RedemptionService } from "./redemptionService";
+export type { FundRedemptionEpochResult, ProcessEpochResult, RedemptionFundingErrors, RedemptionFundingFailure, RedemptionServiceOptions, StructuredRedemptionLog, } from "./redemptionService";

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

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RedemptionService = void 0;
+var redemptionService_1 = require("./redemptionService");
+Object.defineProperty(exports, "RedemptionService", { enumerable: true, get: function () { return redemptionService_1.RedemptionService; } });

package/dist/sdks/long-yield-carry/src/services/redemption/redemptionService.d.ts

@@ -0,0 +1,139 @@
+import { type Address, type TransactionSigner } from "@solana/kit";
+import type { LongYieldCarryClient } from "../../client/client";
+import type { RedemptionEpochSnapshot } from "../../client/types";
+export interface RedemptionServiceOptions {
+    /** Swap slippage tolerance for DCP transactions, in bps. Defaults to 100. */
+    dcpSwapSlippageBps?: number;
+    /** Optional structured sink for warnings (funding CPI failures, partial funding). */
+    structuredLog?: (entry: StructuredRedemptionLog) => void;
+}
+/** Single LP-targeted funding failure captured during epoch funding. */
+export interface RedemptionFundingFailure {
+    lpIndex: number;
+    message: string;
+}
+/** Aggregated non-fatal failures while funding an epoch (DCP vs withdraw phases). */
+export interface RedemptionFundingErrors {
+    dcp: RedemptionFundingFailure[];
+    withdraw: RedemptionFundingFailure[];
+}
+export interface StructuredRedemptionLog {
+    level: "warn" | "info";
+    event: string;
+    data?: Record<string, unknown>;
+}
+export interface FundRedemptionEpochResult {
+    funded: boolean;
+    fundedCollateral: bigint;
+    grossCollateralClaim: bigint;
+    realizedUnwindLoss: bigint;
+    errors: RedemptionFundingErrors;
+}
+export interface ProcessEpochResult {
+    requestsProcessed: number;
+}
+type LogFn = (msg: string) => void;
+/**
+ * Orchestrates the redemption epoch lifecycle: detecting open epochs, waiting
+ * for their time window to elapse, funding (DCP + top-up), and processing
+ * individual async burn requests.
+ *
+ * Holds a reference to the LYC client and caches yielding-bank PDAs per token
+ * so repeated calls against the same token avoid redundant derivation.
+ */
+export declare class RedemptionService {
+    private readonly client;
+    private readonly yieldingBankCache;
+    private readonly dcpSwapSlippageBps;
+    private readonly lpService;
+    private readonly structuredLog?;
+    constructor(client: LongYieldCarryClient, opts?: RedemptionServiceOptions);
+    /** Delegates to `client.account.fetchAllRedemptionEpochs`. */
+    getAllEpochs(): Promise<RedemptionEpochSnapshot[]>;
+    /** Delegates to `client.account.fetchRedemptionEpoch`. */
+    getEpoch(epochPda: Address): Promise<RedemptionEpochSnapshot>;
+    /** Re-fetches an existing snapshot from on-chain state. */
+    refreshEpoch(epoch: RedemptionEpochSnapshot): Promise<RedemptionEpochSnapshot>;
+    /**
+     * Returns the number of milliseconds until the epoch's acceptance window
+     * closes. Zero or negative means the window has already elapsed.
+     */
+    epochWindowRemainingMs(epoch: RedemptionEpochSnapshot): number;
+    /**
+     * Sleeps until the epoch's 60-second acceptance window has elapsed. Returns
+     * immediately if the window is already closed.
+     */
+    waitForEpochWindow(epoch: RedemptionEpochSnapshot, log?: LogFn): Promise<void>;
+    /**
+     * Transitions an epoch from Open → Funding. Waits for the epoch window to
+     * close first so in-flight burns can still land.
+     */
+    closeEpoch(signer: TransactionSigner, epoch: RedemptionEpochSnapshot, log?: LogFn): Promise<void>;
+    /** Transitions an epoch from Funding → Processing. */
+    startProcessing(signer: TransactionSigner, epoch: RedemptionEpochSnapshot, log?: LogFn): Promise<void>;
+    /**
+     * Funds a redemption epoch. Withdraws from debt-free LPs first (no DCP
+     * needed), then — if a deficit remains — runs targeted DCP + withdraw on
+     * carry-loaded LPs, prioritizing non-optimal positions.
+     */
+    fundEpoch(signer: TransactionSigner, epoch: RedemptionEpochSnapshot, log?: LogFn): Promise<FundRedemptionEpochResult>;
+    /**
+     * Processes all remaining async burn requests in a redemption epoch in FIFO
+     * order.
+     */
+    processRequests(signer: TransactionSigner, epoch: RedemptionEpochSnapshot, log?: LogFn): Promise<ProcessEpochResult>;
+    /**
+     * Runs the complete epoch lifecycle: close → fund → transition to
+     * processing → process all requests.
+     *
+     * Returns true if the epoch was fully processed and closed.
+     */
+    processEpoch(signer: TransactionSigner, epoch: RedemptionEpochSnapshot, log?: LogFn): Promise<boolean>;
+    clearYieldingBankCache(): void;
+    /**
+     * Credits only the residual shortfall from collateral already sitting in the
+     * token PDA's unlent reserve. LP withdrawals run first so existing reserves
+     * are used as the tail of mixed LP/unlent funding, not the first source.
+     */
+    private creditResidualUnlent;
+    /** Phase 1: withdraw directly from LPs that have no debt (no DCP needed). */
+    private fundFromDebtFreeLps;
+    /**
+     * Phase 2: DCP + withdraw from carry-loaded LPs, sorted so non-optimal
+     * positions are unwound first.
+     */
+    private fundFromCarryLps;
+    /**
+     * Runs a targeted DCP on each LP that needs collateral freed. Iterates `lps`
+     * in the caller-provided order (non-optimal positions first).
+     */
+    private dcpAcrossLps;
+    /**
+     * Max collateral (native units) withdrawable from an LP without a prior DCP.
+     *
+     * TopUpUnlentReserves re-checks `is_utilization_rate_at_or_below_target`
+     * AFTER the withdrawal (util <= target + target * threshold / 10_000), and
+     * utilization scales as `util_after = util * collateral / (collateral - w)`
+     * when debt and prices stay constant (mirrors on-chain
+     * `simulate_utilization_rate_bps_after_collateral_withdraw`). Inverting
+     * against the upper bound gives:
+     *   w_max = collateral * (limit - util) / limit
+     */
+    private maxDirectWithdrawal;
+    /**
+     * Executes a single DCP on one lending position with retry logic. Uses full
+     * unwind (target utilization 0) when the deficit exceeds the LP's collateral,
+     * otherwise uses `collateralWithdrawal` steering.
+     */
+    private dcpSingleLp;
+    /**
+     * Withdraws collateral from lending positions into unlent reserves, crediting
+     * the redemption epoch. Stops as soon as the epoch is fully funded.
+     */
+    private withdrawFromLps;
+    private isFullyFunded;
+    private deficitUi;
+    private fundResult;
+    private resolveYieldingBanks;
+}
+export {};