@kestrelfi/lyc-sdk 1.0.1 → 1.0.3

package/scripts/inspect/format.ts

@@ -1,576 +0,0 @@
-import { BN } from "@anchor-lang/core";
-import type { Address } from "@solana/kit";
-import { type Environment, LendingPlatform, toBigInt } from "common";
-import type {
-  CollateralPriceTriggerLevel,
-  EnrichedTokenSnapshot,
-  EnrichedYieldingBankSnapshot,
-  EnrichedYieldingBankHolding,
-} from "../../src/types/enriched";
-
-const DIVIDER = "─".repeat(72);
-const SECTION_DIVIDER = "  " + "·".repeat(68);
-const HEADER_DIVIDER = "=".repeat(72);
-const LABEL_WIDTH = 24;
-const DIM = "\x1b[2m";
-const BOLD = "\x1b[1m";
-const GREEN = "\x1b[32m";
-const RED = "\x1b[31m";
-const RESET = "\x1b[0m";
-
-export interface FeeWalletBalance {
-  symbol: string;
-  decimals: number;
-  balance: bigint;
-}
-
-function addr(a: Address | string): string {
-  return a.toString();
-}
-
-function bps(raw: number): string {
-  return `${(raw / 100).toFixed(2)}%`;
-}
-
-function statusBadge(isActive: boolean): string {
-  return isActive ? `${GREEN}${BOLD}ACTIVE${RESET}` : `${RED}${BOLD}CIRCUIT BREAKER${RESET}`;
-}
-
-function staleness(lastRefreshedTs: bigint | BN): string {
-  const ts = Number(toBigInt(lastRefreshedTs));
-  if (ts === 0) return "never";
-  const ageSecs = Math.floor(Date.now() / 1000) - ts;
-  if (ageSecs < 60) return `${ageSecs}s ago`;
-  if (ageSecs < 3600) return `${Math.floor(ageSecs / 60)}m ago`;
-  return `${Math.floor(ageSecs / 3600)}h ${Math.floor((ageSecs % 3600) / 60)}m ago`;
-}
-
-function firstMintLabel(ts: bigint): string {
-  if (ts === 0n) return "never";
-  return new Date(Number(ts) * 1000).toISOString() + `  ${dim(staleness(ts))}`;
-}
-
-function durationEstimate(seconds: number): string {
-  if (seconds <= 0) return "next refresh";
-  if (seconds < 3_600) return `~${Math.ceil(seconds / 60)}m`;
-  if (seconds < 86_400) return `~${(seconds / 3_600).toFixed(1)}h`;
-  if (seconds < 365 * 86_400) return `~${(seconds / 86_400).toFixed(1)} days`;
-  return `~${(seconds / (365 * 86_400)).toFixed(1)} years`;
-}
-
-function feeAbsorptionEtaLabel(fees: EnrichedTokenSnapshot["fees"]): string {
-  switch (fees.absorptionStatus) {
-    case "estimated":
-      return fees.absorptionEtaSeconds == null
-        ? "unavailable"
-        : durationEstimate(fees.absorptionEtaSeconds);
-    case "no_fees":
-      return "none outstanding";
-    case "parked":
-      return "parked (drip disabled)";
-    case "apy_saturated":
-      return "no APY headroom at current rate";
-    default:
-      return "unavailable";
-  }
-}
-
-function timelockLabel(isTimelocked: boolean): string {
-  if (isTimelocked) {
-    return "timelock: locked";
-  }
-  return "timelock: unlocked";
-}
-
-function platformLabel(platform: LendingPlatform): string {
-  switch (platform) {
-    case LendingPlatform.Kamino:
-      return "Kamino";
-    case LendingPlatform.Marginfi:
-      return "Marginfi";
-    default:
-      return "None";
-  }
-}
-
-/** Dim secondary detail text so it doesn't compete with the primary numbers. */
-function dim(text: string): string {
-  return `${DIM}${text}${RESET}`;
-}
-
-function bold(text: string): string {
-  return `${BOLD}${text}${RESET}`;
-}
-
-function field(label: string, value: string, indent = 2): string {
-  return `${" ".repeat(indent)}${`${label}:`.padEnd(LABEL_WIDTH)} ${value}`;
-}
-
-function section(label: string): string {
-  return `  ${bold(label)}`;
-}
-
-function usdPriceUi(value: number): string {
-  return (
-    "$" + value.toLocaleString("en-US", { minimumFractionDigits: 2, maximumFractionDigits: 6 })
-  );
-}
-
-function usdUi(value: number): string {
-  return (
-    "$" + value.toLocaleString("en-US", { minimumFractionDigits: 2, maximumFractionDigits: 2 })
-  );
-}
-
-function formatTokenAmountUi(value: bigint, decimals: number): string {
-  const ui = Number(value) / 10 ** decimals;
-  return ui.toLocaleString("en-US", { maximumFractionDigits: decimals });
-}
-
-function formatTriggerMove(
-  trigger: CollateralPriceTriggerLevel | undefined,
-  currentUtilizationRateBps: number | undefined,
-  triggerKind: "increase" | "decrease"
-): string | undefined {
-  if (!trigger) {
-    return "unavailable";
-  }
-
-  const modeLabel = trigger.priceMode === "ema" ? "EMA" : "RT";
-
-  if (currentUtilizationRateBps != null) {
-    const isAlreadyOutOfBounds =
-      triggerKind === "increase"
-        ? currentUtilizationRateBps <= trigger.targetUtilizationRateBps
-        : currentUtilizationRateBps >= trigger.targetUtilizationRateBps;
-    if (isAlreadyOutOfBounds) {
-      return `awaiting ${triggerKind}  ${dim(`| ${modeLabel}`)}`;
-    }
-  }
-
-  const direction = trigger.priceChangePct < 0 ? "fall" : "rise";
-  const move = Math.abs(trigger.priceChangePct).toFixed(2) + "%";
-
-  const description =
-    trigger.priceChangePct === 0
-      ? `at ${usdPriceUi(trigger.triggerCollateralPrice)} now`
-      : `${direction} ${move} to ${usdPriceUi(trigger.triggerCollateralPrice)}`;
-
-  return `${description}  ${dim(`| ${modeLabel}`)}`;
-}
-
-// ---------------------------------------------------------------------------
-// Header
-// ---------------------------------------------------------------------------
-
-export function formatHeader(env: Environment, tokenCount: number, bankCount: number): string {
-  return [
-    "",
-    HEADER_DIVIDER,
-    `  ${bold("LYC Inspect")}`,
-    field("Environment", env),
-    field("Snapshot", new Date().toISOString()),
-    field("Coverage", `${tokenCount} token(s) | ${bankCount} yielding bank(s)`),
-    HEADER_DIVIDER,
-  ].join("\n");
-}
-
-export function formatFooter(totalTvlUsd: number): string {
-  return ["", HEADER_DIVIDER, field("Total TVL", usdUi(totalTvlUsd)), HEADER_DIVIDER].join("\n");
-}
-
-// ---------------------------------------------------------------------------
-// Yielding Bank
-// ---------------------------------------------------------------------------
-
-export function formatYieldingBankSnapshot(
-  bank: EnrichedYieldingBankSnapshot,
-  allTokens?: EnrichedTokenSnapshot[]
-): string {
-  const lines: string[] = [""];
-
-  lines.push(`${bold("Yielding Bank")}  ${bank.baseSymbol}  ${statusBadge(bank.isActive)}`);
-  lines.push(DIVIDER);
-  lines.push(field("Address", addr(bank.address)));
-  lines.push(field("Curator", addr(bank.curator)));
-  lines.push(field("Base mint", bank.baseSymbol));
-
-  // -- Core accounting --
-  lines.push(field("TVL", usdUi(bank.tvlUsd)));
-  lines.push(field("Share decimals", bank.decimals.toString()));
-  lines.push(field("Share price", usdPriceUi(bank.sharePrice)));
-  lines.push(field("Total shares", bank.totalShares.toLocaleString("en-US")));
-
-  if (allTokens) {
-    const accountedRaw = allTokens
-      .flatMap((t) => t.carryPositions)
-      .filter((cp) => cp.yieldingBankAddress === bank.address)
-      .reduce((sum, cp) => sum + cp.sharesRaw, 0n);
-    const accountedUi = Number(accountedRaw) / 10 ** bank.decimals;
-    const diff = accountedUi - bank.totalShares;
-    const diffStr =
-      diff === 0
-        ? `${GREEN}${BOLD}✓ exact${RESET}`
-        : `${RED}${BOLD}MISMATCH ${diff > 0 ? "+" : ""}${diff.toLocaleString("en-US")}${RESET}`;
-    lines.push(
-      field(
-        "Shares accounted",
-        `${accountedUi.toLocaleString("en-US")}  ${dim(`(${accountedRaw.toString()} raw)`)}  ${diffStr}`
-      )
-    );
-  }
-
-  lines.push(field("Last refresh", staleness(bank.lastRefreshedTs)));
-  lines.push(field("Last rebalance", staleness(bank.lastRebalancedTs)));
-  lines.push(field("Timelock", timelockLabel(bank.isTimelocked)));
-
-  // -- Redemption mint --
-  if (bank.defaultRedemptionMint && bank.defaultRedemptionSymbol) {
-    lines.push(
-      field(
-        "Redemption mint",
-        `${bank.defaultRedemptionSymbol}  ${dim(`| ${addr(bank.defaultRedemptionMint)}`)}`
-      )
-    );
-  }
-
-  // -- Asset holdings --
-  lines.push(SECTION_DIVIDER);
-  lines.push(section("Holdings"));
-  for (const holding of bank.holdings) {
-    lines.push(
-      field(
-        `[${holding.kind}] ${holding.symbol}`,
-        `${holding.amountUi.toLocaleString("en-US", { maximumFractionDigits: holding.decimals })} ${
-          holding.symbol
-        }`,
-        4
-      )
-    );
-    lines.push(
-      field(
-        "Details",
-        dim(`price: ${usdPriceUi(holding.priceUi)} | ${timelockLabel(holding.isTimelocked)}`),
-        4
-      )
-    );
-  }
-
-  // -- External yielding positions --
-  for (const ext of bank.externalYieldingPositions) {
-    lines.push(SECTION_DIVIDER);
-    lines.push(section(`External ${platformLabel(ext.platform)}`));
-    lines.push(field("TVL", usdUi(ext.tvlUsd), 4));
-    lines.push(field("Pool", dim(addr(ext.pool)), 4));
-    lines.push(field("Timelock", dim(timelockLabel(ext.isTimelocked)), 4));
-  }
-
-  return lines.join("\n");
-}
-
-// ---------------------------------------------------------------------------
-// Token
-// ---------------------------------------------------------------------------
-
-export function formatTokenSnapshot(
-  token: EnrichedTokenSnapshot,
-  enrichedBanks?: EnrichedYieldingBankSnapshot[]
-): string {
-  const lines: string[] = [""];
-  const collSymbol = token.collateral.symbol;
-  const collDecimals = token.collateral.decimals;
-
-  lines.push(`${bold("Token")}  ${collSymbol}  ${statusBadge(token.isActive)}`);
-  lines.push(DIVIDER);
-  lines.push(field("Address", addr(token.address)));
-  lines.push(field("Curator", addr(token.curator)));
-
-  // -- Mint & config --
-  lines.push(field("Mint", `${addr(token.mint)}  ${dim(`| decimals: ${token.decimals}`)}`));
-
-  // -- Accounting --
-  lines.push(field("Price", `${token.price.toFixed(6)} ${collSymbol}`));
-  lines.push(field("Total supply", token.totalSupply.toLocaleString("en-US")));
-  lines.push(field("TVL", usdUi(token.tvlUsd)));
-  lines.push(field("Last refresh", staleness(token.lastRefreshedTs)));
-  lines.push(field("First mint", firstMintLabel(token.firstMintTs)));
-
-  // -- Collateral --
-  lines.push(SECTION_DIVIDER);
-  lines.push(section("Collateral"));
-  lines.push(
-    field(
-      "Unlent",
-      `${token.collateral.unlentAmountUi.toLocaleString("en-US", {
-        maximumFractionDigits: collDecimals,
-      })} ${collSymbol}`,
-      4
-    )
-  );
-  lines.push(
-    field(
-      "Pending unwind residual",
-      `${token.collateral.pendingUnwindResidualUi.toLocaleString("en-US", {
-        maximumFractionDigits: collDecimals,
-      })} ${collSymbol}`,
-      4
-    )
-  );
-  lines.push(
-    field(
-      "Oracle price",
-      `RT ${usdPriceUi(token.collateral.oraclePriceRealtimeUi)} | EMA ${usdPriceUi(
-        token.collateral.oraclePriceEmaUi
-      )}  ${dim(`| on-chain ${usdPriceUi(token.collateral.oraclePriceOnChainUi)}`)}`,
-      4
-    )
-  );
-  lines.push(field("Collateral oracle", dim(addr(token.collateral.oracle)), 4));
-  lines.push(
-    field(
-      "Secondary oracle",
-      token.collateral.secondaryOracle ? dim(addr(token.collateral.secondaryOracle)) : "none",
-      4
-    )
-  );
-  lines.push(field("Price refresh", staleness(token.collateral.lastRefreshedTs), 4));
-
-  // -- Lending positions --
-  for (const lp of token.lendingPositions) {
-    if (lp.collateralAmountUi === 0 && lp.debtAmountUi === 0) continue;
-    const liveUtilizationRateBps =
-      lp.inspectMetrics?.utilizationRateBps.realtime ?? lp.onChainUtilizationRateBps;
-    const emaUtilizationRateBps = lp.inspectMetrics?.utilizationRateBps.ema;
-    const positionHeadline = [
-      `Lending[${lp.index}]`,
-      `platform: ${platformLabel(lp.platform)}`,
-      `${lp.collateralSymbol}/${lp.debtSymbol}`,
-      lp.withdrawPending ? "WARN WITHDRAW PENDING" : undefined,
-    ]
-      .filter((part): part is string => part !== undefined)
-      .join(" | ");
-
-    lines.push(SECTION_DIVIDER);
-    lines.push(section(positionHeadline));
-    const collateralUsd = lp.collateralAmountUi * token.collateral.oraclePriceRealtimeUi;
-    lines.push(
-      field(
-        "Collateral",
-        `${lp.collateralAmountUi.toLocaleString("en-US", {
-          maximumFractionDigits: lp.collateralDecimals,
-        })} ${lp.collateralSymbol}  ${dim(`(${usdUi(collateralUsd)})`)}`,
-        4
-      )
-    );
-    lines.push(
-      field(
-        "Debt",
-        `${lp.debtAmountUi.toLocaleString("en-US", {
-          maximumFractionDigits: lp.debtDecimals,
-        })} ${lp.debtSymbol}  ${dim(`(${usdUi(lp.debtTvlUsd)})`)}`,
-        4
-      )
-    );
-    lines.push(field("Debt price", usdPriceUi(lp.debtPriceUi), 4));
-    lines.push(
-      field(
-        "Utilization",
-        `${bps(liveUtilizationRateBps)} RT` +
-          (emaUtilizationRateBps != null ? ` | ${bps(emaUtilizationRateBps)} EMA` : "") +
-          ` | ${bps(lp.onChainUtilizationRateBps)} on-chain`,
-        4
-      )
-    );
-    lines.push(
-      field(
-        "Target band",
-        dim(
-          `target ${bps(lp.targetUtilizationRateBps)} | ` +
-            `-${bps(lp.maxDeviationBelowTargetUtilBps)} / +${bps(
-              lp.maxDeviationAboveTargetUtilBps
-            )}`
-        ),
-        4
-      )
-    );
-    const increaseTriggerLine = formatTriggerMove(
-      lp.inspectMetrics?.triggerBand.lower,
-      emaUtilizationRateBps,
-      "increase"
-    );
-    if (increaseTriggerLine) {
-      lines.push(field("Increase trigger", increaseTriggerLine, 4));
-    }
-    const decreaseTriggerLine = formatTriggerMove(
-      lp.inspectMetrics?.triggerBand.upper,
-      liveUtilizationRateBps,
-      "decrease"
-    );
-    if (decreaseTriggerLine) {
-      lines.push(field("Decrease trigger", decreaseTriggerLine, 4));
-    }
-    lines.push(field("Last rebalance", staleness(lp.lastRebalancedTs), 4));
-    lines.push(field("Pool", dim(addr(lp.pool)), 4));
-    lines.push(field("User account", dim(addr(lp.userAccount)), 4));
-  }
-
-  // -- Carry positions --
-  for (const carry of token.carryPositions) {
-    if (carry.sharesRaw === 0n && carry.tvlUsd === 0) continue;
-    lines.push(SECTION_DIVIDER);
-    const sharesUi =
-      carry.sharesUi != null && carry.shareDecimals != null
-        ? carry.sharesUi.toLocaleString("en-US", { maximumFractionDigits: carry.shareDecimals })
-        : carry.sharesRaw.toString();
-
-    lines.push(
-      section(`Carry #${carry.index} | bank ${carry.yieldingBankId} | ${carry.baseSymbol}`)
-    );
-    if (carry.yieldingBankAddress) {
-      lines.push(field("Bank address", dim(addr(carry.yieldingBankAddress)), 4));
-    }
-    lines.push(field("Shares", `${sharesUi}  ${dim(`(${carry.sharesRaw.toString()} raw)`)}`, 4));
-    lines.push(field("TVL", usdUi(carry.tvlUsd), 4));
-  }
-
-  if (token.carryPositions.length > 0) {
-    lines.push(SECTION_DIVIDER);
-    lines.push(section("Carry summary"));
-    lines.push(field("Total carry TVL", usdUi(token.carrySummary.totalCarryTvlUsd), 4));
-    lines.push(field("Total debt USD", usdUi(token.carrySummary.totalDebtUsd), 4));
-    lines.push(field("Net yield", usdUi(token.carrySummary.netYieldUsd), 4));
-    lines.push(
-      field(
-        "Interest to collect",
-        token.hasInterestToCollect
-          ? `${GREEN}yes${RESET}  ${dim(`(${usdUi(token.carrySummary.netYieldUsd)} collectable)`)}`
-          : dim("no"),
-        4
-      )
-    );
-
-    for (const lp of token.lendingPositions) {
-      if (lp.debtAmountUi === 0) continue;
-      lines.push(field(`Debt price [${lp.index}] ${lp.debtSymbol}`, usdPriceUi(lp.debtPriceUi), 4));
-    }
-
-    if (enrichedBanks) {
-      for (const carry of token.carryPositions) {
-        if (!carry.yieldingBankAddress) continue;
-        const bank = enrichedBanks.find((b) => b.address === carry.yieldingBankAddress);
-        if (!bank || bank.holdings.length === 0) continue;
-        const largest = bank.holdings.reduce<EnrichedYieldingBankHolding>(
-          (best, h) => (h.amountUi * h.priceUi > best.amountUi * best.priceUi ? h : best),
-          bank.holdings[0]
-        );
-        lines.push(
-          field(
-            `Bank[${carry.yieldingBankId}] top holding`,
-            `${largest.symbol}  ${dim(`price: ${usdPriceUi(largest.priceUi)}`)}`,
-            4
-          )
-        );
-      }
-    }
-  }
-
-  // -- Fees --
-  lines.push(SECTION_DIVIDER);
-  lines.push(section("Fees"));
-  lines.push(field("Minting", bps(token.fees.mintingFeeBps), 4));
-  lines.push(field("Burning", bps(token.fees.burningFeeBps), 4));
-  lines.push(field("Performance", bps(token.fees.performanceFeeBps), 4));
-  lines.push(field("Protocol mint/burn pct", bps(token.fees.protocolMintBurnPctBps), 4));
-  lines.push(field("Curator mint/burn pct", bps(token.fees.curatorMintBurnPctBps), 4));
-  lines.push(field("Holder mint/burn pct", bps(token.fees.holderMintBurnPctBps), 4));
-  lines.push(field("Curator perf pct", bps(token.fees.curatorPerfPctBps), 4));
-  lines.push(field("Fee drip max APY", bps(token.fees.feeDripMaxApyBps), 4));
-  lines.push(
-    field(
-      "Current fee-window APY",
-      token.fees.currentApyBps == null ? "unavailable" : bps(token.fees.currentApyBps),
-      4
-    )
-  );
-  lines.push(
-    field(
-      "Fee drip duration",
-      `${(Number(token.fees.feeDripDurationSecs) / 86_400).toLocaleString("en-US", {
-        maximumFractionDigits: 2,
-      })} days`,
-      4
-    )
-  );
-  lines.push(
-    field(
-      "Unabsorbed fee buffer",
-      `${token.fees.undrippedFeeCollateralUi.toLocaleString("en-US", {
-        maximumFractionDigits: collDecimals,
-      })} ${collSymbol}  ${dim(`(${token.fees.undrippedFeeCollateralRaw.toString()} raw)`)}`,
-      4
-    )
-  );
-  lines.push(
-    field(
-      "Fee drip end",
-      token.fees.dripEndTs === 0n
-        ? "none"
-        : new Date(Number(token.fees.dripEndTs) * 1000).toISOString(),
-      4
-    )
-  );
-  lines.push(field("Fee absorption ETA", feeAbsorptionEtaLabel(token.fees), 4));
-  if (token.fees.pendingProtocolFeesRaw > 0n) {
-    lines.push(
-      field(
-        "Pending protocol fees",
-        `${token.fees.pendingProtocolFeesUi.toLocaleString("en-US")} yTokens`,
-        4
-      )
-    );
-  }
-  if (token.fees.pendingCuratorFeesRaw > 0n) {
-    lines.push(
-      field(
-        "Pending curator fees",
-        `${token.fees.pendingCuratorFeesUi.toLocaleString("en-US")} yTokens`,
-        4
-      )
-    );
-  }
-
-  return lines.join("\n");
-}
-
-// ---------------------------------------------------------------------------
-// Fee Wallet
-// ---------------------------------------------------------------------------
-
-export function formatFeeWallet(wallet: Address, balances: FeeWalletBalance[]): string {
-  const lines: string[] = [""];
-  const nonZeroBalances = balances
-    .filter((balance) => balance.balance > 0n)
-    .sort((a, b) => a.symbol.localeCompare(b.symbol));
-
-  lines.push(bold("Fee Wallet"));
-  lines.push(DIVIDER);
-  lines.push(field("Address", addr(wallet)));
-
-  if (nonZeroBalances.length === 0) {
-    lines.push(field("Balances", "none"));
-  } else {
-    lines.push(SECTION_DIVIDER);
-    lines.push(section("Balances"));
-    for (const balance of nonZeroBalances) {
-      lines.push(
-        field(
-          balance.symbol,
-          `${formatTokenAmountUi(balance.balance, balance.decimals)} ${balance.symbol}`,
-          4
-        )
-      );
-    }
-  }
-
-  return lines.join("\n");
-}