@kestrelfi/lyc-sdk 1.0.1

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

@@ -0,0 +1,28 @@
+import { BN } from "@anchor-lang/core";
+import type { Address } from "@solana/kit";
+import type { YieldingBankExternalLiquiditySource } from "../client/types";
+/**
+ * PodBool is a Rust `#[repr(transparent)]` newtype over `u8`.
+ * Anchor deserializes tuple-struct fields using positional integer keys, so
+ * `PodBool(1)` arrives from the RPC as `{ '0': 1 }` instead of a plain number.
+ *
+ * This helper extracts the underlying u8 value so callers work with a plain
+ * number rather than the intermediate struct object.
+ */
+export declare function podBoolToNumber(val: {
+    0: number;
+} | number): number;
+/**
+ * Build external-liquidity source descriptors for one mint across multiple accounts.
+ */
+export declare function toYieldingBankExternalLiquiditySources(mint: Address, accounts: Address[]): YieldingBankExternalLiquiditySource[];
+/**
+ * Convert a raw token amount and raw oracle price into 8-decimal USD TVL units.
+ */
+export declare function amountToTvl(amount: number | bigint | BN, price: number | bigint | BN, decimals: number): BN;
+/**
+ * Generate a redemption epoch ID by flooring `Date.now()` to the nearest minute.
+ * Burns within the same 60-second window will share an epoch PDA, allowing the
+ * manager to batch-process them together.
+ */
+export declare function currentEpochId(): BN;

package/dist/sdks/long-yield-carry/src/utils/general.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.podBoolToNumber = podBoolToNumber;
+exports.toYieldingBankExternalLiquiditySources = toYieldingBankExternalLiquiditySources;
+exports.amountToTvl = amountToTvl;
+exports.currentEpochId = currentEpochId;
+const core_1 = require("@anchor-lang/core");
+const common_1 = require("common");
+/**
+ * PodBool is a Rust `#[repr(transparent)]` newtype over `u8`.
+ * Anchor deserializes tuple-struct fields using positional integer keys, so
+ * `PodBool(1)` arrives from the RPC as `{ '0': 1 }` instead of a plain number.
+ *
+ * This helper extracts the underlying u8 value so callers work with a plain
+ * number rather than the intermediate struct object.
+ */
+function podBoolToNumber(val) {
+    if (typeof val === "number")
+        return val;
+    return val[0] ?? 0;
+}
+/**
+ * Build external-liquidity source descriptors for one mint across multiple accounts.
+ */
+function toYieldingBankExternalLiquiditySources(mint, accounts) {
+    return accounts.map((account) => ({ mint, account }));
+}
+/**
+ * Convert a raw token amount and raw oracle price into 8-decimal USD TVL units.
+ */
+function amountToTvl(amount, price, decimals) {
+    const amountBn = new core_1.BN(amount.toString());
+    const priceBn = new core_1.BN(price.toString());
+    const assetScale = (0, common_1.fromUiAmount)(1, decimals);
+    const tvlScale = (0, common_1.fromUiAmount)(1, 8);
+    const scaleFactor = assetScale.mul(assetScale).div(tvlScale);
+    return amountBn.mul(priceBn).div(scaleFactor);
+}
+const EPOCH_BUCKET_MS = 60000;
+/**
+ * Generate a redemption epoch ID by flooring `Date.now()` to the nearest minute.
+ * Burns within the same 60-second window will share an epoch PDA, allowing the
+ * manager to batch-process them together.
+ */
+function currentEpochId() {
+    return new core_1.BN(Math.floor(Date.now() / EPOCH_BUCKET_MS) * EPOCH_BUCKET_MS);
+}

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

@@ -0,0 +1,13 @@
+export * from "./enrichment";
+export * from "./lycData";
+export * from "./lookupTables";
+export * from "./ix";
+export * from "./general";
+export * from "./data";
+export * from "./cache";
+export * from "./transactions";
+export * from "./lendingPosition";
+export * from "./yieldingBank";
+export * from "./timelock";
+export * from "./tokenFeeMath";
+export * from "./feeDripMetrics";

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

@@ -0,0 +1,29 @@
+"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 });
+__exportStar(require("./enrichment"), exports);
+__exportStar(require("./lycData"), exports);
+__exportStar(require("./lookupTables"), exports);
+__exportStar(require("./ix"), exports);
+__exportStar(require("./general"), exports);
+__exportStar(require("./data"), exports);
+__exportStar(require("./cache"), exports);
+__exportStar(require("./transactions"), exports);
+__exportStar(require("./lendingPosition"), exports);
+__exportStar(require("./yieldingBank"), exports);
+__exportStar(require("./timelock"), exports);
+__exportStar(require("./tokenFeeMath"), exports);
+__exportStar(require("./feeDripMetrics"), exports);

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

@@ -0,0 +1,83 @@
+import { type Address } from "@solana/kit";
+import { IdlTypes } from "@anchor-lang/core";
+import { type CustomAccountMeta, type InstructionRefs } from "common";
+import type { LongYieldCarry } from "../idl/long_yield_carry";
+import type { DecreaseCarryPositionPlan, YieldingBankAllocationConfig } from "../client/types";
+export declare function toAnchorAllocationConfig(cfg: YieldingBankAllocationConfig): IdlTypes<LongYieldCarry>["yieldingBankAllocationConfig"];
+/**
+ * Build the carry-trade account metas that are prepended to remaining_accounts
+ * for increase/decrease carry position instructions.
+ *
+ * The two ATA accounts are tagged with `isRequiredAta` so that
+ * `getCreateAtaInstructions` will create them if they don't yet exist.
+ *
+ * Order must match `parse_carry_trade_accounts` on the Rust side:
+ *   0. token              (writable)
+ *   1. yieldingBank       (writable)
+ *   2. tokenLpDebtTa      (writable, ATA)
+ *   3. yieldingBankTa     (writable, ATA)
+ *   4. lendingPositionUserAccount (readonly)
+ *   5. lendingPositionCollateralReserve (readonly)
+ *   6. debtOracle         (readonly)
+ *   7. debtTokenProgram   (readonly)
+ *   8. instructions_sysvar (readonly)
+ */
+export declare function buildCarryTradeAccountMetas(token: Address, yieldingBank: Address, tokenLpDebtTa: Address, yieldingBankTa: Address, lendingPositionUserAccount: Address, lendingPositionCollateralReserve: Address, debtOracle: Address, debtMint: Address, debtTokenProgram: Address): CustomAccountMeta[];
+/**
+ * Build the initial remaining-accounts prefix for `rebalance_token`.
+ *
+ * Order must match `RebalanceTokenAccounts::parse` on the Rust side:
+ *   0. token                              (writable)
+ *   1. yieldingBank                       (writable)
+ *   2. sourceDebtTokenProgram             (readonly)
+ *   3. yieldingBankSourceDebtAta          (writable, ATA)
+ *   4. sourceLpUserAccount                (readonly)
+ *   5. sourceLpCollateralReserve          (readonly)
+ *   6. sourceLpDebtOracle                 (readonly — also serves as the
+ *                                          dust-sweep source_debt_oracle)
+ *   7. destinationLpUserAccount           (readonly)
+ *   8. destinationLpCollateralReserve     (readonly)
+ *   9. destinationLpDebtOracle            (readonly)
+ *
+ * The destination debt mint is referenced by inner CPIs (borrow / swap) and
+ * reaches the pool through CPI dedup; it does not need a fixed slot here.
+ * The token PDA's source-debt ATA is part of the flash-borrow / repay path
+ * and is also resolved at runtime from the CPI account pool — only the
+ * yielding-bank's source-debt ATA needs an explicit slot for the dust sweep.
+ */
+export declare function buildRebalanceTokenInitialAccounts(args: {
+    token: Address;
+    yieldingBank: Address;
+    sourceDebtMint: Address;
+    sourceDebtTokenProgram: Address;
+    yieldingBankSourceDebtAta: Address;
+    lpUserAccount: Address;
+    sourceDebtOracle: Address;
+    destinationDebtOracle: Address;
+}): CustomAccountMeta[];
+/**
+ * Normalize grouped CPI refs for `decrease_carry_position`.
+ *
+ * The plan can contain either:
+ * - one group: repay only, or
+ * - two groups: yielding-bank swap/redeem first, then repay.
+ */
+export declare function resolveDecreaseCarryIxRefs(refsGroups: InstructionRefs[], options?: {
+    hasTokenPrerequisiteCpis?: boolean;
+}): {
+    ybIxRefs?: InstructionRefs;
+    prerequisiteCpis?: InstructionRefs;
+    tokenIxRefs: InstructionRefs;
+};
+export interface ResolvedDecreaseCarryCpiPlan {
+    accounts: CustomAccountMeta[];
+    lookupTables: Address[];
+    ybIxRefs?: InstructionRefs;
+    prerequisiteCpis?: InstructionRefs;
+    tokenIxRefs: InstructionRefs;
+}
+/**
+ * Build the grouped CPI pool for `decrease_carry_position` and normalize the
+ * resulting ref groups into the instruction params the SDK passes on-chain.
+ */
+export declare function resolveDecreaseCarryCpiPlan(plan: DecreaseCarryPositionPlan): ResolvedDecreaseCarryCpiPlan;

package/dist/sdks/long-yield-carry/src/utils/ix.js

@@ -0,0 +1,165 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toAnchorAllocationConfig = toAnchorAllocationConfig;
+exports.buildCarryTradeAccountMetas = buildCarryTradeAccountMetas;
+exports.buildRebalanceTokenInitialAccounts = buildRebalanceTokenInitialAccounts;
+exports.resolveDecreaseCarryIxRefs = resolveDecreaseCarryIxRefs;
+exports.resolveDecreaseCarryCpiPlan = resolveDecreaseCarryCpiPlan;
+const common_1 = require("common");
+function toAnchorAssetConfig(cfg) {
+    return {
+        oracle: (0, common_1.toWeb3Pk)(cfg.oracle),
+        oracleType: cfg.oracleType,
+        externalLiquidity: cfg.externalLiquidityType,
+    };
+}
+function toAnchorAssetAllocationConfig(cfg) {
+    return {
+        mint: (0, common_1.toWeb3Pk)(cfg.mint),
+        decimals: cfg.decimals,
+        tokenProgram: cfg.tokenProgram,
+    };
+}
+function toAnchorExternalPositionConfig(cfg) {
+    return {
+        lendingPlatform: cfg.lendingPlatform,
+        lendingType: cfg.lendingType,
+        pool: (0, common_1.toWeb3Pk)(cfg.pool),
+        collateralReserve: (0, common_1.toWeb3Pk)(cfg.collateralReserve),
+        debtReserve: (0, common_1.toWeb3Pk)(cfg.debtReserve),
+        protocolUserAcc: (0, common_1.toWeb3Pk)(cfg.protocolUserAcc),
+        collateral: toAnchorAssetAllocationConfig(cfg.collateral),
+        debt: toAnchorAssetAllocationConfig(cfg.debt),
+    };
+}
+function toAnchorAllocationConfig(cfg) {
+    return {
+        assetHolding: cfg.assetHolding ? toAnchorAssetConfig(cfg.assetHolding) : null,
+        externalPosition: cfg.externalPosition
+            ? toAnchorExternalPositionConfig(cfg.externalPosition)
+            : null,
+    };
+}
+/**
+ * Build the carry-trade account metas that are prepended to remaining_accounts
+ * for increase/decrease carry position instructions.
+ *
+ * The two ATA accounts are tagged with `isRequiredAta` so that
+ * `getCreateAtaInstructions` will create them if they don't yet exist.
+ *
+ * Order must match `parse_carry_trade_accounts` on the Rust side:
+ *   0. token              (writable)
+ *   1. yieldingBank       (writable)
+ *   2. tokenLpDebtTa      (writable, ATA)
+ *   3. yieldingBankTa     (writable, ATA)
+ *   4. lendingPositionUserAccount (readonly)
+ *   5. lendingPositionCollateralReserve (readonly)
+ *   6. debtOracle         (readonly)
+ *   7. debtTokenProgram   (readonly)
+ *   8. instructions_sysvar (readonly)
+ */
+function buildCarryTradeAccountMetas(token, yieldingBank, tokenLpDebtTa, yieldingBankTa, lendingPositionUserAccount, lendingPositionCollateralReserve, debtOracle, debtMint, debtTokenProgram) {
+    return [
+        (0, common_1.toCustomAccountMeta)(token, true),
+        (0, common_1.toCustomAccountMeta)(yieldingBank, true),
+        (0, common_1.toCustomAccountMeta)(tokenLpDebtTa, true, {
+            owner: token,
+            mint: debtMint,
+            tokenProgram: debtTokenProgram,
+        }),
+        (0, common_1.toCustomAccountMeta)(yieldingBankTa, true, {
+            owner: yieldingBank,
+            mint: debtMint,
+            tokenProgram: debtTokenProgram,
+        }),
+        (0, common_1.toCustomAccountMeta)(lendingPositionUserAccount),
+        (0, common_1.toCustomAccountMeta)(lendingPositionCollateralReserve),
+        (0, common_1.toCustomAccountMeta)(debtOracle),
+        (0, common_1.toCustomAccountMeta)(debtTokenProgram),
+        common_1.IX_SYSVAR_META,
+    ];
+}
+/**
+ * Build the initial remaining-accounts prefix for `rebalance_token`.
+ *
+ * Order must match `RebalanceTokenAccounts::parse` on the Rust side:
+ *   0. token                              (writable)
+ *   1. yieldingBank                       (writable)
+ *   2. sourceDebtTokenProgram             (readonly)
+ *   3. yieldingBankSourceDebtAta          (writable, ATA)
+ *   4. sourceLpUserAccount                (readonly)
+ *   5. sourceLpCollateralReserve          (readonly)
+ *   6. sourceLpDebtOracle                 (readonly — also serves as the
+ *                                          dust-sweep source_debt_oracle)
+ *   7. destinationLpUserAccount           (readonly)
+ *   8. destinationLpCollateralReserve     (readonly)
+ *   9. destinationLpDebtOracle            (readonly)
+ *
+ * The destination debt mint is referenced by inner CPIs (borrow / swap) and
+ * reaches the pool through CPI dedup; it does not need a fixed slot here.
+ * The token PDA's source-debt ATA is part of the flash-borrow / repay path
+ * and is also resolved at runtime from the CPI account pool — only the
+ * yielding-bank's source-debt ATA needs an explicit slot for the dust sweep.
+ */
+function buildRebalanceTokenInitialAccounts(args) {
+    return [
+        (0, common_1.toCustomAccountMeta)(args.token, true),
+        (0, common_1.toCustomAccountMeta)(args.yieldingBank, true),
+        (0, common_1.toCustomAccountMeta)(args.sourceDebtTokenProgram),
+        (0, common_1.toCustomAccountMeta)(args.yieldingBankSourceDebtAta, true, {
+            owner: args.yieldingBank,
+            mint: args.sourceDebtMint,
+            tokenProgram: args.sourceDebtTokenProgram,
+        }),
+        (0, common_1.toCustomAccountMeta)(args.lpUserAccount),
+        (0, common_1.toCustomAccountMeta)(args.sourceDebtOracle),
+        (0, common_1.toCustomAccountMeta)(args.destinationDebtOracle),
+    ];
+}
+/**
+ * Normalize grouped CPI refs for `decrease_carry_position`.
+ *
+ * The plan can contain either:
+ * - one group: repay only, or
+ * - two groups: yielding-bank swap/redeem first, then repay.
+ */
+function resolveDecreaseCarryIxRefs(refsGroups, options) {
+    const hasTokenPrerequisiteCpis = options?.hasTokenPrerequisiteCpis ?? false;
+    const lastRefs = refsGroups[refsGroups.length - 1];
+    if (!lastRefs) {
+        throw new Error("Expected at least one CPI ref group for decrease carry flow");
+    }
+    const prerequisiteCpis = hasTokenPrerequisiteCpis ? refsGroups[refsGroups.length - 2] : undefined;
+    if (hasTokenPrerequisiteCpis && !prerequisiteCpis) {
+        throw new Error("Expected prerequisite CPI ref group for decrease carry flow");
+    }
+    const ybIxRefs = refsGroups[0] && refsGroups[0] !== prerequisiteCpis && refsGroups[0] !== lastRefs
+        ? refsGroups[0]
+        : undefined;
+    return {
+        tokenIxRefs: lastRefs,
+        ...(prerequisiteCpis ? { prerequisiteCpis } : {}),
+        ...(ybIxRefs ? { ybIxRefs } : {}),
+    };
+}
+/**
+ * Build the grouped CPI pool for `decrease_carry_position` and normalize the
+ * resulting ref groups into the instruction params the SDK passes on-chain.
+ */
+function resolveDecreaseCarryCpiPlan(plan) {
+    const cpiDataGroups = [
+        ...(plan.cpiDataGroups.length === 2 ? [plan.cpiDataGroups[0]] : []),
+        ...(plan.tokenPrerequisiteCpis?.length ? [plan.tokenPrerequisiteCpis] : []),
+        plan.cpiDataGroups[plan.cpiDataGroups.length - 1],
+    ];
+    const { accounts, refsGroups, lookupTables } = (0, common_1.createMultiCpiRefs)(cpiDataGroups, {
+        initialAccounts: plan.initialAccounts,
+    });
+    return {
+        accounts,
+        lookupTables,
+        ...resolveDecreaseCarryIxRefs(refsGroups, {
+            hasTokenPrerequisiteCpis: Boolean(plan.tokenPrerequisiteCpis?.length),
+        }),
+    };
+}

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

@@ -0,0 +1,68 @@
+import { type Address } from "@solana/kit";
+import { LendingPlatform } from "common";
+import { type LendingPlatformClientBase, type LendingPlatformData } from "lending-platforms";
+import type { LYCToken } from "../models/lycToken";
+import type { CreateTokenLendingPositionAccounts, CreateTokenLendingPositionParams } from "../client/types";
+export interface BuildLendingPositionAllocationArgs {
+    /** Lending platform client used to resolve reserves and user accounts. */
+    lendingClient: LendingPlatformClientBase<LendingPlatformData>;
+    /** Token PDA that will own the lending position. */
+    tokenPda: Address;
+    /** Collateral mint address. Used to resolve the collateral reserve in the pool. */
+    collateralMint: Address;
+    /** Debt mint address. Decimals and token program are resolved from the mint registry. */
+    debtMint: Address;
+    /** Debt reserve address. If omitted, looked up from the pool by `debtMint`. */
+    debtReserve?: Address;
+    /** Obligation / user-account ID within the lending pool. */
+    userAccountId: number;
+    /**
+     * Lending pool address. When omitted, resolved automatically from the
+     * collateral mint via {@link getEligiblePools}. Throws if the mint is
+     * listed in zero or multiple pools (caller must disambiguate).
+     */
+    pool?: Address;
+    /** @default LendingPlatform.Kamino */
+    lendingPlatform?: LendingPlatform;
+    /** @default 9000 */
+    targetUtilizationRateBps?: number;
+    /** @default 150 */
+    maxDeviationAboveTargetUtilBps?: number;
+    /** @default 300 */
+    maxDeviationBelowTargetUtilBps?: number;
+}
+export interface LendingPositionAllocation {
+    params: CreateTokenLendingPositionParams;
+    accounts: CreateTokenLendingPositionAccounts;
+    pool: Address;
+    collateralReserve: Address;
+    debtReserve: Address;
+    protocolUserAccount: Address;
+    userAccountId: number;
+}
+export interface GetAvailableTokenLendingUserAccountIdArgs {
+    lendingClient: LendingPlatformClientBase<LendingPlatformData>;
+    token: LYCToken;
+    pool: Address;
+    lendingPlatform?: LendingPlatform;
+}
+/**
+ * Resolves the lending pool for a collateral mint when the caller didn't
+ * supply one explicitly. Uses the static `KAMINO_ACCOUNTS` registry to
+ * find which pool(s) list the mint.
+ *
+ * - Exactly one pool   → returns it.
+ * - Zero pools         → throws (mint not listed anywhere).
+ * - Multiple pools     → throws (caller must pass `pool` to disambiguate).
+ */
+export declare function resolveDefaultPool(collateralMint: Address): Address;
+export declare function getAvailableTokenLendingUserAccountId({ lendingClient, token, pool, lendingPlatform, }: GetAvailableTokenLendingUserAccountIdArgs): Promise<number>;
+/**
+ * Resolves reserves, oracle data, and user-account PDA, then assembles a
+ * `CreateTokenLendingPositionParams` ready for `ix.createTokenLendingPosition`.
+ *
+ * The collateral reserve is resolved from the collateral mint against the pool.
+ * Debt metadata (decimals, token program) is resolved from the mint registry;
+ * the debt reserve address is either provided directly or looked up by mint.
+ */
+export declare function buildLendingPositionAllocation(args: BuildLendingPositionAllocationArgs): Promise<LendingPositionAllocation>;

package/dist/sdks/long-yield-carry/src/utils/lendingPosition.js

@@ -0,0 +1,105 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveDefaultPool = resolveDefaultPool;
+exports.getAvailableTokenLendingUserAccountId = getAvailableTokenLendingUserAccountId;
+exports.buildLendingPositionAllocation = buildLendingPositionAllocation;
+const common_1 = require("common");
+const lending_platforms_1 = require("lending-platforms");
+const oracle_1 = require("oracle");
+const DEFAULT_TARGET_UTILIZATION_RATE_BPS = 9000;
+// =============================================================================
+// Pool resolution
+// =============================================================================
+/**
+ * Resolves the lending pool for a collateral mint when the caller didn't
+ * supply one explicitly. Uses the static `KAMINO_ACCOUNTS` registry to
+ * find which pool(s) list the mint.
+ *
+ * - Exactly one pool   → returns it.
+ * - Zero pools         → throws (mint not listed anywhere).
+ * - Multiple pools     → throws (caller must pass `pool` to disambiguate).
+ */
+function resolveDefaultPool(collateralMint) {
+    const mintInfo = common_1.mints.get(collateralMint);
+    const symbol = mintInfo?.symbol ?? String(collateralMint);
+    const eligible = (0, lending_platforms_1.getEligiblePools)(symbol);
+    if (eligible.length === 0) {
+        throw new Error(`resolveDefaultPool: collateral mint ${symbol} (${collateralMint}) is not listed in any known lending pool`);
+    }
+    if (eligible.length > 1) {
+        throw new Error(`resolveDefaultPool: collateral mint ${symbol} is listed in multiple pools — ` +
+            `pass \`pool\` explicitly. Eligible pools:\n` +
+            eligible.map((m) => `  ${m}`).join("\n"));
+    }
+    return eligible[0];
+}
+async function getAvailableTokenLendingUserAccountId({ lendingClient, token, pool, lendingPlatform = common_1.LendingPlatform.Kamino, }) {
+    const activeProtocolUserAccounts = token.activeLendingPositions
+        .filter(({ data }) => (0, common_1.lendingPlatformToEnum)(data.platform) === lendingPlatform)
+        .map(({ data }) => (0, common_1.fromWeb3Pk)(data.protocolUserAcc));
+    return lendingClient.getAvailableUserAccountId(pool, token.address, activeProtocolUserAccounts);
+}
+// =============================================================================
+// Builder
+// =============================================================================
+/**
+ * Resolves reserves, oracle data, and user-account PDA, then assembles a
+ * `CreateTokenLendingPositionParams` ready for `ix.createTokenLendingPosition`.
+ *
+ * The collateral reserve is resolved from the collateral mint against the pool.
+ * Debt metadata (decimals, token program) is resolved from the mint registry;
+ * the debt reserve address is either provided directly or looked up by mint.
+ */
+async function buildLendingPositionAllocation(args) {
+    const { lendingClient, tokenPda, collateralMint, debtMint, userAccountId, lendingPlatform = common_1.LendingPlatform.Kamino, targetUtilizationRateBps = DEFAULT_TARGET_UTILIZATION_RATE_BPS, maxDeviationAboveTargetUtilBps = 150, maxDeviationBelowTargetUtilBps = 300, } = args;
+    const debtMintInfo = common_1.mints.get(debtMint);
+    if (!debtMintInfo) {
+        throw new Error(`buildLendingPositionAllocation: debt mint ${debtMint} not found in mint registry`);
+    }
+    const pool = args.pool ?? resolveDefaultPool(collateralMint);
+    const collateralReserve = await lendingClient.data.fetchReserveByMint(pool, collateralMint);
+    if (!collateralReserve) {
+        throw new Error(`buildLendingPositionAllocation: no reserve found for collateral mint ${collateralMint} in pool ${pool}`);
+    }
+    const collateralReserveAddress = collateralReserve.address;
+    let debtReserveAddress;
+    if (args.debtReserve) {
+        debtReserveAddress = args.debtReserve;
+    }
+    else {
+        const reserve = await lendingClient.data.fetchReserveByMint(pool, debtMint);
+        if (!reserve) {
+            throw new Error(`buildLendingPositionAllocation: no reserve found for debt mint ${debtMint} in pool ${pool}`);
+        }
+        debtReserveAddress = reserve.address;
+    }
+    const protocolUserAccount = await lendingClient.accounts.getUserAccountAddress(pool, tokenPda, userAccountId);
+    const debtOracleData = oracle_1.oracle.getOracleData(debtMint);
+    const debtTokenProgram = (0, common_1.enumToTokenProgram)(debtMintInfo.isToken2022 ? common_1.TokenProgram.Token2022 : common_1.TokenProgram.Spl);
+    const params = {
+        lendingPlatform: (0, common_1.enumToLendingPlatform)(lendingPlatform),
+        pool,
+        debtReserve: debtReserveAddress,
+        targetUtilizationRateBps,
+        maxDeviationAboveTargetUtilBps,
+        maxDeviationBelowTargetUtilBps,
+        debtMint,
+        debtDecimals: debtMintInfo.decimals,
+        debtTokenProgram,
+        debtOracleType: (0, common_1.enumToOracleType)(debtOracleData.oracleType),
+    };
+    const accounts = {
+        protocolUserAcc: protocolUserAccount,
+        collateralReserve: collateralReserveAddress,
+        debtOracle: debtOracleData.oracle,
+    };
+    return {
+        params,
+        accounts,
+        pool,
+        collateralReserve: collateralReserveAddress,
+        debtReserve: debtReserveAddress,
+        protocolUserAccount,
+        userAccountId,
+    };
+}

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

@@ -0,0 +1,55 @@
+import { type Address, Rpc, SolanaRpcApi, TransactionSigner } from "@solana/kit";
+import { type Environment } from "common";
+import { LongYieldCarryClient } from "../client/client";
+import { LYCToken } from "../models/lycToken";
+/**
+ * Get the specific lookup table for the given Token PDA (if it exists).
+ *
+ * `TOKEN_LOOKUP_TABLES` is keyed by Token PDA address.
+ */
+export declare function getLookupTableForToken(tokenPda: Address): Address | undefined;
+/**
+ * Assembles lookup table addresses for LYC transaction plans: the deployment
+ * general LUT (when not `local`), any registered per-token LUT for the given
+ * token PDAs, then any CPI/swap tables. Entries are omitted when missing or
+ * equal to the default (unused) public key; duplicates are removed in first-seen
+ * order.
+ */
+export declare function mergeLycLookupTables(environment: Environment, tokenPda?: Address | readonly Address[], existingLookupTables?: readonly Address[]): Address[];
+/**
+ * Refresh per-token lookup tables for every Token account owned by the program.
+ *
+ * @param client - Initialized client (provides RPC-backed account fetch and Kamino helpers).
+ */
+export declare function updateTokenLutsIfNeeded(signer: TransactionSigner, rpc: Rpc<SolanaRpcApi>, client: LongYieldCarryClient): Promise<void>;
+/**
+ * Extend the per-token lookup table with addresses needed for that token's
+ * instructions: mints, token/YB ATAs, registry debt-mint ATAs for the token PDA, lending protocol accounts, Kamino
+ * obligation ATAs when applicable. Lending reserve accounts live on the
+ * lending-platform LUT; price oracles for registry-listed debt/YBAs and risk
+ * assets live on the general LUT.
+ *
+ * Collateral mint is read from on-chain token state (it is not a PDA).
+ *
+ * @param client - Used for Kamino reserve metadata and reserve interaction ATAs.
+ * @param token - Fetched token model (`LYCToken`); avoids an extra fetch.
+ */
+export declare function updateTokenLutIfNeeded(signer: TransactionSigner, rpc: Rpc<SolanaRpcApi>, client: LongYieldCarryClient, token: LYCToken): Promise<void>;
+/**
+ * Extend the shared general lookup table: program IDs, well-known SPL programs,
+ * stablecoin and YBA mints (plus registry oracles), Standard + LST oracle accounts,
+ * Perena program id, every on-chain YieldingBank PDA, each bank’s ATAs for
+ * all registry debt mints (stablecoins) and yield-bearing assets, the canonical
+ * Jito tip accounts (referenced by every Jito-bundle tip ix), the ComputeBudget
+ * program (referenced by every CU-limit ix), and the deployment's role wallets:
+ * manager, protocol admin, circuit-breaker controller, and protocol fee wallet.
+ *
+ * Risk asset (Standard + LST) mints are omitted here; they appear on each token LUT
+ * as collateral.
+ *
+ * Uses {@link GENERAL_LOOKUP_TABLES} for {@link LongYieldCarryClient.environment}
+ * (`test` | `prod` only) and only that tier’s program ID.
+ *
+ * @throws If `client.environment` is `local` — there is no pinned general LUT for local.
+ */
+export declare function updateGeneralLutIfNeeded(signer: TransactionSigner, rpc: Rpc<SolanaRpcApi>, client: LongYieldCarryClient): Promise<Address>;