@kestrelfi/lyc-sdk 1.0.1

package/scripts/inspect/format.ts

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