@aspan/sdk 0.4.0 → 0.4.1

package/README.md

@@ -21,12 +21,12 @@ import { BSC_ADDRESSES } from "@aspan/sdk";
 
 | Contract | Address |
 |----------|---------|
-| **Diamond (Main Entry)** | `0x10d25Ae0690533e0BA9E64EC7ae77dbD4fE8A46f` |
+| **Diamond (Main Entry)** | `0x6a11B30d3a70727d5477D6d8090e144443fA1c78` |
 | **Router** | `0x813d3D1A3154950E2f1d8718305426a335A974A9` |
-| **ApUSD** | `0x1977097E2E5697A6DD91b6732F368a14F50f6B3d` |
-| **XBNB** | `0xB78eB4d5928bAb158Eb23c3154544084cD2661d5` |
+| **ApUSD** | `0x4570047eeB5aDb4081c5d470494EB5134e34A287` |
+| **XBNB** | `0x0A0c9CD826e747D99F90D63e780B3727Da4D0d43` |
 | **SApUSD** | `0xE2BE739C4aA4126ee72D612d9548C38B1B0e5A1b` |
-| **wclisBNB** | `0x439faaC2229559121C4Ad4fd8B3FE13Dff038046` |
+| **wclisBNB** | `0x448f7c2fa4e5135a4a5B50879602cf3CD428e108` |
 
 ## Quick Start
 
@@ -576,6 +576,46 @@ const client = createAspanTestnetReadClient("0x...");
 const router = createRouterTestnetClient("0x...", account);
 ```
 
+---
+
+## Risk Keeper Bot
+
+The SDK includes a Risk Keeper service for automated risk management:
+
+### Features
+
+1. **Stability Mode 2 Trigger** - Automatically triggers SM2 when CR < 130%
+2. **TWAP Vault Cleaning** - Cleans xBNB from sApUSD vault after SM2
+
+### Environment Variables
+
+```bash
+# Required for Risk Keeper
+RISK_KEEPER_ENABLED=true
+KEEPER_PRIVATE_KEY=0x...
+SAPUSD_ADDRESS=0xE2BE739C4aA4126ee72D612d9548C38B1B0e5A1b
+
+# Optional (with defaults)
+ROUTER_ADDRESS=0x10ED43C718714eb63d5aA57B78B54704E256024E  # PancakeSwap V2
+WBNB_ADDRESS=0xbb4CdB9CBd36B01bD1cBaEBF2De08d9173bc095c
+SM2_COOLDOWN_MS=1800000     # 30 min
+TWAP_INTERVAL_MS=600000     # 10 min
+TWAP_PERCENTAGE=5           # 5% per batch
+MAX_SLIPPAGE_BPS=50         # 0.5%
+TWAP_START_CR=13500         # 135%
+```
+
+### Risk Management Functions
+
+| Function | Description |
+|----------|-------------|
+| `triggerStabilityMode2(targetCR)` | Trigger SM2 forced conversion |
+| `cleanXbnb(amount)` | Clean underwater xBNB (user burn) |
+| `canTriggerStabilityMode2()` | Check if SM2 can be triggered |
+| `getStabilityMode()` | Get current stability mode (0/1/2) |
+
+---
+
 ## License
 
 MIT

package/dist/index.d.mts

@@ -464,6 +464,16 @@ declare class AspanReadClient {
     getMaxPriceAge(): Promise<bigint>;
     getMinDepositPeriod(): Promise<bigint>;
     isPaused(): Promise<boolean>;
+    /**
+     * Check if xBNB liquidity has been bootstrapped
+     * @returns true if bootstrap has been called
+     */
+    isBootstrapped(): Promise<boolean>;
+    /**
+     * Get the amount of xBNB locked in bootstrap (burned to dead address)
+     * @returns xBNB amount in wei
+     */
+    getBootstrapXBNBAmount(): Promise<bigint>;
     getStabilityMode(): Promise<StabilityModeInfo>;
     canTriggerStabilityMode2(): Promise<StabilityMode2Info>;
     getOwner(): Promise<Address>;
@@ -521,6 +531,43 @@ declare class AspanClient extends AspanReadClient {
      * @returns Transaction hash
      */
     harvestYield(): Promise<Hash>;
+    /**
+     * Trigger Stability Mode 2 forced conversion
+     * @description Anyone can call when CR < 130%. Burns apUSD from stability pool
+     * and mints xBNB to compensate stakers.
+     * @param targetCR Target CR to restore to (in BPS, e.g., 14000 = 140%)
+     * @returns Transaction hash
+     */
+    triggerStabilityMode2(targetCR?: bigint): Promise<Hash>;
+    /**
+     * Clean underwater xBNB (burn without getting LST back)
+     * @description Only works when xBNB is underwater (price = 0)
+     * @param xBNBAmount Amount of xBNB to clean (burn)
+     * @returns Transaction hash
+     */
+    cleanXbnb(xBNBAmount: bigint): Promise<Hash>;
+    /**
+     * Set fee tiers (requires feeManager or owner role)
+     * @param tiers Array of fee tier configurations
+     * @returns Transaction hash
+     */
+    setFeeTiers(tiers: Array<{
+        minCR: bigint;
+        apUSDMintFee: number;
+        apUSDRedeemFee: number;
+        xBNBMintFee: number;
+        xBNBRedeemFee: number;
+        apUSDMintDisabled: boolean;
+    }>): Promise<Hash>;
+    /**
+     * Bootstrap xBNB liquidity (owner only)
+     * @description Initializes xBNB supply by minting to dead address, preventing extreme initial prices.
+     * Similar to Uniswap V2's MINIMUM_LIQUIDITY. Can only be called once.
+     * @param lstToken LST token address to deposit
+     * @param lstAmount Amount of LST to deposit for bootstrap
+     * @returns Transaction hash
+     */
+    bootstrap(lstToken: Address, lstAmount: bigint): Promise<Hash>;
     /**
      * Wait for transaction confirmation
      * @param hash Transaction hash
@@ -1536,6 +1583,44 @@ declare const DiamondABI: readonly [{
         readonly internalType: "bool";
     }];
     readonly stateMutability: "view";
+}, {
+    readonly type: "function";
+    readonly name: "bootstrap";
+    readonly inputs: readonly [{
+        readonly name: "_lstToken";
+        readonly type: "address";
+        readonly internalType: "address";
+    }, {
+        readonly name: "_lstAmount";
+        readonly type: "uint256";
+        readonly internalType: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "xBNBAmount";
+        readonly type: "uint256";
+        readonly internalType: "uint256";
+    }];
+    readonly stateMutability: "nonpayable";
+}, {
+    readonly type: "function";
+    readonly name: "isBootstrapped";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "bool";
+        readonly internalType: "bool";
+    }];
+    readonly stateMutability: "view";
+}, {
+    readonly type: "function";
+    readonly name: "getBootstrapXBNBAmount";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+        readonly internalType: "uint256";
+    }];
+    readonly stateMutability: "view";
 }, {
     readonly type: "function";
     readonly name: "getStabilityMode";
@@ -1586,6 +1671,16 @@ declare const DiamondABI: readonly [{
         readonly internalType: "uint256";
     }];
     readonly stateMutability: "nonpayable";
+}, {
+    readonly type: "function";
+    readonly name: "cleanXbnb";
+    readonly inputs: readonly [{
+        readonly name: "_xBNBAmount";
+        readonly type: "uint256";
+        readonly internalType: "uint256";
+    }];
+    readonly outputs: readonly [];
+    readonly stateMutability: "nonpayable";
 }, {
     readonly type: "event";
     readonly name: "StabilityMode2Triggered";
@@ -1621,6 +1716,71 @@ declare const DiamondABI: readonly [{
         readonly internalType: "address";
     }];
     readonly stateMutability: "view";
+}, {
+    readonly type: "function";
+    readonly name: "setFeeManager";
+    readonly inputs: readonly [{
+        readonly name: "_feeManager";
+        readonly type: "address";
+        readonly internalType: "address";
+    }];
+    readonly outputs: readonly [];
+    readonly stateMutability: "nonpayable";
+}, {
+    readonly type: "function";
+    readonly name: "getFeeManager";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "address";
+        readonly internalType: "address";
+    }];
+    readonly stateMutability: "view";
+}, {
+    readonly type: "function";
+    readonly name: "setFeeTiers";
+    readonly inputs: readonly [{
+        readonly name: "_tiers";
+        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 outputs: readonly [];
+    readonly stateMutability: "nonpayable";
+}, {
+    readonly type: "event";
+    readonly name: "FeeManagerSet";
+    readonly inputs: readonly [{
+        readonly name: "feeManager";
+        readonly type: "address";
+        readonly indexed: true;
+        readonly internalType: "address";
+    }];
+    readonly anonymous: false;
 }];
 
 /**
@@ -2413,14 +2573,14 @@ declare const PRECISION: bigint;
 declare const BPS_PRECISION = 10000n;
 declare const PRICE_PRECISION: bigint;
 declare const BSC_ADDRESSES: {
-    readonly diamond: "0x10d25Ae0690533e0BA9E64EC7ae77dbD4fE8A46f";
+    readonly diamond: "0x6a11B30d3a70727d5477D6d8090e144443fA1c78";
     readonly router: "0x813d3D1A3154950E2f1d8718305426a335A974A9";
-    readonly apUSD: "0x1977097E2E5697A6DD91b6732F368a14F50f6B3d";
-    readonly xBNB: "0xB78eB4d5928bAb158Eb23c3154544084cD2661d5";
-    readonly sApUSD: "0xE2BE739C4aA4126ee72D612d9548C38B1B0e5A1b";
+    readonly apUSD: "0x4570047eeB5aDb4081c5d470494EB5134e34A287";
+    readonly xBNB: "0x0A0c9CD826e747D99F90D63e780B3727Da4D0d43";
+    readonly sApUSD: "0x73407A291c007a47CC926EcD5CaC256A1E2d00cF";
     readonly slisBNB: "0xB0b84D294e0C75A6abe60171b70edEb2EFd14A1B";
     readonly asBNB: "0x77734e70b6E88b4d82fE632a168EDf6e700912b6";
-    readonly wclisBNB: "0x439faaC2229559121C4Ad4fd8B3FE13Dff038046";
+    readonly wclisBNB: "0x448f7c2fa4e5135a4a5B50879602cf3CD428e108";
     readonly USDT: "0x55d398326f99059fF775485246999027B3197955";
     readonly USDC: "0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d";
     readonly WBNB: "0xbb4CdB9CBd36B01bD1cBaEBF2De08d9173bc095c";

package/dist/index.d.ts

@@ -464,6 +464,16 @@ declare class AspanReadClient {
     getMaxPriceAge(): Promise<bigint>;
     getMinDepositPeriod(): Promise<bigint>;
     isPaused(): Promise<boolean>;
+    /**
+     * Check if xBNB liquidity has been bootstrapped
+     * @returns true if bootstrap has been called
+     */
+    isBootstrapped(): Promise<boolean>;
+    /**
+     * Get the amount of xBNB locked in bootstrap (burned to dead address)
+     * @returns xBNB amount in wei
+     */
+    getBootstrapXBNBAmount(): Promise<bigint>;
     getStabilityMode(): Promise<StabilityModeInfo>;
     canTriggerStabilityMode2(): Promise<StabilityMode2Info>;
     getOwner(): Promise<Address>;
@@ -521,6 +531,43 @@ declare class AspanClient extends AspanReadClient {
      * @returns Transaction hash
      */
     harvestYield(): Promise<Hash>;
+    /**
+     * Trigger Stability Mode 2 forced conversion
+     * @description Anyone can call when CR < 130%. Burns apUSD from stability pool
+     * and mints xBNB to compensate stakers.
+     * @param targetCR Target CR to restore to (in BPS, e.g., 14000 = 140%)
+     * @returns Transaction hash
+     */
+    triggerStabilityMode2(targetCR?: bigint): Promise<Hash>;
+    /**
+     * Clean underwater xBNB (burn without getting LST back)
+     * @description Only works when xBNB is underwater (price = 0)
+     * @param xBNBAmount Amount of xBNB to clean (burn)
+     * @returns Transaction hash
+     */
+    cleanXbnb(xBNBAmount: bigint): Promise<Hash>;
+    /**
+     * Set fee tiers (requires feeManager or owner role)
+     * @param tiers Array of fee tier configurations
+     * @returns Transaction hash
+     */
+    setFeeTiers(tiers: Array<{
+        minCR: bigint;
+        apUSDMintFee: number;
+        apUSDRedeemFee: number;
+        xBNBMintFee: number;
+        xBNBRedeemFee: number;
+        apUSDMintDisabled: boolean;
+    }>): Promise<Hash>;
+    /**
+     * Bootstrap xBNB liquidity (owner only)
+     * @description Initializes xBNB supply by minting to dead address, preventing extreme initial prices.
+     * Similar to Uniswap V2's MINIMUM_LIQUIDITY. Can only be called once.
+     * @param lstToken LST token address to deposit
+     * @param lstAmount Amount of LST to deposit for bootstrap
+     * @returns Transaction hash
+     */
+    bootstrap(lstToken: Address, lstAmount: bigint): Promise<Hash>;
     /**
      * Wait for transaction confirmation
      * @param hash Transaction hash
@@ -1536,6 +1583,44 @@ declare const DiamondABI: readonly [{
         readonly internalType: "bool";
     }];
     readonly stateMutability: "view";
+}, {
+    readonly type: "function";
+    readonly name: "bootstrap";
+    readonly inputs: readonly [{
+        readonly name: "_lstToken";
+        readonly type: "address";
+        readonly internalType: "address";
+    }, {
+        readonly name: "_lstAmount";
+        readonly type: "uint256";
+        readonly internalType: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "xBNBAmount";
+        readonly type: "uint256";
+        readonly internalType: "uint256";
+    }];
+    readonly stateMutability: "nonpayable";
+}, {
+    readonly type: "function";
+    readonly name: "isBootstrapped";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "bool";
+        readonly internalType: "bool";
+    }];
+    readonly stateMutability: "view";
+}, {
+    readonly type: "function";
+    readonly name: "getBootstrapXBNBAmount";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+        readonly internalType: "uint256";
+    }];
+    readonly stateMutability: "view";
 }, {
     readonly type: "function";
     readonly name: "getStabilityMode";
@@ -1586,6 +1671,16 @@ declare const DiamondABI: readonly [{
         readonly internalType: "uint256";
     }];
     readonly stateMutability: "nonpayable";
+}, {
+    readonly type: "function";
+    readonly name: "cleanXbnb";
+    readonly inputs: readonly [{
+        readonly name: "_xBNBAmount";
+        readonly type: "uint256";
+        readonly internalType: "uint256";
+    }];
+    readonly outputs: readonly [];
+    readonly stateMutability: "nonpayable";
 }, {
     readonly type: "event";
     readonly name: "StabilityMode2Triggered";
@@ -1621,6 +1716,71 @@ declare const DiamondABI: readonly [{
         readonly internalType: "address";
     }];
     readonly stateMutability: "view";
+}, {
+    readonly type: "function";
+    readonly name: "setFeeManager";
+    readonly inputs: readonly [{
+        readonly name: "_feeManager";
+        readonly type: "address";
+        readonly internalType: "address";
+    }];
+    readonly outputs: readonly [];
+    readonly stateMutability: "nonpayable";
+}, {
+    readonly type: "function";
+    readonly name: "getFeeManager";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "address";
+        readonly internalType: "address";
+    }];
+    readonly stateMutability: "view";
+}, {
+    readonly type: "function";
+    readonly name: "setFeeTiers";
+    readonly inputs: readonly [{
+        readonly name: "_tiers";
+        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 outputs: readonly [];
+    readonly stateMutability: "nonpayable";
+}, {
+    readonly type: "event";
+    readonly name: "FeeManagerSet";
+    readonly inputs: readonly [{
+        readonly name: "feeManager";
+        readonly type: "address";
+        readonly indexed: true;
+        readonly internalType: "address";
+    }];
+    readonly anonymous: false;
 }];
 
 /**
@@ -2413,14 +2573,14 @@ declare const PRECISION: bigint;
 declare const BPS_PRECISION = 10000n;
 declare const PRICE_PRECISION: bigint;
 declare const BSC_ADDRESSES: {
-    readonly diamond: "0x10d25Ae0690533e0BA9E64EC7ae77dbD4fE8A46f";
+    readonly diamond: "0x6a11B30d3a70727d5477D6d8090e144443fA1c78";
     readonly router: "0x813d3D1A3154950E2f1d8718305426a335A974A9";
-    readonly apUSD: "0x1977097E2E5697A6DD91b6732F368a14F50f6B3d";
-    readonly xBNB: "0xB78eB4d5928bAb158Eb23c3154544084cD2661d5";
-    readonly sApUSD: "0xE2BE739C4aA4126ee72D612d9548C38B1B0e5A1b";
+    readonly apUSD: "0x4570047eeB5aDb4081c5d470494EB5134e34A287";
+    readonly xBNB: "0x0A0c9CD826e747D99F90D63e780B3727Da4D0d43";
+    readonly sApUSD: "0x73407A291c007a47CC926EcD5CaC256A1E2d00cF";
     readonly slisBNB: "0xB0b84D294e0C75A6abe60171b70edEb2EFd14A1B";
     readonly asBNB: "0x77734e70b6E88b4d82fE632a168EDf6e700912b6";
-    readonly wclisBNB: "0x439faaC2229559121C4Ad4fd8B3FE13Dff038046";
+    readonly wclisBNB: "0x448f7c2fa4e5135a4a5B50879602cf3CD428e108";
     readonly USDT: "0x55d398326f99059fF775485246999027B3197955";
     readonly USDC: "0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d";
     readonly WBNB: "0xbb4CdB9CBd36B01bD1cBaEBF2De08d9173bc095c";