@kehtus/proportion-sdk 0.1.0

package/src/sdk.ts

@@ -0,0 +1,93 @@
+import { createPublicClient, http, type Address } from "viem";
+import { ADDRESSES, hyperEvm } from "./constants.js";
+import { VaultModule } from "./vault.js";
+import { AccountModule } from "./account.js";
+import { FactoryModule } from "./factory.js";
+import { IndexerModule } from "./indexer.js";
+import { mainVaultAbi } from "./abi/mainVault.js";
+import type { SDKConfig } from "./types.js";
+
+export class ProportionSDK {
+  readonly vault: VaultModule;
+  readonly account: AccountModule;
+  readonly factory: FactoryModule;
+  readonly indexer: IndexerModule;
+
+  /**
+   * Async factory: resolves addresses from explicit config > ENV > ProtocolConfig > hardcoded constants.
+   *
+   * ProtocolConfig is only a convenience fallback from the indexer. It is not the source of truth
+   * for protocol configuration and should not replace explicit deployment config in applications.
+   *
+   * ENV vars: PROPORTION_VAULT_ADDRESS, PROPORTION_FACTORY_ADDRESS, PROPORTION_USDC_ADDRESS
+   */
+  static async create(config: SDKConfig): Promise<ProportionSDK> {
+    const resolved: Record<string, string> = { ...config.addresses };
+
+    // ENV fallbacks (Node; safely ignored in browsers)
+    const env = typeof process !== "undefined" ? process.env : undefined;
+    if (!resolved.MAIN_VAULT && env?.PROPORTION_VAULT_ADDRESS) resolved.MAIN_VAULT = env.PROPORTION_VAULT_ADDRESS;
+    if (!resolved.FACTORY && env?.PROPORTION_FACTORY_ADDRESS) resolved.FACTORY = env.PROPORTION_FACTORY_ADDRESS;
+    if (!resolved.USDC && env?.PROPORTION_USDC_ADDRESS) resolved.USDC = env.PROPORTION_USDC_ADDRESS;
+
+    // Fetch missing addresses from the indexer only as a convenience fallback.
+    // Primary address sources remain explicit config.addresses and ENV.
+    if (!resolved.MAIN_VAULT || !resolved.FACTORY) {
+      try {
+        const indexer = new IndexerModule(config.graphqlUrl, undefined, {
+          fetchFn: config.fetchFn,
+          webSocketCtor: config.webSocketCtor,
+        });
+        const protocol = await indexer.getProtocolConfig();
+        if (protocol) {
+          if (!resolved.MAIN_VAULT && protocol.vaultAddress) resolved.MAIN_VAULT = protocol.vaultAddress;
+          if (!resolved.FACTORY && protocol.factoryAddress) resolved.FACTORY = protocol.factoryAddress;
+        }
+      } catch { /* fall back to hardcoded constants */ }
+    }
+
+    if (resolved.MAIN_VAULT && !resolved.USDC) {
+      try {
+        const publicClient = createPublicClient({
+          chain: hyperEvm,
+          transport: http(config.rpcUrl ?? hyperEvm.rpcUrls.default.http[0]),
+        });
+        resolved.USDC = await publicClient.readContract({
+          address: resolved.MAIN_VAULT as Address,
+          abi: mainVaultAbi,
+          functionName: "usdc",
+        });
+      } catch { /* fall back to hardcoded constants */ }
+    }
+
+    return new ProportionSDK({ ...config, addresses: resolved });
+  }
+
+  constructor(config: SDKConfig) {
+    const addresses = {
+      vault: (config.addresses?.MAIN_VAULT ?? ADDRESSES.MAIN_VAULT) as Address,
+      usdc: (config.addresses?.USDC ?? ADDRESSES.USDC) as Address,
+      factory: (config.addresses?.FACTORY ?? ADDRESSES.FACTORY) as Address,
+    };
+
+    const publicClient = createPublicClient({
+      chain: hyperEvm,
+      transport: http(config.rpcUrl ?? hyperEvm.rpcUrls.default.http[0]),
+    });
+
+    this.vault = new VaultModule(publicClient, config.walletClient, hyperEvm, {
+      vault: addresses.vault,
+      usdc: addresses.usdc,
+    });
+    this.account = new AccountModule(publicClient, config.walletClient, hyperEvm);
+    this.factory = new FactoryModule(publicClient, addresses.factory);
+    this.indexer = new IndexerModule(config.graphqlUrl, config.graphqlWsUrl, {
+      fetchFn: config.fetchFn,
+      webSocketCtor: config.webSocketCtor,
+    });
+  }
+
+  disconnect(): void {
+    this.indexer.disconnect();
+  }
+}

package/src/types.ts

@@ -0,0 +1,426 @@
+import type { Address, WalletClient } from "viem";
+import type { ADDRESSES } from "./constants.js";
+
+// ── Config ──────────────────────────────────────────
+export interface SDKConfig {
+  rpcUrl?: string;
+  graphqlUrl: string;
+  graphqlWsUrl?: string;
+  walletClient?: WalletClient;
+  fetchFn?: typeof fetch;
+  webSocketCtor?: WebSocketConstructor;
+  addresses?: Partial<typeof ADDRESSES>;
+}
+
+export interface WebSocketLike {
+  readyState: number;
+  send(data: string): void;
+  close(): void;
+  onopen: ((this: unknown, ...args: unknown[]) => unknown) | null;
+  onmessage: ((this: unknown, event: { data: unknown }, ...args: unknown[]) => unknown) | null;
+  onclose: ((this: unknown, ...args: unknown[]) => unknown) | null;
+  onerror: ((this: unknown, ...args: unknown[]) => unknown) | null;
+}
+
+export interface WebSocketConstructor {
+  new (url: string, protocols?: string | string[]): WebSocketLike;
+  readonly OPEN: number;
+}
+
+// ── Enums ───────────────────────────────────────────
+export enum AccountState {
+  Uninitialized,
+  Initialized,
+  Active,
+  WithdrawalPending,
+  Closing,
+  Returning,
+  Closed,
+}
+
+export type AccountStateLabel =
+  | "UNINITIALIZED"
+  | "INITIALIZED"
+  | "ACTIVE"
+  | "WITHDRAWAL_PENDING"
+  | "CLOSING"
+  | "RETURNING"
+  | "CLOSED";
+
+export type IndexerAccountStateLabel =
+  | "INITIALIZED"
+  | "ACTIVE"
+  | "WITHDRAWAL_PENDING"
+  | "CLOSING"
+  | "RETURNING"
+  | "CLOSED";
+
+export type BreachType =
+  | "TRAILING_DRAWDOWN"
+  | "DAILY_DRAWDOWN"
+  | "LEVERAGE"
+  | "POSITION_LEVERAGE"
+  | "UNAUTHORIZED_ASSET"
+  | "SUBSCRIPTION_EXPIRED";
+
+// ── On-chain return types ───────────────────────────
+export interface VaultStats {
+  totalAssets: bigint;
+  sharePrice: bigint;
+  utilizationBps: bigint;
+  availableForAllocation: bigint;
+  maxAccountSize: bigint;
+  remainingCap: bigint;
+  paused: boolean;
+  feeMultiplier: number;
+  subscriptionFeeMultiplier: number;
+  totalShares: bigint;
+  totalAllocated: bigint;
+  owner: Address;
+  pendingOwner: Address;
+  relayer: Address;
+  protocolFeeReceiver: Address;
+  maxCap: bigint;
+  hypeForSpot: bigint;
+  factory: Address;
+  minBuilderShares: bigint;
+  builderLeverage: bigint;
+  protocolFeeBps: bigint;
+  minAccountSize: bigint;
+  maxAccountSizeLimit: bigint;
+  minDrawdownBps: number;
+  maxDrawdownBps: number;
+  maxUtilizationBps: bigint;
+  maxSingleAccountBps: bigint;
+  dailyDdDiscountBps: number;
+}
+
+export interface LPPosition {
+  shares: bigint;
+  sharesValue: bigint;
+  withdrawableShares: bigint;
+}
+
+export interface BuilderInfo {
+  active: boolean;
+  activeFunded: bigint;
+  availableFunded: bigint;
+}
+
+export interface AccountDetails {
+  address: Address;
+  state: AccountState;
+  owner: Address;
+  builder: Address;
+  accountSize: bigint;
+  drawdownBps: number;
+  dailyDrawdownEnabled: boolean;
+  subscriptionFeeMultiplier: number;
+  highWaterMark: bigint;
+  dayStartValue: bigint;
+  activatedAt: bigint;
+  subscriptionPaidUntil: bigint;
+  subscriptionCancelled: boolean;
+  pendingSubscriptionFee: bigint;
+  apiWallet: Address;
+  riskEngineWallet: Address;
+  builderRiskEngineWallet: Address;
+  checkpointIndex: number;
+  totalCheckpoints: number;
+  profitableDaysCount: number;
+  lastCheckpointDay: bigint;
+  closingInitiatedAt: number;
+  returnInitiatedAt: number;
+  pendingWithdrawal: { profit: bigint; requestedAt: number };
+  trailingFloor: bigint;
+  dailyFloor: bigint;
+  subscriptionFee: bigint;
+  isSubscriptionActive: boolean;
+  canWithdrawProfit: boolean;
+  checkpoints: Array<{
+    accountValue: bigint;
+    timestamp: number;
+    profitable: boolean;
+  }>;
+}
+
+// ── GraphQL entity types ────────────────────────────
+export interface GqlVault {
+  id: string;
+  address: string;
+  totalDeposits: string;
+  totalWithdrawals: string;
+  totalActivationFees: string;
+  cumulativeActivationFeesToVault: string;
+  totalAllocated: string;
+  totalShares: string;
+  cumulativeProfitShares: string;
+  cumulativeCancelledProfit: string;
+  cumulativeSubscriptionFees: string;
+  cumulativeProtocolFeesRouted: string;
+  cumulativeHypercoreFees: string;
+  cumulativeAccountGains: string;
+  cumulativeAccountLosses: string;
+  cumulativeRescuedFunds: string;
+  totalAccountsActivated: number;
+  totalAccountsActive: number;
+  totalAccountsClosed: number;
+  paused: boolean;
+  subscriptionFeeMultiplier: number;
+  protocolFeeBps: number;
+  protocolFeeReceiver: string | null;
+  updatedAt: string;
+}
+
+export interface GqlLP {
+  id: string;
+  totalDeposited: string;
+  totalWithdrawn: string;
+  depositCount: number;
+  withdrawCount: number;
+  lastActionAt: string;
+}
+
+export interface GqlBuilder {
+  id: string;
+  address: string;
+  vaultAddress: string;
+  active: boolean;
+  totalAccountsActivated: number;
+  totalAccountsClosed: number;
+  activeAccounts: number;
+  registeredAt: string;
+  deactivatedAt: string | null;
+}
+
+export interface GqlAccount {
+  id: string;
+  owner: string;
+  builder: { id: string; address: string; vaultAddress: string };
+  vaultAddress: string;
+  factoryAddress: string;
+  state: IndexerAccountStateLabel;
+  accountSize: string;
+  drawdownBps: number;
+  dailyDrawdownEnabled: boolean;
+  activationFee: string;
+  highWaterMark: string;
+  profitableDaysCount: number;
+  lastCheckpointDay: string;
+  totalCheckpoints: number;
+  subscriptionPaidUntil: string;
+  subscriptionCancelled: boolean;
+  pendingSubscriptionFee: string;
+  subscriptionFeeMultiplier: number;
+  dayStartValue: string;
+  apiWallet: string | null;
+  riskEngineWallet: string | null;
+  builderRiskEngineWallet: string | null;
+  createdAt: string;
+  activatedAt: string | null;
+  closingInitiatedAt: string | null;
+  returnInitiatedAt: string | null;
+  closedAt: string | null;
+  returnedAmount: string | null;
+  breachType: BreachType | null;
+  breachValue: string | null;
+  breachFloor: string | null;
+  closePendingSubFee: string | null;
+  closePendingProfit: string | null;
+  lastWithdrawalId: string | null;
+  updatedAt: string;
+}
+
+export interface GqlCheckpoint {
+  id: string;
+  dayNumber: string;
+  accountValue: string;
+  previousValue: string;
+  profitable: boolean;
+  profitableDaysCount: number;
+  timestamp: string;
+}
+
+export interface GqlProfitWithdrawal {
+  id: string;
+  profit: string;
+  ownerAmount: string;
+  vaultAmount: string;
+  protocolAmount: string;
+  status: "REQUESTED" | "CLAIMED" | "CANCELLED";
+  requestedAt: string;
+  claimedAt: string | null;
+  cancelledAt: string | null;
+}
+
+export interface GqlSubscriptionPayment {
+  id: string;
+  amount: string;
+  paidUntil: string;
+  timestamp: string;
+}
+
+export interface GqlDeposit {
+  id: string;
+  lp: { id: string };
+  amount: string;
+  sharesReceived: string;
+  timestamp: string;
+  blockNumber?: number;
+  txHash: string;
+}
+
+export interface GqlWithdrawal {
+  id: string;
+  lp: { id: string };
+  amount: string;
+  sharesBurned: string;
+  timestamp: string;
+  blockNumber?: number;
+  txHash: string;
+}
+
+export interface GqlAccountEvent {
+  id: string;
+  eventType: string;
+  data: string;
+  timestamp: string;
+  blockNumber: number;
+  txHash: string;
+}
+
+export interface GqlAllowedPerp {
+  id: string;
+  vaultAddress: string;
+  perpIndex: number;
+  allowed: boolean;
+}
+
+export interface GqlDelegate {
+  id: string;
+  vaultAddress: string;
+  delegateAddress: string;
+  builderAddress: string;
+}
+
+export interface GqlProtocolConfig {
+  id: string;
+  vaultAddress: string;
+  factoryAddress: string;
+  updatedAt: string;
+}
+
+export type GqlConfigContractType = "MainVault" | "FundedAccountFactory";
+
+export interface GqlMainVaultConfig {
+  id: string;
+  vaultAddress: string;
+  factoryAddress: string;
+  owner: string;
+  pendingOwner: string;
+  relayer: string;
+  paused: boolean;
+  protocolFeeReceiver: string;
+  feeMultiplier: number;
+  subscriptionFeeMultiplier: number;
+  dailyDdDiscountBps: number;
+  minBuilderShares: string;
+  builderLeverage: string;
+  protocolFeeBps: number;
+  minAccountSize: string;
+  maxAccountSize: string;
+  minDrawdownBps: number;
+  maxDrawdownBps: number;
+  maxUtilizationBps: number;
+  maxSingleAccountBps: number;
+  hypeForSpot: string;
+  maxCap: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface GqlFactoryConfig {
+  id: string;
+  factoryAddress: string;
+  vaultAddress: string;
+  owner: string;
+  pendingOwner: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface GqlConfigChange {
+  id: string;
+  contractAddress: string;
+  contractType: GqlConfigContractType;
+  field: string;
+  oldValue: string;
+  newValue: string;
+  blockNumber: number;
+  timestamp: string;
+  txHash: string;
+}
+
+export interface GqlVaultDayData {
+  id: string;
+  date: number;
+  dayNumber: number;
+  evmBalance: string;
+  totalAllocated: string;
+  totalAssets: string;
+  totalShares: string;
+  sharePrice: string;
+  dailyDeposits: string;
+  dailyWithdrawals: string;
+  dailyNetLpFlow: string;
+  dailyActivationFees: string;
+  dailyActivationFeesToVault: string;
+  dailyProfitShares: string;
+  dailyCancelledProfit: string;
+  dailySubscriptionFees: string;
+  dailyProtocolFeesRouted: string;
+  dailyHypercoreFees: string;
+  dailyRescuedFunds: string;
+  dailyAccountReturnAmount: string;
+  dailyAccountPrincipalReturned: string;
+  dailyAccountGains: string;
+  dailyAccountLosses: string;
+  dailyPerformancePnl: string;
+  totalAccountsActivated: number;
+  totalAccountsActive: number;
+  totalAccountsClosed: number;
+  accountsActivatedToday: number;
+  accountsClosedToday: number;
+  navChange24h: string;
+  sharePriceChange24h: string;
+  return24hBps: number;
+  paused: boolean;
+  updatedAt: string;
+}
+
+export interface GqlLiquidityProviderDayData {
+  id: string;
+  lp: { id: string };
+  date: number;
+  dayNumber: number;
+  shares: string;
+  sharesValue: string;
+  dailyDeposits: string;
+  dailyWithdrawals: string;
+  depositCount: number;
+  withdrawCount: number;
+}
+
+// ── Helpers ─────────────────────────────────────────
+export interface Pagination {
+  limit?: number;
+  offset?: number;
+}
+
+export interface ConfigChangeFilters extends Pagination {
+  contractAddress?: string;
+  contractType?: GqlConfigContractType;
+  field?: string;
+}
+
+export type Unsubscribe = () => void;

package/src/utils.ts

@@ -0,0 +1,143 @@
+import {
+  BPS,
+  DAILY_DD_DISCOUNT_BPS,
+  DECIMALS_MULTIPLIER,
+  OWNER_PROFIT_BPS,
+  PROTOCOL_PROFIT_BPS,
+  USDC_DECIMALS,
+} from "./constants.js";
+import { AccountState, type AccountStateLabel } from "./types.js";
+
+// ── Decimals ────────────────────────────────────────
+
+export function fromUsdc(amount: bigint): number {
+  return Number(amount) / 10 ** USDC_DECIMALS;
+}
+
+export function toUsdc(amount: number): bigint {
+  return BigInt(Math.round(amount * 10 ** USDC_DECIMALS));
+}
+
+export function from8Dec(value: bigint): number {
+  return Number(value) / 1e8;
+}
+
+export function toUsdc6(value8dec: bigint): bigint {
+  return value8dec / DECIMALS_MULTIPLIER;
+}
+
+export function to8Dec(value6dec: bigint): bigint {
+  return value6dec * DECIMALS_MULTIPLIER;
+}
+
+export function formatUsd(amount: bigint, dec: number = USDC_DECIMALS): string {
+  const num = Number(amount) / 10 ** dec;
+  return "$" + num.toLocaleString("en-US", { minimumFractionDigits: 2, maximumFractionDigits: 2 });
+}
+
+// ── Drawdown ────────────────────────────────────────
+
+export function trailingFloor(hwm: bigint, drawdownBps: number): bigint {
+  return hwm - (hwm * BigInt(drawdownBps)) / BPS;
+}
+
+export function dailyFloor(dayStartValue: bigint, drawdownBps: number): bigint {
+  const dailyBps = BigInt(drawdownBps) / 2n;
+  return dayStartValue - (dayStartValue * dailyBps) / BPS;
+}
+
+export function isTrailingBreached(value: bigint, hwm: bigint, bps: number): boolean {
+  return value < trailingFloor(hwm, bps);
+}
+
+export function isDailyBreached(value: bigint, dsv: bigint, bps: number): boolean {
+  return value < dailyFloor(dsv, bps);
+}
+
+// ── Fees ────────────────────────────────────────────
+
+const FEE_DIVISOR = 1_000_000n;
+const USDC_UNIT = 1_000_000n;
+
+function roundUpUsdc(fee: bigint): bigint {
+  return ((fee + USDC_UNIT - 1n) / USDC_UNIT) * USDC_UNIT;
+}
+
+function applyDailyDiscount(fee: bigint, discountBps: bigint): bigint {
+  return (fee * (BPS - discountBps)) / BPS;
+}
+
+export function activationFee(
+  accountSize: bigint,
+  drawdownBps: number,
+  dailyDD: boolean,
+  feeMultiplier: number = 120,
+  dailyDdDiscountBps: number = Number(DAILY_DD_DISCOUNT_BPS),
+): bigint {
+  let fee = (accountSize * BigInt(drawdownBps) * BigInt(feeMultiplier)) / FEE_DIVISOR;
+  if (dailyDD) {
+    fee = applyDailyDiscount(fee, BigInt(dailyDdDiscountBps));
+  }
+  return roundUpUsdc(fee);
+}
+
+export function subscriptionFee(accountSize: bigint, subFeeMultiplier: number): bigint;
+export function subscriptionFee(
+  accountSize: bigint,
+  _drawdownBps: number,
+  _dailyDD: boolean,
+  subFeeMultiplier: number,
+): bigint;
+export function subscriptionFee(
+  accountSize: bigint,
+  a: number,
+  _b?: boolean,
+  c?: number,
+): bigint {
+  const subFeeMultiplier = c ?? a;
+  const fee = (accountSize * BigInt(subFeeMultiplier)) / BPS;
+  return roundUpUsdc(fee);
+}
+
+// ── Profit split ────────────────────────────────────
+
+export function splitProfit(profit: bigint): {
+  owner: bigint;
+  vault: bigint;
+  protocol: bigint;
+} {
+  const owner = (profit * OWNER_PROFIT_BPS) / BPS;
+  const protocol = (profit * PROTOCOL_PROFIT_BPS) / BPS;
+  const vault = profit - owner - protocol;
+  return { owner, vault, protocol };
+}
+
+// ── Enum mapping ────────────────────────────────────
+
+const stateLabels: Record<AccountState, AccountStateLabel> = {
+  [AccountState.Uninitialized]: "UNINITIALIZED",
+  [AccountState.Initialized]: "INITIALIZED",
+  [AccountState.Active]: "ACTIVE",
+  [AccountState.WithdrawalPending]: "WITHDRAWAL_PENDING",
+  [AccountState.Closing]: "CLOSING",
+  [AccountState.Returning]: "RETURNING",
+  [AccountState.Closed]: "CLOSED",
+};
+
+const labelStates: Record<AccountStateLabel, AccountState> = {
+  UNINITIALIZED: AccountState.Uninitialized,
+  INITIALIZED: AccountState.Initialized,
+  ACTIVE: AccountState.Active,
+  WITHDRAWAL_PENDING: AccountState.WithdrawalPending,
+  CLOSING: AccountState.Closing,
+  RETURNING: AccountState.Returning,
+  CLOSED: AccountState.Closed,
+};
+
+export function stateToLabel(state: AccountState): AccountStateLabel {
+  return stateLabels[state];
+}
+
+export function labelToState(label: AccountStateLabel): AccountState {
+  return labelStates[label];
+}