@kestrelfi/lyc-sdk 1.0.1

package/src/models/index.ts

@@ -0,0 +1,9 @@
+export { LYCToken } from "./lycToken";
+export type {
+  TokenAccountData,
+  TokenCarryPositionData,
+  TokenLendingPositionData,
+  IndexedCarryPosition,
+  IndexedLendingPosition,
+} from "./lycToken";
+export { LYCYieldingBank } from "./yieldingBank";

package/src/models/lycToken.ts

@@ -0,0 +1,380 @@
+import { address, type Address } from "@solana/kit";
+import { BN, IdlAccounts } from "@anchor-lang/core";
+import { PublicKey } from "@solana/web3.js";
+import { LongYieldCarry } from "../idl/long_yield_carry";
+import {
+  applyBps,
+  fromWeb3Pk,
+  LendingPlatform,
+  lendingPlatformToEnum,
+  mints,
+  toBigInt,
+  toUiAmount,
+  TVL_USD_DECIMAL_PLACES,
+} from "common";
+import type { PdaClient } from "../client/pda";
+import { podBoolToNumber } from "../utils/general";
+import { collectableNetYieldUsd, splitFeeProportionally } from "../utils/tokenFeeMath";
+import type { BurnAmounts, MintAmounts } from "../client/types/general";
+
+const MAX_COLLECTABLE_SURPLUS_BPS = BigInt(1);
+const BASIS_POINTS = BigInt(10_000);
+
+/** Decoded on-chain data for a Token account, derived from the IDL. */
+export type TokenAccountData = IdlAccounts<LongYieldCarry>["token"];
+
+export type TokenLendingPositionData = TokenAccountData["lendingPositions"][number];
+
+export type TokenCarryPositionData = TokenAccountData["debtCarry"][number];
+
+/** A carry position paired with its index in the `debtCarry` array. */
+export interface IndexedCarryPosition {
+  index: number;
+  data: TokenCarryPositionData;
+}
+
+/** A lending position paired with its index in the `lendingPositions` array. */
+export interface IndexedLendingPosition {
+  index: number;
+  data: TokenLendingPositionData;
+}
+
+/**
+ * Wrapper around the raw Token account data from the program.
+ *
+ * Provides typed access to on-chain state and a home for
+ * derived/computed helpers as the SDK grows.
+ */
+export class LYCToken {
+  constructor(
+    /** The Token PDA address this data was fetched from */
+    readonly address: Address,
+    /** Deserialized account data */
+    readonly data: TokenAccountData
+  ) {}
+
+  get circuitBreaker(): number {
+    return podBoolToNumber(this.data.config.circuitBreaker);
+  }
+
+  /** Whether the token is operational (circuit breaker is off). */
+  get isActive(): boolean {
+    return this.circuitBreaker === 0;
+  }
+
+  /**
+   * Returns carry positions that have a non-default yielding base mint and
+   * positive shares — i.e. positions with actual yield exposure. Includes the
+   * original array index so callers can reference `debtCarry[index]` on-chain.
+   */
+  get activeCarryPositions(): IndexedCarryPosition[] {
+    return this.data.debtCarry
+      .map((carry, index) => ({ index, data: carry }))
+      .filter(
+        ({ data }) =>
+          !data.yieldingBaseMint.equals(PublicKey.default) && toBigInt(data.shares) > BigInt(0)
+      );
+  }
+
+  /**
+   * Returns lending positions that have a non-None platform — i.e. positions
+   * with an active lending protocol. Includes the original array index so
+   * callers can reference `lendingPositions[index]` on-chain.
+   */
+  get activeLendingPositions(): IndexedLendingPosition[] {
+    return this.data.lendingPositions
+      .map((lp, index) => ({ index, data: lp }))
+      .filter(({ data }) => lendingPlatformToEnum(data.platform) !== LendingPlatform.None);
+  }
+
+  /**
+   * Subset of {@link activeLendingPositions} that currently has supplied
+   * collateral on-chain. Filters out slots whose platform is set but whose
+   * collateral has been fully withdrawn — those slots can still report
+   * non-zero protocol-level state via a shared obligation, which makes them
+   * unsafe targets for borrow/withdraw flows.
+   */
+  get usedLendingPositions(): IndexedLendingPosition[] {
+    return this.activeLendingPositions.filter(
+      ({ data }) => toBigInt(data.accounting.collateral) > BigInt(0)
+    );
+  }
+
+  get config(): TokenAccountData["config"] {
+    return this.data.config;
+  }
+
+  get collateral(): TokenAccountData["collateral"] {
+    return this.data.collateral;
+  }
+
+  get fees(): TokenAccountData["fees"] {
+    return this.data.fees;
+  }
+
+  get accounting(): TokenAccountData["accounting"] {
+    return this.data.accounting;
+  }
+
+  get id(): number {
+    return this.data.config.id;
+  }
+
+  get mint(): Address {
+    return address(this.data.config.mint.toString());
+  }
+
+  get collateralMint(): Address {
+    return address(this.data.collateral.mint.toString());
+  }
+
+  get label(): string {
+    const symbol = mints.get(this.collateralMint)?.symbol;
+    return (symbol ? symbol : this.address).toLowerCase();
+  }
+
+  get decimals(): number {
+    return this.data.config.decimals;
+  }
+
+  /**
+   * On-chain token price: **collateral per yToken** in UI units (same decimals as
+   * the yToken), not USD. At genesis this is 1:1 with the collateral asset; it
+   * moves with NAV. For USD notional use `tvlUsd` / `totalSupply`, or
+   * `client.account.fetchUserHoldings` (pro-rata TVL).
+   */
+  get price(): number {
+    return toUiAmount(this.data.accounting.price, this.decimals);
+  }
+
+  get totalSupply(): number {
+    return toUiAmount(this.data.accounting.totalSupply, this.decimals);
+  }
+
+  /**
+   * Total protocol TVL in USD (on-chain `accounting.tvlUsd` is 8-decimal
+   * fixed-point USD, $1 = 10^8).
+   */
+  get tvlUsd(): number {
+    return toUiAmount(this.data.accounting.tvlUsd, TVL_USD_DECIMAL_PLACES);
+  }
+
+  get depositLimitUi(): number {
+    return toUiAmount(this.data.config.depositLimit, this.data.collateral.decimals);
+  }
+
+  /**
+   * Sum of active `debtCarry[*].tvlUsd` (8-decimal normalized USD stored on-chain).
+   * Mirrors the on-chain `Token::total_carry_tvl_usd` helper.
+   */
+  get totalCarryTvlUsd(): bigint {
+    return this.activeCarryPositions.reduce(
+      (sum, { data }) => sum + toBigInt(data.tvlUsd),
+      BigInt(0)
+    );
+  }
+
+  /**
+   * Sum of active `lendingPositions[*].accounting.debt.tvlUsd` (8-decimal normalized USD).
+   * Mirrors the on-chain `Token::total_lp_debt_usd` helper.
+   */
+  get totalLendingDebtTvlUsd(): bigint {
+    return this.activeLendingPositions.reduce(
+      (sum, { data }) => sum + toBigInt(data.accounting.debt.tvlUsd),
+      BigInt(0)
+    );
+  }
+
+  /**
+   * Collectable net yield (8-dec USD): any carry surplus above debt. Zero when
+   * carry TVL does not exceed debt TVL.
+   */
+  get collectableNetYieldUsd(): bigint {
+    return collectableNetYieldUsd(this.totalCarryTvlUsd, this.totalLendingDebtTvlUsd);
+  }
+
+  /**
+   * True when the token is active and carry TVL exceeds debt by at most 1 bp.
+   */
+  hasInterestToCollect(): boolean {
+    const totalDebtUsd = this.totalLendingDebtTvlUsd;
+    const surplusUsd = collectableNetYieldUsd(this.totalCarryTvlUsd, totalDebtUsd);
+
+    if (!this.isActive || totalDebtUsd === BigInt(0) || surplusUsd === BigInt(0)) {
+      return false;
+    }
+
+    // A carry surplus above 1 bp of debt cannot plausibly accrue between hourly
+    // collection cycles at supported yields, so treat it as stablecoin pricing
+    // drift instead of realizable interest. Cross-multiplication preserves
+    // sub-bp precision without truncating an integer bps calculation.
+    return surplusUsd * BASIS_POINTS <= totalDebtUsd * MAX_COLLECTABLE_SURPLUS_BPS;
+  }
+
+  /**
+   * Finds an active lending position whose debt mint matches `debtMint`.
+   *
+   * Returns the 0-based position index, or `-1` if no active position matches.
+   */
+  findLendingPositionByDebtMint(debtMint: Address): number {
+    for (let i = 0; i < this.data.lendingPositions.length; i++) {
+      const position = this.data.lendingPositions[i];
+      if (lendingPlatformToEnum(position.platform) === LendingPlatform.None) continue;
+      if (fromWeb3Pk(position.accounting.debt.mint) === debtMint) return i;
+    }
+    return -1;
+  }
+
+  /**
+   * Mirror the on-chain `Token::compute_mint_amounts` formula.
+   *
+   * The holder price-fee (the residual after protocol/curator take their split)
+   * is a gift to the pre-mint supply `S`. To stop the minter clawing back their
+   * own gift, all minted tokens are sized at the post-gift price — i.e. scaled by
+   * `S / (S + priceFee)`. The fee is not applied to the price on-chain at mint
+   * time; it is buffered and released gradually by `refreshTokenState`, so this
+   * quote returns the same base-unit amounts the program mints.
+   *
+   * When `totalSupply === 0` the price-fee has no beneficiary, so the whole fee
+   * is split between protocol and curator and the user is priced at the current
+   * price.
+   */
+  computeMintAmounts(depositAmount: BN | number): MintAmounts {
+    const deposit = BigInt(depositAmount.toString());
+    const feeBps = BigInt(this.data.fees.mintingFeeBps);
+    const protocolPctBps = BigInt(this.data.fees.protocolMintBurnPctBps);
+    const curatorPctBps = BigInt(this.data.fees.curatorMintBurnPctBps);
+    const price = BigInt(this.data.accounting.price.toString());
+    const scale = BigInt(Math.pow(10, this.data.config.decimals));
+    const totalSupply = BigInt(this.data.accounting.totalSupply.toString());
+
+    const tokensBeforeFees = (deposit * scale) / price;
+    const totalFee = applyBps(tokensBeforeFees, feeBps);
+
+    // Genesis: no holders to receive the price-fee → split the whole fee and
+    // price the user at the current price (no post-gift scaling).
+    if (totalSupply === 0n) {
+      const [protocolFee, curatorFee] = splitFeeProportionally(
+        totalFee,
+        protocolPctBps,
+        curatorPctBps
+      );
+      return { tokensToUser: tokensBeforeFees - totalFee, protocolFee, curatorFee };
+    }
+
+    const baseProtocolFee = applyBps(totalFee, protocolPctBps);
+    const baseCuratorFee = applyBps(totalFee, curatorPctBps);
+    const priceFee = totalFee - baseProtocolFee - baseCuratorFee;
+
+    // Post-gift sizing: scale every minted amount by S / (S + priceFee).
+    const denom = totalSupply + priceFee;
+    const tokensToUser = ((tokensBeforeFees - totalFee) * totalSupply) / denom;
+    const protocolFee = (baseProtocolFee * totalSupply) / denom;
+    const curatorFee = (baseCuratorFee * totalSupply) / denom;
+
+    return { tokensToUser, protocolFee, curatorFee };
+  }
+
+  /**
+   * Mirror the on-chain `Token::compute_burn_amounts` formula.
+   *
+   * Returns exact base-unit values for the three accounting effects of a burn:
+   *   - `collateralToUser`: collateral returned to the burner
+   *   - `protocolFee`: yTokens accrued as pending protocol fees
+   *   - `supplyReduction`: net decrease in total supply
+   *
+   * The holder price-fee (residual after protocol/curator take their split) is
+   * not paid out as collateral; on-chain it is buffered and dripped into the
+   * price for the remaining holders. The burner is leaving, so there is no
+   * self-dealing to guard against and no post-gift scaling is applied. When the
+   * burner is redeeming all circulating supply (no remaining holders), the full
+   * fee is split between protocol and curator instead of benefiting no one.
+   */
+  computeBurnAmounts(burnAmount: BN | number): BurnAmounts {
+    const burn = BigInt(burnAmount.toString());
+    const feeBps = BigInt(this.data.fees.burningFeeBps);
+    const protocolPctBps = BigInt(this.data.fees.protocolMintBurnPctBps);
+    const curatorPctBps = BigInt(this.data.fees.curatorMintBurnPctBps);
+    const price = BigInt(this.data.accounting.price.toString());
+    const scale = BigInt(Math.pow(10, this.data.config.decimals));
+
+    const totalSupply = BigInt(this.data.accounting.totalSupply.toString());
+    const pendingProtocolFees = BigInt(this.data.accounting.pendingProtocolFees.toString());
+    const pendingCuratorFees = BigInt(this.data.accounting.pendingCuratorFees.toString());
+    const pendingFees = pendingProtocolFees + pendingCuratorFees;
+    const circulatingSupply = totalSupply > pendingFees ? totalSupply - pendingFees : BigInt(0);
+    const isLastHolder = burn >= circulatingSupply;
+
+    const totalFee = applyBps(burn, feeBps);
+    const baseProtocolFee = applyBps(totalFee, protocolPctBps);
+    const baseCuratorFee = applyBps(totalFee, curatorPctBps);
+    let protocolFee: bigint;
+    let curatorFee: bigint;
+    if (isLastHolder) {
+      [protocolFee, curatorFee] = splitFeeProportionally(totalFee, protocolPctBps, curatorPctBps);
+    } else {
+      // No cap: protocol/curator take their base split and the price-fee residual
+      // is buffered (dripped into the price) rather than redirected to them.
+      [protocolFee, curatorFee] = [baseProtocolFee, baseCuratorFee];
+    }
+    const tokensAfterFee = burn - totalFee;
+    const collateralToUser = (tokensAfterFee * price) / scale;
+    const supplyReduction = burn - protocolFee - curatorFee;
+
+    return { collateralToUser, protocolFee, curatorFee, supplyReduction };
+  }
+
+  /**
+   * Convenience wrapper around {@link computeBurnAmounts} that returns only
+   * the collateral owed to the user, converted to a UI amount
+   * (divided by 10^collateral.decimals).
+   */
+  computeBurnWithdrawUiAmount(burnAmount: BN | number): number {
+    const { collateralToUser } = this.computeBurnAmounts(burnAmount);
+    return toUiAmount(collateralToUser, this.data.collateral.decimals);
+  }
+
+  /**
+   * Derives the YieldingBank PDA for the `debtCarry` entry at `debtCarryIndex`.
+   *
+   * @param debtCarryIndex - Index into `data.debtCarry`
+   * @param pda - Program PDA client (`YIELDING_BANK` seeds match on-chain).
+   */
+  async deriveYieldingBankAddressForDebtCarryIndex(
+    debtCarryIndex: number,
+    pda: PdaClient
+  ): Promise<Address> {
+    const carry = this.data.debtCarry[debtCarryIndex];
+    if (!carry) {
+      throw new Error(
+        `Invalid debtCarryIndex ${debtCarryIndex} (token has ${this.data.debtCarry.length} debt carry entries)`
+      );
+    }
+    if (carry.yieldingBaseMint.equals(PublicKey.default)) {
+      throw new Error(
+        `debtCarry[${debtCarryIndex}] has no active yielding bank (zero yielding base mint)`
+      );
+    }
+    const [bankPda] = await pda.deriveYieldingBankPda(
+      fromWeb3Pk(carry.yieldingBaseMint),
+      carry.yieldingBankId
+    );
+    return bankPda;
+  }
+
+  /**
+   * Resolves the YieldingBank PDA for the token's first active `debtCarry`
+   * entry. Used as a default when callers haven't picked a specific bank.
+   */
+  async resolveFirstYieldingBankAddress(pda: PdaClient): Promise<Address> {
+    const firstActiveIdx = this.data.debtCarry.findIndex(
+      (entry) => !entry.yieldingBaseMint.equals(PublicKey.default)
+    );
+    if (firstActiveIdx < 0) {
+      throw new Error(
+        "Token has no active yielding banks — call `increase_carry_position` first or pick a bank explicitly"
+      );
+    }
+    return this.deriveYieldingBankAddressForDebtCarryIndex(firstActiveIdx, pda);
+  }
+}

package/src/models/yieldingBank.ts

@@ -0,0 +1,127 @@
+import { type Address } from "@solana/kit";
+import { PublicKey } from "@solana/web3.js";
+import { IdlAccounts } from "@anchor-lang/core";
+import { LongYieldCarry } from "../idl/long_yield_carry";
+import { fromWeb3Pk, toUiAmount } from "common";
+import { podBoolToNumber } from "../utils/general";
+import { TOKEN_STALENESS_THRESHOLD_SECS } from "../constants/general";
+
+/** Decoded on-chain data for a YieldingBank account, derived from the IDL. */
+export type YieldingBankAccountData = IdlAccounts<LongYieldCarry>["yieldingBank"];
+
+/**
+ * Wrapper around the raw YieldingBank account data from the program.
+ *
+ * Provides typed access to on-chain state and a home for
+ * derived/computed helpers as the SDK grows.
+ */
+export class LYCYieldingBank {
+  constructor(
+    /** The YieldingBank PDA address this data was fetched from */
+    readonly address: Address,
+    /** Deserialized account data */
+    readonly data: YieldingBankAccountData
+  ) {}
+
+  get circuitBreaker(): number {
+    return podBoolToNumber(this.data.config.circuitBreaker);
+  }
+
+  get isActive(): boolean {
+    return this.circuitBreaker === 0;
+  }
+
+  get config(): YieldingBankAccountData["config"] {
+    return this.data.config;
+  }
+
+  get accounting(): YieldingBankAccountData["accounting"] {
+    return this.data.accounting;
+  }
+
+  get baseMint(): Address {
+    return fromWeb3Pk(this.data.config.baseMint);
+  }
+
+  get defaultRedemptionMint(): Address {
+    return fromWeb3Pk(this.data.config.defaultRedemptionMint);
+  }
+
+  get id(): number {
+    return this.data.config.id;
+  }
+
+  get decimals(): number {
+    return this.data.config.decimals;
+  }
+
+  get timeCreatedTs(): bigint {
+    return BigInt(this.data.config.timeCreatedTs.toString());
+  }
+
+  get sharePrice(): number {
+    return toUiAmount(this.data.accounting.sharePrice, this.decimals);
+  }
+
+  get totalShares(): number {
+    return toUiAmount(this.data.accounting.totalShares, this.decimals);
+  }
+
+  /**
+   * `true` when the bank's cached `lastRefreshedTs` is older than the
+   * client-side staleness threshold and a `refresh_yielding_bank` ix should
+   * be prepended before any handler that calls `verify_price_is_fresh`.
+   */
+  get isStale(): boolean {
+    const lastRefreshed = this.data.accounting.lastRefreshedTs.toNumber();
+    const nowSecs = Math.floor(Date.now() / 1000);
+    return nowSecs - lastRefreshed > TOKEN_STALENESS_THRESHOLD_SECS;
+  }
+
+  get baseAsset(): YieldingBankAccountData["baseAsset"] {
+    return this.data.baseAsset;
+  }
+
+  get assets(): YieldingBankAccountData["assets"] {
+    return this.data.assets;
+  }
+
+  get externalYieldingPositions(): YieldingBankAccountData["externalYieldingPositions"] {
+    return this.data.externalYieldingPositions;
+  }
+
+  /**
+   * Find the asset holding entry for a given mint across the bank's
+   * base asset and additional assets. Returns null if not held.
+   */
+  findAssetHolding(mint: Address): YieldingBankAccountData["baseAsset"] | null {
+    if (this.baseMint === mint) {
+      return this.data.baseAsset;
+    }
+
+    for (const asset of this.data.assets) {
+      if (asset.mint.equals(PublicKey.default)) continue;
+      if (fromWeb3Pk(asset.mint) === mint) {
+        return asset;
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Returns the flat index for the asset holding matching the given mint
+   * (0 = base_asset, 1–12 = assets[0–11]), or null if not found.
+   */
+  findAssetHoldingIndex(mint: Address): number | null {
+    if (this.baseMint === mint) return 0;
+
+    for (let i = 0; i < this.data.assets.length; i++) {
+      const asset = this.data.assets[i];
+      if (asset.mint.equals(PublicKey.default)) continue;
+      if (fromWeb3Pk(asset.mint) === mint) return i + 1;
+    }
+
+    return null;
+  }
+}