@aspan/sdk 0.1.4 → 0.1.8

package/README.md

@@ -23,10 +23,12 @@ pnpm add @aspan/sdk
 
 ## Quick Start
 
+### Read-Only Client (Query Data)
+
 ```typescript
 import { createAspanReadClient, formatAmount, formatCR } from "@aspan/sdk";
 
-const DIAMOND = "0xa67e91ebbb709516c563bcf1d9dae355aaf6d2ef";
+const DIAMOND = "0x10d25Ae0690533e0BA9E64EC7ae77dbD4fE8A46f";
 const client = createAspanReadClient(DIAMOND, "https://bsc-dataseed.binance.org/");
 
 const stats = await client.getProtocolStats();
@@ -34,6 +36,53 @@ console.log("TVL:", formatAmount(stats.tvlInUSD), "USD");
 console.log("CR:", formatCR(stats.collateralRatio));
 ```
 
+### Write Client - Browser (React/wagmi)
+
+```typescript
+import { AspanClient } 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
+    });
+  };
+
+  const handleMint = async () => {
+    const client = getClient();
+    if (!client) return;
+    
+    const hash = await client.mintApUSD({
+      lstToken: "0xB0b84D294e0C75A6abe60171b70edEb2EFd14A1B",
+      lstAmount: parseAmount("1"),
+    });
+    console.log("Tx hash:", hash);
+  };
+}
+```
+
+### Write Client - 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 hash = await client.mintApUSD({
+  lstToken: "0xB0b84D294e0C75A6abe60171b70edEb2EFd14A1B",
+  lstAmount: parseAmount("1"),
+});
+```
+
 ---
 
 ## User Flows
@@ -42,10 +91,56 @@ console.log("CR:", formatCR(stats.collateralRatio));
 
 User deposits LST (e.g., slisBNB) to mint apUSD stablecoin.
 
+#### Browser (React/wagmi)
+
+```typescript
+import { AspanClient, parseAmount } from "@aspan/sdk";
+import { useWalletClient } from "wagmi";
+
+const DIAMOND = "0x10d25Ae0690533e0BA9E64EC7ae77dbD4fE8A46f";
+const SLISBNB = "0xB0b84D294e0C75A6abe60171b70edEb2EFd14A1B";
+
+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";
-import { erc20Abi } from "viem";
 
 const account = privateKeyToAccount("0x...");
 const client = createAspanClient(DIAMOND, account);
@@ -70,8 +165,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);
 ```
@@ -90,8 +186,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);
 ```
 
@@ -111,12 +212,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: 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 4: Stake apUSD to Earn Yield (sApUSD)
+### Flow 5: Stake apUSD to Earn Yield (sApUSD)
 
 User deposits apUSD to stability pool to earn LST yield.
 
@@ -141,7 +276,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.
 
@@ -164,7 +299,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.
 
@@ -394,6 +529,18 @@ displayDashboard();
 
 ## 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)
+
 ### View Functions
 
 | Category | Methods |

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import * as viem from 'viem';
-import { Address, Hash, PublicClient, Chain, Account } from 'viem';
+import { Address, Hash, PublicClient, Chain, Account, WalletClient, Transport } from 'viem';
 
 /**
  * Aspan SDK Type Definitions
@@ -71,21 +71,29 @@ interface StabilityMode2Info {
 interface MintApUSDParams {
     lstToken: Address;
     lstAmount: bigint;
+    /** Minimum apUSD output for slippage protection (default: 0n) */
+    minOut?: bigint;
 }
 /** Parameters for redeeming apUSD */
 interface RedeemApUSDParams {
     lstToken: Address;
     apUSDAmount: bigint;
+    /** Minimum LST output for slippage protection (default: 0n) */
+    minOut?: bigint;
 }
 /** Parameters for minting xBNB */
 interface MintXBNBParams {
     lstToken: Address;
     lstAmount: bigint;
+    /** Minimum xBNB output for slippage protection (default: 0n) */
+    minOut?: bigint;
 }
 /** Parameters for redeeming xBNB */
 interface RedeemXBNBParams {
     lstToken: Address;
     xBNBAmount: bigint;
+    /** Minimum LST output for slippage protection (default: 0n) */
+    minOut?: bigint;
 }
 /** Parameters for depositing to stability pool */
 interface DepositParams {
@@ -199,8 +207,10 @@ interface AspanClientConfig {
     rpcUrl?: string;
 }
 interface AspanWriteClientConfig extends AspanClientConfig {
-    /** Account for signing transactions */
-    account: Account;
+    /** Account for signing transactions (required if walletClient not provided) */
+    account?: Account;
+    /** External wallet client (for browser environments with wagmi/rainbowkit) */
+    walletClient?: WalletClient<Transport, Chain, Account>;
 }
 /**
  * Read-only client for querying Aspan Protocol state
@@ -240,7 +250,7 @@ declare class AspanReadClient {
     getBNBPriceUSD(): Promise<bigint>;
     getLSTPriceUSD(lstToken: Address): Promise<bigint>;
     getLSTInfo(lstToken: Address): Promise<LSTInfo>;
-    getSupportedLSTs(): Promise<readonly Address[]>;
+    getSupportedLSTs(): Promise<Address[]>;
     isLSTSupported(lstToken: Address): Promise<boolean>;
     getBNBPriceFeed(): Promise<Address>;
     getOracleBounds(priceFeed: Address): Promise<OracleBounds>;
@@ -363,6 +373,10 @@ declare const DiamondABI: readonly [{
         readonly name: "_lstAmount";
         readonly type: "uint256";
         readonly internalType: "uint256";
+    }, {
+        readonly name: "_minOut";
+        readonly type: "uint256";
+        readonly internalType: "uint256";
     }];
     readonly outputs: readonly [{
         readonly name: "apUSDAmount";
@@ -381,6 +395,10 @@ declare const DiamondABI: readonly [{
         readonly name: "_apUSDAmount";
         readonly type: "uint256";
         readonly internalType: "uint256";
+    }, {
+        readonly name: "_minOut";
+        readonly type: "uint256";
+        readonly internalType: "uint256";
     }];
     readonly outputs: readonly [{
         readonly name: "lstAmount";
@@ -399,6 +417,10 @@ declare const DiamondABI: readonly [{
         readonly name: "_lstAmount";
         readonly type: "uint256";
         readonly internalType: "uint256";
+    }, {
+        readonly name: "_minOut";
+        readonly type: "uint256";
+        readonly internalType: "uint256";
     }];
     readonly outputs: readonly [{
         readonly name: "xBNBAmount";
@@ -417,6 +439,10 @@ declare const DiamondABI: readonly [{
         readonly name: "_xBNBAmount";
         readonly type: "uint256";
         readonly internalType: "uint256";
+    }, {
+        readonly name: "_minOut";
+        readonly type: "uint256";
+        readonly internalType: "uint256";
     }];
     readonly outputs: readonly [{
         readonly name: "lstAmount";
@@ -1302,8 +1328,8 @@ declare function parseAmount(amount: string): bigint;
 declare function formatFeeBPS(bps: number): string;
 /**
  * Format collateral ratio to percentage string
- * @param cr Collateral ratio (18 decimals, 1e18 = 100%)
- * @returns Percentage string (e.g., "150%")
+ * @param cr Collateral ratio in BPS (10000 = 100%, contract format)
+ * @returns Percentage string (e.g., "150.00%")
  */
 declare function formatCR(cr: bigint): string;
 /**

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as viem from 'viem';
-import { Address, Hash, PublicClient, Chain, Account } from 'viem';
+import { Address, Hash, PublicClient, Chain, Account, WalletClient, Transport } from 'viem';
 
 /**
  * Aspan SDK Type Definitions
@@ -71,21 +71,29 @@ interface StabilityMode2Info {
 interface MintApUSDParams {
     lstToken: Address;
     lstAmount: bigint;
+    /** Minimum apUSD output for slippage protection (default: 0n) */
+    minOut?: bigint;
 }
 /** Parameters for redeeming apUSD */
 interface RedeemApUSDParams {
     lstToken: Address;
     apUSDAmount: bigint;
+    /** Minimum LST output for slippage protection (default: 0n) */
+    minOut?: bigint;
 }
 /** Parameters for minting xBNB */
 interface MintXBNBParams {
     lstToken: Address;
     lstAmount: bigint;
+    /** Minimum xBNB output for slippage protection (default: 0n) */
+    minOut?: bigint;
 }
 /** Parameters for redeeming xBNB */
 interface RedeemXBNBParams {
     lstToken: Address;
     xBNBAmount: bigint;
+    /** Minimum LST output for slippage protection (default: 0n) */
+    minOut?: bigint;
 }
 /** Parameters for depositing to stability pool */
 interface DepositParams {
@@ -199,8 +207,10 @@ interface AspanClientConfig {
     rpcUrl?: string;
 }
 interface AspanWriteClientConfig extends AspanClientConfig {
-    /** Account for signing transactions */
-    account: Account;
+    /** Account for signing transactions (required if walletClient not provided) */
+    account?: Account;
+    /** External wallet client (for browser environments with wagmi/rainbowkit) */
+    walletClient?: WalletClient<Transport, Chain, Account>;
 }
 /**
  * Read-only client for querying Aspan Protocol state
@@ -240,7 +250,7 @@ declare class AspanReadClient {
     getBNBPriceUSD(): Promise<bigint>;
     getLSTPriceUSD(lstToken: Address): Promise<bigint>;
     getLSTInfo(lstToken: Address): Promise<LSTInfo>;
-    getSupportedLSTs(): Promise<readonly Address[]>;
+    getSupportedLSTs(): Promise<Address[]>;
     isLSTSupported(lstToken: Address): Promise<boolean>;
     getBNBPriceFeed(): Promise<Address>;
     getOracleBounds(priceFeed: Address): Promise<OracleBounds>;
@@ -363,6 +373,10 @@ declare const DiamondABI: readonly [{
         readonly name: "_lstAmount";
         readonly type: "uint256";
         readonly internalType: "uint256";
+    }, {
+        readonly name: "_minOut";
+        readonly type: "uint256";
+        readonly internalType: "uint256";
     }];
     readonly outputs: readonly [{
         readonly name: "apUSDAmount";
@@ -381,6 +395,10 @@ declare const DiamondABI: readonly [{
         readonly name: "_apUSDAmount";
         readonly type: "uint256";
         readonly internalType: "uint256";
+    }, {
+        readonly name: "_minOut";
+        readonly type: "uint256";
+        readonly internalType: "uint256";
     }];
     readonly outputs: readonly [{
         readonly name: "lstAmount";
@@ -399,6 +417,10 @@ declare const DiamondABI: readonly [{
         readonly name: "_lstAmount";
         readonly type: "uint256";
         readonly internalType: "uint256";
+    }, {
+        readonly name: "_minOut";
+        readonly type: "uint256";
+        readonly internalType: "uint256";
     }];
     readonly outputs: readonly [{
         readonly name: "xBNBAmount";
@@ -417,6 +439,10 @@ declare const DiamondABI: readonly [{
         readonly name: "_xBNBAmount";
         readonly type: "uint256";
         readonly internalType: "uint256";
+    }, {
+        readonly name: "_minOut";
+        readonly type: "uint256";
+        readonly internalType: "uint256";
     }];
     readonly outputs: readonly [{
         readonly name: "lstAmount";
@@ -1302,8 +1328,8 @@ declare function parseAmount(amount: string): bigint;
 declare function formatFeeBPS(bps: number): string;
 /**
  * Format collateral ratio to percentage string
- * @param cr Collateral ratio (18 decimals, 1e18 = 100%)
- * @returns Percentage string (e.g., "150%")
+ * @param cr Collateral ratio in BPS (10000 = 100%, contract format)
+ * @returns Percentage string (e.g., "150.00%")
  */
 declare function formatCR(cr: bigint): string;
 /**