@kestrelfi/lyc-sdk 1.0.1

package/src/metrics/protocolMetrics.ts

@@ -0,0 +1,976 @@
+import { PublicKey } from "@solana/web3.js";
+import type { Address } from "@solana/kit";
+import { fetchMaybeToken, TOKEN_PROGRAM_ADDRESS } from "@solana-program/token";
+import {
+  fetchMaybeToken as fetchMaybeToken2022,
+  TOKEN_2022_PROGRAM_ADDRESS,
+} from "@solana-program/token-2022";
+import {
+  calculateTvlUsd,
+  fromWeb3Pk,
+  getAtaAddress,
+  LendingPlatform,
+  lendingPlatformToEnum,
+  mintSymbol,
+  resolveTokenProgram,
+  toBigInt,
+  toUiAmount,
+  TVL_USD_DECIMAL_PLACES,
+  type AnchorTokenProgram,
+} from "common";
+import type { LendingPositionInspectMetrics, ReserveBase } from "lending-platforms";
+import type { LongYieldCarryClient } from "../client";
+import { PROTOCOL_FEE_WALLET } from "../constants/general";
+import type { LYCToken, TokenLendingPositionData } from "../models/lycToken";
+import type { LYCYieldingBank, YieldingBankAccountData } from "../models/yieldingBank";
+import { calculateFeeDripMetrics, type FeeDripAbsorptionStatus } from "../utils/feeDripMetrics";
+import { podBoolToNumber } from "../utils/general";
+import { collectableNetYieldUsd } from "../utils/tokenFeeMath";
+
+/** Skip dust Kamino slots when a material position exists on the same token. */
+export const MIN_MATERIAL_KAMINO_COLLATERAL_USD = 1;
+
+export interface LendingPositionInspectMetricSnapshot {
+  utilizationRealtimeBps: number;
+  utilizationEmaBps: number;
+  lowerTriggerPriceChangePct?: number;
+  upperTriggerPriceChangePct?: number;
+}
+
+export interface YieldingBankExternalPositionMetricSnapshot {
+  platform: LendingPlatform;
+  pool: Address;
+  tvlUsdRaw: string;
+  tvlUsd: number;
+}
+
+export 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.
+ */
+export 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). */
+export 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[];
+}
+
+export const PROTOCOL_MANIFEST_PK = "protocol_manifest";
+
+export 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;
+}
+
+export 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;
+}
+
+export 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;
+}
+
+export 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;
+}
+
+export 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;
+}
+
+export 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;
+}
+
+export type ProtocolMetricSnapshotRow =
+  | TokenMetricSnapshot
+  | YieldingBankMetricSnapshot
+  | YieldingBankAssetMetricSnapshot
+  | KaminoPositionRateSnapshot
+  | TokenLendingPositionMetricSnapshot
+  | TokenCarryPositionMetricSnapshot
+  | FeeWalletBalanceMetricSnapshot
+  | ProtocolManifestSnapshot;
+
+export interface ProtocolMetricsSnapshot {
+  timestamp: number;
+  tokens: TokenMetricSnapshot[];
+  yieldingBanks: YieldingBankMetricSnapshot[];
+  yieldingBankAssets: YieldingBankAssetMetricSnapshot[];
+  kaminoPositionRates: KaminoPositionRateSnapshot[];
+  tokenLendingPositions: TokenLendingPositionMetricSnapshot[];
+  tokenCarryPositions: TokenCarryPositionMetricSnapshot[];
+  feeWalletBalances: FeeWalletBalanceMetricSnapshot[];
+  errors: ProtocolMetricsSnapshotError[];
+}
+
+export interface ProtocolMetricsSnapshotError {
+  scope: "kamino_position_rate" | "lending_position_inspect";
+  token: Address;
+  lendingPositionIndex: number;
+  message: string;
+}
+
+export interface BuildProtocolMetricsSnapshotOptions {
+  timestamp?: number;
+  includeInactive?: boolean;
+  tokens?: LYCToken[];
+  yieldingBanks?: LYCYieldingBank[];
+}
+
+export function protocolMetricPartitionKey(metric: ProtocolMetricSnapshotRow): string {
+  switch (metric.entityType) {
+    case "token":
+      return `token#${metric.mint}`;
+    case "yielding_bank":
+      return `yielding_bank#${metric.bank}`;
+    case "yielding_bank_asset":
+      return `yielding_bank_asset#${metric.bank}#${metric.mint}`;
+    case "kamino_position_rate":
+      return `kamino_position#${metric.mint}#${metric.lendingPositionIndex}`;
+    case "token_lending_position":
+      return `token_lending_position#${metric.mint}#${metric.lendingPositionIndex}`;
+    case "token_carry_position":
+      return `token_carry_position#${metric.mint}#${metric.carryPositionIndex}`;
+    case "fee_wallet_balance":
+      return `fee_wallet#${metric.wallet}#${metric.mint}`;
+    case "protocol_manifest":
+      return PROTOCOL_MANIFEST_PK;
+  }
+}
+
+export function buildProtocolManifestSnapshot(
+  snapshot: ProtocolMetricsSnapshot
+): ProtocolManifestSnapshot {
+  return {
+    entityType: "protocol_manifest",
+    tokenMints: snapshot.tokens.map((token) => token.mint),
+    bankAddresses: snapshot.yieldingBanks.map((bank) => bank.bank),
+    kaminoPositions: snapshot.kaminoPositionRates.map((rate) => ({
+      mint: rate.mint,
+      lendingPositionIndex: rate.lendingPositionIndex,
+    })),
+    yieldingBankAssets: snapshot.yieldingBankAssets.map((asset) => ({
+      bank: asset.bank,
+      mint: asset.mint,
+    })),
+    tokenLendingPositions: snapshot.tokenLendingPositions.map((position) => ({
+      mint: position.mint,
+      lendingPositionIndex: position.lendingPositionIndex,
+    })),
+    tokenCarryPositions: snapshot.tokenCarryPositions.map((position) => ({
+      mint: position.mint,
+      carryPositionIndex: position.carryPositionIndex,
+    })),
+    feeWalletBalances: snapshot.feeWalletBalances.map((balance) => ({
+      wallet: balance.wallet,
+      mint: balance.mint,
+    })),
+    errors: snapshot.errors,
+  };
+}
+
+export function flattenProtocolMetricsSnapshot(
+  snapshot: ProtocolMetricsSnapshot
+): ProtocolMetricSnapshotRow[] {
+  return [
+    ...snapshot.tokens,
+    ...snapshot.yieldingBanks,
+    ...snapshot.yieldingBankAssets,
+    ...snapshot.kaminoPositionRates,
+    ...snapshot.tokenLendingPositions,
+    ...snapshot.tokenCarryPositions,
+    ...snapshot.feeWalletBalances,
+    buildProtocolManifestSnapshot(snapshot),
+  ];
+}
+
+/** Dynamo item shape written by {@link buildProtocolMetricDynamoItems}. */
+export interface ProtocolMetricDynamoItem {
+  pk: string;
+  timestamp: number;
+  entityType: ProtocolMetricEntityType;
+  metrics: ProtocolMetricSnapshotRow;
+  ttl?: number;
+}
+
+export function toProtocolMetricDynamoItem(
+  metric: ProtocolMetricSnapshotRow,
+  hourTimestamp: number,
+  ttl?: number
+): ProtocolMetricDynamoItem {
+  return {
+    pk: protocolMetricPartitionKey(metric),
+    timestamp: hourTimestamp,
+    entityType: metric.entityType,
+    metrics: metric,
+    ttl,
+  };
+}
+
+export interface BuildProtocolMetricDynamoItemsOptions extends BuildProtocolMetricsSnapshotOptions {
+  hourTimestamp: number;
+  ttl?: number;
+}
+
+export interface BuildProtocolMetricDynamoItemsResult {
+  items: ProtocolMetricDynamoItem[];
+  errors: ProtocolMetricsSnapshotError[];
+}
+
+/** Builds on-chain snapshot rows and maps them to Dynamo put payloads. */
+export async function buildProtocolMetricDynamoItems(
+  client: LongYieldCarryClient,
+  opts: BuildProtocolMetricDynamoItemsOptions
+): Promise<BuildProtocolMetricDynamoItemsResult> {
+  const snapshot = await buildProtocolMetricsSnapshot(client, {
+    ...opts,
+    timestamp: opts.hourTimestamp,
+  });
+
+  const items = flattenProtocolMetricsSnapshot(snapshot).map((row) =>
+    toProtocolMetricDynamoItem(row, opts.hourTimestamp, opts.ttl)
+  );
+
+  return { items, errors: snapshot.errors };
+}
+
+export async function buildProtocolMetricsSnapshot(
+  client: LongYieldCarryClient,
+  opts: BuildProtocolMetricsSnapshotOptions = {}
+): Promise<ProtocolMetricsSnapshot> {
+  const timestamp = opts.timestamp ?? Math.floor(Date.now() / 1000);
+  const { tokens, yieldingBanks } =
+    opts.tokens && opts.yieldingBanks
+      ? { tokens: opts.tokens, yieldingBanks: opts.yieldingBanks }
+      : await client.account.fetchAllTokensAndYieldingBanks();
+
+  const filteredTokens = opts.includeInactive ? tokens : tokens.filter((token) => token.isActive);
+  const filteredBanks = opts.includeInactive
+    ? yieldingBanks
+    : yieldingBanks.filter((bank) => bank.isActive);
+
+  const tokenSnapshots = filteredTokens.map((token) =>
+    buildTokenMetricSnapshot(token, filteredBanks, timestamp)
+  );
+  const bankSnapshots = filteredBanks.map(buildYieldingBankMetricSnapshot);
+  const assetSnapshots = filteredBanks.flatMap(buildYieldingBankAssetMetricSnapshots);
+  const lendingPositionResults = await Promise.all(
+    filteredTokens.map((token) =>
+      buildTokenLendingPositionMetricSnapshotsAsync(client, token, filteredBanks)
+    )
+  );
+  const lendingPositionSnapshots = lendingPositionResults.flatMap((result) => result.snapshots);
+  // Kamino rate rows use `usedLendingPositions` (collateral > 0) while lending position
+  // snapshots use `activeLendingPositions` (all configured slots). Zero-collateral slots
+  // can still appear in lending rows; Kamino rate rows and stale-slot alerts handle that.
+  const { rates, errors } = await buildKaminoPositionRateSnapshots(client, filteredTokens);
+  const carryPositionSnapshots = filteredTokens.flatMap((token) =>
+    buildTokenCarryPositionMetricSnapshots(token, filteredBanks)
+  );
+  const feeWalletBalances = await buildFeeWalletBalanceSnapshots(client, filteredTokens);
+
+  return {
+    timestamp,
+    tokens: tokenSnapshots,
+    yieldingBanks: bankSnapshots,
+    yieldingBankAssets: assetSnapshots,
+    kaminoPositionRates: rates,
+    tokenLendingPositions: lendingPositionSnapshots,
+    tokenCarryPositions: carryPositionSnapshots,
+    feeWalletBalances,
+    errors: [...errors, ...lendingPositionResults.flatMap((result) => result.errors)],
+  };
+}
+
+/**
+ * Snapshots the protocol fee wallet's ATA balances for every token's
+ * collateral mint (cumulative performance fees) and yToken mint (cumulative
+ * collected mint/burn fees). Collateral mints shared by multiple tokens are
+ * deduped — the balance is per mint, not per token. RPC failures skip the
+ * row rather than failing the whole snapshot; the balance reappears next hour.
+ */
+type FeeWalletTarget = {
+  kind: "collateral" | "ytoken";
+  symbol: string;
+  decimals: number;
+  priceUsd: number;
+  tokenProgram: Address;
+};
+
+function resolveFeeWalletTokenProgram(tp: AnchorTokenProgram | undefined): Address {
+  if (tp == null) {
+    return TOKEN_PROGRAM_ADDRESS;
+  }
+  return resolveTokenProgram(tp);
+}
+
+/** Read an SPL or Token-2022 ATA balance using the mint's token program. */
+async function fetchFeeWalletTokenAmountRaw(
+  rpc: LongYieldCarryClient["rpc"],
+  ata: Address,
+  tokenProgram: Address
+): Promise<bigint> {
+  const account =
+    tokenProgram === TOKEN_2022_PROGRAM_ADDRESS
+      ? await fetchMaybeToken2022(rpc, ata)
+      : await fetchMaybeToken(rpc, ata);
+  return account.exists ? account.data.amount : 0n;
+}
+
+export async function buildFeeWalletBalanceSnapshots(
+  client: LongYieldCarryClient,
+  tokens: LYCToken[]
+): Promise<FeeWalletBalanceMetricSnapshot[]> {
+  const wallet = PROTOCOL_FEE_WALLET[client.environment];
+  const targets = new Map<Address, FeeWalletTarget>();
+
+  for (const token of tokens) {
+    const collateralPriceUsd = toUiAmount(
+      token.data.collateral.price,
+      token.data.collateral.decimals
+    );
+    const collateralTokenProgram = resolveFeeWalletTokenProgram(token.data.collateral.tokenProgram);
+    if (!targets.has(token.collateralMint)) {
+      targets.set(token.collateralMint, {
+        kind: "collateral",
+        symbol: mintSymbol(token.collateralMint),
+        decimals: token.data.collateral.decimals,
+        priceUsd: collateralPriceUsd,
+        tokenProgram: collateralTokenProgram,
+      });
+    }
+    targets.set(token.mint, {
+      kind: "ytoken",
+      symbol: `y${mintSymbol(token.collateralMint)}`,
+      decimals: token.decimals,
+      priceUsd: token.price * collateralPriceUsd,
+      tokenProgram: resolveFeeWalletTokenProgram(token.data.config.tokenProgram),
+    });
+  }
+
+  const snapshots = await Promise.all(
+    [...targets.entries()].map(
+      async ([mint, target]): Promise<FeeWalletBalanceMetricSnapshot | null> => {
+        try {
+          const ata = await getAtaAddress(mint, wallet, target.tokenProgram);
+          const amountRaw = await fetchFeeWalletTokenAmountRaw(
+            client.rpc,
+            ata,
+            target.tokenProgram
+          );
+          const amountUi = toUiAmount(amountRaw, target.decimals);
+          return {
+            entityType: "fee_wallet_balance",
+            wallet,
+            mint,
+            symbol: target.symbol,
+            kind: target.kind,
+            decimals: target.decimals,
+            amountRaw: amountRaw.toString(),
+            amountUi,
+            priceUsd: target.priceUsd,
+            valueUsd: amountUi * target.priceUsd,
+          };
+        } catch {
+          return null;
+        }
+      }
+    )
+  );
+
+  return snapshots.filter((row): row is FeeWalletBalanceMetricSnapshot => row !== null);
+}
+
+export function buildTokenMetricSnapshot(
+  token: LYCToken,
+  yieldingBanks: LYCYieldingBank[] = [],
+  nowTs = Math.floor(Date.now() / 1000)
+): TokenMetricSnapshot {
+  const carryTvlUsdRaw = token.data.debtCarry
+    .filter(
+      (carry) =>
+        !carry.yieldingBaseMint.equals(PublicKey.default) && toBigInt(carry.shares) > BigInt(0)
+    )
+    .reduce((sum, carry) => sum + toBigInt(carry.tvlUsd), 0n);
+  const debtUsdRaw = token.activeLendingPositions.reduce(
+    (sum, { data }) => sum + toBigInt(data.accounting.debt.tvlUsd),
+    0n
+  );
+  const netYieldUsdRaw = collectableNetYieldUsd(carryTvlUsdRaw, debtUsdRaw);
+  const collateralPriceUsd = toUiAmount(
+    token.data.collateral.price,
+    token.data.collateral.decimals
+  );
+  const feeDripMetrics = calculateFeeDripMetrics({
+    currentPriceRaw: toBigInt(token.data.accounting.price),
+    apyReferencePriceRaw: toBigInt(token.data.feeDrip.apyReferencePrice),
+    apyReferenceTs: toBigInt(token.data.feeDrip.apyReferenceTs),
+    currentPriceTs: BigInt(token.data.accounting.lastRefreshedTs.toNumber()),
+    totalSupplyRaw: toBigInt(token.data.accounting.totalSupply),
+    tokenDecimals: token.decimals,
+    undrippedFeeCollateralRaw: toBigInt(token.data.feeDrip.undrippedFeeCollateral),
+    feeDripMaxApyBps: token.data.fees.feeDripMaxApyBps,
+    feeDripDurationSecs: toBigInt(token.data.fees.feeDripDurationSecs),
+    dripEndTs: toBigInt(token.data.feeDrip.dripEndTs),
+    nowTs: BigInt(nowTs),
+  });
+
+  return {
+    entityType: "token",
+    token: token.address,
+    mint: token.mint,
+    collateralMint: token.collateralMint,
+    isActive: token.isActive,
+    priceCollateral: token.price,
+    collateralPriceUsd,
+    priceUsd: token.price * collateralPriceUsd,
+    totalSupply: token.totalSupply,
+    tvlUsdRaw: toBigInt(token.data.accounting.tvlUsd).toString(),
+    tvlUsd: toUiAmount(token.data.accounting.tvlUsd, TVL_USD_DECIMAL_PLACES),
+    carryTvlUsdRaw: carryTvlUsdRaw.toString(),
+    carryTvlUsd: toUiAmount(carryTvlUsdRaw, TVL_USD_DECIMAL_PLACES),
+    debtUsdRaw: debtUsdRaw.toString(),
+    debtUsd: toUiAmount(debtUsdRaw, TVL_USD_DECIMAL_PLACES),
+    netYieldUsdRaw: netYieldUsdRaw.toString(),
+    netYieldUsd: toUiAmount(netYieldUsdRaw, TVL_USD_DECIMAL_PLACES),
+    pendingProtocolFeesRaw: toBigInt(token.data.accounting.pendingProtocolFees).toString(),
+    pendingProtocolFeesUi: toUiAmount(token.data.accounting.pendingProtocolFees, token.decimals),
+    pendingCuratorFeesRaw: toBigInt(token.data.accounting.pendingCuratorFees).toString(),
+    pendingCuratorFeesUi: toUiAmount(token.data.accounting.pendingCuratorFees, token.decimals),
+    performanceFeeBps: token.data.fees.performanceFeeBps,
+    mintingFeeBps: token.data.fees.mintingFeeBps,
+    burningFeeBps: token.data.fees.burningFeeBps,
+    protocolMintBurnPctBps: token.data.fees.protocolMintBurnPctBps,
+    curatorMintBurnPctBps: token.data.fees.curatorMintBurnPctBps,
+    curatorPerfPctBps: token.data.fees.curatorPerfPctBps,
+    feeDripMaxApyBps: token.data.fees.feeDripMaxApyBps,
+    feeDripCurrentApyBps: feeDripMetrics.currentApyBps,
+    undrippedFeeCollateralUi: toUiAmount(
+      token.data.feeDrip.undrippedFeeCollateral,
+      token.data.collateral.decimals
+    ),
+    feeDripAbsorptionEtaSeconds: feeDripMetrics.absorptionEtaSeconds,
+    feeDripAbsorptionStatus: feeDripMetrics.absorptionStatus,
+    firstMintTs: token.data.accounting.firstMintTs.toNumber(),
+    collateralOracle: fromWeb3Pk(token.data.collateral.oracle),
+    collateralLastRefreshedTs: token.data.collateral.lastRefreshedTs.toNumber(),
+    unlentCollateralUi: toUiAmount(
+      token.data.collateral.unlentAmount,
+      token.data.collateral.decimals
+    ),
+    lastRefreshedTs: token.data.accounting.lastRefreshedTs.toNumber(),
+  };
+}
+
+export function buildYieldingBankMetricSnapshot(bank: LYCYieldingBank): YieldingBankMetricSnapshot {
+  const defaultRedemptionMint =
+    bank.defaultRedemptionMint !== PublicKey.default.toBase58()
+      ? bank.defaultRedemptionMint
+      : undefined;
+
+  const externalYieldingPositions = bank.externalYieldingPositions
+    .map((position) => ({
+      platform: lendingPlatformToEnum(position.lendingPlatform),
+      pool: fromWeb3Pk(position.pool),
+      tvlRaw: toBigInt(position.tvl),
+      tvlUsd: toUiAmount(position.tvl, TVL_USD_DECIMAL_PLACES),
+    }))
+    .filter((position) => position.platform !== LendingPlatform.None)
+    .map((position) => ({
+      platform: position.platform,
+      pool: position.pool,
+      tvlUsdRaw: position.tvlRaw.toString(),
+      tvlUsd: position.tvlUsd,
+    }));
+
+  return {
+    entityType: "yielding_bank",
+    bank: bank.address,
+    id: bank.id,
+    baseMint: bank.baseMint,
+    baseSymbol: mintSymbol(bank.baseMint),
+    curator: fromWeb3Pk(bank.data.roles.curator),
+    isActive: bank.isActive,
+    circuitBreaker: bank.circuitBreaker,
+    defaultRedemptionMint,
+    externalYieldingPositions,
+    sharePriceRaw: toBigInt(bank.data.accounting.sharePrice).toString(),
+    sharePriceUsd: bank.sharePrice,
+    totalSharesRaw: toBigInt(bank.data.accounting.totalShares).toString(),
+    totalShares: bank.totalShares,
+    tvlUsdRaw: toBigInt(bank.data.accounting.tvl).toString(),
+    tvlUsd: toUiAmount(bank.data.accounting.tvl, TVL_USD_DECIMAL_PLACES),
+    lastRefreshedTs: bank.data.accounting.lastRefreshedTs.toNumber(),
+    lastRebalancedTs: bank.data.accounting.lastRebalancedTs.toNumber(),
+  };
+}
+
+export function buildTokenLendingPositionMetricSnapshots(
+  token: LYCToken,
+  yieldingBanks: LYCYieldingBank[] = []
+): TokenLendingPositionMetricSnapshot[] {
+  const collateralSymbol = mintSymbol(token.collateralMint);
+  const collateralDecimals = token.data.collateral.decimals;
+  const collateralPriceUsd = toUiAmount(
+    token.data.collateral.price,
+    token.data.collateral.decimals
+  );
+  return token.activeLendingPositions.map(({ index, data: position }) => {
+    const platform = lendingPlatformToEnum(position.platform);
+    const collateralAmountUi = toUiAmount(position.accounting.collateral, collateralDecimals);
+    const debtMint = fromWeb3Pk(position.accounting.debt.mint);
+    const debtTvlUsdRaw = toBigInt(position.accounting.debt.tvlUsd);
+
+    return {
+      entityType: "token_lending_position",
+      token: token.address,
+      mint: token.mint,
+      lendingPositionIndex: index,
+      platform,
+      withdrawPending: podBoolToNumber(position.withdrawPending) !== 0,
+      pool: fromWeb3Pk(position.pool),
+      userAccount: fromWeb3Pk(position.protocolUserAcc),
+      collateralAmountRaw: toBigInt(position.accounting.collateral).toString(),
+      collateralAmountUi,
+      collateralSymbol,
+      collateralUsd: collateralAmountUi * collateralPriceUsd,
+      debtAmountRaw: toBigInt(position.accounting.debt.amount).toString(),
+      debtAmountUi: toUiAmount(position.accounting.debt.amount, position.accounting.debt.decimals),
+      debtTvlUsdRaw: debtTvlUsdRaw.toString(),
+      debtTvlUsd: toUiAmount(debtTvlUsdRaw, TVL_USD_DECIMAL_PLACES),
+      debtMint,
+      debtSymbol: mintSymbol(debtMint),
+      debtPriceUsd: 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,
+    };
+  });
+}
+
+export async function buildTokenLendingPositionMetricSnapshotsAsync(
+  client: LongYieldCarryClient,
+  token: LYCToken,
+  yieldingBanks: LYCYieldingBank[] = []
+): Promise<{
+  snapshots: TokenLendingPositionMetricSnapshot[];
+  errors: ProtocolMetricsSnapshotError[];
+}> {
+  const baseSnapshots = buildTokenLendingPositionMetricSnapshots(token, yieldingBanks);
+  const kaminoData = client.getLendingPlatformClientByPlatform(LendingPlatform.Kamino).data;
+  const errors: ProtocolMetricsSnapshotError[] = [];
+
+  const snapshots = await Promise.all(
+    baseSnapshots.map(async (snapshot) => {
+      if (snapshot.platform !== LendingPlatform.Kamino) {
+        return snapshot;
+      }
+
+      const position = token.activeLendingPositions.find(
+        (row) => row.index === snapshot.lendingPositionIndex
+      )?.data;
+      if (!position) {
+        return snapshot;
+      }
+
+      try {
+        const { LycLendingPositionManager } = await import("../services/carry");
+        const manager = await LycLendingPositionManager.create(kaminoData, position);
+        const inspectMetrics = await manager.getInspectMetrics();
+        const inspect = serializeLendingPositionInspectMetrics(inspectMetrics);
+        return inspect ? { ...snapshot, inspect } : snapshot;
+      } catch (err) {
+        // The base snapshot is still valid without inspect enrichment, but the
+        // failure must be recorded — silently missing Util RT/EMA cells have
+        // hidden real bugs (e.g. trigger-band math throwing on >100% bands).
+        errors.push({
+          scope: "lending_position_inspect",
+          token: token.address,
+          lendingPositionIndex: snapshot.lendingPositionIndex,
+          message: err instanceof Error ? err.message : String(err),
+        });
+        return snapshot;
+      }
+    })
+  );
+
+  return { snapshots, errors };
+}
+
+export function serializeLendingPositionInspectMetrics(
+  metrics: LendingPositionInspectMetrics | null | undefined
+): LendingPositionInspectMetricSnapshot | undefined {
+  if (!metrics) {
+    return undefined;
+  }
+
+  return {
+    utilizationRealtimeBps: metrics.utilizationRateBps.realtime,
+    utilizationEmaBps: metrics.utilizationRateBps.ema,
+    lowerTriggerPriceChangePct: metrics.triggerBand.lower?.priceChangePct,
+    upperTriggerPriceChangePct: metrics.triggerBand.upper?.priceChangePct,
+  };
+}
+
+export function kaminoCollateralUsd(token: LYCToken, position: TokenLendingPositionData): number {
+  const collateralAmountUi = toUiAmount(
+    position.accounting.collateral,
+    token.data.collateral.decimals
+  );
+  const collateralPriceUsd = toUiAmount(
+    token.data.collateral.price,
+    token.data.collateral.decimals
+  );
+  return collateralAmountUi * collateralPriceUsd;
+}
+
+export function shouldIncludeKaminoPositionRate(
+  collateralUsd: number,
+  maxCollateralUsdOnToken: number
+): boolean {
+  if (maxCollateralUsdOnToken < MIN_MATERIAL_KAMINO_COLLATERAL_USD) {
+    return true;
+  }
+  return collateralUsd >= MIN_MATERIAL_KAMINO_COLLATERAL_USD;
+}
+
+export function buildTokenCarryPositionMetricSnapshots(
+  token: LYCToken,
+  yieldingBanks: LYCYieldingBank[]
+): TokenCarryPositionMetricSnapshot[] {
+  const snapshots: TokenCarryPositionMetricSnapshot[] = [];
+
+  token.data.debtCarry.forEach((carry, carryPositionIndex) => {
+    if (carry.yieldingBaseMint.equals(PublicKey.default)) {
+      return;
+    }
+
+    const baseMint = fromWeb3Pk(carry.yieldingBaseMint);
+    const resolvedBank = yieldingBanks.find(
+      (bank) => bank.id === carry.yieldingBankId && bank.baseMint === baseMint
+    );
+
+    snapshots.push({
+      entityType: "token_carry_position",
+      token: token.address,
+      mint: token.mint,
+      carryPositionIndex,
+      yieldingBankId: carry.yieldingBankId,
+      yieldingBankAddress: resolvedBank?.address,
+      baseMint,
+      baseSymbol: mintSymbol(baseMint),
+      sharesRaw: toBigInt(carry.shares).toString(),
+      sharesUi: resolvedBank ? toUiAmount(carry.shares, resolvedBank.decimals) : undefined,
+      tvlUsdRaw: toBigInt(carry.tvlUsd).toString(),
+      tvlUsd: toUiAmount(carry.tvlUsd, TVL_USD_DECIMAL_PLACES),
+    });
+  });
+
+  return snapshots;
+}
+
+export function buildYieldingBankAssetMetricSnapshots(
+  bank: LYCYieldingBank
+): YieldingBankAssetMetricSnapshot[] {
+  const snapshots: YieldingBankAssetMetricSnapshot[] = [];
+  if (!bank.data.baseAsset.mint.equals(PublicKey.default)) {
+    snapshots.push(buildYieldingBankAssetMetricSnapshot(bank, bank.data.baseAsset, 0, "base"));
+  }
+
+  bank.data.assets.forEach((asset, index) => {
+    if (asset.mint.equals(PublicKey.default)) return;
+    snapshots.push(buildYieldingBankAssetMetricSnapshot(bank, asset, index + 1, "asset"));
+  });
+
+  return snapshots;
+}
+
+async function buildKaminoPositionRateSnapshots(
+  client: LongYieldCarryClient,
+  tokens: LYCToken[]
+): Promise<{
+  rates: KaminoPositionRateSnapshot[];
+  errors: ProtocolMetricsSnapshotError[];
+}> {
+  const rates: KaminoPositionRateSnapshot[] = [];
+  const errors: ProtocolMetricsSnapshotError[] = [];
+  const kaminoData = client.getLendingPlatformClientByPlatform(LendingPlatform.Kamino).data;
+
+  for (const token of tokens) {
+    const kaminoPositions = token.usedLendingPositions.filter(
+      ({ data: position }) => lendingPlatformToEnum(position.platform) === LendingPlatform.Kamino
+    );
+    const maxCollateralUsd = Math.max(
+      0,
+      ...kaminoPositions.map(({ data: position }) => kaminoCollateralUsd(token, position))
+    );
+
+    for (const { index, data: position } of kaminoPositions) {
+      const collateralUsd = kaminoCollateralUsd(token, position);
+      if (!shouldIncludeKaminoPositionRate(collateralUsd, maxCollateralUsd)) {
+        continue;
+      }
+
+      try {
+        const rate = await buildKaminoPositionRateSnapshot(token, index, position, kaminoData);
+        rates.push(rate);
+      } catch (err) {
+        errors.push({
+          scope: "kamino_position_rate",
+          token: token.address,
+          lendingPositionIndex: index,
+          message: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }
+  }
+
+  return { rates, errors };
+}
+
+async function buildKaminoPositionRateSnapshot(
+  token: LYCToken,
+  lendingPositionIndex: number,
+  position: TokenLendingPositionData,
+  kaminoData: ReturnType<LongYieldCarryClient["getLendingPlatformClientByPlatform"]>["data"]
+): Promise<KaminoPositionRateSnapshot> {
+  const pool = fromWeb3Pk(position.pool);
+  const [collateralReserve, debtReserve] = await Promise.all([
+    kaminoData.fetchReserve(pool, fromWeb3Pk(position.collateralReserve)),
+    kaminoData.fetchReserve(pool, fromWeb3Pk(position.debtReserve)),
+  ]);
+
+  if (!collateralReserve || !debtReserve) {
+    throw new Error("Failed to fetch Kamino reserves");
+  }
+
+  return buildKaminoPositionRateSnapshotFromReserves(
+    token,
+    lendingPositionIndex,
+    position,
+    collateralReserve,
+    debtReserve
+  );
+}
+
+export function buildKaminoPositionRateSnapshotFromReserves(
+  token: LYCToken,
+  lendingPositionIndex: number,
+  position: TokenLendingPositionData,
+  collateralReserve: ReserveBase,
+  debtReserve: ReserveBase
+): KaminoPositionRateSnapshot {
+  const supplyEffectiveApy = collateralReserve.supplyAPY(debtReserve.address);
+  const borrowEffectiveApy = debtReserve.borrowAPY(collateralReserve.address);
+
+  return {
+    entityType: "kamino_position_rate",
+    token: token.address,
+    mint: token.mint,
+    lendingPositionIndex,
+    pool: fromWeb3Pk(position.pool),
+    userAccount: fromWeb3Pk(position.protocolUserAcc),
+    collateralReserve: fromWeb3Pk(position.collateralReserve),
+    debtReserve: fromWeb3Pk(position.debtReserve),
+    collateralMint: collateralReserve.mint.mint,
+    debtMint: debtReserve.mint.mint,
+    supplyBaseApy: collateralReserve.deposits.apy,
+    borrowBaseApy: debtReserve.borrows.apy,
+    supplyEffectiveApy,
+    borrowEffectiveApy,
+    netEffectiveApy: supplyEffectiveApy - borrowEffectiveApy,
+    collateralReserveUtilizationPct: collateralReserve.utilizationRatePct(),
+    debtReserveUtilizationPct: debtReserve.utilizationRatePct(),
+    onChainLtvUtilizationBps: position.accounting.ltvUtilizationRateBps,
+    targetUtilizationRateBps: position.config.targetUtilizationRateBps,
+    maxDeviationAboveTargetUtilBps: position.config.maxDeviationAboveTargetUtilBps,
+    maxDeviationBelowTargetUtilBps: position.config.maxDeviationBelowTargetUtilBps,
+  };
+}
+
+function buildYieldingBankAssetMetricSnapshot(
+  bank: LYCYieldingBank,
+  asset: YieldingBankAccountData["baseAsset"],
+  assetIndex: number,
+  assetKind: "base" | "asset"
+): YieldingBankAssetMetricSnapshot {
+  const amountRaw = toBigInt(asset.amount);
+  const priceRaw = toBigInt(asset.price);
+  const tvlUsdRaw = calculateTvlUsd(amountRaw, priceRaw, asset.decimals);
+
+  return {
+    entityType: "yielding_bank_asset",
+    bank: bank.address,
+    assetIndex,
+    assetKind,
+    mint: fromWeb3Pk(asset.mint),
+    amountRaw: amountRaw.toString(),
+    amountUi: toUiAmount(asset.amount, asset.decimals),
+    decimals: asset.decimals,
+    priceRaw: priceRaw.toString(),
+    priceUsd: toUiAmount(asset.price, asset.decimals),
+    tvlUsdRaw: tvlUsdRaw.toString(),
+    tvlUsd: toUiAmount(tvlUsdRaw, TVL_USD_DECIMAL_PLACES),
+  };
+}