@kestrelfi/lyc-sdk 1.0.1

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

@@ -0,0 +1,115 @@
+/**
+ * Long Yield Carry program client.
+ *
+ * Composes PDA derivation, account fetching, instruction building, and
+ * transaction composition behind a single entry point.
+ *
+ * The Anchor program ID flows through to all sub-clients — no global state
+ * required.
+ *
+ * Usage:
+ *   const client = new LongYieldCarryClient(provider, "local");
+ *   const [pda, bump] = client.pda.token(mintAddress);
+ *   const ix = await client.tx.createToken.getIx({
+ *     mint,
+ *     collateralMint,
+ *     params,
+ *   });
+ *   const data = await client.account.token(pda);
+ *   const tx = await client.tx.collectInterest.getTx({ manager: manager, token: token, params: { yieldingBank } });
+ */
+import { AnchorProvider } from "@anchor-lang/core";
+import { type Instruction, type Rpc, type Signature, type SolanaRpcApi, type TransactionSigner } from "@solana/kit";
+import { LendingPlatform, type Environment, type SendTransactionOptionsWithPostSuccess, type SwapClient, type TransactionPlan } from "common";
+import { KaminoClient, type LendingPlatformClientBase, type LendingPlatformData, type OutstandingIncentive } from "lending-platforms";
+import { PdaClient } from "./pda";
+import { AccountClient } from "./account";
+import type { LongYieldCarryTransactionPlan } from "./types";
+import type { LYCToken, TokenLendingPositionData } from "../models/lycToken";
+import { LendingPlatformClientRegistry, type SupportedLendingPlatformClients } from "./lendingPlatformClients";
+import { TransactionClient } from "./transaction";
+export interface LongYieldCarryClientOptions {
+    /**
+     * Swap client override. Replaces the default `AggSwapClient` for all swaps
+     * (including collect_interest). Useful in tests that need a restricted routing
+     * client (e.g. Surfpool direct-route-only client).
+     */
+    swapClient?: SwapClient;
+    /**
+     * Optional overrides for internally managed lending platform clients.
+     * These are primarily useful in tests.
+     */
+    lendingPlatformClients?: Partial<SupportedLendingPlatformClients>;
+}
+/** Claimable incentives keyed by the token's lending position index. */
+export type OutstandingIncentivesByPosition = Map<number, OutstandingIncentive[]>;
+export declare class LongYieldCarryClient {
+    /**
+     * Deployment tier for this client (`local`, `test`, `prod`) — drives program ID,
+     * RPC URL, and authority constants passed into transaction builders.
+     */
+    readonly environment: Environment;
+    /** Shared RPC client used by SDK send helpers */
+    readonly rpc: Rpc<SolanaRpcApi>;
+    /** PDA derivation utilities */
+    readonly pda: PdaClient;
+    /** On-chain account fetchers */
+    readonly account: AccountClient;
+    /** Transaction/instruction builders */
+    readonly tx: TransactionClient;
+    /** Aggregated swap client (Perena for USD* pairs, Jupiter fallback) */
+    readonly swap: SwapClient;
+    /** Shared registry of protocol-specific lending clients */
+    readonly lendingPlatformClients: LendingPlatformClientRegistry;
+    /**
+     * @param provider - Anchor provider (connection + wallet)
+     * @param environment - Optional environment override ("local", "test", "prod").
+     *                      Determines which program ID and RPC URL to use. Defaults to the IDL address.
+     * @param options - Optional configuration overrides (e.g. custom swap client for tests).
+     */
+    /**
+     * Create a read-only client with a throwaway keypair.
+     *
+     * Use this for services that only need to read on-chain state (e.g. the
+     * price ingestion Lambda) and never sign transactions.
+     */
+    static readOnly(env: Environment): LongYieldCarryClient;
+    constructor(provider: AnchorProvider, environment?: Environment, options?: LongYieldCarryClientOptions);
+    /**
+     * Sign, send, and confirm a transaction, then apply any post-success cache
+     * invalidations embedded in the transaction plan.
+     */
+    sendTransaction(payer: TransactionSigner, instructionsOrPlan: Instruction[] | TransactionPlan, options?: SendTransactionOptionsWithPostSuccess): Promise<Signature>;
+    /**
+     * Returns currently claimable lending incentives keyed by lending position
+     * index. Each value contains that position's claimable incentive entries as
+     * reported by the underlying lending-platform client.
+     *
+     * `minUiAmount` filters out dust rewards (UI-denominated, per reward token);
+     * defaults to {@link DEFAULT_MIN_INCENTIVE_UI_AMOUNT} so harvesting never pays
+     * a transaction fee for an economically negligible balance.
+     */
+    getOutstandingIncentives(token: LYCToken, minUiAmount?: number, log?: (msg: string) => void): Promise<OutstandingIncentivesByPosition>;
+    /**
+     * Drops every cached entry across all sub-clients (account data, Kamino
+     * lending data, swap quotes). The next read through any sub-client will
+     * hit the RPC / API fresh.
+     *
+     * Use this between sequential phases that mutate on-chain state so that
+     * the later phase doesn't operate on stale snapshots.
+     */
+    clearAllCache(): void;
+    /**
+     * Clears cached data that a confirmed transaction has made stale.
+     *
+     * Call this after a transaction built from a `LongYieldCarryTransactionPlan`
+     * has been confirmed by an external sender (e.g. the backend
+     * `TransactionService`). The built-in `sendTransaction` applies these
+     * automatically; this method exists for callers that sign/send through a
+     * different path.
+     */
+    applyCacheInvalidations(plan: LongYieldCarryTransactionPlan): void;
+    getLendingPlatformClient(position: TokenLendingPositionData): LendingPlatformClientBase<LendingPlatformData>;
+    getLendingPlatformClientByPlatform(platform: LendingPlatform.Kamino): KaminoClient;
+    getLendingPlatformClientByPlatform(platform: LendingPlatform): LendingPlatformClientBase<LendingPlatformData>;
+}

package/dist/sdks/long-yield-carry/src/client/client.js

@@ -0,0 +1,166 @@
+"use strict";
+/**
+ * Long Yield Carry program client.
+ *
+ * Composes PDA derivation, account fetching, instruction building, and
+ * transaction composition behind a single entry point.
+ *
+ * The Anchor program ID flows through to all sub-clients — no global state
+ * required.
+ *
+ * Usage:
+ *   const client = new LongYieldCarryClient(provider, "local");
+ *   const [pda, bump] = client.pda.token(mintAddress);
+ *   const ix = await client.tx.createToken.getIx({
+ *     mint,
+ *     collateralMint,
+ *     params,
+ *   });
+ *   const data = await client.account.token(pda);
+ *   const tx = await client.tx.collectInterest.getTx({ manager: manager, token: token, params: { yieldingBank } });
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LongYieldCarryClient = void 0;
+const core_1 = require("@anchor-lang/core");
+const kit_1 = require("@solana/kit");
+const common_1 = require("common");
+const lending_platforms_1 = require("lending-platforms");
+const swap_aggregator_1 = require("swap-aggregator");
+const long_yield_carry_1 = require("../idl/long_yield_carry");
+const general_1 = require("../constants/general");
+const pda_1 = require("./pda");
+const account_1 = require("./account");
+const lendingPlatformClients_1 = require("./lendingPlatformClients");
+const externalLiquidityResolver_1 = require("./externalLiquidityResolver");
+const transaction_1 = require("./transaction");
+class LongYieldCarryClient {
+    /**
+     * @param provider - Anchor provider (connection + wallet)
+     * @param environment - Optional environment override ("local", "test", "prod").
+     *                      Determines which program ID and RPC URL to use. Defaults to the IDL address.
+     * @param options - Optional configuration overrides (e.g. custom swap client for tests).
+     */
+    /**
+     * Create a read-only client with a throwaway keypair.
+     *
+     * Use this for services that only need to read on-chain state (e.g. the
+     * price ingestion Lambda) and never sign transactions.
+     */
+    static readOnly(env) {
+        return new LongYieldCarryClient((0, common_1.createReadOnlyAnchorProvider)(env), env);
+    }
+    constructor(provider, environment, options) {
+        const env = environment ?? "local";
+        this.environment = env;
+        const rpcUrl = (0, common_1.getRpcUrl)(env);
+        const rpcUrls = (0, common_1.getRpcUrls)(env);
+        const idl = environment ? { ...long_yield_carry_1.IDL, address: general_1.PROGRAM_ID[environment] } : long_yield_carry_1.IDL;
+        const program = new core_1.Program(idl, provider);
+        this.rpc = (0, common_1.createRpc)(env);
+        this.pda = new pda_1.PdaClient((0, kit_1.address)(program.programId.toBase58()));
+        this.account = new account_1.AccountClient(program, this.pda, this.rpc);
+        const kaminoClient = options?.lendingPlatformClients?.kamino ?? new lending_platforms_1.KaminoClient(rpcUrl, rpcUrls);
+        this.lendingPlatformClients = new lendingPlatformClients_1.LendingPlatformClientRegistry({
+            kamino: kaminoClient,
+        });
+        this.swap = options?.swapClient ?? (0, swap_aggregator_1.createAggSwapClient)(rpcUrl, env);
+        const externalLiquidityResolver = new externalLiquidityResolver_1.LongYieldCarryExternalLiquidityResolver(rpcUrl);
+        this.tx = new transaction_1.TransactionClient({
+            rpc: this.rpc,
+            program,
+            account: this.account,
+            pda: this.pda,
+            swap: this.swap,
+            externalLiquidityResolver,
+            environment: environment ?? "local",
+            lendingPlatformClients: this.lendingPlatformClients,
+        });
+    }
+    /**
+     * Sign, send, and confirm a transaction, then apply any post-success cache
+     * invalidations embedded in the transaction plan.
+     */
+    async sendTransaction(payer, instructionsOrPlan, options) {
+        const plan = Array.isArray(instructionsOrPlan)
+            ? undefined
+            : instructionsOrPlan;
+        return (0, common_1.signSendAndConfirmTransaction)(this.rpc, payer, instructionsOrPlan, {
+            ...options,
+            onSuccess: () => {
+                if (plan)
+                    this.applyCacheInvalidations(plan);
+                options?.onSuccess?.();
+            },
+        });
+    }
+    /**
+     * Returns currently claimable lending incentives keyed by lending position
+     * index. Each value contains that position's claimable incentive entries as
+     * reported by the underlying lending-platform client.
+     *
+     * `minUiAmount` filters out dust rewards (UI-denominated, per reward token);
+     * defaults to {@link DEFAULT_MIN_INCENTIVE_UI_AMOUNT} so harvesting never pays
+     * a transaction fee for an economically negligible balance.
+     */
+    async getOutstandingIncentives(token, minUiAmount = general_1.DEFAULT_MIN_INCENTIVE_UI_AMOUNT, log) {
+        const positionIncentives = await Promise.all(token.activeLendingPositions.map(async ({ index, data: position }) => {
+            log?.(`\n[getOutstandingIncentives] position #${index} userAcc=${(0, common_1.fromWeb3Pk)(position.protocolUserAcc).slice(0, 6)}…`);
+            const incentives = await this.lendingPlatformClients
+                .getForPosition(position)
+                .getOutstandingIncentives((0, common_1.fromWeb3Pk)(position.protocolUserAcc), minUiAmount, log);
+            return { index, incentives };
+        }));
+        const incentivesByPosition = new Map();
+        for (const { index, incentives } of positionIncentives) {
+            const known = incentives.filter((i) => common_1.mints.get(i.mint) !== undefined);
+            const unknown = incentives.filter((i) => common_1.mints.get(i.mint) === undefined);
+            if (unknown.length > 0) {
+                log?.(`  position #${index}: ${unknown.length} incentive(s) skipped — mint not in registry: ${unknown.map((i) => i.mint.slice(0, 6) + "…").join(", ")}`);
+            }
+            if (known.length > 0) {
+                incentivesByPosition.set(index, known);
+            }
+        }
+        return incentivesByPosition;
+    }
+    /**
+     * Drops every cached entry across all sub-clients (account data, Kamino
+     * lending data, swap quotes). The next read through any sub-client will
+     * hit the RPC / API fresh.
+     *
+     * Use this between sequential phases that mutate on-chain state so that
+     * the later phase doesn't operate on stale snapshots.
+     */
+    clearAllCache() {
+        this.account.dataCache.clearAllCache();
+        for (const lpClient of this.lendingPlatformClients.getAll()) {
+            lpClient.data.clearCache();
+        }
+    }
+    /**
+     * Clears cached data that a confirmed transaction has made stale.
+     *
+     * Call this after a transaction built from a `LongYieldCarryTransactionPlan`
+     * has been confirmed by an external sender (e.g. the backend
+     * `TransactionService`). The built-in `sendTransaction` applies these
+     * automatically; this method exists for callers that sign/send through a
+     * different path.
+     */
+    applyCacheInvalidations(plan) {
+        const invalidations = plan.postSuccessCacheInvalidations ?? [];
+        for (const lpClient of this.lendingPlatformClients.getAll()) {
+            lpClient.applyPostSuccessCacheInvalidations(invalidations);
+        }
+        (0, common_1.applyDataCacheTransactionInvalidations)(this.account.dataCache, invalidations, {
+            tokenPdaCategory: account_1.LYC_TOKEN_CACHE_CATEGORY,
+            yieldingBankPdaCategory: account_1.YIELDING_BANK_CACHE_CATEGORY,
+        });
+    }
+    getLendingPlatformClient(position) {
+        return this.lendingPlatformClients.getForPosition(position);
+    }
+    getLendingPlatformClientByPlatform(platform) {
+        return this.lendingPlatformClients.getByPlatform(platform);
+    }
+}
+exports.LongYieldCarryClient = LongYieldCarryClient;

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

@@ -0,0 +1,13 @@
+import type { Address } from "@solana/kit";
+import { type CpiData, type TransactionCacheInvalidation } from "common";
+import type { YieldingBankExternalLiquiditySource } from "./types";
+import type { AccountClient } from "./account";
+export interface YieldingBankRefreshExternalLiquidity {
+    externalLiquiditySources: YieldingBankExternalLiquiditySource[];
+    postSuccessCacheInvalidations: TransactionCacheInvalidation[];
+}
+export declare class LongYieldCarryExternalLiquidityResolver {
+    private readonly perena;
+    constructor(rpcUrl: string);
+    resolveYieldingBankRefreshExternalLiquidity(accountClient: AccountClient, yieldingBank: Address, cpiData?: readonly CpiData[]): Promise<YieldingBankRefreshExternalLiquidity>;
+}

package/dist/sdks/long-yield-carry/src/client/externalLiquidityResolver.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LongYieldCarryExternalLiquidityResolver = void 0;
+const common_1 = require("common");
+const perena_helpers_1 = require("perena-helpers");
+class LongYieldCarryExternalLiquidityResolver {
+    constructor(rpcUrl) {
+        this.perena = new perena_helpers_1.PerenaClient(rpcUrl);
+    }
+    async resolveYieldingBankRefreshExternalLiquidity(accountClient, yieldingBank, cpiData = []) {
+        const usdStarJuniorMint = common_1.mints.get("USD*-J");
+        if (!usdStarJuniorMint) {
+            return { externalLiquiditySources: [], postSuccessCacheInvalidations: [] };
+        }
+        const bank = await accountClient.fetchYieldingBank(yieldingBank);
+        if (!bank.findAssetHolding(usdStarJuniorMint.address)) {
+            return { externalLiquiditySources: [], postSuccessCacheInvalidations: [] };
+        }
+        const withdrawalQueues = (0, common_1.dedupeOrderedAddresses)([
+            ...(await this.perena.getActiveWithdrawalQueues(yieldingBank)),
+            ...(0, perena_helpers_1.getPerenaWithdrawalQueueAddressesFromCpiData)(cpiData),
+        ]);
+        return {
+            externalLiquiditySources: withdrawalQueues.map((account) => ({
+                mint: usdStarJuniorMint.address,
+                account,
+            })),
+            postSuccessCacheInvalidations: withdrawalQueues.length
+                ? [this.perena.getActiveWithdrawalQueuesCacheInvalidation(yieldingBank)]
+                : [],
+        };
+    }
+}
+exports.LongYieldCarryExternalLiquidityResolver = LongYieldCarryExternalLiquidityResolver;

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

@@ -0,0 +1,10 @@
+export { LongYieldCarryClient, type LongYieldCarryClientOptions } from "./client";
+export * from "./transaction";
+export { LendingPlatformClientRegistry, type SupportedLendingPlatformClients, } from "./lendingPlatformClients";
+export { assertCollectInterestPlanHasPositiveRedemptions, buildCollectInterestPlan, } from "./plans/collectInterest";
+export { buildDecreaseCarryPositionPlan } from "./plans/decreaseCarryPosition";
+export * from "./types";
+export { LYCToken } from "../models/lycToken";
+export type { TokenAccountData, TokenCarryPositionData, IndexedCarryPosition, } from "../models/lycToken";
+export { LYCYieldingBank } from "../models/yieldingBank";
+export * from "../types";

package/dist/sdks/long-yield-carry/src/client/index.js

@@ -0,0 +1,33 @@
+"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 __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LYCYieldingBank = exports.LYCToken = exports.buildDecreaseCarryPositionPlan = exports.buildCollectInterestPlan = exports.assertCollectInterestPlanHasPositiveRedemptions = exports.LendingPlatformClientRegistry = exports.LongYieldCarryClient = void 0;
+var client_1 = require("./client");
+Object.defineProperty(exports, "LongYieldCarryClient", { enumerable: true, get: function () { return client_1.LongYieldCarryClient; } });
+__exportStar(require("./transaction"), exports);
+var lendingPlatformClients_1 = require("./lendingPlatformClients");
+Object.defineProperty(exports, "LendingPlatformClientRegistry", { enumerable: true, get: function () { return lendingPlatformClients_1.LendingPlatformClientRegistry; } });
+var collectInterest_1 = require("./plans/collectInterest");
+Object.defineProperty(exports, "assertCollectInterestPlanHasPositiveRedemptions", { enumerable: true, get: function () { return collectInterest_1.assertCollectInterestPlanHasPositiveRedemptions; } });
+Object.defineProperty(exports, "buildCollectInterestPlan", { enumerable: true, get: function () { return collectInterest_1.buildCollectInterestPlan; } });
+var decreaseCarryPosition_1 = require("./plans/decreaseCarryPosition");
+Object.defineProperty(exports, "buildDecreaseCarryPositionPlan", { enumerable: true, get: function () { return decreaseCarryPosition_1.buildDecreaseCarryPositionPlan; } });
+__exportStar(require("./types"), exports);
+var lycToken_1 = require("../models/lycToken");
+Object.defineProperty(exports, "LYCToken", { enumerable: true, get: function () { return lycToken_1.LYCToken; } });
+var yieldingBank_1 = require("../models/yieldingBank");
+Object.defineProperty(exports, "LYCYieldingBank", { enumerable: true, get: function () { return yieldingBank_1.LYCYieldingBank; } });
+__exportStar(require("../types"), exports);

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

@@ -0,0 +1,19 @@
+import { LendingPlatform } from "common";
+import type { KaminoClient, LendingPlatformClientBase, LendingPlatformData } from "lending-platforms";
+import type { TokenLendingPositionData } from "../models/lycToken";
+export interface SupportedLendingPlatformClients {
+    kamino: KaminoClient;
+}
+/**
+ * Central registry for protocol-specific lending clients used throughout the
+ * long-yield-carry SDK.
+ */
+export declare class LendingPlatformClientRegistry {
+    private readonly kaminoClient;
+    constructor(clients: SupportedLendingPlatformClients);
+    getAll(): LendingPlatformClientBase<LendingPlatformData>[];
+    getPlatformForPosition(position: TokenLendingPositionData): LendingPlatform;
+    getForPosition(position: TokenLendingPositionData): LendingPlatformClientBase<LendingPlatformData>;
+    getByPlatform(platform: LendingPlatform.Kamino): KaminoClient;
+    getByPlatform(platform: LendingPlatform): LendingPlatformClientBase<LendingPlatformData>;
+}

package/dist/sdks/long-yield-carry/src/client/lendingPlatformClients.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LendingPlatformClientRegistry = void 0;
+const common_1 = require("common");
+/**
+ * Central registry for protocol-specific lending clients used throughout the
+ * long-yield-carry SDK.
+ */
+class LendingPlatformClientRegistry {
+    constructor(clients) {
+        this.kaminoClient = clients.kamino;
+    }
+    getAll() {
+        return [this.kaminoClient];
+    }
+    getPlatformForPosition(position) {
+        return (0, common_1.lendingPlatformToEnum)(position.platform);
+    }
+    getForPosition(position) {
+        return this.getByPlatform(this.getPlatformForPosition(position));
+    }
+    getByPlatform(platform) {
+        switch (platform) {
+            case common_1.LendingPlatform.None:
+                throw new Error("Lending position does not have an active lending platform");
+            case common_1.LendingPlatform.Kamino:
+                return this.kaminoClient;
+            default:
+                throw new Error(`Unsupported lending platform client: ${platform}`);
+        }
+    }
+}
+exports.LendingPlatformClientRegistry = LendingPlatformClientRegistry;

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

@@ -0,0 +1,33 @@
+import { type Address, type ProgramDerivedAddressBump } from "@solana/kit";
+/**
+ * PDA derivation for the long_yield_carry program.
+ *
+ * The program ID is injected via constructor — no global state.
+ */
+export declare class PdaClient {
+    private readonly programAddress;
+    constructor(programAddress: Address);
+    /**
+     * Derives the Token PDA for a given mint and ID.
+     *
+     * Seeds: ["TOKEN", mint_pubkey, id]
+     *
+     * @param mintAddress - The yToken mint address
+     * @param id - The token ID (u8)
+     * @returns Tuple of [PDA address, bump seed]
+     */
+    deriveTokenPda(mintAddress: Address, id: number): Promise<readonly [Address, ProgramDerivedAddressBump]>;
+    /**
+     * Derives the YieldingBank PDA for a given base mint and yielding ID.
+     *
+     * Seeds: ["YIELDING_BANK", base_mint_pubkey, id_le_bytes]
+     *
+     * @param baseMint - The base mint address
+     * @param yieldingId - The yielding bank ID (u8)
+     * @returns Tuple of [PDA address, bump seed]
+     */
+    deriveYieldingBankPda(baseMint: Address, yieldingId: number): Promise<readonly [Address, ProgramDerivedAddressBump]>;
+    deriveRedemptionEpochPda(token: Address, epochId: bigint | number): Promise<readonly [Address, ProgramDerivedAddressBump]>;
+    deriveAsyncBurnRequestPda(token: Address, epochId: bigint | number, sequence: bigint | number): Promise<readonly [Address, ProgramDerivedAddressBump]>;
+    deriveCpiPlanPda(uniqueId: Address, createdTs: bigint | number): Promise<readonly [Address, ProgramDerivedAddressBump]>;
+}

package/dist/sdks/long-yield-carry/src/client/pda.js

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PdaClient = void 0;
+const kit_1 = require("@solana/kit");
+const addressEncoder = (0, kit_1.getAddressEncoder)();
+function u64LeBytes(value) {
+    const bytes = new Uint8Array(8);
+    const view = new DataView(bytes.buffer);
+    view.setBigUint64(0, BigInt(value), true);
+    return bytes;
+}
+/**
+ * PDA derivation for the long_yield_carry program.
+ *
+ * The program ID is injected via constructor — no global state.
+ */
+class PdaClient {
+    constructor(programAddress) {
+        this.programAddress = programAddress;
+    }
+    /**
+     * Derives the Token PDA for a given mint and ID.
+     *
+     * Seeds: ["TOKEN", mint_pubkey, id]
+     *
+     * @param mintAddress - The yToken mint address
+     * @param id - The token ID (u8)
+     * @returns Tuple of [PDA address, bump seed]
+     */
+    async deriveTokenPda(mintAddress, id) {
+        return await (0, kit_1.getProgramDerivedAddress)({
+            programAddress: this.programAddress,
+            seeds: [Buffer.from("TOKEN"), addressEncoder.encode(mintAddress), new Uint8Array([id])],
+        });
+    }
+    /**
+     * Derives the YieldingBank PDA for a given base mint and yielding ID.
+     *
+     * Seeds: ["YIELDING_BANK", base_mint_pubkey, id_le_bytes]
+     *
+     * @param baseMint - The base mint address
+     * @param yieldingId - The yielding bank ID (u8)
+     * @returns Tuple of [PDA address, bump seed]
+     */
+    async deriveYieldingBankPda(baseMint, yieldingId) {
+        return await (0, kit_1.getProgramDerivedAddress)({
+            programAddress: this.programAddress,
+            seeds: [
+                Buffer.from("YIELDING_BANK"),
+                addressEncoder.encode(baseMint),
+                new Uint8Array([yieldingId]),
+            ],
+        });
+    }
+    async deriveRedemptionEpochPda(token, epochId) {
+        return await (0, kit_1.getProgramDerivedAddress)({
+            programAddress: this.programAddress,
+            seeds: [Buffer.from("REDEMPTION_EPOCH"), addressEncoder.encode(token), u64LeBytes(epochId)],
+        });
+    }
+    async deriveAsyncBurnRequestPda(token, epochId, sequence) {
+        return await (0, kit_1.getProgramDerivedAddress)({
+            programAddress: this.programAddress,
+            seeds: [
+                Buffer.from("ASYNC_BURN_REQUEST"),
+                addressEncoder.encode(token),
+                u64LeBytes(epochId),
+                u64LeBytes(sequence),
+            ],
+        });
+    }
+    async deriveCpiPlanPda(uniqueId, createdTs) {
+        return await (0, kit_1.getProgramDerivedAddress)({
+            programAddress: this.programAddress,
+            seeds: [Buffer.from("cpi plan"), addressEncoder.encode(uniqueId), u64LeBytes(createdTs)],
+        });
+    }
+}
+exports.PdaClient = PdaClient;

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

@@ -0,0 +1,24 @@
+import type { Address } from "@solana/kit";
+import type { AccountClient } from "../account";
+import type { CollectInterestPlan, CollectInterestPlanParams } from "../types";
+/**
+ * Ensures the planner produced at least one positive redemption leg. Without this,
+ * routing would fail or build an empty CPI list even though share math passed.
+ */
+export declare function assertCollectInterestPlanHasPositiveRedemptions(plan: CollectInterestPlan): void;
+/**
+ * Derive deterministic collect-interest values from fresh token and bank state.
+ * This intentionally excludes route / venue selection.
+ *
+ * @param account - Account client used to fetch fresh token and yielding-bank state.
+ * @param token - Token PDA whose carry position should collect accrued interest.
+ * @param params - Yielding bank to redeem from.
+ * @returns Deterministic collect-interest plan without swap routing attached.
+ *
+ * @throws {NoInterestToCollectError} When carry/debt math rules out collection.
+ *
+ * Before swap routing, run `assertCollectInterestPlanHasPositiveRedemptions` on the
+ * returned plan (the `getCollectInterestTx` transaction builder does this) so rounding
+ * cannot yield an empty redemption list.
+ */
+export declare function buildCollectInterestPlan(account: AccountClient, token: Address, params: CollectInterestPlanParams): Promise<CollectInterestPlan>;