@aspan/sdk 0.4.4 → 0.4.6

package/dist/index.mjs

@@ -305,6 +305,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",
@@ -405,6 +415,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",
@@ -426,6 +443,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",
@@ -619,6 +655,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,
@@ -1012,6 +1180,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),
@@ -1062,20 +1243,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 {
@@ -1230,6 +1418,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({

package/package.json

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

package/src/__tests__/read-client.test.ts

@@ -0,0 +1,212 @@
+/**
+ * AspanReadClient Tests - Read-only queries against BSC mainnet
+ *
+ * Tests new SDK methods: previewRedeemMulti, getVaultInfo, getAllFeeTiers, getProtocolOverview
+ * No wallet/private key needed — pure view calls.
+ *
+ * Run with: npm test -- read-client
+ */
+
+import { describe, it, expect, beforeAll } from "vitest";
+import { parseEther, zeroAddress, type Address } from "viem";
+import { bsc } from "viem/chains";
+import { AspanReadClient, BSC_ADDRESSES } from "../index";
+
+// ============ Configuration ============
+
+const DIAMOND = BSC_ADDRESSES.diamond;
+const RPC_URL = process.env.BSC_RPC_URL || "https://bsc-dataseed.binance.org";
+
+describe("AspanReadClient - View Functions", () => {
+  let client: AspanReadClient;
+
+  beforeAll(() => {
+    client = new AspanReadClient({
+      diamondAddress: DIAMOND,
+      chain: bsc,
+      rpcUrl: RPC_URL,
+    });
+  });
+
+  // ============ Vault Info ============
+
+  describe("getVaultInfo", () => {
+    it("should return vault state with all fields", async () => {
+      const info = await client.getVaultInfo();
+
+      expect(info).toHaveProperty("totalSupply");
+      expect(info).toHaveProperty("totalAssets");
+      expect(info).toHaveProperty("exchangeRate");
+      expect(info).toHaveProperty("hasXBNB");
+      expect(info).toHaveProperty("xBNBAmount");
+
+      expect(typeof info.totalSupply).toBe("bigint");
+      expect(typeof info.totalAssets).toBe("bigint");
+      expect(typeof info.exchangeRate).toBe("bigint");
+      expect(typeof info.hasXBNB).toBe("boolean");
+      expect(typeof info.xBNBAmount).toBe("bigint");
+
+      // Exchange rate should be > 0 (at least 1e18 for 1:1)
+      expect(info.exchangeRate).toBeGreaterThan(0n);
+    });
+  });
+
+  // ============ Preview Redeem Multi ============
+
+  describe("previewRedeemMulti", () => {
+    it("should return apUSD and xBNB amounts for given shares", async () => {
+      const shares = parseEther("1"); // 1 share
+      const preview = await client.previewRedeemMulti(shares);
+
+      expect(preview).toHaveProperty("apUSD");
+      expect(preview).toHaveProperty("xBNB");
+      expect(preview).toHaveProperty("hasXBNB");
+
+      expect(typeof preview.apUSD).toBe("bigint");
+      expect(typeof preview.xBNB).toBe("bigint");
+      expect(typeof preview.hasXBNB).toBe("boolean");
+    });
+
+    it("should return zero for zero shares", async () => {
+      const preview = await client.previewRedeemMulti(0n);
+
+      expect(preview.apUSD).toBe(0n);
+      expect(preview.xBNB).toBe(0n);
+    });
+
+    it("should have consistent hasXBNB with getVaultInfo", async () => {
+      const shares = parseEther("1");
+      const [preview, vault] = await Promise.all([
+        client.previewRedeemMulti(shares),
+        client.getVaultInfo(),
+      ]);
+
+      expect(preview.hasXBNB).toBe(vault.hasXBNB);
+    });
+  });
+
+  // ============ Fee Tiers ============
+
+  describe("getAllFeeTiers", () => {
+    it("should return non-empty array of fee tiers", async () => {
+      const tiers = await client.getAllFeeTiers();
+
+      expect(Array.isArray(tiers)).toBe(true);
+      expect(tiers.length).toBeGreaterThan(0);
+    });
+
+    it("should have correct fee tier structure", async () => {
+      const tiers = await client.getAllFeeTiers();
+      const tier = tiers[0];
+
+      expect(tier).toHaveProperty("minCR");
+      expect(tier).toHaveProperty("apUSDMintFee");
+      expect(tier).toHaveProperty("apUSDRedeemFee");
+      expect(tier).toHaveProperty("xBNBMintFee");
+      expect(tier).toHaveProperty("xBNBRedeemFee");
+      expect(tier).toHaveProperty("apUSDMintDisabled");
+
+      expect(typeof tier.minCR).toBe("bigint");
+      expect(typeof tier.apUSDMintDisabled).toBe("boolean");
+    });
+
+    it("should be sorted by minCR descending", async () => {
+      const tiers = await client.getAllFeeTiers();
+
+      for (let i = 1; i < tiers.length; i++) {
+        expect(tiers[i - 1].minCR).toBeGreaterThanOrEqual(tiers[i].minCR);
+      }
+    });
+
+    it("should match getFeeTierCount", async () => {
+      const [tiers, count] = await Promise.all([
+        client.getAllFeeTiers(),
+        client.getFeeTierCount(),
+      ]);
+
+      expect(BigInt(tiers.length)).toBe(count);
+    });
+  });
+
+  // ============ Protocol Overview ============
+
+  describe("getProtocolOverview", () => {
+    it("should return all protocol metrics", async () => {
+      const overview = await client.getProtocolOverview();
+
+      expect(overview).toHaveProperty("collateralRatio");
+      expect(overview).toHaveProperty("tvlBNB");
+      expect(overview).toHaveProperty("tvlUSD");
+      expect(overview).toHaveProperty("apUSDSupply");
+      expect(overview).toHaveProperty("xBNBSupply");
+      expect(overview).toHaveProperty("xBNBPriceUSD");
+      expect(overview).toHaveProperty("xBNBPriceBNB");
+      expect(overview).toHaveProperty("bnbPriceUSD");
+      expect(overview).toHaveProperty("currentFees");
+      expect(overview).toHaveProperty("stabilityMode");
+      expect(overview).toHaveProperty("totalStaked");
+    });
+
+    it("should have positive TVL and prices", async () => {
+      const overview = await client.getProtocolOverview();
+
+      expect(overview.tvlBNB).toBeGreaterThan(0n);
+      expect(overview.tvlUSD).toBeGreaterThan(0n);
+      expect(overview.bnbPriceUSD).toBeGreaterThan(0n);
+      expect(overview.collateralRatio).toBeGreaterThan(0n);
+    });
+
+    it("should have valid currentFees structure", async () => {
+      const overview = await client.getProtocolOverview();
+      const fees = overview.currentFees;
+
+      expect(fees).toHaveProperty("minCR");
+      expect(fees).toHaveProperty("apUSDMintFee");
+    });
+
+    it("should have valid stabilityMode structure", async () => {
+      const overview = await client.getProtocolOverview();
+      const sm = overview.stabilityMode;
+
+      expect(sm).toHaveProperty("mode");
+      // mode should be 0 (normal), 1, or 2
+      expect([0, 1, 2]).toContain(sm.mode);
+    });
+  });
+
+  // ============ Existing view methods consistency ============
+
+  describe("cross-method consistency", () => {
+    it("vault totalStaked should match getVaultInfo totalSupply context", async () => {
+      const [staked, vault] = await Promise.all([
+        client.getTotalStaked(),
+        client.getVaultInfo(),
+      ]);
+
+      // totalStaked from Diamond should relate to vault totalAssets
+      expect(typeof staked).toBe("bigint");
+      expect(typeof vault.totalAssets).toBe("bigint");
+    });
+
+    it("exchangeRate from getVaultInfo should match getExchangeRate", async () => {
+      const [vault, rate] = await Promise.all([
+        client.getVaultInfo(),
+        client.getExchangeRate(),
+      ]);
+
+      expect(vault.exchangeRate).toBe(rate);
+    });
+  });
+
+  describe("getBalanceMulti", () => {
+    it("should return apUSD and xBNB balances for a user", async () => {
+      const testUser = zeroAddress; // zero address will have 0 balances
+      const result = await client.getBalanceMulti(testUser);
+
+      expect(typeof result.apUSDBalance).toBe("bigint");
+      expect(typeof result.xBNBBalance).toBe("bigint");
+      expect(result.apUSDBalance).toBe(0n);
+      expect(result.xBNBBalance).toBe(0n);
+    });
+  });
+});

package/src/abi/diamond.ts

@@ -303,6 +303,16 @@ export const 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",
@@ -406,6 +416,13 @@ export const 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",
@@ -427,6 +444,25 @@ export const 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",

package/src/abi/sApUSD.ts

@@ -25,6 +25,18 @@ export const SApUSDABI = [
     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",
@@ -35,6 +47,30 @@ export const SApUSDABI = [
     ],
     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",