@kestrelfi/lyc-sdk 1.0.1

package/src/client/types/builders.ts

@@ -0,0 +1,19 @@
+import type { Program } from "@anchor-lang/core";
+import type { Rpc, SolanaRpcApi } from "@solana/kit";
+import type { Environment, SwapClient } from "common";
+import type { LongYieldCarry } from "../../idl/long_yield_carry";
+import type { AccountClient } from "../account";
+import type { LongYieldCarryExternalLiquidityResolver } from "../externalLiquidityResolver";
+import type { LendingPlatformClientRegistry } from "../lendingPlatformClients";
+import type { PdaClient } from "../pda";
+
+export interface LongYieldCarryBuilderContext {
+  rpc: Rpc<SolanaRpcApi>;
+  environment: Environment;
+  program: Program<LongYieldCarry>;
+  account: AccountClient;
+  pda: PdaClient;
+  swap: SwapClient;
+  externalLiquidityResolver: LongYieldCarryExternalLiquidityResolver;
+  lendingPlatformClients: LendingPlatformClientRegistry;
+}

package/src/client/types/enums.ts

@@ -0,0 +1,47 @@
+// --- InterestDistribution ---
+
+export type AnchorInterestDistribution = { intoTokenPrice: {} } | { intoWallets: {} };
+
+export enum InterestDistribution {
+  IntoTokenPrice = 0,
+  IntoWallets = 1,
+}
+
+export function interestDistributionToEnum(v: AnchorInterestDistribution): InterestDistribution {
+  if ("intoTokenPrice" in v) return InterestDistribution.IntoTokenPrice;
+  if ("intoWallets" in v) return InterestDistribution.IntoWallets;
+  throw new Error("Unknown InterestDistribution variant");
+}
+
+export function enumToInterestDistribution(t: InterestDistribution): AnchorInterestDistribution {
+  switch (t) {
+    case InterestDistribution.IntoTokenPrice:
+      return { intoTokenPrice: {} };
+    case InterestDistribution.IntoWallets:
+      return { intoWallets: {} };
+  }
+}
+
+// --- LendingType ---
+
+export type AnchorLendingType = { lendingMarket: {} } | { vault: {} };
+
+export enum LendingType {
+  LendingMarket = 0,
+  Vault = 1,
+}
+
+export function lendingTypeToEnum(v: AnchorLendingType): LendingType {
+  if ("lendingMarket" in v) return LendingType.LendingMarket;
+  if ("vault" in v) return LendingType.Vault;
+  throw new Error("Unknown LendingType variant");
+}
+
+export function enumToLendingType(t: LendingType): AnchorLendingType {
+  switch (t) {
+    case LendingType.LendingMarket:
+      return { lendingMarket: {} };
+    case LendingType.Vault:
+      return { vault: {} };
+  }
+}

package/src/client/types/general.ts

@@ -0,0 +1,117 @@
+import { type BN } from "@anchor-lang/core";
+import { type Address } from "@solana/kit";
+import { type AnchorOracleType } from "common";
+import type { LYCToken } from "../../models/lycToken";
+
+// =============================================================================
+// Account snapshot types
+// =============================================================================
+
+/** Lightweight read-only snapshot of a `RedemptionEpoch` account. */
+export interface RedemptionEpochSnapshot {
+  pda: Address;
+  tokenPda: Address;
+  epochId: bigint;
+  /** SOL rent payer recorded when the epoch PDA was first funded (`Pubkey.default` on legacy accounts). */
+  payer: Address;
+  status: number;
+  requestCount: number;
+  processedRequestCount: number;
+  grossCollateralClaim: bigint;
+  realizedUnwindLoss: bigint;
+  fundedCollateral: bigint;
+}
+
+// =============================================================================
+// Shared param types
+// =============================================================================
+
+export interface OracleConfigDetails {
+  /** Oracle account address */
+  oracle: Address;
+  /** Oracle type */
+  oracleType: AnchorOracleType;
+  /** Optional secondary oracle account for composite oracle types (e.g. the
+   * SPL stake pool account for `PythSplStake`). Omit for single-account types. */
+  secondaryOracle?: Address;
+}
+
+/**
+ * Accounts required to reference a priced SPL mint: the mint itself, the
+ * SPL token program that governs it, and the oracle that prices it.
+ */
+export interface PricedMint {
+  mint: Address;
+  tokenProgram: Address;
+  oracle: Address;
+}
+
+export interface FeeConfig {
+  /** Management fee in basis points */
+  performanceFeeBps: number;
+  /** Minting fee in basis points */
+  mintingFeeBps: number;
+  /** Burning fee in basis points */
+  burningFeeBps: number;
+  /** Percentage of mint/burn fees that go to the protocol (in bps) */
+  protocolMintBurnPctBps: number;
+  /** Percentage of mint/burn fees that go to the curator (in bps) */
+  curatorMintBurnPctBps: number;
+  /** Curator's share of performance fees (in bps); protocol implicitly gets the rest. */
+  curatorPerfPctBps: number;
+  /**
+   * Cap (in bps) on the annualized token-price growth contributed by the fee
+   * drip. `0` disables the cap (release limited only by the linear rate).
+   * Omit to default to 200 bps on test/prod or `0` on local.
+   */
+  feeDripMaxApyBps?: number;
+  /**
+   * Duration (in seconds) over which absorbed mint/burn fees release into the
+   * price. `0` parks fees until recollateralization consumes them.
+   * Omit to default to three days on test/prod or parked-buffer mode on local.
+   */
+  feeDripDurationSecs?: BN;
+}
+
+// =============================================================================
+// Computed result types
+// =============================================================================
+
+/** Base-unit breakdown of the accounting effects of a mint. */
+export interface MintAmounts {
+  tokensToUser: bigint;
+  protocolFee: bigint;
+  curatorFee: bigint;
+}
+
+/** Base-unit breakdown of the accounting effects of a burn. */
+export interface BurnAmounts {
+  collateralToUser: bigint;
+  protocolFee: bigint;
+  curatorFee: bigint;
+  supplyReduction: bigint;
+}
+
+/**
+ * A single LYC yToken position held by a wallet.
+ *
+ * Returned by `AccountClient.fetchUserHoldings`. `token` is the full
+ * {@link LYCToken} model so callers can access price, label, decimals, and all
+ * on-chain accounting without a second fetch.
+ */
+export interface UserHolding {
+  /** The LYC Token domain object (price, label, decimals, TVL, etc.). */
+  token: LYCToken;
+  /** User's ATA address for this yToken mint. */
+  tokenAccount: Address;
+  /** Raw balance in the yToken's smallest unit. */
+  balance: bigint;
+  /** Decimal-adjusted balance (e.g. `1.5` for 1.5 yTokens). */
+  uiBalance: number;
+  /**
+   * Wallet USD notional when the caller supplies a collateral USD price
+   * (`uiBalance × token.price × priceMap[collateralMint]`). Omitted if no
+   * usable collateral price was available.
+   */
+  valueUsd?: number;
+}

package/src/client/types/index.ts

@@ -0,0 +1,6 @@
+export * from "./builders";
+export * from "./enums";
+export * from "./general";
+export * from "./ix";
+export * from "./planTypes/index";
+export * from "./tx";

package/src/client/types/ix.ts

@@ -0,0 +1,452 @@
+import { type BN } from "@anchor-lang/core";
+import { type Address } from "@solana/kit";
+import { type AnchorInterestDistribution, type AnchorLendingType } from "./enums";
+import { type OracleConfigDetails, type FeeConfig, type PricedMint } from "./general";
+import {
+  type AnchorTokenProgram,
+  type AnchorLendingPlatform,
+  type AnchorOracleType,
+  type InstructionRefs,
+  type CustomAccountMeta,
+  AnchorExternalLiquidityType,
+} from "common";
+
+// =============================================================================
+// create_cpi_plan
+// =============================================================================
+
+export interface CreateCpiPlanParams {
+  /** Unique ID used in PDA derivation. For rebalance_token this is the Token PDA. */
+  uniqueId: Address;
+  /** Unix timestamp seconds used in PDA derivation. */
+  createdTs: BN;
+  /** Up to 10 instruction refs packed into the zero-copy CPI plan account. */
+  refs: InstructionRefs[];
+}
+
+// =============================================================================
+// create_yielding_bank
+// =============================================================================
+
+export interface CreateYieldingBankParams {
+  /** Unique ID for this yielding bank (u8), used in PDA derivation */
+  id: number;
+  /** Oracle configuration for pricing the base asset */
+  oracleConfig: OracleConfigDetails;
+  /** The mint used as the default source when redeeming from the bank */
+  defaultRedemptionMint: Address;
+}
+
+// =============================================================================
+// update_yielding_bank_config
+// =============================================================================
+
+export interface UpdateYieldingBankConfigParams {
+  /** New default redemption mint (passed as a named account, not a param) */
+  defaultRedemptionMint: Address;
+}
+
+// =============================================================================
+// update_token_configuration
+// =============================================================================
+
+export interface UpdateTokenConfigurationParams {
+  performanceFeeBps: number;
+  mintingFeeBps: number;
+  burningFeeBps: number;
+  protocolMintBurnPctBps: number;
+  curatorMintBurnPctBps: number;
+  curatorPerfPctBps: number;
+  /**
+   * Cap (bps) on annualized price growth from the fee drip; `0` disables.
+   * Omit to preserve the token's current on-chain value.
+   */
+  feeDripMaxApyBps?: number;
+  /**
+   * Seconds over which absorbed mint/burn fees release into the price.
+   * `0` parks fees until recollateralization consumes them.
+   * Omit to preserve the token's current on-chain value.
+   */
+  feeDripDurationSecs?: BN;
+  burnRateLimit?: {
+    maxAmount: BN;
+    windowDurationSecs: BN;
+  };
+  /**
+   * When set, updates the deposit cap in raw collateral base units. Omit to leave unchanged.
+   * Pass `new BN(0)` to disable the cap (same semantics as `mint_token`).
+   */
+  depositLimit?: BN;
+}
+
+// =============================================================================
+// create_token
+// =============================================================================
+
+export interface CreateTokenParams {
+  /** Unique ID for this token (u8), used in PDA derivation */
+  id: number;
+  /** How interest is distributed */
+  interestDistribution: AnchorInterestDistribution;
+  /** Oracle configuration for pricing the collateral asset */
+  oracleConfig: OracleConfigDetails;
+  /** Fee configuration */
+  feeConfig: FeeConfig;
+}
+
+// =============================================================================
+// rebalance_yielding_bank
+// =============================================================================
+
+/** Configuration for the collateral or debt side of an external position */
+export interface AssetAllocationConfig {
+  mint: Address;
+  decimals: number;
+  tokenProgram: AnchorTokenProgram;
+}
+
+/**
+ * Configuration for adding a new asset holding.
+ *
+ * `mint` resolves the `allocation_mint` account — it is not serialized as an
+ * instruction param. Decimals and token program are read from the mint
+ * account on-chain.
+ */
+export interface AssetConfig {
+  mint: Address;
+  oracle: Address;
+  oracleType: AnchorOracleType;
+  externalLiquidityType: AnchorExternalLiquidityType;
+}
+
+/** Configuration for adding a new external yielding position */
+export interface ExternalPositionConfig {
+  lendingPlatform: AnchorLendingPlatform;
+  lendingType: AnchorLendingType;
+  pool: Address;
+  collateralReserve: Address;
+  debtReserve: Address;
+  protocolUserAcc: Address;
+  collateral: AssetAllocationConfig;
+  debt: AssetAllocationConfig;
+}
+
+/**
+ * Registers one new holding or external position before a rebalance.
+ * At most one of `assetHolding` or `externalPosition` may be set per call.
+ */
+export interface YieldingBankAllocationConfig {
+  assetHolding?: AssetConfig;
+  externalPosition?: ExternalPositionConfig;
+}
+
+export interface RebalanceYieldingBankParams {
+  /**
+   * Pre-built instruction refs containing deduplicated CPI account indices,
+   * CPI type registry indices, and packed args.
+   *
+   * Build with `createCpiRefs(cpis, { initialAccounts: oracleAccounts })` so
+   * that oracle and CPI accounts are deduplicated into a single pool and the
+   * indices in `ixRefs` already account for the oracle account positions.
+   */
+  ixRefs: InstructionRefs;
+  /**
+   * The fully deduplicated remaining-accounts pool for this instruction —
+   * oracle accounts at the front followed by any CPI-only accounts.
+   *
+   * This is the `accounts` array returned by `createCpiRefs` when called with
+   * `initialAccounts: oracleAccounts`.
+   */
+  remainingAccounts: CustomAccountMeta[];
+}
+
+// =============================================================================
+// create_token_lending_position
+// =============================================================================
+
+/**
+ * Parameters for `createTokenLendingPosition`. Account-backed values (protocol
+ * user account, collateral reserve, debt oracle) are passed as accounts via
+ * `CreateTokenLendingPositionIxArgs.lpPosition`, not duplicated here.
+ */
+export interface CreateTokenLendingPositionParams {
+  lendingPlatform: AnchorLendingPlatform;
+  pool: Address;
+  debtReserve: Address;
+  targetUtilizationRateBps: number;
+  maxDeviationAboveTargetUtilBps: number;
+  maxDeviationBelowTargetUtilBps: number;
+  debtMint: Address;
+  debtDecimals: number;
+  debtTokenProgram: AnchorTokenProgram;
+  debtOracleType: AnchorOracleType;
+  /**
+   * Optional setup CPIs (e.g. Kamino init_user_metadata, init_obligation,
+   * refresh_reserve, refresh_obligation) signed by the Token PDA and executed
+   * before the final refresh. When provided, the on-chain refresh reads the
+   * freshly-initialized protocol user account; otherwise the refresh is a
+   * no-op over an empty account.
+   */
+  tokenCpis?: InstructionRefs;
+  /** Fully deduplicated remaining-accounts pool for `tokenCpis`. */
+  remainingAccounts?: CustomAccountMeta[];
+}
+
+/**
+ * Accounts that describe and back a new lending position. Their pubkeys are
+ * stored on the position; their on-chain state is read by the final refresh.
+ */
+export interface CreateTokenLendingPositionAccounts {
+  /** The program's user/authority account on the lending protocol. */
+  protocolUserAcc: Address;
+  /** The lending protocol's reserve/bank for the collateral asset. */
+  collateralReserve: Address;
+  /** Oracle for the debt asset's price. */
+  debtOracle: Address;
+}
+
+// =============================================================================
+// update_lending_position_config
+// =============================================================================
+
+export interface UpdateLendingPositionConfigParams {
+  lendingPositionIndex: number;
+  targetUtilizationRateBps: number;
+  maxDeviationAboveTargetUtilBps: number;
+  maxDeviationBelowTargetUtilBps: number;
+}
+
+// =============================================================================
+// deposit_unlent_collateral
+// =============================================================================
+
+export interface DepositUnlentCollateralParams {
+  /** Pre-built deposit CPI refs (must contain exactly one Deposit CPI). */
+  ixRefs: InstructionRefs;
+  /** Index into the token's lending_positions array for the target position. */
+  lendingPositionIndex: number;
+  /** Fully deduplicated remaining-accounts pool for the deposit CPI. */
+  remainingAccounts: CustomAccountMeta[];
+}
+
+// =============================================================================
+// increase_carry_position
+// =============================================================================
+
+export interface IncreaseCarryPositionParams {
+  /** Optional prerequisite CPIs executed before any lending-position refresh. */
+  prerequisiteCpis?: InstructionRefs;
+  /** Pre-built borrow CPI refs (must contain exactly one Borrow CPI). */
+  ixRefs: InstructionRefs;
+  /** Index into the token's lending_positions array for the position to borrow against. */
+  lendingPositionIndex: number;
+  /**
+   * The fully deduplicated remaining-accounts pool for the borrow CPI.
+   * Carry-trade accounts (token, yieldingBank, tokenLpDebtTa, yieldingBankTa,
+   * lendingPositionUserAccount, lendingPositionCollateralReserve, debtOracle,
+   * debtTokenProgram) are prepended automatically.
+   */
+  remainingAccounts: CustomAccountMeta[];
+}
+
+// =============================================================================
+// claim_incentives
+// =============================================================================
+
+export interface ClaimIncentivesParams {
+  /** Optional prerequisite CPIs (reserve / obligation refresh) executed before the claim CPI. */
+  prerequisiteCpis?: InstructionRefs;
+  /** Pre-built Kamino claim-incentive CPI refs. */
+  tokenIxRefs: InstructionRefs;
+  /** Index into the token's lending_positions array. */
+  lendingPositionIndex: number;
+  /** Incentive reward mint expected to be claimed. */
+  expectedIncentiveMint: Address;
+  /** Token program for the incentive mint. */
+  incentiveTokenProgram: Address;
+  /** Oracle type for `incentiveOracle`. Required on debt and collateral branches. */
+  incentiveOracleType: AnchorOracleType;
+  /**
+   * Yielding bank that receives the claimed rewards and mints carry shares.
+   * Required on the debt branch; null otherwise.
+   */
+  yieldingBank: Address | null;
+  /**
+   * Oracle pricing `expectedIncentiveMint`. Required on the debt and
+   * collateral branches; null on the fee branch.
+   */
+  incentiveOracle: Address | null;
+  /**
+   * Optional curator fee wallet override. When null/omitted, builders resolve
+   * `token.roles.curator_fee_wallet()` and still pass the fee wallet accounts.
+   */
+  feeWallet?: Address | null;
+  /** Fully deduplicated remaining-accounts pool for the claim CPI. */
+  remainingAccounts: CustomAccountMeta[];
+}
+
+// =============================================================================
+// rebalance_token
+// =============================================================================
+
+export interface TokenLpPositionAccountOverrides {
+  /** Override for the lending position protocol user account. */
+  userAccount?: Address;
+  /** Override for the lending position collateral reserve. */
+  collateralReserve?: Address;
+  /** Override for the lending position debt oracle. */
+  debtOracle?: Address;
+}
+
+export interface RebalanceTokenParams {
+  /** Index into the token's lending_positions array for the position to rebalance in place. */
+  lpIndex: number;
+  /** Oracle type for the destination debt mint. Used to update the stored oracle_type after swapping debt in place. */
+  destinationDebtOracleType: AnchorOracleType;
+  /**
+   * Flash-loan fee in source-debt base units. The on-chain handler derives
+   * the total flash-repay amount from this plus the source-debt ATA balance
+   * observed at handler entry (= what Kamino actually flash-borrowed),
+   * caps it at 5 bps of the principal as a sanity check, and uses it as
+   * the post-swap balance threshold + dust-sweep cutoff + SPL Approve
+   * delegation amount.
+   */
+  flashFeeAmount: BN;
+  /**
+   * Source LP repay amount in the flash-borrowed mint's base units. The on-chain
+   * handler injects this into the repay CPI loaded from the CPI plan.
+   */
+  repayAmount: BN;
+  /** CPI plan PDA holding refs in order: repay, borrow, swap. */
+  cpiPlan: Address;
+  /**
+   * Fully deduplicated remaining-accounts pool. The first 7 slots must hold
+   * the rebalance-token initial accounts (see `buildRebalanceTokenInitialAccounts`),
+   * followed by any CPI accounts referenced by the CPI plan's refs.
+   */
+  remainingAccounts: CustomAccountMeta[];
+}
+
+// =============================================================================
+// decrease_carry_position
+// =============================================================================
+
+export interface DecreaseCarryPositionParams {
+  /** Optional prerequisite CPIs executed before any lending-position refresh. */
+  prerequisiteCpis?: InstructionRefs;
+  /**
+   * Optional manager-only target utilization override used for the post-repay
+   * utilization check.
+   */
+  targetUtilizationRateBps?: number;
+  /**
+   * Optional CPI refs for yielding-bank operations (withdraw from external
+   * positions, swap yield-bearing asset into debt token). Omit this when the
+   * yielding bank already holds the debt tokens.
+   */
+  ybIxRefs?: InstructionRefs;
+  /** Pre-built repay CPI refs (must contain exactly one Repay CPI). */
+  tokenIxRefs: InstructionRefs;
+  /** Index into the token's lending_positions array for the position to repay. */
+  lendingPositionIndex: number;
+  /**
+   * Amount of debt tokens to repay. When omitted, `ybIxRefs` must be provided
+   * and the amount is derived from the yielding bank TA balance change.
+   * `AMOUNT_ALL_SENTINEL` repays the maximum available amount, capped by
+   * current debt. When set with `ybIxRefs`, the on-chain instruction only swaps
+   * if the yielding bank is short and caps non-manager swap over-output.
+   */
+  repayAmount?: BN;
+  /**
+   * Index of the asset holding used as the swap source (0 = base_asset,
+   * 1–12 = assets[0–11]). Required when `ybIxRefs` is provided.
+   * Non-manager signers may only specify a holding whose mint matches the
+   * bank's `default_redemption_mint`.
+   */
+  sourceAssetHoldingIndex?: number;
+  /** Optional redemption epoch that absorbs DCP unwind loss for async burns. */
+  redemptionEpoch?: Address;
+  /**
+   * The fully deduplicated remaining-accounts pool for the CPIs.
+   * Carry-trade accounts (token, yieldingBank, tokenLpDebtTa, yieldingBankTa,
+   * lendingPositionUserAccount, lendingPositionCollateralReserve, debtOracle,
+   * debtTokenProgram) are prepended automatically.
+   */
+  remainingAccounts: CustomAccountMeta[];
+}
+
+// =============================================================================
+// burn_token
+// =============================================================================
+
+/**
+ * Low-level params for `ix.burnToken`. Pre-built refs and accounts must be
+ * assembled by the caller (typically `tx.getBurnTokenTx`).
+ */
+export interface BurnTokenIxParams {
+  burnAmount: BN | number;
+  asyncFallback?: {
+    epochId: BN | number;
+    requestSequence: BN | number;
+    redemptionEpoch?: Address;
+    request?: Address;
+  };
+}
+
+export interface SetRedemptionEpochStatusParams {
+  status: number;
+}
+
+export interface TopUpUnlentReservesParams {
+  prerequisiteCpis: InstructionRefs;
+  ixRefs: InstructionRefs;
+  lendingPositionIndex: number;
+  remainingAccounts: CustomAccountMeta[];
+  redemptionEpoch?: Address;
+}
+
+// =============================================================================
+// update_token_metadata
+// =============================================================================
+
+export interface UpdateTokenMetadataParams {
+  /** Pre-built Metaplex UpdateMetadataAccountV2 CPI refs (exactly one CPI). */
+  ixRefs: InstructionRefs;
+  /** Fully deduplicated remaining-accounts pool for the metadata CPI. */
+  remainingAccounts: CustomAccountMeta[];
+}
+
+// =============================================================================
+// recollateralize_loss
+// =============================================================================
+
+export interface RecollateralizeLossParams {
+  /** Optional prerequisite CPIs executed before any lending-position refresh. */
+  prerequisiteCpis?: InstructionRefs;
+  /**
+   * CPI refs for the Withdraw -> Swap -> Repay sequence (exactly 1 of each,
+   * in that order). All three CPIs share one deduplicated account pool.
+   */
+  ixRefs: InstructionRefs;
+  /** Index into the token's lending_positions array. */
+  lendingPositionIndex: number;
+  /** Fully deduplicated remaining-accounts pool for the withdraw/swap/repay CPIs. */
+  remainingAccounts: CustomAccountMeta[];
+  /** Yielding bank to deposit any excess debt tokens after repay. Required for execution; may be omitted when testing pre-condition failures. */
+  yieldingBank?: Address;
+  /** Optional explicit overrides for LP refresh accounts. */
+  lpPosition?: TokenLpPositionAccountOverrides;
+}
+
+// =============================================================================
+// collect_interest
+// =============================================================================
+
+export interface CollectInterestParams {
+  /** Default redemption asset being sold in the swap. */
+  redemption: PricedMint;
+  /** Pre-built swap CPI refs (yielding bank assets -> collateral). */
+  refs: InstructionRefs;
+  /** Fully deduplicated remaining-accounts pool for the swap CPIs. */
+  remainingAccounts: CustomAccountMeta[];
+}