@kestrelfi/lyc-sdk 1.0.1

package/src/client/builders/base.ts

@@ -0,0 +1,303 @@
+import type { Address, Instruction } from "@solana/kit";
+import type { BN } from "@anchor-lang/core";
+import { PublicKey } from "@solana/web3.js";
+import {
+  BaseIXBuilderService,
+  accountExists,
+  createSignerFromAddress,
+  fromWeb3Pk,
+  getCreateAtaIxIfNeeded,
+  getWrapSolInstructions,
+  mints,
+} from "common";
+import type {
+  LendingOperationCpiBundle,
+  LendingOperationParams,
+  RepayOperationParams,
+} from "lending-platforms";
+import { mergeLycLookupTables } from "../../utils";
+import type { TokenAccountData, TokenLendingPositionData } from "../../models/lycToken";
+import type { YieldingBankAccountData } from "../../models/yieldingBank";
+import {
+  CIRCUIT_BREAKER_CONTROLLER,
+  MANAGER,
+  PROGRAM_ID,
+  PROTOCOL_ADMIN,
+  PROTOCOL_FEE_WALLET,
+} from "../../constants/general";
+import type { LongYieldCarryBuilderContext } from "../types/builders";
+import type { LongYieldCarryTransactionPlan } from "../types";
+
+export abstract class LongYieldCarryBuilderBase<
+  TIxArgs,
+  TTxArgs = TIxArgs,
+  TTxResult = LongYieldCarryTransactionPlan,
+> extends BaseIXBuilderService<LongYieldCarryBuilderContext, TIxArgs, TTxArgs, TTxResult> {
+  protected get rpc() {
+    return this.context.rpc;
+  }
+
+  protected get program() {
+    return this.context.program;
+  }
+
+  protected get account() {
+    return this.context.account;
+  }
+
+  protected get pda() {
+    return this.context.pda;
+  }
+
+  protected get swap() {
+    return this.context.swap;
+  }
+
+  protected get externalLiquidityResolver() {
+    return this.context.externalLiquidityResolver;
+  }
+
+  protected get environment() {
+    return this.context.environment;
+  }
+
+  protected get lendingPlatformClients() {
+    return this.context.lendingPlatformClients;
+  }
+
+  /**
+   * Environment-level manager fallback. Use {@link resolveTokenManager} /
+   * {@link resolveYieldingBankManager} whenever a specific token/bank's role
+   * might override the default.
+   */
+  private get manager() {
+    return MANAGER[this.environment];
+  }
+
+  /**
+   * Environment-level circuit-breaker-controller fallback. Use
+   * {@link resolveTokenCbController} / {@link resolveYieldingBankCbController}
+   * whenever a specific token/bank's role might override the default.
+   */
+  private get circuitBreakerController() {
+    return CIRCUIT_BREAKER_CONTROLLER[this.environment];
+  }
+
+  /**
+   * Program-level admin. Also doubles as the environment-level fallback for
+   * `TokenRoles::admin()` / `YieldingBankRoles::admin()` when their stored role
+   * is unset — both Rust fallbacks resolve to this same pubkey by design.
+   */
+  private get protocolAdmin() {
+    return PROTOCOL_ADMIN[this.environment];
+  }
+
+  /**
+   * Program-level fee wallet. Also doubles as the fallback for
+   * `TokenRoles::curator_fee_wallet()` when a token's `roles.fees` is unset —
+   * the Rust `curator_fee_wallet()` getter delegates to `protocol_fee_wallet()`.
+   */
+  protected get protocolFeeWallet() {
+    return PROTOCOL_FEE_WALLET[this.environment];
+  }
+
+  /** Program ID for this environment — used as the "no-change"/"use-default" sentinel on role accounts. */
+  protected get programId() {
+    return PROGRAM_ID[this.environment];
+  }
+
+  /**
+   * Return the on-chain role key if it's set, otherwise the environment
+   * fallback. Mirrors the Rust role getter pattern (`if self.role != default()
+   * { self.role } else { <env default> }`).
+   */
+  private resolveStoredOrFallback(stored: PublicKey, fallback: Address): Address {
+    return stored.equals(PublicKey.default) ? fallback : fromWeb3Pk(stored);
+  }
+
+  protected resolveTokenAdmin(tokenData: TokenAccountData): Address {
+    return this.resolveStoredOrFallback(tokenData.roles.admin, this.protocolAdmin);
+  }
+
+  protected resolveTokenManager(tokenData: TokenAccountData): Address {
+    return this.resolveStoredOrFallback(tokenData.roles.manager, this.manager);
+  }
+
+  protected resolveTokenCuratorFeeWallet(tokenData: TokenAccountData): Address {
+    return this.resolveStoredOrFallback(tokenData.roles.fees, this.protocolFeeWallet);
+  }
+
+  protected resolveTokenCbController(tokenData: TokenAccountData): Address {
+    return this.resolveStoredOrFallback(
+      tokenData.roles.cbController,
+      this.circuitBreakerController
+    );
+  }
+
+  /**
+   * Optional composite collateral oracle (e.g. SPL stake pool for PythSplStake).
+   * Anchor optional accounts must be passed as `null` when unset.
+   */
+  protected resolveOptionalSecondaryCollateralOracle(
+    collateral: TokenAccountData["collateral"]
+  ): Address | null {
+    return collateral.secondaryOracle.equals(PublicKey.default)
+      ? null
+      : fromWeb3Pk(collateral.secondaryOracle);
+  }
+
+  protected resolveYieldingBankAdmin(bankData: YieldingBankAccountData): Address {
+    return this.resolveStoredOrFallback(bankData.roles.admin, this.protocolAdmin);
+  }
+
+  protected resolveYieldingBankManager(bankData: YieldingBankAccountData): Address {
+    return this.resolveStoredOrFallback(bankData.roles.manager, this.manager);
+  }
+
+  protected resolveYieldingBankCbController(bankData: YieldingBankAccountData): Address {
+    return this.resolveStoredOrFallback(bankData.roles.cbController, this.circuitBreakerController);
+  }
+
+  protected getTxLookupTables(
+    tokenPda?: Address | readonly Address[],
+    existingLookupTables?: readonly Address[]
+  ): Address[] {
+    return mergeLycLookupTables(this.context.environment, tokenPda, existingLookupTables);
+  }
+
+  protected getLendingPlatformClient(position: TokenLendingPositionData) {
+    return this.lendingPlatformClients.getForPosition(position);
+  }
+
+  protected async getCreateUserCollateralAtaIxIfNeeded(
+    owner: Address,
+    collateralMint: Address,
+    collateralTokenProgram: Address
+  ) {
+    return getCreateAtaIxIfNeeded(this.rpc, owner, collateralMint, owner, collateralTokenProgram, {
+      accountClient: this.account,
+    });
+  }
+
+  protected async getWrapSolInstructionsIfMintIsSol(
+    owner: Address,
+    mint: Address,
+    lamports: BN
+  ): Promise<{
+    instructions?: Instruction[];
+    postSuccessCacheInvalidations?: LongYieldCarryTransactionPlan["postSuccessCacheInvalidations"];
+  }> {
+    const solMint = mints.get("SOL");
+    if (!solMint || mint !== solMint.address) {
+      return {};
+    }
+
+    const wrap = await getWrapSolInstructions(
+      this.rpc,
+      owner,
+      createSignerFromAddress(owner),
+      lamports,
+      { accountClient: this.account }
+    );
+    return {
+      instructions: wrap.instructions,
+      postSuccessCacheInvalidations: wrap.postSuccessCacheInvalidations,
+    };
+  }
+
+  protected async getLendingOperationCpiData(
+    token: Address,
+    manager: Address,
+    position: TokenLendingPositionData,
+    txId: string,
+    operation: "deposit" | "withdraw" | "borrow" | "repay",
+    uiAmount?: number | "all"
+  ): Promise<LendingOperationCpiBundle> {
+    const lpClient = this.getLendingPlatformClient(position);
+    const pool = fromWeb3Pk(position.pool);
+    const userAccount = fromWeb3Pk(position.protocolUserAcc);
+    const reserve =
+      operation === "deposit" || operation === "withdraw"
+        ? fromWeb3Pk(position.collateralReserve)
+        : fromWeb3Pk(position.debtReserve);
+
+    const operationParams = {
+      user: token,
+      payer: manager,
+      pool,
+      reserve,
+      userAccount,
+      uiAmount,
+      txId,
+    } satisfies LendingOperationParams;
+
+    if (operation === "deposit") {
+      return lpClient.ix.getDepositCpiBundle(operationParams);
+    }
+
+    if (operation === "borrow") {
+      const needsInit = !(await accountExists(this.rpc, userAccount));
+      return needsInit
+        ? lpClient.ix.getInitBorrowPositionCpiBundle(
+            operationParams,
+            fromWeb3Pk(position.collateralReserve)
+          )
+        : lpClient.ix.getBorrowCpiBundle(operationParams);
+    }
+
+    if (operation === "withdraw") {
+      return lpClient.ix.getWithdrawCpiBundle(operationParams);
+    }
+
+    if (uiAmount === "all") {
+      throw new Error('The "all" amount sentinel is only valid for withdrawals');
+    }
+    const repayParams: RepayOperationParams = { ...operationParams, uiAmount };
+    return lpClient.ix.getRepayCpiBundle(repayParams);
+  }
+}
+
+export abstract class LongYieldCarrySingleInstructionBuilderService<
+  TIxArgs,
+  TTxArgs = TIxArgs,
+  TTxPlan extends LongYieldCarryTransactionPlan = LongYieldCarryTransactionPlan,
+> extends LongYieldCarryBuilderBase<TIxArgs, TTxArgs, TTxPlan> {
+  protected async deriveIxArgs(txArgs: TTxArgs): Promise<TIxArgs> {
+    return txArgs as unknown as TIxArgs;
+  }
+
+  protected async buildPreambleInstructions(
+    _args: TIxArgs,
+    _txArgs: TTxArgs
+  ): Promise<Instruction[]> {
+    return [];
+  }
+
+  protected async buildLookupTables(
+    _args: TIxArgs,
+    _txArgs: TTxArgs
+  ): Promise<readonly Address[] | undefined> {
+    return undefined;
+  }
+
+  protected async buildPlanExtras(
+    _args: TIxArgs,
+    _txArgs: TTxArgs
+  ): Promise<Omit<TTxPlan, "instructions" | "lookupTables"> | undefined> {
+    return undefined;
+  }
+
+  async getTx(txArgs: TTxArgs): Promise<TTxPlan> {
+    const args = await this.deriveIxArgs(txArgs);
+    const preambleInstructions = await this.buildPreambleInstructions(args, txArgs);
+    const instruction = await this.getIx(args);
+    const lookupTables = await this.buildLookupTables(args, txArgs);
+    const extras = await this.buildPlanExtras(args, txArgs);
+
+    return {
+      instructions: [...preambleInstructions, instruction],
+      ...(lookupTables?.length ? { lookupTables: [...lookupTables] } : {}),
+      ...(extras ?? {}),
+    } as TTxPlan;
+  }
+}

package/src/client/builders/burnTokenBuilder.ts

@@ -0,0 +1,258 @@
+import { BN } from "@anchor-lang/core";
+import type { Instruction } from "@solana/kit";
+import { SYSTEM_PROGRAM_ADDRESS } from "@solana-program/system";
+import { ASSOCIATED_TOKEN_PROGRAM_ADDRESS } from "@solana-program/token";
+import {
+  createSignerFromAddress,
+  fetchSplTokenAccountAmounts,
+  getAtaAddress,
+  getUnwrapSolInstruction,
+  mints,
+  resolveTokenProgram,
+  toKitInstruction,
+  type TransactionCacheInvalidation,
+} from "common";
+import { AMOUNT_ALL_SENTINEL } from "../../constants/general";
+import type { LYCToken } from "../../models/lycToken";
+import { currentEpochId, getTokenCacheInvalidation } from "../../utils";
+import type { LongYieldCarryTransactionPlan } from "../types";
+import type { BurnTokenIxArgs, BurnTokenTxArgs } from "./args";
+import { LongYieldCarryBuilderBase } from "./base";
+import { getRefreshTokenInstructionsIfStale } from "./utils";
+
+export interface BundledBurnPlan {
+  instructions?: Instruction[];
+  [key: string]: unknown;
+}
+
+type ResolvedBurnTokenTxArgs = Omit<BurnTokenTxArgs, "params"> & {
+  params: Omit<BurnTokenTxArgs["params"], "burnAmount"> & { burnAmount: BN | number };
+  ixBurnAmount: BN;
+};
+
+type BurnTokenAsyncAccounts = {
+  epochId: BN | number;
+  requestSequence: BN | number;
+  redemptionEpoch: BurnTokenIxArgs["token"];
+  request: BurnTokenIxArgs["token"];
+  requestTokenAccount: BurnTokenIxArgs["token"];
+};
+
+export class BurnTokenBuilder extends LongYieldCarryBuilderBase<BurnTokenIxArgs, BurnTokenTxArgs> {
+  async getIx(args: BurnTokenIxArgs): Promise<Instruction> {
+    const tokenData = await this.account.fetchToken(args.token);
+    const mint = tokenData.mint;
+    const collateralMint = tokenData.collateralMint;
+    const tokenProgram = resolveTokenProgram(tokenData.data.config.tokenProgram);
+    const collateralTokenProgram = resolveTokenProgram(tokenData.data.collateral.tokenProgram);
+    const userTokenAccount = await getAtaAddress(mint, args.signer, tokenProgram);
+    const userCollateralAccount = await getAtaAddress(
+      collateralMint,
+      args.signer,
+      collateralTokenProgram
+    );
+    const collateralTokenAccount = await getAtaAddress(
+      collateralMint,
+      args.token,
+      collateralTokenProgram
+    );
+    const asyncAccounts = await this.resolveAsyncAccounts(args, mint, tokenProgram);
+
+    const burnIxArgs = asyncAccounts
+      ? {
+          async: {
+            burnAmount: new BN(args.params.burnAmount.toString()),
+            epochId: new BN(asyncAccounts.epochId.toString()),
+            requestSequence: new BN(asyncAccounts.requestSequence.toString()),
+          },
+        }
+      : {
+          sync: {
+            burnAmount: new BN(args.params.burnAmount.toString()),
+          },
+        };
+
+    return this.program.methods
+      .burnToken(burnIxArgs)
+      .accountsPartial({
+        signer: args.signer,
+        payer: args.payer ?? args.signer,
+        token: args.token,
+        mint,
+        userTokenAccount,
+        collateralMint,
+        userCollateralAccount,
+        collateralTokenAccount,
+        redemptionEpoch: asyncAccounts?.redemptionEpoch ?? null,
+        request: asyncAccounts?.request ?? null,
+        requestTokenAccount: asyncAccounts?.requestTokenAccount ?? null,
+        tokenProgram,
+        collateralTokenProgram,
+        associatedTokenProgram: ASSOCIATED_TOKEN_PROGRAM_ADDRESS,
+        systemProgram: SYSTEM_PROGRAM_ADDRESS,
+      })
+      .instruction()
+      .then(toKitInstruction);
+  }
+
+  async getTx(args: BurnTokenTxArgs): Promise<LongYieldCarryTransactionPlan> {
+    const resolved = await this.resolveAllSentinel(args);
+    const tokenData = await this.account.fetchToken(args.token, { fresh: true });
+    const collateralTokenProgram = resolveTokenProgram(tokenData.data.collateral.tokenProgram);
+    const userCollateralAtaSetup = await this.getCreateUserCollateralAtaIxIfNeeded(
+      args.signer,
+      tokenData.collateralMint,
+      collateralTokenProgram
+    );
+    const refreshInstructions = await getRefreshTokenInstructionsIfStale(
+      this.context,
+      args.signer,
+      tokenData
+    );
+
+    const asyncAccounts = await this.resolveAsyncFallbackParams(args.token, {
+      epochId: args.params.epochId,
+      requestSequence: args.params.requestSequence,
+    });
+
+    const instructions: Instruction[] = [...refreshInstructions];
+    if (userCollateralAtaSetup.instruction) {
+      instructions.push(userCollateralAtaSetup.instruction);
+    }
+    instructions.push(
+      await this.getIx({
+        signer: args.signer,
+        payer: args.payer,
+        token: args.token,
+        params: {
+          burnAmount: resolved.ixBurnAmount,
+          asyncFallback: asyncAccounts,
+        },
+      })
+    );
+
+    const unwrapSolIx = await this.getUnwrapSolAfterBurnIfCollateralSol(args.signer, tokenData);
+    if (unwrapSolIx) {
+      instructions.push(unwrapSolIx);
+    }
+
+    const postSuccessCacheInvalidations: TransactionCacheInvalidation[] = [
+      ...(userCollateralAtaSetup.postSuccessCacheInvalidations ?? []),
+      getTokenCacheInvalidation(args.token),
+    ];
+    if (unwrapSolIx) {
+      const userCollateralAta = await getAtaAddress(
+        tokenData.collateralMint,
+        args.signer,
+        collateralTokenProgram
+      );
+      postSuccessCacheInvalidations.push({ client: "splAta", ata: userCollateralAta });
+    }
+
+    return {
+      instructions,
+      lookupTables: this.getTxLookupTables(args.token),
+      postSuccessCacheInvalidations,
+    };
+  }
+
+  async buildBundledBurnPlan(..._args: unknown[]): Promise<BundledBurnPlan> {
+    throw new Error("Managed burn unwind plans were removed; use async burn funding instead.");
+  }
+
+  private async resolveAllSentinel(args: BurnTokenTxArgs): Promise<ResolvedBurnTokenTxArgs> {
+    if (args.params.burnAmount !== "all") {
+      const amount = args.params.burnAmount;
+      return {
+        ...args,
+        params: { ...args.params, burnAmount: amount },
+        ixBurnAmount: new BN(amount.toString()),
+      };
+    }
+    const tokenData = await this.account.fetchToken(args.token);
+    const userTokenAta = await getAtaAddress(
+      tokenData.mint,
+      args.signer,
+      resolveTokenProgram(tokenData.data.config.tokenProgram)
+    );
+    const balances = await fetchSplTokenAccountAmounts(this.rpc, [userTokenAta]);
+    return {
+      ...args,
+      params: {
+        ...args.params,
+        burnAmount: new BN((balances.get(userTokenAta) ?? BigInt(0)).toString()),
+      },
+      ixBurnAmount: AMOUNT_ALL_SENTINEL,
+    };
+  }
+
+  private async resolveAsyncFallbackParams(
+    token: BurnTokenTxArgs["token"],
+    overrides: { epochId?: BN | number; requestSequence?: BN | number }
+  ): Promise<NonNullable<BurnTokenIxArgs["params"]["asyncFallback"]>> {
+    const epochId = overrides.epochId ?? currentEpochId();
+    const [redemptionEpoch] = await this.pda.deriveRedemptionEpochPda(
+      token,
+      BigInt(epochId.toString())
+    );
+    const requestSequence =
+      overrides.requestSequence ?? (await this.resolveNextRequestSequence(redemptionEpoch));
+    const [request] = await this.pda.deriveAsyncBurnRequestPda(
+      token,
+      BigInt(epochId.toString()),
+      BigInt(requestSequence.toString())
+    );
+    return { epochId, requestSequence, redemptionEpoch, request };
+  }
+
+  private async resolveNextRequestSequence(redemptionEpoch: BurnTokenIxArgs["token"]): Promise<BN> {
+    try {
+      const epoch = await this.program.account.redemptionEpoch.fetch(redemptionEpoch);
+      return new BN(epoch.sequencing.nextRequestSequence.toString());
+    } catch {
+      return new BN(0);
+    }
+  }
+
+  private async resolveAsyncAccounts(
+    args: BurnTokenIxArgs,
+    mint: BurnTokenIxArgs["token"],
+    tokenProgram: BurnTokenIxArgs["token"]
+  ): Promise<BurnTokenAsyncAccounts | undefined> {
+    if (!args.params.asyncFallback) {
+      return undefined;
+    }
+    const epochId = args.params.asyncFallback.epochId;
+    const requestSequence = args.params.asyncFallback.requestSequence;
+    const redemptionEpoch =
+      args.params.asyncFallback.redemptionEpoch ??
+      (await this.pda.deriveRedemptionEpochPda(args.token, BigInt(epochId.toString())))[0];
+    const request =
+      args.params.asyncFallback.request ??
+      (
+        await this.pda.deriveAsyncBurnRequestPda(
+          args.token,
+          BigInt(epochId.toString()),
+          BigInt(requestSequence.toString())
+        )
+      )[0];
+    return {
+      epochId,
+      requestSequence,
+      redemptionEpoch,
+      request,
+      requestTokenAccount: await getAtaAddress(mint, request, tokenProgram),
+    };
+  }
+
+  private async getUnwrapSolAfterBurnIfCollateralSol(
+    signer: BurnTokenTxArgs["signer"],
+    tokenData: LYCToken
+  ): Promise<Instruction | null> {
+    const solMint = mints.get("SOL");
+    if (!solMint || tokenData.collateralMint !== solMint.address) {
+      return null;
+    }
+    return getUnwrapSolInstruction(createSignerFromAddress(signer));
+  }
+}