@kestrelfi/lyc-sdk 1.0.1

package/src/client/account.ts

@@ -0,0 +1,503 @@
+import { type Address, address, type Rpc, type SolanaRpcApi } from "@solana/kit";
+import { PublicKey } from "@solana/web3.js";
+import { Program } from "@anchor-lang/core";
+import { LongYieldCarry } from "../idl/long_yield_carry";
+import { LYCToken, type TokenAccountData } from "../models/lycToken";
+import { LYCYieldingBank, type YieldingBankAccountData } from "../models/yieldingBank";
+import {
+  BaseAccountClient,
+  CustomAccountMeta,
+  ExternalLiquidityType,
+  ExternalLiquidityTypeToEnum,
+  fetchSplTokenAccountAmounts,
+  fromWeb3Pk,
+  getAtaAddress,
+  LendingPlatform,
+  lendingPlatformToEnum,
+  resolveTokenProgram,
+  toBigInt,
+  toCustomAccountMeta,
+  toUiAmount,
+  toWeb3Pk,
+} from "common";
+import type { PdaClient } from "./pda";
+import type {
+  RedemptionEpochSnapshot,
+  TokenLpPositionAccountOverrides,
+  UserHolding,
+  YieldingBankAllocationConfig,
+  YieldingBankExternalLiquiditySource,
+} from "./types";
+import { buildCarryTradeAccountMetas, buildRebalanceTokenInitialAccounts } from "../utils/ix";
+
+/** DataCache category for LYC `Token` accounts (used when clearing cache after writes). */
+export const LYC_TOKEN_CACHE_CATEGORY = "token";
+export const YIELDING_BANK_CACHE_CATEGORY = "yieldingBank";
+export const REDEMPTION_EPOCH_CACHE_CATEGORY = "redemptionEpoch";
+export const IGNORED_LYC_TOKEN_ADDRESSES = new Set<string>([
+  "GphwC2jwG3mcM8FYFFm5j8A4jNw3i7Hhic4poLbnoKpu", // jupSOL - need proper oracle implementation to fix this (TODO)
+]);
+
+/**
+ * Account fetchers for the long_yield_carry program.
+ *
+ * Extends {@link BaseAccountClient} for shared DataCache + `splAtaExists`, then adds LYC-specific
+ * deserialization and helpers (Token, YieldingBank, carry-trade metas).
+ */
+export class AccountClient extends BaseAccountClient {
+  constructor(
+    private readonly program: Program<LongYieldCarry>,
+    readonly pda: PdaClient,
+    rpc: Rpc<SolanaRpcApi>
+  ) {
+    super(rpc, {
+      categoryTtlMs: {
+        [LYC_TOKEN_CACHE_CATEGORY]: 60_000 * 5,
+        [YIELDING_BANK_CACHE_CATEGORY]: 60_000 * 10,
+        [REDEMPTION_EPOCH_CACHE_CATEGORY]: 30_000,
+      },
+    });
+  }
+
+  /** Fetch and deserialize a Token account by its PDA address. */
+  async fetchToken(token: Address, opts?: { fresh?: boolean }): Promise<LYCToken> {
+    if (opts?.fresh) {
+      this.dataCache.clearCacheEntry(LYC_TOKEN_CACHE_CATEGORY, token);
+    }
+    const { data } = await this.dataCache.getDataOrThrow(
+      () => this.program.account.token.fetch(toWeb3Pk(token)),
+      LYC_TOKEN_CACHE_CATEGORY,
+      token
+    );
+    return new LYCToken(token, data);
+  }
+
+  /** Fetch and deserialize multiple Token accounts by their PDA addresses. */
+  async fetchTokens(tokens: Address[]): Promise<LYCToken[]> {
+    const { data } = await this.dataCache.getDataBatch(
+      () => this.program.account.token.fetchMultiple(tokens.map(toWeb3Pk)),
+      LYC_TOKEN_CACHE_CATEGORY,
+      tokens
+    );
+    return data.map((x, i) => new LYCToken(tokens[i], x));
+  }
+
+  /**
+   * Fetch all Token accounts owned by the program.
+   *
+   * Pass `{ fresh: true }` to clear the cached `"all"` entry before reading,
+   * forcing a fresh `getProgramAccounts` call. The returned data is
+   * re-cached so subsequent callers benefit from the same refresh.
+   */
+  async fetchAllTokens(opts?: { fresh?: boolean }): Promise<LYCToken[]> {
+    if (opts?.fresh) {
+      this.dataCache.clearCacheEntry(LYC_TOKEN_CACHE_CATEGORY, "all");
+    }
+    const { data } = await this.dataCache.getDataOrThrow(
+      () => this.program.account.token.all(),
+      LYC_TOKEN_CACHE_CATEGORY,
+      "all"
+    );
+    return data
+      .map((acc) => new LYCToken(address(acc.publicKey.toBase58()), acc.account))
+      .filter(
+        (token) =>
+          !IGNORED_LYC_TOKEN_ADDRESSES.has(token.address) &&
+          !IGNORED_LYC_TOKEN_ADDRESSES.has(token.mint)
+      );
+  }
+
+  /** Fetch and deserialize a YieldingBank account by its PDA address. */
+  async fetchYieldingBank(bank: Address): Promise<LYCYieldingBank> {
+    const { data } = await this.dataCache.getDataOrThrow(
+      () => this.program.account.yieldingBank.fetch(toWeb3Pk(bank)),
+      YIELDING_BANK_CACHE_CATEGORY,
+      bank
+    );
+    return new LYCYieldingBank(bank, data);
+  }
+
+  /** Fetch and deserialize multiple YieldingBank accounts by their PDA addresses. */
+  async fetchYieldingBanks(banks: Address[]): Promise<LYCYieldingBank[]> {
+    const { data } = await this.dataCache.getDataBatch(
+      () => this.program.account.yieldingBank.fetchMultiple(banks.map(toWeb3Pk)),
+      YIELDING_BANK_CACHE_CATEGORY,
+      banks
+    );
+    return data.map((x, i) => new LYCYieldingBank(banks[i], x));
+  }
+
+  /** Fetch all YieldingBank accounts owned by the program. */
+  async fetchAllYieldingBanks(): Promise<LYCYieldingBank[]> {
+    const { data } = await this.dataCache.getDataOrThrow(
+      () => this.program.account.yieldingBank.all(),
+      YIELDING_BANK_CACHE_CATEGORY,
+      "all"
+    );
+    return data.map((acc) => new LYCYieldingBank(address(acc.publicKey.toBase58()), acc.account));
+  }
+
+  /** Fetch and deserialize a RedemptionEpoch account by its PDA address. */
+  async fetchRedemptionEpoch(
+    epochPda: Address,
+    opts?: { fresh?: boolean }
+  ): Promise<RedemptionEpochSnapshot> {
+    if (opts?.fresh) {
+      this.dataCache.clearCacheEntry(REDEMPTION_EPOCH_CACHE_CATEGORY, epochPda);
+    }
+    const { data } = await this.dataCache.getDataOrThrow(
+      () => this.program.account.redemptionEpoch.fetch(toWeb3Pk(epochPda)),
+      REDEMPTION_EPOCH_CACHE_CATEGORY,
+      epochPda
+    );
+    return this.toRedemptionEpochSnapshot(epochPda, data);
+  }
+
+  /** Fetch all RedemptionEpoch accounts owned by the program. */
+  async fetchAllRedemptionEpochs(opts?: { fresh?: boolean }): Promise<RedemptionEpochSnapshot[]> {
+    if (opts?.fresh) {
+      this.dataCache.clearCacheEntry(REDEMPTION_EPOCH_CACHE_CATEGORY, "all");
+    }
+    const { data } = await this.dataCache.getDataOrThrow(
+      () => this.program.account.redemptionEpoch.all(),
+      REDEMPTION_EPOCH_CACHE_CATEGORY,
+      "all"
+    );
+    return data
+      .filter((acc) => acc?.publicKey && acc?.account)
+      .map((acc) => this.toRedemptionEpochSnapshot(address(acc.publicKey.toBase58()), acc.account));
+  }
+
+  /**
+   * Fetch all LYC yToken holdings for a wallet.
+   *
+   * Reads the user's ATA per LYC token directly via `getMultipleAccounts` —
+   * cost scales with the LYC token count (typically <10), not the wallet's
+   * total token-account count, which can be in the hundreds for active users.
+   *
+   * USD valuation: only when `opts.priceMap` supplies a positive USD price for
+   * the collateral mint and `token.price` (NAV) is positive:
+   *   `valueUsd = uiBalance × token.price × priceMap[collateralMint]`.
+   * If the caller does not supply a usable collateral price, `valueUsd` is
+   * omitted — we do not infer USD from on-chain `tvlUsd` / `totalSupply`, since
+   * those can lag risk-asset markets by tens of minutes.
+   *
+   * Tokens with no user ATA or a zero balance are filtered out unless
+   * `opts.includeEmpty` is set.
+   *
+   * Pass `opts.tokens` when the caller already has a list of tokens (e.g. a
+   * backend service with its own shorter-lived tokens cache) to skip the
+   * internal `fetchAllTokens` call and its 5-minute SDK cache.
+   */
+  async fetchUserHoldings(
+    owner: Address,
+    opts?: {
+      includeEmpty?: boolean;
+      tokens?: LYCToken[];
+      priceMap?: Partial<Record<Address, number>>;
+    }
+  ): Promise<UserHolding[]> {
+    const tokens = opts?.tokens ?? (await this.fetchAllTokens());
+    if (tokens.length === 0) return [];
+
+    // Derive the user's ATA per LYC token mint up front so we can fetch them
+    // all in a single round trip rather than enumerating the wallet's full
+    // token-account set.
+    const ataByMint = new Map<Address, Address>();
+    const ataAddresses: Address[] = [];
+    for (const token of tokens) {
+      const tokenProgram = resolveTokenProgram(token.data.config.tokenProgram);
+      const ata = await getAtaAddress(token.mint, owner, tokenProgram);
+      ataByMint.set(token.mint, ata);
+      ataAddresses.push(ata);
+    }
+
+    const balanceByAta = await fetchSplTokenAccountAmounts(this.rpc, ataAddresses);
+
+    const holdings: UserHolding[] = [];
+    for (const token of tokens) {
+      const tokenAccount = ataByMint.get(token.mint)!;
+      const balance = balanceByAta.get(tokenAccount) ?? BigInt(0);
+
+      if (balance === BigInt(0) && !opts?.includeEmpty) continue;
+
+      const uiBalance = toUiAmount(balance, token.decimals);
+
+      const collateralPrice = opts?.priceMap?.[token.collateralMint];
+      let valueUsd: number | undefined;
+      if (collateralPrice !== undefined && collateralPrice > 0 && token.price > 0) {
+        valueUsd = uiBalance * token.price * collateralPrice;
+      }
+
+      holdings.push({
+        token,
+        tokenAccount,
+        balance,
+        uiBalance,
+        valueUsd,
+      });
+    }
+    return holdings;
+  }
+
+  /** Fetch all Token and YieldingBank accounts in parallel. */
+  async fetchAllTokensAndYieldingBanks(): Promise<{
+    tokens: LYCToken[];
+    yieldingBanks: LYCYieldingBank[];
+  }> {
+    const [tokens, yieldingBanks] = await Promise.all([
+      this.fetchAllTokens(),
+      this.fetchAllYieldingBanks(),
+    ]);
+    return { tokens, yieldingBanks };
+  }
+
+  /**
+   * Build the ordered remaining-accounts list required by refresh_yielding_bank
+   * (and embedded within rebalance_yielding_bank):
+   *
+   *   1. base_asset: [token_account, oracle, external_liquidity...] (if active)
+   *   2. Per active asset holding (in slot order): [token_account, oracle, external_liquidity...]
+   *      The token_account is the mint's ATA owned by the bank PDA; the program
+   *      reads its raw balance to sync asset.amount on every refresh.
+   *   3. One user account per active external yielding position (in slot order)
+   *
+   * If `newAllocation` is provided, its [token_account, oracle, external_liquidity...]
+   * tuple is injected at the first inactive slot, matching where `apply_allocation`
+   * will register it.
+   */
+  async getYieldingBankRefreshAccounts(
+    bank: Address,
+    newAllocation?: YieldingBankAllocationConfig,
+    externalLiquiditySources: YieldingBankExternalLiquiditySource[] = []
+  ): Promise<CustomAccountMeta[]> {
+    const bankData = await this.fetchYieldingBank(bank);
+
+    const pushAssetAccounts = async (
+      mint: Address,
+      tokenProgramAddr: Address,
+      externalLiquidityType: YieldingBankAccountData["baseAsset"]["externalLiquidity"],
+      oracle: Address,
+      accounts: CustomAccountMeta[]
+    ) => {
+      const ata = await getAtaAddress(mint, bank, tokenProgramAddr);
+      accounts.push(
+        toCustomAccountMeta(ata, false, { owner: bank, tokenProgram: tokenProgramAddr, mint })
+      );
+      accounts.push(toCustomAccountMeta(oracle));
+      if (ExternalLiquidityTypeToEnum(externalLiquidityType) !== ExternalLiquidityType.None) {
+        const sources = externalLiquiditySources
+          .filter((source) => source.mint === mint)
+          .map((source) => source.account);
+        accounts.push(...sources.map((source) => toCustomAccountMeta(source)));
+      }
+    };
+
+    const assetAccounts: CustomAccountMeta[] = [];
+
+    // base_asset first
+    const baseAsset = bankData.baseAsset;
+    if (!baseAsset.mint.equals(PublicKey.default)) {
+      await pushAssetAccounts(
+        fromWeb3Pk(baseAsset.mint),
+        resolveTokenProgram(baseAsset.tokenProgram),
+        baseAsset.externalLiquidity,
+        fromWeb3Pk(baseAsset.oracle),
+        assetAccounts
+      );
+    }
+
+    // Per active asset holding: [token_account, oracle].
+    // The first inactive slot gets the newAllocation pair (if provided).
+    let newAssetInserted = false;
+    for (const asset of bankData.assets) {
+      if (!asset.mint.equals(PublicKey.default)) {
+        await pushAssetAccounts(
+          fromWeb3Pk(asset.mint),
+          resolveTokenProgram(asset.tokenProgram),
+          asset.externalLiquidity,
+          fromWeb3Pk(asset.oracle),
+          assetAccounts
+        );
+      } else if (newAllocation?.assetHolding && !newAssetInserted) {
+        const { mint, oracle, externalLiquidityType } = newAllocation.assetHolding;
+        const mintInfo = await this.rpc.getAccountInfo(mint, { encoding: "base64" }).send();
+        const mintOwner = mintInfo.value!.owner;
+        await pushAssetAccounts(mint, mintOwner, externalLiquidityType, oracle, assetAccounts);
+        newAssetInserted = true;
+      }
+    }
+
+    // External position accounts — active slots only (lendingPlatform != None).
+    // Per position: [protocol_user_acc, collateral_reserve].
+    // The new allocation's accounts are inserted at the first inactive slot.
+    const extAccounts: CustomAccountMeta[] = [];
+    let newExtInserted = false;
+    for (const pos of bankData.externalYieldingPositions) {
+      if (!("none" in pos.lendingPlatform)) {
+        extAccounts.push(toCustomAccountMeta(fromWeb3Pk(pos.protocolUserAcc)));
+        extAccounts.push(toCustomAccountMeta(fromWeb3Pk(pos.collateralReserve)));
+      } else if (newAllocation?.externalPosition && !newExtInserted) {
+        extAccounts.push(toCustomAccountMeta(newAllocation.externalPosition.protocolUserAcc));
+        extAccounts.push(toCustomAccountMeta(newAllocation.externalPosition.collateralReserve));
+        newExtInserted = true;
+      }
+    }
+
+    return [...assetAccounts, ...extAccounts];
+  }
+
+  /**
+   * Build the carry-trade remaining accounts for increase/decrease carry
+   * position instructions.
+   *
+   * Fetches the token's lending position at `lendingPositionIndex`, derives
+   * the debt ATAs, and returns the ordered account metas that
+   * `parse_carry_trade_accounts` expects on the Rust side.
+   *
+   * Returns the fixed carry-trade account prefix, including the instructions
+   * sysvar in slot 8 so CPI refs are derived against the on-chain layout.
+   *
+   * @param lendingPositionUserAccount - Override for the protocol user account.
+   *   Defaults to the value stored in the on-chain lending position.
+   */
+  async getCarryTradeAccounts(
+    token: Address,
+    yieldingBank: Address,
+    lendingPositionIndex: number,
+    lendingPositionUserAccount?: Address
+  ): Promise<CustomAccountMeta[]> {
+    const tokenData = await this.fetchToken(token);
+    const position = tokenData.data.lendingPositions[lendingPositionIndex];
+    const debt = position.accounting.debt;
+    const debtMint = fromWeb3Pk(debt.mint);
+    const debtTokenProgram = resolveTokenProgram(debt.tokenProgram);
+    const tokenLpDebtTa = await getAtaAddress(debtMint, token, debtTokenProgram);
+    const yieldingBankTa = await getAtaAddress(debtMint, yieldingBank, debtTokenProgram);
+    return buildCarryTradeAccountMetas(
+      token,
+      yieldingBank,
+      tokenLpDebtTa,
+      yieldingBankTa,
+      lendingPositionUserAccount ?? fromWeb3Pk(position.protocolUserAcc),
+      fromWeb3Pk(position.collateralReserve),
+      fromWeb3Pk(position.accounting.debt.oracle),
+      debtMint,
+      debtTokenProgram
+    );
+  }
+
+  /**
+   * Derive the account set needed to refresh a single token lending position.
+   *
+   * This pulls the protocol user account, collateral reserve, and debt oracle
+   * from the selected lending position so callers can pass the exact accounts
+   * required by refresh-oriented instructions. Optional overrides let tests or
+   * advanced callers substitute explicit addresses when needed.
+   */
+  getTokenLendingPositionRefreshAccounts(
+    tokenData: TokenAccountData,
+    lendingPositionIndex: number,
+    overrides?: TokenLpPositionAccountOverrides
+  ) {
+    const position = tokenData.lendingPositions[lendingPositionIndex];
+    if (!position) {
+      throw new Error(`Invalid lending position index: ${lendingPositionIndex}`);
+    }
+
+    return {
+      userAccount: overrides?.userAccount ?? fromWeb3Pk(position.protocolUserAcc),
+      collateralReserve: overrides?.collateralReserve ?? fromWeb3Pk(position.collateralReserve),
+      debtOracle: overrides?.debtOracle ?? fromWeb3Pk(position.accounting.debt.oracle),
+    };
+  }
+
+  /**
+   * Build the fixed initial-accounts prefix for `rebalance_token`.
+   *
+   * The Rust handler reads these positionally from the front of
+   * `remaining_accounts` (see `RebalanceTokenAccounts::parse`). Returning the
+   * prefix as `initialAccounts` to `createMultiCpiRefs` lets every CPI in the
+   * flash-rebalance bundle deduplicate against these slots, shrinking the
+   * transaction's account list compared to declaring them as named ix
+   * accounts that would force separate copies in the message header.
+   */
+  async getRebalanceTokenInitialAccounts(
+    token: Address,
+    yieldingBank: Address,
+    lpIndex: number,
+    destinationDebtOracle: Address,
+    overrides?: TokenLpPositionAccountOverrides
+  ): Promise<CustomAccountMeta[]> {
+    const tokenData = await this.fetchToken(token);
+    const position = tokenData.data.lendingPositions[lpIndex];
+    if (!position) {
+      throw new Error(`Invalid lending position index: ${lpIndex}`);
+    }
+    const sourceDebtMint = fromWeb3Pk(position.accounting.debt.mint);
+    const sourceDebtTokenProgram = resolveTokenProgram(position.accounting.debt.tokenProgram);
+    const yieldingBankSourceDebtAta = await getAtaAddress(
+      sourceDebtMint,
+      yieldingBank,
+      sourceDebtTokenProgram
+    );
+    const lp = this.getTokenLendingPositionRefreshAccounts(tokenData.data, lpIndex, overrides);
+    return buildRebalanceTokenInitialAccounts({
+      token,
+      yieldingBank,
+      sourceDebtMint,
+      sourceDebtTokenProgram,
+      yieldingBankSourceDebtAta,
+      lpUserAccount: lp.userAccount,
+      sourceDebtOracle: lp.debtOracle,
+      destinationDebtOracle,
+    });
+  }
+
+  /**
+   * Build the initial account pool seed for refresh_token_state.
+   *
+   * These accounts are placed at the front of the deduplicated remaining_accounts
+   * pool (positions 0..N-1), so the index-based TokenRefreshRefs computed by
+   * the builder remain stable whether or not prereq CPIs introduce additional accounts.
+   *
+   * Order:
+   *   1. Per active lending position (in slot order): protocol_user_acc, collateral_reserve, debt_oracle
+   *   2. One YieldingBank PDA per active carry position (in slot order)
+   */
+  async getTokenRefreshAccounts(token: Address): Promise<CustomAccountMeta[]> {
+    const tokenData = await this.fetchToken(token);
+    const accounts: CustomAccountMeta[] = [];
+
+    for (const position of tokenData.data.lendingPositions) {
+      if (lendingPlatformToEnum(position.platform) === LendingPlatform.None) continue;
+      accounts.push(toCustomAccountMeta(fromWeb3Pk(position.protocolUserAcc)));
+      accounts.push(toCustomAccountMeta(fromWeb3Pk(position.collateralReserve)));
+      accounts.push(toCustomAccountMeta(fromWeb3Pk(position.accounting.debt.oracle)));
+    }
+
+    for (const { data: carry } of tokenData.activeCarryPositions) {
+      const baseMint = fromWeb3Pk(carry.yieldingBaseMint);
+      const [bankPda] = await this.pda.deriveYieldingBankPda(baseMint, carry.yieldingBankId);
+      accounts.push(toCustomAccountMeta(bankPda));
+    }
+
+    return accounts;
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  private toRedemptionEpochSnapshot(pda: Address, data: any): RedemptionEpochSnapshot {
+    return {
+      pda,
+      tokenPda: data.header.token.toBase58() as Address,
+      epochId: BigInt(data.header.id.toString()),
+      payer: data.header.payer.toBase58() as Address,
+      status: data.header.status,
+      requestCount: Number(data.sequencing.requestCount.toString()),
+      processedRequestCount: Number(data.sequencing.processedRequestCount.toString()),
+      grossCollateralClaim: toBigInt(data.accounting.grossCollateralClaim),
+      realizedUnwindLoss: toBigInt(data.accounting.realizedUnwindLoss),
+      fundedCollateral: toBigInt(data.accounting.fundedCollateral),
+    };
+  }
+}