@kamino-finance/klend-sdk 5.12.8 → 5.13.0

package/src/classes/obligationOrder.ts

@@ -1,12 +1,13 @@
 /* eslint-disable max-classes-per-file */
 import { Fraction } from './fraction';
 import { ObligationOrder } from '../idl_codegen/types';
-import { getSingleElement, orThrow, roundNearest } from './utils';
+import { orThrow, roundNearest } from './utils';
 import Decimal from 'decimal.js';
 import BN from 'bn.js';
 import { KaminoObligation, Position } from './obligation';
 import { TokenAmount } from './types';
 import { ONE_HUNDRED_PCT_IN_BPS } from '../utils';
+import { getSingleElement } from '../utils/validations';
 
 // Polymorphic parts of an order:
 
@@ -16,7 +17,7 @@ import { ONE_HUNDRED_PCT_IN_BPS } from '../utils';
  * When a {@link KaminoObligationOrder.condition} is met by an obligation, the corresponding
  * {@link KaminoObligationOrder.opportunity} becomes available to liquidators.
  */
-interface OrderCondition {
+export interface OrderCondition {
   /**
    * An abstract parameter of the condition, meaningful in context of the condition's type.
    */
@@ -50,7 +51,7 @@ export interface OrderOpportunity {
  * A condition met when obligation's overall "User LTV" is strictly higher than the given threshold.
  */
 export class UserLtvAbove implements OrderCondition {
-  private readonly minUserLtvExclusive: Decimal;
+  readonly minUserLtvExclusive: Decimal;
 
   constructor(minUserLtvExclusive: Decimal.Value) {
     this.minUserLtvExclusive = new Decimal(minUserLtvExclusive);
@@ -72,7 +73,7 @@ export class UserLtvAbove implements OrderCondition {
  * A condition met when obligation's overall "User LTV" is strictly lower than the given threshold.
  */
 export class UserLtvBelow implements OrderCondition {
-  private readonly maxUserLtvExclusive: Decimal;
+  readonly maxUserLtvExclusive: Decimal;
 
   constructor(maxUserLtvExclusive: Decimal.Value) {
     this.maxUserLtvExclusive = new Decimal(maxUserLtvExclusive);
@@ -97,7 +98,7 @@ export class UserLtvBelow implements OrderCondition {
  * May only be applied to single-collateral, single-debt obligations.
  */
 export class DebtCollPriceRatioAbove implements OrderCondition {
-  private readonly minDebtCollPriceRatioExclusive: Decimal;
+  readonly minDebtCollPriceRatioExclusive: Decimal;
 
   constructor(minDebtCollPriceRatioExclusive: Decimal.Value) {
     this.minDebtCollPriceRatioExclusive = new Decimal(minDebtCollPriceRatioExclusive);
@@ -114,8 +115,10 @@ export class DebtCollPriceRatioAbove implements OrderCondition {
       this.minDebtCollPriceRatioExclusive,
       // For single-debt-single-coll obligations, the price ratio is directly proportional
       // to LTV - so we can calculate the "liquidation price ratio" simply by scaling the
-      // current value by the ratio of unhealthy/current LTV:
-      priceRatio.mul(obligation.refreshedStats.liquidationLtv).div(obligation.refreshedStats.loanToValue)
+      // current value by the ratio of unhealthy/current borrow value:
+      priceRatio
+        .mul(obligation.refreshedStats.borrowLiquidationLimit)
+        .div(obligation.refreshedStats.userTotalBorrowBorrowFactorAdjusted)
     );
   }
 }
@@ -127,7 +130,7 @@ export class DebtCollPriceRatioAbove implements OrderCondition {
  * May only be applied to single-collateral, single-debt obligations.
  */
 export class DebtCollPriceRatioBelow implements OrderCondition {
-  private readonly maxDebtCollPriceRatioExclusive: Decimal;
+  readonly maxDebtCollPriceRatioExclusive: Decimal;
 
   constructor(maxDebtCollPriceRatioExclusive: Decimal.Value) {
     this.maxDebtCollPriceRatioExclusive = new Decimal(maxDebtCollPriceRatioExclusive);
@@ -150,7 +153,7 @@ export class DebtCollPriceRatioBelow implements OrderCondition {
  * May only be applied to single-debt obligations.
  */
 export class DeleverageDebtAmount implements OrderOpportunity {
-  private readonly amount: Decimal;
+  readonly amount: Decimal;
 
   constructor(amount: Decimal.Value) {
     this.amount = new Decimal(amount);
@@ -161,7 +164,7 @@ export class DeleverageDebtAmount implements OrderOpportunity {
   }
 
   getMaxRepay(borrows: Array<Position>): TokenAmount {
-    const singleBorrow = getSingleElement(borrows, 'Opportunity type requires a single borrow');
+    const singleBorrow = getSingleElement(borrows, 'borrow');
     return {
       mint: singleBorrow.mintAddress,
       amount: Decimal.min(singleBorrow.amount, this.amount),
@@ -372,6 +375,15 @@ export class KaminoObligationOrder {
     });
   }
 
+  /**
+   * Binds this order to the given slot.
+   *
+   * This is just a convenience method for easier interaction with {@link KaminoAction#buildSetObligationOrderIxn()}.
+   */
+  atIndex(index: number): ObligationOrderAtIndex {
+    return new ObligationOrderAtIndex(index, this);
+  }
+
   /**
    * Calculates the given order's actual execution bonus rate.
    *
@@ -389,18 +401,43 @@ export class KaminoObligationOrder {
       this.minExecutionBonusRate,
       this.maxExecutionBonusRate
     );
-    // Note: instead of the existing `obligation.noBfLoanToValue()`, here we use a formula consistent with the
-    // `obligation.refreshedStats.loanToValue` (that we use in other parts of obligation orders' SDK logic):
-    const userNoBfLtv = obligation.refreshedStats.userTotalBorrow.div(
-      obligation.refreshedStats.userTotalCollateralDeposit
-    );
     // In order to ensure that LTV improves on order execution, we apply the same heuristic formula as for the regular
-    // liquidations:
-    const diffToBadDebt = new Decimal(1).sub(userNoBfLtv);
+    // liquidations. Please note that we deliberately use the `obligation.noBfLoanToValue()`, which is consistent with
+    // the smart contract's calculation:
+    const diffToBadDebt = new Decimal(1).sub(obligation.noBfLoanToValue());
     return Decimal.min(interpolatedBonusRate, diffToBadDebt);
   }
 }
 
+/**
+ * A single slot within {@link Obligation.orders} (which may contain an order or not).
+ *
+ * This is used as an argument to {@link KaminoAction.buildSetObligationOrderIxn()} to easily set or cancel an order.
+ */
+export class ObligationOrderAtIndex {
+  index: number;
+  order: KaminoObligationOrder | null;
+
+  constructor(index: number, order: KaminoObligationOrder | null) {
+    this.index = index;
+    this.order = order;
+  }
+
+  /**
+   * Creates an empty slot representation (suitable for cancelling an order).
+   */
+  static empty(index: number): ObligationOrderAtIndex {
+    return new ObligationOrderAtIndex(index, null);
+  }
+
+  /**
+   * Returns the on-chain state of the order (potentially a zeroed account data, if the order is not set).
+   */
+  orderState(): ObligationOrder {
+    return this.order !== null ? this.order.toState() : KaminoObligationOrder.NULL_STATE;
+  }
+}
+
 /**
  * Numeric details on why an order's condition was met.
  */
@@ -449,7 +486,7 @@ export type AvailableOrderExecution = {
 // Internal calculation functions:
 
 function tokenAmountToValue(tokenAmount: TokenAmount, position: Position): Decimal {
-  if (tokenAmount.mint !== position.mintAddress) {
+  if (!tokenAmount.mint.equals(position.mintAddress)) {
     throw new Error(`Value of token amount ${tokenAmount} cannot be computed using data from ${position}`);
   }
   return tokenAmount.amount.mul(position.marketValueRefreshed).div(position.amount);
@@ -496,8 +533,8 @@ function evaluateTakeProfit(currentValue: Decimal, conditionThreshold: Decimal):
 }
 
 function calculateDebtCollPriceRatio(obligation: KaminoObligation): Decimal {
-  const singleBorrow = getSingleElement(obligation.getBorrows(), 'Condition type requires a single borrow');
-  const singleDeposit = getSingleElement(obligation.getDeposits(), 'Condition type requires a single deposit');
+  const singleBorrow = getSingleElement(obligation.getBorrows(), 'borrow');
+  const singleDeposit = getSingleElement(obligation.getDeposits(), 'deposit');
   return calculateTokenPrice(singleBorrow).div(calculateTokenPrice(singleDeposit));
 }
 

package/src/classes/utils.ts

@@ -336,13 +336,6 @@ export function orThrow(message: string): never {
   throw new Error(message);
 }
 
-export function getSingleElement<T>(array: T[], message: string): T {
-  if (array.length !== 1) {
-    throw new Error(`${message} (found ${array.length})`);
-  }
-  return array[0];
-}
-
 /**
  * Returns an integer {@link Decimal} nearest to the given one.
  *

package/src/lib.ts

@@ -14,3 +14,4 @@ export * from './utils';
 export * from './leverage';
 export * from './referrals';
 export * from './lending_operations';
+export * from './obligation_orders';

package/src/obligation_orders/common.ts

@@ -0,0 +1,70 @@
+import { KaminoMarket, KaminoObligation } from '../classes';
+import Decimal from 'decimal.js';
+
+/**
+ * A basic context needed to interpret orders.
+ */
+export type OrderContext = {
+  kaminoMarket: KaminoMarket;
+  kaminoObligation: KaminoObligation;
+};
+
+/**
+ * A type of order for obligations that follow the "one optional stop-loss and one optional take-profit" convention.
+ */
+export enum OrderType {
+  StopLoss = 'StopLoss',
+  TakeProfit = 'TakeProfit',
+}
+
+/**
+ * A discriminator enum for {@link OrderAction};
+ */
+export enum OrderActionType {
+  FullRepay = 'FullRepay',
+  PartialRepay = 'PartialRepay',
+}
+
+/**
+ * One of possible actions to take on a price-based order.
+ */
+export type OrderAction = FullRepay | PartialRepay;
+
+/**
+ * An action repaying entire obligation debt.
+ */
+export type FullRepay = {
+  type: OrderActionType.FullRepay;
+};
+
+/**
+ * An action repaying the given amount of the debt.
+ */
+export type PartialRepay = {
+  type: OrderActionType.PartialRepay;
+  repayDebtAmountLamports: Decimal;
+};
+
+/**
+ * A high-level specification of an order.
+ * The trigger type `T` depends on the order's flavour (e.g. price-based or LTV-based).
+ */
+export type OrderSpecification<T> = {
+  /**
+   * The condition that makes the {@link action} available to be executed.
+   */
+  trigger: T;
+
+  /**
+   * The action that may be executed.
+   */
+  action: OrderAction;
+
+  /**
+   * The minimum and maximum bonus for an executor of the action, in bps.
+   *
+   * The minimum is paid when the order condition is "barely met", and then the bonus grows towards maximum as the
+   * condition gets exceeded more and more.
+   */
+  executionBonusBpsRange: [number, number];
+};

package/src/obligation_orders/index.ts

@@ -0,0 +1,3 @@
+export * from './price_based';
+export * from './ltv_based';
+export * from './common';

package/src/obligation_orders/internal.ts

@@ -0,0 +1,92 @@
+import Decimal from 'decimal.js';
+import {
+  DeleverageAllDebt,
+  DeleverageDebtAmount,
+  KaminoObligationOrder,
+  OrderCondition,
+  OrderOpportunity,
+} from '../classes/obligationOrder';
+import { checkThat, getSingleElement } from '../utils/validations';
+import { ONE_HUNDRED_PCT_IN_BPS } from '../utils';
+import { OrderAction, OrderActionType, OrderContext, OrderSpecification, OrderType } from './common';
+
+// These methods are exported, buy only used internally within the obligation orders utils:
+
+export function toOrderIndex(orderType: OrderType): number {
+  switch (orderType) {
+    case OrderType.StopLoss:
+      return 0;
+    case OrderType.TakeProfit:
+      return 1;
+  }
+}
+
+export function createConditionBasedOrder<C>(
+  context: OrderContext,
+  condition: OrderCondition,
+  specification: OrderSpecification<C>
+): KaminoObligationOrder {
+  checkThat(condition.evaluate(context.kaminoObligation) === null, `cannot create an immediately-triggered order`);
+  const opportunity = toOrderOpportunity(context, specification.action);
+  const [minExecutionBonusRate, maxExecutionBonusRate] = toExecutionBonusRates(specification.executionBonusBpsRange);
+  return new KaminoObligationOrder(condition, opportunity, minExecutionBonusRate, maxExecutionBonusRate);
+}
+
+export function readTriggerBasedOrder<T>(kaminoOrder: KaminoObligationOrder, trigger: T): OrderSpecification<T> {
+  return {
+    trigger,
+    action: toAction(kaminoOrder.opportunity),
+    executionBonusBpsRange: toExecutionBonusBps(kaminoOrder.minExecutionBonusRate, kaminoOrder.maxExecutionBonusRate),
+  };
+}
+
+// Only internals below:
+
+function toOrderOpportunity(context: OrderContext, action: OrderAction): OrderOpportunity {
+  switch (action.type) {
+    case OrderActionType.FullRepay:
+      return new DeleverageAllDebt();
+    case OrderActionType.PartialRepay:
+      const { repayDebtAmountLamports } = action;
+      checkThat(repayDebtAmountLamports.gt(0), `repay amount must be positive; got ${repayDebtAmountLamports}`);
+      const availableDebtAmountLamports = getSingleElement(context.kaminoObligation.getBorrows(), 'borrow').amount;
+      checkThat(
+        repayDebtAmountLamports.lte(availableDebtAmountLamports),
+        `partial repay amount ${repayDebtAmountLamports} cannot exceed the borrowed amount ${availableDebtAmountLamports}`
+      );
+      return new DeleverageDebtAmount(action.repayDebtAmountLamports);
+  }
+}
+
+function toExecutionBonusRates(executionBonusBpsRange: [number, number]): [Decimal, Decimal] {
+  const [minExecutionBonusRate, maxExecutionBonusRate] = executionBonusBpsRange.map((bps) =>
+    new Decimal(bps).div(ONE_HUNDRED_PCT_IN_BPS)
+  );
+  checkThat(minExecutionBonusRate.gte(0), `execution bonus rate cannot be negative: ${minExecutionBonusRate}`);
+  checkThat(
+    maxExecutionBonusRate.gte(minExecutionBonusRate),
+    `max execution bonus rate ${maxExecutionBonusRate} cannot be lower than min ${minExecutionBonusRate}`
+  );
+  return [minExecutionBonusRate, maxExecutionBonusRate];
+}
+
+function toAction(opportunity: OrderOpportunity): OrderAction {
+  if (opportunity instanceof DeleverageAllDebt) {
+    return {
+      type: OrderActionType.FullRepay,
+    };
+  }
+  if (opportunity instanceof DeleverageDebtAmount) {
+    return {
+      type: OrderActionType.PartialRepay,
+      repayDebtAmountLamports: opportunity.amount,
+    };
+  }
+  throw new Error(`incompatible on-chain opportunity ${opportunity.constructor.name}`);
+}
+
+function toExecutionBonusBps(minExecutionBonusRate: Decimal, maxExecutionBonusRate: Decimal): [number, number] {
+  return [minExecutionBonusRate, maxExecutionBonusRate].map((rate) =>
+    new Decimal(rate).mul(ONE_HUNDRED_PCT_IN_BPS).toNumber()
+  ) as [number, number];
+}

package/src/obligation_orders/ltv_based.ts

@@ -0,0 +1,143 @@
+import Decimal from 'decimal.js';
+import { ObligationOrderAtIndex, OrderCondition, UserLtvAbove, UserLtvBelow } from '../classes/obligationOrder';
+import { checkThat } from '../utils/validations';
+import { OrderContext, OrderSpecification, OrderType } from './common';
+import { createConditionBasedOrder, readTriggerBasedOrder, toOrderIndex } from './internal';
+
+/**
+ * Creates an LTV-based {@link ObligationOrderAtIndex} based on the given stop-loss or take-profit specification.
+ *
+ * The returned object can then be passed directly to {@link KaminoAction.buildSetObligationOrderIxn()} to build an
+ * instruction which replaces (or cancels, if the specification is `null`) the given obligation's stop-loss or
+ * take-profit order on-chain.
+ *
+ * The given obligation cannot use 0-LTV collaterals (see {@link checkObligationCompatible()} for rationale).
+ */
+export function createLtvBasedOrder(
+  context: OrderContext,
+  orderType: OrderType,
+  specification: LtvBasedOrderSpecification | null
+): ObligationOrderAtIndex {
+  checkObligationCompatible(context);
+  const index = toOrderIndex(orderType);
+  if (specification === null) {
+    return ObligationOrderAtIndex.empty(index);
+  }
+  const condition = toOrderCondition(orderType, specification.trigger);
+  checkThat(
+    condition.threshold().gte(MIN_LTV_THRESHOLD) && condition.threshold().lte(MAX_LTV_THRESHOLD),
+    `LTV-based trigger outside valid range [${MIN_LTV_THRESHOLD}%; ${MAX_LTV_THRESHOLD}%]: ${condition.threshold()}%`
+  );
+  return createConditionBasedOrder(context, condition, specification).atIndex(index);
+}
+
+/**
+ * Parses an {@link OrderSpecification} from the selected stop-loss or take-profit order of the given obligation.
+ *
+ * The given obligation cannot use 0-LTV collaterals (see {@link checkObligationCompatible()} for rationale).
+ *
+ * The selected order is expected to be of matching type (i.e. as if it was created using the
+ * {@link createLtvBasedOrder()}).
+ */
+export function readLtvBasedOrder(context: OrderContext, orderType: OrderType): LtvBasedOrderSpecification | null {
+  checkObligationCompatible(context);
+  const kaminoOrder = context.kaminoObligation.getOrders()[toOrderIndex(orderType)];
+  if (kaminoOrder === null) {
+    return null;
+  }
+  const trigger = toTrigger(kaminoOrder.condition, orderType);
+  return readTriggerBasedOrder(kaminoOrder, trigger);
+}
+
+/**
+ * A high-level specification of an LTV-based order.
+ */
+export type LtvBasedOrderSpecification = OrderSpecification<LtvBasedOrderTrigger>;
+
+/**
+ * A discriminator enum for {@link LtvBasedOrderTrigger};
+ */
+export enum LtvBasedOrderTriggerType {
+  StopLoss = 'StopLoss',
+  TakeProfit = 'TakeProfit',
+}
+
+/**
+ * One of possible triggers depending on the obligation's type and the price bracket's side.
+ */
+export type LtvBasedOrderTrigger = StopLoss | TakeProfit;
+
+/**
+ * A trigger for a stop-loss on LTV.
+ */
+export type StopLoss = {
+  type: LtvBasedOrderTriggerType.StopLoss;
+  whenLtvPctAbove: number;
+};
+
+/**
+ * A trigger for a take-profit on LTV.
+ */
+export type TakeProfit = {
+  type: LtvBasedOrderTriggerType.TakeProfit;
+  whenLtvPctBelow: number;
+};
+
+// Only internals below:
+
+const FULL_PCT = 100;
+const MIN_LTV_THRESHOLD = 0.01;
+const MAX_LTV_THRESHOLD = 0.99;
+
+function checkObligationCompatible({ kaminoMarket, kaminoObligation }: OrderContext) {
+  for (const depositReserveAddress of kaminoObligation.deposits.keys()) {
+    const depositReserve = kaminoMarket.getExistingReserveByAddress(depositReserveAddress);
+    // Note: the seemingly over-cautious requirement below ensures that the user-facing LTV calculation gives the same
+    // result as on the Klend SC side (they differ in the handling of 0-LTV collaterals; see
+    // `KaminoObligation.loanToValue()` doc for details). We may unify the 0-LTV handling some day and remove this.
+    checkThat(
+      depositReserve.state.config.loanToValuePct !== 0,
+      `LTV-based orders cannot be used with a 0-LTV collateral: ${depositReserve.symbol}`
+    );
+  }
+}
+
+function toOrderCondition(orderType: OrderType, trigger: LtvBasedOrderTrigger): OrderCondition {
+  switch (orderType) {
+    case OrderType.StopLoss:
+      if (trigger.type === LtvBasedOrderTriggerType.StopLoss) {
+        return new UserLtvAbove(new Decimal(trigger.whenLtvPctAbove).div(FULL_PCT));
+      }
+      break;
+    case OrderType.TakeProfit:
+      if (trigger.type === LtvBasedOrderTriggerType.TakeProfit) {
+        return new UserLtvBelow(new Decimal(trigger.whenLtvPctBelow).div(FULL_PCT));
+      }
+      break;
+  }
+  throw new Error(`an LTV-based ${orderType} order cannot use ${trigger.type} condition`);
+}
+
+function toTrigger(condition: OrderCondition, orderType: OrderType): LtvBasedOrderTrigger {
+  switch (orderType) {
+    case OrderType.StopLoss:
+      if (condition instanceof UserLtvAbove) {
+        return {
+          type: LtvBasedOrderTriggerType.StopLoss,
+          whenLtvPctAbove: condition.minUserLtvExclusive.mul(FULL_PCT).toNumber(),
+        };
+      }
+      break;
+    case OrderType.TakeProfit:
+      if (condition instanceof UserLtvBelow) {
+        return {
+          type: LtvBasedOrderTriggerType.TakeProfit,
+          whenLtvPctBelow: condition.maxUserLtvExclusive.mul(FULL_PCT).toNumber(),
+        };
+      }
+      break;
+  }
+  throw new Error(
+    `an LTV-based ${orderType} order has an incompatible on-chain condition ${condition.constructor.name}`
+  );
+}