@aspan/sdk 0.1.4 → 0.1.7

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,52 @@ 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: Mint apUSD
+    const hash = await client.mintApUSD({ lstToken: SLISBNB, lstAmount });
+    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);
@@ -394,6 +485,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
@@ -199,8 +199,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 +242,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>;

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
@@ -199,8 +199,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 +242,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>;

package/dist/index.js

@@ -865,11 +865,12 @@ var AspanReadClient = class _AspanReadClient {
     };
   }
   async getSupportedLSTs() {
-    return this.publicClient.readContract({
+    const result = await this.publicClient.readContract({
       address: this.diamondAddress,
       abi: DiamondABI,
       functionName: "getSupportedLSTs"
     });
+    return [...result];
   }
   async isLSTSupported(lstToken) {
     return this.publicClient.readContract({
@@ -1244,11 +1245,17 @@ var AspanClient = class extends AspanReadClient {
   walletClient;
   constructor(config) {
     super(config);
-    this.walletClient = (0, import_viem.createWalletClient)({
-      account: config.account,
-      chain: this.chain,
-      transport: (0, import_viem.http)(config.rpcUrl)
-    });
+    if (config.walletClient) {
+      this.walletClient = config.walletClient;
+    } else if (config.account) {
+      this.walletClient = (0, import_viem.createWalletClient)({
+        account: config.account,
+        chain: this.chain,
+        transport: (0, import_viem.http)(config.rpcUrl)
+      });
+    } else {
+      throw new Error("Either walletClient or account must be provided");
+    }
   }
   // ============ Pool Write Functions ============
   /**
@@ -1258,6 +1265,8 @@ var AspanClient = class extends AspanReadClient {
    */
   async mintApUSD(params) {
     return this.walletClient.writeContract({
+      chain: this.chain,
+      account: this.walletClient.account,
       address: this.diamondAddress,
       abi: DiamondABI,
       functionName: "mintApUSD",
@@ -1271,6 +1280,8 @@ var AspanClient = class extends AspanReadClient {
    */
   async redeemApUSD(params) {
     return this.walletClient.writeContract({
+      chain: this.chain,
+      account: this.walletClient.account,
       address: this.diamondAddress,
       abi: DiamondABI,
       functionName: "redeemApUSD",
@@ -1284,6 +1295,8 @@ var AspanClient = class extends AspanReadClient {
    */
   async mintXBNB(params) {
     return this.walletClient.writeContract({
+      chain: this.chain,
+      account: this.walletClient.account,
       address: this.diamondAddress,
       abi: DiamondABI,
       functionName: "mintXBNB",
@@ -1297,6 +1310,8 @@ var AspanClient = class extends AspanReadClient {
    */
   async redeemXBNB(params) {
     return this.walletClient.writeContract({
+      chain: this.chain,
+      account: this.walletClient.account,
       address: this.diamondAddress,
       abi: DiamondABI,
       functionName: "redeemXBNB",
@@ -1311,6 +1326,8 @@ var AspanClient = class extends AspanReadClient {
    */
   async deposit(params) {
     return this.walletClient.writeContract({
+      chain: this.chain,
+      account: this.walletClient.account,
       address: this.diamondAddress,
       abi: DiamondABI,
       functionName: "deposit",
@@ -1324,6 +1341,8 @@ var AspanClient = class extends AspanReadClient {
    */
   async withdraw(params) {
     return this.walletClient.writeContract({
+      chain: this.chain,
+      account: this.walletClient.account,
       address: this.diamondAddress,
       abi: DiamondABI,
       functionName: "withdraw",
@@ -1337,6 +1356,8 @@ var AspanClient = class extends AspanReadClient {
    */
   async withdrawAssets(params) {
     return this.walletClient.writeContract({
+      chain: this.chain,
+      account: this.walletClient.account,
       address: this.diamondAddress,
       abi: DiamondABI,
       functionName: "withdrawAssets",
@@ -1349,6 +1370,8 @@ var AspanClient = class extends AspanReadClient {
    */
   async harvestYield() {
     return this.walletClient.writeContract({
+      chain: this.chain,
+      account: this.walletClient.account,
       address: this.diamondAddress,
       abi: DiamondABI,
       functionName: "harvestYield"

package/dist/index.mjs

@@ -828,11 +828,12 @@ var AspanReadClient = class _AspanReadClient {
     };
   }
   async getSupportedLSTs() {
-    return this.publicClient.readContract({
+    const result = await this.publicClient.readContract({
       address: this.diamondAddress,
       abi: DiamondABI,
       functionName: "getSupportedLSTs"
     });
+    return [...result];
   }
   async isLSTSupported(lstToken) {
     return this.publicClient.readContract({
@@ -1207,11 +1208,17 @@ var AspanClient = class extends AspanReadClient {
   walletClient;
   constructor(config) {
     super(config);
-    this.walletClient = createWalletClient({
-      account: config.account,
-      chain: this.chain,
-      transport: http(config.rpcUrl)
-    });
+    if (config.walletClient) {
+      this.walletClient = config.walletClient;
+    } else if (config.account) {
+      this.walletClient = createWalletClient({
+        account: config.account,
+        chain: this.chain,
+        transport: http(config.rpcUrl)
+      });
+    } else {
+      throw new Error("Either walletClient or account must be provided");
+    }
   }
   // ============ Pool Write Functions ============
   /**
@@ -1221,6 +1228,8 @@ var AspanClient = class extends AspanReadClient {
    */
   async mintApUSD(params) {
     return this.walletClient.writeContract({
+      chain: this.chain,
+      account: this.walletClient.account,
       address: this.diamondAddress,
       abi: DiamondABI,
       functionName: "mintApUSD",
@@ -1234,6 +1243,8 @@ var AspanClient = class extends AspanReadClient {
    */
   async redeemApUSD(params) {
     return this.walletClient.writeContract({
+      chain: this.chain,
+      account: this.walletClient.account,
       address: this.diamondAddress,
       abi: DiamondABI,
       functionName: "redeemApUSD",
@@ -1247,6 +1258,8 @@ var AspanClient = class extends AspanReadClient {
    */
   async mintXBNB(params) {
     return this.walletClient.writeContract({
+      chain: this.chain,
+      account: this.walletClient.account,
       address: this.diamondAddress,
       abi: DiamondABI,
       functionName: "mintXBNB",
@@ -1260,6 +1273,8 @@ var AspanClient = class extends AspanReadClient {
    */
   async redeemXBNB(params) {
     return this.walletClient.writeContract({
+      chain: this.chain,
+      account: this.walletClient.account,
       address: this.diamondAddress,
       abi: DiamondABI,
       functionName: "redeemXBNB",
@@ -1274,6 +1289,8 @@ var AspanClient = class extends AspanReadClient {
    */
   async deposit(params) {
     return this.walletClient.writeContract({
+      chain: this.chain,
+      account: this.walletClient.account,
       address: this.diamondAddress,
       abi: DiamondABI,
       functionName: "deposit",
@@ -1287,6 +1304,8 @@ var AspanClient = class extends AspanReadClient {
    */
   async withdraw(params) {
     return this.walletClient.writeContract({
+      chain: this.chain,
+      account: this.walletClient.account,
       address: this.diamondAddress,
       abi: DiamondABI,
       functionName: "withdraw",
@@ -1300,6 +1319,8 @@ var AspanClient = class extends AspanReadClient {
    */
   async withdrawAssets(params) {
     return this.walletClient.writeContract({
+      chain: this.chain,
+      account: this.walletClient.account,
       address: this.diamondAddress,
       abi: DiamondABI,
       functionName: "withdrawAssets",
@@ -1312,6 +1333,8 @@ var AspanClient = class extends AspanReadClient {
    */
   async harvestYield() {
     return this.walletClient.writeContract({
+      chain: this.chain,
+      account: this.walletClient.account,
       address: this.diamondAddress,
       abi: DiamondABI,
       functionName: "harvestYield"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aspan/sdk",
-  "version": "0.1.4",
+  "version": "0.1.7",
   "description": "TypeScript SDK for Aspan Protocol - LST-backed stablecoin on BNB Chain",
   "main": "dist/index.js",
   "module": "dist/index.mjs",

package/src/client.ts

@@ -52,8 +52,10 @@ export interface AspanClientConfig {
 }
 
 export 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 ============
@@ -398,12 +400,13 @@ export class AspanReadClient {
     };
   }
 
-  async getSupportedLSTs(): Promise<readonly Address[]> {
-    return this.publicClient.readContract({
+  async getSupportedLSTs(): Promise<Address[]> {
+    const result = await this.publicClient.readContract({
       address: this.diamondAddress,
       abi: DiamondABI,
       functionName: "getSupportedLSTs",
     });
+    return [...result];
   }
 
   async isLSTSupported(lstToken: Address): Promise<boolean> {
@@ -829,16 +832,24 @@ export class AspanReadClient {
  * Full client with write capabilities for interacting with Aspan Protocol
  */
 export class AspanClient extends AspanReadClient {
-  private readonly walletClient: WalletClient<Transport, Chain, Account>;
+  private readonly walletClient: WalletClient;
 
   constructor(config: AspanWriteClientConfig) {
     super(config);
 
-    this.walletClient = createWalletClient({
-      account: config.account,
-      chain: this.chain,
-      transport: http(config.rpcUrl),
-    });
+    // Use external walletClient if provided (browser environment with wagmi/rainbowkit)
+    // Otherwise create internal walletClient (server environment)
+    if (config.walletClient) {
+      this.walletClient = config.walletClient;
+    } else if (config.account) {
+      this.walletClient = createWalletClient({
+        account: config.account,
+        chain: this.chain,
+        transport: http(config.rpcUrl),
+      });
+    } else {
+      throw new Error('Either walletClient or account must be provided');
+    }
   }
 
   // ============ Pool Write Functions ============
@@ -850,6 +861,8 @@ export class AspanClient extends AspanReadClient {
    */
   async mintApUSD(params: MintApUSDParams): Promise<Hash> {
     return this.walletClient.writeContract({
+      chain: this.chain,
+      account: this.walletClient.account!,
       address: this.diamondAddress,
       abi: DiamondABI,
       functionName: "mintApUSD",
@@ -864,6 +877,8 @@ export class AspanClient extends AspanReadClient {
    */
   async redeemApUSD(params: RedeemApUSDParams): Promise<Hash> {
     return this.walletClient.writeContract({
+      chain: this.chain,
+      account: this.walletClient.account!,
       address: this.diamondAddress,
       abi: DiamondABI,
       functionName: "redeemApUSD",
@@ -878,6 +893,8 @@ export class AspanClient extends AspanReadClient {
    */
   async mintXBNB(params: MintXBNBParams): Promise<Hash> {
     return this.walletClient.writeContract({
+      chain: this.chain,
+      account: this.walletClient.account!,
       address: this.diamondAddress,
       abi: DiamondABI,
       functionName: "mintXBNB",
@@ -892,6 +909,8 @@ export class AspanClient extends AspanReadClient {
    */
   async redeemXBNB(params: RedeemXBNBParams): Promise<Hash> {
     return this.walletClient.writeContract({
+      chain: this.chain,
+      account: this.walletClient.account!,
       address: this.diamondAddress,
       abi: DiamondABI,
       functionName: "redeemXBNB",
@@ -908,6 +927,8 @@ export class AspanClient extends AspanReadClient {
    */
   async deposit(params: DepositParams): Promise<Hash> {
     return this.walletClient.writeContract({
+      chain: this.chain,
+      account: this.walletClient.account!,
       address: this.diamondAddress,
       abi: DiamondABI,
       functionName: "deposit",
@@ -922,6 +943,8 @@ export class AspanClient extends AspanReadClient {
    */
   async withdraw(params: WithdrawParams): Promise<Hash> {
     return this.walletClient.writeContract({
+      chain: this.chain,
+      account: this.walletClient.account!,
       address: this.diamondAddress,
       abi: DiamondABI,
       functionName: "withdraw",
@@ -936,6 +959,8 @@ export class AspanClient extends AspanReadClient {
    */
   async withdrawAssets(params: WithdrawAssetsParams): Promise<Hash> {
     return this.walletClient.writeContract({
+      chain: this.chain,
+      account: this.walletClient.account!,
       address: this.diamondAddress,
       abi: DiamondABI,
       functionName: "withdrawAssets",
@@ -949,6 +974,8 @@ export class AspanClient extends AspanReadClient {
    */
   async harvestYield(): Promise<Hash> {
     return this.walletClient.writeContract({
+      chain: this.chain,
+      account: this.walletClient.account!,
       address: this.diamondAddress,
       abi: DiamondABI,
       functionName: "harvestYield",