@kestrelfi/lyc-sdk 1.0.1

package/src/client/builders/claimIncentivesBuilder.ts

@@ -0,0 +1,211 @@
+import type { Address, Instruction } from "@solana/kit";
+import type { LongYieldCarryTransactionPlan } from "../types";
+import { LongYieldCarryBuilderBase } from "./base";
+import type { ClaimIncentivesIxArgs, ClaimIncentivesTxArgs } from "./args";
+import {
+  type AnchorOracleType,
+  LendingPlatform,
+  createMultiCpiRefs,
+  fromWeb3Pk,
+  getAtaAddress,
+  getCreateAtaInstructions,
+  getCreateAtaIxIfNeeded,
+  mints,
+  resolveTokenProgram,
+  toKitInstruction,
+  toWeb3AccountMeta,
+} from "common";
+import { PYTH_FEEDS } from "oracle";
+import { TOKEN_PROGRAM_ADDRESS } from "@solana-program/token";
+import { getTokenCacheInvalidation, getYieldingBankCacheInvalidation } from "../../utils";
+import { RefreshYieldingBankBuilder } from "./refreshYieldingBankBuilder";
+import type { TokenAccountData } from "../../models/lycToken";
+
+export class ClaimIncentivesBuilder extends LongYieldCarryBuilderBase<
+  ClaimIncentivesIxArgs,
+  ClaimIncentivesTxArgs
+> {
+  async getIx(args: ClaimIncentivesIxArgs): Promise<Instruction> {
+    const tokenData = await this.account.fetchToken(args.token);
+    const tokenIncentiveAta = await getAtaAddress(
+      args.params.expectedIncentiveMint,
+      args.token,
+      args.params.incentiveTokenProgram
+    );
+    const yieldingBankIncentiveAta = args.params.yieldingBank
+      ? await getAtaAddress(
+          args.params.expectedIncentiveMint,
+          args.params.yieldingBank,
+          args.params.incentiveTokenProgram
+        )
+      : null;
+    const feeWallet = args.params.feeWallet ?? this.resolveTokenCuratorFeeWallet(tokenData.data);
+    const feeWalletIncentiveAta = await getAtaAddress(
+      args.params.expectedIncentiveMint,
+      feeWallet,
+      args.params.incentiveTokenProgram
+    );
+
+    return this.program.methods
+      .claimIncentives({
+        prerequisiteCpis: args.params.prerequisiteCpis ?? null,
+        tokenIxRefs: args.params.tokenIxRefs,
+        lendingPositionIndex: args.params.lendingPositionIndex,
+        incentiveOracleType: args.params.incentiveOracleType,
+      })
+      .accountsPartial({
+        manager: this.resolveTokenManager(tokenData.data),
+        token: args.token,
+        yieldingBank: args.params.yieldingBank ?? null,
+        expectedIncentiveMint: args.params.expectedIncentiveMint,
+        tokenIncentiveAta,
+        yieldingBankIncentiveAta: yieldingBankIncentiveAta ?? null,
+        incentiveOracle: args.params.incentiveOracle ?? null,
+        feeWallet,
+        feeWalletIncentiveAta,
+        incentiveTokenProgram: args.params.incentiveTokenProgram,
+      })
+      .remainingAccounts(args.params.remainingAccounts.map(toWeb3AccountMeta))
+      .instruction()
+      .then(toKitInstruction);
+  }
+
+  async getTx(args: ClaimIncentivesTxArgs): Promise<LongYieldCarryTransactionPlan> {
+    const tokenData = await this.account.fetchToken(args.token, { fresh: true });
+    const manager = this.resolveTokenManager(tokenData.data);
+    const position = tokenData.data.lendingPositions[args.params.lendingPositionIndex];
+    const lpClients = this.lendingPlatformClients;
+    const lpClient = this.getLendingPlatformClient(position);
+    const positionPlatform = lpClients.getPlatformForPosition(position);
+    if (positionPlatform !== LendingPlatform.Kamino) {
+      throw new Error(`Unsupported lending platform for claim_incentives: ${positionPlatform}`);
+    }
+
+    const yieldingBank =
+      args.params.yieldingBank ?? (await tokenData.resolveFirstYieldingBankAddress(this.pda));
+
+    const debtMint = fromWeb3Pk(position.accounting.debt.mint);
+    const isDebtMintIncentive = args.params.incentiveMint === debtMint;
+    const incentiveTokenProgram = isDebtMintIncentive
+      ? resolveTokenProgram(position.accounting.debt.tokenProgram)
+      : (mints.get(args.params.incentiveMint)?.tokenProgram ?? TOKEN_PROGRAM_ADDRESS);
+
+    const { incentiveOracle, incentiveOracleType } = this.resolveIncentiveOracle(
+      tokenData.data,
+      args.params
+    );
+
+    let claimAccounts = args.params.claimAccounts;
+    if (!claimAccounts) {
+      const matchingIncentives = (
+        await lpClient.getOutstandingIncentives(fromWeb3Pk(position.protocolUserAcc))
+      ).filter((incentive) => incentive.mint === args.params.incentiveMint);
+      if (matchingIncentives.length !== 1 || !matchingIncentives[0].claimAccounts) {
+        throw new Error(
+          `Unable to resolve claim accounts for incentive mint ${args.params.incentiveMint}` +
+            ` (found ${matchingIncentives.length} matching farm(s));` +
+            ` pass claimAccounts explicitly to disambiguate`
+        );
+      }
+      claimAccounts = matchingIncentives[0].claimAccounts;
+    }
+
+    const kaminoClient = lpClients.getByPlatform(LendingPlatform.Kamino);
+    const claimCpiData = await kaminoClient.ix.getClaimIncentiveCpiData(
+      args.token,
+      manager,
+      fromWeb3Pk(position.pool),
+      fromWeb3Pk(position.collateralReserve),
+      fromWeb3Pk(position.protocolUserAcc),
+      claimAccounts.farm,
+      claimAccounts.userFarm,
+      args.params.incentiveMint
+    );
+
+    const {
+      accounts: remainingAccounts,
+      refsGroups,
+      lookupTables,
+    } = createMultiCpiRefs([claimCpiData]);
+    const tokenIxRefs = refsGroups[0];
+    const { instructions: ataCreationIxs, postSuccessCacheInvalidations } =
+      await getCreateAtaInstructions(this.rpc, manager, remainingAccounts);
+
+    const { instruction: createYbAtaIx, postSuccessCacheInvalidations: ybAtaCacheInv } =
+      await getCreateAtaIxIfNeeded(
+        this.rpc,
+        manager,
+        args.params.incentiveMint,
+        yieldingBank,
+        incentiveTokenProgram
+      );
+
+    const refreshYieldingBankPlan = await new RefreshYieldingBankBuilder(this.context).getTx({
+      signer: manager,
+      yieldingBank,
+    });
+
+    return {
+      instructions: [
+        ...ataCreationIxs,
+        ...(createYbAtaIx ? [createYbAtaIx] : []),
+        ...refreshYieldingBankPlan.instructions,
+        await this.getIx({
+          token: args.token,
+          params: {
+            tokenIxRefs,
+            lendingPositionIndex: args.params.lendingPositionIndex,
+            yieldingBank,
+            expectedIncentiveMint: args.params.incentiveMint,
+            incentiveTokenProgram,
+            incentiveOracle,
+            incentiveOracleType,
+            feeWallet: this.resolveTokenCuratorFeeWallet(tokenData.data),
+            remainingAccounts,
+          },
+        }),
+      ],
+      lookupTables: this.getTxLookupTables(args.token, lookupTables ?? []),
+      postSuccessCacheInvalidations: [
+        ...postSuccessCacheInvalidations,
+        ...ybAtaCacheInv,
+        getTokenCacheInvalidation(args.token),
+        getYieldingBankCacheInvalidation(yieldingBank),
+      ],
+    };
+  }
+
+  private resolveIncentiveOracle(
+    tokenData: TokenAccountData,
+    params: ClaimIncentivesTxArgs["params"]
+  ): { incentiveOracle: Address; incentiveOracleType: AnchorOracleType } {
+    for (const lp of tokenData.lendingPositions) {
+      const debtMint = fromWeb3Pk(lp.accounting.debt.mint);
+      if (debtMint !== params.incentiveMint) continue;
+      return {
+        incentiveOracle: fromWeb3Pk(lp.accounting.debt.oracle),
+        incentiveOracleType: lp.accounting.debt.oracleType,
+      };
+    }
+
+    if (params.incentiveOracle && params.incentiveOracleType) {
+      return {
+        incentiveOracle: params.incentiveOracle,
+        incentiveOracleType: params.incentiveOracleType,
+      };
+    }
+
+    const symbol = mints.get(params.incentiveMint)?.symbol;
+    const pythFeed = symbol ? PYTH_FEEDS[symbol as keyof typeof PYTH_FEEDS] : undefined;
+    if (pythFeed) {
+      return {
+        incentiveOracle: pythFeed.account,
+        incentiveOracleType: { pyth: {} },
+      };
+    }
+
+    throw new Error(
+      `claim_incentives: cannot auto-resolve oracle for incentive mint ${params.incentiveMint}; pass incentiveOracle and incentiveOracleType explicitly`
+    );
+  }
+}

package/src/client/builders/collectFeesBuilder.ts

@@ -0,0 +1,52 @@
+import type { Address, Instruction } from "@solana/kit";
+import { fromWeb3Pk, getAtaAddress, resolveTokenProgram, toKitInstruction } from "common";
+import { PROTOCOL_ADMIN } from "../../constants/general";
+import { LongYieldCarrySingleInstructionBuilderService } from "./base";
+import type { CollectFeesIxArgs } from "./args";
+
+/**
+ * Collects pending fees for either the curator or the protocol. The caller
+ * passes the `authority` signer. If it is `PROTOCOL_ADMIN`, the protocol bucket and
+ * protocol fee wallet are used (even when that address is also the token curator).
+ * Otherwise, if it is the curator only, the curator bucket and curator fee wallet are used.
+ * Throws client-side if the signer matches neither role (mirroring the on-chain check).
+ */
+export class CollectFeesBuilder extends LongYieldCarrySingleInstructionBuilderService<CollectFeesIxArgs> {
+  async getIx(args: CollectFeesIxArgs): Promise<Instruction> {
+    const tokenData = await this.account.fetchToken(args.token);
+    const mint = tokenData.mint;
+    const tokenProgram = resolveTokenProgram(tokenData.data.config.tokenProgram);
+
+    const curator = fromWeb3Pk(tokenData.data.roles.curator);
+    const protocolAdmin = PROTOCOL_ADMIN[this.environment];
+    let feeWallet: Address;
+    if (args.authority === curator) {
+      feeWallet = this.resolveTokenCuratorFeeWallet(tokenData.data);
+    } else if (args.authority === protocolAdmin) {
+      feeWallet = this.protocolFeeWallet;
+    } else {
+      throw new Error(
+        `collectFees: authority ${args.authority} is neither the token's curator ` +
+          `(${curator}) nor PROTOCOL_ADMIN (${protocolAdmin})`
+      );
+    }
+    const feeWalletTokenAccount = await getAtaAddress(mint, feeWallet, tokenProgram);
+
+    return this.program.methods
+      .collectFees()
+      .accountsPartial({
+        authority: args.authority,
+        token: args.token,
+        mint,
+        feeWallet,
+        feeWalletTokenAccount,
+        tokenProgram,
+      })
+      .instruction()
+      .then(toKitInstruction);
+  }
+
+  protected async buildLookupTables(args: CollectFeesIxArgs): Promise<readonly Address[]> {
+    return this.getTxLookupTables(args.token);
+  }
+}

package/src/client/builders/collectInterestBuilder.ts

@@ -0,0 +1,165 @@
+import type { Instruction } from "@solana/kit";
+import type { LongYieldCarryTransactionPlan } from "../types";
+import { LongYieldCarryBuilderBase } from "./base";
+import type { CollectInterestIxArgs, CollectInterestTxArgs } from "./args";
+import {
+  assertCollectInterestPlanHasPositiveRedemptions,
+  buildCollectInterestPlan,
+} from "../plans/collectInterest";
+import { buildCollectInterestRoutePlan } from "../routes/collectInterest";
+import {
+  createCpiRefs,
+  fromWeb3Pk,
+  getAtaAddress,
+  getCreateAtaInstructions,
+  getCreateAtaIxIfNeeded,
+  resolveTokenProgram,
+  toKitInstruction,
+  toWeb3AccountMeta,
+} from "common";
+export class CollectInterestBuilder extends LongYieldCarryBuilderBase<
+  CollectInterestIxArgs,
+  CollectInterestTxArgs
+> {
+  async getIx(args: CollectInterestIxArgs): Promise<Instruction> {
+    const tokenData = await this.account.fetchToken(args.token);
+    const collateralMint = fromWeb3Pk(tokenData.data.collateral.mint);
+    const collateralOracle = fromWeb3Pk(tokenData.data.collateral.oracle);
+    const secondaryCollateralOracle = this.resolveOptionalSecondaryCollateralOracle(
+      tokenData.data.collateral
+    );
+    const collateralTokenProgram = resolveTokenProgram(tokenData.data.collateral.tokenProgram);
+    const { redemption } = args.params;
+    const collateralTokenAccount = await getAtaAddress(
+      collateralMint,
+      args.token,
+      collateralTokenProgram
+    );
+    const ybCollateralTokenAccount = await getAtaAddress(
+      collateralMint,
+      args.yieldingBank,
+      collateralTokenProgram
+    );
+    const ybRedemptionTokenAccount = await getAtaAddress(
+      redemption.mint,
+      args.yieldingBank,
+      redemption.tokenProgram
+    );
+    const curatorFeeWallet = this.resolveTokenCuratorFeeWallet(tokenData.data);
+    const protocolFeeWallet = this.protocolFeeWallet;
+    const curatorFeeWalletCollateralAccount = await getAtaAddress(
+      collateralMint,
+      curatorFeeWallet,
+      collateralTokenProgram
+    );
+    const protocolFeeWalletCollateralAccount = await getAtaAddress(
+      collateralMint,
+      protocolFeeWallet,
+      collateralTokenProgram
+    );
+
+    return this.program.methods
+      .collectInterest(args.params.refs)
+      .accountsPartial({
+        manager: this.resolveTokenManager(tokenData.data),
+        token: args.token,
+        yieldingBank: args.yieldingBank,
+        collateralMint,
+        collateralOracle,
+        secondaryCollateralOracle,
+        redemptionOracle: redemption.oracle,
+        collateralTokenAccount,
+        ybCollateralTokenAccount,
+        ybRedemptionTokenAccount,
+        curatorFeeWalletCollateralAccount,
+        protocolFeeWalletCollateralAccount,
+        collateralTokenProgram,
+      })
+      .remainingAccounts(args.params.remainingAccounts.map(toWeb3AccountMeta))
+      .instruction()
+      .then(toKitInstruction);
+  }
+
+  async getTx(args: CollectInterestTxArgs): Promise<LongYieldCarryTransactionPlan> {
+    const plan = await buildCollectInterestPlan(this.account, args.token, args.params);
+    assertCollectInterestPlanHasPositiveRedemptions(plan);
+    const executionPlan = await buildCollectInterestRoutePlan(
+      this.swap,
+      plan,
+      args.params,
+      args.manager
+    );
+    const { collateral, redemption, cpiData } = executionPlan;
+    const {
+      accounts: remainingAccounts,
+      refs,
+      lookupTables,
+    } = createCpiRefs(cpiData, {
+      initialAccounts: [],
+    });
+    const tokenData = await this.account.fetchToken(args.token);
+    const {
+      instruction: ybCollateralAtaIx,
+      postSuccessCacheInvalidations: ybCollateralAtaCacheInv,
+    } = await getCreateAtaIxIfNeeded(
+      this.rpc,
+      args.manager,
+      collateral.mint,
+      args.params.yieldingBank,
+      collateral.tokenProgram
+    );
+    const curatorFeeWallet = this.resolveTokenCuratorFeeWallet(tokenData.data);
+    const protocolFeeWallet = this.protocolFeeWallet;
+    const {
+      instruction: curatorPerfFeeAtaIx,
+      postSuccessCacheInvalidations: curatorPerfFeeAtaCacheInv,
+    } = await getCreateAtaIxIfNeeded(
+      this.rpc,
+      args.manager,
+      collateral.mint,
+      curatorFeeWallet,
+      collateral.tokenProgram
+    );
+    const {
+      instruction: protocolPerfFeeAtaIx,
+      postSuccessCacheInvalidations: protocolPerfFeeAtaCacheInv,
+    } = await getCreateAtaIxIfNeeded(
+      this.rpc,
+      args.manager,
+      collateral.mint,
+      protocolFeeWallet,
+      collateral.tokenProgram
+    );
+    const { instructions, postSuccessCacheInvalidations } = await getCreateAtaInstructions(
+      this.rpc,
+      args.manager,
+      remainingAccounts
+    );
+
+    return {
+      instructions: [
+        ...executionPlan.preInstructions,
+        ...(ybCollateralAtaIx ? [ybCollateralAtaIx] : []),
+        ...(curatorPerfFeeAtaIx ? [curatorPerfFeeAtaIx] : []),
+        ...(protocolPerfFeeAtaIx ? [protocolPerfFeeAtaIx] : []),
+        ...instructions,
+        await this.getIx({
+          token: args.token,
+          yieldingBank: args.params.yieldingBank,
+          params: {
+            redemption,
+            refs,
+            remainingAccounts,
+          },
+        }),
+      ],
+      lookupTables: this.getTxLookupTables(args.token, lookupTables ?? []),
+      postSuccessCacheInvalidations: [
+        ...ybCollateralAtaCacheInv,
+        ...curatorPerfFeeAtaCacheInv,
+        ...protocolPerfFeeAtaCacheInv,
+        ...postSuccessCacheInvalidations,
+      ],
+    };
+  }
+}

package/src/client/builders/createCpiPlanBuilder.ts

@@ -0,0 +1,21 @@
+import type { Instruction } from "@solana/kit";
+import { toKitInstruction, toWeb3Pk } from "common";
+import { LongYieldCarrySingleInstructionBuilderService } from "./base";
+import type { CreateCpiPlanIxArgs } from "./args";
+
+export class CreateCpiPlanBuilder extends LongYieldCarrySingleInstructionBuilderService<CreateCpiPlanIxArgs> {
+  async getIx(args: CreateCpiPlanIxArgs): Promise<Instruction> {
+    return this.program.methods
+      .createCpiPlan({
+        uniqueId: toWeb3Pk(args.params.uniqueId),
+        createdTs: args.params.createdTs,
+        refs: args.params.refs,
+      })
+      .accountsPartial({
+        manager: args.manager,
+        cpiPlan: args.cpiPlan,
+      })
+      .instruction()
+      .then(toKitInstruction);
+  }
+}

package/src/client/builders/createTokenBuilder.ts

@@ -0,0 +1,73 @@
+import { BN } from "@anchor-lang/core";
+import type { Address, Instruction } from "@solana/kit";
+import { TOKEN_PROGRAM_ADDRESS } from "@solana-program/token";
+import { getAtaAddress, toKitInstruction, toWeb3Pk } from "common";
+import { PROTOCOL_ADMIN } from "../../constants/general";
+import { LongYieldCarrySingleInstructionBuilderService } from "./base";
+import type { CreateTokenIxArgs } from "./args";
+
+const DEFAULT_FEE_DRIP_MAX_APY_BPS = 200;
+const DEFAULT_FEE_DRIP_DURATION_SECS = 3 * 24 * 60 * 60;
+
+export class CreateTokenBuilder extends LongYieldCarrySingleInstructionBuilderService<CreateTokenIxArgs> {
+  async getIx(args: CreateTokenIxArgs): Promise<Instruction> {
+    const [tokenPda] = await this.pda.deriveTokenPda(args.mint, args.params.id);
+    const tokenProgram = args.tokenProgram ?? TOKEN_PROGRAM_ADDRESS;
+    const collateralTokenProgram = args.collateralTokenProgram ?? TOKEN_PROGRAM_ADDRESS;
+    // Keep local omission behavior unchanged for existing tests. Deployed
+    // environments default to a capped three-day release schedule.
+    const defaultFeeDripMaxApyBps = this.environment === "local" ? 0 : DEFAULT_FEE_DRIP_MAX_APY_BPS;
+    const defaultFeeDripDurationSecs =
+      this.environment === "local" ? 0 : DEFAULT_FEE_DRIP_DURATION_SECS;
+    const collateralTokenAccount = await getAtaAddress(
+      args.collateralMint,
+      tokenPda,
+      collateralTokenProgram
+    );
+
+    const curator = args.curator ?? PROTOCOL_ADMIN[this.environment];
+
+    return this.program.methods
+      .createToken({
+        id: args.params.id,
+        interestDistribution: args.params.interestDistribution,
+        oracleConfig: {
+          oracle: toWeb3Pk(args.params.oracleConfig.oracle),
+          oracleType: args.params.oracleConfig.oracleType,
+          secondaryOracle: args.params.oracleConfig.secondaryOracle
+            ? toWeb3Pk(args.params.oracleConfig.secondaryOracle)
+            : null,
+        },
+        feeConfig: {
+          performanceFeeBps: args.params.feeConfig.performanceFeeBps,
+          mintingFeeBps: args.params.feeConfig.mintingFeeBps,
+          burningFeeBps: args.params.feeConfig.burningFeeBps,
+          protocolMintBurnPctBps: args.params.feeConfig.protocolMintBurnPctBps,
+          curatorMintBurnPctBps: args.params.feeConfig.curatorMintBurnPctBps,
+          curatorPerfPctBps: args.params.feeConfig.curatorPerfPctBps,
+          feeDripMaxApyBps: args.params.feeConfig.feeDripMaxApyBps ?? defaultFeeDripMaxApyBps,
+          feeDripDurationSecs:
+            args.params.feeConfig.feeDripDurationSecs ?? new BN(defaultFeeDripDurationSecs),
+        },
+      })
+      .accountsPartial({
+        curator,
+        adminRole: args.adminRole ?? null,
+        managerRole: args.managerRole ?? null,
+        feesRole: args.feesRole ?? null,
+        cbControllerRole: args.cbControllerRole ?? null,
+        token: tokenPda,
+        mint: args.mint,
+        collateralMint: args.collateralMint,
+        collateralTokenAccount,
+        tokenProgram,
+        collateralTokenProgram,
+      })
+      .instruction()
+      .then(toKitInstruction);
+  }
+
+  protected async buildLookupTables(): Promise<readonly Address[]> {
+    return this.getTxLookupTables();
+  }
+}