@aspan/sdk 0.3.1 → 0.4.0

package/README.md

@@ -12,26 +12,30 @@ pnpm add @aspan/sdk
 
 ## Contract Addresses (BSC Mainnet)
 
+```typescript
+import { BSC_ADDRESSES } from "@aspan/sdk";
+
+// Or use directly:
+// BSC_ADDRESSES.diamond, BSC_ADDRESSES.router, etc.
+```
 
 | Contract | Address |
 |----------|---------|
 | **Diamond (Main Entry)** | `0x10d25Ae0690533e0BA9E64EC7ae77dbD4fE8A46f` |
-| **Router** | `0x159B2990966B0E4f07cD58c9Def513EA1fF81c0C` |
-| **wclisBNB** | `0x439faaC2229559121C4Ad4fd8B3FE13Dff038046` |
+| **Router** | `0x813d3D1A3154950E2f1d8718305426a335A974A9` |
 | **ApUSD** | `0x1977097E2E5697A6DD91b6732F368a14F50f6B3d` |
 | **XBNB** | `0xB78eB4d5928bAb158Eb23c3154544084cD2661d5` |
 | **SApUSD** | `0xE2BE739C4aA4126ee72D612d9548C38B1B0e5A1b` |
-| **SlisBNBAdapter** | `0x1B0b8001624CC67031f1c30cCDC12fBdD5752376` |
+| **wclisBNB** | `0x439faaC2229559121C4Ad4fd8B3FE13Dff038046` |
 
 ## Quick Start
 
 ### Read-Only Client (Query Data)
 
 ```typescript
-import { createAspanReadClient, formatAmount, formatCR } from "@aspan/sdk";
+import { createAspanReadClient, formatAmount, formatCR, BSC_ADDRESSES } from "@aspan/sdk";
 
-const DIAMOND = "0x10d25Ae0690533e0BA9E64EC7ae77dbD4fE8A46f";
-const client = createAspanReadClient(DIAMOND, "https://bsc-dataseed.binance.org/");
+const client = createAspanReadClient(BSC_ADDRESSES.diamond, "https://bsc-dataseed.binance.org/");
 
 const stats = await client.getProtocolStats();
 console.log("TVL:", formatAmount(stats.tvlInUSD), "USD");
@@ -41,19 +45,17 @@ console.log("CR:", formatCR(stats.collateralRatio));
 ### Write Client - Browser (React/wagmi)
 
 ```typescript
-import { AspanClient } from "@aspan/sdk";
+import { AspanClient, BSC_ADDRESSES } from "@aspan/sdk";
 import { useWalletClient } from "wagmi";
 
-const DIAMOND = "0x10d25Ae0690533e0BA9E64EC7ae77dbD4fE8A46f";
-
 function MyComponent() {
   const { data: walletClient } = useWalletClient();
 
   const getClient = () => {
     if (!walletClient) return null;
     return new AspanClient({
-      diamondAddress: DIAMOND,
-      walletClient: walletClient,  // Pass wagmi's walletClient
+      diamondAddress: BSC_ADDRESSES.diamond,
+      walletClient: walletClient,
     });
   };
 
@@ -62,7 +64,7 @@ function MyComponent() {
     if (!client) return;
     
     const hash = await client.mintApUSD({
-      lstToken: "0xB0b84D294e0C75A6abe60171b70edEb2EFd14A1B",
+      lstToken: BSC_ADDRESSES.slisBNB,
       lstAmount: parseAmount("1"),
     });
     console.log("Tx hash:", hash);
@@ -73,14 +75,14 @@ function MyComponent() {
 ### Write Client - Node.js / Server
 
 ```typescript
-import { createAspanClient, parseAmount } from "@aspan/sdk";
+import { createAspanClient, parseAmount, BSC_ADDRESSES } from "@aspan/sdk";
 import { privateKeyToAccount } from "viem/accounts";
 
 const account = privateKeyToAccount("0x...");
-const client = createAspanClient(DIAMOND, account);
+const client = createAspanClient(BSC_ADDRESSES.diamond, account);
 
 const hash = await client.mintApUSD({
-  lstToken: "0xB0b84D294e0C75A6abe60171b70edEb2EFd14A1B",
+  lstToken: BSC_ADDRESSES.slisBNB,
   lstAmount: parseAmount("1"),
 });
 ```
@@ -94,41 +96,37 @@ AspanRouter is a periphery contract that enables users to mint/redeem apUSD or x
 ### Router Client Setup
 
 ```typescript
-import { createRouterClient, AspanRouterClient } from "@aspan/sdk";
+import { createRouterClient, AspanRouterClient, BSC_ADDRESSES } from "@aspan/sdk";
 import { privateKeyToAccount } from "viem/accounts";
-import { zeroAddress } from "viem";
-
-const ROUTER = "0x159B2990966B0E4f07cD58c9Def513EA1fF81c0C";
 
 // Node.js
 const account = privateKeyToAccount("0x...");
-const router = createRouterClient(ROUTER, account);
+const router = createRouterClient(BSC_ADDRESSES.router, account);
 
 // Browser (wagmi)
 const router = new AspanRouterClient({
-  routerAddress: ROUTER,
+  routerAddress: BSC_ADDRESSES.router,
   walletClient,  // from useWalletClient()
 });
 ```
 
-### Swap USDT/USDC → apUSD (One-Click)
+### Swap USDT/USDC → apUSD or xBNB (One-Click)
 
 ```typescript
-import { parseAmount, type SwapAndMintParams } from "@aspan/sdk";
+import { parseAmount, BSC_ADDRESSES, type SwapAndMintParams } from "@aspan/sdk";
 import { zeroAddress } from "viem";
 
-const USDT = "0x55d398326f99059fF775485246999027B3197955";
-
 // Full control with SwapParams + MintParams
 const params: SwapAndMintParams = {
   swapParams: {
-    inputToken: USDT,
+    inputToken: BSC_ADDRESSES.USDT,
     inputAmount: parseAmount("100"),  // 100 USDT
     targetLST: zeroAddress,           // Use default LST
     minLSTOut: 0n,                    // Or set slippage protection
     poolFee: 2500,                    // 0.25% V3 pool fee
   },
   mintParams: {
+    mintXBNB: false,                  // false = apUSD, true = xBNB
     minMintOut: parseAmount("99"),    // Min 99 apUSD (1% slippage)
     recipient: zeroAddress,           // Send to msg.sender
     deadline: BigInt(Math.floor(Date.now() / 1000) + 3600),
@@ -136,77 +134,56 @@ const params: SwapAndMintParams = {
 };
 
 // Approve USDT first, then swap+mint
-const hash = await router.swapAndMintApUSD(params);
+const hash = await router.swapAndMint(params);
 await router.waitForTransaction(hash);
 ```
 
-### Simplified: Swap → apUSD (Default LST)
+### Simplified: Swap → apUSD/xBNB (Default LST)
 
 ```typescript
-// Simpler API using default LST and V2
-const hash = await router.swapAndMintApUSDDefault({
-  inputToken: USDT,
+// Simpler API using default LST
+const hash = await router.swapAndMintDefault({
+  inputToken: BSC_ADDRESSES.USDT,
   inputAmount: parseAmount("100"),
+  mintXBNB: false,                    // false = apUSD, true = xBNB
   minMintOut: parseAmount("99"),
   deadline: BigInt(Math.floor(Date.now() / 1000) + 3600),
 });
 ```
 
-### Stake Native BNB → apUSD (Bypasses DEX)
+### Stake Native BNB → apUSD/xBNB (Bypasses DEX)
 
 Direct BNB staking gets better rates for large amounts by bypassing DEX.
 
 ```typescript
-// Stake BNB directly to Lista/Astherus → mint apUSD
-const hash = await router.stakeAndMintApUSD(
-  parseAmount("99"),    // minMintOut
-  parseAmount("1"),     // 1 BNB to stake (sent as value)
-);
-
-// Or with full control
+// Stake BNB directly to Lista/Astherus → mint apUSD or xBNB
 const hash = await router.stakeAndMint({
-  targetLST: "0xB0b84D294e0C75A6abe60171b70edEb2EFd14A1B", // slisBNB
-  isXBNB: false,
+  targetLST: BSC_ADDRESSES.slisBNB,
+  isXBNB: false,                      // false = apUSD, true = xBNB
   minMintOut: parseAmount("99"),
   deadline: BigInt(Math.floor(Date.now() / 1000) + 3600),
-  value: parseAmount("1"),  // 1 BNB
-});
-```
-
-### Swap → xBNB (Leveraged Long)
-
-```typescript
-// Full params
-const hash = await router.swapAndMintXBNB(params);
-
-// Or simplified
-const hash = await router.swapAndMintXBNBDefault({
-  inputToken: USDT,
-  inputAmount: parseAmount("1000"),
-  minMintOut: parseAmount("1"),  // Min 1 xBNB
-  deadline: BigInt(Math.floor(Date.now() / 1000) + 3600),
+  value: parseAmount("1"),            // 1 BNB
 });
-
-// Or stake BNB directly
-const hash = await router.stakeAndMintXBNB(parseAmount("1"), parseAmount("10"));
 ```
 
 ### Direct Mint/Redeem via Router
 
-If you already have LST, use direct functions (still routes through Diamond):
+If you already have LST, use direct functions:
 
 ```typescript
-// Mint apUSD with LST
-const hash = await router.mintApUSD({
-  lst: "0xB0b84D294e0C75A6abe60171b70edEb2EFd14A1B", // slisBNB
+// Mint apUSD or xBNB with LST
+const hash = await router.mint({
+  lst: BSC_ADDRESSES.slisBNB,
   lstAmount: parseAmount("10"),
+  mintXBNB: false,                    // false = apUSD, true = xBNB
   minOut: parseAmount("99"),
 });
 
-// Redeem apUSD for LST
-const hash = await router.redeemApUSD({
-  lst: "0xB0b84D294e0C75A6abe60171b70edEb2EFd14A1B",
-  apUSDAmount: parseAmount("100"),
+// Redeem apUSD or xBNB for LST
+const hash = await router.redeem({
+  lst: BSC_ADDRESSES.slisBNB,
+  redeemXBNB: false,                  // false = redeem apUSD, true = redeem xBNB
+  amount: parseAmount("100"),
   minOut: parseAmount("0.9"),
 });
 ```
@@ -214,31 +191,45 @@ const hash = await router.redeemApUSD({
 ### Redeem + Swap to USDT/BNB (V3 Path)
 
 ```typescript
-import { encodeV3Path } from "@aspan/sdk";
-
-const SLISBNB = "0xB0b84D294e0C75A6abe60171b70edEb2EFd14A1B";
-const WBNB = "0xbb4CdB9CBd36B01bD1cBaEBF2De08d9173bc095c";
-const USDT = "0x55d398326f99059fF775485246999027B3197955";
+import { encodeV3Path, BSC_ADDRESSES } from "@aspan/sdk";
 
 // Encode V3 swap path: slisBNB → WBNB → USDT
-// Use encodeV3Path helper or get optimal path from PancakeSwap Quoter
 const path = encodeV3Path(
-  [SLISBNB, WBNB, USDT],  // tokens
+  [BSC_ADDRESSES.slisBNB, BSC_ADDRESSES.WBNB, BSC_ADDRESSES.USDT],
   [500, 500]              // pool fees (0.05% each hop)
 );
 
-// Redeem apUSD and swap LST to USDT via V3 path
-const hash = await router.redeemApUSDAndSwap({
-  lst: SLISBNB,
-  amount: parseAmount("100"),      // 100 apUSD
-  path,                            // V3 encoded path
-  minOut: parseAmount("99"),       // Min 99 USDT
+// Redeem apUSD/xBNB and swap LST to output token via V3 path
+const hash = await router.redeemAndSwap({
+  lst: BSC_ADDRESSES.slisBNB,
+  redeemXBNB: false,                  // false = redeem apUSD, true = redeem xBNB
+  amount: parseAmount("100"),
+  path,
+  minOut: parseAmount("99"),
   deadline: BigInt(Math.floor(Date.now() / 1000) + 3600),
+  unwrapBNB: false,                   // true to unwrap WBNB → native BNB
 });
 ```
 
-> **Note**: For optimal swap paths and quotes, use PancakeSwap V3 Quoter contract:
-> `0xB048Bbc1Ee6b733FFfCFb9e9CeF7375518e25997` (BSC Mainnet)
+### Get Native BNB (Auto-unwrap)
+
+```typescript
+// Redeem and get native BNB (auto-unwrap WBNB)
+const path = encodeV3Path(
+  [BSC_ADDRESSES.slisBNB, BSC_ADDRESSES.WBNB],
+  [2500]  // 0.25% pool fee
+);
+
+const hash = await router.redeemAndSwap({
+  lst: BSC_ADDRESSES.slisBNB,
+  redeemXBNB: false,
+  amount: parseAmount("100"),
+  path,
+  minOut: parseAmount("0.15"),
+  deadline: BigInt(Math.floor(Date.now() / 1000) + 3600),
+  unwrapBNB: true,                    // Auto-unwrap to native BNB!
+});
+```
 
 ### Native Unstake (7-15 Day Unbonding)
 
@@ -246,9 +237,11 @@ For no-slippage BNB redemption, use Lista's native unstake:
 
 ```typescript
 // Request unstake (starts 7-15 day unbonding period)
-const hash = await router.redeemApUSDAndRequestUnstake(parseAmount("100"));
+const hash = await router.redeemAndRequestUnstake({
+  redeemXBNB: false,                  // false = redeem apUSD, true = redeem xBNB
+  amount: parseAmount("100"),
+});
 const receipt = await router.waitForTransaction(hash);
-// Parse event to get requestIndex...
 
 // Check withdrawal status
 const indices = await router.getUserWithdrawalIndices(account.address);
@@ -258,7 +251,7 @@ for (const idx of indices) {
 }
 
 // Claim BNB after unbonding
-const hash = await router.claimUnstake(requestIndex);
+const claimHash = await router.claimUnstake(requestIndex);
 ```
 
 ### Router View Functions
@@ -266,518 +259,287 @@ const hash = await router.claimUnstake(requestIndex);
 ```typescript
 // Check supported tokens
 const defaultLST = await router.getDefaultLST();
-const isSupported = await router.isSupportedInputToken(USDT);
-const isLSTSupported = await router.isSupportedLST(slisBNB);
+const isSupported = await router.isSupportedInputToken(BSC_ADDRESSES.USDT);
+const isLSTSupported = await router.isSupportedLST(BSC_ADDRESSES.slisBNB);
 
-// Preview mint/redeem with LST (accurate with fees)
-const apUSDOut = await router.previewMintApUSD(slisBNB, parseAmount("1"));
-const xBNBOut = await router.previewMintXBNB(slisBNB, parseAmount("1"));
-const lstFromApUSD = await router.previewRedeemApUSD(slisBNB, parseAmount("100"));
-const lstFromXBNB = await router.previewRedeemXBNB(slisBNB, parseAmount("10"));
+// Preview mint/redeem (accurate with fees)
+const apUSDOut = await router.previewMint(BSC_ADDRESSES.slisBNB, parseAmount("1"), false);
+const xBNBOut = await router.previewMint(BSC_ADDRESSES.slisBNB, parseAmount("1"), true);
+const lstFromApUSD = await router.previewRedeem(BSC_ADDRESSES.slisBNB, false, parseAmount("100"));
+const lstFromXBNB = await router.previewRedeem(BSC_ADDRESSES.slisBNB, true, parseAmount("10"));
 
 // Get token addresses
 const wbnb = await router.getWBNB();
 const usdt = await router.getUSDT();
 const slisBNB = await router.getSlisBNB();
-const wclisBNB = await router.getWclisBNB();
 ```
 
 ---
 
-## User Flows
-
-### Flow 1: Mint apUSD (Stablecoin)
+## Use Cases
 
-User deposits LST (e.g., slisBNB) to mint apUSD stablecoin.
+### 1. New User: USDT → apUSD (One-Click)
 
-#### Browser (React/wagmi)
+The simplest way to mint apUSD stablecoin with USDT.
 
 ```typescript
-import { AspanClient, parseAmount } from "@aspan/sdk";
-import { useWalletClient } from "wagmi";
+import { createRouterClient, parseAmount, BSC_ADDRESSES } from "@aspan/sdk";
 
-const DIAMOND = "0x10d25Ae0690533e0BA9E64EC7ae77dbD4fE8A46f";
-const SLISBNB = "0xB0b84D294e0C75A6abe60171b70edEb2EFd14A1B";
+const router = createRouterClient(BSC_ADDRESSES.router, account);
 
-function MintComponent() {
-  const { data: walletClient } = useWalletClient();
-
-  const handleMint = async () => {
-    if (!walletClient) return;
-
-    const client = new AspanClient({
-      diamondAddress: DIAMOND,
-      walletClient,
-    });
-
-    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();
-    if (fees.apUSDMintDisabled) throw new Error("Minting disabled");
-
-    // Step 3: Approve LST (use wagmi's useWriteContract or viem)
-    // ...
-
-    // Step 4: Calculate minOut for slippage protection (e.g., 0.5% slippage)
-    const expectedApUSD = lstAmount; // Simplified, use actual calculation
-    const minOut = expectedApUSD * 995n / 1000n; // 0.5% slippage
-
-    // Step 5: Mint apUSD
-    const hash = await client.mintApUSD({ lstToken: SLISBNB, lstAmount, minOut });
-    const receipt = await client.waitForTransaction(hash);
-    console.log("Minted apUSD:", receipt.status);
-  };
-}
-```
-
-#### Node.js / Server
-
-```typescript
-import { createAspanClient, parseAmount } from "@aspan/sdk";
-import { privateKeyToAccount } from "viem/accounts";
-
-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 with slippage protection
-const minOut = lstAmount * 995n / 1000n; // 0.5% slippage tolerance
-const hash = await client.mintApUSD({ lstToken: SLISBNB, lstAmount, minOut });
-const receipt = await client.waitForTransaction(hash);
-console.log("Minted apUSD:", receipt.status);
+// 100 USDT → apUSD (auto DEX swap + mint)
+const hash = await router.swapAndMintDefault({
+  inputToken: BSC_ADDRESSES.USDT,
+  inputAmount: parseAmount("100"),
+  mintXBNB: false,  // apUSD
+  minMintOut: parseAmount("99"),
+  deadline: BigInt(Math.floor(Date.now() / 1000) + 3600),
+});
 ```
 
-### Flow 2: Redeem apUSD for LST
+### 2. BNB Holder: BNB → apUSD/xBNB (Direct Stake)
 
-User burns apUSD to get back LST.
+For large BNB amounts, stake directly to Lista to avoid DEX slippage.
 
 ```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: Calculate expected LST output and set minOut
-const expectedLST = (apUSDAmount * parseAmount("1")) / lstPrice;
-const minOut = expectedLST * 995n / 1000n; // 0.5% slippage
-
-// Step 4: Redeem with slippage protection
-const hash = await client.redeemApUSD({ lstToken: SLISBNB, apUSDAmount, minOut });
-await client.waitForTransaction(hash);
+// 1 BNB → apUSD (direct stake, no DEX slippage)
+const hash = await router.stakeAndMint({
+  targetLST: BSC_ADDRESSES.slisBNB,
+  isXBNB: false,  // false = apUSD, true = xBNB
+  minMintOut: parseAmount("750"),
+  deadline: BigInt(Math.floor(Date.now() / 1000) + 3600),
+  value: parseAmount("1"),  // 1 BNB
+});
 ```
 
-### Flow 3: Mint xBNB (Leveraged Long)
+### 3. Leverage Trader: BNB → xBNB (Long BNB)
 
-User deposits LST to mint xBNB, a leveraged long position on BNB.
+xBNB is leveraged BNB exposure, ideal for bullish BNB traders.
 
 ```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");
-}
+// 1 BNB → xBNB (~1.2x leverage)
+const hash = await router.stakeAndMint({
+  targetLST: BSC_ADDRESSES.slisBNB,
+  isXBNB: true,  // xBNB
+  minMintOut: parseAmount("0.001"),
+  deadline: BigInt(Math.floor(Date.now() / 1000) + 3600),
+  value: parseAmount("1"),
+});
 
-// Step 3: Approve LST, then mint xBNB with slippage protection
-const minOut = 0n; // Set appropriate minOut based on expected xBNB output
-const hash = await client.mintXBNB({ lstToken: SLISBNB, lstAmount, minOut });
-await client.waitForTransaction(hash);
+// Check current leverage
+const stats = await client.getProtocolStats();
+console.log("xBNB Leverage:", formatAmount(stats.effectiveLeverage), "x");
 ```
 
-### Flow 4: Redeem xBNB for LST
+### 4. Yield Farming: apUSD → sApUSD (Stability Pool)
 
-User burns xBNB to get back LST.
+Deposit apUSD into the Stability Pool to earn protocol yield.
 
 ```typescript
-const xBNBAmount = parseAmount("100"); // 100 xBNB
+import { createAspanClient, parseAmount, BSC_ADDRESSES } from "@aspan/sdk";
 
-// Step 1: Check xBNB price (ensure not underwater)
-const xBNBPrice = await client.getXBNBPriceBNB();
-if (xBNBPrice === 0n) {
-  throw new Error("xBNB is underwater - redemption may result in 0 LST");
-}
-
-// Step 2: Check current fees
-const fees = await client.getCurrentFees();
-console.log("xBNB Redeem fee:", fees.xBNBRedeemFee / 100, "%");
+const client = createAspanClient(BSC_ADDRESSES.diamond, account);
 
-// Step 3: Check available LST liquidity
-const collateral = await client.getLSTCollateral(SLISBNB);
-console.log("Available collateral:", formatAmount(collateral));
+// Deposit apUSD
+const hash = await client.deposit({ apUSDAmount: parseAmount("1000") });
 
-// Step 4: Approve xBNB spending (use viem directly)
-// ...
-
-// Step 5: Calculate expected LST and set minOut for slippage protection
-const expectedLST = (xBNBAmount * xBNBPrice) / parseAmount("1");
-const minOut = expectedLST * 995n / 1000n; // 0.5% slippage
-
-// Step 6: Redeem xBNB
-const hash = await client.redeemXBNB({ lstToken: SLISBNB, xBNBAmount, minOut });
-await client.waitForTransaction(hash);
+// Check earnings
+const position = await client.getUserStabilityPoolPosition(account.address);
+console.log("sApUSD Balance:", formatAmount(position.balance));
+console.log("Earned:", formatAmount(position.balance - position.deposited));
 ```
 
-### Flow 5: Stake apUSD to Earn Yield (sApUSD)
+### 5. Quick Exit: apUSD/xBNB → USDT
 
-User deposits apUSD to stability pool to earn LST yield.
+Exit to USDT via DEX swap when you need liquidity fast.
 
 ```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));
+import { encodeV3Path, BSC_ADDRESSES } from "@aspan/sdk";
 
-// Step 3: Approve apUSD, then deposit
-const hash = await client.deposit({ apUSDAmount: depositAmount });
-await client.waitForTransaction(hash);
+// Path: slisBNB → WBNB → USDT (PancakeSwap V3)
+const path = encodeV3Path(
+  [BSC_ADDRESSES.slisBNB, BSC_ADDRESSES.WBNB, BSC_ADDRESSES.USDT],
+  [500, 500]
+);
 
-// 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));
+// 100 apUSD → USDT
+const hash = await router.redeemAndSwap({
+  lst: BSC_ADDRESSES.slisBNB,
+  redeemXBNB: false,  // apUSD
+  amount: parseAmount("100"),
+  path,
+  minOut: parseAmount("99"),
+  deadline: BigInt(Math.floor(Date.now() / 1000) + 3600),
+  unwrapBNB: false,
+});
 ```
 
-### Flow 6: Withdraw from Stability Pool
+### 6. Quick Exit: apUSD/xBNB → Native BNB (Lista StableSwap)
 
-User withdraws their staked apUSD plus accumulated yield.
+Exit to native BNB using Lista StableSwap for better rates on slisBNB → WBNB.
 
 ```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);
+// For slisBNB → WBNB, Router auto-routes through Lista StableSwap
+// Just use a single-hop path
+const path = encodeV3Path(
+  [BSC_ADDRESSES.slisBNB, BSC_ADDRESSES.WBNB],
+  [100]  // Fee tier ignored for Lista StableSwap route
+);
 
-// Or withdraw specific amount of apUSD:
-// const hash = await client.withdrawAssets({ assets: parseAmount("500") });
+// xBNB → Native BNB
+const hash = await router.redeemAndSwap({
+  lst: BSC_ADDRESSES.slisBNB,
+  redeemXBNB: true,  // xBNB
+  amount: parseAmount("0.001"),
+  path,
+  minOut: parseAmount("0.8"),
+  deadline: BigInt(Math.floor(Date.now() / 1000) + 3600),
+  unwrapBNB: true,  // Auto-unwrap WBNB to native BNB
+});
 ```
 
-### Flow 7: Manual Yield Harvest
+### 7. Zero-Slippage Exit: Lista Native Unstake (7 Days)
 
-Anyone can trigger yield harvest to distribute pending LST yield.
+Don't want to pay DEX slippage? Use Lista native unstake for 1:1 BNB redemption after 7 days.
 
 ```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);
+// Step 1: Request unstake
+const hash = await router.redeemAndRequestUnstake({
+  redeemXBNB: false,  // apUSD
+  amount: parseAmount("100"),
+});
+await router.waitForTransaction(hash);
+
+// Step 2: Check status
+const indices = await router.getUserWithdrawalIndices(account.address);
+for (const idx of indices) {
+  const status = await router.getWithdrawalStatus(idx);
+  console.log(`#${idx}: ${status.isClaimable ? "Claimable" : "Pending"}, ${formatAmount(status.bnbAmount)} BNB`);
 }
+
+// Step 3: Claim BNB after 7 days
+const claimHash = await router.claimUnstake(requestIndex);
 ```
 
 ---
 
-## 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
-```
+## User Flows
 
-### xBNB Price (Section 3.3 & 4)
+### Flow 1: Mint apUSD (Stablecoin)
 
-| 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` |
+User deposits LST (e.g., slisBNB) to mint apUSD stablecoin.
 
 ```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) |
+import { createAspanClient, parseAmount, BSC_ADDRESSES } from "@aspan/sdk";
+import { privateKeyToAccount } from "viem/accounts";
 
-```typescript
-const cr = await client.getCollateralRatio();
-// CR in BPS: 15000 = 150%, 13000 = 130%, 10000 = 100%
-console.log("CR:", Number(cr) / 100, "%");
-```
+const account = privateKeyToAccount("0x...");
+const client = createAspanClient(BSC_ADDRESSES.diamond, account);
 
-### Effective Leverage (Section 5)
+const lstAmount = parseAmount("10"); // 10 slisBNB
 
-| Metric | SDK Method | Formula |
-|--------|------------|---------|
-| **Leverage** | `getEffectiveLeverage()` | `TVL / xBNB_market_cap` |
+// Check fees
+const fees = await client.getCurrentFees();
+if (fees.apUSDMintDisabled) throw new Error("Minting disabled in current CR");
 
-```typescript
-const leverage = await client.getEffectiveLeverage();
-// 1e18 = 1x, 2e18 = 2x leverage
-console.log("Leverage:", formatAmount(leverage), "x");
+// Approve LST, then mint with slippage protection
+const minOut = lstAmount * 995n / 1000n; // 0.5% slippage tolerance
+const hash = await client.mintApUSD({
+  lstToken: BSC_ADDRESSES.slisBNB,
+  lstAmount,
+  minOut,
+});
+await client.waitForTransaction(hash);
 ```
 
-### 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 |
+### Flow 2: Redeem apUSD for LST
 
 ```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
-```
+const apUSDAmount = parseAmount("5000");
 
-### 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% |
+// Calculate expected LST and set minOut
+const lstPrice = await client.getLSTPriceUSD(BSC_ADDRESSES.slisBNB);
+const expectedLST = (apUSDAmount * parseAmount("1")) / lstPrice;
+const minOut = expectedLST * 995n / 1000n;
 
-```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
+const hash = await client.redeemApUSD({
+  lstToken: BSC_ADDRESSES.slisBNB,
+  apUSDAmount,
+  minOut,
+});
 ```
 
-### 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 |
+### Flow 3: Stake apUSD to Earn Yield (sApUSD)
 
 ```typescript
+// Check pool stats
 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
+console.log("Exchange Rate:", formatAmount(poolStats.exchangeRate));
 
-```typescript
-const bnbPrice = await client.getBNBPriceUSD();
-console.log("BNB Price:", formatPriceUSD(bnbPrice));
-// Note: BNB price is 8 decimals (Chainlink format)
+// Deposit apUSD
+const hash = await client.deposit({ apUSDAmount: parseAmount("1000") });
 
-const lstPrice = await client.getLSTPriceUSD(SLISBNB);
-console.log("LST Price:", formatAmount(lstPrice), "USD");
-// Note: LST price is 18 decimals
+// Check position
+const position = await client.getUserStabilityPoolPosition(account.address);
+console.log("Balance (incl. yield):", formatAmount(position.balance));
 ```
 
 ---
 
-## Complete Dashboard Example
+## Protocol Metrics
 
 ```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)})`);
-  }
-}
+const stats = await client.getProtocolStats();
+const fees = await client.getCurrentFees();
+const mode = await client.getStabilityMode();
 
-displayDashboard();
+console.log("TVL:", formatAmount(stats.tvlInUSD), "USD");
+console.log("CR:", formatCR(stats.collateralRatio));
+console.log("Stability Mode:", mode.mode);
+console.log("xBNB Price:", formatAmount(stats.xBNBPriceBNB), "BNB");
+console.log("Leverage:", formatAmount(stats.effectiveLeverage), "x");
 ```
 
 ---
 
 ## API Reference
 
-### Client Configuration
-
-| Option | Type | Required | Description |
-|--------|------|----------|-------------|
-| `diamondAddress` | `Address` | ✅ | Diamond contract address |
-| `chain` | `Chain` | ❌ | Chain config (default: BSC Mainnet) |
-| `rpcUrl` | `string` | ❌ | RPC URL (default: BSC public RPC) |
-| `walletClient` | `WalletClient` | ⚠️ | For browser/wagmi (required if no account) |
-| `account` | `Account` | ⚠️ | For Node.js (required if no walletClient) |
-
-> ⚠️ Write client requires either `walletClient` (browser) or `account` (Node.js)
+### Router Write Functions (v2.0.0)
 
-### 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()` |
+| Function | Description |
+|----------|-------------|
+| `swapAndMint(params)` | Swap input token → LST → mint apUSD/xBNB |
+| `swapAndMintDefault(params)` | Simplified swap+mint using default LST |
+| `stakeAndMint(params)` | Stake BNB directly → LST → mint apUSD/xBNB |
+| `mint(params)` | Direct mint apUSD/xBNB with LST |
+| `redeem(params)` | Direct redeem apUSD/xBNB for LST |
+| `redeemAndSwap(params)` | Redeem + swap LST to output token (V3 path, optional unwrapBNB) |
+| `redeemAndRequestUnstake(params)` | Redeem + request native unstake from Lista |
+| `claimUnstake(requestIndex)` | Claim BNB after unbonding period |
 
 ### Router View Functions
 
-| Category | Methods |
-|----------|---------|
-| **Config** | `getDefaultLST()`, `isSupportedInputToken()`, `isSupportedLST()`, `getDiamond()` |
-| **Preview** | `previewMintApUSD()`, `previewMintXBNB()`, `previewRedeemApUSD()`, `previewRedeemXBNB()` |
-| **Unstake** | `getUserWithdrawalIndices()`, `getWithdrawalStatus()` |
-| **Addresses** | `getWBNB()`, `getUSDT()`, `getUSDC()`, `getSlisBNB()`, `getAsBNB()`, `getWclisBNB()`, `getApUSD()`, `getXBNB()` |
-
-### Router Write Functions
-
-| Category | Methods |
-|----------|---------|
-| **Swap+Mint** | `swapAndMintApUSD()`, `swapAndMintXBNB()`, `swapAndMintApUSDDefault()`, `swapAndMintXBNBDefault()` |
-| **Stake+Mint** | `stakeAndMint()`, `stakeAndMintApUSD()`, `stakeAndMintXBNB()` |
-| **Direct** | `mintApUSD()`, `mintXBNB()`, `redeemApUSD()`, `redeemXBNB()` |
-| **Redeem+Swap** | `redeemApUSDAndSwap()`, `redeemXBNBAndSwap()` (V3 path) |
-| **Native Unstake** | `redeemApUSDAndRequestUnstake()`, `redeemXBNBAndRequestUnstake()`, `claimUnstake()` |
+| Function | Description |
+|----------|-------------|
+| `previewMint(lst, amount, mintXBNB)` | Preview mint output |
+| `previewRedeem(lst, redeemXBNB, amount)` | Preview redeem output |
+| `getDefaultLST()` | Get default LST address |
+| `isSupportedInputToken(token)` | Check if input token supported |
+| `isSupportedLST(lst)` | Check if LST supported |
+| `getUserWithdrawalIndices(user)` | Get user's unstake request indices |
+| `getWithdrawalStatus(index)` | Check unstake request status |
+
+### Diamond Write Functions
+
+| Function | Description |
+|----------|-------------|
+| `mintApUSD(params)` | Mint apUSD with LST |
+| `redeemApUSD(params)` | Redeem apUSD for LST |
+| `mintXBNB(params)` | Mint xBNB with LST |
+| `redeemXBNB(params)` | Redeem xBNB for LST |
+| `deposit(params)` | Deposit apUSD to stability pool |
+| `withdraw(params)` | Withdraw from stability pool |
+| `harvestYield()` | Trigger yield distribution |
 
 ---
 
@@ -790,7 +552,8 @@ import {
   formatFeeBPS,     // 25 -> "0.25%"
   formatCR,         // 15000n -> "150%"
   formatPriceUSD,   // 58325000000n -> "$583.25"
-  calculateAPY,     // (oldRate, newRate, days) -> APY%
+  encodeV3Path,     // Encode PancakeSwap V3 swap path
+  BSC_ADDRESSES,    // All contract addresses
   PRECISION,        // 10^18
   BPS_PRECISION,    // 10000
   PRICE_PRECISION,  // 10^8
@@ -809,13 +572,8 @@ import {
   createRouterTestnetClient,
 } from "@aspan/sdk";
 
-// Diamond client (testnet)
 const client = createAspanTestnetReadClient("0x...");
-const writeClient = createAspanTestnetClient("0x...", account);
-
-// Router client (testnet)
-const routerRead = createRouterTestnetReadClient("0x...");
-const routerWrite = createRouterTestnetClient("0x...", account);
+const router = createRouterTestnetClient("0x...", account);
 ```
 
 ## License