@kamino-finance/klend-sdk 5.12.8 → 5.13.1

package/src/classes/fraction.ts

@@ -1,6 +1,7 @@
 import BN from 'bn.js';
 import Decimal from 'decimal.js';
 import { roundNearest } from './utils';
+import { BigFractionBytes } from '../lib';
 
 export class Fraction {
   static MAX_SIZE_F = 128;
@@ -72,3 +73,9 @@ export class Fraction {
 }
 
 export const ZERO_FRACTION = new Fraction(new BN(0));
+
+export function bfToDecimal(x: BigFractionBytes): Decimal {
+  const bsf = x.value;
+  const accSf = bsf.reduce((acc, curr, i) => acc.add(curr.shln(i * 64)), new BN(0));
+  return new Fraction(accSf).toDecimal();
+}

package/src/classes/manager.ts

@@ -629,10 +629,7 @@ export class KaminoManager {
     const switchboardV2 = await SwitchboardProgram.loadMainnet(this.getConnection());
 
     // Group reserves by market
-    const marketToReserve = new PubkeyHashMap<
-      PublicKey,
-      [PublicKey, Reserve, AccountInfo<Buffer>][]
-    >();
+    const marketToReserve = new PubkeyHashMap<PublicKey, [PublicKey, Reserve, AccountInfo<Buffer>][]>();
     for (const [reserveAddress, reserveState, buffer] of reservePairs) {
       const marketAddress = reserveState.lendingMarket;
       if (!marketToReserve.has(marketAddress)) {

package/src/classes/market.ts

@@ -36,6 +36,7 @@ import { parseTokenSymbol, parseZeroPaddedUtf8 } from './utils';
 import SwitchboardProgram from '@switchboard-xyz/sbv2-lite';
 import { ObligationZP } from '../idl_codegen/zero_padding';
 import { getProgramAccounts } from '../utils';
+import { checkDefined } from '../utils/validations';
 
 export interface ReserveRewardInfo {
   rewardsPerSecond: Decimal; // not lamport
@@ -175,13 +176,10 @@ export class KaminoMarket {
     if (elevationGroupId === 0) {
       return null;
     }
-    const elevationGroup = this.getMarketElevationGroupDescriptions().find(
-      (candidate) => candidate.elevationGroup === elevationGroupId
+    return checkDefined(
+      this.getMarketElevationGroupDescriptions().find((candidate) => candidate.elevationGroup === elevationGroupId),
+      `${description} elevation group ${elevationGroupId} not found`
     );
-    if (elevationGroup === undefined) {
-      throw new Error(`${description} elevation group ${elevationGroupId} not found in market ${this.getAddress()}`);
-    }
-    return elevationGroup;
   }
 
   getMinNetValueObligation(): Decimal {
@@ -420,6 +418,14 @@ export class KaminoMarket {
     return this.reserves.get(address);
   }
 
+  /**
+   * Returns this market's reserve of the given address, or throws an error (including the given description) if such
+   * reserve does not exist.
+   */
+  getExistingReserveByAddress(address: PublicKey, description: string = 'Requested'): KaminoReserve {
+    return checkDefined(this.getReserveByAddress(address), `${description} reserve ${address} not found`);
+  }
+
   getReserveByMint(address: PublicKey): KaminoReserve | undefined {
     for (const reserve of this.reserves.values()) {
       if (reserve.getLiquidityMint().equals(address)) {
@@ -434,11 +440,7 @@ export class KaminoMarket {
    * such reserve does not exist.
    */
   getExistingReserveByMint(address: PublicKey, description: string = 'Requested'): KaminoReserve {
-    const reserve = this.getReserveByMint(address);
-    if (!reserve) {
-      throw new Error(`${description} reserve with mint ${address} not found in market ${this.getAddress()}`);
-    }
-    return reserve;
+    return checkDefined(this.getReserveByMint(address), `${description} reserve with mint ${address} not found`);
   }
 
   getReserveBySymbol(symbol: string) {
@@ -450,6 +452,14 @@ export class KaminoMarket {
     return undefined;
   }
 
+  /**
+   * Returns this market's reserve of the given symbol, or throws an error (including the given description) if
+   * such reserve does not exist.
+   */
+  getExistingReserveBySymbol(symbol: string, description: string = 'Requested'): KaminoReserve {
+    return checkDefined(this.getReserveBySymbol(symbol), `${description} reserve with symbol ${symbol} not found`);
+  }
+
   getReserveMintBySymbol(symbol: string) {
     return this.getReserveBySymbol(symbol)?.getLiquidityMint();
   }

package/src/classes/obligation.ts

@@ -5,7 +5,7 @@ import { KaminoReserve } from './reserve';
 import { Obligation } from '../idl_codegen/accounts';
 import { ElevationGroupDescription, KaminoMarket } from './market';
 import BN from 'bn.js';
-import { Fraction } from './fraction';
+import { bfToDecimal, Fraction } from './fraction';
 import {
   ObligationCollateral,
   ObligationCollateralFields,
@@ -67,7 +67,7 @@ export type ObligationStats = {
    * The LTV at which the obligation becomes subject to liquidation, *suitable for UI display*.
    *
    * Technically, this is a ratio:
-   * - of a sum of all borrows' values multiplied by reserves' borrowFactor (i.e. `userTotalBorrowBorrowFactorAdjusted`)
+   * - of a sum of values of all deposits multiplied by reserves' liquidationLtv (i.e. `borrowLiquidationLimit`)
    * - to a sum of values of all deposits having reserve's liquidationLtv > 0 (i.e. `userTotalLiquidatableDeposit`)
    *
    * Please note that this is different from the smart contract's definition of liquidation LTV (which divides by a sum
@@ -271,7 +271,7 @@ export class KaminoObligation {
   }
 
   /**
-   * Returns obligation orders (including the null ones, i.e. non-active order slots).
+   * Returns obligation orders (including the null ones, i.e. non-active positions in the orders' array).
    */
   getOrders(): Array<KaminoObligationOrder | null> {
     return this.state.orders.map((order) => KaminoObligationOrder.fromState(order));
@@ -1475,12 +1475,7 @@ export class KaminoObligation {
    * @returns Cumulative borrow rate for the specified obligation liquidity/borrow asset
    */
   static getCumulativeBorrowRate(borrow: ObligationLiquidity): Decimal {
-    let accSf = new BN(0);
-    for (const value of borrow.cumulativeBorrowRateBsf.value.reverse()) {
-      accSf = accSf.add(value);
-      accSf.shrn(64);
-    }
-    return new Fraction(accSf).toDecimal();
+    return bfToDecimal(borrow.cumulativeBorrowRateBsf);
   }
 
   public static getRatesForObligation(

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/reserve.ts

@@ -39,8 +39,7 @@ import {
   positiveOrZero,
   sameLengthArrayEquals,
 } from './utils';
-import { Fraction } from './fraction';
-import BN from 'bn.js';
+import { bfToDecimal, Fraction } from './fraction';
 import { ActionType } from './action';
 import { BorrowCapsAndCounters, ElevationGroupDescription, KaminoMarket } from './market';
 import {
@@ -212,9 +211,7 @@ export class KaminoReserve {
    * @returns the stale cumulative borrow rate of the reserve from the last refresh
    */
   getCumulativeBorrowRate(): Decimal {
-    const cumulativeBorrowRateBsf = this.state.liquidity.cumulativeBorrowRateBsf.value;
-    const accSf = cumulativeBorrowRateBsf.reduce((prev, curr, i) => prev.add(curr.shln(i * 64)), new BN(0));
-    return new Fraction(accSf).toDecimal();
+    return bfToDecimal(this.state.liquidity.cumulativeBorrowRateBsf);
   }
 
   /**

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/classes/vault.ts

@@ -1616,6 +1616,9 @@ export class KaminoVaultClient {
       totalAllocation = totalAllocation.add(allocation.targetWeight);
     });
     const expectedHoldingsDistribution = new PubkeyHashMap<PublicKey, Decimal>();
+    allReserves.forEach((reserve) => {
+      expectedHoldingsDistribution.set(reserve, new Decimal(0));
+    });
 
     let totalLeftToInvest = holdings.totalAUMIncludingFees.sub(holdings.pendingFees);
     let currentAllocationSum = totalAllocation;

package/src/lending_operations/repay_with_collateral_operations.ts

@@ -346,7 +346,6 @@ async function buildRepayWithCollateralIxs(
       false,
       requestElevationGroup,
       undefined,
-      undefined,
       referrer
     );
   } else {
@@ -364,7 +363,6 @@ async function buildRepayWithCollateralIxs(
       false,
       requestElevationGroup,
       undefined,
-      undefined,
       referrer
     );
   }

package/src/lending_operations/swap_collateral_operations.ts

@@ -407,8 +407,7 @@ async function getDepositTargetCollIxns(
     0, // no extra compute budget
     false, // we do not need ATA ixns here (we construct and close them ourselves)
     removesElevationGroup, // we may need to (temporarily) remove the elevation group; the same or a different one will be set on withdraw, if requested
-    false, // we are dealing with an existing obligation, no need to create user metadata
-    false, // we do not need to create a lookup table, dealing with an existing obligation
+    { skipInitialization: true, skipLutCreation: true }, // we are dealing with an existing obligation, no need to create user metadata
     context.referrer,
     context.currentSlot,
     removesElevationGroup ? 0 : undefined // only applicable when removing the group
@@ -457,8 +456,7 @@ async function getWithdrawSourceCollIxns(
     0, // no extra compute budget
     false, // we do not need ATA ixns here (we construct and close them ourselves)
     requestedElevationGroup !== undefined, // the `elevationGroupIdToRequestAfterWithdraw()` has already decided on this
-    false, // we are dealing with an existing obligation, no need to create user metadata
-    false, // we do not need to create a lookup table, dealing with an existing obligation
+    { skipInitialization: true, skipLutCreation: true }, // we are dealing with an existing obligation, no need to create user metadata
     context.referrer,
     context.currentSlot,
     requestedElevationGroup,

package/src/leverage/operations.ts

@@ -552,8 +552,7 @@ async function buildDepositWithLeverageIxns(
     0,
     false,
     elevationGroupOverride === 0 ? false : true, // emode
-    false, // to be checked and created in a setup tx in the UI
-    false, // to be checked and created in a setup tx in the UI
+    { skipInitialization: true, skipLutCreation: true }, // to be checked and created in a setup tx in the UI
     referrer,
     currentSlot
   );
@@ -986,9 +985,8 @@ export async function buildWithdrawWithLeverageIxns(
     undefined,
     0,
     false,
-    false, // to be checked and created in a setup tx in the UI (won't be the case for withdraw anyway as this would be created in deposit)
-    false, // to be checked and created in a setup tx in the UI (won't be the case for withdraw anyway as this would be created in deposit)
-    isClosingPosition,
+    false,
+    { skipInitialization: true, skipLutCreation: true }, // to be checked and created in a setup tx in the UI (won't be the case for withdraw anyway as this would be created in deposit)
     referrer
   );
 
@@ -1547,8 +1545,7 @@ async function buildIncreaseLeverageIxns(
     0,
     false,
     false,
-    false, // to be checked and create in a setup tx in the UI (won't be the case for adjust anyway as this would be created in deposit)
-    false, // to be checked and create in a setup tx in the UI (won't be the case for adjust anyway as this would be created in deposit)
+    { skipInitialization: true, skipLutCreation: true },
     referrer,
     currentSlot
   );
@@ -1565,8 +1562,7 @@ async function buildIncreaseLeverageIxns(
     0,
     false,
     false,
-    false, // to be checked and create in a setup tx in the UI (won't be the case for adjust anyway as this would be created in deposit)
-    false, // to be checked and create in a setup tx in the UI (won't be the case for adjust anyway as this would be created in deposit)
+    { skipInitialization: true, skipLutCreation: true }, // to be checked and create in a setup tx in the UI (won't be the case for adjust anyway as this would be created in deposit)
     referrer,
     currentSlot
   );
@@ -1739,8 +1735,7 @@ async function buildDecreaseLeverageIxns(
     0,
     false,
     false,
-    false, // to be checked and create in a setup tx in the UI (won't be the case for adjust anyway as this would be created in deposit)
-    false, // to be checked and create in a setup tx in the UI (won't be the case for adjust anyway as this would be created in deposit)
+    { skipInitialization: true, skipLutCreation: true }, // to be checked and create in a setup tx in the UI (won't be the case for adjust anyway as this would be created in deposit)
     referrer
   );
 
@@ -1756,8 +1751,7 @@ async function buildDecreaseLeverageIxns(
     0,
     false,
     false,
-    false, // to be checked and create in a setup tx in the UI (won't be the case for adjust anyway as this would be created in deposit)
-    false, // to be checked and create in a setup tx in the UI (won't be the case for adjust anyway as this would be created in deposit)
+    { skipInitialization: true, skipLutCreation: true }, // to be checked and create in a setup tx in the UI (won't be the case for adjust anyway as this would be created in deposit)
     referrer,
     currentSlot
   );

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];
+}