@kestrelfi/lyc-sdk 1.0.1

package/dist/sdks/long-yield-carry/scripts/updateTokenMetadata.js

@@ -0,0 +1,194 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+require("./env");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const common_1 = require("common");
+const client_1 = require("../src/client/client");
+const general_1 = require("../src/constants/general");
+const localUtils_1 = require("./localUtils");
+/**
+ * Updates on-chain Metaplex metadata (name, symbol, URI) for a token's mint.
+ *
+ * Usage:
+ *   pnpm run update-token-metadata -- test|prod <TOKEN_PDA|COLLATERAL_SYMBOL> [--name NAME] [--symbol SYMBOL] [--uri URI] [--json PATH] [KEYPAIR_JSON]
+ *
+ * At least one of --name, --symbol, --uri, or --json must be provided.
+ * Omitted fields retain their current on-chain values.
+ * When --json is provided, its fields (name, symbol, uri) override individual flags.
+ *
+ * Examples:
+ *   pnpm run update-token-metadata -- test SOL --name "ySOL" --symbol "ySOL" --uri "https://example.com/ysol.json"
+ *   pnpm run update-token-metadata -- test SOL --name "Long Yield SOL"
+ *   pnpm run update-token-metadata -- prod 7fEA5HTsveMn5HfnXN82nmTniXeWDs6YJuvLyk7qFcNG --uri "https://example.com/new-metadata.json"
+ *   pnpm run update-token-metadata -- prod SOL --json ./docs/example-metadata.json
+ */
+async function main() {
+    const { env, rest } = (0, localUtils_1.parseCliEnvironmentAndRest)("update-token-metadata");
+    const { rest: args, keypairPath: keypairFlagPath } = (0, localUtils_1.extractKeypairFlag)(rest);
+    const { tokenArg, flags, keypairArg } = parseArgs(args);
+    const keypairPath = keypairFlagPath ?? keypairArg ?? general_1.LYC_ADMIN_KEYPAIR_FP[env];
+    const { signer: adminSigner, web3Keypair } = await (0, common_1.loadLocalKeypairWithWeb3)(keypairPath);
+    const provider = (0, common_1.createDefaultAnchorProvider)(env, web3Keypair);
+    const client = new client_1.LongYieldCarryClient(provider, env);
+    const { tokenPda, collateralSymbol } = await (0, localUtils_1.resolveTokenPda)(client, tokenArg);
+    const token = await client.account.fetchToken(tokenPda, { fresh: true });
+    const mint = token.mint;
+    const metadataPda = await (0, common_1.deriveMetadataPda)(mint);
+    const connection = provider.connection;
+    const currentMetadata = await (0, common_1.fetchTokenMetadata)(connection, mint);
+    const isCreate = currentMetadata === null;
+    const currentName = currentMetadata?.name ?? "";
+    const currentSymbol = currentMetadata?.symbol ?? "";
+    const currentUri = currentMetadata?.uri ?? "";
+    const newName = flags.name ?? currentName;
+    const newSymbol = flags.symbol ?? currentSymbol;
+    const newUri = flags.uri ?? currentUri;
+    console.log(`Token PDA:  ${tokenPda} (collateral: ${collateralSymbol ?? "unknown"})`);
+    console.log(`Mint:       ${mint}`);
+    console.log(`Metadata:   ${metadataPda}`);
+    console.log(`Action:     ${isCreate ? "CREATE (no metadata account exists)" : "UPDATE"}`);
+    console.log("");
+    if (!isCreate) {
+        console.log("Current metadata:");
+        console.log(`  name:   "${currentName}"`);
+        console.log(`  symbol: "${currentSymbol}"`);
+        console.log(`  uri:    "${currentUri}"`);
+        console.log("");
+    }
+    console.log("New metadata:");
+    console.log(`  name:   "${newName}"${flags.name || isCreate ? "" : " (unchanged)"}`);
+    console.log(`  symbol: "${newSymbol}"${flags.symbol || isCreate ? "" : " (unchanged)"}`);
+    console.log(`  uri:    "${newUri}"${flags.uri || isCreate ? "" : " (unchanged)"}`);
+    if (!isCreate &&
+        newName === currentName &&
+        newSymbol === currentSymbol &&
+        newUri === currentUri) {
+        console.log("\nNo changes detected — skipping transaction.");
+        return;
+    }
+    const cpiData = isCreate
+        ? await (0, common_1.buildCreateMetadataCpiData)({
+            mint,
+            mintAuthority: tokenPda,
+            payer: adminSigner.address,
+            updateAuthority: tokenPda,
+            data: { name: newName, symbol: newSymbol, uri: newUri },
+        })
+        : await (0, common_1.buildUpdateMetadataCpiData)({
+            mint,
+            updateAuthority: tokenPda,
+            data: { name: newName, symbol: newSymbol, uri: newUri },
+        });
+    const { accounts, refs } = (0, common_1.createCpiRefs)([cpiData]);
+    const plan = await client.tx.updateTokenMetadata.getTx({
+        token: tokenPda,
+        mint,
+        params: {
+            ixRefs: refs,
+            remainingAccounts: accounts,
+        },
+    });
+    const sig = await client.sendTransaction(adminSigner, plan);
+    console.log("");
+    console.log("update_token_metadata succeeded.");
+    console.log("  environment:", env);
+    console.log("  admin:", adminSigner.address);
+    console.log("  signature:", sig);
+}
+function parseArgs(rest) {
+    if (rest.length < 1) {
+        printUsageAndExit();
+    }
+    const tokenArg = rest[0];
+    const flags = {};
+    let keypairArg;
+    let i = 1;
+    while (i < rest.length) {
+        const arg = rest[i];
+        if (arg === "--name" && i + 1 < rest.length) {
+            flags.name = rest[++i];
+        }
+        else if (arg === "--symbol" && i + 1 < rest.length) {
+            flags.symbol = rest[++i];
+        }
+        else if (arg === "--uri" && i + 1 < rest.length) {
+            flags.uri = rest[++i];
+        }
+        else if (arg === "--json" && i + 1 < rest.length) {
+            const jsonPath = path.resolve(process.env.INIT_CWD ?? process.cwd(), rest[++i]);
+            const raw = JSON.parse(fs.readFileSync(jsonPath, "utf-8"));
+            if (raw.name)
+                flags.name = raw.name;
+            if (raw.symbol)
+                flags.symbol = raw.symbol;
+            if (raw.uri)
+                flags.uri = raw.uri;
+        }
+        else if (!arg.startsWith("--") && !keypairArg) {
+            keypairArg = arg;
+        }
+        else {
+            console.error(`Unknown or incomplete argument: ${arg}`);
+            printUsageAndExit();
+        }
+        i++;
+    }
+    if (!flags.name && !flags.symbol && !flags.uri) {
+        console.error("Error: At least one of --name, --symbol, --uri, or --json must be provided.\n");
+        printUsageAndExit();
+    }
+    return { tokenArg, flags, keypairArg };
+}
+function printUsageAndExit() {
+    console.error("Usage: pnpm run update-token-metadata -- [test|prod] <TOKEN_PDA|COLLATERAL_SYMBOL> [--name NAME] [--symbol SYMBOL] [--uri URI] [--json PATH] [KEYPAIR_JSON]\n\n" +
+        "Arguments:\n" +
+        "  TOKEN_PDA|COLLATERAL_SYMBOL  Token PDA address or collateral symbol (e.g. SOL)\n" +
+        "  --name NAME                  New token name\n" +
+        "  --symbol SYMBOL              New token symbol\n" +
+        "  --uri URI                    New metadata URI\n" +
+        "  --json PATH                  Path to a JSON file with name/symbol/uri fields\n" +
+        "  KEYPAIR_JSON                 Optional path to admin keypair JSON\n\n" +
+        "At least one of --name, --symbol, --uri, or --json must be provided.\n" +
+        "Omitted fields retain their current on-chain values.");
+    process.exit(1);
+}
+main()
+    .then(() => console.log("Finished"))
+    .catch((err) => {
+    console.error(err);
+    process.exit(1);
+});

package/dist/sdks/long-yield-carry/scripts/updateYieldingBankConfig.d.ts

@@ -0,0 +1 @@
+import "./env";

package/dist/sdks/long-yield-carry/scripts/updateYieldingBankConfig.js

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+require("./env");
+const kit_1 = require("@solana/kit");
+const common_1 = require("common");
+const client_1 = require("../src/client/client");
+const general_1 = require("../src/constants/general");
+const localUtils_1 = require("./localUtils");
+const USAGE = `Usage:
+
+  pnpm run update-yb-config -- [test|prod] <YIELDING_BANK> <REDEMPTION_MINT>
+
+  YIELDING_BANK:  yielding bank PDA address
+  REDEMPTION_MINT: new default redemption mint (common registry symbol like USD* or a mint address)
+
+  Examples:
+    pnpm run update-yb-config -- test 7fEA5HTs... USD*`;
+function resolveMint(arg) {
+    const trimmed = arg.trim();
+    const symbol = trimmed.toUpperCase();
+    const mintInfo = common_1.mints.get(symbol);
+    if (mintInfo) {
+        return { mint: mintInfo.address, label: symbol };
+    }
+    if (!(0, localUtils_1.isValidPubkeyString)(trimmed)) {
+        throw new Error(`Unknown mint "${arg}". Use a common mint symbol (for example USD*) or a mint address.`);
+    }
+    return { mint: (0, kit_1.address)(trimmed), label: trimmed };
+}
+async function main() {
+    const { env, rest } = (0, localUtils_1.parseCliEnvironmentAndRest)("update-yb-config");
+    const { rest: args, keypairPath: keypairFlagPath } = (0, localUtils_1.extractKeypairFlag)(rest);
+    const yieldingBankArg = args[0];
+    const redemptionMintArg = args[1];
+    if (yieldingBankArg === undefined || redemptionMintArg === undefined) {
+        console.error(USAGE);
+        process.exit(1);
+    }
+    if (!(0, localUtils_1.isValidPubkeyString)(yieldingBankArg)) {
+        console.error(`Invalid yielding bank address "${yieldingBankArg}".`);
+        process.exit(1);
+    }
+    let redemptionMint;
+    let redemptionLabel;
+    try {
+        ({ mint: redemptionMint, label: redemptionLabel } = resolveMint(redemptionMintArg));
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : err);
+        process.exit(1);
+    }
+    const yieldingBank = (0, kit_1.address)(yieldingBankArg);
+    const { signer: adminSigner, web3Keypair } = await (0, common_1.loadLocalKeypairWithWeb3)(keypairFlagPath ?? general_1.LYC_ADMIN_KEYPAIR_FP[env]);
+    const provider = (0, common_1.createDefaultAnchorProvider)(env, web3Keypair);
+    const client = new client_1.LongYieldCarryClient(provider, env);
+    const bank = await client.account.fetchYieldingBank(yieldingBank);
+    const currentRedemptionMint = bank.data.config.defaultRedemptionMint;
+    console.log("Yielding bank:", yieldingBank);
+    console.log("  base mint:", bank.baseMint);
+    console.log("");
+    console.log("Current config:");
+    console.log("  defaultRedemptionMint:", currentRedemptionMint);
+    console.log("");
+    console.log("New config:");
+    console.log("  defaultRedemptionMint:", redemptionMint, `(${redemptionLabel})`);
+    const plan = await client.tx.updateYieldingBankConfig.getTx({
+        yieldingBank,
+        params: {
+            defaultRedemptionMint: redemptionMint,
+        },
+    });
+    const sig = await client.sendTransaction(adminSigner, plan);
+    console.log("");
+    console.log("update_yielding_bank_config succeeded.");
+    console.log("  environment:", env);
+    console.log("  admin (must match on-chain):", general_1.PROTOCOL_ADMIN[env]);
+    console.log("  signature:", sig);
+}
+main()
+    .then(() => console.log("Finished"))
+    .catch((err) => {
+    console.error(err);
+    process.exit(1);
+});

package/dist/sdks/long-yield-carry/scripts/withdrawUnlentCollateral.d.ts

@@ -0,0 +1 @@
+import "./env";

package/dist/sdks/long-yield-carry/scripts/withdrawUnlentCollateral.js

@@ -0,0 +1,140 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+require("./env");
+const common_1 = require("common");
+const client_1 = require("../src/client/client");
+const general_1 = require("../src/constants/general");
+const lycLendingPositionManager_1 = require("../src/services/carry/lycLendingPositionManager");
+const localUtils_1 = require("./localUtils");
+/** Mirrors on-chain `UTILIZATION_RATE_DEVIATION_THRESHOLD_BPS` (150 = 1.5%). */
+const UTILIZATION_RATE_DEVIATION_THRESHOLD_BPS = 150;
+const USAGE = `Withdraw collateral from a lending position into the token PDA's unlent reserves.
+
+Requires the **manager** keypair. Withdraws the maximum collateral allowed without
+pushing utilization above the position's target band (same constraint as
+top_up_unlent_reserves on-chain). Debt-free positions withdraw all supply.
+
+Usage:
+  pnpm run withdraw-unlent -- [test|prod] <TOKEN> <LP_INDEX|DEBT_SYMBOL> [KEYPAIR_JSON]
+  From repo root: pnpm run lyc:withdraw-unlent -- [test|prod] <TOKEN> <LP_INDEX|DEBT_SYMBOL] [KEYPAIR_JSON]
+
+Examples:
+  pnpm run withdraw-unlent -- test SOL USDC
+  pnpm run withdraw-unlent -- test SOL 0 --keypair ~/.config/solana/tp-lyc-manager-test.json
+
+Keypair defaults to ~/.config/solana/tp-lyc-manager-{env}.json`;
+async function main() {
+    const { env, rest } = (0, localUtils_1.parseCliEnvironmentAndRest)("withdraw-unlent");
+    const { rest: args, keypairPath: keypairFlagPath } = (0, localUtils_1.extractKeypairFlag)(rest);
+    const tokenArg = args[0];
+    const positionIdentifier = args[1];
+    if (tokenArg === undefined || positionIdentifier === undefined) {
+        console.error(USAGE);
+        process.exit(1);
+    }
+    if (args.length > 3) {
+        console.error(USAGE);
+        process.exit(1);
+    }
+    const keypairPath = keypairFlagPath ?? args[2] ?? general_1.LYC_MANAGER_KEYPAIR_FP[env];
+    const { signer: managerSigner, web3Keypair } = await (0, common_1.loadLocalKeypairWithWeb3)(keypairPath);
+    const provider = (0, common_1.createDefaultAnchorProvider)(env, web3Keypair);
+    const client = new client_1.LongYieldCarryClient(provider, env);
+    const { tokenPda, collateralSymbol } = await (0, localUtils_1.resolveTokenPda)(client, tokenArg);
+    let token = await client.account.fetchToken(tokenPda, { fresh: true });
+    const lendingPositionIndex = (0, localUtils_1.resolveLendingPositionIndex)(token, positionIdentifier, tokenPda);
+    const position = token.data.lendingPositions[lendingPositionIndex];
+    const debtMint = (0, common_1.fromWeb3Pk)(position.accounting.debt.mint);
+    const debtLabel = common_1.mints.get(debtMint)?.symbol ?? debtMint;
+    console.log("Withdraw unlent collateral");
+    console.log("  environment:", env);
+    console.log("  manager:", managerSigner.address);
+    console.log("  token:", tokenPda, collateralSymbol ? `(${collateralSymbol})` : "");
+    console.log("  lending position index:", lendingPositionIndex);
+    console.log("  debt mint:", debtLabel);
+    const collateralRaw = (0, common_1.toBigInt)(position.accounting.collateral);
+    if (collateralRaw === BigInt(0)) {
+        console.error("Lending position has no supplied collateral to withdraw.");
+        process.exit(1);
+    }
+    const collateralUiBefore = (0, common_1.toUiAmount)(collateralRaw, token.data.collateral.decimals);
+    console.log(`  supplied collateral: ${collateralUiBefore}`);
+    console.log("\nRefreshing token state...");
+    const refreshPlan = await client.tx.refreshTokens.getTx({
+        signer: managerSigner.address,
+        params: { tokens: [tokenPda] },
+    });
+    await client.sendTransaction(managerSigner, refreshPlan);
+    client.clearAllCache();
+    token = await client.account.fetchToken(tokenPda, { fresh: true });
+    const withdrawUiAmount = await computeMaxWithdrawUiAmount(client, token, lendingPositionIndex);
+    if (withdrawUiAmount === 0) {
+        console.error("No collateral can be withdrawn without exceeding the position utilization target. " +
+            "Run decrease-carry or deleverage-all first to free headroom.");
+        process.exit(1);
+    }
+    const withdrawLabel = withdrawUiAmount === "all" ? "all" : withdrawUiAmount.toFixed(9);
+    console.log(`\nWithdrawing ${withdrawLabel} collateral to unlent reserves...`);
+    const topUpPlan = await client.tx.topUpUnlentReserves.getTx({
+        token: tokenPda,
+        params: {
+            lendingPositionIndex,
+            uiAmount: withdrawUiAmount,
+        },
+    });
+    const sig = await client.sendTransaction(managerSigner, topUpPlan);
+    console.log("\ntop_up_unlent_reserves succeeded.");
+    console.log("  signature:", sig);
+    console.log("  withdrawn:", withdrawLabel);
+}
+/**
+ * Maximum withdraw allowed by `top_up_unlent_reserves`: all collateral when
+ * debt-free; otherwise the largest partial withdraw that keeps post-withdraw
+ * utilization at or below target + deviation margin.
+ */
+async function computeMaxWithdrawUiAmount(client, token, lendingPositionIndex) {
+    const position = token.data.lendingPositions[lendingPositionIndex];
+    const decimals = token.data.collateral.decimals;
+    const collateralUi = (0, common_1.toUiAmount)(position.accounting.collateral, decimals);
+    if ((0, common_1.toBigInt)(position.accounting.debt.amount) === BigInt(0)) {
+        return "all";
+    }
+    const manager = await lycLendingPositionManager_1.LycLendingPositionManager.create(client.getLendingPlatformClient(position).data, position);
+    const target = position.config.targetUtilizationRateBps;
+    const margin = Math.floor((target * UTILIZATION_RATE_DEVIATION_THRESHOLD_BPS) / 10000);
+    const upperBoundBps = Math.min(target + margin, 10000);
+    const minWithdrawUi = 1 / 10 ** decimals;
+    try {
+        const postUtilAtMin = await manager.calcPostWithdrawalUtilizationRateBps(minWithdrawUi);
+        if (postUtilAtMin > upperBoundBps) {
+            return 0;
+        }
+    }
+    catch {
+        return 0;
+    }
+    let lo = minWithdrawUi;
+    let hi = collateralUi * (1 - 1 / 10 ** decimals);
+    for (let i = 0; i < 50; i += 1) {
+        const mid = (lo + hi) / 2;
+        try {
+            const postUtil = await manager.calcPostWithdrawalUtilizationRateBps(mid);
+            if (postUtil <= upperBoundBps) {
+                lo = mid;
+            }
+            else {
+                hi = mid;
+            }
+        }
+        catch {
+            hi = mid;
+        }
+    }
+    return lo >= minWithdrawUi ? lo : 0;
+}
+main()
+    .then(() => console.log("Finished"))
+    .catch((err) => {
+    console.error(err);
+    process.exit(1);
+});

package/dist/sdks/long-yield-carry/src/client/account.d.ts

@@ -0,0 +1,152 @@
+import { type Address, type Rpc, type SolanaRpcApi } from "@solana/kit";
+import { Program } from "@anchor-lang/core";
+import { LongYieldCarry } from "../idl/long_yield_carry";
+import { LYCToken, type TokenAccountData } from "../models/lycToken";
+import { LYCYieldingBank } from "../models/yieldingBank";
+import { BaseAccountClient, CustomAccountMeta } from "common";
+import type { PdaClient } from "./pda";
+import type { RedemptionEpochSnapshot, TokenLpPositionAccountOverrides, UserHolding, YieldingBankAllocationConfig, YieldingBankExternalLiquiditySource } from "./types";
+/** DataCache category for LYC `Token` accounts (used when clearing cache after writes). */
+export declare const LYC_TOKEN_CACHE_CATEGORY = "token";
+export declare const YIELDING_BANK_CACHE_CATEGORY = "yieldingBank";
+export declare const REDEMPTION_EPOCH_CACHE_CATEGORY = "redemptionEpoch";
+export declare const IGNORED_LYC_TOKEN_ADDRESSES: Set<string>;
+/**
+ * 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 declare class AccountClient extends BaseAccountClient {
+    private readonly program;
+    readonly pda: PdaClient;
+    constructor(program: Program<LongYieldCarry>, pda: PdaClient, rpc: Rpc<SolanaRpcApi>);
+    /** Fetch and deserialize a Token account by its PDA address. */
+    fetchToken(token: Address, opts?: {
+        fresh?: boolean;
+    }): Promise<LYCToken>;
+    /** Fetch and deserialize multiple Token accounts by their PDA addresses. */
+    fetchTokens(tokens: Address[]): Promise<LYCToken[]>;
+    /**
+     * 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.
+     */
+    fetchAllTokens(opts?: {
+        fresh?: boolean;
+    }): Promise<LYCToken[]>;
+    /** Fetch and deserialize a YieldingBank account by its PDA address. */
+    fetchYieldingBank(bank: Address): Promise<LYCYieldingBank>;
+    /** Fetch and deserialize multiple YieldingBank accounts by their PDA addresses. */
+    fetchYieldingBanks(banks: Address[]): Promise<LYCYieldingBank[]>;
+    /** Fetch all YieldingBank accounts owned by the program. */
+    fetchAllYieldingBanks(): Promise<LYCYieldingBank[]>;
+    /** Fetch and deserialize a RedemptionEpoch account by its PDA address. */
+    fetchRedemptionEpoch(epochPda: Address, opts?: {
+        fresh?: boolean;
+    }): Promise<RedemptionEpochSnapshot>;
+    /** Fetch all RedemptionEpoch accounts owned by the program. */
+    fetchAllRedemptionEpochs(opts?: {
+        fresh?: boolean;
+    }): Promise<RedemptionEpochSnapshot[]>;
+    /**
+     * 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.
+     */
+    fetchUserHoldings(owner: Address, opts?: {
+        includeEmpty?: boolean;
+        tokens?: LYCToken[];
+        priceMap?: Partial<Record<Address, number>>;
+    }): Promise<UserHolding[]>;
+    /** Fetch all Token and YieldingBank accounts in parallel. */
+    fetchAllTokensAndYieldingBanks(): Promise<{
+        tokens: LYCToken[];
+        yieldingBanks: LYCYieldingBank[];
+    }>;
+    /**
+     * 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.
+     */
+    getYieldingBankRefreshAccounts(bank: Address, newAllocation?: YieldingBankAllocationConfig, externalLiquiditySources?: YieldingBankExternalLiquiditySource[]): Promise<CustomAccountMeta[]>;
+    /**
+     * 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.
+     */
+    getCarryTradeAccounts(token: Address, yieldingBank: Address, lendingPositionIndex: number, lendingPositionUserAccount?: Address): Promise<CustomAccountMeta[]>;
+    /**
+     * 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): {
+        userAccount: Address;
+        collateralReserve: Address;
+        debtOracle: Address;
+    };
+    /**
+     * 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.
+     */
+    getRebalanceTokenInitialAccounts(token: Address, yieldingBank: Address, lpIndex: number, destinationDebtOracle: Address, overrides?: TokenLpPositionAccountOverrides): Promise<CustomAccountMeta[]>;
+    /**
+     * 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)
+     */
+    getTokenRefreshAccounts(token: Address): Promise<CustomAccountMeta[]>;
+    private toRedemptionEpochSnapshot;
+}