@kestrelfi/lyc-sdk 1.0.1

package/src/client/builders/recollateralizeLossBuilder.ts

@@ -0,0 +1,367 @@
+import type { Address, Instruction } from "@solana/kit";
+import { PublicKey } from "@solana/web3.js";
+import type { LongYieldCarryTransactionPlan } from "../types";
+import { LongYieldCarryBuilderBase } from "./base";
+import type { RecollateralizeLossIxArgs, RecollateralizeLossTxArgs } from "./args";
+import { NoOpTransactionError } from "../../errors";
+import { DecreaseCarryPositionBuilder } from "./decreaseCarryPositionBuilder";
+import {
+  type SwapQuote,
+  createMultiCpiRefs,
+  fromWeb3Pk,
+  getAtaAddress,
+  getCreateAtaInstructions,
+  requestHeapFrameIx,
+  resolveTokenProgram,
+  toBigInt,
+  toKitInstruction,
+  toUiAmount,
+  toWeb3AccountMeta,
+  tvlUsdToBaseUnits,
+} from "common";
+import { getLendingUserAccountCacheInvalidation } from "lending-platforms";
+import {
+  DEFAULT_RECOLLATERALIZE_LOSS_SLIPPAGE_BPS,
+  MAX_HEAP_FRAME_BYTES,
+} from "../../constants/general";
+import { LycLendingPositionManager } from "../../services/carry";
+import { getTokenCacheInvalidation } from "../../utils";
+import type { LYCToken, TokenLendingPositionData } from "../../models/lycToken";
+
+interface RecollateralizationTarget {
+  tokenData: LYCToken;
+  totalDebtUsd: bigint;
+  totalCarryUsd: bigint;
+  lendingPositionIndex: number;
+  position: TokenLendingPositionData;
+  yieldingBank: Address;
+}
+
+interface RecollateralizationSwapPlan {
+  collateralToWithdrawUi: number;
+  repayUiAmount: number;
+  repayBaseUnits: bigint;
+  swapQuote: SwapQuote;
+}
+
+// Extra repay (bps of the measured deficit) to offset swap costs and oracle
+// drift, which also scale with the swap size. On-chain only requires the
+// deficit to strictly shrink, so an undershoot just leaves a dust residual
+// for the next run; any surplus (carry > debt) must stay within the on-chain
+// RECOLLATERALIZE_LOSS_THRESHOLD_BPS (20 bps of debt) ceiling.
+const RECOLLATERALIZE_LOSS_OVERSHOOT_BUFFER_BPS = BigInt(10);
+
+export class RecollateralizeLossBuilder extends LongYieldCarryBuilderBase<
+  RecollateralizeLossIxArgs,
+  RecollateralizeLossTxArgs,
+  LongYieldCarryTransactionPlan[]
+> {
+  async getIx(args: RecollateralizeLossIxArgs): 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 collateralTokenAccount = await getAtaAddress(
+      collateralMint,
+      args.token,
+      collateralTokenProgram
+    );
+
+    const lpIdx = args.params.lendingPositionIndex;
+    const position = tokenData.data.lendingPositions[lpIdx];
+    // Position may be missing (out-of-bounds) or inactive (zeroed debt mint).
+    // Fall back to an active position so the instruction can reach the on-chain
+    // InvalidLendingPosition check rather than failing on account validation.
+    const isActive = position && !position.accounting.debt.mint.equals(PublicKey.default);
+    const refPositionEntry = isActive
+      ? { index: lpIdx, data: position }
+      : tokenData.activeLendingPositions[0];
+    const refPosition = refPositionEntry?.data ?? tokenData.data.lendingPositions[0];
+    const debtMint = fromWeb3Pk(refPosition.accounting.debt.mint);
+    const debtTokenProgram = resolveTokenProgram(refPosition.accounting.debt.tokenProgram);
+    const yieldingBank = args.params.yieldingBank ?? args.token;
+    const [tokenLpDebtTa, yieldingBankTa] = await Promise.all([
+      getAtaAddress(debtMint, args.token, debtTokenProgram),
+      getAtaAddress(debtMint, yieldingBank, debtTokenProgram),
+    ]);
+
+    // For out-of-bounds indices (position === undefined), use the ref position's
+    // accounts so the instruction can be built. The on-chain bounds check fires
+    // first and rejects it with InvalidLendingPosition before accounts matter.
+    const lpPositionAccountIdx = isActive ? lpIdx : (refPositionEntry?.index ?? 0);
+
+    const builtIx = await this.program.methods
+      .recollateralizeLoss({
+        prerequisiteCpis: args.params.prerequisiteCpis ?? null,
+        ixRefs: args.params.ixRefs,
+        lendingPositionIndex: args.params.lendingPositionIndex,
+      })
+      .accountsStrict({
+        manager: this.resolveTokenManager(tokenData.data),
+        token: args.token,
+        collateralMint,
+        collateralTokenAccount,
+        collateralOracle,
+        secondaryCollateralOracle,
+        lpPosition: this.account.getTokenLendingPositionRefreshAccounts(
+          tokenData.data,
+          lpPositionAccountIdx,
+          args.params.lpPosition
+        ),
+        collateralTokenProgram,
+        yieldingBank,
+        debtMint,
+        tokenLpDebtTa,
+        yieldingBankTa,
+        debtTokenProgram,
+      })
+      .remainingAccounts(args.params.remainingAccounts.map(toWeb3AccountMeta))
+      .instruction();
+
+    return toKitInstruction(builtIx);
+  }
+
+  async getTx(args: RecollateralizeLossTxArgs): Promise<LongYieldCarryTransactionPlan[]> {
+    const tokenData = await this.account.fetchToken(args.token, { fresh: true });
+    const txId = args.params.txId ?? `recollateralize-loss-${Date.now()}`;
+    const slippageBps = args.params.swapSlippageBps ?? DEFAULT_RECOLLATERALIZE_LOSS_SLIPPAGE_BPS;
+    const target = await this.selectRecollateralizationTarget(tokenData);
+    const swapPlan = await this.buildRecollateralizationSwapPlan(target, slippageBps);
+    const dcpPhase = await this.buildOptionalDecreaseCarryPhase(args, target, swapPlan, txId);
+    const recollateralizePhase = await this.buildRecollateralizePhase(args, target, swapPlan, txId);
+
+    return dcpPhase ? [dcpPhase, recollateralizePhase] : [recollateralizePhase];
+  }
+
+  private async selectRecollateralizationTarget(
+    tokenData: LYCToken
+  ): Promise<RecollateralizationTarget> {
+    const totalDebtUsd = tokenData.activeLendingPositions.reduce(
+      (sum, { data: lp }) => sum + toBigInt(lp.accounting.debt.tvlUsd),
+      BigInt(0)
+    );
+    const totalCarryUsd = tokenData.activeCarryPositions.reduce(
+      (sum, { data: carry }) => sum + toBigInt(carry.tvlUsd),
+      BigInt(0)
+    );
+
+    if (totalDebtUsd <= totalCarryUsd) {
+      throw new NoOpTransactionError("Recollateralization not needed: debt does not exceed carry");
+    }
+
+    const bestLp = tokenData.activeLendingPositions.reduce((best, current) =>
+      toBigInt(current.data.accounting.collateral) > toBigInt(best.data.accounting.collateral)
+        ? current
+        : best
+    );
+    const bestCarry = tokenData.activeCarryPositions.reduce((best, current) =>
+      toBigInt(current.data.tvlUsd) > toBigInt(best.data.tvlUsd) ? current : best
+    );
+    const yieldingBank = await tokenData.deriveYieldingBankAddressForDebtCarryIndex(
+      bestCarry.index,
+      this.pda
+    );
+
+    return {
+      tokenData,
+      totalDebtUsd,
+      totalCarryUsd,
+      lendingPositionIndex: bestLp.index,
+      position: bestLp.data,
+      yieldingBank,
+    };
+  }
+
+  private async buildRecollateralizationSwapPlan(
+    target: RecollateralizationTarget,
+    slippageBps: number
+  ): Promise<RecollateralizationSwapPlan> {
+    const { tokenData, position, totalDebtUsd, totalCarryUsd } = target;
+    const debtExcessUsd = totalDebtUsd - totalCarryUsd;
+    const overshootBuffer =
+      (debtExcessUsd * RECOLLATERALIZE_LOSS_OVERSHOOT_BUFFER_BPS) / BigInt(10000);
+    const targetRepayUsd = debtExcessUsd + overshootBuffer;
+
+    const collateralPrice = toBigInt(tokenData.data.collateral.price);
+    if (collateralPrice === BigInt(0)) {
+      throw new Error("Collateral price is zero — refresh the token state first");
+    }
+    const collateralInputAmount = tvlUsdToBaseUnits(
+      targetRepayUsd,
+      collateralPrice,
+      tokenData.data.collateral.decimals
+    );
+    if (collateralInputAmount === BigInt(0)) {
+      throw new NoOpTransactionError(
+        "Collateral input rounds to zero — no recollateralization needed"
+      );
+    }
+
+    const swapQuote = await this.swap.getQuote({
+      inputMint: tokenData.collateralMint,
+      outputMint: fromWeb3Pk(position.accounting.debt.mint),
+      amount: Number(collateralInputAmount),
+      slippageBps,
+    });
+
+    // Minimum guaranteed output after slippage; on-chain repays exactly this amount.
+    // Any surplus from the actual swap sits in the debt ATA and gets deposited to the
+    // yielding bank by the on-chain handler.
+    const repayBaseUnits = (swapQuote.outputAmount * BigInt(10000 - slippageBps)) / BigInt(10000);
+
+    return {
+      collateralToWithdrawUi: toUiAmount(swapQuote.inputAmount, tokenData.data.collateral.decimals),
+      repayUiAmount: toUiAmount(repayBaseUnits, position.accounting.debt.decimals),
+      repayBaseUnits,
+      swapQuote,
+    };
+  }
+
+  private async buildOptionalDecreaseCarryPhase(
+    args: RecollateralizeLossTxArgs,
+    target: RecollateralizationTarget,
+    swapPlan: RecollateralizationSwapPlan,
+    txId: string
+  ): Promise<LongYieldCarryTransactionPlan | undefined> {
+    const { position, lendingPositionIndex, yieldingBank } = target;
+    const lpClient = this.getLendingPlatformClient(position);
+    lpClient.ix.clearCacheEntry(
+      lpClient.ix.data.userAccountCatKey,
+      fromWeb3Pk(position.protocolUserAcc)
+    );
+
+    const lycLendingPositionManager = await LycLendingPositionManager.create(
+      lpClient.data,
+      position
+    );
+    const postWithdrawalUtilBps =
+      await lycLendingPositionManager.calcPostWithdrawalUtilizationRateBps(
+        swapPlan.collateralToWithdrawUi
+      );
+    if (postWithdrawalUtilBps <= position.config.targetUtilizationRateBps) {
+      return undefined;
+    }
+
+    const preWithdrawalTargetBps =
+      await lycLendingPositionManager.calcPreWithdrawalTargetUtilizationRateBps(
+        swapPlan.collateralToWithdrawUi
+      );
+    return new DecreaseCarryPositionBuilder(this.context).buildTx(
+      this.resolveTokenManager(target.tokenData.data),
+      args.token,
+      {
+        lendingPositionIndex,
+        yieldingBank,
+        sourceMint: args.params.sourceMint,
+        swapSlippageBps: args.params.swapSlippageBps,
+        repaySteering: {
+          mode: "explicitTargetUtilization",
+          targetUtilizationRateBps: preWithdrawalTargetBps,
+        },
+        txId,
+      },
+      { includePreInstructions: true }
+    );
+  }
+
+  private async buildRecollateralizePhase(
+    args: RecollateralizeLossTxArgs,
+    target: RecollateralizationTarget,
+    swapPlan: RecollateralizationSwapPlan,
+    txId: string
+  ): Promise<LongYieldCarryTransactionPlan> {
+    const { position, lendingPositionIndex } = target;
+    const manager = this.resolveTokenManager(target.tokenData.data);
+    const lpClient = this.getLendingPlatformClient(position);
+    const withdrawCpiData = await this.getLendingOperationCpiData(
+      args.token,
+      manager,
+      position,
+      txId,
+      "withdraw",
+      swapPlan.collateralToWithdrawUi
+    );
+    const swapCpiData = await this.swap.getSwapCpiData(swapPlan.swapQuote, args.token, {
+      payer: manager,
+    });
+    const repayCpiData = await this.getLendingOperationCpiData(
+      args.token,
+      manager,
+      position,
+      txId,
+      "repay",
+      swapPlan.repayUiAmount
+    );
+    const prerequisiteCpiGroup = [...withdrawCpiData.prerequisiteCpis];
+    const executionCpiGroup = [
+      ...withdrawCpiData.cpis,
+      swapCpiData,
+      ...repayCpiData.prerequisiteCpis,
+      ...repayCpiData.cpis,
+    ];
+    const {
+      accounts: remainingAccounts,
+      refsGroups,
+      lookupTables,
+    } = createMultiCpiRefs(
+      prerequisiteCpiGroup.length ? [prerequisiteCpiGroup, executionCpiGroup] : [executionCpiGroup]
+    );
+    const prerequisiteCpis = prerequisiteCpiGroup.length ? refsGroups[0] : undefined;
+    const ixRefs = refsGroups[prerequisiteCpiGroup.length ? 1 : 0];
+    const preInstructions = await lpClient.ix.getPreInstructions(txId);
+    const carryTradeAccounts = await this.account.getCarryTradeAccounts(
+      args.token,
+      target.yieldingBank,
+      lendingPositionIndex
+    );
+    const [
+      { instructions, postSuccessCacheInvalidations },
+      { instructions: debtAtaInstructions, postSuccessCacheInvalidations: debtAtaInvalidations },
+    ] = await Promise.all([
+      getCreateAtaInstructions(this.rpc, manager, remainingAccounts),
+      getCreateAtaInstructions(this.rpc, manager, carryTradeAccounts),
+    ]);
+    const recollateralizeIx = await this.getIx({
+      token: args.token,
+      params: {
+        prerequisiteCpis,
+        ixRefs,
+        lendingPositionIndex,
+        remainingAccounts,
+        yieldingBank: target.yieldingBank,
+        lpPosition: args.params.lpPosition,
+      },
+    });
+    const setupInstructions = [
+      ...preInstructions,
+      ...(swapCpiData.preInstructions ?? []),
+      ...debtAtaInstructions,
+      ...instructions,
+    ];
+
+    return {
+      instructions: [
+        ...setupInstructions,
+        // The heap frame applies only to this transaction. Keep it with the
+        // CPI-heavy instruction while allowing refresh and ATA setup to move
+        // into earlier transactions in the same atomic bundle.
+        requestHeapFrameIx(MAX_HEAP_FRAME_BYTES),
+        recollateralizeIx,
+      ],
+      lookupTables: this.getTxLookupTables(args.token, lookupTables ?? []),
+      segmentLengths: [...setupInstructions.map(() => 1), 2],
+      postSuccessCacheInvalidations: [
+        getTokenCacheInvalidation(args.token),
+        getLendingUserAccountCacheInvalidation(fromWeb3Pk(position.protocolUserAcc)),
+        ...postSuccessCacheInvalidations,
+        ...debtAtaInvalidations,
+        ...withdrawCpiData.postSuccessCacheInvalidations,
+        ...repayCpiData.postSuccessCacheInvalidations,
+        ...(swapCpiData.postSuccessCacheInvalidations ?? []),
+      ],
+    };
+  }
+}

package/src/client/builders/refreshTokenStateBuilder.ts

@@ -0,0 +1,153 @@
+import type { Address, Instruction } from "@solana/kit";
+import type { LongYieldCarryTransactionPlan } from "../types";
+import { LongYieldCarrySingleInstructionBuilderService } from "./base";
+import type { RefreshTokenStateIxArgs } from "./args";
+import {
+  type CpiData,
+  LendingPlatform,
+  createCpiRefs,
+  fromWeb3Pk,
+  toKitInstruction,
+  toWeb3AccountMeta,
+} from "common";
+import { TOKEN_PROGRAM_ADDRESS } from "@solana-program/token";
+import { RefreshYieldingBankBuilder } from "./refreshYieldingBankBuilder";
+
+interface RefreshPrerequisiteTarget {
+  pool: Address;
+  userAccount: Address;
+  collateralReserves: Address[];
+  debtReserves: Address[];
+}
+
+export class RefreshTokenStateBuilder extends LongYieldCarrySingleInstructionBuilderService<RefreshTokenStateIxArgs> {
+  async getIx(args: RefreshTokenStateIxArgs): Promise<Instruction> {
+    const { prerequisiteCpis, accountRefs, remainingAccounts } =
+      await this.getRefreshTokenStateParams(args.token);
+
+    return this.program.methods
+      .refreshTokenState({
+        prerequisiteCpis,
+        accountRefs,
+      })
+      .accountsPartial({
+        signer: args.signer,
+        token: args.token,
+        collateralOracle: args.collateralOracle,
+        secondaryCollateralOracle: args.secondaryCollateralOracle ?? null,
+        collateralTokenAccount: args.collateralTokenAccount,
+        collateralTokenProgram: args.collateralTokenProgram ?? TOKEN_PROGRAM_ADDRESS,
+      })
+      .remainingAccounts(remainingAccounts.map(toWeb3AccountMeta))
+      .instruction()
+      .then(toKitInstruction);
+  }
+
+  async getTx(args: RefreshTokenStateIxArgs): Promise<LongYieldCarryTransactionPlan> {
+    const ixs: Instruction[] = [];
+    const tokenAccount = await this.account.fetchToken(args.token);
+    const uniqueBanks = new Set<Address>();
+
+    for (const { data: carry } of tokenAccount.activeCarryPositions) {
+      const [yieldingBank] = await this.pda.deriveYieldingBankPda(
+        fromWeb3Pk(carry.yieldingBaseMint),
+        carry.yieldingBankId
+      );
+      uniqueBanks.add(yieldingBank);
+    }
+
+    for (const yieldingBank of uniqueBanks) {
+      const refreshYieldingBankPlan = await new RefreshYieldingBankBuilder(this.context).getTx({
+        signer: args.signer,
+        yieldingBank,
+      });
+      ixs.push(...refreshYieldingBankPlan.instructions);
+    }
+
+    ixs.push(await this.getIx(args));
+
+    return {
+      instructions: ixs,
+      lookupTables: this.getTxLookupTables(args.token),
+    };
+  }
+
+  private async getRefreshTokenStateParams(token: Address) {
+    const tokenData = await this.account.fetchToken(token);
+    const refreshAccounts = await this.account.getTokenRefreshAccounts(token);
+    const prerequisiteCpis: CpiData[] = [];
+    const refreshTargetsByPlatform = new Map<
+      LendingPlatform,
+      Map<string, RefreshPrerequisiteTarget>
+    >();
+
+    for (const { data: position } of tokenData.activeLendingPositions) {
+      const platform = this.lendingPlatformClients.getPlatformForPosition(position);
+      if (platform === LendingPlatform.None) {
+        continue;
+      }
+
+      const pool = fromWeb3Pk(position.pool);
+      const userAccount = fromWeb3Pk(position.protocolUserAcc);
+      const collateralReserve = fromWeb3Pk(position.collateralReserve);
+      const debtReserve = fromWeb3Pk(position.debtReserve);
+      const platformTargets =
+        refreshTargetsByPlatform.get(platform) ?? new Map<string, RefreshPrerequisiteTarget>();
+      const targetKey = `${pool}:${userAccount}`;
+      if (platformTargets.has(targetKey)) {
+        continue;
+      }
+      platformTargets.set(targetKey, {
+        pool,
+        userAccount,
+        collateralReserves: [collateralReserve],
+        debtReserves: [debtReserve],
+      });
+      refreshTargetsByPlatform.set(platform, platformTargets);
+    }
+
+    for (const [platform, platformTargets] of refreshTargetsByPlatform) {
+      const lpClient = this.lendingPlatformClients.getByPlatform(platform);
+      const positionPrerequisiteCpis = await lpClient.ix.getPrerequisiteCpisForRefresh([
+        ...platformTargets.values(),
+      ]);
+      prerequisiteCpis.push(...positionPrerequisiteCpis);
+    }
+
+    // Compute account indices. refreshAccounts is ordered as:
+    //   [userAcc, collateralReserve, debtOracle] × numActiveLPs, then [yieldingBank] × numActiveCarry
+    // initialAccounts are prepended to the pool at stable positions 0..N-1 by createCpiRefs,
+    // so indices are the same whether or not prereq CPIs are present.
+    const numActiveLPs = tokenData.activeLendingPositions.length;
+    const lendingPositions = tokenData.activeLendingPositions.map((_, i) => ({
+      userAccount: i * 3,
+      collateralReserve: i * 3 + 1,
+      debtOracle: i * 3 + 2,
+    }));
+    const carryPositions = Buffer.from(
+      tokenData.activeCarryPositions.map((_, i) => numActiveLPs * 3 + i)
+    );
+    const accountRefs = { lendingPositions, carryPositions };
+
+    if (!prerequisiteCpis.length) {
+      return {
+        prerequisiteCpis: null,
+        accountRefs,
+        remainingAccounts: refreshAccounts,
+      };
+    }
+
+    const { accounts: remainingAccounts, refs: prerequisiteCpiRefs } = createCpiRefs(
+      prerequisiteCpis,
+      {
+        initialAccounts: refreshAccounts,
+      }
+    );
+
+    return {
+      prerequisiteCpis: prerequisiteCpiRefs,
+      accountRefs,
+      remainingAccounts,
+    };
+  }
+}

package/src/client/builders/refreshTokensBuilder.ts

@@ -0,0 +1,82 @@
+import type { Address, Instruction } from "@solana/kit";
+import { fromWeb3Pk, getAtaAddress, resolveTokenProgram } from "common";
+import type { LongYieldCarryTransactionPlan } from "../types";
+import type { LongYieldCarryBuilderContext } from "../types/builders";
+import type { LYCToken } from "../../models";
+import { mergeLycLookupTables } from "../../utils";
+import type { RefreshTokensBuilderTxArgs } from "./args";
+import { RefreshTokenStateBuilder } from "./refreshTokenStateBuilder";
+import { RefreshYieldingBankBuilder } from "./refreshYieldingBankBuilder";
+
+export class RefreshTokensBuilder {
+  constructor(private readonly context: LongYieldCarryBuilderContext) {}
+
+  async getTx(args: RefreshTokensBuilderTxArgs): Promise<LongYieldCarryTransactionPlan> {
+    const tokens = await this.context.account.fetchTokens(args.params.tokens);
+    const instructions: Instruction[] = [];
+    const ybAddresses = await this.getYieldingBanksToRefresh(
+      tokens,
+      args.params.alwaysRefreshYieldingBanks ?? false
+    );
+    const refreshYieldingBankBuilder = new RefreshYieldingBankBuilder(this.context);
+    const refreshTokenStateBuilder = new RefreshTokenStateBuilder(this.context);
+
+    for (const yieldingBank of ybAddresses) {
+      const ybPlan = await refreshYieldingBankBuilder.getTx({
+        signer: args.signer,
+        yieldingBank,
+      });
+      instructions.push(...ybPlan.instructions);
+    }
+
+    for (const token of tokens) {
+      instructions.push(
+        await refreshTokenStateBuilder.getIx({
+          signer: args.signer,
+          token: token.address,
+          collateralOracle: fromWeb3Pk(token.data.collateral.oracle),
+          secondaryCollateralOracle: fromWeb3Pk(token.data.collateral.secondaryOracle),
+          collateralTokenAccount: await getAtaAddress(
+            token.collateralMint,
+            token.address,
+            resolveTokenProgram(token.data.collateral.tokenProgram)
+          ),
+          collateralTokenProgram: resolveTokenProgram(token.data.collateral.tokenProgram),
+        })
+      );
+    }
+
+    return {
+      instructions,
+      lookupTables: mergeLycLookupTables(this.context.environment, args.params.tokens),
+    };
+  }
+
+  private async getYieldingBanksToRefresh(
+    tokens: LYCToken[],
+    alwaysRefreshYieldingBanks: boolean
+  ): Promise<Address[]> {
+    const uniqueYbAddresses: Address[] = [];
+    const seen = new Set<Address>();
+
+    for (const token of tokens) {
+      for (const { data: carry } of token.activeCarryPositions) {
+        const [yieldingBank] = await this.context.pda.deriveYieldingBankPda(
+          fromWeb3Pk(carry.yieldingBaseMint),
+          carry.yieldingBankId
+        );
+        if (!seen.has(yieldingBank)) {
+          seen.add(yieldingBank);
+          uniqueYbAddresses.push(yieldingBank);
+        }
+      }
+    }
+
+    if (alwaysRefreshYieldingBanks || uniqueYbAddresses.length === 0) {
+      return uniqueYbAddresses;
+    }
+
+    const banks = await this.context.account.fetchYieldingBanks(uniqueYbAddresses);
+    return banks.filter((bank) => bank.isStale).map((bank) => bank.address);
+  }
+}

package/src/client/builders/refreshYieldingBankBuilder.ts

@@ -0,0 +1,42 @@
+import type { Address, Instruction } from "@solana/kit";
+import type { LongYieldCarryTransactionPlan } from "../types";
+import { LongYieldCarryBuilderBase } from "./base";
+import type { RefreshYieldingBankIxArgs, RefreshYieldingBankTxArgs } from "./args";
+import { toKitInstruction, toWeb3AccountMeta } from "common";
+
+export class RefreshYieldingBankBuilder extends LongYieldCarryBuilderBase<
+  RefreshYieldingBankIxArgs,
+  RefreshYieldingBankTxArgs
+> {
+  async getIx(args: RefreshYieldingBankIxArgs): Promise<Instruction> {
+    const oracleAccounts = await this.account.getYieldingBankRefreshAccounts(
+      args.yieldingBank,
+      undefined,
+      args.externalLiquiditySources
+    );
+
+    return this.program.methods
+      .refreshYieldingBank()
+      .accountsPartial({
+        signer: args.signer,
+        yieldingBank: args.yieldingBank,
+      })
+      .remainingAccounts(oracleAccounts.map(toWeb3AccountMeta))
+      .instruction()
+      .then(toKitInstruction);
+  }
+
+  async getTx(args: RefreshYieldingBankTxArgs): Promise<LongYieldCarryTransactionPlan> {
+    const { externalLiquiditySources } =
+      await this.externalLiquidityResolver.resolveYieldingBankRefreshExternalLiquidity(
+        this.account,
+        args.yieldingBank
+      );
+    const ix = await this.getIx({
+      signer: args.signer,
+      yieldingBank: args.yieldingBank,
+      externalLiquiditySources,
+    });
+    return { instructions: [ix], lookupTables: this.getTxLookupTables() };
+  }
+}

package/src/client/builders/resetTokenBurnRateLimitBuilder.ts

@@ -0,0 +1,21 @@
+import type { Address, Instruction } from "@solana/kit";
+import { toKitInstruction } from "common";
+import { LongYieldCarrySingleInstructionBuilderService } from "./base";
+import type { ResetTokenBurnRateLimitIxArgs } from "./args";
+
+export class ResetTokenBurnRateLimitBuilder extends LongYieldCarrySingleInstructionBuilderService<ResetTokenBurnRateLimitIxArgs> {
+  async getIx(args: ResetTokenBurnRateLimitIxArgs): Promise<Instruction> {
+    const tokenData = await this.account.fetchToken(args.token);
+    return this.program.methods
+      .resetTokenBurnRateLimit()
+      .accountsPartial({ admin: this.resolveTokenAdmin(tokenData.data), token: args.token })
+      .instruction()
+      .then(toKitInstruction);
+  }
+
+  protected async buildLookupTables(
+    args: ResetTokenBurnRateLimitIxArgs
+  ): Promise<readonly Address[]> {
+    return this.getTxLookupTables(args.token);
+  }
+}