@aspan/sdk 0.1.4

package/src/index.ts

@@ -0,0 +1,144 @@
+/**
+ * Aspan SDK
+ * TypeScript SDK for interacting with the Aspan Protocol on BNB Chain
+ *
+ * @packageDocumentation
+ */
+
+// ============ Client Classes ============
+export {
+  AspanReadClient,
+  AspanClient,
+  createAspanReadClient,
+  createAspanClient,
+  createAspanTestnetReadClient,
+  createAspanTestnetClient,
+  type AspanClientConfig,
+  type AspanWriteClientConfig,
+} from "./client";
+
+// ============ Types ============
+export type {
+  // Core types
+  BigIntString,
+  TokenAddresses,
+  LSTInfo,
+  LSTYieldInfo,
+  FeeTier,
+  CurrentFeeTier,
+  CurrentFees,
+  OracleBounds,
+  StabilityModeInfo,
+  StabilityMode2Info,
+  // Stats
+  ProtocolStats,
+  StabilityPoolStats,
+  YieldStats,
+  UserStabilityPoolPosition,
+  // Transaction params
+  MintApUSDParams,
+  RedeemApUSDParams,
+  MintXBNBParams,
+  RedeemXBNBParams,
+  DepositParams,
+  WithdrawParams,
+  WithdrawAssetsParams,
+  // Events
+  ApUSDMintedEvent,
+  ApUSDRedeemedEvent,
+  XBNBMintedEvent,
+  XBNBRedeemedEvent,
+  DepositedEvent,
+  WithdrawnEvent,
+  YieldHarvestedEvent,
+  // Transaction result
+  TransactionResult,
+  TransactionReceipt,
+} from "./types";
+
+// ============ ABI ============
+export { DiamondABI } from "./abi/diamond";
+
+// ============ Constants ============
+export const PRECISION = 10n ** 18n;
+export const BPS_PRECISION = 10000n;
+export const PRICE_PRECISION = 10n ** 8n; // Chainlink price precision
+
+// ============ Utility Functions ============
+
+/**
+ * Format a bigint amount to human-readable string with decimals
+ * @param amount Amount in wei (18 decimals)
+ * @param decimals Number of decimal places to show
+ * @returns Formatted string
+ */
+export function formatAmount(amount: bigint, decimals: number = 4): string {
+  const divisor = 10n ** BigInt(18 - decimals);
+  const scaled = amount / divisor;
+  const intPart = scaled / 10n ** BigInt(decimals);
+  const fracPart = scaled % 10n ** BigInt(decimals);
+  return `${intPart}.${fracPart.toString().padStart(decimals, "0")}`;
+}
+
+/**
+ * Parse a human-readable amount to bigint (18 decimals)
+ * @param amount Human-readable amount string
+ * @returns Amount in wei
+ */
+export function parseAmount(amount: string): bigint {
+  const [intPart, fracPart = ""] = amount.split(".");
+  const paddedFrac = fracPart.padEnd(18, "0").slice(0, 18);
+  return BigInt(intPart) * PRECISION + BigInt(paddedFrac);
+}
+
+/**
+ * Format a fee in basis points to percentage string
+ * @param bps Fee in basis points
+ * @returns Percentage string (e.g., "0.25%")
+ */
+export function formatFeeBPS(bps: number): string {
+  return `${(bps / 100).toFixed(2)}%`;
+}
+
+/**
+ * Format collateral ratio to percentage string
+ * @param cr Collateral ratio (18 decimals, 1e18 = 100%)
+ * @returns Percentage string (e.g., "150%")
+ */
+export function formatCR(cr: bigint): string {
+  const percentage = (cr * 100n) / PRECISION;
+  return `${percentage}%`;
+}
+
+/**
+ * Format price (8 decimals) to USD string
+ * @param price Price in 8 decimals
+ * @returns USD string (e.g., "$583.25")
+ */
+export function formatPriceUSD(price: bigint): string {
+  const dollars = price / PRICE_PRECISION;
+  const cents = (price % PRICE_PRECISION) / 10n ** 6n;
+  return `$${dollars}.${cents.toString().padStart(2, "0")}`;
+}
+
+/**
+ * Calculate effective APY from exchange rate change
+ * @param previousRate Previous exchange rate
+ * @param currentRate Current exchange rate
+ * @param periodDays Number of days between rates
+ * @returns Annualized percentage yield
+ */
+export function calculateAPY(
+  previousRate: bigint,
+  currentRate: bigint,
+  periodDays: number
+): number {
+  if (previousRate === 0n || periodDays === 0) return 0;
+
+  const rateChange =
+    Number((currentRate - previousRate) * 10000n) / Number(previousRate);
+  const dailyRate = rateChange / periodDays;
+  const annualizedRate = dailyRate * 365;
+
+  return annualizedRate / 100; // Convert from percentage basis points
+}

package/src/types.ts

@@ -0,0 +1,237 @@
+/**
+ * Aspan SDK Type Definitions
+ */
+
+import type { Address, Hash } from "viem";
+
+// ============ Core Types ============
+
+/** BigInt formatted as string for serialization */
+export type BigIntString = string;
+
+/** Token addresses */
+export interface TokenAddresses {
+  apUSD: Address;
+  xBNB: Address;
+  sApUSD: Address;
+}
+
+/** LST (Liquid Staking Token) info */
+export interface LSTInfo {
+  isAccepted: boolean;
+  priceFeed: Address;
+  manualPriceUSD: bigint;
+  collateralAmount: bigint;
+  decimals: number;
+  exchangeRateProvider: Address;
+  useIntrinsicValue: boolean;
+}
+
+/** LST yield tracking info */
+export interface LSTYieldInfo {
+  lastExchangeRate: bigint;
+  lastUpdateTimestamp: bigint;
+}
+
+/** Fee tier configuration */
+export interface FeeTier {
+  minCR: bigint;
+  apUSDMintFee: number;
+  apUSDRedeemFee: number;
+  xBNBMintFee: number;
+  xBNBRedeemFee: number;
+  apUSDMintDisabled: boolean;
+}
+
+/** Current fee tier with CR */
+export interface CurrentFeeTier extends FeeTier {
+  currentCR: bigint;
+}
+
+/** Current fees with tier info */
+export interface CurrentFees {
+  currentCR: bigint;
+  tierMinCR: bigint;
+  apUSDMintFee: number;
+  apUSDRedeemFee: number;
+  xBNBMintFee: number;
+  xBNBRedeemFee: number;
+  apUSDMintDisabled: boolean;
+}
+
+/** Oracle bounds */
+export interface OracleBounds {
+  minPrice: bigint;
+  maxPrice: bigint;
+}
+
+/** Stability mode info */
+export interface StabilityModeInfo {
+  mode: number;
+  currentCR: bigint;
+}
+
+/** Stability mode 2 trigger info */
+export interface StabilityMode2Info {
+  canTrigger: boolean;
+  currentCR: bigint;
+  potentialConversion: bigint;
+}
+
+/** Stability mode 2 trigger result */
+export interface StabilityMode2Result {
+  apUSDBurned: bigint;
+  xBNBMinted: bigint;
+}
+
+// ============ Transaction Parameters ============
+
+/** Parameters for minting apUSD */
+export interface MintApUSDParams {
+  lstToken: Address;
+  lstAmount: bigint;
+}
+
+/** Parameters for redeeming apUSD */
+export interface RedeemApUSDParams {
+  lstToken: Address;
+  apUSDAmount: bigint;
+}
+
+/** Parameters for minting xBNB */
+export interface MintXBNBParams {
+  lstToken: Address;
+  lstAmount: bigint;
+}
+
+/** Parameters for redeeming xBNB */
+export interface RedeemXBNBParams {
+  lstToken: Address;
+  xBNBAmount: bigint;
+}
+
+/** Parameters for depositing to stability pool */
+export interface DepositParams {
+  apUSDAmount: bigint;
+}
+
+/** Parameters for withdrawing from stability pool */
+export interface WithdrawParams {
+  shares: bigint;
+}
+
+/** Parameters for withdrawing assets from stability pool */
+export interface WithdrawAssetsParams {
+  assets: bigint;
+}
+
+// ============ Protocol Stats ============
+
+/** Overall protocol statistics */
+export interface ProtocolStats {
+  tvlInBNB: bigint;
+  tvlInUSD: bigint;
+  collateralRatio: bigint;
+  apUSDSupply: bigint;
+  xBNBSupply: bigint;
+  xBNBPriceBNB: bigint;
+  xBNBPriceUSD: bigint;
+  effectiveLeverage: bigint;
+}
+
+/** Stability pool statistics */
+export interface StabilityPoolStats {
+  totalStaked: bigint;
+  exchangeRate: bigint;
+  pendingYield: bigint;
+}
+
+/** Yield statistics */
+export interface YieldStats {
+  totalYieldGenerated: bigint;
+  pendingYield: bigint;
+  lastHarvestTimestamp: bigint;
+  minHarvestInterval: bigint;
+  previewedHarvest: bigint;
+}
+
+// ============ User Position ============
+
+/** User's position in the stability pool */
+export interface UserStabilityPoolPosition {
+  shares: bigint;
+  balance: bigint;
+}
+
+// ============ Event Types ============
+
+/** ApUSD minted event */
+export interface ApUSDMintedEvent {
+  user: Address;
+  lstToken: Address;
+  lstAmount: bigint;
+  apUSDAmount: bigint;
+  feeBPS: bigint;
+}
+
+/** ApUSD redeemed event */
+export interface ApUSDRedeemedEvent {
+  user: Address;
+  lstToken: Address;
+  apUSDAmount: bigint;
+  lstAmount: bigint;
+  feeBPS: bigint;
+}
+
+/** xBNB minted event */
+export interface XBNBMintedEvent {
+  user: Address;
+  lstToken: Address;
+  lstAmount: bigint;
+  xBNBAmount: bigint;
+  feeBPS: bigint;
+}
+
+/** xBNB redeemed event */
+export interface XBNBRedeemedEvent {
+  user: Address;
+  lstToken: Address;
+  xBNBAmount: bigint;
+  lstAmount: bigint;
+  feeBPS: bigint;
+}
+
+/** Deposited to stability pool event */
+export interface DepositedEvent {
+  user: Address;
+  apUSDAmount: bigint;
+  sharesReceived: bigint;
+}
+
+/** Withdrawn from stability pool event */
+export interface WithdrawnEvent {
+  user: Address;
+  sharesRedeemed: bigint;
+  apUSDReceived: bigint;
+}
+
+/** Yield harvested event */
+export interface YieldHarvestedEvent {
+  yieldUSD: bigint;
+}
+
+// ============ Transaction Result ============
+
+/** Result of a transaction */
+export interface TransactionResult {
+  hash: Hash;
+  wait: () => Promise<TransactionReceipt>;
+}
+
+/** Transaction receipt */
+export interface TransactionReceipt {
+  blockHash: Hash;
+  blockNumber: bigint;
+  transactionHash: Hash;
+  status: "success" | "reverted";
+}