@kestrelfi/lyc-sdk 1.0.1

package/src/services/allocation/index.ts

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

package/src/services/allocation/types.ts

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

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

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

package/src/services/carry/lycLendingPositionManager.ts

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

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

package/src/services/lendingPosition/index.ts

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