@aspan/sdk 0.1.4 → 0.1.8

package/src/abi/diamond.ts

@@ -9,7 +9,8 @@ export const DiamondABI = [
     name: "mintApUSD",
     inputs: [
       { name: "_lstToken", type: "address", internalType: "address" },
-      { name: "_lstAmount", type: "uint256", internalType: "uint256" }
+      { name: "_lstAmount", type: "uint256", internalType: "uint256" },
+      { name: "_minOut", type: "uint256", internalType: "uint256" }
     ],
     outputs: [{ name: "apUSDAmount", type: "uint256", internalType: "uint256" }],
     stateMutability: "nonpayable"
@@ -19,7 +20,8 @@ export const DiamondABI = [
     name: "redeemApUSD",
     inputs: [
       { name: "_lstToken", type: "address", internalType: "address" },
-      { name: "_apUSDAmount", type: "uint256", internalType: "uint256" }
+      { name: "_apUSDAmount", type: "uint256", internalType: "uint256" },
+      { name: "_minOut", type: "uint256", internalType: "uint256" }
     ],
     outputs: [{ name: "lstAmount", type: "uint256", internalType: "uint256" }],
     stateMutability: "nonpayable"
@@ -29,7 +31,8 @@ export const DiamondABI = [
     name: "mintXBNB",
     inputs: [
       { name: "_lstToken", type: "address", internalType: "address" },
-      { name: "_lstAmount", type: "uint256", internalType: "uint256" }
+      { name: "_lstAmount", type: "uint256", internalType: "uint256" },
+      { name: "_minOut", type: "uint256", internalType: "uint256" }
     ],
     outputs: [{ name: "xBNBAmount", type: "uint256", internalType: "uint256" }],
     stateMutability: "nonpayable"
@@ -39,7 +42,8 @@ export const DiamondABI = [
     name: "redeemXBNB",
     inputs: [
       { name: "_lstToken", type: "address", internalType: "address" },
-      { name: "_xBNBAmount", type: "uint256", internalType: "uint256" }
+      { name: "_xBNBAmount", type: "uint256", internalType: "uint256" },
+      { name: "_minOut", type: "uint256", internalType: "uint256" }
     ],
     outputs: [{ name: "lstAmount", type: "uint256", internalType: "uint256" }],
     stateMutability: "nonpayable"

package/src/bot/config.ts

@@ -17,7 +17,7 @@ export interface BotConfig {
   statsReportInterval: number;
   crCheckInterval: number;
 
-  // CR Thresholds (18 decimals: 1.5e18 = 150%)
+  // CR Thresholds (BPS: 15000 = 150%, matches contract format)
   crThresholdMode1: bigint;
   crThresholdMode2: bigint;
 
@@ -59,13 +59,13 @@ export function loadConfig(): BotConfig {
     ), // 5 min
     crCheckInterval: parseInt(process.env.CR_CHECK_INTERVAL_MS ?? "30000", 10), // 30 sec
 
-    // CR Thresholds
+    // CR Thresholds (BPS format to match contract)
     crThresholdMode1: BigInt(
-      process.env.CR_THRESHOLD_MODE1 ?? "1500000000000000000"
-    ), // 150%
+      process.env.CR_THRESHOLD_MODE1 ?? "15000"
+    ), // 150% in BPS
     crThresholdMode2: BigInt(
-      process.env.CR_THRESHOLD_MODE2 ?? "1300000000000000000"
-    ), // 130%
+      process.env.CR_THRESHOLD_MODE2 ?? "13000"
+    ), // 130% in BPS
 
     // TVL
     tvlImpactThresholdPercent: parseFloat(

package/src/bot/monitors/cr-monitor.ts

@@ -79,6 +79,14 @@ export class CRMonitor {
       const currentCR = stabilityMode.currentCR;
       const now = Date.now();
 
+      // Skip alerts when protocol is effectively empty
+      // CR < 100 BPS (1%) indicates negligible TVL/supply, not a real crisis
+      const MIN_MEANINGFUL_CR = 100n; // 1% in BPS
+      if (currentCR < MIN_MEANINGFUL_CR) {
+        console.log(`[CRMonitor] Protocol effectively empty (CR = ${formatCR(currentCR)}), skipping alerts`);
+        return;
+      }
+
       // Check Mode 2 threshold (< 130%)
       if (currentCR < this.config.crThresholdMode2) {
         if (!this.state.mode2Triggered || this.shouldRepeatAlert(now)) {

package/src/bot/monitors/stats-monitor.ts

@@ -143,7 +143,7 @@ export class StatsMonitor {
               },
               {
                 title: "xBNB Supply",
-                value: formatAmount(stats.xBNBSupply, 4),
+                value: formatAmount(stats.xBNBSupply, 18),
                 short: true,
               },
               {

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 ============
@@ -100,25 +102,28 @@ export class AspanReadClient {
    * Get comprehensive protocol statistics
    */
   async getProtocolStats(): Promise<ProtocolStats> {
-    const [
-      tvlInBNB,
-      tvlInUSD,
-      collateralRatio,
-      apUSDSupply,
-      xBNBSupply,
-      xBNBPriceBNB,
-      xBNBPriceUSD,
-      effectiveLeverage,
-    ] = await Promise.all([
-      this.getTVLInBNB(),
-      this.getTVLInUSD(),
-      this.getCollateralRatio(),
-      this.getApUSDSupply(),
-      this.getXBNBSupply(),
-      this.getXBNBPriceBNB(),
-      this.getXBNBPriceUSD(),
-      this.getEffectiveLeverage(),
-    ]);
+    // First get supplies to determine if xBNB exists
+    const [tvlInBNB, tvlInUSD, collateralRatio, apUSDSupply, xBNBSupply] =
+      await Promise.all([
+        this.getTVLInBNB(),
+        this.getTVLInUSD(),
+        this.getCollateralRatio(),
+        this.getApUSDSupply(),
+        this.getXBNBSupply(),
+      ]);
+
+    // Only fetch xBNB price and leverage if xBNB supply exists
+    let xBNBPriceBNB = 0n;
+    let xBNBPriceUSD = 0n;
+    let effectiveLeverage = 0n;
+
+    if (xBNBSupply > 0n) {
+      [xBNBPriceBNB, xBNBPriceUSD, effectiveLeverage] = await Promise.all([
+        this.getXBNBPriceBNB(),
+        this.getXBNBPriceUSD(),
+        this.getEffectiveLeverage(),
+      ]);
+    }
 
     return {
       tvlInBNB,
@@ -216,8 +221,8 @@ export class AspanReadClient {
         functionName: "getCollateralRatio",
       });
       // Contract returns max uint256 when supply is zero (infinite CR)
-      // Treat anything above 1000000% (10000 * 1e18) as zero/undefined
-      if (cr > 10000n * 10n ** 18n) {
+      // CR is in BPS format (10000 = 100%), anything above 100000000 BPS is invalid
+      if (cr > 100000000n) {
         return 0n;
       }
       return cr;
@@ -232,11 +237,17 @@ export class AspanReadClient {
 
   async getXBNBPriceBNB(): Promise<bigint> {
     try {
-      return await this.publicClient.readContract({
+      const price = await this.publicClient.readContract({
         address: this.diamondAddress,
         abi: DiamondABI,
         functionName: "getXBNBPriceBNB",
       });
+      // Contract returns extreme values when xBNB supply is zero
+      // Normal xBNB price should be < 1000 BNB (1000 * 1e18)
+      if (price > 1000n * 10n ** 18n) {
+        return 0n;
+      }
+      return price;
     } catch (error) {
       // Price undefined when no xBNB exists
       if (this.isZeroSupplyError(error)) {
@@ -248,11 +259,17 @@ export class AspanReadClient {
 
   async getXBNBPriceUSD(): Promise<bigint> {
     try {
-      return await this.publicClient.readContract({
+      const price = await this.publicClient.readContract({
         address: this.diamondAddress,
         abi: DiamondABI,
         functionName: "getXBNBPriceUSD",
       });
+      // Contract returns extreme values when xBNB supply is zero
+      // xBNBPriceUSD is in 18 decimals, normal price should be < $1,000,000 (1e6 * 1e18)
+      if (price > 1000000n * 10n ** 18n) {
+        return 0n;
+      }
+      return price;
     } catch (error) {
       // Price undefined when no xBNB exists
       if (this.isZeroSupplyError(error)) {
@@ -264,11 +281,17 @@ export class AspanReadClient {
 
   async getEffectiveLeverage(): Promise<bigint> {
     try {
-      return await this.publicClient.readContract({
+      const leverage = await this.publicClient.readContract({
         address: this.diamondAddress,
         abi: DiamondABI,
         functionName: "getEffectiveLeverage",
       });
+      // Contract returns extreme values when xBNB supply is zero
+      // Normal leverage should be < 100x (100 * 1e18)
+      if (leverage > 100n * 10n ** 18n) {
+        return 0n;
+      }
+      return leverage;
     } catch (error) {
       // Leverage undefined when no xBNB exists
       if (this.isZeroSupplyError(error)) {
@@ -334,8 +357,15 @@ export class AspanReadClient {
         functionName: "getCurrentFees",
       });
 
+      let currentCR = result[0];
+      // Contract returns max uint256 when supply is zero (infinite CR)
+      // CR is in BPS format (10000 = 100%)
+      if (currentCR > 100000000n) {
+        currentCR = 0n;
+      }
+
       return {
-        currentCR: result[0],
+        currentCR,
         tierMinCR: result[1],
         apUSDMintFee: result[2],
         apUSDRedeemFee: result[3],
@@ -398,12 +428,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> {
@@ -710,6 +741,13 @@ export class AspanReadClient {
         functionName: "getCurrentFeeTier",
       });
 
+      let currentCR = result[6];
+      // Contract returns max uint256 when supply is zero (infinite CR)
+      // CR is in BPS format (10000 = 100%)
+      if (currentCR > 100000000n) {
+        currentCR = 0n;
+      }
+
       return {
         minCR: result[0],
         apUSDMintFee: result[1],
@@ -717,7 +755,7 @@ export class AspanReadClient {
         xBNBMintFee: result[3],
         xBNBRedeemFee: result[4],
         apUSDMintDisabled: result[5],
-        currentCR: result[6],
+        currentCR,
       };
     } catch (error) {
       // Return default fee tier when protocol is empty
@@ -770,9 +808,16 @@ export class AspanReadClient {
         functionName: "getStabilityMode",
       });
 
+      let currentCR = result[1];
+      // Contract returns max uint256 when supply is zero (infinite CR)
+      // CR is in BPS format (10000 = 100%)
+      if (currentCR > 100000000n) {
+        currentCR = 0n;
+      }
+
       return {
         mode: result[0],
-        currentCR: result[1],
+        currentCR,
       };
     } catch (error) {
       // Return normal mode when protocol is empty
@@ -794,9 +839,16 @@ export class AspanReadClient {
         functionName: "canTriggerStabilityMode2",
       });
 
+      let currentCR = result[1];
+      // Contract returns max uint256 when supply is zero (infinite CR)
+      // CR is in BPS format (10000 = 100%)
+      if (currentCR > 100000000n) {
+        currentCR = 0n;
+      }
+
       return {
         canTrigger: result[0],
-        currentCR: result[1],
+        currentCR,
         potentialConversion: result[2],
       };
     } catch (error) {
@@ -829,16 +881,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,10 +910,12 @@ 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",
-      args: [params.lstToken, params.lstAmount],
+      args: [params.lstToken, params.lstAmount, params.minOut ?? 0n],
     });
   }
 
@@ -864,10 +926,12 @@ 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",
-      args: [params.lstToken, params.apUSDAmount],
+      args: [params.lstToken, params.apUSDAmount, params.minOut ?? 0n],
     });
   }
 
@@ -878,10 +942,12 @@ 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",
-      args: [params.lstToken, params.lstAmount],
+      args: [params.lstToken, params.lstAmount, params.minOut ?? 0n],
     });
   }
 
@@ -892,10 +958,12 @@ 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",
-      args: [params.lstToken, params.xBNBAmount],
+      args: [params.lstToken, params.xBNBAmount, params.minOut ?? 0n],
     });
   }
 
@@ -908,6 +976,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 +992,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 +1008,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 +1023,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",

package/src/index.ts

@@ -102,12 +102,13 @@ export 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%")
  */
 export function formatCR(cr: bigint): string {
-  const percentage = (cr * 100n) / PRECISION;
-  return `${percentage}%`;
+  // CR is in BPS: 15000 = 150%
+  const percentage = Number(cr) / 100;
+  return `${percentage.toFixed(2)}%`;
 }
 
 /**

package/src/types.ts

@@ -90,24 +90,32 @@ export interface StabilityMode2Result {
 export interface MintApUSDParams {
   lstToken: Address;
   lstAmount: bigint;
+  /** Minimum apUSD output for slippage protection (default: 0n) */
+  minOut?: bigint;
 }
 
 /** Parameters for redeeming apUSD */
 export interface RedeemApUSDParams {
   lstToken: Address;
   apUSDAmount: bigint;
+  /** Minimum LST output for slippage protection (default: 0n) */
+  minOut?: bigint;
 }
 
 /** Parameters for minting xBNB */
 export interface MintXBNBParams {
   lstToken: Address;
   lstAmount: bigint;
+  /** Minimum xBNB output for slippage protection (default: 0n) */
+  minOut?: bigint;
 }
 
 /** Parameters for redeeming xBNB */
 export interface RedeemXBNBParams {
   lstToken: Address;
   xBNBAmount: bigint;
+  /** Minimum LST output for slippage protection (default: 0n) */
+  minOut?: bigint;
 }
 
 /** Parameters for depositing to stability pool */