@kestrelfi/lyc-sdk 1.0.1 → 1.0.3

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

@@ -1,181 +0,0 @@
-"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

@@ -1,26 +0,0 @@
-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

@@ -1,26 +0,0 @@
-"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

@@ -1,40 +0,0 @@
-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

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

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

@@ -1,2 +0,0 @@
-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

@@ -1,5 +0,0 @@
-"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

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