@hobba-io/core 0.1.0

package/src/position.ts

@@ -0,0 +1,131 @@
+import { Connection, PublicKey } from "@solana/web3.js";
+import {
+  DEFAULT_LENDING_PROVIDER,
+  LENDING_PROVIDER_JUPLEND,
+  XSTOCKS_MARKET,
+} from "./constants";
+import {
+  parseObligationDebt,
+  parseObligationCTokens,
+  cTokensToUnderlying,
+} from "./kamino/obligationParser";
+import {
+  XSTOCKS_MARKET_CONFIG,
+  resolveMainMarketConfigByMint,
+  type KaminoMarketConfig,
+} from "./marketConfig";
+import { fetchUserState, type CurrentVaultType } from "./userState";
+
+export type Lender = "juplend" | "kamino";
+
+/**
+ * A user's Hobba position for one collateral asset, in base units
+ * (collateral in lamports/satoshis, debt in micro-USDC). Amounts are decimal
+ * strings so they survive JSON and avoid float drift at the integration
+ * boundary.
+ */
+export interface HobbaPosition {
+  /** false → no UserState exists for this (owner, collateral). */
+  exists: boolean;
+  /** Active lender; for new users this is the default lender init() would pick. */
+  lender: Lender;
+  /** Kamino lending market pubkey (distinguishes Main vs xStocks). */
+  lendingMarket?: string;
+  /** Deposited collateral, base units. */
+  collateral: string;
+  /** Total obligation debt, micro-USDC (user + operator-deployed). */
+  debtUsdc: string;
+  /** Operator-deployed capital, micro-USDC. */
+  depositedToVault: string;
+  /** max(0, debtUsdc - depositedToVault) — what UIs show as the user's loan. */
+  userDebtUsdc: string;
+  currentVault: CurrentVaultType;
+  /** Obligation (Kamino) / position (JupLend) address. */
+  obligation?: string;
+}
+
+export function resolveKaminoMarketConfig(
+  lendingMarket: PublicKey,
+  collateralMint: PublicKey,
+): KaminoMarketConfig {
+  return lendingMarket.equals(XSTOCKS_MARKET)
+    ? XSTOCKS_MARKET_CONFIG
+    : resolveMainMarketConfigByMint(collateralMint);
+}
+
+const EMPTY_POSITION = (lender: Lender): HobbaPosition => ({
+  exists: false,
+  lender,
+  collateral: "0",
+  debtUsdc: "0",
+  depositedToVault: "0",
+  userDebtUsdc: "0",
+  currentVault: "none",
+});
+
+export interface GetPositionParams {
+  connection: Connection;
+  owner: PublicKey;
+  collateralMint: PublicKey;
+  /** Hobba backend base URL serving /api/juplend-position. "" = same-origin. */
+  apiBaseUrl?: string;
+}
+
+/**
+ * Headless position read: UserState → lender routing → obligation (Kamino,
+ * parsed client-side) or JupLend position (via the backend, which handles the
+ * tick-based debt computation). Mirrors the app's useUserState +
+ * useObligationData hooks.
+ */
+export async function getPosition(params: GetPositionParams): Promise<HobbaPosition> {
+  const { connection, owner, collateralMint } = params;
+  const base = (params.apiBaseUrl ?? "").replace(/\/+$/, "");
+
+  const userState = await fetchUserState(connection, owner, collateralMint);
+  if (!userState) {
+    return EMPTY_POSITION(
+      DEFAULT_LENDING_PROVIDER === LENDING_PROVIDER_JUPLEND ? "juplend" : "kamino",
+    );
+  }
+
+  const isJuplend = userState.lendingProvider === LENDING_PROVIDER_JUPLEND;
+  let collateral = "0";
+  let debtUsdc = "0";
+
+  if (isJuplend) {
+    const res = await fetch(
+      `${base}/api/juplend-position?address=${userState.obligation.toBase58()}`,
+    );
+    if (!res.ok) throw new Error(`juplend-position fetch failed: ${res.status}`);
+    const data = await res.json();
+    collateral = String(data.collateral ?? "0");
+    debtUsdc = String(data.debt ?? "0");
+  } else {
+    const mc = resolveKaminoMarketConfig(userState.lendingMarket, collateralMint);
+    const [obligationInfo, reserveInfo] = await Promise.all([
+      connection.getAccountInfo(userState.obligation),
+      connection.getAccountInfo(mc.collateralReserve),
+    ]);
+    if (obligationInfo) {
+      debtUsdc = String(parseObligationDebt(obligationInfo.data as Buffer));
+      const cTokens = parseObligationCTokens(obligationInfo.data as Buffer);
+      collateral = String(
+        reserveInfo ? cTokensToUnderlying(cTokens, reserveInfo.data as Buffer) : cTokens,
+      );
+    }
+  }
+
+  const userDebt = Math.max(0, Number(debtUsdc) - userState.depositedToVault);
+
+  return {
+    exists: true,
+    lender: isJuplend ? "juplend" : "kamino",
+    lendingMarket: isJuplend ? undefined : userState.lendingMarket.toBase58(),
+    collateral,
+    debtUsdc,
+    depositedToVault: String(userState.depositedToVault),
+    userDebtUsdc: String(userDebt),
+    currentVault: userState.currentVaultType,
+    obligation: userState.obligation.toBase58(),
+  };
+}

package/src/positionMetrics.ts

@@ -0,0 +1,387 @@
+import { Connection, PublicKey } from "@solana/web3.js";
+import { collateralDecimals, collateralLabel } from "./amountUtils";
+import { XSTOCKS_MARKET } from "./constants";
+import { getPosition, type HobbaPosition, type Lender } from "./position";
+
+/**
+ * Display-ready dashboard metrics for a Hobba position — the exact values
+ * app.hobba.io renders, computed with the same logic (ported verbatim from the
+ * app's Dashboard.tsx). Partners render these without knowing Hobba's rate /
+ * operator / dust-threshold rules.
+ */
+export interface HobbaPositionMetrics {
+  position: HobbaPosition;
+  lender: Lender;
+
+  /** Collateral price used for every USD figure below. */
+  collateralPriceUsd: number;
+  collateralUi: number;
+  collateralUsd: number;
+  /** User-visible loan (total debt minus operator-deployed capital), UI units. */
+  loanUsdc: number;
+
+  currentLtvPct: number;
+  ltvStatus: "HEALTHY" | "MODERATE" | "NEEDS_ATTENTION";
+  liquidationLtvPct: number;
+  /** null when the position is effectively just earning (no meaningful debt). */
+  liquidationPriceUsd: number | null;
+  dropToLiquidationPct: number | null;
+
+  /** Big Supply APY figure (earn APY once the loan is effectively cleared). */
+  supplyApyPct: number;
+  /** Big Loan APY figure; null renders as "—" (no effective debt). */
+  loanApyPct: number | null;
+  /** True → "Smart Earning" badge; false → "Reducing Interest". */
+  isEarning: boolean;
+  /**
+   * True when the position renders as effectively debt-free (earn view or
+   * dust-offset loan) — the state in which loanApyPct is null and LTV/loan
+   * figures display as zero.
+   */
+  showZeroDebt: boolean;
+  /** Operator debt used in the APY math (optimistic target-LTV projection), UI USDC. */
+  operatorBorrowedUsdc: number;
+  /** Estimated self-repay date (dd/mm/yyyy) when loan APY is negative. */
+  selfRepayDate: string | null;
+
+  estimatedEarningsPerYearUsd: number;
+  borrowLimitUsd: number;
+  borrowLimitUsedUsd: number;
+  borrowLimitUsedPct: number;
+
+  // "More info" block
+  lendingSource: string; // "JupLend" | "Kamino Main" | "Kamino XStocks" | "—"
+  borrowApyPct: number;
+  yieldVault: string; // "Perena USD*" | "Allez USDC" | … | "—"
+  vaultSupplyApyPct: number;
+  capitalEarningYieldUsdc: number;
+
+  // Tooltip-level breakdown (per day, USD) so partner UIs can mirror Hobba's
+  // Supply/Loan APY tooltips without re-deriving anything.
+  dailyBorrowCostUsd: number;
+  dailyEngineEarningsUsd: number;
+  collateralSupplyApyPct: number;
+  collateralRewardsApyPct: number;
+}
+
+const VAULT_NAME_MAP: Record<string, string> = {
+  allez: "Allez USDC",
+  prime: "Prime USDC",
+  rockawayRWA: "RockawayRWA USDC",
+  perena: "Perena USDC",
+};
+
+const VAULT_DISPLAY_MAP: Record<string, string> = {
+  allez: "Allez USDC",
+  prime: "Prime USDC",
+  rockawayRWA: "RockawayRWA USDC",
+  perena: "Perena USD*",
+};
+
+export interface RatesPayload {
+  markets: { name: string; borrowAPY: number; error?: string }[];
+  collateralSupplyAPYs: Record<string, number>;
+  juplendCollateralSupplyAPYs: Record<string, number>;
+  juplendCollateralRewardsAPYs: Record<string, number>;
+  collateralLtvs: Record<string, { loanToValuePct: number; liquidationThresholdPct: number }>;
+  juplendCollateralLtvs: Record<string, { loanToValuePct: number; liquidationThresholdPct: number }>;
+}
+
+export interface SupplyRatesPayload {
+  vaults: { name: string; supplyAPY: number }[];
+}
+
+export async function fetchRatesPayload(base: string): Promise<RatesPayload> {
+  const res = await fetch(`${base}/api/rates`);
+  if (!res.ok) throw new Error(`rates fetch failed: ${res.status}`);
+  const data = await res.json();
+  return {
+    markets: (data.markets ?? []).filter((m: any) => !m.error),
+    collateralSupplyAPYs: data.collateralSupplyAPYs ?? {},
+    juplendCollateralSupplyAPYs: data.juplendCollateralSupplyAPYs ?? {},
+    juplendCollateralRewardsAPYs: data.juplendCollateralRewardsAPYs ?? {},
+    collateralLtvs: data.collateralLtvs ?? {},
+    juplendCollateralLtvs: data.juplendCollateralLtvs ?? {},
+  };
+}
+
+export async function fetchSupplyRatesPayload(base: string): Promise<SupplyRatesPayload> {
+  const res = await fetch(`${base}/api/supply-rates`);
+  if (!res.ok) throw new Error(`supply-rates fetch failed: ${res.status}`);
+  const data = await res.json();
+  return { vaults: (data.vaults ?? []).filter((v: any) => !v.error && v.supplyAPY > 0) };
+}
+
+export async function fetchCollateralPrice(base: string, label: string): Promise<number> {
+  const route = label === "SOL" ? "sol-price" : "btc-price";
+  const res = await fetch(`${base}/api/${route}`);
+  if (!res.ok) throw new Error(`${route} fetch failed: ${res.status}`);
+  const data = await res.json();
+  const price = Number(data.price);
+  if (!Number.isFinite(price) || price <= 0) throw new Error(`${route} returned no price`);
+  return price;
+}
+
+export function bestMarketName(rates: RatesPayload): string | null {
+  let best: string | null = null;
+  let bestApy = Infinity;
+  for (const m of rates.markets) {
+    if (m.borrowAPY < bestApy) {
+      bestApy = m.borrowAPY;
+      best = m.name;
+    }
+  }
+  return best;
+}
+
+export interface GetPositionMetricsParams {
+  connection: Connection;
+  owner: PublicKey;
+  collateralMint: PublicKey;
+  apiBaseUrl?: string;
+}
+
+export async function getPositionMetrics(
+  params: GetPositionMetricsParams,
+): Promise<HobbaPositionMetrics> {
+  const { connection, owner, collateralMint } = params;
+  const base = (params.apiBaseUrl ?? "").replace(/\/+$/, "");
+  const label = collateralLabel(collateralMint);
+
+  const [position, rates, supplyRates, collateralPrice] = await Promise.all([
+    getPosition({ connection, owner, collateralMint, apiBaseUrl: base }),
+    fetchRatesPayload(base),
+    fetchSupplyRatesPayload(base),
+    fetchCollateralPrice(base, label),
+  ]);
+
+  return computePositionMetrics({
+    position,
+    rates,
+    supplyRates,
+    collateralPriceUsd: collateralPrice,
+    collateralMint,
+  });
+}
+
+/**
+ * Inputs for the pure metric computation. The app feeds these from its own
+ * cached hooks (per-keystroke/optimistic refresh paths); `getPositionMetrics`
+ * feeds them from the backend fetches above. Same math either way.
+ */
+export interface PositionMetricsInputs {
+  position: HobbaPosition;
+  rates: RatesPayload;
+  supplyRates: SupplyRatesPayload;
+  collateralPriceUsd: number;
+  collateralMint: PublicKey;
+  /**
+   * Pending-harvest yield not yet applied on-chain (micro-USDC), netted off
+   * the user-visible debt. The headless read passes 0 (projection requires an
+   * extra chain read); the app passes its useJuplendHarvestProjection value.
+   */
+  earnedNotAppliedMicro?: number;
+}
+
+export function computePositionMetrics(
+  inputs: PositionMetricsInputs,
+): HobbaPositionMetrics {
+  const {
+    position,
+    rates,
+    supplyRates,
+    collateralPriceUsd: collateralPrice,
+    collateralMint,
+    earnedNotAppliedMicro = 0,
+  } = inputs;
+  const label = collateralLabel(collateralMint);
+  const decimals = collateralDecimals(collateralMint);
+
+  // --- Ported verbatim from app Dashboard.tsx ---
+  const collateral = Number(position.collateral);
+  const totalDebt = Number(position.debtUsdc);
+  const depositedToVault = Number(position.depositedToVault);
+  // NOTE: earnedNotAppliedMicro is NOT netted here — the app keeps userDebt
+  // (and so LTV / loan APY) on the on-chain figure and only uses the pending
+  // harvest to decide the earn-view threshold below.
+  const userDebt = Math.max(0, totalDebt - depositedToVault);
+
+  const divisor = Math.pow(10, decimals);
+  const collateralUsd = (collateral / divisor) * collateralPrice;
+  const ltv = collateralUsd > 0 ? (userDebt / 1e6 / collateralUsd) * 100 : 0;
+
+  const isJuplendLender = position.exists
+    ? position.lender === "juplend"
+    : bestMarketName(rates) === "JupLend";
+
+  const borrowSource = !position.exists
+    ? "—"
+    : position.lender === "juplend"
+      ? "JupLend"
+      : position.lendingMarket === XSTOCKS_MARKET.toBase58()
+        ? "Kamino XStocks"
+        : "Kamino Main";
+
+  const borrowMarketNameForRates = !position.exists
+    ? "Kamino Main Market"
+    : position.lender === "juplend"
+      ? "JupLend"
+      : position.lendingMarket === XSTOCKS_MARKET.toBase58()
+        ? "Kamino xStocks"
+        : "Kamino Main Market";
+  const borrowMarket = rates.markets.find((m) => m.name === borrowMarketNameForRates);
+  const borrowAPY = borrowMarket?.borrowAPY ?? 0;
+
+  const vaultName = VAULT_NAME_MAP[position.currentVault] ?? "";
+  const supplyVault = supplyRates.vaults.find((v) => v.name === vaultName);
+  const currentVaultAPY = supplyVault?.supplyAPY ?? 0;
+  // Assumed default vault when no position exists yet: Perena USD*.
+  const perenaVaultAPY = supplyRates.vaults.find((v) => v.name === "Perena USDC")?.supplyAPY ?? 0;
+  const vaultAPY = currentVaultAPY > 0 ? currentVaultAPY : perenaVaultAPY;
+
+  const collateralBaseSupplyAPY =
+    (isJuplendLender
+      ? rates.juplendCollateralSupplyAPYs[label]
+      : rates.collateralSupplyAPYs[label]) ?? 0;
+  const collateralRewardsAPY = isJuplendLender
+    ? (rates.juplendCollateralRewardsAPYs[label] ?? 0)
+    : 0;
+  const collateralSupplyAPY = collateralBaseSupplyAPY + collateralRewardsAPY;
+
+  const collateralLtv = isJuplendLender
+    ? rates.juplendCollateralLtvs[label]
+    : rates.collateralLtvs[label];
+  const liquidationLtvPct = collateralLtv?.liquidationThresholdPct ?? 85;
+
+  const userBorrowed = userDebt / 1e6;
+  const actualOperatorBorrowed = depositedToVault / 1e6;
+
+  // Optimistic operator debt: what the operator WOULD borrow to reach the
+  // per-asset target LTV (65% cbBTC, 60% SOL).
+  const TARGET_LTV = label === "SOL" ? 0.6 : 0.65;
+  const optimisticOperatorBorrowed = (() => {
+    if (!collateralUsd || collateralUsd <= 0) return actualOperatorBorrowed;
+    if (vaultAPY <= borrowAPY) return 0;
+    const targetTotalDebt = collateralUsd * TARGET_LTV;
+    const projected = Math.max(0, targetTotalDebt - userBorrowed);
+    return Math.max(actualOperatorBorrowed, projected);
+  })();
+  const operatorBorrowed = optimisticOperatorBorrowed;
+
+  const operatorHasNotBorrowed = depositedToVault === 0;
+  const hasDeposit = collateralUsd > 0;
+  const willDeployToVault = hasDeposit && operatorHasNotBorrowed && borrowAPY < vaultAPY;
+  const capitalEarningYield = willDeployToVault ? operatorBorrowed : depositedToVault / 1e6;
+  const displayVaultType =
+    position.currentVault !== "none"
+      ? position.currentVault
+      : willDeployToVault
+        ? "perena"
+        : position.currentVault;
+
+  const loanAPY =
+    userBorrowed > 0
+      ? ((userBorrowed + operatorBorrowed) * borrowAPY - operatorBorrowed * vaultAPY) /
+        userBorrowed
+      : null;
+
+  const currentPrice = collateralPrice;
+  const liquidationPrice =
+    currentPrice > 0 && ltv > 0 && liquidationLtvPct > 0
+      ? currentPrice * (ltv / liquidationLtvPct)
+      : 0;
+  const buffer =
+    currentPrice > 0 && liquidationPrice > 0
+      ? Math.max(0, ((currentPrice - liquidationPrice) / currentPrice) * 100)
+      : 100;
+
+  const ltvStatus: HobbaPositionMetrics["ltvStatus"] =
+    ltv > 75 ? "NEEDS_ATTENTION" : ltv > 50 ? "MODERATE" : "HEALTHY";
+
+  // Dust-offset loan: tiny outstanding debt more than covered by net yield.
+  const hobbaDailyEarning = (operatorBorrowed * vaultAPY) / 100 / 365;
+  const dailyBorrowCost = ((userBorrowed + operatorBorrowed) * borrowAPY) / 100 / 365;
+  const netDailyEarning = hobbaDailyEarning - dailyBorrowCost;
+
+  const DUST_DEBT_THRESHOLD_USDC = 0.01;
+  const isDustOffsetLoan =
+    userBorrowed < DUST_DEBT_THRESHOLD_USDC && netDailyEarning > userBorrowed;
+
+  // Earn view: once the yield already earned-but-not-yet-applied (pending
+  // harvest) brings residual debt under 0.1 USDC, the position is effectively
+  // just earning. Matches app Dashboard.tsx: only this threshold test nets the
+  // pending harvest; every other figure stays on the on-chain debt.
+  const EARN_VIEW_THRESHOLD_USDC = 0.1;
+  const residualDebtMicro = Math.max(0, userDebt - earnedNotAppliedMicro);
+  const isEarnView = residualDebtMicro < EARN_VIEW_THRESHOLD_USDC * 1e6;
+  const showZeroDebt = isEarnView || isDustOffsetLoan;
+
+  const hobbaSupplyContribution =
+    isDustOffsetLoan && collateralUsd > 0 ? ((netDailyEarning * 365) / collateralUsd) * 100 : 0;
+
+  const displaySupplyAPY = collateralSupplyAPY + hobbaSupplyContribution;
+  const displayLoanAPY: number | null = showZeroDebt ? null : loanAPY;
+  const displayUserBorrowed = showZeroDebt ? 0 : userBorrowed;
+
+  const estimatedAnnualEarnings =
+    operatorBorrowed > 0 && vaultAPY > borrowAPY
+      ? (operatorBorrowed * (vaultAPY - borrowAPY)) / 100
+      : 0;
+  const earnApy =
+    collateralSupplyAPY + (collateralUsd > 0 ? (estimatedAnnualEarnings / collateralUsd) * 100 : 0);
+
+  // Self-repay estimate when the net loan APY is negative.
+  let selfRepayDate: string | null = null;
+  if (displayLoanAPY !== null && displayLoanAPY < 0) {
+    const yearsToRepay = 1 / Math.abs(displayLoanAPY / 100);
+    if (yearsToRepay <= 10) {
+      const daysToRepay = yearsToRepay * 365;
+      const repayDate = new Date();
+      repayDate.setDate(repayDate.getDate() + Math.ceil(daysToRepay));
+      selfRepayDate = `${repayDate.getDate().toString().padStart(2, "0")}/${(repayDate.getMonth() + 1)
+        .toString()
+        .padStart(2, "0")}/${repayDate.getFullYear()}`;
+    }
+  }
+
+  const borrowLimit = collateralUsd * 0.5;
+  const borrowLimitUsed = borrowLimit > 0 ? (displayUserBorrowed / borrowLimit) * 100 : 0;
+
+  return {
+    position,
+    lender: position.lender,
+    collateralPriceUsd: collateralPrice,
+    collateralUi: collateral / divisor,
+    collateralUsd,
+    loanUsdc: displayUserBorrowed,
+    currentLtvPct: showZeroDebt ? 0 : ltv,
+    ltvStatus,
+    liquidationLtvPct,
+    liquidationPriceUsd: isEarnView || liquidationPrice <= 0 ? null : liquidationPrice,
+    dropToLiquidationPct: isEarnView || liquidationPrice <= 0 ? null : buffer,
+    supplyApyPct: showZeroDebt ? earnApy : displaySupplyAPY,
+    loanApyPct: displayLoanAPY,
+    isEarning: showZeroDebt || (displayLoanAPY !== null && displayLoanAPY <= 0),
+    showZeroDebt,
+    operatorBorrowedUsdc: operatorBorrowed,
+    selfRepayDate,
+    estimatedEarningsPerYearUsd: estimatedAnnualEarnings,
+    borrowLimitUsd: borrowLimit,
+    borrowLimitUsedUsd: displayUserBorrowed,
+    borrowLimitUsedPct: borrowLimitUsed,
+    lendingSource: borrowSource,
+    borrowApyPct: borrowAPY,
+    yieldVault:
+      borrowSource === "—"
+        ? "—"
+        : !displayVaultType || displayVaultType === "none"
+          ? "Perena USD*"
+          : (VAULT_DISPLAY_MAP[displayVaultType] ?? displayVaultType),
+    vaultSupplyApyPct: vaultAPY,
+    capitalEarningYieldUsdc: capitalEarningYield,
+    dailyBorrowCostUsd: dailyBorrowCost,
+    dailyEngineEarningsUsd: hobbaDailyEarning,
+    collateralSupplyApyPct: collateralSupplyAPY,
+    collateralRewardsApyPct: collateralRewardsAPY,
+  };
+}

package/src/program.ts

@@ -0,0 +1,30 @@
+import { AnchorProvider, Program } from "@coral-xyz/anchor";
+import {
+  Connection,
+  PublicKey,
+  Transaction,
+  VersionedTransaction,
+} from "@solana/web3.js";
+import idl from "./idl/hobba.json";
+import { PROGRAM_ID } from "./constants";
+
+/**
+ * Build the Hobba wrapper Anchor `Program` for instruction-building only.
+ *
+ * `.methods.x().instruction()` never signs, so a no-op signing wallet is enough;
+ * real signing happens later in `transactionBuilder` via the caller's HobbaSigner.
+ * `PROGRAM_ID` is selected from `NEXT_PUBLIC_MAINNET`/`NEXT_PUBLIC_STAGING` at
+ * build/runtime (see constants.ts), matching the app's AnchorProvider.
+ */
+export function buildHobbaProgram(connection: Connection, owner: PublicKey): Program {
+  const noopWallet = {
+    publicKey: owner,
+    signTransaction: async <T extends Transaction | VersionedTransaction>(tx: T) => tx,
+    signAllTransactions: async <T extends Transaction | VersionedTransaction>(txs: T[]) => txs,
+  };
+  const provider = new AnchorProvider(connection, noopWallet as any, {
+    commitment: "confirmed",
+  });
+  const idlWithAddress = { ...(idl as any), address: PROGRAM_ID.toBase58() };
+  return new Program(idlWithAddress as any, provider);
+}