@kestrelfi/lyc-sdk 1.0.1

package/dist/shared/perena-helpers/src/client.js

@@ -0,0 +1,680 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PerenaClient = void 0;
+const core_1 = require("@anchor-lang/core");
+const web3_js_1 = require("@solana/web3.js");
+const bankineco_sdk_1 = require("@perena/bankineco-sdk");
+const token_1 = require("@solana-program/token");
+const system_1 = require("@solana-program/system");
+const constants_1 = require("./constants");
+const common_1 = require("common");
+const cpi_1 = require("./cpi");
+const ACTIVE_WITHDRAWAL_QUEUES_CACHE_CATEGORY = "activeWithdrawalQueues";
+/**
+ * Perena USD* client implementing RoutableSwapClient and TokenProtocolClient.
+ *
+ * Provides a unified API for:
+ * - Minting and burning USD*
+ * - Querying protocol capabilities and info (YieldProtocolClient interface)
+ *
+ * @example
+ * ```typescript
+ * import { PerenaClient } from "perena-helpers";
+ * import { defaultMints } from "common/services/mints";
+ *
+ * const client = new PerenaClient(rpcUrl);
+ * const usdc = defaultMints.get("USDC")!;
+ * const usdStar = defaultMints.get("USD*")!;
+ *
+ * // Mint: USDC → USD*
+ * const mintQuote = await client.getQuote({
+ *   inputMint: usdc.address,
+ *   outputMint: usdStar.address,
+ *   amount: 10_000_000, // 10 USDC
+ *   slippageBps: 100,
+ * });
+ *
+ * // Burn: USD* → USDC
+ * const burnQuote = await client.getQuote({
+ *   inputMint: usdStar.address,
+ *   outputMint: usdc.address,
+ *   amount: 10_000_000, // 10 USD*
+ *   slippageBps: 100,
+ * });
+ *
+ * // Get CPI accounts for instruction
+ * const { accounts, programId } = await client.getSwapCpiData(
+ *   mintQuote,
+ *   userPda
+ * );
+ * ```
+ */
+class PerenaClient {
+    /**
+     * Creates a new Perena client.
+     *
+     * @param rpcUrl - Solana RPC URL
+     */
+    constructor(rpcUrl) {
+        this.sdkClient = bankineco_sdk_1.UsdStarClient.new({
+            env: "prod",
+            rpcUrl,
+        });
+        this.cache = new common_1.DataCache({
+            defaultTtlMs: 60000 * 5, // 5 minute default
+        });
+        const usdStar = common_1.mints.get("USD*");
+        if (!usdStar) {
+            throw new Error("USD* mint not found in registry");
+        }
+        this.bankMint = usdStar.address;
+        const usdStarJ = common_1.mints.get("USD*-J");
+        if (!usdStarJ) {
+            throw new Error("USD*-J mint not found in registry");
+        }
+        this.juniorMint = usdStarJ.address;
+        const yieldingMints = Object.keys(this.sdkClient.idleVaultIndices);
+        const routable = Object.freeze([this.bankMint, this.juniorMint, ...yieldingMints]);
+        this.inputMints = routable;
+        this.outputMints = routable;
+        this.routeAnchorMints = Object.freeze([this.bankMint, this.juniorMint]);
+    }
+    /**
+     * Get mints that can directly mint USD*.
+     */
+    async getSupportedSourceMints() {
+        return Object.keys(this.sdkClient.idleVaultIndices).map((key) => key);
+    }
+    /**
+     * Get current protocol info for a source mint.
+     * @param sourceMint - The source mint to get info for (i.e. USDC, USDT, etc.)
+     * @returns Protocol info including fees and limits
+     * @throws Error if sourceMint is not supported by Perena
+     */
+    async getProtocolInfo(sourceMint) {
+        const supportedSourceMints = await this.getSupportedSourceMints();
+        if (!supportedSourceMints.includes(sourceMint)) {
+            throw new Error(`Source mint ${sourceMint} is not supported by Perena`);
+        }
+        const { data } = await this.cache.getDataOrThrow(async () => {
+            const vault = this.sdkClient.getVault(new web3_js_1.PublicKey(sourceMint));
+            const vaultInfo = await this.sdkClient.bankineco.pg.account.vaultGenState.fetch(vault);
+            return {
+                sourceMint,
+                mintFeeBps: vaultInfo.config.mintingFeeBps,
+                redemptionFeeBps: vaultInfo.config.burningFeeBps,
+                depositLimit: BigInt(0),
+                redemptionLimit: BigInt(vaultInfo.accounting.yieldingReserveAmount.toString()),
+            };
+        }, "yieldProtocolInfo", sourceMint);
+        return data;
+    }
+    /**
+     * Get the latest USD* price in UI units (e.g. dollars).
+     *
+     * @returns The current bank mint price as a number
+     */
+    async getLatestBankMintUiPrice() {
+        const { data } = await this.cache.getDataOrThrow(() => this.sdkClient.latestBankMintUiPrice(), "bankMintUiPrice", "latest");
+        return data;
+    }
+    /**
+     * Get the latest USD*-J price in UI units (e.g. dollars).
+     *
+     * @returns The current junior mint price as a number
+     */
+    async getLatestJuniorMintUiPrice() {
+        const { data } = await this.cache.getDataOrThrow(() => this.sdkClient.latestJuniorMintUiPrice(), "juniorMintUiPrice", "latest");
+        return data;
+    }
+    /**
+     * Size a USD* burn so the routed yielding output (e.g. USDC) is at least
+     * `minYieldingOut` base units, without scanning inputs.
+     *
+     * Perena's `bankMintToYieldingQuote` is linear in the burn amount for fixed
+     * oracles: bank-mint price, yielding price, burn fee bps, and decimal
+     * rescales are all proportional in `amountToBurn`. We take **one** reference
+     * quote at exactly 1.0 bank-mint token (10^decimals base units) to read the
+     * effective `yieldingOut / bankMintIn` rate implied by the current prices,
+     * then `ceil(need * refIn / refOut)` and re-quote once at that input so the
+     * returned {@link PerenaSwapQuote} matches the CPI.
+     */
+    /**
+     * @deprecated Prefer {@link getQuoteCoveringMinOutput} — same behavior with generic param names.
+     */
+    async getQuoteCoveringYieldingOut(params) {
+        return this.getQuoteCoveringMinOutput({
+            inputMint: params.inputMint,
+            outputMint: params.outputMint,
+            minOutputAmount: params.minYieldingOut,
+            maxInputAmount: params.maxBankMintIn,
+            slippageBps: params.slippageBps,
+        });
+    }
+    async getQuoteCoveringMinOutput(params) {
+        if (params.inputMint !== this.bankMint) {
+            throw new Error("getQuoteCoveringMinOutput only supports burning USD* into a yielding mint");
+        }
+        const need = params.minOutputAmount;
+        if (need <= BigInt(0)) {
+            throw new Error("getQuoteCoveringMinOutput: minOutputAmount must be positive");
+        }
+        const maxIn = params.maxInputAmount;
+        if (maxIn <= BigInt(0)) {
+            throw new Error("getQuoteCoveringMinOutput: maxInputAmount must be positive");
+        }
+        const vault = this.sdkClient.getVault(new web3_js_1.PublicKey(params.outputMint));
+        const refInBn = common_1.mints.get("USD*").fromUiAmount(1);
+        const oneBankMint = BigInt(refInBn.toString());
+        const refSdk = await this.sdkClient.bankMintToYieldingQuote(refInBn, vault);
+        const refOut = BigInt(refSdk.amount.toString());
+        if (refOut === BigInt(0)) {
+            throw new Error("Perena reference burn quote returned zero yielding output");
+        }
+        const maxSdk = await this.sdkClient.bankMintToYieldingQuote(new core_1.BN(maxIn.toString()), vault);
+        if (BigInt(maxSdk.amount.toString()) < need) {
+            throw new Error("Perena: bank mint holding cannot cover the yielding output required for this unwind");
+        }
+        /** `ceil(targetOut * oneBankMint / refOut)` — inverting the reference rate from oracle pricing. */
+        const scaleInput = (targetOut) => {
+            const numer = targetOut * oneBankMint + refOut - BigInt(1);
+            return numer / refOut;
+        };
+        let inputRaw = scaleInput(need);
+        if (inputRaw > maxIn) {
+            inputRaw = maxIn;
+        }
+        if (inputRaw < BigInt(1)) {
+            inputRaw = BigInt(1);
+        }
+        const slippageBps = params.slippageBps ?? 100;
+        const quoteAt = async (inAmt) => {
+            if (inAmt > BigInt(Number.MAX_SAFE_INTEGER)) {
+                throw new Error("getQuoteCoveringMinOutput: burn input exceeds Number.MAX_SAFE_INTEGER");
+            }
+            return this.getQuote({
+                inputMint: params.inputMint,
+                outputMint: params.outputMint,
+                amount: Number(inAmt),
+                slippageBps,
+            });
+        };
+        let quote = await quoteAt(inputRaw);
+        let out = BigInt(quote.outputAmount.toString());
+        if (out < need && inputRaw < maxIn) {
+            inputRaw = (need * inputRaw + out - BigInt(1)) / out;
+            if (inputRaw > maxIn) {
+                inputRaw = maxIn;
+            }
+            quote = await quoteAt(inputRaw);
+            out = BigInt(quote.outputAmount.toString());
+        }
+        // Integer rounding inside the Perena SDK can leave the output 1 base unit
+        // short even after proportional re-scaling. Bump the input by 1 and
+        // re-quote once more before giving up.
+        if (out < need && inputRaw < maxIn) {
+            inputRaw += BigInt(1);
+            if (inputRaw > maxIn) {
+                inputRaw = maxIn;
+            }
+            quote = await quoteAt(inputRaw);
+            out = BigInt(quote.outputAmount.toString());
+        }
+        if (out < need) {
+            throw new Error("Perena: sized burn quote still below required yielding output (rounding); try larger holding or refresh oracles");
+        }
+        return quote;
+    }
+    /**
+     * Get a quote for minting/burning USD* or staking/unstaking USD*-J.
+     *
+     * The operation is determined by the mints:
+     * - outputMint is USD*: mint (yielding → USD*)
+     * - inputMint is USD*: burn (USD* → yielding)
+     * - outputMint is USD*-J: stake (USD* → USD*-J)
+     * - inputMint is USD*-J: unstake (USD*-J → USD* or yielding)
+     *
+     * @param params - Quote parameters
+     * @returns Normalized swap quote
+     * @throws Error if the mint pair is not supported
+     */
+    async getQuote(params) {
+        const isJuniorInput = params.inputMint === this.juniorMint;
+        const isJuniorOutput = params.outputMint === this.juniorMint;
+        if (isJuniorOutput) {
+            if (params.inputMint !== this.bankMint) {
+                throw new Error("Invalid Perena quote: can only stake USD* into USD*-J");
+            }
+            return this.getStakeQuote(params);
+        }
+        if (isJuniorInput) {
+            return this.getUnstakeQuote(params);
+        }
+        const isMint = params.outputMint === this.bankMint;
+        const isBurn = params.inputMint === this.bankMint;
+        if (!isMint && !isBurn) {
+            throw new Error("Invalid Perena quote: either inputMint or outputMint must be USD* or USD*-J");
+        }
+        if (isMint && isBurn) {
+            throw new Error("Invalid Perena quote: cannot swap USD* to USD*");
+        }
+        const yieldingMint = isMint ? params.inputMint : params.outputMint;
+        const yieldingMintPubkey = new web3_js_1.PublicKey(yieldingMint);
+        const vault = this.sdkClient.getVault(yieldingMintPubkey);
+        const amount = new core_1.BN(params.amount);
+        const vaultInfo = await this.sdkClient.bankineco.pg.account.vaultGenState.fetch(vault);
+        const feeBps = isMint ? vaultInfo.config.mintingFeeBps : vaultInfo.config.burningFeeBps;
+        const priceImpactPct = feeBps / 100;
+        if (isMint) {
+            const sdkQuote = await this.sdkClient.yieldingToBankMintQuote(amount, vault);
+            return {
+                inputMint: params.inputMint,
+                outputMint: params.outputMint,
+                inputAmount: BigInt(params.amount),
+                outputAmount: BigInt(sdkQuote.amount.toString()),
+                priceImpactPct,
+                rawQuote: { operation: "mint", yieldingMint, sdkQuote },
+            };
+        }
+        else {
+            const sdkQuote = await this.sdkClient.bankMintToYieldingQuote(amount, vault);
+            return {
+                inputMint: params.inputMint,
+                outputMint: params.outputMint,
+                inputAmount: BigInt(params.amount),
+                outputAmount: BigInt(sdkQuote.amount.toString()),
+                priceImpactPct,
+                rawQuote: { operation: "burn", yieldingMint, sdkQuote },
+            };
+        }
+    }
+    /**
+     * Quote for staking USD* → USD*-J.
+     *
+     * Shares minted = amount × bankMintPrice / sharePrice.
+     * Staking has no fee; the on-chain conversion is deterministic.
+     */
+    async getStakeQuote(params) {
+        const trancheState = await this.sdkClient.fetchTrancheState(true);
+        const bankState = await this.sdkClient.bankineco.pg.account.bankState.fetch(this.sdkClient.bank);
+        const amount = new core_1.BN(params.amount);
+        const sharesOut = amount.mul(bankState.mint.price).div(trancheState.accounting.sharePrice);
+        return {
+            inputMint: params.inputMint,
+            outputMint: params.outputMint,
+            inputAmount: BigInt(params.amount),
+            outputAmount: BigInt(sharesOut.toString()),
+            priceImpactPct: 0,
+            rawQuote: { operation: "stake" },
+        };
+    }
+    /**
+     * Quote for unstaking USD*-J → USD* or yielding mint.
+     *
+     * Uses `fetchUnstakeFee` with `early: true` because instant unstake
+     * always applies the early fee.
+     */
+    async getUnstakeQuote(params) {
+        const isToYielding = params.outputMint !== this.bankMint;
+        const targetMintPk = isToYielding ? new web3_js_1.PublicKey(params.outputMint) : undefined;
+        const unstakeFee = await this.sdkClient.fetchUnstakeFee({
+            amount: new core_1.BN(params.amount),
+            early: true,
+            targetMint: targetMintPk,
+        });
+        const totalFee = unstakeFee.feeAmount.add(unstakeFee.burningFeeAmount);
+        const grossOutput = unstakeFee.amountAfterFee.add(totalFee);
+        const feePct = grossOutput.isZero() ? 0 : (totalFee.toNumber() / grossOutput.toNumber()) * 100;
+        return {
+            inputMint: params.inputMint,
+            outputMint: params.outputMint,
+            inputAmount: BigInt(params.amount),
+            outputAmount: BigInt(unstakeFee.amountAfterFee.toString()),
+            priceImpactPct: feePct,
+            rawQuote: {
+                operation: "unstake",
+                targetMint: isToYielding ? params.outputMint : undefined,
+                unstakeFee,
+            },
+        };
+    }
+    /**
+     * Get CPI accounts for a Perena instruction.
+     *
+     * Account order matches the IDL for the respective instruction.
+     *
+     * @param quote - Quote from getQuote()
+     * @param userPublicKey - Address that will execute the swap (can be a PDA)
+     * @param options - Options on building the CPI
+     * @returns CPI accounts, program ID, and serialized instruction data
+     */
+    async getSwapCpiData(quote, userPublicKey, _options) {
+        const { operation } = quote.rawQuote;
+        switch (operation) {
+            case "mint":
+            case "burn":
+                return this.getMintBurnCpiData(quote, userPublicKey);
+            case "stake":
+                return await this.getStakeCpiData(quote, userPublicKey);
+            case "unstake":
+                return await this.getInstantUnstakeCpiData(quote, userPublicKey);
+            case "request_unstake": {
+                const rq = quote.rawQuote;
+                return await this.getRequestUnstakeCpiData({
+                    shares: new core_1.BN(quote.inputAmount.toString()),
+                    queueId: rq.queueId,
+                    userPublicKey,
+                    payer: rq.payer,
+                    targetMint: rq.targetMint,
+                });
+            }
+            case "fulfill_unstake": {
+                const fq = quote.rawQuote;
+                return await this.getFulfillUnstakeCpiData({
+                    withdrawalQueue: fq.withdrawalQueue,
+                    signer: fq.owner,
+                    queuePayer: fq.queuePayer,
+                    owner: fq.owner,
+                    targetMint: fq.targetMint,
+                });
+            }
+        }
+    }
+    /**
+     * Derive the withdrawal queue PDA for a given user and queue slot.
+     */
+    deriveWithdrawalQueue(user, queueId) {
+        return (0, common_1.fromWeb3Pk)(this.sdkClient.bankineco.withdrawalQueuePDA(this.sdkClient.bank, new web3_js_1.PublicKey(user), queueId));
+    }
+    /**
+     * Fetch all active withdrawal queue PDAs owned by `user`.
+     *
+     * "Active" means the queue account exists, is owned by Perena, and currently
+     * holds a non-zero locked amount.
+     */
+    async getActiveWithdrawalQueues(user) {
+        const { data } = await this.cache.getDataOrThrow(async () => {
+            const userPublicKey = new web3_js_1.PublicKey(user);
+            const queueInfos = await this.sdkClient.fetchAllWithdrawalQueues(userPublicKey);
+            return queueInfos
+                .filter((queueInfo) => queueInfo.amount.gt(new core_1.BN(0)))
+                .map((queueInfo) => (0, common_1.fromWeb3Pk)(queueInfo.address));
+        }, ACTIVE_WITHDRAWAL_QUEUES_CACHE_CATEGORY, user);
+        return data;
+    }
+    /**
+     * Cache invalidation descriptor for the active-withdrawal-queues snapshot of
+     * one owner. Use this when a transaction may create, consume, or otherwise
+     * mutate Perena withdrawal queues outside this exact client instance.
+     */
+    getActiveWithdrawalQueuesCacheInvalidation(owner) {
+        return this.getActiveWithdrawalQueuesInvalidation(owner);
+    }
+    getActiveWithdrawalQueuesInvalidation(owner) {
+        return {
+            client: "perena",
+            dataCache: this.cache,
+            category: ACTIVE_WITHDRAWAL_QUEUES_CACHE_CATEGORY,
+            id: owner,
+        };
+    }
+    /**
+     * Build CPI data for mint_w_yielding_gen or burn_for_yielding_gen.
+     */
+    async getMintBurnCpiData(quote, userPublicKey) {
+        const raw = quote.rawQuote;
+        const isMint = raw.operation === "mint";
+        const action = isMint ? bankineco_sdk_1.BankinecoAction.Mint : bankineco_sdk_1.BankinecoAction.Burn;
+        const cpiAccounts = await this.sdkClient.getMintAndBurnCpiAccounts(new web3_js_1.PublicKey(raw.yieldingMint), action, new web3_js_1.PublicKey(userPublicKey));
+        const accounts = [
+            (0, common_1.toCustomAccountMeta)(userPublicKey, false, undefined, false),
+            (0, common_1.toCustomAccountMetaFromWeb3AccountMeta)(cpiAccounts.bankState),
+            (0, common_1.toCustomAccountMetaFromWeb3AccountMeta)(cpiAccounts.vaultState),
+            (0, common_1.toCustomAccountMetaFromWeb3AccountMeta)(cpiAccounts.oracleState),
+            (0, common_1.toCustomAccountMetaFromWeb3AccountMeta)(cpiAccounts.yieldingMint),
+            (0, common_1.toCustomAccountMetaFromWeb3AccountMeta)(cpiAccounts.bankMint),
+            (0, common_1.toCustomAccountMetaFromWeb3AccountMeta)(cpiAccounts.yieldingUserTa),
+            {
+                ...(0, common_1.toCustomAccountMetaFromWeb3AccountMeta)(cpiAccounts.bankMintUserTa),
+                isRequiredAta: {
+                    mint: (0, common_1.fromWeb3Pk)(cpiAccounts.bankMint.pubkey),
+                    owner: userPublicKey,
+                    tokenProgram: common_1.mints.get("USD*").tokenProgram,
+                },
+            },
+            (0, common_1.toCustomAccountMetaFromWeb3AccountMeta)(cpiAccounts.yieldingVaultAta),
+            (0, common_1.toCustomAccountMetaFromWeb3AccountMeta)(cpiAccounts.teamState),
+            (0, common_1.toCustomAccountMetaFromWeb3AccountMeta)(cpiAccounts.feeTeamAta),
+            (0, common_1.toCustomAccountMetaFromWeb3AccountMeta)(cpiAccounts.systemProgram),
+            (0, common_1.toCustomAccountMetaFromWeb3AccountMeta)(cpiAccounts.tokenProgram),
+            (0, common_1.toCustomAccountMetaFromWeb3AccountMeta)(cpiAccounts.yieldingMintProgram),
+            (0, common_1.toCustomAccountMetaFromWeb3AccountMeta)(cpiAccounts.associatedTokenProgram),
+            ...(cpiAccounts.remainingAccounts ?? []).map((meta) => (0, common_1.toCustomAccountMeta)(meta.pubkey.toBase58(), meta.isWritable, undefined, meta.isSigner)),
+        ];
+        return {
+            cpiType: isMint ? common_1.CpiTypes.PERENA_MINT : common_1.CpiTypes.PERENA_BURN,
+            accounts,
+            programId: constants_1.PERENA_PROGRAM_ID,
+            data: isMint
+                ? (0, cpi_1.getPerenaMintArgs)({
+                    amountYieldingDeposit: quote.inputAmount,
+                    minBankMintMinted: quote.outputAmount,
+                })
+                : (0, cpi_1.getPerenaBurnArgs)({
+                    amountToBurn: quote.inputAmount,
+                    minimumYieldingWithdrawn: quote.outputAmount,
+                }),
+        };
+    }
+    /**
+     * Build CPI data for stake_junior.
+     *
+     * Account order matches the IDL:
+     *   user, tranche_state, bank_state, bank_mint, junior_mint,
+     *   user_bank_mint_ata, user_junior_mint_ata, junior_escrow_ata,
+     *   system_program, token_program, associated_token_program
+     */
+    async getStakeCpiData(quote, userPublicKey) {
+        const userPk = new web3_js_1.PublicKey(userPublicKey);
+        const trancheAccounts = await this.sdkClient.getStakeCpiAccounts(userPk);
+        const { bankMint, juniorMint, tokenProgram } = trancheAccounts;
+        const userBankMintAta = await (0, common_1.getAtaAddress)((0, common_1.fromWeb3Pk)(bankMint), userPublicKey, (0, common_1.fromWeb3Pk)(tokenProgram));
+        const userJuniorMintAta = await (0, common_1.getAtaAddress)((0, common_1.fromWeb3Pk)(juniorMint), userPublicKey, (0, common_1.fromWeb3Pk)(tokenProgram));
+        const accounts = [
+            (0, common_1.toCustomAccountMeta)(userPublicKey, true, undefined, false),
+            (0, common_1.toCustomAccountMeta)((0, common_1.fromWeb3Pk)(trancheAccounts.trancheState), true),
+            (0, common_1.toCustomAccountMeta)((0, common_1.fromWeb3Pk)(trancheAccounts.bankState)),
+            (0, common_1.toCustomAccountMeta)((0, common_1.fromWeb3Pk)(bankMint)),
+            (0, common_1.toCustomAccountMeta)((0, common_1.fromWeb3Pk)(juniorMint), true),
+            (0, common_1.toCustomAccountMeta)(userBankMintAta, true),
+            {
+                ...(0, common_1.toCustomAccountMeta)(userJuniorMintAta, true),
+                isRequiredAta: {
+                    mint: this.juniorMint,
+                    owner: userPublicKey,
+                    tokenProgram: common_1.mints.get("USD*-J").tokenProgram,
+                },
+            },
+            (0, common_1.toCustomAccountMeta)((0, common_1.fromWeb3Pk)(trancheAccounts.juniorEscrowAta), true),
+            (0, common_1.toCustomAccountMeta)(system_1.SYSTEM_PROGRAM_ADDRESS),
+            (0, common_1.toCustomAccountMeta)((0, common_1.fromWeb3Pk)(tokenProgram)),
+            (0, common_1.toCustomAccountMeta)(token_1.ASSOCIATED_TOKEN_PROGRAM_ADDRESS),
+        ];
+        return {
+            cpiType: common_1.CpiTypes.PERENA_STAKE,
+            accounts,
+            programId: constants_1.PERENA_PROGRAM_ID,
+            data: (0, common_1.numToU64Bytes)(quote.inputAmount),
+        };
+    }
+    /**
+     * Build CPI data for instant_unstake_junior.
+     *
+     * Account order matches the IDL:
+     *   user, tranche_state, bank_state, bank_mint, target_mint, junior_mint,
+     *   user_junior_mint_ata, owner_bank_mint_ata, junior_escrow_ata,
+     *   locked_junior_shares_ata, token_program,
+     *   [vault_state, vault_oracle_state, vault_team_state, yielding_mint,
+     *    yielding_vault_ata, owner_yielding_ta, vault_fee_team_ata,
+     *    yielding_mint_program]  (optional, when unstaking to a yielding mint)
+     */
+    async getInstantUnstakeCpiData(quote, userPublicKey) {
+        const raw = quote.rawQuote;
+        const userPk = new web3_js_1.PublicKey(userPublicKey);
+        const targetMintPk = raw.targetMint ? new web3_js_1.PublicKey(raw.targetMint) : undefined;
+        const trancheAccounts = await this.sdkClient.getUnstakeCpiAccounts(userPk, targetMintPk);
+        const { bankMint, juniorMint, tokenProgram } = trancheAccounts;
+        const userJuniorMintAta = await (0, common_1.getAtaAddress)((0, common_1.fromWeb3Pk)(juniorMint), userPublicKey, (0, common_1.fromWeb3Pk)(tokenProgram));
+        const ownerBankMintAta = await (0, common_1.getAtaAddress)((0, common_1.fromWeb3Pk)(bankMint), userPublicKey, (0, common_1.fromWeb3Pk)(tokenProgram));
+        const targetMintAddress = raw.targetMint ?? this.bankMint;
+        const accounts = [
+            (0, common_1.toCustomAccountMeta)(userPublicKey, false, undefined, false),
+            (0, common_1.toCustomAccountMeta)((0, common_1.fromWeb3Pk)(trancheAccounts.trancheState), true),
+            (0, common_1.toCustomAccountMeta)((0, common_1.fromWeb3Pk)(trancheAccounts.bankState), true),
+            (0, common_1.toCustomAccountMeta)((0, common_1.fromWeb3Pk)(bankMint), true),
+            (0, common_1.toCustomAccountMeta)(targetMintAddress),
+            (0, common_1.toCustomAccountMeta)((0, common_1.fromWeb3Pk)(juniorMint), true),
+            (0, common_1.toCustomAccountMeta)(userJuniorMintAta, true),
+            {
+                ...(0, common_1.toCustomAccountMeta)(ownerBankMintAta, true),
+                isRequiredAta: {
+                    mint: (0, common_1.fromWeb3Pk)(bankMint),
+                    owner: userPublicKey,
+                    tokenProgram: common_1.mints.get("USD*").tokenProgram,
+                },
+            },
+            (0, common_1.toCustomAccountMeta)((0, common_1.fromWeb3Pk)(trancheAccounts.juniorEscrowAta), true),
+            (0, common_1.toCustomAccountMeta)((0, common_1.fromWeb3Pk)(trancheAccounts.lockedJuniorSharesAta), true),
+            (0, common_1.toCustomAccountMeta)((0, common_1.fromWeb3Pk)(tokenProgram)),
+        ];
+        this.pushYieldingRedemptionAccounts(accounts, trancheAccounts, userPublicKey);
+        return {
+            cpiType: common_1.CpiTypes.PERENA_INSTANT_UNSTAKE,
+            accounts,
+            programId: constants_1.PERENA_PROGRAM_ID,
+            data: (0, common_1.numToU64Bytes)(quote.inputAmount),
+        };
+    }
+    /**
+     * Build CPI data for request_unstake_junior.
+     *
+     * Account order matches the IDL:
+     *   user, payer, withdrawal_queue, tranche_state, bank_state, bank_mint,
+     *   target_mint, junior_mint, user_junior_mint_ata, locked_junior_shares_ata,
+     *   system_program, token_program
+     */
+    async getRequestUnstakeCpiData(params) {
+        const userPk = new web3_js_1.PublicKey(params.userPublicKey);
+        const targetMintPk = params.targetMint ? new web3_js_1.PublicKey(params.targetMint) : undefined;
+        const trancheAccounts = await this.sdkClient.getUnstakeCpiAccounts(userPk, targetMintPk);
+        const { bankMint, juniorMint, tokenProgram } = trancheAccounts;
+        const userJuniorMintAta = await (0, common_1.getAtaAddress)((0, common_1.fromWeb3Pk)(juniorMint), params.userPublicKey, (0, common_1.fromWeb3Pk)(tokenProgram));
+        const targetMintAddress = params.targetMint ?? this.bankMint;
+        const withdrawalQueue = this.deriveWithdrawalQueue(params.userPublicKey, params.queueId);
+        const accounts = [
+            (0, common_1.toCustomAccountMeta)(params.userPublicKey, false, undefined, false),
+            (0, common_1.toCustomAccountMeta)(params.payer, true, undefined, true),
+            (0, common_1.toCustomAccountMeta)(withdrawalQueue, true),
+            (0, common_1.toCustomAccountMeta)((0, common_1.fromWeb3Pk)(trancheAccounts.trancheState)),
+            (0, common_1.toCustomAccountMeta)((0, common_1.fromWeb3Pk)(trancheAccounts.bankState)),
+            (0, common_1.toCustomAccountMeta)((0, common_1.fromWeb3Pk)(bankMint)),
+            (0, common_1.toCustomAccountMeta)(targetMintAddress),
+            (0, common_1.toCustomAccountMeta)((0, common_1.fromWeb3Pk)(juniorMint)),
+            (0, common_1.toCustomAccountMeta)(userJuniorMintAta, true),
+            (0, common_1.toCustomAccountMeta)((0, common_1.fromWeb3Pk)(trancheAccounts.lockedJuniorSharesAta), true),
+            (0, common_1.toCustomAccountMeta)(system_1.SYSTEM_PROGRAM_ADDRESS),
+            (0, common_1.toCustomAccountMeta)((0, common_1.fromWeb3Pk)(tokenProgram)),
+        ];
+        return {
+            cpiType: common_1.CpiTypes.PERENA_REQUEST_UNSTAKE,
+            accounts,
+            programId: constants_1.PERENA_PROGRAM_ID,
+            data: (0, cpi_1.getPerenaRequestUnstakeArgs)({
+                shares: params.shares,
+                queueId: params.queueId,
+            }),
+            postSuccessCacheInvalidations: [
+                this.getActiveWithdrawalQueuesInvalidation(params.userPublicKey),
+            ],
+        };
+    }
+    /**
+     * Build CPI data for fulfill_unstake_junior.
+     *
+     * Account order matches the IDL:
+     *   signer, queue_payer, withdrawal_queue, tranche_state, bank_state,
+     *   bank_mint, junior_mint, owner_bank_mint_ata, junior_escrow_ata,
+     *   locked_junior_shares_ata, token_program,
+     *   [vault_state, vault_oracle_state, vault_team_state, yielding_mint,
+     *    yielding_vault_ata, owner_yielding_ta, vault_fee_team_ata,
+     *    yielding_mint_program]  (optional, when fulfilling to a yielding mint)
+     */
+    async getFulfillUnstakeCpiData(params) {
+        const ownerPk = new web3_js_1.PublicKey(params.owner);
+        const targetMintPk = params.targetMint ? new web3_js_1.PublicKey(params.targetMint) : undefined;
+        const trancheAccounts = await this.sdkClient.getUnstakeCpiAccounts(ownerPk, targetMintPk);
+        const { bankMint, juniorMint, tokenProgram } = trancheAccounts;
+        const ownerBankMintAta = await (0, common_1.getAtaAddress)((0, common_1.fromWeb3Pk)(bankMint), params.owner, (0, common_1.fromWeb3Pk)(tokenProgram));
+        const accounts = [
+            (0, common_1.toCustomAccountMeta)(params.signer, false, undefined, false),
+            (0, common_1.toCustomAccountMeta)(params.queuePayer, true),
+            (0, common_1.toCustomAccountMeta)(params.withdrawalQueue, true),
+            (0, common_1.toCustomAccountMeta)((0, common_1.fromWeb3Pk)(trancheAccounts.trancheState), true),
+            (0, common_1.toCustomAccountMeta)((0, common_1.fromWeb3Pk)(trancheAccounts.bankState), true),
+            (0, common_1.toCustomAccountMeta)((0, common_1.fromWeb3Pk)(bankMint), true),
+            (0, common_1.toCustomAccountMeta)((0, common_1.fromWeb3Pk)(juniorMint), true),
+            {
+                ...(0, common_1.toCustomAccountMeta)(ownerBankMintAta, true),
+                isRequiredAta: {
+                    mint: (0, common_1.fromWeb3Pk)(bankMint),
+                    owner: params.owner,
+                    tokenProgram: common_1.mints.get("USD*").tokenProgram,
+                },
+            },
+            (0, common_1.toCustomAccountMeta)((0, common_1.fromWeb3Pk)(trancheAccounts.juniorEscrowAta), true),
+            (0, common_1.toCustomAccountMeta)((0, common_1.fromWeb3Pk)(trancheAccounts.lockedJuniorSharesAta), true),
+            (0, common_1.toCustomAccountMeta)((0, common_1.fromWeb3Pk)(tokenProgram)),
+        ];
+        this.pushYieldingRedemptionAccounts(accounts, trancheAccounts, params.owner);
+        return {
+            cpiType: common_1.CpiTypes.PERENA_FULFILL_UNSTAKE,
+            accounts,
+            programId: constants_1.PERENA_PROGRAM_ID,
+            data: new Uint8Array(0),
+            postSuccessCacheInvalidations: [this.getActiveWithdrawalQueuesInvalidation(params.owner)],
+        };
+    }
+    /**
+     * Appends the 8 yielding-redemption account slots that `instant_unstake_junior`
+     * and `fulfill_unstake_junior` expect after `token_program`.
+     *
+     * When a yielding mint is involved, real accounts are pushed. Otherwise Anchor
+     * still requires all 8 slots to be present — each set to the program ID as the
+     * `Option<Account>` sentinel for `None`.
+     */
+    pushYieldingRedemptionAccounts(accounts, trancheAccounts, owner) {
+        const yr = trancheAccounts.yieldingRedemption;
+        if (yr) {
+            accounts.push((0, common_1.toCustomAccountMeta)((0, common_1.fromWeb3Pk)(yr.vaultState), true), (0, common_1.toCustomAccountMeta)((0, common_1.fromWeb3Pk)(yr.vaultOracleState)), (0, common_1.toCustomAccountMeta)((0, common_1.fromWeb3Pk)(yr.vaultTeamState), true), (0, common_1.toCustomAccountMeta)((0, common_1.fromWeb3Pk)(yr.yieldingMint)), (0, common_1.toCustomAccountMeta)((0, common_1.fromWeb3Pk)(yr.yieldingVaultAta), true), {
+                ...(0, common_1.toCustomAccountMeta)((0, common_1.fromWeb3Pk)(yr.ownerYieldingTa), true),
+                isRequiredAta: {
+                    mint: (0, common_1.fromWeb3Pk)(yr.yieldingMint),
+                    owner,
+                    tokenProgram: (0, common_1.fromWeb3Pk)(yr.yieldingMintProgram),
+                },
+            }, (0, common_1.toCustomAccountMeta)((0, common_1.fromWeb3Pk)(yr.vaultFeeTeamAta), true), (0, common_1.toCustomAccountMeta)((0, common_1.fromWeb3Pk)(yr.yieldingMintProgram)));
+        }
+        else {
+            const sentinel = constants_1.PERENA_PROGRAM_ID;
+            for (let i = 0; i < 8; i++) {
+                accounts.push((0, common_1.toCustomAccountMeta)(sentinel));
+            }
+        }
+        if (trancheAccounts.remainingAccounts) {
+            for (const meta of trancheAccounts.remainingAccounts) {
+                accounts.push((0, common_1.toCustomAccountMeta)(meta.pubkey.toBase58(), meta.isWritable, undefined, meta.isSigner));
+            }
+        }
+    }
+}
+exports.PerenaClient = PerenaClient;

package/dist/shared/perena-helpers/src/constants.d.ts

@@ -0,0 +1,5 @@
+import { type Address } from "@solana/kit";
+/**
+ * Perena Bankineco Program ID (prod)
+ */
+export declare const PERENA_PROGRAM_ID: Address;