@kestrelfi/lyc-sdk 1.0.1

package/src/client/types/planTypes/collectInterest.ts

@@ -0,0 +1,97 @@
+import type { BN } from "@anchor-lang/core";
+import type { Address } from "@solana/kit";
+import type { CpiData } from "common";
+import type { PricedMint } from "../general";
+import type { SingleCpiExecutionPlan } from "./common";
+
+/**
+ * Deterministic inputs for deriving a `collect_interest` plan.
+ */
+export interface CollectInterestPlanParams {
+  /** Yielding bank whose active carry position should be partially redeemed. */
+  yieldingBank: Address;
+  /**
+   * Minimum net yield (in USD) below which collection is skipped.
+   * Prevents wasteful swaps when accrued interest is negligible.
+   * Value is in human-readable USD (e.g. 0.5 = $0.50).
+   */
+  minYieldUsd?: number;
+}
+
+/**
+ * One yielding-bank holding that should be redeemed during interest collection.
+ */
+export interface CollectInterestHoldingPlan {
+  /** Mint held by the yielding bank allocation. */
+  mint: Address;
+  /** Amount to redeem in raw base units for this holding. */
+  amount: BN;
+  /** Whether this holding came from the bank's base-asset slot. */
+  isBaseAsset: boolean;
+}
+
+/**
+ * Deterministic `collect_interest` plan produced by `client.planner`.
+ *
+ * This captures protocol-derived values only: the active carry position,
+ * shares to burn, and the ordered bank holdings that should be redeemed.
+ * It intentionally does not encode swap venue or routing policy.
+ */
+export interface CollectInterestPlan {
+  /** Token PDA whose carry position is collecting accrued yield. */
+  token: Address;
+  /** Yielding bank the active carry position is allocated to. */
+  yieldingBank: Address;
+  /** Base mint configured on the yielding bank. */
+  baseMint: Address;
+  /** Default redemption asset that accrued interest is collected from. */
+  redemption: PricedMint;
+  /** Token collateral asset that collection must ultimately end in. */
+  collateral: PricedMint;
+  /** Index of the active `debtCarry` entry on the token account. */
+  carryIndex: number;
+  /** Number of carry-position shares the program should burn. */
+  sharesToBurn: BN;
+  /** USD value represented by the burned shares, in program-scale units. */
+  sharesBurnedValueUsd: BN;
+  /** Ordered yielding-bank holdings to redeem before final collateral settlement. */
+  holdingsToRedeem: CollectInterestHoldingPlan[];
+}
+
+/**
+ * Caller-controlled routing inputs for turning a deterministic collect-interest
+ * plan into concrete swap CPI data.
+ */
+export interface CollectInterestRouteBuilderParams {
+  /** Final output mint. Defaults to `plan.collateral.mint`. */
+  outputMint?: Address;
+  /** Slippage tolerance applied to all collect-interest swaps. Defaults to `100`. */
+  slippageBps?: number;
+}
+
+/**
+ * Manual CPI inputs for callers that already know the exact swap sequence they
+ * want `collect_interest` to execute.
+ */
+export interface CollectInterestBuilderParams {
+  /** Yielding bank whose shares will be redeemed. */
+  yieldingBank: Address;
+  /** Prebuilt CPI descriptors that swap redeemed assets into collateral. */
+  cpiData: CpiData[];
+}
+
+/**
+ * Fully executable `collect_interest` plan produced by `client.routeBuilder`.
+ *
+ * Extends the deterministic planner result with the exact CPI sequence,
+ * pre-instructions, and initial accounts required by the final tx composer.
+ */
+export interface CollectInterestExecutionPlan extends CollectInterestPlan, SingleCpiExecutionPlan {}
+
+/**
+ * Precomputed execution-plan wrapper accepted by `client.tx.collectInterest.getTx({...})`.
+ */
+export interface CollectInterestTxPlanParams {
+  /** Route-builder result previously returned by `client.routeBuilder.buildCollectInterestRoutePlan()`. */
+  plan: CollectInterestExecutionPlan;
+}

package/src/client/types/planTypes/common.ts

@@ -0,0 +1,31 @@
+import type { Instruction } from "@solana/kit";
+import type { CpiData, CustomAccountMeta } from "common";
+
+/**
+ * Shared fields carried by normalized execution plans.
+ *
+ * These values are produced before the transaction layer resolves remaining
+ * account refs and ATA creation instructions.
+ */
+export interface PlannedInstructionBase {
+  /** Pre-instructions that must run before ATA creation or the main instruction. */
+  preInstructions: Instruction[];
+  /** Accounts that must lead the remaining-accounts pool before CPI accounts are appended. */
+  initialAccounts: CustomAccountMeta[];
+}
+
+/**
+ * Execution-plan shape for instructions that use a single CPI ref group.
+ */
+export interface SingleCpiExecutionPlan extends PlannedInstructionBase {
+  /** Ordered CPI descriptors consumed by one instruction-level refs input. */
+  cpiData: CpiData[];
+}
+
+/**
+ * Execution-plan shape for instructions that use multiple CPI ref groups.
+ */
+export interface GroupedCpiExecutionPlan extends PlannedInstructionBase {
+  /** Ordered CPI groups where each group maps to a distinct refs input. */
+  cpiDataGroups: CpiData[][];
+}

package/src/client/types/planTypes/decreaseCarryPosition.ts

@@ -0,0 +1,134 @@
+import type { Address } from "@solana/kit";
+import type BN from "bn.js";
+import type { LendingPlatformData, LpInstructionsBase } from "lending-platforms";
+import type { CpiData, Environment } from "common";
+import type { GroupedCpiExecutionPlan } from "./common";
+
+/**
+ * Mutually exclusive ways to steer repay sizing. Omit to use default obligation-relative
+ * sizing (`LycLendingPositionManager.calcDebtChangeAmount` with no utilization target).
+ *
+ * `DecreaseCarryPositionPlan.targetUtilizationRateBps` is set when the on-chain instruction
+ * must validate post-repay utilization against an explicit bps value (manager signer):
+ * - `explicitTargetUtilization` — caller supplies bps for both sizing and the instruction.
+ * - `collateralWithdrawal` with `allowBelowTargetOnChain` — sizing uses
+ *   `calcPreWithdrawalTargetUtilizationRateBps`; set the flag when this DCP must pass derived
+ *   utilization bps on-chain because post-repay utilization will sit **below** the position's
+ *   configured `targetUtilizationRateBps` (e.g. pre-rebalance unwind).
+ */
+export type DecreaseCarryRepaySteering =
+  | {
+      mode: "collateralWithdrawal";
+      /** Collateral (UI units) removed after this repay. */
+      collateralWithdrawalUiAmount: number;
+      /**
+       * Desired utilization after the later collateral withdrawal. Defaults to the
+       * position's configured target.
+       */
+      postWithdrawalTargetUtilizationRateBps?: number;
+      /**
+       * When true, allow passing derived utilization bps on-chain (same bps as sizing) so a
+       * manager `decrease_carry_position` can validate when post-repay utilization sits **below**
+       * the position's configured `targetUtilizationRateBps` (e.g. pre-rebalance unwind).
+       */
+      allowBelowTargetOnChain?: boolean;
+    }
+  | {
+      mode: "explicitTargetUtilization";
+      /**
+       * Caller supplies utilization (bps) for repay sizing and on-chain post-repay check (manager signer).
+       * Often equals or is derived from the position's configured target; this mode passes bps through
+       * explicitly, unlike `collateralWithdrawal`, which derives a target from UI collateral out.
+       */
+      targetUtilizationRateBps: number;
+    };
+
+/**
+ * Deterministic inputs for deriving a `decrease_carry_position` plan.
+ *
+ * Pass this to `client.planner.buildDecreaseCarryPositionPlan()` when you want
+ * the SDK to compute repay math, swap requirements, and grouped CPI inputs.
+ */
+export interface DecreaseCarryPositionBuilderParams {
+  /** Index into the token's `lendingPositions` array for the position to repay. */
+  lendingPositionIndex: number;
+  /** Yielding bank PDA holding the funds that will be redeemed or swapped for repayment. */
+  yieldingBank: Address;
+  /** Lending-platform instruction client used to build the repay CPI sequence. */
+  lendingIx: LpInstructionsBase<LendingPlatformData>;
+  /** Deployment environment used for off-chain price fetches during repay sizing. */
+  environment?: Environment;
+  /** Slippage tolerance for any required DCP swap, in basis points. Defaults to `40`. */
+  swapSlippageBps?: number;
+  /** DEX labels to exclude from any required DCP swap (e.g. venues that failed a prior attempt). */
+  swapExcludeDexes?: string[];
+  /**
+   * Optional override for the asset redeemed from the yielding bank.
+   *
+   * Defaults to the bank's `defaultRedemptionMint`. On-chain permission checks
+   * may reject non-manager callers that override this away from the configured
+   * default redemption mint.
+   */
+  sourceMint?: Address;
+  /**
+   * Optional transaction identifier shared with the lending client.
+   *
+   * Reuse a parent transaction ID when composing this flow into a larger
+   * transaction so lending pre-instructions are not duplicated.
+   */
+  txId?: string;
+  /**
+   * Steers how the planner picks the obligation / repay size. At most one variant;
+   * omit for default sizing.
+   */
+  repaySteering?: DecreaseCarryRepaySteering;
+  /**
+   * When true (e.g. burn-token liquidity management), non-manager callers may execute
+   * the resulting plan subject to the instruction's post-repay validation.
+   */
+  permissionlessOperation?: boolean;
+}
+
+/**
+ * Precomputed plan wrapper accepted by `client.tx.decreaseCarryPosition.getTx({...})`.
+ */
+export interface DecreaseCarryPositionTxPlanParams {
+  /** Planner result previously returned by `client.planner.buildDecreaseCarryPositionPlan()`. */
+  plan: DecreaseCarryPositionPlan;
+}
+
+/**
+ * Deterministic execution plan for `decrease_carry_position`.
+ *
+ * Produced by `client.planner.buildDecreaseCarryPositionPlan()` and later
+ * consumed by `client.tx.decreaseCarryPosition.getTx({...})`. This keeps repay math,
+ * swap decisions, and grouped CPI assembly out of the transaction composer.
+ */
+export interface DecreaseCarryPositionPlan extends GroupedCpiExecutionPlan {
+  /** Optional prerequisite CPIs executed before any lending-position refresh. */
+  tokenPrerequisiteCpis?: CpiData[];
+  /**
+   * When set, passed through to `decrease_carry_position` for manager-only
+   * post-repay validation. Populated from explicit steering or from
+   * `collateralWithdrawal` + `allowBelowTargetOnChain` (derived bps = sizing target).
+   */
+  targetUtilizationRateBps?: number;
+  /** Index into the token account's `lendingPositions` array. */
+  lendingPositionIndex: number;
+  /** Raw debt repayment amount in base units. */
+  repayAmount: BN;
+  /**
+   * Yielding-bank holding index redeemed as the swap source.
+   *
+   * Omitted when no preliminary swap is needed because the debt asset is
+   * already held directly by the yielding bank.
+   */
+  sourceAssetHoldingIndex?: number;
+  /** Yielding bank refreshed immediately before the instruction executes. */
+  yieldingBank: Address;
+  /**
+   * When set, `decrease_carry_position` / burn unwind must encode `repay_amount` as null.
+   * This is only needed for flows where the exact repay amount must be derived on-chain.
+   */
+  omitOnChainRepayAmount?: boolean;
+}

package/src/client/types/planTypes/index.ts

@@ -0,0 +1,3 @@
+export * from "./collectInterest";
+export * from "./common";
+export * from "./decreaseCarryPosition";

package/src/client/types/tx.ts

@@ -0,0 +1,409 @@
+import type { BN } from "@anchor-lang/core";
+import type { Address } from "@solana/kit";
+import type {
+  AnchorOracleType,
+  CpiData,
+  SwapClient,
+  TransactionCacheInvalidation,
+  TransactionPlan as BaseTransactionPlan,
+} from "common";
+import { YieldingBankAllocationConfig } from "./ix";
+import type {
+  DecreaseCarryPositionTxPlanParams,
+  DecreaseCarryRepaySteering,
+} from "./planTypes/decreaseCarryPosition";
+import type { TokenLpPositionAccountOverrides } from "./ix";
+
+/**
+ * Fully composed transaction output ready to pass to `sendTransaction`.
+ */
+export interface LongYieldCarryTransactionPlan extends BaseTransactionPlan {
+  /**
+   * Cache entries that should be cleared only after the transaction confirms.
+   *
+   * This keeps transaction builders pure while still letting callers invalidate
+   * stale off-chain snapshots when a successful on-chain write changes account
+   * topology (for example first-time lending account setup).
+   */
+  postSuccessCacheInvalidations?: TransactionCacheInvalidation[];
+  /** Optional lending-client transaction id reused across composed plans. */
+  txId?: string;
+  /** Optional diagnostics for operator-facing scripts and services. */
+  debug?: LongYieldCarryTransactionPlanDebug;
+}
+
+export interface LongYieldCarryTransactionPlanDebug {
+  processAsyncBurn?: {
+    epochId: bigint;
+    sequence: bigint;
+    request: Address;
+    user: Address;
+    /** How collateral is delivered when the request is processed. */
+    collateralDelivery: "nativeSol" | "tokenAta";
+    /** Populated for non-native collateral mints. */
+    userCollateralAccount?: Address;
+    /** Populated for wrapped SOL collateral (request-scoped WSOL escrow). */
+    requestCollateralAccount?: Address;
+  };
+}
+
+// =============================================================================
+// mint_token
+// =============================================================================
+
+export interface MintTokenTxParams {
+  /**
+   * Collateral amount to deposit in base units (e.g. lamports).
+   *
+   * Pass `"all"` to deposit the entire collateral ATA balance. The on-chain
+   * instruction resolves `u64::MAX` to the ATA's live balance at execution time.
+   */
+  depositAmount: BN | "all";
+}
+
+// =============================================================================
+// burn_token
+// =============================================================================
+
+export interface BurnTokenTxParams {
+  /**
+   * yToken amount to burn in base units (e.g. lamports for a 9-decimal token).
+   *
+   * Pass `"all"` to burn every yToken in the user's ATA. The on-chain
+   * instruction resolves `u64::MAX` to the ATA's live balance at execution time.
+   */
+  burnAmount: BN | number | "all";
+  /**
+   * Override the auto-derived redemption epoch ID. Defaults to
+   * {@link currentEpochId} (floored to the nearest minute).
+   */
+  epochId?: BN | number;
+  /**
+   * Override the auto-derived request sequence within the epoch. Defaults to
+   * the next available sequence read from on-chain epoch state (or 0 for a
+   * fresh epoch).
+   */
+  requestSequence?: BN | number;
+}
+
+// =============================================================================
+// rebalance_yielding_bank
+// =============================================================================
+
+export interface RebalanceSwapSpec {
+  /**
+   * Swap client used to quote and build CPI data for this rebalance leg.
+   * When omitted, `getRebalanceYieldingBankTx` uses the transaction client's
+   * default aggregate swap client (Perena for USD* ↔ supported stables, Jupiter otherwise).
+   */
+  swapClient?: SwapClient;
+  /** Mint being sold. */
+  inputMint: Address;
+  /** Mint being bought. */
+  outputMint: Address;
+  /** Exact input or requested quote amount, depending on the swap client. */
+  amount: number;
+  /** Slippage tolerance in basis points. Defaults to the caller's chosen swap behavior. */
+  slippageBps?: number;
+}
+
+/**
+ * Extra account that backs an asset holding's off-ATA liquidity during refresh.
+ *
+ * Example: a Perena withdrawal queue that temporarily escrows USD*-J shares after
+ * `request_unstake_junior`, while the YieldingBank still economically owns them.
+ */
+export interface YieldingBankExternalLiquiditySource {
+  /** Asset mint whose refresh should include this external source. */
+  mint: Address;
+  /** Account holding the pending balance for that mint. */
+  account: Address;
+}
+
+/**
+ * Inputs for `client.tx.rebalanceYieldingBank.getTx({...})`.
+ *
+ * The transaction must be signed by the program's manager; ATA setup in the plan uses the
+ * client's environment manager address.
+ */
+export interface RebalanceYieldingBankTxParams {
+  /** Pre-built CPI descriptors (one per swap / deposit step). */
+  cpiData?: CpiData[];
+  /**
+   * High-level swap specifications. Each is resolved into CPI data by calling
+   * `getQuote` + `getSwapCpiData` on the leg's `swapClient`, or the SDK aggregate
+   * swap client when `swapClient` is omitted. Resolved CPI data is appended after
+   * any explicit `cpiData` entries.
+   */
+  swaps?: RebalanceSwapSpec[];
+  /**
+   * Optional new holding or external position to register before the
+   * rebalance executes.
+   */
+  newAllocation?: {
+    config: YieldingBankAllocationConfig;
+  };
+}
+
+// =============================================================================
+// refresh_tokens
+// =============================================================================
+
+export interface RefreshTokensTxParams {
+  /** Token PDA addresses to refresh. */
+  tokens: Address[];
+  /**
+   * When true, always prepend `refresh_yielding_bank` for each bank referenced
+   * by the token's active carry positions, even if the bank appears fresh
+   * client-side.
+   *
+   * When false (default), the builder skips yielding-bank refreshes whose
+   * cached `lastRefreshedTs` is still inside the normal freshness window.
+   */
+  alwaysRefreshYieldingBanks?: boolean;
+}
+
+// =============================================================================
+// top_up_unlent_reserves
+// =============================================================================
+
+export interface TopUpUnlentReservesTxParams {
+  /** Index into the token's lending_positions array for the source position. */
+  lendingPositionIndex: number;
+  /**
+   * Withdrawal amount in UI units (e.g. 1.5 for 1.5 SOL).
+   * Pass `"all"` to withdraw the entire lending position's collateral.
+   */
+  uiAmount: number | "all";
+  /** Optional redemption epoch PDA to credit with the withdrawn amount. */
+  redemptionEpoch?: Address;
+  /** Optional txId reused across composed plans in the same transaction. */
+  txId?: string;
+}
+
+// =============================================================================
+// process_async_burn
+// =============================================================================
+
+export interface ProcessAsyncBurnTxParams {
+  /** Epoch ID (the minute-bucketed timestamp used when the epoch was created). */
+  epochId: bigint | number;
+  /** FIFO sequence number of the request to process within the epoch. */
+  sequence: bigint | number;
+}
+
+// =============================================================================
+// deposit_unlent_collateral
+// =============================================================================
+
+export interface DepositUnlentCollateralTxParams {
+  /** Index into the token's lending_positions array for the target position. */
+  lendingPositionIndex: number;
+  /**
+   * Deposit amount in UI units (e.g. 1.5 for 1.5 SOL).
+   * Required unless `depositAll` is true.
+   */
+  uiAmount?: number;
+  /**
+   * When true, deposits all remaining unlent collateral. The token account
+   * is fetched to determine the exact amount, so `uiAmount` can be omitted.
+   */
+  depositAll?: boolean;
+  /** Optional txId reused across composed plans in the same transaction. */
+  txId?: string;
+}
+
+// =============================================================================
+// increase_carry_position
+// =============================================================================
+
+export interface IncreaseCarryPositionTxParams {
+  /** Index into the token's lending_positions array for the position to borrow against. */
+  lendingPositionIndex: number;
+  /** The YieldingBank PDA receiving the borrow proceeds. */
+  yieldingBank: Address;
+  /** Borrow amount in UI units (e.g. 100 for 100 USDC). */
+  uiAmount: number;
+  /** Optional txId reused across composed plans in the same transaction. */
+  txId?: string;
+}
+
+/**
+ * Inputs for `client.tx.rebalanceToken.getTx({...})`.
+ *
+ * When the source lending position would exceed target utilization after the
+ * collateral withdrawal, the builder automatically constructs the flash-loan-
+ * wrapped variant: flash-borrow source debt mint → repay source → withdraw
+ * collateral → deposit to destination → borrow destination debt mint →
+ * exact-out swap back to source debt mint → flash-repay.
+ */
+export interface RebalanceTokenTxParams {
+  /** Index into the token's lending_positions array for the position to rebalance in-place. */
+  lpIndex: number;
+  /**
+   * Target debt mint. The position's current debt is fully repaid via flash loan and this mint
+   * is borrowed instead on the same lending position. The builder resolves the corresponding
+   * reserve via `fetchReserveByMint` and the oracle via the oracle registry.
+   */
+  destinationDebtMint: Address;
+  /**
+   * Collateral amount used for destination borrow capacity sizing, in UI units. Pass `"all"` to
+   * size based on the full current source debt (uses the platform's repay-all sentinel so
+   * on-chain interest accrual between snapshot and landing cannot leave dust).
+   */
+  uiAmount: number | "all";
+  /** Slippage tolerance for the exact-out flash swap, in basis points. Defaults to 100. */
+  swapSlippageBps?: number;
+  /**
+   * Maximum acceptable execution cost (route fees + price impact) of the
+   * rebalance swap quote vs the oracle-fair cross rate, in bps (see
+   * `FlashRebalanceParams.maxSwapCostBps`). When breached, `getTx` throws
+   * `FlashRebalanceSwapCostExceededError` instead of returning a plan.
+   * Unset = no limit.
+   */
+  maxSwapCostBps?: number;
+  /**
+   * Maximum acceptable market basis between the two debt stables (oracle-fair
+   * cross rate vs 1:1), in bps, either direction (see
+   * `FlashRebalanceParams.maxMarketBasisBps`). Unset = no limit.
+   */
+  maxMarketBasisBps?: number;
+  /** Optional explicit overrides for the LP refresh accounts (user account, collateral reserve, debt oracle). */
+  lpPosition?: TokenLpPositionAccountOverrides;
+  /**
+   * Optional transaction identifier shared with lending clients so composed
+   * flows can hoist top-level pre-instructions.
+   */
+  txId?: string;
+  /**
+   * Yielding bank that absorbs the destination-debt slippage dust after the
+   * exact-out swap. Defaults to the first active yielding bank recorded in the
+   * token's `debtCarry` entries.
+   */
+  yieldingBank?: Address;
+}
+
+export interface DecreaseCarryPositionTxBuilderParams {
+  /** Index into the token's `lendingPositions` array for the position to repay. */
+  lendingPositionIndex: number;
+  /** Yielding bank PDA holding the funds that will be redeemed or swapped for repayment. */
+  yieldingBank: Address;
+  /** Slippage tolerance for any required DCP swap, in basis points. Defaults to `40`. */
+  swapSlippageBps?: number;
+  /** DEX labels to exclude from any required DCP swap (e.g. venues that failed a prior attempt). */
+  swapExcludeDexes?: string[];
+  /**
+   * Optional override for the asset redeemed from the yielding bank.
+   *
+   * Defaults to the bank's `defaultRedemptionMint`. On-chain permission checks
+   * may reject non-manager callers that override this away from the configured
+   * default redemption mint.
+   */
+  sourceMint?: Address;
+  /**
+   * Optional transaction identifier shared with the lending client.
+   *
+   * Reuse a parent transaction ID when composing this flow into a larger
+   * transaction so lending pre-instructions are not duplicated.
+   */
+  txId?: string;
+  /** See {@link DecreaseCarryRepaySteering}. */
+  repaySteering?: DecreaseCarryRepaySteering;
+  /**
+   * Same as {@link DecreaseCarryPositionBuilderParams.permissionlessOperation}: when true,
+   * non-manager callers may execute the resulting plan subject to post-repay validation.
+   */
+  permissionlessOperation?: boolean;
+}
+
+/**
+ * Inputs accepted by `client.tx.decreaseCarryPosition.getTx({...})`.
+ *
+ * Pass raw builder params to have the SDK plan the instruction for you, or
+ * pass `{ plan }` when you have pre-built a plan via `buildDecreaseCarryPositionPlan`.
+ */
+export type DecreaseCarryPositionTxParams =
+  | DecreaseCarryPositionTxBuilderParams
+  | DecreaseCarryPositionTxPlanParams;
+
+// =============================================================================
+// recollateralize_loss
+// =============================================================================
+
+/**
+ * Inputs for `client.tx.recollateralizeLoss.getTx({...})`.
+ *
+ * The transaction builder internally:
+ *  1. Computes the debt excess (total_debt − total_carry) from on-chain state.
+ *  2. Quotes a collateral → debt swap to cover that excess.
+ *  3. Checks whether withdrawing the required collateral would push the LP
+ *     above its target utilization rate. If so, prepends a
+ *     `decrease_carry_position` sized to free the needed headroom.
+ *  4. Builds the Withdraw → Swap → Repay CPI sequence for the main instruction.
+ */
+export interface RecollateralizeLossTxParams {
+  /** Slippage tolerance for swaps (collateral → debt), in basis points. Defaults to 150. */
+  swapSlippageBps?: number;
+  /**
+   * Optional override for the asset redeemed from the yielding bank during DCP.
+   * Defaults to the bank's `defaultRedemptionMint`. Only used when a
+   * `decrease_carry_position` is needed to free collateral for the withdrawal.
+   */
+  sourceMint?: Address;
+  /** Optional txId shared with lending clients for pre-instruction deduplication. */
+  txId?: string;
+  /** Optional explicit overrides for LP refresh accounts. */
+  lpPosition?: TokenLpPositionAccountOverrides;
+}
+
+// =============================================================================
+// collect_interest
+// =============================================================================
+
+/**
+ * Inputs accepted by `client.tx.collectInterest.getTx({...})`.
+ */
+export interface CollectInterestTxParams {
+  /** Yielding bank whose carry position should collect accrued interest. */
+  yieldingBank: Address;
+  /** Slippage tolerance applied to all swaps. Defaults to 100 bps. */
+  slippageBps?: number;
+  /** Final output mint. Defaults to the token's collateral mint. */
+  outputMint?: Address;
+  /**
+   * Minimum net yield (in USD) below which collection is skipped.
+   * Prevents wasteful swaps when accrued interest is negligible.
+   * Value is in human-readable USD (e.g. 0.5 = $0.50).
+   */
+  minYieldUsd?: number;
+}
+
+// =============================================================================
+// claim_incentives
+// =============================================================================
+
+export interface ClaimIncentivesTxParams {
+  /** Index into the token's lending_positions array. */
+  lendingPositionIndex: number;
+  /** Incentive reward mint to harvest. */
+  incentiveMint: Address;
+  /**
+   * Pre-resolved farm and user-farm addresses for the claim CPI. When provided
+   * the builder skips the on-chain incentive lookup — required when the same
+   * incentive mint appears from multiple farms (obligation vs. direct).
+   */
+  claimAccounts?: { farm: Address; userFarm: Address };
+  /**
+   * Yielding bank that receives the claimed rewards. Defaults to the first
+   * active yielding bank recorded in the token's `debtCarry` entries.
+   */
+  yieldingBank?: Address;
+  /**
+   * Oracle pricing `incentiveMint`. Auto-resolved when the mint matches the
+   * debt of an active lending position or is in the shared mints registry;
+   * required otherwise.
+   */
+  incentiveOracle?: Address;
+  /** Oracle type for `incentiveOracle`. Auto-resolved when `incentiveOracle` is. */
+  incentiveOracleType?: AnchorOracleType;
+}