@aspan/sdk 0.1.8 → 0.2.1

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,218 @@ 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
+  isXBNB: 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 + mint output (accurate calculation with fees)
+const mintOutput = await router.getExpectedMintOutput(
+  USDT,                  // inputToken
+  parseAmount("100"),    // inputAmount
+  zeroAddress,           // targetLST (use default)
+  false                  // isXBNB (false = apUSD)
+);
+console.log("Expected LST from swap:", formatAmount(mintOutput.expectedLST));
+console.log("Expected apUSD after mint:", formatAmount(mintOutput.expectedMint));
+
+// Preview redeem + swap output
+const redeemOutput = await router.getExpectedRedeemOutput(
+  false,                 // isXBNB (false = apUSD)
+  parseAmount("100"),    // redeemAmount
+  slisBNB,               // LST to redeem
+  USDT                   // outputToken
+);
+console.log("Expected LST from redeem:", formatAmount(redeemOutput.expectedLST));
+console.log("Expected USDT from swap:", formatAmount(redeemOutput.expectedMint));
+
+// Preview mint/redeem with LST (no swap, 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"));
+
+// 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)
@@ -561,6 +774,27 @@ displayDashboard();
 | **Pool** | `mintApUSD()`, `redeemApUSD()`, `mintXBNB()`, `redeemXBNB()` |
 | **Stability Pool** | `deposit()`, `withdraw()`, `withdrawAssets()`, `harvestYield()` |
 
+### Router View Functions
+
+| Category | Methods |
+|----------|---------|
+| **Config** | `getDefaultLST()`, `isSupportedInputToken()`, `isSupportedLST()`, `getDiamond()` |
+| **Preview Swap+Mint** | `getExpectedMintOutput()` (swap → LST → mint) |
+| **Preview Redeem+Swap** | `getExpectedRedeemOutput()` (redeem → LST → swap) |
+| **Preview Direct** | `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()`, `redeemApUSDAndUnstake()`, `redeemXBNBAndUnstake()` |
+| **Native Unstake** | `redeemApUSDAndRequestUnstake()`, `redeemXBNBAndRequestUnstake()`, `claimUnstake()` |
+
 ---
 
 ## Utility Functions
@@ -587,10 +821,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