@aspan/sdk 0.1.7 → 0.2.0

package/README.md

@@ -16,6 +16,7 @@ pnpm add @aspan/sdk
 | Contract | Address |
 |----------|---------|
 | **Diamond (Main Entry)** | `0x10d25Ae0690533e0BA9E64EC7ae77dbD4fE8A46f` |
+| **Router** | `0x46d4Bb3bB2d0A0a85739A6d467eFB3025388AE2E` |
 | **ApUSD** | `0x1977097E2E5697A6DD91b6732F368a14F50f6B3d` |
 | **XBNB** | `0xB78eB4d5928bAb158Eb23c3154544084cD2661d5` |
 | **SApUSD** | `0xE2BE739C4aA4126ee72D612d9548C38B1B0e5A1b` |
@@ -85,6 +86,197 @@ const hash = await client.mintApUSD({
 
 ---
 
+## Router (One-Click Operations)
+
+AspanRouter is a periphery contract that enables users to mint/redeem apUSD or xBNB in a single transaction using common tokens like USDT, USDC, BNB, or WBNB. The router automatically handles DEX swaps, LST staking, and minting.
+
+### Router Client Setup
+
+```typescript
+import { createRouterClient, AspanRouterClient } from "@aspan/sdk";
+import { privateKeyToAccount } from "viem/accounts";
+import { zeroAddress } from "viem";
+
+const ROUTER = "0x46d4Bb3bB2d0A0a85739A6d467eFB3025388AE2E";
+
+// Node.js
+const account = privateKeyToAccount("0x...");
+const router = createRouterClient(ROUTER, account);
+
+// Browser (wagmi)
+const router = new AspanRouterClient({
+  routerAddress: ROUTER,
+  walletClient,  // from useWalletClient()
+});
+```
+
+### Swap USDT/USDC → apUSD (One-Click)
+
+```typescript
+import { parseAmount, type SwapAndMintParams } from "@aspan/sdk";
+import { zeroAddress } from "viem";
+
+const USDT = "0x55d398326f99059fF775485246999027B3197955";
+
+// Full control with SwapParams + MintParams
+const params: SwapAndMintParams = {
+  swapParams: {
+    inputToken: USDT,
+    inputAmount: parseAmount("100"),  // 100 USDT
+    targetLST: zeroAddress,           // Use default LST
+    minLSTOut: 0n,                    // Or set slippage protection
+    poolFee: 2500,                    // 0.25% V3 pool fee
+    useV2: true,                      // Use PancakeSwap V2
+  },
+  mintParams: {
+    mintXBNB: false,                  // Mint apUSD
+    minMintOut: parseAmount("99"),    // Min 99 apUSD (1% slippage)
+    recipient: zeroAddress,           // Send to msg.sender
+    deadline: BigInt(Math.floor(Date.now() / 1000) + 3600),
+  },
+};
+
+// Approve USDT first, then swap+mint
+const hash = await router.swapAndMintApUSD(params);
+await router.waitForTransaction(hash);
+```
+
+### Simplified: Swap → apUSD (Default LST)
+
+```typescript
+// Simpler API using default LST and V2
+const hash = await router.swapAndMintApUSDDefault({
+  inputToken: USDT,
+  inputAmount: parseAmount("100"),
+  minMintOut: parseAmount("99"),
+  deadline: BigInt(Math.floor(Date.now() / 1000) + 3600),
+});
+```
+
+### Stake Native BNB → apUSD (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
+const hash = await router.stakeAndMint({
+  targetLST: "0xB0b84D294e0C75A6abe60171b70edEb2EFd14A1B", // slisBNB
+  mintXBNB: false,
+  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),
+});
+
+// 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):
+
+```typescript
+// Mint apUSD with LST
+const hash = await router.mintApUSD({
+  lst: "0xB0b84D294e0C75A6abe60171b70edEb2EFd14A1B", // slisBNB
+  lstAmount: parseAmount("10"),
+  minOut: parseAmount("99"),
+});
+
+// Redeem apUSD for LST
+const hash = await router.redeemApUSD({
+  lst: "0xB0b84D294e0C75A6abe60171b70edEb2EFd14A1B",
+  apUSDAmount: parseAmount("100"),
+  minOut: parseAmount("0.9"),
+});
+```
+
+### Redeem + Swap to USDT/BNB
+
+```typescript
+// Redeem apUSD and swap LST to USDT
+const hash = await router.redeemApUSDAndSwap({
+  lst: "0xB0b84D294e0C75A6abe60171b70edEb2EFd14A1B",
+  amount: parseAmount("100"),      // 100 apUSD
+  outputToken: USDT,               // Get USDT
+  minOut: parseAmount("99"),       // Min 99 USDT
+  deadline: BigInt(Math.floor(Date.now() / 1000) + 3600),
+  useV2: true,
+  poolFee: 2500,
+});
+
+// Redeem and get native BNB instantly (via DEX swap)
+const hash = await router.redeemApUSDAndUnstake({
+  lst: "0xB0b84D294e0C75A6abe60171b70edEb2EFd14A1B",
+  amount: parseAmount("100"),
+  minBNBOut: parseAmount("0.1"),
+  deadline: BigInt(Math.floor(Date.now() / 1000) + 3600),
+});
+```
+
+### Native Unstake (7-15 Day Unbonding)
+
+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 receipt = await router.waitForTransaction(hash);
+// Parse event to get requestIndex...
+
+// Check withdrawal status
+const indices = await router.getUserWithdrawalIndices(account.address);
+for (const idx of indices) {
+  const status = await router.getWithdrawalStatus(idx);
+  console.log(`Request ${idx}: claimable=${status.isClaimable}, amount=${status.bnbAmount}`);
+}
+
+// Claim BNB after unbonding
+const hash = await router.claimUnstake(requestIndex);
+```
+
+### Router View Functions
+
+```typescript
+// Check supported tokens
+const defaultLST = await router.getDefaultLST();
+const isSupported = await router.isSupportedInputToken(USDT);
+const isLSTSupported = await router.isSupportedLST(slisBNB);
+
+// Preview swap output
+const output = await router.getExpectedOutput(USDT, parseAmount("100"), zeroAddress, false);
+console.log("Expected LST:", output.expectedLST);
+console.log("Expected apUSD:", output.expectedMint);
+
+// Get token addresses
+const wbnb = await router.getWBNB();
+const usdt = await router.getUSDT();
+const slisBNB = await router.getSlisBNB();
+```
+
+---
+
 ## User Flows
 
 ### Flow 1: Mint apUSD (Stablecoin)
@@ -124,8 +316,12 @@ function MintComponent() {
     // Step 3: Approve LST (use wagmi's useWriteContract or viem)
     // ...
 
-    // Step 4: Mint apUSD
-    const hash = await client.mintApUSD({ lstToken: SLISBNB, lstAmount });
+    // 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);
   };
@@ -161,8 +357,9 @@ if (fees.apUSDMintDisabled) throw new Error("Minting disabled in current CR");
 //   args: [DIAMOND, lstAmount],
 // });
 
-// Step 4: Mint apUSD
-const hash = await client.mintApUSD({ lstToken: SLISBNB, 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);
 ```
@@ -181,8 +378,13 @@ 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 });
+
+// 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);
 ```
 
@@ -202,12 +404,46 @@ 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 });
+// 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);
 ```
 
-### Flow 4: Stake apUSD to Earn Yield (sApUSD)
+### Flow 4: Redeem xBNB for LST
+
+User burns xBNB to get back LST.
+
+```typescript
+const xBNBAmount = parseAmount("100"); // 100 xBNB
+
+// 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, "%");
+
+// Step 3: Check available LST liquidity
+const collateral = await client.getLSTCollateral(SLISBNB);
+console.log("Available collateral:", formatAmount(collateral));
+
+// 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);
+```
+
+### Flow 5: Stake apUSD to Earn Yield (sApUSD)
 
 User deposits apUSD to stability pool to earn LST yield.
 
@@ -232,7 +468,7 @@ console.log("Shares:", formatAmount(position.shares));
 console.log("Balance (incl. yield):", formatAmount(position.balance));
 ```
 
-### Flow 5: Withdraw from Stability Pool
+### Flow 6: Withdraw from Stability Pool
 
 User withdraws their staked apUSD plus accumulated yield.
 
@@ -255,7 +491,7 @@ await client.waitForTransaction(hash);
 // const hash = await client.withdrawAssets({ assets: parseAmount("500") });
 ```
 
-### Flow 6: Manual Yield Harvest
+### Flow 7: Manual Yield Harvest
 
 Anyone can trigger yield harvest to distribute pending LST yield.
 
@@ -517,6 +753,25 @@ displayDashboard();
 | **Pool** | `mintApUSD()`, `redeemApUSD()`, `mintXBNB()`, `redeemXBNB()` |
 | **Stability Pool** | `deposit()`, `withdraw()`, `withdrawAssets()`, `harvestYield()` |
 
+### Router View Functions
+
+| Category | Methods |
+|----------|---------|
+| **Config** | `getDefaultLST()`, `isSupportedInputToken()`, `isSupportedLST()`, `getDiamond()` |
+| **Preview** | `getExpectedOutput()` |
+| **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()`, `redeemApUSDAndUnstake()`, `redeemXBNBAndUnstake()` |
+| **Native Unstake** | `redeemApUSDAndRequestUnstake()`, `redeemXBNBAndRequestUnstake()`, `claimUnstake()` |
+
 ---
 
 ## Utility Functions
@@ -543,10 +798,17 @@ import {
 import {
   createAspanTestnetReadClient,
   createAspanTestnetClient,
+  createRouterTestnetReadClient,
+  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);
 ```
 
 ## License