@aspan/sdk 0.1.4

package/README.md

@@ -0,0 +1,451 @@
+# @aspan/sdk
+
+TypeScript SDK for Aspan Protocol - LST-backed stablecoin on BNB Chain.
+
+## Installation
+
+```bash
+npm install @aspan/sdk
+# or
+pnpm add @aspan/sdk
+```
+
+## Contract Addresses (BSC Mainnet)
+
+
+| Contract | Address |
+|----------|---------|
+| **Diamond (Main Entry)** | `0x10d25Ae0690533e0BA9E64EC7ae77dbD4fE8A46f` |
+| **ApUSD** | `0x1977097E2E5697A6DD91b6732F368a14F50f6B3d` |
+| **XBNB** | `0xB78eB4d5928bAb158Eb23c3154544084cD2661d5` |
+| **SApUSD** | `0xE2BE739C4aA4126ee72D612d9548C38B1B0e5A1b` |
+| **SlisBNBAdapter** | `0x1B0b8001624CC67031f1c30cCDC12fBdD5752376` |
+
+## Quick Start
+
+```typescript
+import { createAspanReadClient, formatAmount, formatCR } from "@aspan/sdk";
+
+const DIAMOND = "0xa67e91ebbb709516c563bcf1d9dae355aaf6d2ef";
+const client = createAspanReadClient(DIAMOND, "https://bsc-dataseed.binance.org/");
+
+const stats = await client.getProtocolStats();
+console.log("TVL:", formatAmount(stats.tvlInUSD), "USD");
+console.log("CR:", formatCR(stats.collateralRatio));
+```
+
+---
+
+## User Flows
+
+### Flow 1: Mint apUSD (Stablecoin)
+
+User deposits LST (e.g., slisBNB) to mint apUSD stablecoin.
+
+```typescript
+import { createAspanClient, parseAmount } from "@aspan/sdk";
+import { privateKeyToAccount } from "viem/accounts";
+import { erc20Abi } from "viem";
+
+const account = privateKeyToAccount("0x...");
+const client = createAspanClient(DIAMOND, account);
+
+const SLISBNB = "0xB0b84D294e0C75A6abe60171b70edEb2EFd14A1B";
+const lstAmount = parseAmount("10"); // 10 slisBNB
+
+// Step 1: Check LST is supported
+const isSupported = await client.isLSTSupported(SLISBNB);
+if (!isSupported) throw new Error("LST not supported");
+
+// Step 2: Check current fees
+const fees = await client.getCurrentFees();
+console.log("Mint fee:", fees.apUSDMintFee / 100, "%");
+if (fees.apUSDMintDisabled) throw new Error("Minting disabled in current CR");
+
+// Step 3: Approve LST spending (use viem directly)
+// await walletClient.writeContract({
+//   address: SLISBNB,
+//   abi: erc20Abi,
+//   functionName: "approve",
+//   args: [DIAMOND, lstAmount],
+// });
+
+// Step 4: Mint apUSD
+const hash = await client.mintApUSD({ lstToken: SLISBNB, lstAmount });
+const receipt = await client.waitForTransaction(hash);
+console.log("Minted apUSD:", receipt.status);
+```
+
+### Flow 2: Redeem apUSD for LST
+
+User burns apUSD to get back LST.
+
+```typescript
+const apUSDAmount = parseAmount("5000"); // 5000 apUSD
+
+// Step 1: Check available LST liquidity
+const collateral = await client.getLSTCollateral(SLISBNB);
+const lstPrice = await client.getLSTPriceUSD(SLISBNB);
+const maxRedeemable = (collateral * lstPrice) / parseAmount("1");
+console.log("Max redeemable:", formatAmount(maxRedeemable), "USD");
+
+// Step 2: Approve apUSD spending (use viem directly)
+// Step 3: Redeem
+const hash = await client.redeemApUSD({ lstToken: SLISBNB, apUSDAmount });
+await client.waitForTransaction(hash);
+```
+
+### Flow 3: Mint xBNB (Leveraged Long)
+
+User deposits LST to mint xBNB, a leveraged long position on BNB.
+
+```typescript
+// Step 1: Check xBNB price and leverage
+const xBNBPrice = await client.getXBNBPriceBNB();
+const leverage = await client.getEffectiveLeverage();
+console.log("xBNB Price:", formatAmount(xBNBPrice), "BNB");
+console.log("Effective Leverage:", formatAmount(leverage), "x");
+
+// Step 2: Check if xBNB is underwater (price = 0)
+if (xBNBPrice === 0n) {
+  throw new Error("xBNB underwater - cannot mint");
+}
+
+// Step 3: Approve LST, then mint xBNB
+const hash = await client.mintXBNB({ lstToken: SLISBNB, lstAmount });
+await client.waitForTransaction(hash);
+```
+
+### Flow 4: Stake apUSD to Earn Yield (sApUSD)
+
+User deposits apUSD to stability pool to earn LST yield.
+
+```typescript
+// Step 1: Check stability pool stats
+const poolStats = await client.getStabilityPoolStats();
+console.log("Total Staked:", formatAmount(poolStats.totalStaked));
+console.log("Exchange Rate:", formatAmount(poolStats.exchangeRate));
+
+// Step 2: Preview deposit
+const depositAmount = parseAmount("1000");
+const expectedShares = await client.previewDeposit(depositAmount);
+console.log("Expected shares:", formatAmount(expectedShares));
+
+// Step 3: Approve apUSD, then deposit
+const hash = await client.deposit({ apUSDAmount: depositAmount });
+await client.waitForTransaction(hash);
+
+// Step 4: Check position
+const position = await client.getUserStabilityPoolPosition(account.address);
+console.log("Shares:", formatAmount(position.shares));
+console.log("Balance (incl. yield):", formatAmount(position.balance));
+```
+
+### Flow 5: Withdraw from Stability Pool
+
+User withdraws their staked apUSD plus accumulated yield.
+
+```typescript
+// Step 1: Get user's shares
+const shares = await client.getShares(account.address);
+
+// Step 2: Preview redemption
+const expectedAssets = await client.previewRedeem(shares);
+console.log("Expected apUSD:", formatAmount(expectedAssets));
+
+// Step 3: Approve sApUSD shares transfer
+// const sApUSD = await client.getSApUSD();
+
+// Step 4: Withdraw all shares
+const hash = await client.withdraw({ shares });
+await client.waitForTransaction(hash);
+
+// Or withdraw specific amount of apUSD:
+// const hash = await client.withdrawAssets({ assets: parseAmount("500") });
+```
+
+### Flow 6: Manual Yield Harvest
+
+Anyone can trigger yield harvest to distribute pending LST yield.
+
+```typescript
+// Step 1: Check pending yield
+const yieldStats = await client.getYieldStats();
+console.log("Pending yield:", formatAmount(yieldStats.pendingYield), "USD");
+console.log("Preview harvest:", formatAmount(yieldStats.previewedHarvest), "USD");
+
+// Step 2: Harvest (if there's yield)
+if (yieldStats.pendingYield + yieldStats.previewedHarvest > 0n) {
+  const hash = await client.harvestYield();
+  await client.waitForTransaction(hash);
+}
+```
+
+---
+
+## Protocol Metrics Guide
+
+Based on protocol-analysis.md, here's how to read all key metrics:
+
+### Core Metrics (Section 3: Core Math Model)
+
+| Metric | SDK Method | Description |
+|--------|------------|-------------|
+| **TVL** | `getTVLInUSD()` | Total Value Locked in USD |
+| **TVL (BNB)** | `getTVLInBNB()` | TVL in BNB terms |
+| **apUSD Supply** | `getApUSDSupply()` | Total apUSD minted |
+| **xBNB Supply** | `getXBNBSupply()` | Total xBNB minted |
+
+```typescript
+const stats = await client.getProtocolStats();
+// stats.tvlInUSD - TVL = sum of all LST collateral value
+// stats.apUSDSupply - stable portion of the pool
+// stats.xBNBSupply - leveraged long portion
+```
+
+### xBNB Price (Section 3.3 & 4)
+
+| Metric | SDK Method | Formula |
+|--------|------------|---------|
+| **xBNB Price (BNB)** | `getXBNBPriceBNB()` | `(TVL_BNB - apUSD_value_BNB) / xBNB_supply` |
+| **xBNB Price (USD)** | `getXBNBPriceUSD()` | `xBNB_price_BNB * BNB_price_USD` |
+
+```typescript
+const xBNBPriceBNB = await client.getXBNBPriceBNB();
+const xBNBPriceUSD = await client.getXBNBPriceUSD();
+// Price = 0 means xBNB is "underwater" (TVL <= apUSD value)
+```
+
+### Collateral Ratio (Section 7)
+
+| Metric | SDK Method | Formula |
+|--------|------------|---------|
+| **CR** | `getCollateralRatio()` | `(TVL_USD / apUSD_supply) * 10000` (BPS) |
+
+```typescript
+const cr = await client.getCollateralRatio();
+// CR in BPS: 15000 = 150%, 13000 = 130%, 10000 = 100%
+console.log("CR:", Number(cr) / 100, "%");
+```
+
+### Effective Leverage (Section 5)
+
+| Metric | SDK Method | Formula |
+|--------|------------|---------|
+| **Leverage** | `getEffectiveLeverage()` | `TVL / xBNB_market_cap` |
+
+```typescript
+const leverage = await client.getEffectiveLeverage();
+// 1e18 = 1x, 2e18 = 2x leverage
+console.log("Leverage:", formatAmount(leverage), "x");
+```
+
+### Stability Mode (Section 8)
+
+| Mode | CR Range | Description |
+|------|----------|-------------|
+| **Normal (0)** | CR >= 150% | Standard operations |
+| **Mode 1 (1)** | 130% <= CR < 150% | Fee adjustments active |
+| **Mode 2 (2)** | CR < 130% | Forced conversion possible |
+
+```typescript
+const mode = await client.getStabilityMode();
+// mode.mode: 0=Normal, 1=StabilityMode1, 2=StabilityMode2
+// mode.currentCR: Current CR in BPS
+
+const mode2Info = await client.canTriggerStabilityMode2();
+// mode2Info.canTrigger: true if CR < 130%
+// mode2Info.potentialConversion: apUSD that would be converted
+```
+
+### Fee Tiers (Section 8.2)
+
+| Mode | apUSD Mint | apUSD Redeem | xBNB Mint | xBNB Redeem |
+|------|------------|--------------|-----------|-------------|
+| Normal | 0.2% | 0.2% | 1% | 1% |
+| Mode 1 | 0.3% | 0.1% | 0.25% | 4% |
+| Mode 2 | **Disabled** | 0% | 0% | 8% |
+
+```typescript
+const fees = await client.getCurrentFees();
+// fees.currentCR - Current CR
+// fees.tierMinCR - Tier threshold
+// fees.apUSDMintFee - in BPS (20 = 0.2%)
+// fees.apUSDMintDisabled - true in Mode 2
+```
+
+### Stability Pool / Yield (Section 6)
+
+| Metric | SDK Method | Description |
+|--------|------------|-------------|
+| **Total Staked** | `getTotalStaked()` | apUSD in stability pool |
+| **Exchange Rate** | `getExchangeRate()` | sApUSD to apUSD ratio |
+| **Pending Yield** | `getPendingYield()` | Yield waiting to be distributed |
+| **Total Generated** | `getTotalYieldGenerated()` | All-time yield |
+
+```typescript
+const poolStats = await client.getStabilityPoolStats();
+const yieldStats = await client.getYieldStats();
+
+// APY calculation (Section 6.2-6.3)
+// APY = LST_yield_rate * (TVL / staked_apUSD)
+const amplification = stats.tvlInUSD / poolStats.totalStaked;
+const estimatedAPY = 0.08 * Number(amplification); // Assuming 8% LST yield
+```
+
+### LST Information
+
+```typescript
+// Get all supported LSTs
+const lsts = await client.getSupportedLSTs();
+
+for (const lst of lsts) {
+  const info = await client.getLSTInfo(lst);
+  const price = await client.getLSTPriceUSD(lst);
+  const collateral = await client.getLSTCollateral(lst);
+  const yieldInfo = await client.getLSTYieldInfo(lst);
+
+  console.log(`LST: ${lst}`);
+  console.log(`  Accepted: ${info.isAccepted}`);
+  console.log(`  Collateral: ${formatAmount(collateral)}`);
+  console.log(`  Price: $${formatAmount(price)}`);
+  console.log(`  Exchange Rate: ${formatAmount(yieldInfo.lastExchangeRate)}`);
+}
+```
+
+### Oracle / Prices
+
+```typescript
+const bnbPrice = await client.getBNBPriceUSD();
+console.log("BNB Price:", formatPriceUSD(bnbPrice));
+// Note: BNB price is 8 decimals (Chainlink format)
+
+const lstPrice = await client.getLSTPriceUSD(SLISBNB);
+console.log("LST Price:", formatAmount(lstPrice), "USD");
+// Note: LST price is 18 decimals
+```
+
+---
+
+## Complete Dashboard Example
+
+```typescript
+import {
+  createAspanReadClient,
+  formatAmount,
+  formatCR,
+  formatFeeBPS,
+  formatPriceUSD,
+} from "@aspan/sdk";
+
+const DIAMOND = "0xa67e91ebbb709516c563bcf1d9dae355aaf6d2ef";
+const client = createAspanReadClient(DIAMOND);
+
+async function displayDashboard() {
+  // === Protocol Overview ===
+  const stats = await client.getProtocolStats();
+  const mode = await client.getStabilityMode();
+  const fees = await client.getCurrentFees();
+
+  console.log("=== Aspan Protocol Dashboard ===");
+  console.log(`TVL: $${formatAmount(stats.tvlInUSD)}`);
+  console.log(`CR: ${formatCR(stats.collateralRatio)}`);
+  console.log(`Stability Mode: ${mode.mode === 0 ? "Normal" : `Mode ${mode.mode}`}`);
+  console.log(`Effective Leverage: ${formatAmount(stats.effectiveLeverage)}x`);
+
+  // === Token Stats ===
+  console.log("\n=== Tokens ===");
+  console.log(`apUSD Supply: ${formatAmount(stats.apUSDSupply)}`);
+  console.log(`xBNB Supply: ${formatAmount(stats.xBNBSupply)}`);
+  console.log(`xBNB Price: ${formatAmount(stats.xBNBPriceBNB)} BNB`);
+
+  // === Current Fees ===
+  console.log("\n=== Current Fees ===");
+  console.log(`apUSD Mint: ${formatFeeBPS(fees.apUSDMintFee)}${fees.apUSDMintDisabled ? " (DISABLED)" : ""}`);
+  console.log(`apUSD Redeem: ${formatFeeBPS(fees.apUSDRedeemFee)}`);
+  console.log(`xBNB Mint: ${formatFeeBPS(fees.xBNBMintFee)}`);
+  console.log(`xBNB Redeem: ${formatFeeBPS(fees.xBNBRedeemFee)}`);
+
+  // === Stability Pool ===
+  const poolStats = await client.getStabilityPoolStats();
+  const yieldStats = await client.getYieldStats();
+
+  console.log("\n=== Stability Pool (sApUSD) ===");
+  console.log(`Total Staked: ${formatAmount(poolStats.totalStaked)} apUSD`);
+  console.log(`Exchange Rate: ${formatAmount(poolStats.exchangeRate)}`);
+  console.log(`Pending Yield: $${formatAmount(yieldStats.pendingYield)}`);
+  console.log(`Total Yield Generated: $${formatAmount(yieldStats.totalYieldGenerated)}`);
+
+  // === LST Collateral ===
+  const lsts = await client.getSupportedLSTs();
+  console.log("\n=== LST Collateral ===");
+  for (const lst of lsts) {
+    const collateral = await client.getLSTCollateral(lst);
+    const price = await client.getLSTPriceUSD(lst);
+    const value = (collateral * price) / 10n ** 18n;
+    console.log(`${lst.slice(0, 10)}...: ${formatAmount(collateral)} ($${formatAmount(value)})`);
+  }
+}
+
+displayDashboard();
+```
+
+---
+
+## API Reference
+
+### View Functions
+
+| Category | Methods |
+|----------|---------|
+| **Stats** | `getProtocolStats()`, `getStabilityPoolStats()`, `getYieldStats()` |
+| **Pool** | `getTVLInBNB()`, `getTVLInUSD()`, `getCollateralRatio()`, `getXBNBPriceBNB()`, `getXBNBPriceUSD()`, `getEffectiveLeverage()`, `getApUSDSupply()`, `getXBNBSupply()`, `getLSTCollateral()`, `getCurrentFees()` |
+| **Stability Pool** | `getShares()`, `getBalance()`, `getUserStabilityPoolPosition()`, `getExchangeRate()`, `getTotalStaked()`, `previewDeposit()`, `previewRedeem()`, `getPendingYield()` |
+| **Yield** | `getTotalYieldGenerated()`, `getLSTYieldInfo()`, `getMinHarvestInterval()`, `getLastHarvestTimestamp()`, `previewHarvest()` |
+| **Oracle** | `getBNBPriceUSD()`, `getLSTPriceUSD()`, `getLSTInfo()`, `getSupportedLSTs()`, `isLSTSupported()`, `getBNBPriceFeed()`, `getOracleBounds()` |
+| **Config** | `getTokens()`, `getSApUSD()`, `getStabilityPool()`, `getTreasury()`, `getFeeTierCount()`, `getFeeTier()`, `getCurrentFeeTier()`, `getMaxPriceAge()`, `getMinDepositPeriod()`, `isPaused()` |
+| **Stability Mode** | `getStabilityMode()`, `canTriggerStabilityMode2()` |
+| **Ownership** | `getOwner()` |
+
+### Write Functions
+
+| Category | Methods |
+|----------|---------|
+| **Pool** | `mintApUSD()`, `redeemApUSD()`, `mintXBNB()`, `redeemXBNB()` |
+| **Stability Pool** | `deposit()`, `withdraw()`, `withdrawAssets()`, `harvestYield()` |
+
+---
+
+## Utility Functions
+
+```typescript
+import {
+  formatAmount,     // bigint -> "1234.5678"
+  parseAmount,      // "1234.5678" -> bigint
+  formatFeeBPS,     // 25 -> "0.25%"
+  formatCR,         // 15000n -> "150%"
+  formatPriceUSD,   // 58325000000n -> "$583.25"
+  calculateAPY,     // (oldRate, newRate, days) -> APY%
+  PRECISION,        // 10^18
+  BPS_PRECISION,    // 10000
+  PRICE_PRECISION,  // 10^8
+} from "@aspan/sdk";
+```
+
+---
+
+## Testnet
+
+```typescript
+import {
+  createAspanTestnetReadClient,
+  createAspanTestnetClient,
+} from "@aspan/sdk";
+
+const client = createAspanTestnetReadClient("0x...");
+const writeClient = createAspanTestnetClient("0x...", account);
+```
+
+## License
+
+MIT