@kestrelfi/lyc-sdk 1.0.1 → 1.0.3

package/dist/index.d.mts

@@ -0,0 +1,2537 @@
+import { M as MintIdentifier, R as ReserveBase, E as Environment, P as PositionBalanceChange, L as LendingPlatformData, C as CpiData, a as PricedMint, S as SingleCpiExecutionPlan, b as LongYieldCarryBuilderBase, c as CreditUnlentToRedemptionEpochIxArgs, d as LongYieldCarryTransactionPlan, e as ProcessAsyncBurnIxArgs, f as ProcessAsyncBurnTxArgs, g as SetRedemptionEpochStatusIxArgs, T as TopUpUnlentReservesIxArgs, h as TopUpUnlentReservesTxArgs, i as LongYieldCarryBuilderContext, j as LYCToken, k as ClaimIncentivesIxArgs, l as ClaimIncentivesTxArgs, m as LongYieldCarrySingleInstructionBuilderService, n as CollectFeesIxArgs, o as CollectInterestIxArgs, p as CollectInterestTxArgs, q as CreateCpiPlanIxArgs, r as CreateTokenIxArgs, s as CreateTokenLendingPositionIxArgs, t as CreateTokenLendingPositionTxArgs, u as CreateYieldingBankAllocationIxArgs, v as CreateYieldingBankIxArgs, w as LendingPlatform, x as LYCYieldingBank, y as TokenLendingPositionData, z as LendingPlatformClientBase, A as AccountClient, B as BurnAmounts, D as CustomAccountMeta, I as InstructionRefs, F as DecreaseCarryPositionPlan, Y as YieldingBankAllocationConfig, G as LongYieldCarry, H as YieldingBankExternalLiquiditySource, J as TransactionCacheInvalidation, K as CreateTokenLendingPositionParams, N as CreateTokenLendingPositionAccounts, O as DecreaseCarryPositionIxArgs, Q as DecreaseCarryPositionTxArgs, U as DecreaseCarryPositionTxParams, V as DecreaseCarryPositionTxBuilderParams, W as DepositUnlentCollateralIxArgs, X as DepositUnlentCollateralTxArgs, Z as IncreaseCarryPositionIxArgs, _ as IncreaseCarryPositionTxArgs, $ as RebalanceTokenIxArgs, a0 as RebalanceTokenTxArgs, a1 as RebalanceYieldingBankIxArgs, a2 as RebalanceYieldingBankTxArgs, a3 as RecollateralizeLossIxArgs, a4 as RecollateralizeLossTxArgs, a5 as RefreshTokenStateIxArgs, a6 as RefreshTokensBuilderTxArgs, a7 as RefreshYieldingBankIxArgs, a8 as RefreshYieldingBankTxArgs, a9 as ResetTokenBurnRateLimitIxArgs, aa as SetTokenCircuitBreakerIxArgs, ab as SetTokenCircuitBreakerTxArgs, ac as SetYieldingBankCircuitBreakerIxArgs, ad as SetYieldingBankCircuitBreakerTxArgs, ae as UpdateLendingPositionConfigIxArgs, af as UpdateTokenConfigurationIxArgs, ag as UpdateTokenMetadataIxArgs, ah as UpdateYieldingBankConfigIxArgs, ai as TransactionPlan, aj as BurnTokenBuilder, ak as MintTokenBuilder, al as PdaClient, am as SwapClient, an as LendingPlatformClientRegistry, ao as SupportedLendingPlatformClients, ap as SendTransactionOptionsWithPostSuccess, aq as OutstandingIncentive, ar as KaminoClient, as as DecreaseCarryPositionBuilderParams, at as IndexedLendingPosition, au as RebalanceSwapSpec, av as RedemptionEpochSnapshot } from './core-DP6wfpME.mjs';
+export { aw as AMOUNT_ALL_SENTINEL, ax as AnchorInterestDistribution, ay as AnchorLendingType, az as AssetAllocationConfig, aA as AssetConfig, aB as BundledBurnPlan, aC as BurnTokenIxParams, aD as BurnTokenTxParams, aE as CIRCUIT_BREAKER_CONTROLLER, aF as ClaimIncentivesParams, aG as ClaimIncentivesTxParams, aH as CollectInterestParams, aI as CollectInterestTxParams, aJ as CreateCpiPlanParams, aK as CreateTokenParams, aL as CreateYieldingBankParams, aM as DEFAULT_MIN_INCENTIVE_UI_AMOUNT, aN as DEFAULT_RECOLLATERALIZE_LOSS_SLIPPAGE_BPS, aO as DecreaseCarryPositionParams, aP as DecreaseCarryPositionTxPlanParams, aQ as DecreaseCarryRepaySteering, aR as DepositUnlentCollateralParams, aS as DepositUnlentCollateralTxParams, aT as ExternalPositionConfig, aU as FeeConfig, aV as GENERAL_LOOKUP_TABLES, aW as GroupedCpiExecutionPlan, aX as IncreaseCarryPositionParams, aY as IncreaseCarryPositionTxParams, aZ as IndexedCarryPosition, a_ as InterestDistribution, a$ as LYC_ADMIN_KEYPAIR_FP, b0 as LYC_CB_KEYPAIR_FP, b1 as LYC_MANAGER_KEYPAIR_FP, b2 as LYC_PROGRAM_IDS, b3 as LYC_TOKEN_METADATA, b4 as LendingType, b5 as LongYieldCarryTransactionPlanDebug, b6 as LycTokenMetadataEntry, b7 as MANAGER, b8 as MAX_HEAP_FRAME_BYTES, b9 as MintAmounts, ba as MintTokenTxParams, bb as OracleConfigDetails, bc as PROGRAM_ID, bd as PROTOCOL_ADMIN, be as PROTOCOL_FEE_WALLET, bf as PlannedInstructionBase, bg as ProcessAsyncBurnTxParams, bh as REBALANCE_TOKEN_RATE_LIMIT_SECS, bi as REDEMPTION_EPOCH_STATUS_FUNDING, bj as REDEMPTION_EPOCH_STATUS_OPEN, bk as REDEMPTION_EPOCH_STATUS_PROCESSING, bl as RebalanceTokenParams, bm as RebalanceTokenTxParams, bn as RebalanceYieldingBankParams, bo as RebalanceYieldingBankTxParams, bp as RecollateralizeLossParams, bq as RecollateralizeLossTxParams, br as RefreshTokensTxParams, bs as SetRedemptionEpochStatusParams, bt as TOKEN_LOOKUP_TABLES, bu as TOKEN_STALENESS_THRESHOLD_SECS, bv as TokenAccountData, bw as TokenCarryPositionData, bx as TokenLpPositionAccountOverrides, by as TopUpUnlentReservesParams, bz as TopUpUnlentReservesTxParams, bA as UpdateLendingPositionConfigParams, bB as UpdateTokenConfigurationParams, bC as UpdateTokenMetadataParams, bD as UpdateYieldingBankConfigParams, bE as UserHolding, bF as enumToInterestDistribution, bG as enumToLendingType, bH as interestDistributionToEnum, bI as lendingTypeToEnum } from './core-DP6wfpME.mjs';
+import { Address, Instruction, TransactionSigner, Rpc, SolanaRpcApi, KeyPairSigner, Signature } from '@solana/kit';
+import { BN, IdlTypes, AnchorProvider } from '@anchor-lang/core';
+import { PriceResult } from 'oracle-service';
+import '@solana-program/token';
+import 'bn.js';
+import '@kamino-finance/klend-sdk';
+import '@kamino-finance/farms-sdk';
+import '@kamino-finance/scope-sdk/dist/@codegen/scope/accounts';
+
+type AssetType = "LST" | "YBA" | "Stablecoin" | "Standard";
+interface MintConfig {
+    address: Address;
+    symbol: string;
+    decimals: number;
+    name?: string;
+    assetType: AssetType;
+    isToken2022?: boolean;
+}
+/**
+ * Runtime information for a token mint.
+ * Extends MintConfig with methods for dynamic data.
+ */
+interface MintInfo extends MintConfig {
+    tokenProgram: Address;
+    /**
+     * Get the current APY for this token (LSTs & YBAs only).
+     * Returns undefined for non-LST tokens.
+     */
+    getApy?: () => Promise<number | undefined>;
+    toUiAmount: (amount: bigint | BN) => number;
+    fromUiAmount: (amount: number) => BN;
+}
+interface MintRegistryOptions {
+    /** Default: true */
+    includeDefaults?: boolean;
+    custom?: MintConfig[];
+}
+
+/**
+ * Registry for token mint information.
+ *
+ * Provides a unified interface to query token metadata by address or symbol.
+ * Supports both well-known tokens and custom configurations.
+ *
+ * @example
+ * ```typescript
+ * // Create registry with defaults
+ * const mints = new MintRegistry();
+ *
+ * // Query by symbol
+ * const usdc = mints.get("USDC");
+ * console.log(usdc?.decimals); // 6
+ *
+ * // Query by address
+ * const token = mints.get(someAddress);
+ * console.log(token?.symbol); // "USDC"
+ *
+ * // Add custom tokens
+ * const mints = new MintRegistry({
+ *   custom: [{ address: "...", symbol: "MY_TOKEN", decimals: 9 }]
+ * });
+ * ```
+ */
+declare class MintRegistry {
+    private byAddress;
+    private bySymbol;
+    constructor(options?: MintRegistryOptions);
+    /**
+     * Register a new mint configuration.
+     * Overwrites existing entries with the same address or symbol.
+     */
+    register(config: MintConfig): void;
+    /**
+     * Get mint information by address or symbol.
+     *
+     * @param mint - Mint address or token symbol (case-insensitive)
+     * @returns MintInfo if found, undefined otherwise
+     *
+     * @example
+     * ```typescript
+     * mints.get("USDC")?.decimals  // 6
+     * mints.get(usdcAddress)?.symbol  // "USDC"
+     * ```
+     */
+    get(mint: MintIdentifier): MintInfo | undefined;
+    all(): MintInfo[];
+    standardAssets(): MintInfo[];
+    stablecoins(): MintInfo[];
+    lsts(): MintInfo[];
+    yieldBearingAssets(): MintInfo[];
+    filterAssetsByType(assetType: AssetType): MintInfo[];
+    symbols(): string[];
+    addresses(): Address[];
+}
+
+interface ReservesPrices {
+    supply: PriceResult;
+    debt: PriceResult;
+}
+interface DebtAdjustmentOptions {
+    /**
+     * How the position changes when debt is adjusted.
+     * `levered` models a loop / flash-loan rebalance where borrowed funds also
+     * increase supplied collateral.
+     * `debtOnly` models changes such as carry-position borrows where only debt
+     * changes and supplied collateral stays constant.
+     */
+    positionChangeMode?: "levered" | "debtOnly";
+}
+/**
+ * Manages a supply/debt reserve pair and provides calculations
+ * for APY, simulations, and debt adjustments.
+ */
+declare class ReservesManager {
+    supplyReserve: ReserveBase;
+    debtReserve: ReserveBase;
+    private environment?;
+    private cache;
+    constructor(supplyReserve: ReserveBase, debtReserve: ReserveBase, environment?: Environment | undefined);
+    /** Max LTV ratio (0-1), using e-mode override when the pair qualifies */
+    get maxLtv(): number;
+    /**
+     * Returns supply and debt token prices.
+     * Uses reserve-embedded prices when available, otherwise fetches from oracle and caches the result.
+     */
+    prices(): Promise<ReservesPrices>;
+    /**
+     * Net APY for the lending & borrowing position.
+     * Accounts for eligible incentives based on the paired reserve relationship.
+     */
+    get netAPY(): number;
+    /**
+     * Simulates net APY after hypothetical position changes.
+     * Accounts for eligible incentives based on the paired reserve relationship.
+     */
+    simulateNetAPY(args: PositionBalanceChange[]): number;
+    /** Current LTV utilization rate in basis points (0-10000) given USD position values */
+    calcLtvUtilizationRateBps(supplyUsd: number, debtUsd: number): number;
+    /**
+     * Calculates the USD debt adjustment needed to reach a target LTV utilization rate.
+     * Positive result = boost (increase leverage), negative = deleverage.
+     */
+    calcDebtAdjustmentUsd(uiSupplyAmount: number, uiDebtAmount: number, targetLtvUtilizationRateBps: number, options?: DebtAdjustmentOptions): Promise<number>;
+}
+
+interface LendingPositionState {
+    prices: ReservesPrices;
+    supplyUsd: number;
+    debtUsd: number;
+}
+interface CollateralPriceTriggerLevel {
+    currentCollateralPrice: number;
+    triggerCollateralPrice: number;
+    targetUtilizationRateBps: number;
+    priceMode: "realtime" | "ema";
+    priceChangePct: number;
+}
+interface CollateralPriceTriggerBand {
+    lower?: CollateralPriceTriggerLevel;
+    upper?: CollateralPriceTriggerLevel;
+}
+interface LendingPositionUtilizationRatesBps {
+    realtime: number;
+    ema: number;
+}
+interface LendingPositionSelectedPrice {
+    value: number;
+    source: "realtime" | "ema" | "ema_fallback_realtime";
+}
+interface LendingPositionUtilizationPrices {
+    realtime: {
+        collateral: LendingPositionSelectedPrice;
+        debt: LendingPositionSelectedPrice;
+    };
+    ema: {
+        collateral: LendingPositionSelectedPrice;
+        debt: LendingPositionSelectedPrice;
+    };
+}
+interface LendingPositionInspectMetrics {
+    utilizationRateBps: LendingPositionUtilizationRatesBps;
+    utilizationPrices: LendingPositionUtilizationPrices;
+    triggerBand: CollateralPriceTriggerBand;
+}
+
+/**
+ * Manages a leveraged lending position (collateral/debt pair): sizing decisions,
+ * threshold triggers, and realtime/EMA-priced state. Wraps a {@link ReservesManager}.
+ *
+ * Generic across protocols — the constructor takes pool + user-account addresses
+ * directly. SDK-specific subclasses may add convenience wrappers that derive
+ * targets from their own on-chain config.
+ */
+declare class LendingPositionManager {
+    readonly lpData: LendingPlatformData;
+    readonly pool: Address;
+    readonly userAccount: Address;
+    readonly reservesManager: ReservesManager;
+    constructor(lpData: LendingPlatformData, pool: Address, userAccount: Address, collateralReserve: ReserveBase, debtReserve: ReserveBase, environment?: Environment);
+    /**
+     * Calculates the UI debt amount change needed to reach the target LTV utilization
+     * rate. Positive values indicate borrowing; negative values indicate repaying.
+     */
+    calcDebtChangeAmount(targetUtilizationRateBps: number): Promise<number>;
+    /**
+     * Fetch current supply and debt position amounts in UI units.
+     */
+    getLendingPositionAmounts(): Promise<{
+        supplyUiAmount: number;
+        debtUiAmount: number;
+    }>;
+    /**
+     * Calculates the utilization rate the source position must reach before a
+     * collateral withdrawal so that, after the withdrawal, the position lands at
+     * the desired target utilization rate.
+     *
+     * Units:
+     * - current supply USD = supplied collateral before withdrawal
+     * - withdrawn USD = collateral requested for the rebalance move
+     * - post-withdraw target = desired utilization after collateral leaves the LP
+     *
+     * Formula:
+     * pre_withdraw_target = post_withdraw_target * (current_supply - withdrawn) / current_supply
+     *
+     * The result is floored to stay conservatively at or below the requested
+     * post-withdraw target once integer basis-point rounding is applied.
+     */
+    calcPreWithdrawalTargetUtilizationRateBps(withdrawUiCollateralAmount: number, postWithdrawalTargetUtilizationRateBps: number): Promise<number>;
+    /**
+     * Calculates the UI debt amount change needed before a collateral withdrawal
+     * so that the position lands at the desired utilization rate after the
+     * withdrawal completes.
+     */
+    calcDebtChangeAmountForCollateralWithdrawal(withdrawUiCollateralAmount: number, postWithdrawalTargetUtilizationRateBps: number): Promise<number>;
+    /**
+     * Calculates the utilization rate after withdrawing collateral while leaving
+     * debt unchanged.
+     */
+    calcPostWithdrawalUtilizationRateBps(withdrawUiCollateralAmount: number): Promise<number>;
+    /**
+     * For burn-token liquidity management: checks that a withdrawal of
+     * `collateralWithdrawalUiAmount` (collateral mint UI units) leaves strictly
+     * positive supplied collateral, matching the pre-withdraw math used in
+     * {@link calcPreWithdrawalTargetUtilizationRateBps}.
+     *
+     * Returns realtime LTV utilization in basis points when eligible; null when the
+     * obligation is missing, has no supply, prices are invalid, or the withdrawal
+     * would consume the full (or more than the full) collateral position.
+     */
+    getBurnUnwindEligibility(collateralWithdrawalUiAmount: number): Promise<{
+        utilizationRateBps: number;
+    } | null>;
+    /**
+     * Returns the collateral price levels that would place the position exactly on
+     * its lower and upper utilization trigger bands.
+     *
+     * The lower-band trigger uses EMA pricing (to mirror boost-trigger semantics),
+     * while the upper-band trigger uses realtime pricing (to mirror unwind-trigger
+     * semantics).
+     */
+    getCollateralPriceTriggerBand(params: {
+        lowerTargetUtilizationRateBps: number;
+        upperTargetUtilizationRateBps: number;
+    }): Promise<CollateralPriceTriggerBand>;
+    getUtilizationRatesBps(): Promise<LendingPositionUtilizationRatesBps | null>;
+    getUtilizationPrices(): Promise<LendingPositionUtilizationPrices | null>;
+    getInspectMetrics(params: {
+        lowerTargetUtilizationRateBps: number;
+        upperTargetUtilizationRateBps: number;
+    }): Promise<LendingPositionInspectMetrics | null>;
+    protected getPositionState(mode: "realtime" | "ema"): Promise<LendingPositionState | null>;
+    private calcPositionSupplyDebtUsd;
+    private selectPrice;
+    private getCollateralPriceTriggerLevel;
+    /**
+     * Solve for collateral price at a target utilization:
+     * utilization = debtUsd / (collateralAmount * collateralPrice * maxLtv).
+     */
+    private calcCollateralPriceForTargetUtilization;
+    private calcDebtChangeAmountFromState;
+    /**
+     * Quantize to the debt mint's base-unit precision. Borrows floor; repays round
+     * away from zero so deleveraging does not undershoot.
+     */
+    private quantizeDebtChangeUiAmount;
+    /** Cap positive borrows to obligation headroom when the platform exposes it. */
+    private capPositiveBorrowToProtocolHeadroom;
+    private calcPreWithdrawalTargetUtilizationRateBpsFromState;
+    private calcPostWithdrawalUtilizationRateBpsFromState;
+    protected assertValidUtilizationRateBps(value: number, field: string): void;
+    /**
+     * Unwind/boost trigger bands may exceed 100% LTV utilization (up to 10_500 bps
+     * on-chain). Debt-sizing paths still use {@link assertValidUtilizationRateBps}.
+     */
+    protected assertValidTriggerBandUtilizationRateBps(value: number, field: string): void;
+}
+
+/**
+ * Deterministic inputs for deriving a `collect_interest` plan.
+ */
+interface CollectInterestPlanParams {
+    /** Yielding bank whose active carry position should be partially redeemed. */
+    yieldingBank: Address;
+    /**
+     * Minimum net yield (in USD) below which collection is skipped.
+     * Prevents wasteful swaps when accrued interest is negligible.
+     * Value is in human-readable USD (e.g. 0.5 = $0.50).
+     */
+    minYieldUsd?: number;
+}
+/**
+ * One yielding-bank holding that should be redeemed during interest collection.
+ */
+interface CollectInterestHoldingPlan {
+    /** Mint held by the yielding bank allocation. */
+    mint: Address;
+    /** Amount to redeem in raw base units for this holding. */
+    amount: BN;
+    /** Whether this holding came from the bank's base-asset slot. */
+    isBaseAsset: boolean;
+}
+/**
+ * Deterministic `collect_interest` plan produced by `client.planner`.
+ *
+ * This captures protocol-derived values only: the active carry position,
+ * shares to burn, and the ordered bank holdings that should be redeemed.
+ * It intentionally does not encode swap venue or routing policy.
+ */
+interface CollectInterestPlan {
+    /** Token PDA whose carry position is collecting accrued yield. */
+    token: Address;
+    /** Yielding bank the active carry position is allocated to. */
+    yieldingBank: Address;
+    /** Base mint configured on the yielding bank. */
+    baseMint: Address;
+    /** Default redemption asset that accrued interest is collected from. */
+    redemption: PricedMint;
+    /** Token collateral asset that collection must ultimately end in. */
+    collateral: PricedMint;
+    /** Index of the active `debtCarry` entry on the token account. */
+    carryIndex: number;
+    /** Number of carry-position shares the program should burn. */
+    sharesToBurn: BN;
+    /** USD value represented by the burned shares, in program-scale units. */
+    sharesBurnedValueUsd: BN;
+    /** Ordered yielding-bank holdings to redeem before final collateral settlement. */
+    holdingsToRedeem: CollectInterestHoldingPlan[];
+}
+/**
+ * Caller-controlled routing inputs for turning a deterministic collect-interest
+ * plan into concrete swap CPI data.
+ */
+interface CollectInterestRouteBuilderParams {
+    /** Final output mint. Defaults to `plan.collateral.mint`. */
+    outputMint?: Address;
+    /** Slippage tolerance applied to all collect-interest swaps. Defaults to `100`. */
+    slippageBps?: number;
+}
+/**
+ * Manual CPI inputs for callers that already know the exact swap sequence they
+ * want `collect_interest` to execute.
+ */
+interface CollectInterestBuilderParams {
+    /** Yielding bank whose shares will be redeemed. */
+    yieldingBank: Address;
+    /** Prebuilt CPI descriptors that swap redeemed assets into collateral. */
+    cpiData: CpiData[];
+}
+/**
+ * Fully executable `collect_interest` plan produced by `client.routeBuilder`.
+ *
+ * Extends the deterministic planner result with the exact CPI sequence,
+ * pre-instructions, and initial accounts required by the final tx composer.
+ */
+interface CollectInterestExecutionPlan extends CollectInterestPlan, SingleCpiExecutionPlan {
+}
+/**
+ * Precomputed execution-plan wrapper accepted by `client.tx.collectInterest.getTx({...})`.
+ */
+interface CollectInterestTxPlanParams {
+    /** Route-builder result previously returned by `client.routeBuilder.buildCollectInterestRoutePlan()`. */
+    plan: CollectInterestExecutionPlan;
+}
+
+declare class SetRedemptionEpochStatusBuilder extends LongYieldCarryBuilderBase<SetRedemptionEpochStatusIxArgs, SetRedemptionEpochStatusIxArgs> {
+    getTx(args: SetRedemptionEpochStatusIxArgs): Promise<LongYieldCarryTransactionPlan>;
+    getIx(args: SetRedemptionEpochStatusIxArgs): Promise<Instruction>;
+}
+declare class TopUpUnlentReservesBuilder extends LongYieldCarryBuilderBase<TopUpUnlentReservesIxArgs, TopUpUnlentReservesTxArgs> {
+    getTx(args: TopUpUnlentReservesTxArgs): Promise<LongYieldCarryTransactionPlan>;
+    getIx(args: TopUpUnlentReservesIxArgs): Promise<Instruction>;
+}
+declare class CreditUnlentToRedemptionEpochBuilder extends LongYieldCarryBuilderBase<CreditUnlentToRedemptionEpochIxArgs, CreditUnlentToRedemptionEpochIxArgs> {
+    getTx(args: CreditUnlentToRedemptionEpochIxArgs): Promise<LongYieldCarryTransactionPlan>;
+    getIx(args: CreditUnlentToRedemptionEpochIxArgs): Promise<Instruction>;
+}
+declare class ProcessAsyncBurnBuilder extends LongYieldCarryBuilderBase<ProcessAsyncBurnIxArgs, ProcessAsyncBurnTxArgs> {
+    getTx(args: ProcessAsyncBurnTxArgs): Promise<LongYieldCarryTransactionPlan>;
+    getIx(args: ProcessAsyncBurnIxArgs): Promise<Instruction>;
+}
+
+declare function getRefreshTokenInstructionsIfStale(context: LongYieldCarryBuilderContext, signer: Address, tokenData: LYCToken): Promise<Instruction[]>;
+
+declare class ClaimIncentivesBuilder extends LongYieldCarryBuilderBase<ClaimIncentivesIxArgs, ClaimIncentivesTxArgs> {
+    getIx(args: ClaimIncentivesIxArgs): Promise<Instruction>;
+    getTx(args: ClaimIncentivesTxArgs): Promise<LongYieldCarryTransactionPlan>;
+    private resolveIncentiveOracle;
+}
+
+/**
+ * Collects pending fees for either the curator or the protocol. The caller
+ * passes the `authority` signer. If it is `PROTOCOL_ADMIN`, the protocol bucket and
+ * protocol fee wallet are used (even when that address is also the token curator).
+ * Otherwise, if it is the curator only, the curator bucket and curator fee wallet are used.
+ * Throws client-side if the signer matches neither role (mirroring the on-chain check).
+ */
+declare class CollectFeesBuilder extends LongYieldCarrySingleInstructionBuilderService<CollectFeesIxArgs> {
+    getIx(args: CollectFeesIxArgs): Promise<Instruction>;
+    protected buildLookupTables(args: CollectFeesIxArgs): Promise<readonly Address[]>;
+}
+
+declare class CollectInterestBuilder extends LongYieldCarryBuilderBase<CollectInterestIxArgs, CollectInterestTxArgs> {
+    getIx(args: CollectInterestIxArgs): Promise<Instruction>;
+    getTx(args: CollectInterestTxArgs): Promise<LongYieldCarryTransactionPlan>;
+}
+
+declare class CreateCpiPlanBuilder extends LongYieldCarrySingleInstructionBuilderService<CreateCpiPlanIxArgs> {
+    getIx(args: CreateCpiPlanIxArgs): Promise<Instruction>;
+}
+
+declare class CreateTokenBuilder extends LongYieldCarrySingleInstructionBuilderService<CreateTokenIxArgs> {
+    getIx(args: CreateTokenIxArgs): Promise<Instruction>;
+    protected buildLookupTables(): Promise<readonly Address[]>;
+}
+
+declare class CreateTokenLendingPositionBuilder extends LongYieldCarryBuilderBase<CreateTokenLendingPositionIxArgs, CreateTokenLendingPositionTxArgs> {
+    getIx(args: CreateTokenLendingPositionIxArgs): Promise<Instruction>;
+    getTx(txArgs: CreateTokenLendingPositionTxArgs): Promise<LongYieldCarryTransactionPlan>;
+    private buildSetupCpis;
+    private buildRefreshCpis;
+}
+
+declare class CreateYieldingBankAllocationBuilder extends LongYieldCarrySingleInstructionBuilderService<CreateYieldingBankAllocationIxArgs> {
+    getIx(args: CreateYieldingBankAllocationIxArgs): Promise<Instruction>;
+    protected buildLookupTables(): Promise<readonly Address[]>;
+}
+
+declare class CreateYieldingBankBuilder extends LongYieldCarrySingleInstructionBuilderService<CreateYieldingBankIxArgs> {
+    getIx(args: CreateYieldingBankIxArgs): Promise<Instruction>;
+    protected buildLookupTables(): Promise<readonly Address[]>;
+}
+
+type FeeDripAbsorptionStatus = "estimated" | "no_fees" | "parked" | "unavailable";
+interface FeeDripMetricsInput {
+    currentPriceRaw: bigint;
+    apyReferencePriceRaw: bigint;
+    apyReferenceTs: bigint;
+    /** Timestamp at which `currentPriceRaw` was last written on-chain. */
+    currentPriceTs: bigint;
+    totalSupplyRaw: bigint;
+    tokenDecimals: number;
+    undrippedFeeCollateralRaw: bigint;
+    feeDripMaxApyBps: number;
+    nowTs: bigint;
+}
+interface FeeDripMetrics {
+    /** Simple annualized price return from the on-chain APY reference, in basis points. */
+    currentApyBps: number | null;
+    /** Estimated seconds until the current fee buffer is fully released. */
+    absorptionEtaSeconds: number | null;
+    absorptionStatus: FeeDripAbsorptionStatus;
+}
+/**
+ * Derives the current fee-window APY and a simple absorption ETA.
+ *
+ * ETA assumes fees release at the configured target APY:
+ *   remaining_price_return = buffer * 10^decimals / (supply * price)
+ *   eta_seconds = remaining_price_return / (target_apy_bps / 10_000) * seconds_per_year
+ *
+ * A zero target parks the buffer. Current-window APY is reported separately and
+ * does not change the ETA.
+ */
+declare function calculateFeeDripMetrics(input: FeeDripMetricsInput): FeeDripMetrics;
+
+interface YieldingBankInspectSnapshotArgs {
+    environment: "local" | "test" | "prod";
+    mintRegistry: MintRegistry;
+    timelocksEnabledInLocal?: boolean;
+}
+interface TokenInspectSnapshotArgs {
+    environment: "local" | "test" | "prod";
+    mintRegistry: MintRegistry;
+    yieldingBanks: readonly LYCYieldingBank[];
+    kaminoData: LendingPlatformData;
+    timelocksEnabledInLocal?: boolean;
+    /** Unix timestamp override for deterministic APY/fee-drip projections. */
+    nowTs?: number;
+}
+interface EnrichedYieldingBankHolding {
+    kind: "base" | "asset";
+    mint: Address;
+    symbol: string;
+    amountRaw: bigint;
+    amountUi: number;
+    decimals: number;
+    priceRaw: bigint;
+    priceUi: number;
+    isTimelocked: boolean;
+}
+interface EnrichedYieldingBankExternalPosition {
+    platform: LendingPlatform;
+    pool: Address;
+    tvlRaw: bigint;
+    tvlUsd: number;
+    isTimelocked: boolean;
+}
+interface EnrichedYieldingBankSnapshot {
+    address: Address;
+    id: number;
+    curator: Address;
+    baseMint: Address;
+    baseSymbol: string;
+    isActive: boolean;
+    circuitBreaker: number;
+    decimals: number;
+    tvlRaw: bigint;
+    tvlUsd: number;
+    sharePrice: number;
+    totalShares: number;
+    lastRefreshedTs: bigint;
+    lastRebalancedTs: bigint;
+    isTimelocked: boolean;
+    defaultRedemptionMint?: Address;
+    defaultRedemptionSymbol?: string;
+    holdings: EnrichedYieldingBankHolding[];
+    externalYieldingPositions: EnrichedYieldingBankExternalPosition[];
+}
+interface EnrichedTokenCollateralSnapshot {
+    mint: Address;
+    symbol: string;
+    decimals: number;
+    unlentAmountRaw: bigint;
+    unlentAmountUi: number;
+    pendingUnwindResidualRaw: bigint;
+    pendingUnwindResidualUi: number;
+    oraclePriceRaw: bigint;
+    oraclePriceOnChainUi: number;
+    oraclePriceRealtimeUi: number;
+    oraclePriceEmaUi: number;
+    oracle: Address;
+    /** Set for composite oracle types (e.g. PythSplStake stake pool). */
+    secondaryOracle?: Address;
+    lastRefreshedTs: bigint;
+}
+interface EnrichedTokenLendingPosition {
+    index: number;
+    platform: LendingPlatform;
+    withdrawPending: boolean;
+    pool: Address;
+    userAccount: Address;
+    collateralAmountRaw: bigint;
+    collateralAmountUi: number;
+    collateralDecimals: number;
+    collateralSymbol: string;
+    debtAmountRaw: bigint;
+    debtAmountUi: number;
+    debtTvlUsdRaw: bigint;
+    debtTvlUsd: number;
+    debtMint: Address;
+    debtSymbol: string;
+    debtDecimals: number;
+    debtPriceRaw: bigint;
+    debtPriceUi: number;
+    onChainUtilizationRateBps: number;
+    targetUtilizationRateBps: number;
+    maxDeviationAboveTargetUtilBps: number;
+    maxDeviationBelowTargetUtilBps: number;
+    /** Stamped only by `rebalance_token`; 0 means never rebalanced. */
+    lastRebalancedTs: bigint;
+    inspectMetrics?: LendingPositionInspectMetrics;
+}
+interface EnrichedTokenCarryPosition {
+    index: number;
+    yieldingBankId: number;
+    yieldingBankAddress?: Address;
+    baseMint: Address;
+    baseSymbol: string;
+    sharesRaw: bigint;
+    sharesUi?: number;
+    shareDecimals?: number;
+    tvlUsdRaw: bigint;
+    tvlUsd: number;
+}
+interface EnrichedTokenCarrySummary {
+    totalCarryTvlUsdRaw: bigint;
+    totalCarryTvlUsd: number;
+    totalDebtUsdRaw: bigint;
+    totalDebtUsd: number;
+    netYieldUsdRaw: bigint;
+    netYieldUsd: number;
+}
+interface EnrichedTokenFeesSnapshot {
+    mintingFeeBps: number;
+    burningFeeBps: number;
+    performanceFeeBps: number;
+    protocolMintBurnPctBps: number;
+    curatorMintBurnPctBps: number;
+    holderMintBurnPctBps: number;
+    curatorPerfPctBps: number;
+    feeDripMaxApyBps: number;
+    undrippedFeeCollateralRaw: bigint;
+    undrippedFeeCollateralUi: number;
+    apyReferencePriceRaw: bigint;
+    apyReferencePrice: number;
+    apyReferenceTs: bigint;
+    currentApyBps: number | null;
+    absorptionEtaSeconds: number | null;
+    absorptionStatus: FeeDripAbsorptionStatus;
+    pendingProtocolFeesRaw: bigint;
+    pendingProtocolFeesUi: number;
+    pendingCuratorFeesRaw: bigint;
+    pendingCuratorFeesUi: number;
+}
+interface EnrichedTokenSnapshot {
+    address: Address;
+    id: number;
+    curator: Address;
+    mint: Address;
+    decimals: number;
+    isActive: boolean;
+    price: number;
+    totalSupply: number;
+    tvlUsdRaw: bigint;
+    tvlUsd: number;
+    lastRefreshedTs: bigint;
+    firstMintTs: bigint;
+    collateral: EnrichedTokenCollateralSnapshot;
+    lendingPositions: EnrichedTokenLendingPosition[];
+    carryPositions: EnrichedTokenCarryPosition[];
+    carrySummary: EnrichedTokenCarrySummary;
+    /** True when the token is active and its positive carry surplus is at most 1 bp of debt. */
+    hasInterestToCollect: boolean;
+    fees: EnrichedTokenFeesSnapshot;
+}
+
+declare function buildYieldingBankInspectSnapshot(bank: LYCYieldingBank, args: YieldingBankInspectSnapshotArgs): EnrichedYieldingBankSnapshot;
+declare function buildTokenInspectSnapshot(token: LYCToken, args: TokenInspectSnapshotArgs): Promise<EnrichedTokenSnapshot>;
+
+/**
+ * Pure helpers over decoded long_yield_carry account data (`Token`, `YieldingBank`, etc.):
+ * selection logic, liquidity / holding analysis, and other algorithms that do not belong on
+ * `AccountClient` or transaction composers.
+ */
+
+/** Any object that can resolve a lending-platform client for a given position. */
+interface LendingPlatformResolver {
+    getForPosition(position: TokenLendingPositionData): LendingPlatformClientBase<LendingPlatformData>;
+}
+declare function getBurnCollateralWithdrawalAmount(tokenData: LYCToken, burnAmount: BN | number): bigint;
+declare function getBurnCollateralWithdrawalUiAmount(tokenData: LYCToken, burnAmount: BN | number, includeOneUnitTolerance?: boolean): number;
+declare function computeBurnAmountsForFrontendEstimate(_account: AccountClient, tokenData: LYCToken, burnAmount: BN | number, _resolver: LendingPlatformResolver): Promise<BurnAmounts>;
+/**
+ * True when at least one active lending position can supply the collateral implied by `burnAmount`
+ * for a liquidity-managed burn (same eligibility filter as {@link findPositionToUnwindForBurn}).
+ */
+declare function hasLendingPositionCoveringBurn(tokenData: LYCToken, burnAmount: BN | number, resolver: LendingPlatformResolver): Promise<boolean>;
+/**
+ * True when the best burn-candidate lending position can absorb a collateral
+ * withdrawal for `burnAmount` without pushing the LTV utilization rate above
+ * the position's upper deviation band — meaning no `decrease_carry_position`
+ * (debt repayment) is required.
+ *
+ * Should only be called after {@link hasLendingPositionCoveringBurn} returns
+ * `true`; uses the same candidate selection logic as
+ * {@link findPositionToUnwindForBurn}.
+ */
+declare function isWithdrawOnlyBurnFeasible(tokenData: LYCToken, burnAmount: BN | number, resolver: LendingPlatformResolver): Promise<boolean>;
+/**
+ * Chooses which `lendingPositions` slot to unwind for a burn liquidity-managed tx.
+ *
+ * Considers only active positions with a supported platform and collateral mint
+ * matching the token. Filters to positions that can cover `collateralWithdrawalUiAmount`
+ * (same strict less-than full-supply rule as pre-withdraw repay sizing). Among those,
+ * picks the position with the most deposited collateral (tie → lower index) so the
+ * burn unwind comes out of the deepest slot and small positions are left intact.
+ *
+ * @param getLendingPlatformClient - Resolves the Kamino (etc.) client for a position;
+ *   kept injectable so callers are not tied to transaction wiring.
+ */
+declare function findPositionToUnwindForBurn(tokenData: LYCToken, collateralWithdrawalUiAmount: number, resolver: LendingPlatformResolver): Promise<{
+    lendingPositionIndex: number;
+    position: TokenLendingPositionData;
+}>;
+/**
+ * Picks the yielding bank to fund repay/swap during a burn liquidity-managed tx.
+ *
+ * Enumerates banks derived from active `debtCarry` entries on the token, fetches
+ * each account via `account.fetchYieldingBanks`, then:
+ * 1. Prefer a bank whose **debt mint** holding is at least `requiredDebtUiAmount` (debt token UI)
+ *    and is largest among those sufficient balances (headroom for the unwind repay).
+ * 2. Otherwise prefer the bank whose **default redemption mint** holding has the largest
+ *    balance in UI units (`toUiAmount` with the holding's on-chain `decimals`).
+ *
+ * Permissionless burn planning does not pass `sourceMint`; the default-redemption fallback
+ * assumes that path is viable for the chosen bank's holdings.
+ */
+declare function findBestYieldingBankForBurn(account: AccountClient, tokenData: LYCToken, position: TokenLendingPositionData, requiredDebtUiAmount: number): Promise<{
+    yieldingBank: Address;
+}>;
+
+/**
+ * Get the specific lookup table for the given Token PDA (if it exists).
+ *
+ * `TOKEN_LOOKUP_TABLES` is keyed by Token PDA address.
+ */
+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.
+ */
+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).
+ */
+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.
+ */
+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 manager.
+ *
+ * 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.
+ */
+declare function updateGeneralLutIfNeeded(signer: TransactionSigner, rpc: Rpc<SolanaRpcApi>, client: LongYieldCarryClient): Promise<Address>;
+
+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)
+ */
+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.
+ */
+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.
+ */
+declare function resolveDecreaseCarryIxRefs(refsGroups: InstructionRefs[], options?: {
+    hasTokenPrerequisiteCpis?: boolean;
+}): {
+    ybIxRefs?: InstructionRefs;
+    prerequisiteCpis?: InstructionRefs;
+    tokenIxRefs: InstructionRefs;
+};
+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.
+ */
+declare function resolveDecreaseCarryCpiPlan(plan: DecreaseCarryPositionPlan): ResolvedDecreaseCarryCpiPlan;
+
+/**
+ * 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.
+ */
+declare function podBoolToNumber(val: {
+    0: number;
+} | number): number;
+/**
+ * Build external-liquidity source descriptors for one mint across multiple accounts.
+ */
+declare function toYieldingBankExternalLiquiditySources(mint: Address, accounts: Address[]): YieldingBankExternalLiquiditySource[];
+/**
+ * Convert a raw token amount and raw oracle price into 8-decimal USD TVL units.
+ */
+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.
+ */
+declare function currentEpochId(): BN;
+
+/**
+ * First token ID (0–255) not yet used for the given yToken mint address.
+ *
+ * Tries `fetchAllTokens` first, then scans PDAs if RPC program accounts are unavailable.
+ */
+declare function findFreeTokenId(client: LongYieldCarryClient, mint: Address): Promise<number>;
+/**
+ * First yielding-bank ID (0–255) not yet used for the given base mint.
+ */
+declare function findFreeYieldingBankId(client: LongYieldCarryClient, baseMint: Address): Promise<number>;
+
+declare function getTokenCacheInvalidation(token: Address): TransactionCacheInvalidation;
+declare function getYieldingBankCacheInvalidation(yieldingBank: Address): TransactionCacheInvalidation;
+
+/**
+ * Compose ordered phases into one bundle-ready plan without making an entire
+ * phase indivisible. Existing atomic segments are preserved, and each phase
+ * after the first is forced to start in a new transaction.
+ */
+declare function composePhasedTransactionPlan(phases: LongYieldCarryTransactionPlan[]): LongYieldCarryTransactionPlan;
+declare function setTokenCircuitBreaker(client: LongYieldCarryClient, signer: KeyPairSigner, token: Address, active: boolean): Promise<Signature>;
+declare function setYieldingBankCircuitBreaker(client: LongYieldCarryClient, signer: KeyPairSigner, yieldingBank: Address, active: boolean): Promise<Signature>;
+/**
+ * Creates a new yToken SPL mint with mint authority = token PDA, using the next free token ID.
+ */
+declare function createYTokenMint(client: LongYieldCarryClient, payer: KeyPairSigner, decimals?: number, tokenProgram?: Address): Promise<{
+    mintSigner: KeyPairSigner;
+    tokenPda: Address;
+    tokenPdaBump: number;
+    id: number;
+}>;
+
+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;
+}
+interface LendingPositionAllocation {
+    params: CreateTokenLendingPositionParams;
+    accounts: CreateTokenLendingPositionAccounts;
+    pool: Address;
+    collateralReserve: Address;
+    debtReserve: Address;
+    protocolUserAccount: Address;
+    userAccountId: number;
+}
+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).
+ */
+declare function resolveDefaultPool(collateralMint: Address): Address;
+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.
+ */
+declare function buildLendingPositionAllocation(args: BuildLendingPositionAllocationArgs): Promise<LendingPositionAllocation>;
+
+/**
+ * Returns the first active yielding bank (circuit breaker off, lowest id).
+ *
+ * TODO: This naively returns the first active bank regardless of what the
+ * lending position actually borrows. It works today because there is one
+ * yielding bank (USDC) and all debt is denominated in USDC. When a second
+ * yielding bank exists (e.g. SOL-denominated) or a lending position borrows
+ * a non-USDC asset, the carry-manager would route that debt into the wrong
+ * bank. At that point this function needs to accept the lending position's
+ * debt mint and match it to the correct bank — either via the token's
+ * existing `debtCarry` entries or an explicit per-token bank configuration.
+ *
+ * @returns The yielding bank address, or `null` if no active bank exists.
+ */
+declare function resolveYieldingBankForPosition(allBanks: LYCYieldingBank[]): Address | null;
+/**
+ * Returns the index of the first active lending position for the given
+ * platform, or `null` if the token has no positions on that platform.
+ */
+declare function firstActiveLendingIndex(token: LYCToken, platform: LendingPlatform): number | null;
+
+type TimelockKind = "touch" | "cleanup";
+interface TimelockStatus {
+    enabled: boolean;
+    isTimelocked: boolean;
+    timeCreated: bigint;
+    unlockAt?: bigint;
+    remainingSecs: bigint;
+}
+interface TimelockOptions {
+    enableLocalTimelocks?: boolean;
+}
+declare function timelocksEnabled(environment: Environment, options?: TimelockOptions): boolean;
+declare function getTimelockStatus(environment: Environment, timeCreated: bigint | number | BN, kind: TimelockKind, options?: TimelockOptions): TimelockStatus;
+type AllocationTimelockKind = TimelockKind;
+type AllocationTimelockStatus = TimelockStatus;
+declare const allocationTimelocksEnabled: typeof timelocksEnabled;
+declare const getAllocationTimelockStatus: typeof getTimelockStatus;
+
+/**
+ * Collectable net yield in 8-decimal normalized USD: any carry surplus above
+ * debt. Returns `0n` when carry TVL does not exceed debt TVL.
+ *
+ * Used by SDK planning and metrics to size collect-interest attempts.
+ *
+ * @param totalCarryTvlUsd Aggregate carry-position TVL (8-dec USD).
+ * @param totalDebtUsd Aggregate lending-position debt TVL (8-dec USD).
+ */
+declare function collectableNetYieldUsd(totalCarryTvlUsd: bigint, totalDebtUsd: bigint): bigint;
+
+/**
+ * Options for {@link DecreaseCarryPositionBuilder.buildTx}. Supports pre-merged CPI accounts
+ * and custom heap size.
+ */
+type DecreaseCarryPositionBuildTxOptions = {
+    includePreInstructions: boolean;
+    /** Defaults to {@link MAX_HEAP_FRAME_BYTES}. */
+    heapFrameBytes?: number;
+    /**
+     * When set, skips internal {@link resolveDecreaseCarryCpiPlan}(plan). Use when remaining
+     * accounts already include additional CPI account slots (e.g. lending withdraw merged for burn).
+     */
+    resolvedCpiPlan?: ResolvedDecreaseCarryCpiPlan;
+    /** When set, the DCP loss is attributed to this epoch instead of socialised into the price. */
+    redemptionEpoch?: Address;
+};
+declare class DecreaseCarryPositionBuilder extends LongYieldCarryBuilderBase<DecreaseCarryPositionIxArgs, DecreaseCarryPositionTxArgs> {
+    constructor(context: LongYieldCarryBuilderContext);
+    getIx(args: DecreaseCarryPositionIxArgs): Promise<Instruction>;
+    getTx(args: DecreaseCarryPositionTxArgs): Promise<LongYieldCarryTransactionPlan>;
+    buildTx(signer: Address, token: Address, params: DecreaseCarryPositionTxParams, options: DecreaseCarryPositionBuildTxOptions): Promise<LongYieldCarryTransactionPlan>;
+    buildPlan(signer: Address, token: Address, params: DecreaseCarryPositionTxBuilderParams): Promise<DecreaseCarryPositionPlan>;
+}
+
+declare class DepositUnlentCollateralBuilder extends LongYieldCarryBuilderBase<DepositUnlentCollateralIxArgs, DepositUnlentCollateralTxArgs> {
+    getIx(args: DepositUnlentCollateralIxArgs): Promise<Instruction>;
+    getTx(args: DepositUnlentCollateralTxArgs): Promise<LongYieldCarryTransactionPlan>;
+}
+
+declare class IncreaseCarryPositionBuilder extends LongYieldCarryBuilderBase<IncreaseCarryPositionIxArgs, IncreaseCarryPositionTxArgs> {
+    getIx(args: IncreaseCarryPositionIxArgs): Promise<Instruction>;
+    getTx(args: IncreaseCarryPositionTxArgs): Promise<LongYieldCarryTransactionPlan>;
+}
+
+declare class RebalanceTokenBuilder extends LongYieldCarryBuilderBase<RebalanceTokenIxArgs, RebalanceTokenTxArgs> {
+    getIx(args: RebalanceTokenIxArgs): Promise<Instruction>;
+    getTx(args: RebalanceTokenTxArgs): Promise<LongYieldCarryTransactionPlan>;
+    private maxPostRebalanceUtilizationBps;
+    private buildFlashRebalanceOrSkip;
+    private collectFlashCpiGroups;
+}
+
+declare class RebalanceYieldingBankBuilder extends LongYieldCarryBuilderBase<RebalanceYieldingBankIxArgs, RebalanceYieldingBankTxArgs> {
+    getIx(args: RebalanceYieldingBankIxArgs): Promise<Instruction>;
+    getTx(args: RebalanceYieldingBankTxArgs): Promise<LongYieldCarryTransactionPlan>;
+}
+
+declare class RecollateralizeLossBuilder extends LongYieldCarryBuilderBase<RecollateralizeLossIxArgs, RecollateralizeLossTxArgs, LongYieldCarryTransactionPlan[]> {
+    getIx(args: RecollateralizeLossIxArgs): Promise<Instruction>;
+    /**
+     * The active lending position holding the most collateral, or `undefined`
+     * when the token has no active positions. Used only to supply a well-formed
+     * reference account layout when `getIx` is called with an invalid index.
+     */
+    private largestActiveLendingPosition;
+    getTx(args: RecollateralizeLossTxArgs): Promise<LongYieldCarryTransactionPlan[]>;
+    private selectRecollateralizationTarget;
+    private buildRecollateralizationSwapPlan;
+    private buildOptionalDecreaseCarryPhase;
+    private buildRecollateralizePhase;
+}
+
+declare class RefreshTokenStateBuilder extends LongYieldCarrySingleInstructionBuilderService<RefreshTokenStateIxArgs> {
+    getIx(args: RefreshTokenStateIxArgs): Promise<Instruction>;
+    getTx(args: RefreshTokenStateIxArgs): Promise<LongYieldCarryTransactionPlan>;
+    private getRefreshTokenStateParams;
+}
+
+declare class RefreshTokensBuilder {
+    private readonly context;
+    constructor(context: LongYieldCarryBuilderContext);
+    getTx(args: RefreshTokensBuilderTxArgs): Promise<LongYieldCarryTransactionPlan>;
+    private getYieldingBanksToRefresh;
+}
+
+declare class RefreshYieldingBankBuilder extends LongYieldCarryBuilderBase<RefreshYieldingBankIxArgs, RefreshYieldingBankTxArgs> {
+    getIx(args: RefreshYieldingBankIxArgs): Promise<Instruction>;
+    getTx(args: RefreshYieldingBankTxArgs): Promise<LongYieldCarryTransactionPlan>;
+}
+
+declare class ResetTokenBurnRateLimitBuilder extends LongYieldCarrySingleInstructionBuilderService<ResetTokenBurnRateLimitIxArgs> {
+    getIx(args: ResetTokenBurnRateLimitIxArgs): Promise<Instruction>;
+    protected buildLookupTables(args: ResetTokenBurnRateLimitIxArgs): Promise<readonly Address[]>;
+}
+
+declare class SetTokenCircuitBreakerBuilder extends LongYieldCarrySingleInstructionBuilderService<SetTokenCircuitBreakerIxArgs, SetTokenCircuitBreakerTxArgs> {
+    protected deriveIxArgs(txArgs: SetTokenCircuitBreakerTxArgs): Promise<SetTokenCircuitBreakerIxArgs>;
+    getIx(args: SetTokenCircuitBreakerIxArgs): Promise<Instruction>;
+    protected buildLookupTables(args: SetTokenCircuitBreakerIxArgs): Promise<readonly Address[]>;
+    protected buildPlanExtras(args: SetTokenCircuitBreakerIxArgs): Promise<{
+        postSuccessCacheInvalidations: TransactionCacheInvalidation[];
+    }>;
+}
+
+declare class SetYieldingBankCircuitBreakerBuilder extends LongYieldCarrySingleInstructionBuilderService<SetYieldingBankCircuitBreakerIxArgs, SetYieldingBankCircuitBreakerTxArgs> {
+    protected deriveIxArgs(txArgs: SetYieldingBankCircuitBreakerTxArgs): Promise<SetYieldingBankCircuitBreakerIxArgs>;
+    getIx(args: SetYieldingBankCircuitBreakerIxArgs): Promise<Instruction>;
+    protected buildLookupTables(): Promise<readonly Address[]>;
+}
+
+declare class UpdateLendingPositionConfigBuilder extends LongYieldCarrySingleInstructionBuilderService<UpdateLendingPositionConfigIxArgs> {
+    getIx(args: UpdateLendingPositionConfigIxArgs): Promise<Instruction>;
+    protected buildLookupTables(args: UpdateLendingPositionConfigIxArgs): Promise<readonly Address[]>;
+    protected buildPlanExtras(args: UpdateLendingPositionConfigIxArgs): Promise<{
+        postSuccessCacheInvalidations: TransactionCacheInvalidation[];
+    }>;
+}
+
+declare class UpdateTokenConfigurationBuilder extends LongYieldCarrySingleInstructionBuilderService<UpdateTokenConfigurationIxArgs> {
+    /**
+     * Builds an update signed by the token admin by default. Callers may pass the
+     * token manager (`feeDripMaxApyBps` only) or curator (curator fee wallet)
+     * through the compatibility-named `admin` argument.
+     *
+     * Omitted fee/config fields are sent as `null` (on-chain `None` = no change).
+     */
+    getIx(args: UpdateTokenConfigurationIxArgs): Promise<Instruction>;
+    protected buildLookupTables(args: UpdateTokenConfigurationIxArgs): Promise<readonly Address[]>;
+}
+
+declare class UpdateTokenMetadataBuilder extends LongYieldCarrySingleInstructionBuilderService<UpdateTokenMetadataIxArgs> {
+    getIx(args: UpdateTokenMetadataIxArgs): Promise<Instruction>;
+    protected buildLookupTables(args: UpdateTokenMetadataIxArgs): Promise<readonly Address[]>;
+}
+
+declare class UpdateYieldingBankConfigBuilder extends LongYieldCarrySingleInstructionBuilderService<UpdateYieldingBankConfigIxArgs> {
+    getIx(args: UpdateYieldingBankConfigIxArgs): Promise<Instruction>;
+    protected buildLookupTables(): Promise<readonly Address[]>;
+    protected buildPlanExtras(args: UpdateYieldingBankConfigIxArgs): Promise<{
+        postSuccessCacheInvalidations: TransactionCacheInvalidation[];
+    }>;
+}
+
+declare class TransactionClient {
+    readonly context: LongYieldCarryBuilderContext;
+    readonly burnToken: BurnTokenBuilder;
+    readonly claimIncentives: ClaimIncentivesBuilder;
+    readonly collectFees: CollectFeesBuilder;
+    readonly collectInterest: CollectInterestBuilder;
+    readonly creditUnlentToRedemptionEpoch: CreditUnlentToRedemptionEpochBuilder;
+    readonly createCpiPlan: CreateCpiPlanBuilder;
+    readonly createToken: CreateTokenBuilder;
+    readonly createTokenLendingPosition: CreateTokenLendingPositionBuilder;
+    readonly createYieldingBank: CreateYieldingBankBuilder;
+    readonly createYieldingBankAllocation: CreateYieldingBankAllocationBuilder;
+    readonly decreaseCarryPosition: DecreaseCarryPositionBuilder;
+    readonly depositUnlentCollateral: DepositUnlentCollateralBuilder;
+    readonly increaseCarryPosition: IncreaseCarryPositionBuilder;
+    readonly mintToken: MintTokenBuilder;
+    readonly rebalanceToken: RebalanceTokenBuilder;
+    readonly rebalanceYieldingBank: RebalanceYieldingBankBuilder;
+    readonly recollateralizeLoss: RecollateralizeLossBuilder;
+    readonly refreshTokenState: RefreshTokenStateBuilder;
+    readonly refreshTokens: RefreshTokensBuilder;
+    readonly refreshYieldingBank: RefreshYieldingBankBuilder;
+    readonly processAsyncBurn: ProcessAsyncBurnBuilder;
+    readonly resetTokenBurnRateLimit: ResetTokenBurnRateLimitBuilder;
+    readonly setRedemptionEpochStatus: SetRedemptionEpochStatusBuilder;
+    readonly setTokenCircuitBreaker: SetTokenCircuitBreakerBuilder;
+    readonly setYieldingBankCircuitBreaker: SetYieldingBankCircuitBreakerBuilder;
+    readonly updateLendingPositionConfig: UpdateLendingPositionConfigBuilder;
+    readonly updateTokenConfiguration: UpdateTokenConfigurationBuilder;
+    readonly updateTokenMetadata: UpdateTokenMetadataBuilder;
+    readonly updateYieldingBankConfig: UpdateYieldingBankConfigBuilder;
+    readonly topUpUnlentReserves: TopUpUnlentReservesBuilder;
+    constructor(context: LongYieldCarryBuilderContext);
+}
+type TransactionBuilder = TransactionClient[keyof TransactionClient];
+type CompositeTransactionPlan = TransactionPlan | LongYieldCarryTransactionPlan;
+
+/**
+ * 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 } });
+ */
+
+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. */
+type OutstandingIncentivesByPosition = Map<number, OutstandingIncentive[]>;
+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>;
+}
+
+/**
+ * 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.
+ */
+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.
+ */
+declare function buildCollectInterestPlan(account: AccountClient, token: Address, params: CollectInterestPlanParams): Promise<CollectInterestPlan>;
+
+/**
+ * Build the execution plan for `decrease_carry_position`.
+ *
+ * LYC-specific concerns (permissionless operation handling, steering-based target
+ * resolution) live here. Sizing, repay CPI construction, and swap assembly are
+ * delegated to the generic {@link LeverageService} from `lending-platforms`.
+ */
+declare function buildDecreaseCarryPositionPlan(account: AccountClient, swap: SwapClient, signer: Address, token: Address, params: DecreaseCarryPositionBuilderParams): Promise<DecreaseCarryPositionPlan>;
+
+/** LYC program error when on-chain utilization guards block a carry update. */
+declare const INVALID_UTILIZATION_RATE_CONDITION_CODE = 8020;
+/**
+ * Thrown when a tx builder receives inputs that make the operation a no-op
+ * (e.g. zero borrow amount, no yield to collect). Callers can catch this
+ * to distinguish "nothing to do" from genuine failures.
+ */
+declare class NoOpTransactionError extends Error {
+    constructor(message: string);
+}
+/**
+ * Thrown when `collect_interest` has nothing meaningful to redeem or swap
+ * (no net carry yield, no matching carry slot, redeem rounds to zero, etc.).
+ *
+ * Extends {@link NoOpTransactionError} so batch jobs that skip no-ops via
+ * `instanceof NoOpTransactionError` continue to treat this as a skip.
+ */
+declare class NoInterestToCollectError extends NoOpTransactionError {
+    constructor(message: string);
+}
+/**
+ * Thrown when an initial lending position cannot be created because of a
+ * permanent configuration gap rather than a transient failure — e.g. the
+ * collateral mint is not listed in any lending pool, has no carry preset, or
+ * has no viable debt mint / reserve.
+ *
+ * Callers running on a tight schedule (e.g. the unlent-buffer worker) should
+ * catch this to **skip** the token instead of failing the task, which would
+ * otherwise retry every cycle and churn the DLQ until the config is fixed.
+ */
+declare class LendingPositionBootstrapError extends Error {
+    constructor(message: string);
+}
+/**
+ * Looks up an Anchor custom error code against the LYC program IDL.
+ * Returns the error name and message if found, or `undefined` for codes
+ * belonging to other programs (e.g. Kamino, SPL Token).
+ */
+declare function lookupLycError(code: number): {
+    name: string;
+    msg: string;
+} | undefined;
+/**
+ * Parses a logged Anchor error from a simulation failure message or program log line.
+ */
+declare function parseLoggedLycAnchorError(text: string): {
+    name: string;
+    code: number;
+    msg: string;
+} | undefined;
+/**
+ * Extracts an LYC program error code from a failed transaction, when present.
+ */
+declare function extractLycErrorCode(err: unknown): number | undefined;
+/** True when a failed tx was rejected by an expected LYC guard (not an incident). */
+declare function isSkippableLycTransactionError(err: unknown): boolean;
+/**
+ * Attempts to parse a Solana `InstructionError` from a transaction simulation
+ * failure message and returns a human-readable string.
+ *
+ * Handles formats like:
+ * - `Transaction simulation failed: {"InstructionError":["0",{"Custom":"6121"}]}`
+ * - `Transaction simulation failed: {"InstructionError":["1","ProgramFailedToComplete"]}`
+ *
+ * If the error contains a `Custom` code in the LYC IDL range, it's decoded to
+ * the program error name and message. Otherwise, the raw code or variant is
+ * included with a note that it may be from a CPI target program.
+ */
+declare function formatTransactionError(errMessage: string): string;
+
+declare const usdStarAllocationConfig: YieldingBankAllocationConfig;
+declare const usdStarJuniorAllocationConfig: YieldingBankAllocationConfig;
+
+/** Maximum value for `targetUtilizationRateBps` (100% in basis points). */
+declare const MAX_TARGET_UTILIZATION_RATE_BPS = 10000;
+/**
+ * Maximum allowed value of `targetUtilizationRateBps + maxDeviationAboveTargetUtilBps`.
+ * Mirrors `MAX_LENDING_POSITION_UPPER_UTIL_BPS` in the on-chain program.
+ */
+declare const MAX_LENDING_POSITION_UPPER_UTIL_BPS = 10500;
+/**
+ * Floor for `maxDeviationAboveTargetUtilBps` in preset-based computation.
+ *
+ * When the raw target is high enough that the unwind-trigger gap would be
+ * smaller than this, `computeCarryLendingAllocationConfig` pulls the target
+ * down so the above-deviation is at least this wide. This prevents
+ * near-zero unwind bands that would trigger constant rebalances.
+ */
+declare const MIN_DEVIATION_ABOVE_TARGET_UTIL_BPS = 200;
+/**
+ * On-chain lending position tuning (see `LendingPositionConfig` in `long_yield_carry`).
+ */
+type CarryLendingAllocationConfig = {
+    targetUtilizationRateBps: number;
+    maxDeviationAboveTargetUtilBps: number;
+    maxDeviationBelowTargetUtilBps: number;
+};
+type ComputeCarryLendingAllocationConfigParams = {
+    /**
+     * Collateral drawdown buffer between the **target** utilization and liquidation (positive percent,
+     * e.g. `25` for 25%). At target utilization, a collateral drop of this size reaches the liquidation
+     * line: `target = (1 − drawdownPctFromTargetToLiq/100) × liquidationThreshold / maxLtv`.
+     *
+     * Must be greater than `drawdownPctFromUnwindToLiq` (the target sits further from liquidation than
+     * the unwind trigger).
+     */
+    drawdownPctFromTargetToLiq: number;
+    /**
+     * Collateral drawdown buffer between the **unwind trigger** and liquidation (positive percent,
+     * e.g. `10` for 10%). At the unwind trigger (`target + maxDeviationAbove`), a collateral drop of
+     * this size reaches the liquidation line:
+     * `unwindTrigger = (1 − drawdownPctFromUnwindToLiq/100) × liquidationThreshold / maxLtv`.
+     *
+     * Must be less than `drawdownPctFromTargetToLiq`.
+     */
+    drawdownPctFromUnwindToLiq: number;
+    /**
+     * Max collateral **appreciation** (positive percent, e.g. `25` for +25%). If you start exactly at
+     * target utilization and collateral rallies this much (debt USD fixed), utilization reaches the
+     * **boost** trigger: `target − maxDeviationBelow`.
+     */
+    maxPriceChangeUpPercent: number;
+    /** Effective max LTV for the pair (decimal `0.8` = 80%), e.g. `ReservesManager.maxLtv`. */
+    maxLtv: number;
+    /** Collateral liquidation threshold (decimal `0.85` = 85%), from reserve config. */
+    liquidationThreshold: number;
+};
+/** The price-band params without pair-specific LTV / liquidation fields. */
+type CarryPriceBandPreset = Omit<ComputeCarryLendingAllocationConfigParams, "maxLtv" | "liquidationThreshold">;
+/**
+ * Clamps a lending position config so it satisfies the on-chain constraints in
+ * `require_valid_lending_position_config_bps`:
+ *
+ * - `targetUtilizationRateBps` is clamped to `[1, MAX_TARGET_UTILIZATION_RATE_BPS]`
+ * - `maxDeviationAboveTargetUtilBps` is clamped so `target + above ≤ MAX_LENDING_POSITION_UPPER_UTIL_BPS`
+ *
+ * Throws only for inputs that indicate a bug (non-integer, negative deviation, target ≤ maxDevBelow).
+ */
+declare function clampLendingPositionConfigBps(config: CarryLendingAllocationConfig): CarryLendingAllocationConfig;
+/**
+ * Builds `targetUtilizationRateBps` and deviation bands from drawdown-to-liquidation buffers.
+ *
+ * **Model:** debt USD fixed; only collateral USD moves. Both the target and the unwind trigger are
+ * defined by how much collateral drawdown separates them from the liquidation line
+ * (`liquidationThreshold / maxLtv`). The boost trigger (below target) is set by a rally percentage.
+ *
+ * `maxDeviationAbove = unwindTriggerBps − targetBps` (derived, not from a price-change input).
+ */
+declare function computeCarryLendingAllocationConfig(params: ComputeCarryLendingAllocationConfigParams): CarryLendingAllocationConfig;
+interface ComputeConfigForCollateralArgs {
+    /** Collateral mint address — used to look up the symbol from the mint registry. */
+    collateralMint: Address;
+    /** Collateral reserve — used to read `liquidationThresholdPct`. */
+    collateralReserve: ReserveBase;
+    /** Debt reserve — paired with collateral to determine `maxLtv` (including e-mode). */
+    debtReserve: ReserveBase;
+    /**
+     * Override the volatility regime. When omitted, uses the asset's
+     * `defaultRegime` from `ASSET_PRESETS`.
+     */
+    regime?: VolatilityRegime;
+}
+/**
+ * Resolves the carry trade price-band preset for a collateral mint and
+ * computes the lending position config (target utilization + deviation bands)
+ * using the reserve pair's `maxLtv` and `liquidationThreshold`.
+ *
+ * Uses {@link ReservesManager} to derive `maxLtv` (including e-mode overrides)
+ * and normalizes `liquidationThresholdPct` to a decimal.
+ *
+ * Throws if the collateral mint symbol is not in `ASSET_PRESETS`.
+ */
+declare function computeConfigForCollateral(args: ComputeConfigForCollateralArgs): CarryLendingAllocationConfig;
+
+/**
+ * Per-asset carry trade price-band presets, split by volatility regime.
+ *
+ * Each preset defines three drawdown / rally buffers that control how aggressively a
+ * lending position is utilized relative to its liquidation line:
+ *
+ * - `drawdownPctFromTargetToLiq` — collateral drawdown (%) that separates the **target**
+ *    utilization from the liquidation line. Larger = more conservative target.
+ * - `drawdownPctFromUnwindToLiq` — collateral drawdown (%) that separates the **unwind
+ *    trigger** from the liquidation line. Smaller than target (closer to liquidation).
+ * - `maxPriceChangeUpPercent` — max collateral **rally** (%) before the boost trigger fires,
+ *    prompting the position to borrow more and return to target.
+ *
+ * ## Usage
+ *
+ * Select the appropriate asset preset and volatility regime, then pass it to
+ * `LycLendingPositionManager.getLendingAllocationConfigFromPriceBands(preset)`, which combines
+ * the price-band params with pair-specific `maxLtv` and `liquidationThreshold` to produce
+ * a `CarryLendingAllocationConfig` (target utilization + deviation bands in bps). The
+ * resulting config is used to update the on-chain `LendingPositionConfig`, adapting the
+ * position's risk envelope to the current market regime.
+ *
+ * ## Asset tiers (tightest → widest buffers)
+ *
+ * BTC → ETH → SOL → large-cap alts → small-cap alts
+ *
+ * Higher-volatility assets use wider buffers to avoid unnecessary unwinds during normal
+ * price swings, while lower-volatility assets can afford tighter bands for better capital
+ * efficiency.
+ */
+
+declare const VOLATILITY_REGIMES: readonly ["lowVol", "highVol"];
+type VolatilityRegime = (typeof VOLATILITY_REGIMES)[number];
+declare function isVolatilityRegime(s: string): s is VolatilityRegime;
+type CarryVolatilityPresets = {
+    lowVol: CarryPriceBandPreset;
+    highVol: CarryPriceBandPreset;
+};
+interface AssetPresetEntry {
+    presets: CarryVolatilityPresets;
+    defaultRegime: VolatilityRegime;
+}
+declare const STOCK_INDEX_PRESETS: CarryVolatilityPresets;
+declare const BTC_CARRY_PRESETS: CarryVolatilityPresets;
+declare const ETH_CARRY_PRESETS: CarryVolatilityPresets;
+declare const SOL_CARRY_PRESETS: CarryVolatilityPresets;
+declare const LST_CARRY_PRESETS: CarryVolatilityPresets;
+declare const LARGE_CAP_ALT_CARRY_PRESETS: CarryVolatilityPresets;
+declare const SMALL_CAP_ALT_CARRY_PRESETS: CarryVolatilityPresets;
+/**
+ * Maps collateral symbol (upper-cased) to its carry trade preset tier and
+ * default volatility regime. Used by scripts and backend services to resolve
+ * the correct price-band parameters when creating or reconfiguring lending
+ * positions.
+ */
+declare const ASSET_PRESETS: Record<string, AssetPresetEntry>;
+/** Looks up the carry preset entry for a collateral symbol (case-insensitive). */
+declare function resolvePresets(collateralSymbol: string): AssetPresetEntry | undefined;
+
+interface DebtAllocationTarget {
+    mint: Address;
+    amountUi: number;
+    /** Proportion of total debt allocated here, in basis points (0–10000) */
+    weightBps: number;
+}
+interface DebtReallocation {
+    token: Address;
+    lendingPositionIndex: number;
+    currentDebtMint: Address;
+    currentDebtAmountUi: number;
+    currentBorrowApy: number;
+    /** Supply APY that the collateral earns as a pair incentive from the current debt token. */
+    currentSupplyIncentiveApy: number;
+    projectedBorrowApy: number;
+    targets: DebtAllocationTarget[];
+    /**
+     * Ordered list of single-mint fallback options to try if the primary targets
+     * fail at execution time (e.g. insufficient borrow capacity or swap liquidity).
+     * Each entry is a full-position allocation to a single mint, ranked by
+     * effective borrow APY ascending.
+     */
+    fallbackTargets: DebtAllocationTarget[][];
+}
+
+interface AllocationServiceOptions {
+    /**
+     * Receives diagnostic log messages. When omitted, the service is silent
+     * (used by unit tests). Pass `console.log` from scripts to inspect per-pool
+     * candidate evaluation, incentive eligibility, and the chosen allocation.
+     */
+    logger?: (message: string) => void;
+    /**
+     * Yielding-bank state used to identify tokens whose active bank holds USD*.
+     * Without this data, allocation remains unbiased.
+     */
+    yieldingBanks?: readonly LYCYieldingBank[];
+}
+declare class AllocationService {
+    private readonly lpData;
+    private readonly log;
+    private readonly yieldingBanks;
+    constructor(lpData: LendingPlatformData, options?: AllocationServiceOptions);
+    /**
+     * Returns the debt mint with the highest pair-adjusted net APY
+     * (supplyAPY − borrowAPY) for a given pool and collateral reserve.
+     *
+     * Use this when creating a new lending position to pick the optimal debt
+     * mint rather than hardcoding a default.
+     */
+    findOptimalDebtMint(pool: Address, collateralReserve: ReserveBase, token?: LYCToken): Promise<{
+        mint: Address;
+        symbol: string;
+        borrowApy: number;
+    } | null>;
+    /**
+     * Groups all active lending positions by pool, then for each position in a
+     * pool finds the allocation across supported borrow mints that minimises
+     * that position's pair-adjusted borrow cost. Positions are optimised
+     * independently — pair-incentive eligibility is keyed on the position's
+     * (debt, collateral) pair, so positions with different collaterals can have
+     * different optimal debt mints. (Utilization coupling between positions on
+     * the same reserve is not modelled; pair-incentive deltas dominate marginal
+     * utilization deltas at typical position sizes.)
+     *
+     * Returns one entry per position whose allocation would change.
+     */
+    computeOptimalAllocations(tokens: LYCToken[]): Promise<DebtReallocation[]>;
+    private resolveAllPositions;
+    private resolvePosition;
+    private tokenUsesUsdStarYieldingBank;
+    private applyUsdcBias;
+    private groupByPool;
+    private processPoolGroup;
+    /**
+     * Optimises a single position against the candidate set, logs the result,
+     * applies the minimum-improvement gate, and returns a reallocation if one
+     * should be emitted. Returns `null` when the position is already optimal,
+     * the optimum doesn't beat current, or the gain is below threshold.
+     *
+     */
+    private evaluatePosition;
+    /**
+     * Logs, in this order:
+     * 1. Each collateral reserve in the pool group + its incentives (once).
+     * 2. Each candidate debt reserve: base borrow APY, utilization, and its
+     *    borrow-side incentives (once).
+     * 3. A net-APY matrix (candidate rows × collateral columns) showing the
+     *    pair-adjusted supply APY, borrow APY, and net APY = supply − borrow.
+     *    The matrix answers "should I borrow USDS or USDG against cbBTC?" at a
+     *    glance — compare rows within the cbBTC column.
+     *
+     * The matrix uses `supplyAPY(debtReserve)` and `borrowAPY(supplyReserve)`,
+     * which include pair-gated incentives. A `★` marks rows where a pair
+     * incentive activates (supplyApy or borrowApy differs from the base).
+     */
+    private logCandidates;
+    private logBorrowRateMatrix;
+    private aggregateExistingDebtByMint;
+    private resolveGroupCandidates;
+    private fetchOptionalReserveByMint;
+    /**
+     * Finds the allocation of `pos.debtAmountUi` across `candidates` that
+     * MAXIMISES this position's pair-adjusted net APY (supplyApy − borrowApy)
+     * using DP over a discrete grid of size K = ALLOCATION_STEPS.
+     *
+     * Both legs are pair-adjusted with this position's own collateral reserve,
+     * since incentive eligibility is keyed on the (debt, collateral) pair. This
+     * matters because some pair incentives (e.g. USDG★cbBTC) act on the supply
+     * side — minimising borrow cost alone would miss them.
+     *
+     * For candidate `i` at step `n`:
+     *   target      = n × stepSize
+     *   posExisting = pos.debtAmountUi if pos.debtMint == candidate.mint else 0
+     *   debtChange  = target − posExisting
+     *   borrowApy   = simulateNewBorrowAPY({debtChange}, pos.collateralReserve)
+     *   supplyApy   = pos.collateralReserve.supplyAPY(reserve.address)
+     *
+     * The DP minimises Σ target × (borrowApy − supplyApy) — equivalent to
+     * maximising debt-weighted net APY. Utilization coupling with sibling
+     * positions is not modelled; the simulator only sees this position's
+     * marginal change.
+     */
+    private optimizePosition;
+    private runDp;
+}
+
+/**
+ * LYC-flavoured {@link LendingPositionManager}: adds carry-specific sizing
+ * signals ({@link shouldIncreaseCarryPosition}, {@link shouldDecreaseCarryPosition})
+ * and defaults utilization targets from the on-chain `LendingPositionConfig`.
+ */
+declare class LycLendingPositionManager extends LendingPositionManager {
+    readonly lendingPosition: TokenLendingPositionData;
+    constructor(lpData: LendingPlatformData, lendingPosition: TokenLendingPositionData, collateralReserve: ReserveBase, debtReserve: ReserveBase, environment?: Environment);
+    static create(lpData: LendingPlatformData, lendingPosition: TokenLendingPositionData, environment?: Environment): Promise<LycLendingPositionManager>;
+    /**
+     * Derives `targetUtilizationRateBps` and carry trigger deviations from drawdown-to-liquidation
+     * buffers and a rally percentage, using this pair's {@link ReservesManager.maxLtv} and the
+     * collateral reserve's **base** `liquidationThresholdPct` (normalized to a decimal).
+     *
+     * For custom `maxLtv` / `liquidationThreshold` (e.g. e-mode liquidation threshold), call
+     * {@link computeCarryLendingAllocationConfig} directly.
+     */
+    getLendingAllocationConfigFromPriceBands(params: CarryPriceBandPreset): CarryLendingAllocationConfig;
+    /**
+     * Returns true when the current LTV utilization (valued at EMA prices) has
+     * fallen far enough below the target that the position should be boosted.
+     */
+    shouldIncreaseCarryPosition(): Promise<boolean>;
+    /**
+     * Returns true when the current LTV utilization (valued at realtime prices) has
+     * risen far enough above the target that the position should be unwound.
+     */
+    shouldDecreaseCarryPosition(): Promise<boolean>;
+    calcDebtChangeAmount(targetUtilizationRateBps?: number): Promise<number>;
+    calcPreWithdrawalTargetUtilizationRateBps(withdrawUiCollateralAmount: number, postWithdrawalTargetUtilizationRateBps?: number): Promise<number>;
+    calcDebtChangeAmountForCollateralWithdrawal(withdrawUiCollateralAmount: number, postWithdrawalTargetUtilizationRateBps?: number): Promise<number>;
+    getCollateralPriceTriggerBand(): Promise<CollateralPriceTriggerBand>;
+    getInspectMetrics(): Promise<LendingPositionInspectMetrics | null>;
+    private configTriggerBandBps;
+}
+
+/** A lending position paired with the amount to deposit into it, in raw base units. */
+interface EvenDepositAllocation {
+    lp: IndexedLendingPosition;
+    depositRaw: bigint;
+}
+/**
+ * Distributes `totalDepositRaw` across `positions` so their post-deposit
+ * collateral balances end up as even as possible. Deposits only — a position
+ * that is already above the resulting water level is left untouched (we never
+ * withdraw to level down).
+ *
+ * Water-filling: the lowest-collateral positions are topped up first until they
+ * reach the next tier, then the remainder is spread evenly across the leveled
+ * front. Base-unit remainders from integer division go to the lowest-collateral
+ * positions first, so the returned deposits sum exactly to `totalDepositRaw`.
+ *
+ * Only positions receiving a positive deposit are returned; each keeps its
+ * original `index` for the on-chain `lendingPositions[index]` reference.
+ */
+declare function computeEvenDepositAllocation(positions: IndexedLendingPosition[], totalDepositRaw: bigint): EvenDepositAllocation[];
+type LogFn$1 = (msg: string) => void;
+interface EnsureInitialKaminoLendingPositionOptions {
+    manager: TransactionSigner;
+    /** When set, refreshes the per-token LUT after the new LP is created. */
+    lutManager?: TransactionSigner;
+    token: LYCToken;
+    sendPlan: (plan: LongYieldCarryTransactionPlan, label: string) => Promise<void>;
+    log?: LogFn$1;
+}
+/**
+ * Shared logic for interacting with a token's lending positions: bootstrapping
+ * the first position, and depositing unlent collateral across positions. Used
+ * by deposit scripts and backend services.
+ */
+declare class LendingPositionService {
+    private readonly client;
+    constructor(client: LongYieldCarryClient);
+    /**
+     * Opens the first Kamino lending position on a token that has none yet.
+     *
+     * Mirrors `scripts/createTokenLendingPosition.ts` and the create-LP branch in
+     * `TokenRebalanceWorker`: resolve pool + optimal debt mint, compute carry
+     * allocation config, send `createTokenLendingPosition`, then refetch the token.
+     *
+     * Kamino-specific: the flow resolves the default Kamino pool, fetches Kamino
+     * reserves, and uses {@link AllocationService} over Kamino reserve data. It is
+     * named accordingly until a second lending platform actually needs bootstrap
+     * support (avoid speculative platform abstraction with a single implementation).
+     *
+     * No-op when the token already has at least one active lending position slot.
+     *
+     * @throws {LendingPositionBootstrapError} when the token cannot be bootstrapped
+     *   because of a permanent configuration gap (collateral mint not in any pool,
+     *   no preset, no viable debt mint / reserve). Callers should treat this as a
+     *   skip rather than a retryable failure.
+     */
+    ensureInitialKaminoLendingPosition(options: EnsureInitialKaminoLendingPositionOptions): Promise<LYCToken>;
+    /**
+     * Deposits all unlent collateral across the token's active lending positions,
+     * distributing it so their post-deposit collateral balances end up as even as
+     * possible (see {@link computeEvenDepositAllocation}).
+     *
+     * Refreshes the token state first, then sends one `depositUnlentCollateral`
+     * per position that receives an allocation. Returns one entry per deposit sent.
+     */
+    depositEvenlyAcrossPositions(signer: TransactionSigner, token: LYCToken, log?: LogFn$1): Promise<{
+        signature: string;
+        lendingPositionIndex: number;
+        depositUi: number;
+        debtSymbol: string;
+    }[]>;
+}
+
+type RebalancePlanResult = {
+    outcome: "skipped";
+    reason: string;
+} | {
+    outcome: "plan";
+    plan: LongYieldCarryTransactionPlan;
+    label: string;
+};
+/**
+ * Shared logic for building a token rebalance plan from a {@link DebtReallocation}.
+ * Callers are responsible for sending the returned plan (and any post-send steps such as
+ * excess-rent reclaim).
+ */
+interface TokenRebalanceServiceOptions {
+    /**
+     * Maximum acceptable execution cost (route fees + price impact) of the
+     * rebalance swap quote vs the oracle-fair cross rate, in bps. Candidates
+     * quoting worse are skipped — that cost is permanently lost value.
+     * Unset = no limit.
+     */
+    maxSwapCostBps?: number;
+    /**
+     * Maximum acceptable market basis between the two debt stables, in bps
+     * either direction. Bounds how much mark-to-market difference the $1-pinned
+     * books absorb per conversion, and blocks rebalancing through a depegging
+     * stable. Unset = no limit.
+     */
+    maxMarketBasisBps?: number;
+}
+declare class TokenRebalanceService {
+    private readonly client;
+    private readonly options;
+    constructor(client: LongYieldCarryClient, options?: TokenRebalanceServiceOptions);
+    /**
+     * Validates a reallocation and builds the rebalance transaction plan.
+     * If the primary targets fail due to insufficient borrow/swap capacity
+     * ({@link ExactInQuoteExceedsMaxInputError}), retries with each fallback
+     * option in order before giving up.
+     *
+     * Returns `{ outcome: "skipped" }` for benign no-ops (inactive token, no active LP for the
+     * reallocation index, no targets). Throws on unexpected errors from the builder.
+     */
+    buildPlan(token: LYCToken, realloc: DebtReallocation): Promise<RebalancePlanResult>;
+    /** Convenience: fetch a fresh token then call {@link buildPlan}. */
+    fetchAndBuildPlan(tokenAddress: Address, realloc: DebtReallocation): Promise<RebalancePlanResult>;
+}
+
+/**
+ * A single allocation target: a mint and its desired weight in basis points.
+ * Weights across all targets in a {@link TargetAllocation} must sum to 10_000.
+ */
+interface AllocationTarget {
+    mint: Address;
+    weightBps: number;
+    /** Slippage tolerance for swaps into/out of this asset (basis points). */
+    slippageBps: number;
+    /**
+     * Allocation config needed to register this asset on the yielding bank
+     * if it doesn't already have a holding slot. Required for first-time
+     * allocations; ignored when the bank already holds the asset.
+     */
+    allocationConfig: YieldingBankAllocationConfig;
+}
+/**
+ * The full target allocation for a yielding bank's non-base assets.
+ * Each entry describes one asset and its desired weight.
+ * Weights must sum to exactly 10_000 (100%).
+ */
+type TargetAllocation = AllocationTarget[];
+/**
+ * The output of {@link RebalancePlanner.plan}: swaps to execute and any
+ * new asset holdings to create before the rebalance instruction fires.
+ */
+interface YieldingBankRebalancePlan {
+    /** Swaps to execute (base → asset or asset → base). */
+    swaps: RebalanceSwapSpec[];
+    /**
+     * If a target allocation references a mint the bank has never held,
+     * the allocation must be registered first. This contains the config
+     * for that one-time setup. At most one new allocation per rebalance.
+     */
+    newAllocation?: {
+        config: YieldingBankAllocationConfig;
+    };
+}
+
+/**
+ * Decides the target allocation for a yielding bank's non-base assets.
+ *
+ * Implementations receive the current bank state and return the desired
+ * distribution across yield-bearing assets. The {@link RebalancePlanner}
+ * then computes the delta (swaps) needed to reach that target.
+ *
+ * Strategies should be pure functions of the bank state (and any external
+ * data injected through the constructor). They must not perform RPC calls
+ * or side effects.
+ */
+interface AllocationStrategy {
+    computeTarget(bank: LYCYieldingBank): TargetAllocation;
+}
+/**
+ * Default strategy: deploy 100% of idle base asset into USD*.
+ *
+ * This is the simplest possible allocation — all non-base value goes to
+ * a single Perena stablecoin. Replace with a multi-asset strategy when
+ * additional yield-bearing positions (e.g. USD*-J) are introduced.
+ */
+declare class SimpleUsdStarStrategy implements AllocationStrategy {
+    computeTarget(_bank: LYCYieldingBank): TargetAllocation;
+}
+
+/**
+ * Computes the swaps needed to move a yielding bank from its current
+ * asset distribution to a target allocation.
+ *
+ * The planner is stateless and performs no RPC — it operates entirely on
+ * the in-memory bank model and the strategy's target. This makes it
+ * straightforward to unit-test.
+ *
+ * ## How it works
+ *
+ * 1. The {@link AllocationStrategy} produces a {@link TargetAllocation}
+ *    (e.g. 25% USD*, 75% USD*-J).
+ * 2. The planner classifies every bank holding as either a **target**
+ *    (a mint the strategy manages) or an **idle source** (everything
+ *    else — the base asset, plus any non-target stablecoins that
+ *    arrived from borrows in other denominations).
+ * 3. Each idle source with a non-trivial balance gets its own
+ *    {@link YieldingBankRebalancePlan} that deploys its capital
+ *    proportionally across the targets according to their weights.
+ * 4. If existing target holdings are imbalanced relative to their
+ *    weights (overweight / underweight), a separate rebalance plan
+ *    routes through the base mint. The resulting swaps are sorted
+ *    sells-first so freed base-mint liquidity is available for
+ *    subsequent buy swaps.
+ *
+ * All swaps route through the bank's base mint as the common
+ * intermediate, matching how the on-chain `rebalance_yielding_bank`
+ * instruction processes CPI swaps.
+ */
+declare class RebalancePlanner {
+    private readonly strategy;
+    constructor(strategy: AllocationStrategy);
+    /**
+     * Plan the rebalance for a single yielding bank.
+     * Returns an empty array if no action is needed.
+     *
+     * Each element is an independent plan that can be sent as its own
+     * transaction. Separate plans are produced for:
+     * - Each idle source (base asset, or non-target stablecoins)
+     * - Target-to-target rebalancing (selling overweight, buying underweight)
+     */
+    plan(bank: LYCYieldingBank): YieldingBankRebalancePlan[];
+    /**
+     * Returns every holding on the bank that is NOT a strategy target.
+     * This includes the base asset and any non-target asset slots with
+     * a positive balance (e.g. a stablecoin that arrived from a
+     * non-base-mint borrow).
+     */
+    private discoverIdleSources;
+    /** Snapshot only the holdings that ARE strategy targets. */
+    private snapshotTargetHoldings;
+    /**
+     * Build a plan that deploys a single idle source proportionally
+     * across the strategy's targets according to their weights.
+     */
+    private buildDeploymentPlan;
+    /**
+     * Build a plan that rebalances between existing target holdings when
+     * they've drifted from the strategy's desired weights. Overweight
+     * targets are sold back to the base mint; underweight targets are
+     * bought with the freed base.
+     */
+    private buildTargetRebalancePlan;
+    private findCurrentAmount;
+}
+
+interface RedemptionServiceOptions {
+    /** Swap slippage tolerance for DCP transactions, in bps. Defaults to 100. */
+    dcpSwapSlippageBps?: number;
+    /** Optional structured sink for warnings (funding CPI failures, partial funding). */
+    structuredLog?: (entry: StructuredRedemptionLog) => void;
+}
+/** Single LP-targeted funding failure captured during epoch funding. */
+interface RedemptionFundingFailure {
+    lpIndex: number;
+    message: string;
+}
+/** Aggregated non-fatal failures while funding an epoch (DCP vs withdraw phases). */
+interface RedemptionFundingErrors {
+    dcp: RedemptionFundingFailure[];
+    withdraw: RedemptionFundingFailure[];
+}
+interface StructuredRedemptionLog {
+    level: "warn" | "info";
+    event: string;
+    data?: Record<string, unknown>;
+}
+interface FundRedemptionEpochResult {
+    funded: boolean;
+    fundedCollateral: bigint;
+    grossCollateralClaim: bigint;
+    realizedUnwindLoss: bigint;
+    errors: RedemptionFundingErrors;
+}
+interface ProcessEpochResult {
+    requestsProcessed: number;
+}
+type LogFn = (msg: string) => void;
+/**
+ * Orchestrates the redemption epoch lifecycle: detecting open epochs, waiting
+ * for their time window to elapse, funding (DCP + top-up), and processing
+ * individual async burn requests.
+ *
+ * Holds a reference to the LYC client and caches yielding-bank PDAs per token
+ * so repeated calls against the same token avoid redundant derivation.
+ */
+declare class RedemptionService {
+    private readonly client;
+    private readonly yieldingBankCache;
+    private readonly dcpSwapSlippageBps;
+    private readonly structuredLog?;
+    constructor(client: LongYieldCarryClient, opts?: RedemptionServiceOptions);
+    /** Delegates to `client.account.fetchAllRedemptionEpochs`. */
+    getAllEpochs(): Promise<RedemptionEpochSnapshot[]>;
+    /** Delegates to `client.account.fetchRedemptionEpoch`. */
+    getEpoch(epochPda: Address): Promise<RedemptionEpochSnapshot>;
+    /** Re-fetches an existing snapshot from on-chain state. */
+    refreshEpoch(epoch: RedemptionEpochSnapshot): Promise<RedemptionEpochSnapshot>;
+    /**
+     * Returns the number of milliseconds until the epoch's acceptance window
+     * closes. Zero or negative means the window has already elapsed.
+     */
+    epochWindowRemainingMs(epoch: RedemptionEpochSnapshot): number;
+    /**
+     * Sleeps until the epoch's 60-second acceptance window has elapsed. Returns
+     * immediately if the window is already closed.
+     */
+    waitForEpochWindow(epoch: RedemptionEpochSnapshot, log?: LogFn): Promise<void>;
+    /**
+     * Transitions an epoch from Open → Funding. Waits for the epoch window to
+     * close first so in-flight burns can still land.
+     */
+    closeEpoch(signer: TransactionSigner, epoch: RedemptionEpochSnapshot, log?: LogFn): Promise<void>;
+    /** Transitions an epoch from Funding → Processing. */
+    startProcessing(signer: TransactionSigner, epoch: RedemptionEpochSnapshot, log?: LogFn): Promise<void>;
+    /**
+     * Funds a redemption epoch. Withdraws from debt-free LPs first (no DCP
+     * needed), then — if a deficit remains — runs targeted DCP + withdraw on
+     * carry-loaded LPs, prioritizing non-optimal positions.
+     */
+    fundEpoch(signer: TransactionSigner, epoch: RedemptionEpochSnapshot, log?: LogFn): Promise<FundRedemptionEpochResult>;
+    /**
+     * Processes all remaining async burn requests in a redemption epoch in FIFO
+     * order.
+     */
+    processRequests(signer: TransactionSigner, epoch: RedemptionEpochSnapshot, log?: LogFn): Promise<ProcessEpochResult>;
+    /**
+     * Runs the complete epoch lifecycle: close → fund → transition to
+     * processing → process all requests.
+     *
+     * Returns true if the epoch was fully processed and closed.
+     */
+    processEpoch(signer: TransactionSigner, epoch: RedemptionEpochSnapshot, log?: LogFn): Promise<boolean>;
+    clearYieldingBankCache(): void;
+    /**
+     * Credits only the residual shortfall from collateral already sitting in the
+     * token PDA's unlent reserve. LP withdrawals run first so existing reserves
+     * are used as the tail of mixed LP/unlent funding, not the first source.
+     */
+    private creditResidualUnlent;
+    /** Phase 1: withdraw directly from LPs that have no debt (no DCP needed). */
+    private fundFromDebtFreeLps;
+    /**
+     * Phase 2: DCP + withdraw from carry-loaded LPs, processed in position order
+     * (first slot to last) so burns unwind positions deterministically.
+     */
+    private fundFromCarryLps;
+    /**
+     * Runs a targeted DCP on each LP that needs collateral freed. Iterates `lps`
+     * in the caller-provided order (on-chain slot order, first to last).
+     */
+    private dcpAcrossLps;
+    /**
+     * Max collateral (native units) withdrawable from an LP without a prior DCP.
+     *
+     * TopUpUnlentReserves re-checks `is_utilization_rate_at_or_below_target`
+     * AFTER the withdrawal (util <= target + target * threshold / 10_000), and
+     * utilization scales as `util_after = util * collateral / (collateral - w)`
+     * when debt and prices stay constant (mirrors on-chain
+     * `simulate_utilization_rate_bps_after_collateral_withdraw`). Inverting
+     * against the upper bound gives:
+     *   w_max = collateral * (limit - util) / limit
+     */
+    private maxDirectWithdrawal;
+    /**
+     * Executes a single DCP on one lending position with retry logic. Uses full
+     * unwind (target utilization 0) when the deficit exceeds the LP's collateral,
+     * otherwise uses `collateralWithdrawal` steering.
+     */
+    private dcpSingleLp;
+    /**
+     * Withdraws collateral from lending positions into unlent reserves, crediting
+     * the redemption epoch. Stops as soon as the epoch is fully funded.
+     */
+    private withdrawFromLps;
+    private isFullyFunded;
+    private deficitUi;
+    private fundResult;
+    private resolveYieldingBanks;
+}
+
+/** Skip dust Kamino slots when a material position exists on the same token. */
+declare const MIN_MATERIAL_KAMINO_COLLATERAL_USD = 1;
+interface LendingPositionInspectMetricSnapshot {
+    utilizationRealtimeBps: number;
+    utilizationEmaBps: number;
+    lowerTriggerPriceChangePct?: number;
+    upperTriggerPriceChangePct?: number;
+}
+interface YieldingBankExternalPositionMetricSnapshot {
+    platform: LendingPlatform;
+    pool: Address;
+    tvlUsdRaw: string;
+    tvlUsd: number;
+}
+type ProtocolMetricEntityType = "token" | "yielding_bank" | "yielding_bank_asset" | "kamino_position_rate" | "token_lending_position" | "token_carry_position" | "fee_wallet_balance" | "protocol_manifest";
+/**
+ * Balance held by the protocol fee wallet for one mint. Performance fees
+ * arrive here as collateral at `collect_interest` time (no pending counter
+ * exists on the token), and mint/burn fees arrive as yTokens via
+ * `collect_fees` — so these balances are the only on-chain record of
+ * cumulative collected fees.
+ */
+interface FeeWalletBalanceMetricSnapshot {
+    entityType: "fee_wallet_balance";
+    wallet: Address;
+    mint: Address;
+    symbol: string;
+    /** "collateral" = performance fees; "ytoken" = collected mint/burn fees. */
+    kind: "collateral" | "ytoken";
+    decimals: number;
+    amountRaw: string;
+    amountUi: number;
+    priceUsd: number;
+    valueUsd: number;
+}
+/** Index of entity keys written for a single ingestion hour (enables API assembly). */
+interface ProtocolManifestSnapshot {
+    entityType: "protocol_manifest";
+    tokenMints: Address[];
+    bankAddresses: Address[];
+    kaminoPositions: Array<{
+        mint: Address;
+        lendingPositionIndex: number;
+    }>;
+    yieldingBankAssets: Array<{
+        bank: Address;
+        mint: Address;
+    }>;
+    /** Present on manifests written after Phase 2 ingestion deploy. */
+    tokenLendingPositions?: Array<{
+        mint: Address;
+        lendingPositionIndex: number;
+    }>;
+    /** Present on manifests written after Phase 2 ingestion deploy. */
+    tokenCarryPositions?: Array<{
+        mint: Address;
+        carryPositionIndex: number;
+    }>;
+    /** Present on manifests written after fee-wallet tracking deploy. */
+    feeWalletBalances?: Array<{
+        wallet: Address;
+        mint: Address;
+    }>;
+    /**
+     * Per-row build failures from this ingestion hour (skipped Kamino rate rows,
+     * failed inspect enrichment). Persisted so the ops dashboard can surface
+     * partial snapshots instead of silently dropping rows.
+     */
+    errors?: ProtocolMetricsSnapshotError[];
+}
+declare const PROTOCOL_MANIFEST_PK = "protocol_manifest";
+interface TokenMetricSnapshot {
+    entityType: "token";
+    token: Address;
+    mint: Address;
+    collateralMint: Address;
+    isActive: boolean;
+    priceCollateral: number;
+    collateralPriceUsd: number;
+    priceUsd: number;
+    totalSupply: number;
+    tvlUsdRaw: string;
+    tvlUsd: number;
+    carryTvlUsdRaw: string;
+    carryTvlUsd: number;
+    debtUsdRaw: string;
+    debtUsd: number;
+    netYieldUsdRaw: string;
+    netYieldUsd: number;
+    pendingProtocolFeesRaw: string;
+    pendingProtocolFeesUi: number;
+    pendingCuratorFeesRaw: string;
+    pendingCuratorFeesUi: number;
+    performanceFeeBps: number;
+    mintingFeeBps: number;
+    burningFeeBps: number;
+    protocolMintBurnPctBps: number;
+    curatorMintBurnPctBps: number;
+    curatorPerfPctBps: number;
+    /** Absent on snapshots ingested before fee-drip projection metrics were added. */
+    feeDripMaxApyBps?: number;
+    feeDripCurrentApyBps?: number | null;
+    undrippedFeeCollateralUi?: number;
+    feeDripAbsorptionEtaSeconds?: number | null;
+    feeDripAbsorptionStatus?: FeeDripAbsorptionStatus;
+    firstMintTs: number;
+    collateralOracle: Address;
+    collateralLastRefreshedTs: number;
+    unlentCollateralUi: number;
+    lastRefreshedTs: number;
+}
+interface YieldingBankMetricSnapshot {
+    entityType: "yielding_bank";
+    bank: Address;
+    id: number;
+    baseMint: Address;
+    isActive: boolean;
+    sharePriceRaw: string;
+    sharePriceUsd: number;
+    totalSharesRaw: string;
+    totalShares: number;
+    tvlUsdRaw: string;
+    tvlUsd: number;
+    baseSymbol: string;
+    curator: Address;
+    circuitBreaker: number;
+    defaultRedemptionMint?: Address;
+    externalYieldingPositions: YieldingBankExternalPositionMetricSnapshot[];
+    lastRefreshedTs: number;
+    lastRebalancedTs: number;
+}
+interface YieldingBankAssetMetricSnapshot {
+    entityType: "yielding_bank_asset";
+    bank: Address;
+    assetIndex: number;
+    assetKind: "base" | "asset";
+    mint: Address;
+    amountRaw: string;
+    amountUi: number;
+    decimals: number;
+    priceRaw: string;
+    priceUsd: number;
+    tvlUsdRaw: string;
+    tvlUsd: number;
+}
+interface TokenLendingPositionMetricSnapshot {
+    entityType: "token_lending_position";
+    token: Address;
+    mint: Address;
+    lendingPositionIndex: number;
+    platform: LendingPlatform;
+    withdrawPending: boolean;
+    pool: Address;
+    userAccount: Address;
+    collateralAmountRaw: string;
+    collateralAmountUi: number;
+    collateralSymbol: string;
+    collateralUsd: number;
+    debtAmountRaw: string;
+    debtAmountUi: number;
+    debtTvlUsdRaw: string;
+    debtTvlUsd: number;
+    debtMint: Address;
+    debtSymbol: string;
+    debtPriceUsd: number;
+    onChainUtilizationRateBps: number;
+    targetUtilizationRateBps: number;
+    maxDeviationAboveTargetUtilBps: number;
+    maxDeviationBelowTargetUtilBps: number;
+    inspect?: LendingPositionInspectMetricSnapshot;
+}
+interface TokenCarryPositionMetricSnapshot {
+    entityType: "token_carry_position";
+    token: Address;
+    mint: Address;
+    carryPositionIndex: number;
+    yieldingBankId: number;
+    yieldingBankAddress?: Address;
+    baseMint: Address;
+    baseSymbol: string;
+    sharesRaw: string;
+    sharesUi?: number;
+    tvlUsdRaw: string;
+    tvlUsd: number;
+}
+interface KaminoPositionRateSnapshot {
+    entityType: "kamino_position_rate";
+    token: Address;
+    mint: Address;
+    lendingPositionIndex: number;
+    pool: Address;
+    userAccount: Address;
+    collateralReserve: Address;
+    debtReserve: Address;
+    collateralMint: Address;
+    debtMint: Address;
+    supplyBaseApy: number;
+    borrowBaseApy: number;
+    supplyEffectiveApy: number;
+    borrowEffectiveApy: number;
+    netEffectiveApy: number;
+    collateralReserveUtilizationPct: number;
+    debtReserveUtilizationPct: number;
+    onChainLtvUtilizationBps: number;
+    targetUtilizationRateBps: number;
+    maxDeviationAboveTargetUtilBps: number;
+    maxDeviationBelowTargetUtilBps: number;
+}
+type ProtocolMetricSnapshotRow = TokenMetricSnapshot | YieldingBankMetricSnapshot | YieldingBankAssetMetricSnapshot | KaminoPositionRateSnapshot | TokenLendingPositionMetricSnapshot | TokenCarryPositionMetricSnapshot | FeeWalletBalanceMetricSnapshot | ProtocolManifestSnapshot;
+interface ProtocolMetricsSnapshot {
+    timestamp: number;
+    tokens: TokenMetricSnapshot[];
+    yieldingBanks: YieldingBankMetricSnapshot[];
+    yieldingBankAssets: YieldingBankAssetMetricSnapshot[];
+    kaminoPositionRates: KaminoPositionRateSnapshot[];
+    tokenLendingPositions: TokenLendingPositionMetricSnapshot[];
+    tokenCarryPositions: TokenCarryPositionMetricSnapshot[];
+    feeWalletBalances: FeeWalletBalanceMetricSnapshot[];
+    errors: ProtocolMetricsSnapshotError[];
+}
+interface ProtocolMetricsSnapshotError {
+    scope: "kamino_position_rate" | "lending_position_inspect";
+    token: Address;
+    lendingPositionIndex: number;
+    message: string;
+}
+interface BuildProtocolMetricsSnapshotOptions {
+    timestamp?: number;
+    includeInactive?: boolean;
+    tokens?: LYCToken[];
+    yieldingBanks?: LYCYieldingBank[];
+}
+declare function protocolMetricPartitionKey(metric: ProtocolMetricSnapshotRow): string;
+declare function buildProtocolManifestSnapshot(snapshot: ProtocolMetricsSnapshot): ProtocolManifestSnapshot;
+declare function flattenProtocolMetricsSnapshot(snapshot: ProtocolMetricsSnapshot): ProtocolMetricSnapshotRow[];
+/** Dynamo item shape written by {@link buildProtocolMetricDynamoItems}. */
+interface ProtocolMetricDynamoItem {
+    pk: string;
+    timestamp: number;
+    entityType: ProtocolMetricEntityType;
+    metrics: ProtocolMetricSnapshotRow;
+    ttl?: number;
+}
+declare function toProtocolMetricDynamoItem(metric: ProtocolMetricSnapshotRow, hourTimestamp: number, ttl?: number): ProtocolMetricDynamoItem;
+interface BuildProtocolMetricDynamoItemsOptions extends BuildProtocolMetricsSnapshotOptions {
+    hourTimestamp: number;
+    ttl?: number;
+}
+interface BuildProtocolMetricDynamoItemsResult {
+    items: ProtocolMetricDynamoItem[];
+    errors: ProtocolMetricsSnapshotError[];
+}
+/** Builds on-chain snapshot rows and maps them to Dynamo put payloads. */
+declare function buildProtocolMetricDynamoItems(client: LongYieldCarryClient, opts: BuildProtocolMetricDynamoItemsOptions): Promise<BuildProtocolMetricDynamoItemsResult>;
+declare function buildProtocolMetricsSnapshot(client: LongYieldCarryClient, opts?: BuildProtocolMetricsSnapshotOptions): Promise<ProtocolMetricsSnapshot>;
+declare function buildFeeWalletBalanceSnapshots(client: LongYieldCarryClient, tokens: LYCToken[]): Promise<FeeWalletBalanceMetricSnapshot[]>;
+declare function buildTokenMetricSnapshot(token: LYCToken, yieldingBanks?: LYCYieldingBank[], nowTs?: number): TokenMetricSnapshot;
+declare function buildYieldingBankMetricSnapshot(bank: LYCYieldingBank): YieldingBankMetricSnapshot;
+declare function buildTokenLendingPositionMetricSnapshots(token: LYCToken, yieldingBanks?: LYCYieldingBank[]): TokenLendingPositionMetricSnapshot[];
+declare function buildTokenLendingPositionMetricSnapshotsAsync(client: LongYieldCarryClient, token: LYCToken, yieldingBanks?: LYCYieldingBank[]): Promise<{
+    snapshots: TokenLendingPositionMetricSnapshot[];
+    errors: ProtocolMetricsSnapshotError[];
+}>;
+declare function serializeLendingPositionInspectMetrics(metrics: LendingPositionInspectMetrics | null | undefined): LendingPositionInspectMetricSnapshot | undefined;
+declare function kaminoCollateralUsd(token: LYCToken, position: TokenLendingPositionData): number;
+declare function shouldIncludeKaminoPositionRate(collateralUsd: number, maxCollateralUsdOnToken: number): boolean;
+declare function buildTokenCarryPositionMetricSnapshots(token: LYCToken, yieldingBanks: LYCYieldingBank[]): TokenCarryPositionMetricSnapshot[];
+declare function buildYieldingBankAssetMetricSnapshots(bank: LYCYieldingBank): YieldingBankAssetMetricSnapshot[];
+declare function buildKaminoPositionRateSnapshotFromReserves(token: LYCToken, lendingPositionIndex: number, position: TokenLendingPositionData, collateralReserve: ReserveBase, debtReserve: ReserveBase): KaminoPositionRateSnapshot;
+
+/** User-facing LYC transaction kinds we index. */
+type LycTransactionType = "mint" | "burn";
+/**
+ * A single normalized LYC transaction event produced from a raw tx payload.
+ *
+ * A single Solana transaction can contain multiple top-level LYC instructions
+ * (e.g. `refresh_yielding_bank` + `decrease_carry_position` + `burn_token`),
+ * but only user-facing ones (`mint_token`, `burn_token`) surface here. Other
+ * LYC instructions in the same tx are infrastructure and are not indexed as
+ * user events.
+ */
+interface LycTransactionEvent {
+    /** Solana transaction signature. */
+    signature: string;
+    /** Solana slot the tx was included in. */
+    slot: number;
+    /** Block time (unix seconds). */
+    blockTime: number;
+    /** Classified instruction kind. */
+    type: LycTransactionType;
+    /** User wallet: the tx signer for mint/burn (fee payer index 0). */
+    wallet: string;
+    /** Token mint minted into / burned from the user's token ATA. */
+    tokenMint: string;
+    /**
+     * Token base-unit amount.
+     * - `mint`: minted to the user (positive).
+     * - `burn`: burned from the user (positive).
+     */
+    tokenAmountBaseUnits: string;
+    /** Underlying collateral mint (e.g. wSOL when collateral is SOL). */
+    collateralMint: string;
+    /**
+     * Collateral base-unit amount moved to/from the user:
+     * - `mint`: collateral deposited by the user.
+     * - `burn`: collateral paid out to the user (net of fees).
+     */
+    collateralAmountBaseUnits: string;
+    /** Transaction fee in lamports paid by the signer. */
+    fee: number;
+}
+/**
+ * One LYC-program-related transaction we ingested and queued for indexing.
+ *
+ * `payload` is the raw Solana transaction object (slot, meta, transaction,
+ * version, etc.) — the same shape you get from `getTransaction` / streamed
+ * commitment updates. `source` discriminates this envelope from other queue
+ * producers if we add them later.
+ */
+interface LycProgramTransactionRecord {
+    source: "lyc-program-transaction";
+    /** Unix seconds when our API accepted and wrapped the payload. */
+    receivedAt: number;
+    signature: string;
+    slot?: number;
+    /** Raw Solana tx + meta (RPC / stream shape). */
+    payload: unknown;
+}
+
+/**
+ * Decoder: streamed Solana transaction payloads → normalized LYC user events.
+ *
+ * Wire shape is validator-style `getTransaction` data wrapped by the API into
+ * {@link LycProgramTransactionRecord} when enqueued. Downstream consumers (the
+ * indexer Lambda, backfill jobs) validate the envelope with
+ * {@link parseLycProgramTransactionRecord} then call
+ * {@link decodeLycProgramTransaction} to produce zero or more user-facing
+ * {@link LycTransactionEvent}s.
+ *
+ * The set of indexed instructions is currently `mint_token` and `burn_token`.
+ * Both are inlined in this module — if we ever add a third, promote back to a
+ * registry/interface pattern.
+ */
+
+/**
+ * Validate and narrow an arbitrary JSON body (SQS message body / API request)
+ * to {@link LycProgramTransactionRecord}. Returns `null` on any shape mismatch.
+ */
+declare function parseLycProgramTransactionRecord(input: unknown): LycProgramTransactionRecord | null;
+/**
+ * Stable enum of why a matched-discriminator instruction produced no event.
+ * All reasons are CPI-driven; none depend on balance deltas.
+ */
+type DecoderRejectionReason = "accounts_too_short" | "missing_key" | "no_inner_instructions_block" | "no_token_burn_cpi" | "no_token_mint_to_cpi" | "no_collateral_out_delta" | "no_collateral_in_delta";
+/**
+ * One reason a tx produced zero events despite looking like something we index.
+ *
+ * - `payload_unparseable`: the envelope `payload` lacked `meta` / `transaction.message` and
+ *   we couldn't even enumerate instructions.
+ * - `instruction_data_invalid`: an LYC-program instruction's `data` field wasn't valid
+ *   base58 so we couldn't read its discriminator.
+ * - `decoder_rejected`: the discriminator matched a user-facing decoder but a guard rail
+ *   returned null — `reason` identifies which guard.
+ */
+type DecodeRejection = {
+    kind: "payload_unparseable";
+} | {
+    kind: "instruction_data_invalid";
+    instructionIndex: number;
+} | {
+    kind: "decoder_rejected";
+    name: "mint_token" | "burn_token";
+    reason: DecoderRejectionReason;
+};
+interface DecodeResult {
+    events: LycTransactionEvent[];
+    /**
+     * Non-empty only when something anomalous happened. Consumers that want to
+     * distinguish "refresh-only tx, nothing to do" from "tried and bailed" check
+     * `rejections.length === 0` for the former and `rejections.length > 0` for
+     * the latter.
+     */
+    rejections: DecodeRejection[];
+}
+/**
+ * Decode one queued tx into zero or more user-facing events, in top-level
+ * instruction order. Silently skips instructions we don't index or whose data
+ * cannot be base58-decoded.
+ */
+declare function decodeLycProgramTransaction(record: LycProgramTransactionRecord): LycTransactionEvent[];
+/**
+ * Same as {@link decodeLycProgramTransaction} but also returns structured
+ * rejections for the indexer's CloudWatch log path. Use this when "zero events"
+ * isn't enough information — e.g. you need to know whether a burn-shaped tx
+ * bailed because its inner-instructions block was missing or because no
+ * collateral transfer CPI landed in the user's ATA.
+ */
+declare function decodeLycProgramTransactionWithDiagnostics(record: LycProgramTransactionRecord): DecodeResult;
+
+/**
+ * Top-level instructions that invoke the LYC program, in tx order.
+ * Returns `null` if the payload can't be parsed (missing meta/message).
+ */
+declare function listLycTopLevelInstructionNames(record: LycProgramTransactionRecord): string[] | null;
+
+/**
+ * IDL-backed account resolution for the LYC decoder.
+ *
+ * The decoder reads specific accounts (wallet, mint, collateral mint, user
+ * ATAs) out of each indexed instruction's account list. Rather than hardcoding
+ * positional indices — which silently break if the on-chain
+ * `#[derive(Accounts)]` struct is ever reordered — we resolve positions by
+ * account name off the SDK's shipped IDL at module load.
+ *
+ * Guarantees:
+ *  - **Resilient to reordering.** If the Rust program reorders accounts, the
+ *    regenerated IDL updates the name→index map and the decoder follows.
+ *  - **Fail-fast on rename/removal.** If an account we depend on is renamed
+ *    or removed, this module throws at import time — the SDK fails to load
+ *    instead of producing mislabeled events.
+ *  - **Minimal surface.** Only pins the accounts the decoder actually reads
+ *    (`signer`, `mint`, `collateral_mint`, `user_token_account`,
+ *    `user_collateral_account`). Unused accounts can be renamed freely.
+ */
+declare const MINT_TOKEN_REQUIRED_ACCOUNT_NAMES: readonly ["signer", "mint", "collateral_mint", "user_collateral_account", "user_token_account"];
+declare const BURN_TOKEN_REQUIRED_ACCOUNT_NAMES: readonly ["signer", "mint", "user_token_account", "user_collateral_account"];
+type MintTokenAccountName = (typeof MINT_TOKEN_REQUIRED_ACCOUNT_NAMES)[number];
+type BurnTokenAccountName = (typeof BURN_TOKEN_REQUIRED_ACCOUNT_NAMES)[number];
+/** Name→index map for the accounts list of `mint_token`. */
+declare const MINT_TOKEN_ACCOUNTS: Readonly<Record<"signer" | "mint" | "user_token_account" | "collateral_mint" | "user_collateral_account", number>>;
+/** Name→index map for the accounts list of `burn_token`. */
+declare const BURN_TOKEN_ACCOUNTS: Readonly<Record<"signer" | "mint" | "user_token_account" | "user_collateral_account", number>>;
+
+export { ASSET_PRESETS, AllocationService, type AllocationServiceOptions, type AllocationStrategy, type AllocationTarget, type AllocationTimelockKind, type AllocationTimelockStatus, type AssetPresetEntry, BTC_CARRY_PRESETS, BURN_TOKEN_ACCOUNTS, BURN_TOKEN_REQUIRED_ACCOUNT_NAMES, type BuildLendingPositionAllocationArgs, type BuildProtocolMetricDynamoItemsOptions, type BuildProtocolMetricDynamoItemsResult, type BuildProtocolMetricsSnapshotOptions, BurnAmounts, type BurnTokenAccountName, BurnTokenBuilder, type CarryLendingAllocationConfig, type CarryPriceBandPreset, type CarryVolatilityPresets, ClaimIncentivesBuilder, type CollateralPriceTriggerBand, type CollateralPriceTriggerLevel, CollectFeesBuilder, CollectInterestBuilder, type CollectInterestBuilderParams, type CollectInterestExecutionPlan, type CollectInterestHoldingPlan, type CollectInterestPlan, type CollectInterestPlanParams, type CollectInterestRouteBuilderParams, type CollectInterestTxPlanParams, type CompositeTransactionPlan, type ComputeCarryLendingAllocationConfigParams, type ComputeConfigForCollateralArgs, CreateCpiPlanBuilder, CreateTokenBuilder, CreateTokenLendingPositionAccounts, CreateTokenLendingPositionBuilder, CreateTokenLendingPositionParams, CreateYieldingBankAllocationBuilder, CreateYieldingBankBuilder, CreditUnlentToRedemptionEpochBuilder, type DebtAllocationTarget, type DebtReallocation, type DecodeRejection, type DecodeResult, type DecoderRejectionReason, type DecreaseCarryPositionBuildTxOptions, DecreaseCarryPositionBuilder, DecreaseCarryPositionBuilderParams, DecreaseCarryPositionPlan, DecreaseCarryPositionTxBuilderParams, DecreaseCarryPositionTxParams, DepositUnlentCollateralBuilder, ETH_CARRY_PRESETS, type EnrichedTokenCarryPosition, type EnrichedTokenCarrySummary, type EnrichedTokenCollateralSnapshot, type EnrichedTokenFeesSnapshot, type EnrichedTokenLendingPosition, type EnrichedTokenSnapshot, type EnrichedYieldingBankExternalPosition, type EnrichedYieldingBankHolding, type EnrichedYieldingBankSnapshot, type EnsureInitialKaminoLendingPositionOptions, type EvenDepositAllocation, type FeeDripAbsorptionStatus, type FeeDripMetrics, type FeeDripMetricsInput, type FeeWalletBalanceMetricSnapshot, type FundRedemptionEpochResult, type GetAvailableTokenLendingUserAccountIdArgs, INVALID_UTILIZATION_RATE_CONDITION_CODE, IncreaseCarryPositionBuilder, IndexedLendingPosition, type KaminoPositionRateSnapshot, LARGE_CAP_ALT_CARRY_PRESETS, LST_CARRY_PRESETS, LYCToken, LYCYieldingBank, LendingPlatformClientRegistry, type LendingPlatformResolver, type LendingPositionAllocation, LendingPositionBootstrapError, type LendingPositionInspectMetricSnapshot, type LendingPositionInspectMetrics, type LendingPositionSelectedPrice, LendingPositionService, type LendingPositionUtilizationPrices, type LendingPositionUtilizationRatesBps, LongYieldCarryBuilderContext, LongYieldCarryClient, type LongYieldCarryClientOptions, LongYieldCarryTransactionPlan, LycLendingPositionManager, type LycProgramTransactionRecord, type LycTransactionEvent, type LycTransactionType, MAX_LENDING_POSITION_UPPER_UTIL_BPS, MAX_TARGET_UTILIZATION_RATE_BPS, MINT_TOKEN_ACCOUNTS, MINT_TOKEN_REQUIRED_ACCOUNT_NAMES, MIN_DEVIATION_ABOVE_TARGET_UTIL_BPS, MIN_MATERIAL_KAMINO_COLLATERAL_USD, type MintTokenAccountName, MintTokenBuilder, NoInterestToCollectError, NoOpTransactionError, PROTOCOL_MANIFEST_PK, PricedMint, ProcessAsyncBurnBuilder, type ProcessEpochResult, type ProtocolManifestSnapshot, type ProtocolMetricDynamoItem, type ProtocolMetricEntityType, type ProtocolMetricSnapshotRow, type ProtocolMetricsSnapshot, type ProtocolMetricsSnapshotError, type RebalancePlanResult, RebalancePlanner, RebalanceSwapSpec, RebalanceTokenBuilder, RebalanceYieldingBankBuilder, RecollateralizeLossBuilder, RedemptionEpochSnapshot, type RedemptionFundingErrors, type RedemptionFundingFailure, RedemptionService, type RedemptionServiceOptions, RefreshTokenStateBuilder, RefreshTokensBuilder, RefreshYieldingBankBuilder, ResetTokenBurnRateLimitBuilder, type ResolvedDecreaseCarryCpiPlan, SMALL_CAP_ALT_CARRY_PRESETS, SOL_CARRY_PRESETS, STOCK_INDEX_PRESETS, SetRedemptionEpochStatusBuilder, SetTokenCircuitBreakerBuilder, SetYieldingBankCircuitBreakerBuilder, SimpleUsdStarStrategy, SingleCpiExecutionPlan, type StructuredRedemptionLog, SupportedLendingPlatformClients, type TargetAllocation, type TimelockKind, type TimelockOptions, type TimelockStatus, type TokenCarryPositionMetricSnapshot, type TokenInspectSnapshotArgs, TokenLendingPositionData, type TokenLendingPositionMetricSnapshot, type TokenMetricSnapshot, TokenRebalanceService, type TokenRebalanceServiceOptions, TopUpUnlentReservesBuilder, type TransactionBuilder, TransactionClient, UpdateLendingPositionConfigBuilder, UpdateTokenConfigurationBuilder, UpdateTokenMetadataBuilder, UpdateYieldingBankConfigBuilder, VOLATILITY_REGIMES, type VolatilityRegime, YieldingBankAllocationConfig, type YieldingBankAssetMetricSnapshot, YieldingBankExternalLiquiditySource, type YieldingBankExternalPositionMetricSnapshot, type YieldingBankInspectSnapshotArgs, type YieldingBankMetricSnapshot, type YieldingBankRebalancePlan, allocationTimelocksEnabled, amountToTvl, assertCollectInterestPlanHasPositiveRedemptions, buildCarryTradeAccountMetas, buildCollectInterestPlan, buildDecreaseCarryPositionPlan, buildFeeWalletBalanceSnapshots, buildKaminoPositionRateSnapshotFromReserves, buildLendingPositionAllocation, buildProtocolManifestSnapshot, buildProtocolMetricDynamoItems, buildProtocolMetricsSnapshot, buildRebalanceTokenInitialAccounts, buildTokenCarryPositionMetricSnapshots, buildTokenInspectSnapshot, buildTokenLendingPositionMetricSnapshots, buildTokenLendingPositionMetricSnapshotsAsync, buildTokenMetricSnapshot, buildYieldingBankAssetMetricSnapshots, buildYieldingBankInspectSnapshot, buildYieldingBankMetricSnapshot, calculateFeeDripMetrics, clampLendingPositionConfigBps, collectableNetYieldUsd, composePhasedTransactionPlan, computeBurnAmountsForFrontendEstimate, computeCarryLendingAllocationConfig, computeConfigForCollateral, computeEvenDepositAllocation, createYTokenMint, currentEpochId, decodeLycProgramTransaction, decodeLycProgramTransactionWithDiagnostics, extractLycErrorCode, findBestYieldingBankForBurn, findFreeTokenId, findFreeYieldingBankId, findPositionToUnwindForBurn, firstActiveLendingIndex, flattenProtocolMetricsSnapshot, formatTransactionError, getAllocationTimelockStatus, getAvailableTokenLendingUserAccountId, getBurnCollateralWithdrawalAmount, getBurnCollateralWithdrawalUiAmount, getLookupTableForToken, getRefreshTokenInstructionsIfStale, getTimelockStatus, getTokenCacheInvalidation, getYieldingBankCacheInvalidation, hasLendingPositionCoveringBurn, isSkippableLycTransactionError, isVolatilityRegime, isWithdrawOnlyBurnFeasible, kaminoCollateralUsd, listLycTopLevelInstructionNames, lookupLycError, mergeLycLookupTables, parseLoggedLycAnchorError, parseLycProgramTransactionRecord, podBoolToNumber, protocolMetricPartitionKey, resolveDecreaseCarryCpiPlan, resolveDecreaseCarryIxRefs, resolveDefaultPool, resolvePresets, resolveYieldingBankForPosition, serializeLendingPositionInspectMetrics, setTokenCircuitBreaker, setYieldingBankCircuitBreaker, shouldIncludeKaminoPositionRate, timelocksEnabled, toAnchorAllocationConfig, toProtocolMetricDynamoItem, toYieldingBankExternalLiquiditySources, updateGeneralLutIfNeeded, updateTokenLutIfNeeded, updateTokenLutsIfNeeded, usdStarAllocationConfig, usdStarJuniorAllocationConfig };