@kestrelfi/lyc-sdk 1.0.1 → 1.0.3

package/src/metrics/protocolMetrics.ts

@@ -1,976 +0,0 @@
-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),
-  };
-}