@kestrelfi/lyc-sdk 1.0.1

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

@@ -0,0 +1,168 @@
+import type { Address } from "@solana/kit";
+import type { LendingPlatform, MintRegistry } from "common";
+import type { LendingPlatformData, LendingPositionInspectMetrics } from "lending-platforms";
+import type { LYCYieldingBank } from "../models/yieldingBank";
+import type { FeeDripAbsorptionStatus } from "../utils/feeDripMetrics";
+export type { LendingPositionInspectMetrics, LendingPositionSelectedPrice, LendingPositionUtilizationRatesBps, LendingPositionUtilizationPrices, CollateralPriceTriggerBand, CollateralPriceTriggerLevel, } from "lending-platforms";
+export interface YieldingBankInspectSnapshotArgs {
+    environment: "local" | "test" | "prod";
+    mintRegistry: MintRegistry;
+    timelocksEnabledInLocal?: boolean;
+}
+export 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;
+}
+export interface EnrichedYieldingBankHolding {
+    kind: "base" | "asset";
+    mint: Address;
+    symbol: string;
+    amountRaw: bigint;
+    amountUi: number;
+    decimals: number;
+    priceRaw: bigint;
+    priceUi: number;
+    isTimelocked: boolean;
+}
+export interface EnrichedYieldingBankExternalPosition {
+    platform: LendingPlatform;
+    pool: Address;
+    tvlRaw: bigint;
+    tvlUsd: number;
+    isTimelocked: boolean;
+}
+export 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[];
+}
+export 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;
+}
+export 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;
+}
+export interface EnrichedTokenCarryPosition {
+    index: number;
+    yieldingBankId: number;
+    yieldingBankAddress?: Address;
+    baseMint: Address;
+    baseSymbol: string;
+    sharesRaw: bigint;
+    sharesUi?: number;
+    shareDecimals?: number;
+    tvlUsdRaw: bigint;
+    tvlUsd: number;
+}
+export interface EnrichedTokenCarrySummary {
+    totalCarryTvlUsdRaw: bigint;
+    totalCarryTvlUsd: number;
+    totalDebtUsdRaw: bigint;
+    totalDebtUsd: number;
+    netYieldUsdRaw: bigint;
+    netYieldUsd: number;
+}
+export interface EnrichedTokenFeesSnapshot {
+    mintingFeeBps: number;
+    burningFeeBps: number;
+    performanceFeeBps: number;
+    protocolMintBurnPctBps: number;
+    curatorMintBurnPctBps: number;
+    holderMintBurnPctBps: number;
+    curatorPerfPctBps: number;
+    feeDripMaxApyBps: number;
+    feeDripDurationSecs: bigint;
+    undrippedFeeCollateralRaw: bigint;
+    undrippedFeeCollateralUi: number;
+    dripEndTs: bigint;
+    apyReferencePriceRaw: bigint;
+    apyReferencePrice: number;
+    apyReferenceTs: bigint;
+    currentApyBps: number | null;
+    absorptionEtaSeconds: number | null;
+    absorptionStatus: FeeDripAbsorptionStatus;
+    pendingProtocolFeesRaw: bigint;
+    pendingProtocolFeesUi: number;
+    pendingCuratorFeesRaw: bigint;
+    pendingCuratorFeesUi: number;
+}
+export 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;
+}

package/dist/sdks/long-yield-carry/src/types/enriched.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -0,0 +1 @@
+export * from "./enriched";

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

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./enriched"), exports);

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

@@ -0,0 +1,4 @@
+import { type Address } from "@solana/kit";
+import { type TransactionCacheInvalidation } from "common";
+export declare function getTokenCacheInvalidation(token: Address): TransactionCacheInvalidation;
+export declare function getYieldingBankCacheInvalidation(yieldingBank: Address): TransactionCacheInvalidation;

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

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getTokenCacheInvalidation = getTokenCacheInvalidation;
+exports.getYieldingBankCacheInvalidation = getYieldingBankCacheInvalidation;
+function getTokenCacheInvalidation(token) {
+    return { client: "lycToken", tokenPda: token };
+}
+function getYieldingBankCacheInvalidation(yieldingBank) {
+    return { client: "lycYieldingBank", yieldingBankPda: yieldingBank };
+}

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

@@ -0,0 +1,12 @@
+import { type Address } from "@solana/kit";
+import type { LongYieldCarryClient } from "../client/client";
+/**
+ * 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.
+ */
+export declare function findFreeTokenId(client: LongYieldCarryClient, mint: Address): Promise<number>;
+/**
+ * First yielding-bank ID (0–255) not yet used for the given base mint.
+ */
+export declare function findFreeYieldingBankId(client: LongYieldCarryClient, baseMint: Address): Promise<number>;

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

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findFreeTokenId = findFreeTokenId;
+exports.findFreeYieldingBankId = findFreeYieldingBankId;
+const common_1 = require("common");
+/**
+ * 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.
+ */
+async function findFreeTokenId(client, mint) {
+    try {
+        client.account.dataCache.clearAllCache();
+        const tokens = await client.account.fetchAllTokens();
+        if (tokens.length > 0) {
+            const usedIds = new Set(tokens.filter((t) => t.mint === mint).map((t) => t.id));
+            for (let id = 0; id <= 255; id++) {
+                if (!usedIds.has(id))
+                    return id;
+            }
+            throw new Error(`No free token ID found for mint ${mint}`);
+        }
+    }
+    catch {
+        // getProgramAccounts may not be supported / reliable on some RPCs
+    }
+    for (let id = 0; id <= 255; id++) {
+        const [pda] = await client.pda.deriveTokenPda(mint, id);
+        if (!(await (0, common_1.accountExists)(client.rpc, pda)))
+            return id;
+    }
+    throw new Error(`No free token ID found for mint ${mint}`);
+}
+/**
+ * First yielding-bank ID (0–255) not yet used for the given base mint.
+ */
+async function findFreeYieldingBankId(client, baseMint) {
+    try {
+        client.account.dataCache.clearAllCache();
+        const banks = await client.account.fetchAllYieldingBanks();
+        if (banks.length > 0) {
+            const usedIds = new Set(banks.filter((b) => b.baseMint === baseMint).map((b) => b.id));
+            for (let id = 0; id <= 255; id++) {
+                if (!usedIds.has(id))
+                    return id;
+            }
+            throw new Error(`No free yielding bank ID found for mint ${baseMint}`);
+        }
+    }
+    catch {
+        // getProgramAccounts may not be supported / reliable on some RPCs
+    }
+    for (let id = 0; id <= 255; id++) {
+        const [pda] = await client.pda.deriveYieldingBankPda(baseMint, id);
+        if (!(await (0, common_1.accountExists)(client.rpc, pda)))
+            return id;
+    }
+    throw new Error(`No free yielding bank ID found for mint ${baseMint}`);
+}

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

@@ -0,0 +1,5 @@
+import type { LYCToken } from "../models/lycToken";
+import type { LYCYieldingBank } from "../models/yieldingBank";
+import type { EnrichedTokenSnapshot, EnrichedYieldingBankSnapshot, TokenInspectSnapshotArgs, YieldingBankInspectSnapshotArgs } from "../types/enriched";
+export declare function buildYieldingBankInspectSnapshot(bank: LYCYieldingBank, args: YieldingBankInspectSnapshotArgs): EnrichedYieldingBankSnapshot;
+export declare function buildTokenInspectSnapshot(token: LYCToken, args: TokenInspectSnapshotArgs): Promise<EnrichedTokenSnapshot>;

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

@@ -0,0 +1,244 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildYieldingBankInspectSnapshot = buildYieldingBankInspectSnapshot;
+exports.buildTokenInspectSnapshot = buildTokenInspectSnapshot;
+const web3_js_1 = require("@solana/web3.js");
+const common_1 = require("common");
+const oracle_1 = require("oracle");
+const carry_1 = require("../services/carry");
+const feeDripMetrics_1 = require("./feeDripMetrics");
+const general_1 = require("./general");
+const tokenFeeMath_1 = require("./tokenFeeMath");
+const timelock_1 = require("./timelock");
+function buildYieldingBankInspectSnapshot(bank, args) {
+    const { environment, mintRegistry, timelocksEnabledInLocal } = args;
+    const timelockOptions = { enableLocalTimelocks: timelocksEnabledInLocal };
+    const baseSymbol = (0, common_1.mintSymbol)(bank.baseMint, mintRegistry);
+    const defaultRedemptionMint = bank.defaultRedemptionMint !== web3_js_1.PublicKey.default.toBase58()
+        ? bank.defaultRedemptionMint
+        : undefined;
+    const holdings = [
+        {
+            kind: "base",
+            mint: bank.baseMint,
+            symbol: baseSymbol,
+            amountRaw: (0, common_1.toBigInt)(bank.data.baseAsset.amount),
+            amountUi: (0, common_1.toUiAmount)(bank.data.baseAsset.amount, bank.data.baseAsset.decimals),
+            decimals: bank.data.baseAsset.decimals,
+            priceRaw: (0, common_1.toBigInt)(bank.data.baseAsset.price),
+            priceUi: (0, common_1.toUiAmount)(bank.data.baseAsset.price, bank.data.baseAsset.decimals),
+            isTimelocked: (0, timelock_1.getTimelockStatus)(environment, bank.data.baseAsset.timeCreated, "touch", timelockOptions).isTimelocked,
+        },
+        ...bank.data.assets
+            .filter((asset) => !asset.mint.equals(web3_js_1.PublicKey.default))
+            .map((asset) => {
+            const mint = (0, common_1.fromWeb3Pk)(asset.mint);
+            return {
+                kind: "asset",
+                mint,
+                symbol: (0, common_1.mintSymbol)(mint, mintRegistry),
+                amountRaw: (0, common_1.toBigInt)(asset.amount),
+                amountUi: (0, common_1.toUiAmount)(asset.amount, asset.decimals),
+                decimals: asset.decimals,
+                priceRaw: (0, common_1.toBigInt)(asset.price),
+                priceUi: (0, common_1.toUiAmount)(asset.price, asset.decimals),
+                isTimelocked: (0, timelock_1.getTimelockStatus)(environment, asset.timeCreated, "touch", timelockOptions)
+                    .isTimelocked,
+            };
+        }),
+    ];
+    const externalYieldingPositions = bank.data.externalYieldingPositions
+        .map((position) => ({
+        platform: (0, common_1.lendingPlatformToEnum)(position.lendingPlatform),
+        pool: (0, common_1.fromWeb3Pk)(position.pool),
+        tvlRaw: (0, common_1.toBigInt)(position.tvl),
+        tvlUsd: (0, common_1.toUiAmount)(position.tvl, common_1.TVL_USD_DECIMAL_PLACES),
+        isTimelocked: (0, timelock_1.getTimelockStatus)(environment, position.timeCreated, "touch", timelockOptions)
+            .isTimelocked,
+    }))
+        .filter((position) => position.platform !== common_1.LendingPlatform.None);
+    return {
+        address: bank.address,
+        id: bank.id,
+        curator: (0, common_1.fromWeb3Pk)(bank.data.roles.curator),
+        baseMint: bank.baseMint,
+        baseSymbol,
+        isActive: bank.isActive,
+        circuitBreaker: bank.circuitBreaker,
+        decimals: bank.decimals,
+        tvlRaw: (0, common_1.toBigInt)(bank.data.accounting.tvl),
+        tvlUsd: (0, common_1.toUiAmount)(bank.data.accounting.tvl, common_1.TVL_USD_DECIMAL_PLACES),
+        sharePrice: bank.sharePrice,
+        totalShares: bank.totalShares,
+        lastRefreshedTs: (0, common_1.toBigInt)(bank.data.accounting.lastRefreshedTs),
+        lastRebalancedTs: (0, common_1.toBigInt)(bank.data.accounting.lastRebalancedTs),
+        isTimelocked: (0, timelock_1.getTimelockStatus)(environment, bank.data.config.timeCreatedTs, "touch", timelockOptions).isTimelocked,
+        defaultRedemptionMint,
+        defaultRedemptionSymbol: defaultRedemptionMint
+            ? (0, common_1.mintSymbol)(defaultRedemptionMint, mintRegistry)
+            : undefined,
+        holdings,
+        externalYieldingPositions,
+    };
+}
+async function buildTokenInspectSnapshot(token, args) {
+    const { environment, mintRegistry, yieldingBanks, kaminoData } = args;
+    const collateralSymbol = (0, common_1.mintSymbol)(token.collateralMint, mintRegistry);
+    const [collateralRealtimePrices, collateralEmaPrices] = await Promise.all([
+        oracle_1.oracle.fetchPrices([token.collateralMint], "realtime", undefined, environment),
+        oracle_1.oracle.fetchPrices([token.collateralMint], "ema", undefined, environment),
+    ]);
+    const collateralRealtimePriceUi = collateralRealtimePrices[token.collateralMint];
+    const collateralEmaPriceUi = collateralEmaPrices[token.collateralMint];
+    const lendingPositions = (await Promise.all(token.data.lendingPositions.map((position, index) => buildLendingPositionInspectSnapshot(position, index, collateralSymbol, token.data.collateral.decimals, kaminoData, mintRegistry)))).filter((position) => position !== undefined);
+    const carryPositions = token.data.debtCarry
+        .map((carry, index) => {
+        if (carry.yieldingBaseMint.equals(web3_js_1.PublicKey.default) || (0, common_1.toBigInt)(carry.shares) <= BigInt(0)) {
+            return undefined;
+        }
+        const baseMint = (0, common_1.fromWeb3Pk)(carry.yieldingBaseMint);
+        const resolvedBank = yieldingBanks.find((bank) => bank.id === carry.yieldingBankId && bank.baseMint === baseMint);
+        const position = {
+            index,
+            yieldingBankId: carry.yieldingBankId,
+            yieldingBankAddress: resolvedBank?.address,
+            baseMint,
+            baseSymbol: (0, common_1.mintSymbol)(baseMint, mintRegistry),
+            sharesRaw: (0, common_1.toBigInt)(carry.shares),
+            sharesUi: resolvedBank ? (0, common_1.toUiAmount)(carry.shares, resolvedBank.decimals) : undefined,
+            shareDecimals: resolvedBank?.decimals,
+            tvlUsdRaw: (0, common_1.toBigInt)(carry.tvlUsd),
+            tvlUsd: (0, common_1.toUiAmount)(carry.tvlUsd, common_1.TVL_USD_DECIMAL_PLACES),
+        };
+        return position;
+    })
+        .filter((position) => position !== undefined);
+    const totalCarryTvlUsdRaw = carryPositions.reduce((sum, position) => sum + position.tvlUsdRaw, 0n);
+    const totalDebtUsdRaw = lendingPositions.reduce((sum, position) => sum + position.debtTvlUsdRaw, 0n);
+    // Net yield is the full active-carry surplus above active debt.
+    const netYieldUsdRaw = (0, tokenFeeMath_1.collectableNetYieldUsd)(totalCarryTvlUsdRaw, totalDebtUsdRaw);
+    const apyReferencePriceRaw = (0, common_1.toBigInt)(token.data.feeDrip.apyReferencePrice);
+    const feeDripMetrics = (0, feeDripMetrics_1.calculateFeeDripMetrics)({
+        currentPriceRaw: (0, common_1.toBigInt)(token.data.accounting.price),
+        apyReferencePriceRaw,
+        apyReferenceTs: (0, common_1.toBigInt)(token.data.feeDrip.apyReferenceTs),
+        currentPriceTs: (0, common_1.toBigInt)(token.data.accounting.lastRefreshedTs),
+        totalSupplyRaw: (0, common_1.toBigInt)(token.data.accounting.totalSupply),
+        tokenDecimals: token.decimals,
+        undrippedFeeCollateralRaw: (0, common_1.toBigInt)(token.data.feeDrip.undrippedFeeCollateral),
+        feeDripMaxApyBps: token.data.fees.feeDripMaxApyBps,
+        feeDripDurationSecs: (0, common_1.toBigInt)(token.data.fees.feeDripDurationSecs),
+        dripEndTs: (0, common_1.toBigInt)(token.data.feeDrip.dripEndTs),
+        nowTs: BigInt(args.nowTs ?? Math.floor(Date.now() / 1000)),
+    });
+    return {
+        address: token.address,
+        id: token.id,
+        curator: (0, common_1.fromWeb3Pk)(token.data.roles.curator),
+        mint: token.mint,
+        decimals: token.decimals,
+        isActive: token.isActive,
+        price: token.price,
+        totalSupply: token.totalSupply,
+        tvlUsdRaw: (0, common_1.toBigInt)(token.data.accounting.tvlUsd),
+        tvlUsd: (0, common_1.toUiAmount)(token.data.accounting.tvlUsd, common_1.TVL_USD_DECIMAL_PLACES),
+        lastRefreshedTs: (0, common_1.toBigInt)(token.data.accounting.lastRefreshedTs),
+        firstMintTs: (0, common_1.toBigInt)(token.data.accounting.firstMintTs),
+        collateral: {
+            mint: token.collateralMint,
+            symbol: collateralSymbol,
+            decimals: token.data.collateral.decimals,
+            unlentAmountRaw: (0, common_1.toBigInt)(token.data.collateral.unlentAmount),
+            unlentAmountUi: (0, common_1.toUiAmount)(token.data.collateral.unlentAmount, token.data.collateral.decimals),
+            pendingUnwindResidualRaw: (0, common_1.toBigInt)(token.data.accounting.pendingUnwindResidual),
+            pendingUnwindResidualUi: (0, common_1.toUiAmount)(token.data.accounting.pendingUnwindResidual, token.data.collateral.decimals),
+            oraclePriceRaw: (0, common_1.toBigInt)(token.data.collateral.price),
+            oraclePriceOnChainUi: (0, common_1.toUiAmount)(token.data.collateral.price, token.data.collateral.decimals),
+            oraclePriceRealtimeUi: collateralRealtimePriceUi,
+            oraclePriceEmaUi: collateralEmaPriceUi,
+            oracle: (0, common_1.fromWeb3Pk)(token.data.collateral.oracle),
+            secondaryOracle: token.data.collateral.secondaryOracle.equals(web3_js_1.PublicKey.default)
+                ? undefined
+                : (0, common_1.fromWeb3Pk)(token.data.collateral.secondaryOracle),
+            lastRefreshedTs: (0, common_1.toBigInt)(token.data.collateral.lastRefreshedTs),
+        },
+        lendingPositions,
+        carryPositions,
+        carrySummary: {
+            totalCarryTvlUsdRaw,
+            totalCarryTvlUsd: (0, common_1.toUiAmount)(totalCarryTvlUsdRaw, common_1.TVL_USD_DECIMAL_PLACES),
+            totalDebtUsdRaw,
+            totalDebtUsd: (0, common_1.toUiAmount)(totalDebtUsdRaw, common_1.TVL_USD_DECIMAL_PLACES),
+            netYieldUsdRaw,
+            netYieldUsd: (0, common_1.toUiAmount)(netYieldUsdRaw, common_1.TVL_USD_DECIMAL_PLACES),
+        },
+        hasInterestToCollect: token.hasInterestToCollect(),
+        fees: {
+            mintingFeeBps: token.data.fees.mintingFeeBps,
+            burningFeeBps: token.data.fees.burningFeeBps,
+            performanceFeeBps: token.data.fees.performanceFeeBps,
+            protocolMintBurnPctBps: token.data.fees.protocolMintBurnPctBps,
+            curatorMintBurnPctBps: token.data.fees.curatorMintBurnPctBps,
+            holderMintBurnPctBps: 10000 - token.data.fees.protocolMintBurnPctBps - token.data.fees.curatorMintBurnPctBps,
+            curatorPerfPctBps: token.data.fees.curatorPerfPctBps,
+            feeDripMaxApyBps: token.data.fees.feeDripMaxApyBps,
+            feeDripDurationSecs: (0, common_1.toBigInt)(token.data.fees.feeDripDurationSecs),
+            undrippedFeeCollateralRaw: (0, common_1.toBigInt)(token.data.feeDrip.undrippedFeeCollateral),
+            undrippedFeeCollateralUi: (0, common_1.toUiAmount)(token.data.feeDrip.undrippedFeeCollateral, token.data.collateral.decimals),
+            dripEndTs: (0, common_1.toBigInt)(token.data.feeDrip.dripEndTs),
+            apyReferencePriceRaw,
+            apyReferencePrice: (0, common_1.toUiAmount)(apyReferencePriceRaw, token.decimals),
+            apyReferenceTs: (0, common_1.toBigInt)(token.data.feeDrip.apyReferenceTs),
+            currentApyBps: feeDripMetrics.currentApyBps,
+            absorptionEtaSeconds: feeDripMetrics.absorptionEtaSeconds,
+            absorptionStatus: feeDripMetrics.absorptionStatus,
+            pendingProtocolFeesRaw: (0, common_1.toBigInt)(token.data.accounting.pendingProtocolFees),
+            pendingProtocolFeesUi: (0, common_1.toUiAmount)(token.data.accounting.pendingProtocolFees, token.decimals),
+            pendingCuratorFeesRaw: (0, common_1.toBigInt)(token.data.accounting.pendingCuratorFees),
+            pendingCuratorFeesUi: (0, common_1.toUiAmount)(token.data.accounting.pendingCuratorFees, token.decimals),
+        },
+    };
+}
+async function buildLendingPositionInspectSnapshot(position, index, collateralSymbol, collateralDecimals, kaminoData, mintRegistry) {
+    const platform = (0, common_1.lendingPlatformToEnum)(position.platform);
+    if (platform === common_1.LendingPlatform.None) {
+        return undefined;
+    }
+    let inspectMetrics;
+    if (platform === common_1.LendingPlatform.Kamino) {
+        try {
+            const manager = await carry_1.LycLendingPositionManager.create(kaminoData, position);
+            inspectMetrics = (await manager.getInspectMetrics()) ?? undefined;
+        }
+        catch {
+            inspectMetrics = undefined;
+        }
+    }
+    const debtMint = (0, common_1.fromWeb3Pk)(position.accounting.debt.mint);
+    return {
+        index,
+        platform,
+        withdrawPending: (0, general_1.podBoolToNumber)(position.withdrawPending) !== 0,
+        pool: (0, common_1.fromWeb3Pk)(position.pool),
+        userAccount: (0, common_1.fromWeb3Pk)(position.protocolUserAcc),
+        collateralAmountRaw: (0, common_1.toBigInt)(position.accounting.collateral),
+        collateralAmountUi: (0, common_1.toUiAmount)(position.accounting.collateral, collateralDecimals),
+        collateralDecimals,
+        collateralSymbol,
+        debtAmountRaw: (0, common_1.toBigInt)(position.accounting.debt.amount),
+        debtAmountUi: (0, common_1.toUiAmount)(position.accounting.debt.amount, position.accounting.debt.decimals),
+        debtTvlUsdRaw: (0, common_1.toBigInt)(position.accounting.debt.tvlUsd),
+        debtTvlUsd: (0, common_1.toUiAmount)(position.accounting.debt.tvlUsd, common_1.TVL_USD_DECIMAL_PLACES),
+        debtMint,
+        debtSymbol: (0, common_1.mintSymbol)(debtMint, mintRegistry),
+        debtDecimals: position.accounting.debt.decimals,
+        debtPriceRaw: (0, common_1.toBigInt)(position.accounting.debt.price),
+        debtPriceUi: (0, common_1.toUiAmount)(position.accounting.debt.price, position.accounting.debt.decimals),
+        onChainUtilizationRateBps: position.accounting.ltvUtilizationRateBps,
+        targetUtilizationRateBps: position.config.targetUtilizationRateBps,
+        maxDeviationAboveTargetUtilBps: position.config.maxDeviationAboveTargetUtilBps,
+        maxDeviationBelowTargetUtilBps: position.config.maxDeviationBelowTargetUtilBps,
+        lastRebalancedTs: (0, common_1.toBigInt)(position.lastUpdatedTs),
+        inspectMetrics,
+    };
+}

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

@@ -0,0 +1,36 @@
+export type FeeDripAbsorptionStatus = "estimated" | "no_fees" | "parked" | "apy_saturated" | "unavailable";
+export 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;
+    feeDripDurationSecs: bigint;
+    dripEndTs: bigint;
+    nowTs: bigint;
+}
+export 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 the time needed to release the
+ * outstanding fee buffer if the observed APY remains constant.
+ *
+ * The buffer's price impact is:
+ *   fee_price_delta [price units]
+ *     = buffer [collateral base units] * 10^token_decimals / supply [yToken base units]
+ *
+ * Dividing by the current price gives the remaining holder return. Dividing
+ * that return by `(max_apy - current_apy) [return/year]` gives the APY-limited
+ * release time in years. The actual estimate is the slower of that limit and
+ * the remaining linear drip schedule.
+ */
+export declare function calculateFeeDripMetrics(input: FeeDripMetricsInput): FeeDripMetrics;

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

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.calculateFeeDripMetrics = calculateFeeDripMetrics;
+const BASIS_POINTS = 10000;
+const SECONDS_PER_YEAR = 365 * 24 * 60 * 60;
+/**
+ * Derives the current fee-window APY and the time needed to release the
+ * outstanding fee buffer if the observed APY remains constant.
+ *
+ * The buffer's price impact is:
+ *   fee_price_delta [price units]
+ *     = buffer [collateral base units] * 10^token_decimals / supply [yToken base units]
+ *
+ * Dividing by the current price gives the remaining holder return. Dividing
+ * that return by `(max_apy - current_apy) [return/year]` gives the APY-limited
+ * release time in years. The actual estimate is the slower of that limit and
+ * the remaining linear drip schedule.
+ */
+function calculateFeeDripMetrics(input) {
+    const currentApyBps = calculateCurrentApyBps(input);
+    if (input.undrippedFeeCollateralRaw <= BigInt(0)) {
+        return {
+            currentApyBps,
+            absorptionEtaSeconds: 0,
+            absorptionStatus: "no_fees",
+        };
+    }
+    if (input.feeDripDurationSecs <= BigInt(0)) {
+        return {
+            currentApyBps,
+            absorptionEtaSeconds: null,
+            absorptionStatus: "parked",
+        };
+    }
+    const estimateTs = input.nowTs > input.currentPriceTs ? input.nowTs : input.currentPriceTs;
+    const linearEtaSeconds = Number(input.dripEndTs > estimateTs ? input.dripEndTs - estimateTs : BigInt(0));
+    if (input.feeDripMaxApyBps === 0) {
+        return finiteEstimate(currentApyBps, linearEtaSeconds);
+    }
+    if (currentApyBps == null ||
+        input.currentPriceRaw <= BigInt(0) ||
+        input.totalSupplyRaw <= BigInt(0) ||
+        input.tokenDecimals < 0) {
+        return {
+            currentApyBps,
+            absorptionEtaSeconds: null,
+            absorptionStatus: "unavailable",
+        };
+    }
+    const availableApyBps = input.feeDripMaxApyBps - currentApyBps;
+    if (availableApyBps <= 0) {
+        return {
+            currentApyBps,
+            absorptionEtaSeconds: null,
+            absorptionStatus: "apy_saturated",
+        };
+    }
+    let scale = BigInt(1);
+    for (let decimal = 0; decimal < input.tokenDecimals; decimal += 1) {
+        scale *= BigInt(10);
+    }
+    const remainingPriceReturn = Number(input.undrippedFeeCollateralRaw * scale) /
+        Number(input.totalSupplyRaw * input.currentPriceRaw);
+    const availableAnnualReturn = availableApyBps / BASIS_POINTS;
+    const apyEtaSeconds = Math.ceil((remainingPriceReturn / availableAnnualReturn) * SECONDS_PER_YEAR);
+    return finiteEstimate(currentApyBps, Math.max(linearEtaSeconds, apyEtaSeconds));
+}
+function calculateCurrentApyBps(input) {
+    if (input.currentPriceRaw <= BigInt(0) ||
+        input.apyReferencePriceRaw <= BigInt(0) ||
+        input.apyReferenceTs <= BigInt(0) ||
+        input.currentPriceTs <= input.apyReferenceTs) {
+        return null;
+    }
+    const elapsedSeconds = Number(input.currentPriceTs - input.apyReferenceTs);
+    const priceReturn = Number(input.currentPriceRaw) / Number(input.apyReferencePriceRaw) - 1;
+    const currentApyBps = priceReturn * (SECONDS_PER_YEAR / elapsedSeconds) * BASIS_POINTS;
+    return Number.isFinite(currentApyBps) ? currentApyBps : null;
+}
+function finiteEstimate(currentApyBps, absorptionEtaSeconds) {
+    if (!Number.isFinite(absorptionEtaSeconds) || absorptionEtaSeconds < 0) {
+        return {
+            currentApyBps,
+            absorptionEtaSeconds: null,
+            absorptionStatus: "unavailable",
+        };
+    }
+    return {
+        currentApyBps,
+        absorptionEtaSeconds: Math.ceil(absorptionEtaSeconds),
+        absorptionStatus: "estimated",
+    };
+}