@kestrelfi/lyc-sdk 1.0.1 → 1.0.3

package/src/services/allocation/index.ts

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

package/src/services/allocation/types.ts

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

package/src/services/carry/carryAllocationConfig.ts

@@ -1,266 +0,0 @@
-import {
-  ltvUtilDeltaBelowTargForRallyPct,
-  maxLtvUtilBeforeCollDrawdown,
-  ReservesManager,
-  type ReserveBase,
-} from "lending-platforms";
-import { mints } from "common";
-import type { Address } from "@solana/kit";
-import { resolvePresets, type VolatilityRegime } from "../../constants/configs/carryTradePresets";
-
-/** Maximum value for `targetUtilizationRateBps` (100% in basis points). */
-export const MAX_TARGET_UTILIZATION_RATE_BPS = 10_000;
-
-/**
- * Maximum allowed value of `targetUtilizationRateBps + maxDeviationAboveTargetUtilBps`.
- * Mirrors `MAX_LENDING_POSITION_UPPER_UTIL_BPS` in the on-chain program.
- */
-export const MAX_LENDING_POSITION_UPPER_UTIL_BPS = 10_500;
-
-/**
- * Floor for `maxDeviationAboveTargetUtilBps` in preset-based computation.
- *
- * When the raw target is high enough that the unwind-trigger gap would be
- * smaller than this, `computeCarryLendingAllocationConfig` pulls the target
- * down so the above-deviation is at least this wide. This prevents
- * near-zero unwind bands that would trigger constant rebalances.
- */
-export const MIN_DEVIATION_ABOVE_TARGET_UTIL_BPS = 200;
-
-/**
- * On-chain lending position tuning (see `LendingPositionConfig` in `long_yield_carry`).
- */
-export type CarryLendingAllocationConfig = {
-  targetUtilizationRateBps: number;
-  maxDeviationAboveTargetUtilBps: number;
-  maxDeviationBelowTargetUtilBps: number;
-};
-
-export type ComputeCarryLendingAllocationConfigParams = {
-  /**
-   * Collateral drawdown buffer between the **target** utilization and liquidation (positive percent,
-   * e.g. `25` for 25%). At target utilization, a collateral drop of this size reaches the liquidation
-   * line: `target = (1 − drawdownPctFromTargetToLiq/100) × liquidationThreshold / maxLtv`.
-   *
-   * Must be greater than `drawdownPctFromUnwindToLiq` (the target sits further from liquidation than
-   * the unwind trigger).
-   */
-  drawdownPctFromTargetToLiq: number;
-  /**
-   * Collateral drawdown buffer between the **unwind trigger** and liquidation (positive percent,
-   * e.g. `10` for 10%). At the unwind trigger (`target + maxDeviationAbove`), a collateral drop of
-   * this size reaches the liquidation line:
-   * `unwindTrigger = (1 − drawdownPctFromUnwindToLiq/100) × liquidationThreshold / maxLtv`.
-   *
-   * Must be less than `drawdownPctFromTargetToLiq`.
-   */
-  drawdownPctFromUnwindToLiq: number;
-  /**
-   * Max collateral **appreciation** (positive percent, e.g. `25` for +25%). If you start exactly at
-   * target utilization and collateral rallies this much (debt USD fixed), utilization reaches the
-   * **boost** trigger: `target − maxDeviationBelow`.
-   */
-  maxPriceChangeUpPercent: number;
-  /** Effective max LTV for the pair (decimal `0.8` = 80%), e.g. `ReservesManager.maxLtv`. */
-  maxLtv: number;
-  /** Collateral liquidation threshold (decimal `0.85` = 85%), from reserve config. */
-  liquidationThreshold: number;
-};
-
-/** The price-band params without pair-specific LTV / liquidation fields. */
-export type CarryPriceBandPreset = Omit<
-  ComputeCarryLendingAllocationConfigParams,
-  "maxLtv" | "liquidationThreshold"
->;
-
-/**
- * Clamps a lending position config so it satisfies the on-chain constraints in
- * `require_valid_lending_position_config_bps`:
- *
- * - `targetUtilizationRateBps` is clamped to `[1, MAX_TARGET_UTILIZATION_RATE_BPS]`
- * - `maxDeviationAboveTargetUtilBps` is clamped so `target + above ≤ MAX_LENDING_POSITION_UPPER_UTIL_BPS`
- *
- * Throws only for inputs that indicate a bug (non-integer, negative deviation, target ≤ maxDevBelow).
- */
-export function clampLendingPositionConfigBps(
-  config: CarryLendingAllocationConfig
-): CarryLendingAllocationConfig {
-  let { targetUtilizationRateBps, maxDeviationAboveTargetUtilBps, maxDeviationBelowTargetUtilBps } =
-    config;
-
-  if (!Number.isInteger(targetUtilizationRateBps) || targetUtilizationRateBps <= 0) {
-    throw new Error("targetUtilizationRateBps must be a positive integer");
-  }
-  for (const [name, v] of [
-    ["maxDeviationAboveTargetUtilBps", maxDeviationAboveTargetUtilBps],
-    ["maxDeviationBelowTargetUtilBps", maxDeviationBelowTargetUtilBps],
-  ] as const) {
-    if (!Number.isInteger(v) || v < 0) {
-      throw new Error(`${name} must be a non-negative integer`);
-    }
-  }
-
-  targetUtilizationRateBps = Math.min(targetUtilizationRateBps, MAX_TARGET_UTILIZATION_RATE_BPS);
-  maxDeviationAboveTargetUtilBps = Math.min(
-    maxDeviationAboveTargetUtilBps,
-    MAX_LENDING_POSITION_UPPER_UTIL_BPS - targetUtilizationRateBps
-  );
-
-  if (targetUtilizationRateBps <= maxDeviationBelowTargetUtilBps) {
-    throw new Error("targetUtilizationRateBps must be greater than maxDeviationBelowTargetUtilBps");
-  }
-
-  return {
-    targetUtilizationRateBps,
-    maxDeviationAboveTargetUtilBps,
-    maxDeviationBelowTargetUtilBps,
-  };
-}
-
-/**
- * Builds `targetUtilizationRateBps` and deviation bands from drawdown-to-liquidation buffers.
- *
- * **Model:** debt USD fixed; only collateral USD moves. Both the target and the unwind trigger are
- * defined by how much collateral drawdown separates them from the liquidation line
- * (`liquidationThreshold / maxLtv`). The boost trigger (below target) is set by a rally percentage.
- *
- * `maxDeviationAbove = unwindTriggerBps − targetBps` (derived, not from a price-change input).
- */
-export function computeCarryLendingAllocationConfig(
-  params: ComputeCarryLendingAllocationConfigParams
-): CarryLendingAllocationConfig {
-  const {
-    drawdownPctFromTargetToLiq,
-    drawdownPctFromUnwindToLiq,
-    maxPriceChangeUpPercent,
-    maxLtv,
-    liquidationThreshold,
-  } = params;
-
-  if (
-    !Number.isFinite(drawdownPctFromTargetToLiq) ||
-    drawdownPctFromTargetToLiq <= 0 ||
-    drawdownPctFromTargetToLiq >= 100
-  ) {
-    throw new RangeError("drawdownPctFromTargetToLiq must be in (0, 100)");
-  }
-  if (
-    !Number.isFinite(drawdownPctFromUnwindToLiq) ||
-    drawdownPctFromUnwindToLiq < 0 ||
-    drawdownPctFromUnwindToLiq >= 100
-  ) {
-    throw new RangeError("drawdownPctFromUnwindToLiq must be in [0, 100)");
-  }
-  if (drawdownPctFromUnwindToLiq >= drawdownPctFromTargetToLiq) {
-    throw new RangeError(
-      "drawdownPctFromUnwindToLiq must be less than drawdownPctFromTargetToLiq (unwind trigger is closer to liquidation than target)"
-    );
-  }
-  if (!Number.isFinite(maxPriceChangeUpPercent) || maxPriceChangeUpPercent <= 0) {
-    throw new RangeError("maxPriceChangeUpPercent must be finite and positive");
-  }
-
-  const targetDecimal = maxLtvUtilBeforeCollDrawdown({
-    drawdownPercent: drawdownPctFromTargetToLiq,
-    ltv: maxLtv,
-    liquidationThreshold,
-  });
-
-  let targetUtilizationRateBps = Math.min(
-    Math.floor(targetDecimal * 10_000),
-    MAX_TARGET_UTILIZATION_RATE_BPS
-  );
-  if (targetUtilizationRateBps <= 0) {
-    throw new RangeError(
-      "Computed target utilization rounds to zero; reduce drawdownPctFromTargetToLiq or check maxLtv / liquidationThreshold"
-    );
-  }
-
-  const unwindTriggerDecimal = maxLtvUtilBeforeCollDrawdown({
-    drawdownPercent: drawdownPctFromUnwindToLiq,
-    ltv: maxLtv,
-    liquidationThreshold,
-  });
-  const unwindTriggerBps = Math.floor(unwindTriggerDecimal * 10_000);
-  let maxDeviationAboveTargetUtilBps = Math.min(
-    unwindTriggerBps - targetUtilizationRateBps,
-    MAX_LENDING_POSITION_UPPER_UTIL_BPS - targetUtilizationRateBps
-  );
-
-  // If the above-deviation is below the minimum (e.g. because the target was
-  // clamped to MAX_TARGET_UTILIZATION_RATE_BPS), pull the target down so the
-  // unwind band is at least MIN_DEVIATION_ABOVE_TARGET_UTIL_BPS wide.
-  if (maxDeviationAboveTargetUtilBps < MIN_DEVIATION_ABOVE_TARGET_UTIL_BPS) {
-    maxDeviationAboveTargetUtilBps = MIN_DEVIATION_ABOVE_TARGET_UTIL_BPS;
-    targetUtilizationRateBps = Math.min(
-      targetUtilizationRateBps,
-      MAX_LENDING_POSITION_UPPER_UTIL_BPS - MIN_DEVIATION_ABOVE_TARGET_UTIL_BPS
-    );
-  }
-
-  const t = targetUtilizationRateBps / 10_000;
-  const maxBelowDecimal = ltvUtilDeltaBelowTargForRallyPct(t, maxPriceChangeUpPercent);
-  const maxDeviationBelowTargetUtilBps = Math.floor(maxBelowDecimal * 10_000);
-
-  return clampLendingPositionConfigBps({
-    targetUtilizationRateBps,
-    maxDeviationAboveTargetUtilBps,
-    maxDeviationBelowTargetUtilBps,
-  });
-}
-
-// =============================================================================
-// High-level preset resolution
-// =============================================================================
-
-export interface ComputeConfigForCollateralArgs {
-  /** Collateral mint address — used to look up the symbol from the mint registry. */
-  collateralMint: Address;
-  /** Collateral reserve — used to read `liquidationThresholdPct`. */
-  collateralReserve: ReserveBase;
-  /** Debt reserve — paired with collateral to determine `maxLtv` (including e-mode). */
-  debtReserve: ReserveBase;
-  /**
-   * Override the volatility regime. When omitted, uses the asset's
-   * `defaultRegime` from `ASSET_PRESETS`.
-   */
-  regime?: VolatilityRegime;
-}
-
-/**
- * Resolves the carry trade price-band preset for a collateral mint and
- * computes the lending position config (target utilization + deviation bands)
- * using the reserve pair's `maxLtv` and `liquidationThreshold`.
- *
- * Uses {@link ReservesManager} to derive `maxLtv` (including e-mode overrides)
- * and normalizes `liquidationThresholdPct` to a decimal.
- *
- * Throws if the collateral mint symbol is not in `ASSET_PRESETS`.
- */
-export function computeConfigForCollateral(
-  args: ComputeConfigForCollateralArgs
-): CarryLendingAllocationConfig {
-  const { collateralMint, collateralReserve, debtReserve } = args;
-
-  const mintInfo = mints.get(collateralMint);
-  const symbol = mintInfo?.symbol ?? String(collateralMint);
-  const entry = resolvePresets(symbol);
-  if (!entry) {
-    throw new Error(
-      `computeConfigForCollateral: no carry preset found for collateral "${symbol}" (${collateralMint})`
-    );
-  }
-
-  const regime = args.regime ?? entry.defaultRegime;
-  const preset = entry.presets[regime];
-
-  const rm = new ReservesManager(collateralReserve, debtReserve);
-  const pct = collateralReserve.config.liquidationThresholdPct;
-  const liquidationThreshold = pct <= 1 ? pct : pct / 100;
-
-  return computeCarryLendingAllocationConfig({
-    ...preset,
-    maxLtv: rm.maxLtv,
-    liquidationThreshold,
-  });
-}

package/src/services/carry/index.ts

@@ -1,2 +0,0 @@
-export * from "./carryAllocationConfig";
-export * from "./lycLendingPositionManager";

package/src/services/carry/lycLendingPositionManager.ts

@@ -1,167 +0,0 @@
-import { fromWeb3Pk, type Environment } from "common";
-import {
-  LendingPlatformData,
-  LendingPositionManager,
-  ReserveBase,
-  type CollateralPriceTriggerBand,
-  type LendingPositionInspectMetrics,
-} from "lending-platforms";
-import { TokenLendingPositionData } from "../../models/lycToken";
-import {
-  computeCarryLendingAllocationConfig,
-  type CarryLendingAllocationConfig,
-  type CarryPriceBandPreset,
-} from "./carryAllocationConfig";
-
-/**
- * LYC-flavoured {@link LendingPositionManager}: adds carry-specific sizing
- * signals ({@link shouldIncreaseCarryPosition}, {@link shouldDecreaseCarryPosition})
- * and defaults utilization targets from the on-chain `LendingPositionConfig`.
- */
-export class LycLendingPositionManager extends LendingPositionManager {
-  constructor(
-    lpData: LendingPlatformData,
-    readonly lendingPosition: TokenLendingPositionData,
-    collateralReserve: ReserveBase,
-    debtReserve: ReserveBase,
-    environment?: Environment
-  ) {
-    super(
-      lpData,
-      fromWeb3Pk(lendingPosition.pool),
-      fromWeb3Pk(lendingPosition.protocolUserAcc),
-      collateralReserve,
-      debtReserve,
-      environment
-    );
-  }
-
-  static async create(
-    lpData: LendingPlatformData,
-    lendingPosition: TokenLendingPositionData,
-    environment?: Environment
-  ): Promise<LycLendingPositionManager> {
-    const pool = fromWeb3Pk(lendingPosition.pool);
-    const [collateralReserve, debtReserve] = await Promise.all([
-      lpData.fetchReserve(pool, fromWeb3Pk(lendingPosition.collateralReserve)),
-      lpData.fetchReserve(pool, fromWeb3Pk(lendingPosition.debtReserve)),
-    ]);
-    if (!collateralReserve || !debtReserve) {
-      throw new Error("Failed to fetch reserves");
-    }
-    return new LycLendingPositionManager(
-      lpData,
-      lendingPosition,
-      collateralReserve,
-      debtReserve,
-      environment
-    );
-  }
-
-  /**
-   * Derives `targetUtilizationRateBps` and carry trigger deviations from drawdown-to-liquidation
-   * buffers and a rally percentage, using this pair's {@link ReservesManager.maxLtv} and the
-   * collateral reserve's **base** `liquidationThresholdPct` (normalized to a decimal).
-   *
-   * For custom `maxLtv` / `liquidationThreshold` (e.g. e-mode liquidation threshold), call
-   * {@link computeCarryLendingAllocationConfig} directly.
-   */
-  getLendingAllocationConfigFromPriceBands(
-    params: CarryPriceBandPreset
-  ): CarryLendingAllocationConfig {
-    const pct = this.reservesManager.supplyReserve.config.liquidationThresholdPct;
-    const liquidationThreshold = pct <= 1 ? pct : pct / 100;
-    return computeCarryLendingAllocationConfig({
-      ...params,
-      maxLtv: this.reservesManager.maxLtv,
-      liquidationThreshold,
-    });
-  }
-
-  /**
-   * Returns true when the current LTV utilization (valued at EMA prices) has
-   * fallen far enough below the target that the position should be boosted.
-   */
-  async shouldIncreaseCarryPosition(): Promise<boolean> {
-    const state = await this.getPositionState("ema");
-    if (!state) return false;
-
-    const { supplyUsd, debtUsd } = state;
-    if (supplyUsd <= 0) return false;
-
-    const currentUtilBps = this.reservesManager.calcLtvUtilizationRateBps(supplyUsd, debtUsd);
-    return (
-      currentUtilBps <=
-      this.lendingPosition.config.targetUtilizationRateBps -
-        this.lendingPosition.config.maxDeviationBelowTargetUtilBps
-    );
-  }
-
-  /**
-   * Returns true when the current LTV utilization (valued at realtime prices) has
-   * risen far enough above the target that the position should be unwound.
-   */
-  async shouldDecreaseCarryPosition(): Promise<boolean> {
-    const state = await this.getPositionState("realtime");
-    if (!state) return false;
-
-    const { supplyUsd, debtUsd } = state;
-    const currentUtilBps = this.reservesManager.calcLtvUtilizationRateBps(supplyUsd, debtUsd);
-    return (
-      currentUtilBps >=
-      this.lendingPosition.config.targetUtilizationRateBps +
-        this.lendingPosition.config.maxDeviationAboveTargetUtilBps
-    );
-  }
-
-  override async calcDebtChangeAmount(
-    targetUtilizationRateBps: number = this.lendingPosition.config.targetUtilizationRateBps
-  ): Promise<number> {
-    return super.calcDebtChangeAmount(targetUtilizationRateBps);
-  }
-
-  override async calcPreWithdrawalTargetUtilizationRateBps(
-    withdrawUiCollateralAmount: number,
-    postWithdrawalTargetUtilizationRateBps: number = this.lendingPosition.config
-      .targetUtilizationRateBps
-  ): Promise<number> {
-    return super.calcPreWithdrawalTargetUtilizationRateBps(
-      withdrawUiCollateralAmount,
-      postWithdrawalTargetUtilizationRateBps
-    );
-  }
-
-  override async calcDebtChangeAmountForCollateralWithdrawal(
-    withdrawUiCollateralAmount: number,
-    postWithdrawalTargetUtilizationRateBps: number = this.lendingPosition.config
-      .targetUtilizationRateBps
-  ): Promise<number> {
-    return super.calcDebtChangeAmountForCollateralWithdrawal(
-      withdrawUiCollateralAmount,
-      postWithdrawalTargetUtilizationRateBps
-    );
-  }
-
-  override async getCollateralPriceTriggerBand(): Promise<CollateralPriceTriggerBand> {
-    return super.getCollateralPriceTriggerBand(this.configTriggerBandBps());
-  }
-
-  override async getInspectMetrics(): Promise<LendingPositionInspectMetrics | null> {
-    return super.getInspectMetrics(this.configTriggerBandBps());
-  }
-
-  private configTriggerBandBps(): {
-    lowerTargetUtilizationRateBps: number;
-    upperTargetUtilizationRateBps: number;
-  } {
-    const {
-      targetUtilizationRateBps,
-      maxDeviationBelowTargetUtilBps,
-      maxDeviationAboveTargetUtilBps,
-    } = this.lendingPosition.config;
-    return {
-      lowerTargetUtilizationRateBps: targetUtilizationRateBps - maxDeviationBelowTargetUtilBps,
-      upperTargetUtilizationRateBps: targetUtilizationRateBps + maxDeviationAboveTargetUtilBps,
-    };
-  }
-}

package/src/services/index.ts

@@ -1,5 +0,0 @@
-export * from "./allocation";
-export * from "./carry";
-export * from "./lendingPosition";
-export * from "./rebalance";
-export * from "./redemption";

package/src/services/lendingPosition/index.ts

@@ -1,5 +0,0 @@
-export { LendingPositionService } from "./lendingPositionService";
-export type {
-  EnsureInitialKaminoLendingPositionOptions,
-  OptimalLendingPosition,
-} from "./lendingPositionService";