@aspan/sdk 0.4.4 → 0.4.6

package/README.md

@@ -347,6 +347,13 @@ const hash = await client.deposit({ apUSDAmount: parseAmount("1000") });
 const position = await client.getUserStabilityPoolPosition(account.address);
 console.log("sApUSD Balance:", formatAmount(position.balance));
 console.log("Earned:", formatAmount(position.balance - position.deposited));
+
+// Preview withdrawal (supports dirty pools with apUSD + xBNB)
+const preview = await client.previewRedeemMulti(position.shares);
+console.log("Will receive apUSD:", formatAmount(preview.apUSD));
+if (preview.hasXBNB) {
+  console.log("Will also receive xBNB:", formatAmount(preview.xBNB));
+}
 ```
 
 ### 5. Quick Exit: apUSD/xBNB → USDT
@@ -539,6 +546,7 @@ console.log("Leverage:", formatAmount(stats.effectiveLeverage), "x");
 | `redeemXBNB(params)` | Redeem xBNB for LST |
 | `deposit(params)` | Deposit apUSD to stability pool |
 | `withdraw(params)` | Withdraw from stability pool |
+| `previewRedeemMulti(shares)` | Preview multi-asset withdrawal (apUSD + xBNB) |
 | `harvestYield()` | Trigger yield distribution |
 
 ---

package/dist/index.d.mts

@@ -457,11 +457,30 @@ declare class AspanReadClient {
     getOracleBounds(priceFeed: Address): Promise<OracleBounds>;
     getShares(user: Address): Promise<bigint>;
     getBalance(user: Address): Promise<bigint>;
+    /**
+     * Get user's underlying balances (apUSD + xBNB) from sApUSD vault
+     */
+    getBalanceMulti(user: Address): Promise<{
+        apUSDBalance: bigint;
+        xBNBBalance: bigint;
+    }>;
     getUserStabilityPoolPosition(user: Address): Promise<UserStabilityPoolPosition>;
     getExchangeRate(): Promise<bigint>;
     getTotalStaked(): Promise<bigint>;
     previewDeposit(assets: bigint): Promise<bigint>;
-    previewRedeem(shares: bigint): Promise<bigint>;
+    /**
+     * Preview withdraw with multi-asset support (apUSD + xBNB)
+     * Replaces previewRedeem — works for both clean and dirty pools.
+     * @param shares Amount of sApUSD shares to redeem
+     * @returns Object with apUSD and xBNB amounts, plus whether vault has xBNB
+     */
+    previewRedeemMulti(shares: bigint): Promise<{
+        apUSD: bigint;
+        xBNB: bigint;
+        hasXBNB: boolean;
+        assets: Address[];
+        amounts: bigint[];
+    }>;
     getPendingYield(): Promise<bigint>;
     getTotalYieldGenerated(): Promise<bigint>;
     getLSTYieldInfo(lstToken: Address): Promise<LSTYieldInfo>;
@@ -474,6 +493,39 @@ declare class AspanReadClient {
     getTreasury(): Promise<Address>;
     getFeeTierCount(): Promise<bigint>;
     getFeeTier(index: bigint): Promise<FeeTier>;
+    /**
+     * Get all fee tiers
+     * @returns Array of fee tiers sorted by minCR descending
+     */
+    getAllFeeTiers(): Promise<FeeTier[]>;
+    /**
+     * Get comprehensive vault (sApUSD) info for frontend display
+     * @returns Vault state including TVL, exchange rate, xBNB status
+     */
+    getVaultInfo(): Promise<{
+        totalSupply: bigint;
+        totalAssets: bigint;
+        exchangeRate: bigint;
+        hasXBNB: boolean;
+        xBNBAmount: bigint;
+    }>;
+    /**
+     * Get full protocol dashboard data in one call (for frontend overview page)
+     * Batches all key metrics into a single multicall
+     */
+    getProtocolOverview(): Promise<{
+        collateralRatio: bigint;
+        tvlBNB: bigint;
+        tvlUSD: bigint;
+        apUSDSupply: bigint;
+        xBNBSupply: bigint;
+        xBNBPriceUSD: bigint;
+        xBNBPriceBNB: bigint;
+        bnbPriceUSD: bigint;
+        currentFees: CurrentFeeTier;
+        stabilityMode: StabilityModeInfo;
+        totalStaked: bigint;
+    }>;
     getCurrentFeeTier(): Promise<CurrentFeeTier>;
     getMaxPriceAge(): Promise<bigint>;
     getMinDepositPeriod(): Promise<bigint>;
@@ -1377,6 +1429,24 @@ declare const DiamondABI: readonly [{
         readonly internalType: "uint256";
     }];
     readonly stateMutability: "view";
+}, {
+    readonly type: "function";
+    readonly name: "previewRedeemMulti";
+    readonly inputs: readonly [{
+        readonly name: "_shares";
+        readonly type: "uint256";
+        readonly internalType: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "assets";
+        readonly type: "address[]";
+        readonly internalType: "address[]";
+    }, {
+        readonly name: "amounts";
+        readonly type: "uint256[]";
+        readonly internalType: "uint256[]";
+    }];
+    readonly stateMutability: "view";
 }, {
     readonly type: "function";
     readonly name: "getPendingYield";
@@ -1529,6 +1599,16 @@ declare const DiamondABI: readonly [{
         readonly internalType: "address";
     }];
     readonly stateMutability: "view";
+}, {
+    readonly type: "function";
+    readonly name: "setSApUSD";
+    readonly inputs: readonly [{
+        readonly name: "_sApUSD";
+        readonly type: "address";
+        readonly internalType: "address";
+    }];
+    readonly outputs: readonly [];
+    readonly stateMutability: "nonpayable";
 }, {
     readonly type: "function";
     readonly name: "getStabilityPool";
@@ -1559,6 +1639,41 @@ declare const DiamondABI: readonly [{
         readonly internalType: "uint256";
     }];
     readonly stateMutability: "view";
+}, {
+    readonly type: "function";
+    readonly name: "getAllFeeTiers";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "tuple[]";
+        readonly internalType: "struct LibAppStorage.FeeTier[]";
+        readonly components: readonly [{
+            readonly name: "minCR";
+            readonly type: "uint256";
+            readonly internalType: "uint256";
+        }, {
+            readonly name: "apUSDMintFee";
+            readonly type: "uint16";
+            readonly internalType: "uint16";
+        }, {
+            readonly name: "apUSDRedeemFee";
+            readonly type: "uint16";
+            readonly internalType: "uint16";
+        }, {
+            readonly name: "xBNBMintFee";
+            readonly type: "uint16";
+            readonly internalType: "uint16";
+        }, {
+            readonly name: "xBNBRedeemFee";
+            readonly type: "uint16";
+            readonly internalType: "uint16";
+        }, {
+            readonly name: "apUSDMintDisabled";
+            readonly type: "bool";
+            readonly internalType: "bool";
+        }];
+    }];
+    readonly stateMutability: "view";
 }, {
     readonly type: "function";
     readonly name: "getFeeTier";

package/dist/index.d.ts

@@ -457,11 +457,30 @@ declare class AspanReadClient {
     getOracleBounds(priceFeed: Address): Promise<OracleBounds>;
     getShares(user: Address): Promise<bigint>;
     getBalance(user: Address): Promise<bigint>;
+    /**
+     * Get user's underlying balances (apUSD + xBNB) from sApUSD vault
+     */
+    getBalanceMulti(user: Address): Promise<{
+        apUSDBalance: bigint;
+        xBNBBalance: bigint;
+    }>;
     getUserStabilityPoolPosition(user: Address): Promise<UserStabilityPoolPosition>;
     getExchangeRate(): Promise<bigint>;
     getTotalStaked(): Promise<bigint>;
     previewDeposit(assets: bigint): Promise<bigint>;
-    previewRedeem(shares: bigint): Promise<bigint>;
+    /**
+     * Preview withdraw with multi-asset support (apUSD + xBNB)
+     * Replaces previewRedeem — works for both clean and dirty pools.
+     * @param shares Amount of sApUSD shares to redeem
+     * @returns Object with apUSD and xBNB amounts, plus whether vault has xBNB
+     */
+    previewRedeemMulti(shares: bigint): Promise<{
+        apUSD: bigint;
+        xBNB: bigint;
+        hasXBNB: boolean;
+        assets: Address[];
+        amounts: bigint[];
+    }>;
     getPendingYield(): Promise<bigint>;
     getTotalYieldGenerated(): Promise<bigint>;
     getLSTYieldInfo(lstToken: Address): Promise<LSTYieldInfo>;
@@ -474,6 +493,39 @@ declare class AspanReadClient {
     getTreasury(): Promise<Address>;
     getFeeTierCount(): Promise<bigint>;
     getFeeTier(index: bigint): Promise<FeeTier>;
+    /**
+     * Get all fee tiers
+     * @returns Array of fee tiers sorted by minCR descending
+     */
+    getAllFeeTiers(): Promise<FeeTier[]>;
+    /**
+     * Get comprehensive vault (sApUSD) info for frontend display
+     * @returns Vault state including TVL, exchange rate, xBNB status
+     */
+    getVaultInfo(): Promise<{
+        totalSupply: bigint;
+        totalAssets: bigint;
+        exchangeRate: bigint;
+        hasXBNB: boolean;
+        xBNBAmount: bigint;
+    }>;
+    /**
+     * Get full protocol dashboard data in one call (for frontend overview page)
+     * Batches all key metrics into a single multicall
+     */
+    getProtocolOverview(): Promise<{
+        collateralRatio: bigint;
+        tvlBNB: bigint;
+        tvlUSD: bigint;
+        apUSDSupply: bigint;
+        xBNBSupply: bigint;
+        xBNBPriceUSD: bigint;
+        xBNBPriceBNB: bigint;
+        bnbPriceUSD: bigint;
+        currentFees: CurrentFeeTier;
+        stabilityMode: StabilityModeInfo;
+        totalStaked: bigint;
+    }>;
     getCurrentFeeTier(): Promise<CurrentFeeTier>;
     getMaxPriceAge(): Promise<bigint>;
     getMinDepositPeriod(): Promise<bigint>;
@@ -1377,6 +1429,24 @@ declare const DiamondABI: readonly [{
         readonly internalType: "uint256";
     }];
     readonly stateMutability: "view";
+}, {
+    readonly type: "function";
+    readonly name: "previewRedeemMulti";
+    readonly inputs: readonly [{
+        readonly name: "_shares";
+        readonly type: "uint256";
+        readonly internalType: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "assets";
+        readonly type: "address[]";
+        readonly internalType: "address[]";
+    }, {
+        readonly name: "amounts";
+        readonly type: "uint256[]";
+        readonly internalType: "uint256[]";
+    }];
+    readonly stateMutability: "view";
 }, {
     readonly type: "function";
     readonly name: "getPendingYield";
@@ -1529,6 +1599,16 @@ declare const DiamondABI: readonly [{
         readonly internalType: "address";
     }];
     readonly stateMutability: "view";
+}, {
+    readonly type: "function";
+    readonly name: "setSApUSD";
+    readonly inputs: readonly [{
+        readonly name: "_sApUSD";
+        readonly type: "address";
+        readonly internalType: "address";
+    }];
+    readonly outputs: readonly [];
+    readonly stateMutability: "nonpayable";
 }, {
     readonly type: "function";
     readonly name: "getStabilityPool";
@@ -1559,6 +1639,41 @@ declare const DiamondABI: readonly [{
         readonly internalType: "uint256";
     }];
     readonly stateMutability: "view";
+}, {
+    readonly type: "function";
+    readonly name: "getAllFeeTiers";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "tuple[]";
+        readonly internalType: "struct LibAppStorage.FeeTier[]";
+        readonly components: readonly [{
+            readonly name: "minCR";
+            readonly type: "uint256";
+            readonly internalType: "uint256";
+        }, {
+            readonly name: "apUSDMintFee";
+            readonly type: "uint16";
+            readonly internalType: "uint16";
+        }, {
+            readonly name: "apUSDRedeemFee";
+            readonly type: "uint16";
+            readonly internalType: "uint16";
+        }, {
+            readonly name: "xBNBMintFee";
+            readonly type: "uint16";
+            readonly internalType: "uint16";
+        }, {
+            readonly name: "xBNBRedeemFee";
+            readonly type: "uint16";
+            readonly internalType: "uint16";
+        }, {
+            readonly name: "apUSDMintDisabled";
+            readonly type: "bool";
+            readonly internalType: "bool";
+        }];
+    }];
+    readonly stateMutability: "view";
 }, {
     readonly type: "function";
     readonly name: "getFeeTier";

package/dist/index.js

@@ -363,6 +363,16 @@ var DiamondABI = [
     outputs: [{ name: "", type: "uint256", internalType: "uint256" }],
     stateMutability: "view"
   },
+  {
+    type: "function",
+    name: "previewRedeemMulti",
+    inputs: [{ name: "_shares", type: "uint256", internalType: "uint256" }],
+    outputs: [
+      { name: "assets", type: "address[]", internalType: "address[]" },
+      { name: "amounts", type: "uint256[]", internalType: "uint256[]" }
+    ],
+    stateMutability: "view"
+  },
   {
     type: "function",
     name: "getPendingYield",
@@ -463,6 +473,13 @@ var DiamondABI = [
     outputs: [{ name: "", type: "address", internalType: "address" }],
     stateMutability: "view"
   },
+  {
+    type: "function",
+    name: "setSApUSD",
+    inputs: [{ name: "_sApUSD", type: "address", internalType: "address" }],
+    outputs: [],
+    stateMutability: "nonpayable"
+  },
   {
     type: "function",
     name: "getStabilityPool",
@@ -484,6 +501,25 @@ var DiamondABI = [
     outputs: [{ name: "", type: "uint256", internalType: "uint256" }],
     stateMutability: "view"
   },
+  {
+    type: "function",
+    name: "getAllFeeTiers",
+    inputs: [],
+    outputs: [{
+      name: "",
+      type: "tuple[]",
+      internalType: "struct LibAppStorage.FeeTier[]",
+      components: [
+        { name: "minCR", type: "uint256", internalType: "uint256" },
+        { name: "apUSDMintFee", type: "uint16", internalType: "uint16" },
+        { name: "apUSDRedeemFee", type: "uint16", internalType: "uint16" },
+        { name: "xBNBMintFee", type: "uint16", internalType: "uint16" },
+        { name: "xBNBRedeemFee", type: "uint16", internalType: "uint16" },
+        { name: "apUSDMintDisabled", type: "bool", internalType: "bool" }
+      ]
+    }],
+    stateMutability: "view"
+  },
   {
     type: "function",
     name: "getFeeTier",
@@ -677,6 +713,138 @@ var DiamondABI = [
   }
 ];
 
+// src/abi/sApUSD.ts
+var SApUSDABI = [
+  // ============ View Functions ============
+  {
+    type: "function",
+    name: "totalAssets",
+    inputs: [],
+    outputs: [{ name: "", type: "uint256", internalType: "uint256" }],
+    stateMutability: "view"
+  },
+  {
+    type: "function",
+    name: "totalSupply",
+    inputs: [],
+    outputs: [{ name: "", type: "uint256", internalType: "uint256" }],
+    stateMutability: "view"
+  },
+  {
+    type: "function",
+    name: "balanceOf",
+    inputs: [{ name: "account", type: "address", internalType: "address" }],
+    outputs: [{ name: "", type: "uint256", internalType: "uint256" }],
+    stateMutability: "view"
+  },
+  {
+    type: "function",
+    name: "previewRedeemMulti",
+    inputs: [
+      { name: "shares", type: "uint256", internalType: "uint256" }
+    ],
+    outputs: [
+      { name: "assets", type: "address[]", internalType: "address[]" },
+      { name: "amounts", type: "uint256[]", internalType: "uint256[]" }
+    ],
+    stateMutability: "view"
+  },
+  {
+    type: "function",
+    name: "hasStabilityConversion",
+    inputs: [],
+    outputs: [
+      { name: "hasXBNB", type: "bool", internalType: "bool" },
+      { name: "xBNBAmount", type: "uint256", internalType: "uint256" }
+    ],
+    stateMutability: "view"
+  },
+  {
+    type: "function",
+    name: "totalValue",
+    inputs: [],
+    outputs: [{ name: "", type: "uint256", internalType: "uint256" }],
+    stateMutability: "view"
+  },
+  {
+    type: "function",
+    name: "underlyingBalances",
+    inputs: [{ name: "_user", type: "address", internalType: "address" }],
+    outputs: [
+      { name: "apUSDBalance", type: "uint256", internalType: "uint256" },
+      { name: "xBNBBalance", type: "uint256", internalType: "uint256" }
+    ],
+    stateMutability: "view"
+  },
+  {
+    type: "function",
+    name: "xBNBToApUSDRate",
+    inputs: [],
+    outputs: [{ name: "", type: "uint256", internalType: "uint256" }],
+    stateMutability: "view"
+  },
+  {
+    type: "function",
+    name: "exchangeRate",
+    inputs: [],
+    outputs: [{ name: "", type: "uint256", internalType: "uint256" }],
+    stateMutability: "view"
+  },
+  {
+    type: "function",
+    name: "previewCleanXBNB",
+    inputs: [
+      { name: "_xBNBAmount", type: "uint256", internalType: "uint256" },
+      { name: "_router", type: "address", internalType: "address" },
+      { name: "_path", type: "address[]", internalType: "address[]" }
+    ],
+    outputs: [{ name: "expectedApUSD", type: "uint256", internalType: "uint256" }],
+    stateMutability: "view"
+  },
+  {
+    type: "function",
+    name: "KEEPER_ROLE",
+    inputs: [],
+    outputs: [{ name: "", type: "bytes32", internalType: "bytes32" }],
+    stateMutability: "view"
+  },
+  {
+    type: "function",
+    name: "hasRole",
+    inputs: [
+      { name: "role", type: "bytes32", internalType: "bytes32" },
+      { name: "account", type: "address", internalType: "address" }
+    ],
+    outputs: [{ name: "", type: "bool", internalType: "bool" }],
+    stateMutability: "view"
+  },
+  // ============ Keeper Functions ============
+  {
+    type: "function",
+    name: "cleanXBNB",
+    inputs: [
+      { name: "_xBNBAmount", type: "uint256", internalType: "uint256" },
+      { name: "_minApUSDOut", type: "uint256", internalType: "uint256" },
+      { name: "_router", type: "address", internalType: "address" },
+      { name: "_path", type: "address[]", internalType: "address[]" },
+      { name: "_deadline", type: "uint256", internalType: "uint256" }
+    ],
+    outputs: [{ name: "apUSDReceived", type: "uint256", internalType: "uint256" }],
+    stateMutability: "nonpayable"
+  },
+  // ============ Events ============
+  {
+    type: "event",
+    name: "VaultCleaned",
+    inputs: [
+      { name: "xBNBSold", type: "uint256", indexed: false, internalType: "uint256" },
+      { name: "apUSDReceived", type: "uint256", indexed: false, internalType: "uint256" },
+      { name: "keeper", type: "address", indexed: true, internalType: "address" }
+    ],
+    anonymous: false
+  }
+];
+
 // src/client.ts
 var pharosTestnet = {
   id: 688689,
@@ -1070,6 +1238,19 @@ var AspanReadClient = class _AspanReadClient {
       args: [user]
     });
   }
+  /**
+   * Get user's underlying balances (apUSD + xBNB) from sApUSD vault
+   */
+  async getBalanceMulti(user) {
+    const sApUSDAddress = await this.getSApUSD();
+    const [apUSDBalance, xBNBBalance] = await this.publicClient.readContract({
+      address: sApUSDAddress,
+      abi: SApUSDABI,
+      functionName: "underlyingBalances",
+      args: [user]
+    });
+    return { apUSDBalance, xBNBBalance };
+  }
   async getUserStabilityPoolPosition(user) {
     const [shares, balance] = await Promise.all([
       this.getShares(user),
@@ -1120,20 +1301,27 @@ var AspanReadClient = class _AspanReadClient {
       throw error;
     }
   }
-  async previewRedeem(shares) {
-    try {
-      return await this.publicClient.readContract({
-        address: this.diamondAddress,
-        abi: DiamondABI,
-        functionName: "previewRedeem",
-        args: [shares]
-      });
-    } catch (error) {
-      if (this.isZeroSupplyError(error)) {
-        return shares;
-      }
-      throw error;
-    }
+  /**
+   * Preview withdraw with multi-asset support (apUSD + xBNB)
+   * Replaces previewRedeem — works for both clean and dirty pools.
+   * @param shares Amount of sApUSD shares to redeem
+   * @returns Object with apUSD and xBNB amounts, plus whether vault has xBNB
+   */
+  async previewRedeemMulti(shares) {
+    const [assets, amounts] = await this.publicClient.readContract({
+      address: this.diamondAddress,
+      abi: DiamondABI,
+      functionName: "previewRedeemMulti",
+      args: [shares]
+    });
+    const hasXBNB = amounts.length > 1 && amounts[1] > 0n;
+    return {
+      apUSD: amounts[0] ?? 0n,
+      xBNB: amounts[1] ?? 0n,
+      hasXBNB,
+      assets,
+      amounts
+    };
   }
   async getPendingYield() {
     try {
@@ -1288,6 +1476,93 @@ var AspanReadClient = class _AspanReadClient {
       apUSDMintDisabled: result[5]
     };
   }
+  /**
+   * Get all fee tiers
+   * @returns Array of fee tiers sorted by minCR descending
+   */
+  async getAllFeeTiers() {
+    const result = await this.publicClient.readContract({
+      address: this.diamondAddress,
+      abi: DiamondABI,
+      functionName: "getAllFeeTiers"
+    });
+    return result.map((tier) => ({
+      minCR: tier.minCR,
+      apUSDMintFee: tier.apUSDMintFee,
+      apUSDRedeemFee: tier.apUSDRedeemFee,
+      xBNBMintFee: tier.xBNBMintFee,
+      xBNBRedeemFee: tier.xBNBRedeemFee,
+      apUSDMintDisabled: tier.apUSDMintDisabled
+    }));
+  }
+  /**
+   * Get comprehensive vault (sApUSD) info for frontend display
+   * @returns Vault state including TVL, exchange rate, xBNB status
+   */
+  async getVaultInfo() {
+    const sApUSDAddress = await this.getSApUSD();
+    const [totalSupply, totalAssets, exchangeRate, conversion] = await Promise.all([
+      this.publicClient.readContract({
+        address: sApUSDAddress,
+        abi: SApUSDABI,
+        functionName: "totalSupply"
+      }),
+      this.publicClient.readContract({
+        address: sApUSDAddress,
+        abi: SApUSDABI,
+        functionName: "totalAssets"
+      }),
+      this.publicClient.readContract({
+        address: sApUSDAddress,
+        abi: SApUSDABI,
+        functionName: "exchangeRate"
+      }),
+      this.publicClient.readContract({
+        address: sApUSDAddress,
+        abi: SApUSDABI,
+        functionName: "hasStabilityConversion"
+      })
+    ]);
+    return {
+      totalSupply,
+      totalAssets,
+      exchangeRate,
+      hasXBNB: conversion[0],
+      xBNBAmount: conversion[1]
+    };
+  }
+  /**
+   * Get full protocol dashboard data in one call (for frontend overview page)
+   * Batches all key metrics into a single multicall
+   */
+  async getProtocolOverview() {
+    const [cr, tvlBNB, tvlUSD, apUSD, xBNB, xPriceUSD, xPriceBNB, bnbPrice, fees, sm, staked] = await Promise.all([
+      this.getCollateralRatio(),
+      this.getTVLInBNB(),
+      this.getTVLInUSD(),
+      this.getApUSDSupply(),
+      this.getXBNBSupply(),
+      this.getXBNBPriceUSD(),
+      this.getXBNBPriceBNB(),
+      this.getBNBPriceUSD(),
+      this.getCurrentFeeTier(),
+      this.getStabilityMode(),
+      this.getTotalStaked()
+    ]);
+    return {
+      collateralRatio: cr,
+      tvlBNB,
+      tvlUSD,
+      apUSDSupply: apUSD,
+      xBNBSupply: xBNB,
+      xBNBPriceUSD: xPriceUSD,
+      xBNBPriceBNB: xPriceBNB,
+      bnbPriceUSD: bnbPrice,
+      currentFees: fees,
+      stabilityMode: sm,
+      totalStaked: staked
+    };
+  }
   async getCurrentFeeTier() {
     try {
       const result = await this.publicClient.readContract({