@kestrelfi/lyc-sdk 1.0.1

package/src/client/builders/args.ts

@@ -0,0 +1,381 @@
+import type { BN } from "@anchor-lang/core";
+import type { Address } from "@solana/kit";
+import type { LendingPlatform } from "common";
+import type {
+  BurnTokenIxParams,
+  BurnTokenTxParams,
+  ClaimIncentivesTxParams,
+  CollectInterestTxParams,
+  ClaimIncentivesParams,
+  CollectInterestParams,
+  CreateCpiPlanParams,
+  CreateTokenLendingPositionAccounts,
+  CreateTokenLendingPositionParams,
+  CreateTokenParams,
+  CreateYieldingBankParams,
+  DecreaseCarryPositionParams,
+  DecreaseCarryPositionTxParams,
+  DepositUnlentCollateralParams,
+  DepositUnlentCollateralTxParams,
+  IncreaseCarryPositionParams,
+  IncreaseCarryPositionTxParams,
+  MintTokenTxParams,
+  RebalanceTokenParams,
+  RebalanceTokenTxParams,
+  RebalanceYieldingBankParams,
+  RebalanceYieldingBankTxParams,
+  RecollateralizeLossParams,
+  RecollateralizeLossTxParams,
+  RefreshTokensTxParams,
+  UpdateLendingPositionConfigParams,
+  UpdateTokenConfigurationParams,
+  UpdateTokenMetadataParams,
+  UpdateYieldingBankConfigParams,
+  SetRedemptionEpochStatusParams,
+  TopUpUnlentReservesParams,
+  TopUpUnlentReservesTxParams,
+  ProcessAsyncBurnTxParams,
+  YieldingBankAllocationConfig,
+  YieldingBankExternalLiquiditySource,
+} from "../types";
+
+export interface CreateTokenIxArgs {
+  mint: Address;
+  collateralMint: Address;
+  params: CreateTokenParams;
+  tokenProgram?: Address;
+  collateralTokenProgram?: Address;
+  /** Curator signer. Must be in the on-chain `WHITELISTED_CURATORS` list.
+   *  Defaults to the builder's admin wallet. */
+  curator?: Address;
+  /** Optional per-token admin override. Omit to use the feature-gated program default. */
+  adminRole?: Address;
+  /** Optional per-token manager override. Omit to use the program default. */
+  managerRole?: Address;
+  /** Optional per-token curator-fees wallet override. Omit to use the program default. */
+  feesRole?: Address;
+  /** Optional per-token circuit-breaker controller override. Omit to use the program default. */
+  cbControllerRole?: Address;
+}
+
+export interface CreateCpiPlanIxArgs {
+  cpiPlan: Address;
+  manager: Address;
+  params: CreateCpiPlanParams;
+}
+
+export interface UpdateTokenMetadataIxArgs {
+  token: Address;
+  mint: Address;
+  params: UpdateTokenMetadataParams;
+}
+
+export interface CreateTokenLendingPositionIxArgs {
+  token: Address;
+  params: CreateTokenLendingPositionParams;
+  /**
+   * Accounts that describe the new lending position — their pubkeys are
+   * stored on the position and their on-chain state is read by the final
+   * refresh.
+   */
+  accounts: CreateTokenLendingPositionAccounts;
+}
+
+export interface CreateTokenLendingPositionTxArgs {
+  /** Token PDA that will own the new lending position. */
+  token: Address;
+  /**
+   * Debt mint address. Decimals, token program, and oracle metadata are
+   * derived from the mint registry / oracle service.
+   */
+  debtMint: Address;
+  /** Debt reserve address. Looked up by `debtMint` against the pool when omitted. */
+  debtReserve?: Address;
+  /**
+   * Lending-protocol user-account ID used when the obligation must be
+   * created. Ignored when the protocol user account already exists.
+   * Defaults to 0. For Kamino this is the obligation sub-account index.
+   */
+  userAccountId?: number;
+  /**
+   * Lending pool. When omitted, resolved automatically from the token's
+   * collateral mint via {@link resolveDefaultPool}. Throws if the mint
+   * is listed in zero or multiple pools (caller must disambiguate).
+   */
+  pool?: Address;
+  /** @default LendingPlatform.Kamino */
+  lendingPlatform?: LendingPlatform;
+  /** @default 9000 */
+  targetUtilizationRateBps?: number;
+  /** @default 150 */
+  maxDeviationAboveTargetUtilBps?: number;
+  /** @default 300 */
+  maxDeviationBelowTargetUtilBps?: number;
+  /** Optional txId reused across composed plans in the same transaction. */
+  txId?: string;
+}
+
+export interface CreateYieldingBankIxArgs {
+  baseMint: Address;
+  params: CreateYieldingBankParams;
+  baseMintTokenProgram?: Address;
+  /** Curator signer. Must be in on-chain `WHITELISTED_CURATORS`. Defaults to builder admin. */
+  curator?: Address;
+  /** Optional admin override. Omit to use the program default. */
+  adminRole?: Address;
+  /** Optional manager override. Omit to use the program default. */
+  managerRole?: Address;
+  /** Optional circuit-breaker controller override. Omit to use the program default. */
+  cbControllerRole?: Address;
+}
+
+export interface RefreshYieldingBankIxArgs {
+  signer: Address;
+  yieldingBank: Address;
+  externalLiquiditySources?: YieldingBankExternalLiquiditySource[];
+}
+
+export interface RefreshYieldingBankTxArgs {
+  signer: Address;
+  yieldingBank: Address;
+}
+
+export interface CreateYieldingBankAllocationIxArgs {
+  yieldingBank: Address;
+  config: YieldingBankAllocationConfig;
+}
+
+export interface RebalanceYieldingBankIxArgs {
+  yieldingBank: Address;
+  params: RebalanceYieldingBankParams;
+}
+
+export interface RebalanceYieldingBankTxArgs {
+  yieldingBank: Address;
+  params: RebalanceYieldingBankTxParams;
+}
+
+export interface RefreshTokenStateIxArgs {
+  signer: Address;
+  token: Address;
+  collateralOracle: Address;
+  /** Optional secondary oracle account, required only for composite oracle
+   * types. For `PythSplStake` collateral this is the SPL stake pool account. */
+  secondaryCollateralOracle?: Address;
+  collateralTokenAccount: Address;
+  collateralTokenProgram: Address;
+}
+
+export interface RefreshTokensBuilderTxArgs {
+  signer: Address;
+  params: RefreshTokensTxParams;
+}
+
+export interface IncreaseCarryPositionIxArgs {
+  token: Address;
+  params: IncreaseCarryPositionParams;
+}
+
+export interface IncreaseCarryPositionTxArgs {
+  manager: Address;
+  token: Address;
+  params: IncreaseCarryPositionTxParams;
+}
+
+export interface RebalanceTokenIxArgs {
+  token: Address;
+  params: RebalanceTokenParams;
+}
+
+export interface RebalanceTokenTxArgs {
+  token: Address;
+  params: RebalanceTokenTxParams;
+}
+
+export interface RecollateralizeLossIxArgs {
+  token: Address;
+  params: RecollateralizeLossParams;
+}
+
+export interface RecollateralizeLossTxArgs {
+  token: Address;
+  params: RecollateralizeLossTxParams;
+}
+
+export interface DecreaseCarryPositionIxArgs {
+  signer: Address;
+  params: DecreaseCarryPositionParams;
+}
+
+export interface DecreaseCarryPositionTxArgs {
+  signer: Address;
+  token: Address;
+  params: DecreaseCarryPositionTxParams;
+  /** When set, the DCP loss is attributed to this epoch instead of socialised into the price. */
+  redemptionEpoch?: Address;
+}
+
+export interface UpdateLendingPositionConfigIxArgs {
+  token: Address;
+  params: UpdateLendingPositionConfigParams;
+}
+
+export interface DepositUnlentCollateralIxArgs {
+  token: Address;
+  params: DepositUnlentCollateralParams;
+}
+
+export interface SetTokenCircuitBreakerIxArgs {
+  authority: Address;
+  token: Address;
+  active: boolean;
+}
+
+export interface SetTokenCircuitBreakerTxArgs {
+  authority: Address;
+  token: Address;
+  active: boolean;
+}
+
+export interface MintTokenIxArgs {
+  signer: Address;
+  token: Address;
+  depositAmount: BN;
+}
+
+export interface MintTokenTxArgs {
+  signer: Address;
+  token: Address;
+  params: MintTokenTxParams;
+}
+
+export interface BurnTokenIxArgs {
+  signer: Address;
+  token: Address;
+  params: BurnTokenIxParams;
+  /** Pays rent for async-path accounts; must sign the transaction. Defaults to signer. */
+  payer?: Address;
+}
+
+export interface BurnTokenTxArgs {
+  signer: Address;
+  token: Address;
+  params: BurnTokenTxParams;
+  /** Pays rent for async-path accounts; must sign the transaction. Defaults to signer. */
+  payer?: Address;
+}
+
+export interface SetRedemptionEpochStatusIxArgs {
+  token: Address;
+  redemptionEpoch: Address;
+  params: SetRedemptionEpochStatusParams;
+}
+
+export interface TopUpUnlentReservesIxArgs {
+  token: Address;
+  params: TopUpUnlentReservesParams;
+}
+
+export interface TopUpUnlentReservesTxArgs {
+  token: Address;
+  params: TopUpUnlentReservesTxParams;
+}
+
+export interface CreditUnlentToRedemptionEpochIxArgs {
+  token: Address;
+  redemptionEpoch: Address;
+}
+
+export interface ProcessAsyncBurnIxArgs {
+  token: Address;
+  redemptionEpoch: Address;
+  request: Address;
+}
+
+export interface ProcessAsyncBurnTxArgs {
+  token: Address;
+  params: ProcessAsyncBurnTxParams;
+}
+
+export interface ClaimIncentivesIxArgs {
+  token: Address;
+  params: ClaimIncentivesParams;
+}
+
+export interface ClaimIncentivesTxArgs {
+  token: Address;
+  params: ClaimIncentivesTxParams;
+}
+
+export interface CollectInterestIxArgs {
+  token: Address;
+  yieldingBank: Address;
+  params: CollectInterestParams;
+}
+
+export interface CollectInterestTxArgs {
+  manager: Address;
+  token: Address;
+  params: CollectInterestTxParams;
+}
+
+export interface SetYieldingBankCircuitBreakerIxArgs {
+  authority: Address;
+  yieldingBank: Address;
+  active: boolean;
+}
+
+export interface SetYieldingBankCircuitBreakerTxArgs {
+  authority: Address;
+  yieldingBank: Address;
+  active: boolean;
+}
+
+export interface UpdateYieldingBankConfigIxArgs {
+  yieldingBank: Address;
+  params: UpdateYieldingBankConfigParams;
+  /** Optional admin signer override. */
+  admin?: Address;
+  /** Optional new manager. Omit for no change. */
+  managerRole?: Address;
+  /** Optional new circuit-breaker controller. Omit for no change. */
+  cbControllerRole?: Address;
+}
+
+export interface ResetTokenBurnRateLimitIxArgs {
+  token: Address;
+}
+
+export interface UpdateTokenConfigurationIxArgs {
+  token: Address;
+  params: UpdateTokenConfigurationParams;
+  /**
+   * Optional authority signer. The token admin may update all configuration;
+   * the token manager may update fee fields only. Defaults to the token admin.
+   */
+  admin?: Address;
+  /** Optional new manager. Omit for no change. */
+  managerRole?: Address;
+  /** Optional new curator-fees wallet. Omit for no change. */
+  feesRole?: Address;
+  /** Optional new circuit-breaker controller. Omit for no change. */
+  cbControllerRole?: Address;
+}
+
+export interface CollectFeesIxArgs {
+  token: Address;
+  /**
+   * Signer collecting the fees. Must be either the token's `roles.curator`
+   * (drains `pending_curator_fees` into the curator fee wallet) or the
+   * program-wide `PROTOCOL_ADMIN` (drains `pending_protocol_fees` into the
+   * protocol fee wallet). The fee bucket and destination wallet are both
+   * derived from whichever role this signer matches.
+   */
+  authority: Address;
+}
+
+export interface DepositUnlentCollateralTxArgs {
+  manager: Address;
+  token: Address;
+  params: DepositUnlentCollateralTxParams;
+}

package/src/client/builders/asyncBurnBuilder.ts

@@ -0,0 +1,305 @@
+import type { Address, Instruction } from "@solana/kit";
+import { PublicKey } from "@solana/web3.js";
+import {
+  createCpiRefs,
+  fromWeb3Pk,
+  getAtaAddress,
+  getCreateAtaInstructions,
+  getCreateAtaIxIfNeeded,
+  mints,
+  resolveTokenProgram,
+  toKitInstruction,
+  toWeb3AccountMeta,
+  type TransactionCacheInvalidation,
+} from "common";
+import type {
+  CreditUnlentToRedemptionEpochIxArgs,
+  ProcessAsyncBurnIxArgs,
+  ProcessAsyncBurnTxArgs,
+  SetRedemptionEpochStatusIxArgs,
+  TopUpUnlentReservesIxArgs,
+  TopUpUnlentReservesTxArgs,
+} from "./args";
+import type { LongYieldCarryTransactionPlan } from "../types";
+import { LongYieldCarryBuilderBase } from "./base";
+
+export class SetRedemptionEpochStatusBuilder extends LongYieldCarryBuilderBase<
+  SetRedemptionEpochStatusIxArgs,
+  SetRedemptionEpochStatusIxArgs
+> {
+  async getTx(args: SetRedemptionEpochStatusIxArgs): Promise<LongYieldCarryTransactionPlan> {
+    return { instructions: [await this.getIx(args)], lookupTables: [] };
+  }
+
+  async getIx(args: SetRedemptionEpochStatusIxArgs): Promise<Instruction> {
+    const tokenData = await this.account.fetchToken(args.token);
+    const manager = this.resolveTokenManager(tokenData.data);
+    const epochData = await this.program.account.redemptionEpoch.fetch(args.redemptionEpoch);
+    const epochRentRecipient = epochData.header.payer.equals(PublicKey.default)
+      ? manager
+      : (epochData.header.payer.toBase58() as Address);
+
+    return this.program.methods
+      .setRedemptionEpochStatus({ status: args.params.status })
+      .accountsPartial({
+        manager,
+        token: args.token,
+        redemptionEpoch: args.redemptionEpoch,
+        epochRentRecipient,
+      })
+      .instruction()
+      .then(toKitInstruction);
+  }
+}
+
+export class TopUpUnlentReservesBuilder extends LongYieldCarryBuilderBase<
+  TopUpUnlentReservesIxArgs,
+  TopUpUnlentReservesTxArgs
+> {
+  async getTx(args: TopUpUnlentReservesTxArgs): Promise<LongYieldCarryTransactionPlan> {
+    const tokenData = await this.account.fetchToken(args.token, { fresh: true });
+    const position = tokenData.data.lendingPositions[args.params.lendingPositionIndex];
+    const manager = this.resolveTokenManager(tokenData.data);
+
+    const txId =
+      args.params.txId ??
+      `top-up-unlent-reserves-${Date.now()}-${position.protocolUserAcc.toBase58()}`;
+
+    const cpiBundle = await this.getLendingOperationCpiData(
+      args.token,
+      manager,
+      position,
+      txId,
+      "withdraw",
+      args.params.uiAmount
+    );
+    const prerequisiteCpiRefs = createCpiRefs(cpiBundle.prerequisiteCpis);
+    const {
+      accounts: remainingAccounts,
+      refs: ixRefs,
+      lookupTables,
+    } = createCpiRefs(cpiBundle.cpis, { initialAccounts: prerequisiteCpiRefs.accounts });
+
+    const lpClient = this.getLendingPlatformClient(position);
+    const preInstructions = await lpClient.ix.getPreInstructions(txId);
+    const { instructions: ataCreationIxs, postSuccessCacheInvalidations } =
+      await getCreateAtaInstructions(this.rpc, manager, remainingAccounts);
+
+    const redemptionEpoch = args.params.redemptionEpoch ?? undefined;
+    const topUpIx = await this.getIx({
+      token: args.token,
+      params: {
+        prerequisiteCpis: prerequisiteCpiRefs.refs,
+        ixRefs,
+        lendingPositionIndex: args.params.lendingPositionIndex,
+        remainingAccounts,
+        redemptionEpoch,
+      },
+    });
+
+    return {
+      instructions: [...preInstructions, ...ataCreationIxs, topUpIx],
+      lookupTables: this.getTxLookupTables(args.token, [
+        ...(lookupTables ?? []),
+        ...(prerequisiteCpiRefs.lookupTables ?? []),
+      ]),
+      postSuccessCacheInvalidations: [
+        ...cpiBundle.postSuccessCacheInvalidations,
+        ...postSuccessCacheInvalidations,
+      ],
+      txId,
+    };
+  }
+
+  async getIx(args: TopUpUnlentReservesIxArgs): Promise<Instruction> {
+    const tokenData = await this.account.fetchToken(args.token);
+    const position = tokenData.data.lendingPositions[args.params.lendingPositionIndex];
+    const collateralTokenProgram = resolveTokenProgram(tokenData.data.collateral.tokenProgram);
+    return this.program.methods
+      .topUpUnlentReserves({
+        prerequisiteCpis: args.params.prerequisiteCpis,
+        ixRefs: args.params.ixRefs,
+        lendingPositionIndex: args.params.lendingPositionIndex,
+      })
+      .accountsPartial({
+        manager: this.resolveTokenManager(tokenData.data),
+        token: args.token,
+        redemptionEpoch: args.params.redemptionEpoch ?? null,
+        collateralMint: tokenData.collateralMint,
+        collateralTokenProgram,
+        lendingPositionUserAccount: fromWeb3Pk(position.protocolUserAcc),
+        lendingPositionCollateralReserve: fromWeb3Pk(position.collateralReserve),
+      })
+      .remainingAccounts(args.params.remainingAccounts.map(toWeb3AccountMeta))
+      .instruction()
+      .then(toKitInstruction);
+  }
+}
+
+export class CreditUnlentToRedemptionEpochBuilder extends LongYieldCarryBuilderBase<
+  CreditUnlentToRedemptionEpochIxArgs,
+  CreditUnlentToRedemptionEpochIxArgs
+> {
+  async getTx(args: CreditUnlentToRedemptionEpochIxArgs): Promise<LongYieldCarryTransactionPlan> {
+    return { instructions: [await this.getIx(args)], lookupTables: [] };
+  }
+
+  async getIx(args: CreditUnlentToRedemptionEpochIxArgs): Promise<Instruction> {
+    const tokenData = await this.account.fetchToken(args.token);
+    const collateralTokenProgram = resolveTokenProgram(tokenData.data.collateral.tokenProgram);
+    const collateralTokenAccount = await getAtaAddress(
+      tokenData.collateralMint,
+      args.token,
+      collateralTokenProgram
+    );
+
+    return this.program.methods
+      .creditUnlentToRedemptionEpoch()
+      .accountsPartial({
+        manager: this.resolveTokenManager(tokenData.data),
+        token: args.token,
+        redemptionEpoch: args.redemptionEpoch,
+        collateralMint: tokenData.collateralMint,
+        collateralTokenAccount,
+        collateralTokenProgram,
+      })
+      .instruction()
+      .then(toKitInstruction);
+  }
+}
+
+export class ProcessAsyncBurnBuilder extends LongYieldCarryBuilderBase<
+  ProcessAsyncBurnIxArgs,
+  ProcessAsyncBurnTxArgs
+> {
+  async getTx(args: ProcessAsyncBurnTxArgs): Promise<LongYieldCarryTransactionPlan> {
+    const epochId = BigInt(args.params.epochId.toString());
+    const sequence = BigInt(args.params.sequence.toString());
+
+    const [redemptionEpoch] = await this.pda.deriveRedemptionEpochPda(args.token, epochId);
+    const [request] = await this.pda.deriveAsyncBurnRequestPda(args.token, epochId, sequence);
+    const tokenData = await this.account.fetchToken(args.token);
+    const manager = this.resolveTokenManager(tokenData.data);
+    const requestData = await this.program.account.asyncBurnRequest.fetch(request);
+    const collateralTokenProgram = resolveTokenProgram(tokenData.data.collateral.tokenProgram);
+    const user = requestData.header.user.toBase58() as Address;
+    const isNativeSolCollateral = tokenData.collateralMint === mints.get("SOL")?.address;
+
+    const instructions: Instruction[] = [];
+    const postSuccessCacheInvalidations: TransactionCacheInvalidation[] = [];
+
+    if (isNativeSolCollateral) {
+      const requestCollateralAccount = await getAtaAddress(
+        tokenData.collateralMint,
+        request,
+        collateralTokenProgram
+      );
+      const createRequestCollateralAta = await getCreateAtaIxIfNeeded(
+        this.rpc,
+        manager,
+        tokenData.collateralMint,
+        request,
+        collateralTokenProgram,
+        { accountClient: this.account }
+      );
+      if (createRequestCollateralAta.instruction) {
+        instructions.push(createRequestCollateralAta.instruction);
+        postSuccessCacheInvalidations.push(
+          ...(createRequestCollateralAta.postSuccessCacheInvalidations ?? [])
+        );
+      }
+    } else {
+      const userCollateralAccount = await getAtaAddress(
+        tokenData.collateralMint,
+        user,
+        collateralTokenProgram
+      );
+      const createUserCollateralAta = await getCreateAtaIxIfNeeded(
+        this.rpc,
+        manager,
+        tokenData.collateralMint,
+        user,
+        collateralTokenProgram,
+        { accountClient: this.account }
+      );
+      if (createUserCollateralAta.instruction) {
+        instructions.push(createUserCollateralAta.instruction);
+        postSuccessCacheInvalidations.push(
+          ...(createUserCollateralAta.postSuccessCacheInvalidations ?? [])
+        );
+      }
+    }
+
+    instructions.push(await this.getIx({ token: args.token, redemptionEpoch, request }));
+
+    return {
+      instructions,
+      lookupTables: this.getTxLookupTables(args.token),
+      postSuccessCacheInvalidations,
+      debug: {
+        processAsyncBurn: {
+          epochId,
+          sequence,
+          request,
+          user,
+          collateralDelivery: isNativeSolCollateral ? "nativeSol" : "tokenAta",
+          userCollateralAccount: isNativeSolCollateral
+            ? undefined
+            : await getAtaAddress(tokenData.collateralMint, user, collateralTokenProgram),
+          requestCollateralAccount: isNativeSolCollateral
+            ? await getAtaAddress(tokenData.collateralMint, request, collateralTokenProgram)
+            : undefined,
+        },
+      },
+    };
+  }
+
+  async getIx(args: ProcessAsyncBurnIxArgs): Promise<Instruction> {
+    const tokenData = await this.account.fetchToken(args.token);
+    const manager = this.resolveTokenManager(tokenData.data);
+    const tokenProgram = resolveTokenProgram(tokenData.data.config.tokenProgram);
+    const collateralTokenProgram = resolveTokenProgram(tokenData.data.collateral.tokenProgram);
+    const requestData = await this.program.account.asyncBurnRequest.fetch(args.request);
+    const user = requestData.header.user.toBase58() as Address;
+    const payer = requestData.header.payer.toBase58() as Address;
+    const epochData = await this.program.account.redemptionEpoch.fetch(args.redemptionEpoch);
+    const epochRentRecipient = epochData.header.payer.equals(PublicKey.default)
+      ? manager
+      : (epochData.header.payer.toBase58() as Address);
+    const isNativeSolCollateral = tokenData.collateralMint === mints.get("SOL")?.address;
+    const requestTokenAccount = await getAtaAddress(tokenData.mint, args.request, tokenProgram);
+    const userCollateralAccount = isNativeSolCollateral
+      ? null
+      : await getAtaAddress(tokenData.collateralMint, user, collateralTokenProgram);
+    const requestCollateralAccount = isNativeSolCollateral
+      ? await getAtaAddress(tokenData.collateralMint, args.request, collateralTokenProgram)
+      : null;
+    const collateralTokenAccount = await getAtaAddress(
+      tokenData.collateralMint,
+      args.token,
+      collateralTokenProgram
+    );
+
+    return this.program.methods
+      .processAsyncBurn()
+      .accountsPartial({
+        manager,
+        payer,
+        token: args.token,
+        redemptionEpoch: args.redemptionEpoch,
+        request: args.request,
+        user,
+        mint: tokenData.mint,
+        requestTokenAccount,
+        collateralMint: tokenData.collateralMint,
+        userCollateralAccount,
+        requestCollateralAccount,
+        collateralTokenAccount,
+        epochRentRecipient,
+        tokenProgram,
+        collateralTokenProgram,
+      })
+      .instruction()
+      .then(toKitInstruction);
+  }
+}