@aspan/sdk 0.1.4

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@aspan/sdk",
+  "version": "0.1.4",
+  "description": "TypeScript SDK for Aspan Protocol - LST-backed stablecoin on BNB Chain",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "lint": "eslint src --ext .ts",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run build",
+    "bot": "tsx src/bot/index.ts",
+    "bot:dev": "tsx watch src/bot/index.ts"
+  },
+  "keywords": [
+    "aspan",
+    "defi",
+    "stablecoin",
+    "lst",
+    "bnb",
+    "ethereum",
+    "web3",
+    "sdk"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "viem": "^2.21.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "tsup": "^8.0.1",
+    "typescript": "^5.3.0",
+    "vitest": "^1.0.0",
+    "eslint": "^8.55.0",
+    "@typescript-eslint/eslint-plugin": "^6.13.0",
+    "@typescript-eslint/parser": "^6.13.0",
+    "tsx": "^4.7.0",
+    "dotenv": "^16.3.1"
+  },
+  "peerDependencies": {
+    "viem": ">=2.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/abi/diamond.ts

@@ -0,0 +1,531 @@
+/**
+ * Combined Diamond ABI - includes all facet functions
+ * This ABI is used to interact with the Aspan Diamond contract
+ */
+export const DiamondABI = [
+  // ============ PoolFacet ============
+  {
+    type: "function",
+    name: "mintApUSD",
+    inputs: [
+      { name: "_lstToken", type: "address", internalType: "address" },
+      { name: "_lstAmount", type: "uint256", internalType: "uint256" }
+    ],
+    outputs: [{ name: "apUSDAmount", type: "uint256", internalType: "uint256" }],
+    stateMutability: "nonpayable"
+  },
+  {
+    type: "function",
+    name: "redeemApUSD",
+    inputs: [
+      { name: "_lstToken", type: "address", internalType: "address" },
+      { name: "_apUSDAmount", type: "uint256", internalType: "uint256" }
+    ],
+    outputs: [{ name: "lstAmount", type: "uint256", internalType: "uint256" }],
+    stateMutability: "nonpayable"
+  },
+  {
+    type: "function",
+    name: "mintXBNB",
+    inputs: [
+      { name: "_lstToken", type: "address", internalType: "address" },
+      { name: "_lstAmount", type: "uint256", internalType: "uint256" }
+    ],
+    outputs: [{ name: "xBNBAmount", type: "uint256", internalType: "uint256" }],
+    stateMutability: "nonpayable"
+  },
+  {
+    type: "function",
+    name: "redeemXBNB",
+    inputs: [
+      { name: "_lstToken", type: "address", internalType: "address" },
+      { name: "_xBNBAmount", type: "uint256", internalType: "uint256" }
+    ],
+    outputs: [{ name: "lstAmount", type: "uint256", internalType: "uint256" }],
+    stateMutability: "nonpayable"
+  },
+  {
+    type: "function",
+    name: "getXBNBPriceBNB",
+    inputs: [],
+    outputs: [{ name: "", type: "uint256", internalType: "uint256" }],
+    stateMutability: "view"
+  },
+  {
+    type: "function",
+    name: "getXBNBPriceUSD",
+    inputs: [],
+    outputs: [{ name: "", type: "uint256", internalType: "uint256" }],
+    stateMutability: "view"
+  },
+  {
+    type: "function",
+    name: "getTVLInBNB",
+    inputs: [],
+    outputs: [{ name: "", type: "uint256", internalType: "uint256" }],
+    stateMutability: "view"
+  },
+  {
+    type: "function",
+    name: "getTVLInUSD",
+    inputs: [],
+    outputs: [{ name: "", type: "uint256", internalType: "uint256" }],
+    stateMutability: "view"
+  },
+  {
+    type: "function",
+    name: "getCollateralRatio",
+    inputs: [],
+    outputs: [{ name: "", type: "uint256", internalType: "uint256" }],
+    stateMutability: "view"
+  },
+  {
+    type: "function",
+    name: "getCurrentFees",
+    inputs: [],
+    outputs: [
+      { name: "currentCR", type: "uint256", internalType: "uint256" },
+      { name: "tierMinCR", 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: "getEffectiveLeverage",
+    inputs: [],
+    outputs: [{ name: "", type: "uint256", internalType: "uint256" }],
+    stateMutability: "view"
+  },
+  {
+    type: "function",
+    name: "getApUSDSupply",
+    inputs: [],
+    outputs: [{ name: "", type: "uint256", internalType: "uint256" }],
+    stateMutability: "view"
+  },
+  {
+    type: "function",
+    name: "getXBNBSupply",
+    inputs: [],
+    outputs: [{ name: "", type: "uint256", internalType: "uint256" }],
+    stateMutability: "view"
+  },
+  {
+    type: "function",
+    name: "getLSTCollateral",
+    inputs: [{ name: "_lstToken", type: "address", internalType: "address" }],
+    outputs: [{ name: "amount", type: "uint256", internalType: "uint256" }],
+    stateMutability: "view"
+  },
+
+  // ============ PoolFacet Events ============
+  {
+    type: "event",
+    name: "ApUSDMinted",
+    inputs: [
+      { name: "user", type: "address", indexed: true, internalType: "address" },
+      { name: "lstToken", type: "address", indexed: true, internalType: "address" },
+      { name: "lstAmount", type: "uint256", indexed: false, internalType: "uint256" },
+      { name: "apUSDAmount", type: "uint256", indexed: false, internalType: "uint256" },
+      { name: "feeBPS", type: "uint256", indexed: false, internalType: "uint256" }
+    ],
+    anonymous: false
+  },
+  {
+    type: "event",
+    name: "ApUSDRedeemed",
+    inputs: [
+      { name: "user", type: "address", indexed: true, internalType: "address" },
+      { name: "lstToken", type: "address", indexed: true, internalType: "address" },
+      { name: "apUSDAmount", type: "uint256", indexed: false, internalType: "uint256" },
+      { name: "lstAmount", type: "uint256", indexed: false, internalType: "uint256" },
+      { name: "feeBPS", type: "uint256", indexed: false, internalType: "uint256" }
+    ],
+    anonymous: false
+  },
+  {
+    type: "event",
+    name: "XBNBMinted",
+    inputs: [
+      { name: "user", type: "address", indexed: true, internalType: "address" },
+      { name: "lstToken", type: "address", indexed: true, internalType: "address" },
+      { name: "lstAmount", type: "uint256", indexed: false, internalType: "uint256" },
+      { name: "xBNBAmount", type: "uint256", indexed: false, internalType: "uint256" },
+      { name: "feeBPS", type: "uint256", indexed: false, internalType: "uint256" }
+    ],
+    anonymous: false
+  },
+  {
+    type: "event",
+    name: "XBNBRedeemed",
+    inputs: [
+      { name: "user", type: "address", indexed: true, internalType: "address" },
+      { name: "lstToken", type: "address", indexed: true, internalType: "address" },
+      { name: "xBNBAmount", type: "uint256", indexed: false, internalType: "uint256" },
+      { name: "lstAmount", type: "uint256", indexed: false, internalType: "uint256" },
+      { name: "feeBPS", type: "uint256", indexed: false, internalType: "uint256" }
+    ],
+    anonymous: false
+  },
+
+  // ============ OracleFacet ============
+  {
+    type: "function",
+    name: "getBNBPriceUSD",
+    inputs: [],
+    outputs: [{ name: "", type: "uint256", internalType: "uint256" }],
+    stateMutability: "view"
+  },
+  {
+    type: "function",
+    name: "getLSTPriceUSD",
+    inputs: [{ name: "_lstToken", type: "address", internalType: "address" }],
+    outputs: [{ name: "", type: "uint256", internalType: "uint256" }],
+    stateMutability: "view"
+  },
+  {
+    type: "function",
+    name: "getLSTInfo",
+    inputs: [{ name: "_lstToken", type: "address", internalType: "address" }],
+    outputs: [
+      { name: "isAccepted", type: "bool", internalType: "bool" },
+      { name: "priceFeed", type: "address", internalType: "address" },
+      { name: "manualPriceUSD", type: "uint256", internalType: "uint256" },
+      { name: "collateralAmount", type: "uint256", internalType: "uint256" },
+      { name: "decimals", type: "uint8", internalType: "uint8" },
+      { name: "exchangeRateProvider", type: "address", internalType: "address" },
+      { name: "useIntrinsicValue", type: "bool", internalType: "bool" }
+    ],
+    stateMutability: "view"
+  },
+  {
+    type: "function",
+    name: "getSupportedLSTs",
+    inputs: [],
+    outputs: [{ name: "", type: "address[]", internalType: "address[]" }],
+    stateMutability: "view"
+  },
+  {
+    type: "function",
+    name: "isLSTSupported",
+    inputs: [{ name: "_lstToken", type: "address", internalType: "address" }],
+    outputs: [{ name: "", type: "bool", internalType: "bool" }],
+    stateMutability: "view"
+  },
+  {
+    type: "function",
+    name: "bnbPriceFeed",
+    inputs: [],
+    outputs: [{ name: "", type: "address", internalType: "address" }],
+    stateMutability: "view"
+  },
+  {
+    type: "function",
+    name: "getOracleBounds",
+    inputs: [{ name: "_priceFeed", type: "address", internalType: "address" }],
+    outputs: [
+      { name: "minPrice", type: "uint256", internalType: "uint256" },
+      { name: "maxPrice", type: "uint256", internalType: "uint256" }
+    ],
+    stateMutability: "view"
+  },
+
+  // ============ StabilityPoolFacet ============
+  {
+    type: "function",
+    name: "deposit",
+    inputs: [{ name: "_apUSDAmount", type: "uint256", internalType: "uint256" }],
+    outputs: [{ name: "shares", type: "uint256", internalType: "uint256" }],
+    stateMutability: "nonpayable"
+  },
+  {
+    type: "function",
+    name: "withdraw",
+    inputs: [{ name: "_shares", type: "uint256", internalType: "uint256" }],
+    outputs: [{ name: "assets", type: "uint256", internalType: "uint256" }],
+    stateMutability: "nonpayable"
+  },
+  {
+    type: "function",
+    name: "withdrawAssets",
+    inputs: [{ name: "_assets", type: "uint256", internalType: "uint256" }],
+    outputs: [{ name: "shares", type: "uint256", internalType: "uint256" }],
+    stateMutability: "nonpayable"
+  },
+  {
+    type: "function",
+    name: "getShares",
+    inputs: [{ name: "_user", type: "address", internalType: "address" }],
+    outputs: [{ name: "", type: "uint256", internalType: "uint256" }],
+    stateMutability: "view"
+  },
+  {
+    type: "function",
+    name: "getBalance",
+    inputs: [{ name: "_user", type: "address", internalType: "address" }],
+    outputs: [{ name: "", type: "uint256", internalType: "uint256" }],
+    stateMutability: "view"
+  },
+  {
+    type: "function",
+    name: "getExchangeRate",
+    inputs: [],
+    outputs: [{ name: "", type: "uint256", internalType: "uint256" }],
+    stateMutability: "view"
+  },
+  {
+    type: "function",
+    name: "getTotalStaked",
+    inputs: [],
+    outputs: [{ name: "", type: "uint256", internalType: "uint256" }],
+    stateMutability: "view"
+  },
+  {
+    type: "function",
+    name: "previewDeposit",
+    inputs: [{ name: "_assets", type: "uint256", internalType: "uint256" }],
+    outputs: [{ name: "", type: "uint256", internalType: "uint256" }],
+    stateMutability: "view"
+  },
+  {
+    type: "function",
+    name: "previewRedeem",
+    inputs: [{ name: "_shares", type: "uint256", internalType: "uint256" }],
+    outputs: [{ name: "", type: "uint256", internalType: "uint256" }],
+    stateMutability: "view"
+  },
+  {
+    type: "function",
+    name: "getPendingYield",
+    inputs: [],
+    outputs: [{ name: "", type: "uint256", internalType: "uint256" }],
+    stateMutability: "view"
+  },
+  {
+    type: "function",
+    name: "harvestYield",
+    inputs: [],
+    outputs: [{ name: "yieldAmount", type: "uint256", internalType: "uint256" }],
+    stateMutability: "nonpayable"
+  },
+
+  // ============ StabilityPoolFacet Events ============
+  {
+    type: "event",
+    name: "Deposited",
+    inputs: [
+      { name: "user", type: "address", indexed: true, internalType: "address" },
+      { name: "apUSDAmount", type: "uint256", indexed: false, internalType: "uint256" },
+      { name: "sharesReceived", type: "uint256", indexed: false, internalType: "uint256" }
+    ],
+    anonymous: false
+  },
+  {
+    type: "event",
+    name: "Withdrawn",
+    inputs: [
+      { name: "user", type: "address", indexed: true, internalType: "address" },
+      { name: "sharesRedeemed", type: "uint256", indexed: false, internalType: "uint256" },
+      { name: "apUSDReceived", type: "uint256", indexed: false, internalType: "uint256" }
+    ],
+    anonymous: false
+  },
+  {
+    type: "event",
+    name: "YieldHarvested",
+    inputs: [
+      { name: "yieldUSD", type: "uint256", indexed: false, internalType: "uint256" }
+    ],
+    anonymous: false
+  },
+
+  // ============ YieldFacet ============
+  {
+    type: "function",
+    name: "getTotalYieldGenerated",
+    inputs: [],
+    outputs: [{ name: "", type: "uint256", internalType: "uint256" }],
+    stateMutability: "view"
+  },
+  {
+    type: "function",
+    name: "getLSTYieldInfo",
+    inputs: [{ name: "_lstToken", type: "address", internalType: "address" }],
+    outputs: [
+      { name: "lastExchangeRate", type: "uint256", internalType: "uint256" },
+      { name: "lastUpdateTimestamp", type: "uint256", internalType: "uint256" }
+    ],
+    stateMutability: "view"
+  },
+  {
+    type: "function",
+    name: "getMinHarvestInterval",
+    inputs: [],
+    outputs: [{ name: "", type: "uint256", internalType: "uint256" }],
+    stateMutability: "view"
+  },
+  {
+    type: "function",
+    name: "getLastHarvestTimestamp",
+    inputs: [],
+    outputs: [{ name: "", type: "uint256", internalType: "uint256" }],
+    stateMutability: "view"
+  },
+  {
+    type: "function",
+    name: "previewHarvest",
+    inputs: [],
+    outputs: [{ name: "totalYieldUSD", type: "uint256", internalType: "uint256" }],
+    stateMutability: "view"
+  },
+
+  // ============ ConfigFacet ============
+  {
+    type: "function",
+    name: "getTokens",
+    inputs: [],
+    outputs: [
+      { name: "apUSD", type: "address", internalType: "address" },
+      { name: "xBNB", type: "address", internalType: "address" }
+    ],
+    stateMutability: "view"
+  },
+  {
+    type: "function",
+    name: "getSApUSD",
+    inputs: [],
+    outputs: [{ name: "", type: "address", internalType: "address" }],
+    stateMutability: "view"
+  },
+  {
+    type: "function",
+    name: "getStabilityPool",
+    inputs: [],
+    outputs: [{ name: "", type: "address", internalType: "address" }],
+    stateMutability: "view"
+  },
+  {
+    type: "function",
+    name: "getTreasury",
+    inputs: [],
+    outputs: [{ name: "", type: "address", internalType: "address" }],
+    stateMutability: "view"
+  },
+  {
+    type: "function",
+    name: "getFeeTierCount",
+    inputs: [],
+    outputs: [{ name: "", type: "uint256", internalType: "uint256" }],
+    stateMutability: "view"
+  },
+  {
+    type: "function",
+    name: "getFeeTier",
+    inputs: [{ name: "_index", type: "uint256", internalType: "uint256" }],
+    outputs: [
+      { 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: "getCurrentFeeTier",
+    inputs: [],
+    outputs: [
+      { 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" },
+      { name: "currentCR", type: "uint256", internalType: "uint256" }
+    ],
+    stateMutability: "view"
+  },
+  {
+    type: "function",
+    name: "getMaxPriceAge",
+    inputs: [],
+    outputs: [{ name: "", type: "uint256", internalType: "uint256" }],
+    stateMutability: "view"
+  },
+  {
+    type: "function",
+    name: "getMinDepositPeriod",
+    inputs: [],
+    outputs: [{ name: "", type: "uint256", internalType: "uint256" }],
+    stateMutability: "view"
+  },
+  {
+    type: "function",
+    name: "isPaused",
+    inputs: [],
+    outputs: [{ name: "", type: "bool", internalType: "bool" }],
+    stateMutability: "view"
+  },
+
+  // ============ StabilityModeFacet ============
+  {
+    type: "function",
+    name: "getStabilityMode",
+    inputs: [],
+    outputs: [
+      { name: "mode", type: "uint8", internalType: "uint8" },
+      { name: "currentCR", type: "uint256", internalType: "uint256" }
+    ],
+    stateMutability: "view"
+  },
+  {
+    type: "function",
+    name: "canTriggerStabilityMode2",
+    inputs: [],
+    outputs: [
+      { name: "canTrigger", type: "bool", internalType: "bool" },
+      { name: "currentCR", type: "uint256", internalType: "uint256" },
+      { name: "potentialConversion", type: "uint256", internalType: "uint256" }
+    ],
+    stateMutability: "view"
+  },
+  {
+    type: "function",
+    name: "triggerStabilityMode2",
+    inputs: [{ name: "_targetCR", type: "uint256", internalType: "uint256" }],
+    outputs: [
+      { name: "apUSDBurned", type: "uint256", internalType: "uint256" },
+      { name: "xBNBMinted", type: "uint256", internalType: "uint256" }
+    ],
+    stateMutability: "nonpayable"
+  },
+
+  // ============ StabilityModeFacet Events ============
+  {
+    type: "event",
+    name: "StabilityMode2Triggered",
+    inputs: [
+      { name: "currentCR", type: "uint256", indexed: false, internalType: "uint256" },
+      { name: "targetCR", type: "uint256", indexed: false, internalType: "uint256" },
+      { name: "apUSDBurned", type: "uint256", indexed: false, internalType: "uint256" },
+      { name: "xBNBMinted", type: "uint256", indexed: false, internalType: "uint256" }
+    ],
+    anonymous: false
+  },
+
+  // ============ OwnershipFacet ============
+  {
+    type: "function",
+    name: "owner",
+    inputs: [],
+    outputs: [{ name: "", type: "address", internalType: "address" }],
+    stateMutability: "view"
+  }
+] as const;

package/src/bot/config.ts

@@ -0,0 +1,84 @@
+/**
+ * Bot Configuration
+ * Loads environment variables and provides typed configuration
+ */
+
+import type { Address } from "viem";
+
+export interface BotConfig {
+  // RPC Configuration
+  rpcUrl: string;
+  rpcFallbackUrls: string[];
+
+  // Contract Address
+  diamondAddress: Address;
+
+  // Monitoring Intervals (milliseconds)
+  statsReportInterval: number;
+  crCheckInterval: number;
+
+  // CR Thresholds (18 decimals: 1.5e18 = 150%)
+  crThresholdMode1: bigint;
+  crThresholdMode2: bigint;
+
+  // TVL Impact Threshold (percentage)
+  tvlImpactThresholdPercent: number;
+
+  // Slack Configuration
+  slackWebhookUrl: string;
+  slackRateLimitMs: number;
+
+  // Retry Configuration
+  maxRetries: number;
+  retryDelayMs: number;
+  retryBackoffMultiplier: number;
+}
+
+export function loadConfig(): BotConfig {
+  const slackWebhookUrl = process.env.SLACK_WEBHOOK_URL;
+  if (!slackWebhookUrl) {
+    throw new Error("SLACK_WEBHOOK_URL environment variable is required");
+  }
+
+  return {
+    // RPC
+    rpcUrl: process.env.RPC_URL ?? "https://bsc-dataseed1.binance.org",
+    rpcFallbackUrls: (process.env.RPC_FALLBACK_URLS ?? "")
+      .split(",")
+      .map((url) => url.trim())
+      .filter(Boolean),
+
+    // Contract
+    diamondAddress: (process.env.DIAMOND_ADDRESS ??
+      "0x10d25Ae0690533e0BA9E64EC7ae77dbD4fE8A46f") as Address,
+
+    // Intervals
+    statsReportInterval: parseInt(
+      process.env.STATS_INTERVAL_MS ?? "300000",
+      10
+    ), // 5 min
+    crCheckInterval: parseInt(process.env.CR_CHECK_INTERVAL_MS ?? "30000", 10), // 30 sec
+
+    // CR Thresholds
+    crThresholdMode1: BigInt(
+      process.env.CR_THRESHOLD_MODE1 ?? "1500000000000000000"
+    ), // 150%
+    crThresholdMode2: BigInt(
+      process.env.CR_THRESHOLD_MODE2 ?? "1300000000000000000"
+    ), // 130%
+
+    // TVL
+    tvlImpactThresholdPercent: parseFloat(
+      process.env.TVL_IMPACT_THRESHOLD ?? "5"
+    ),
+
+    // Slack
+    slackWebhookUrl,
+    slackRateLimitMs: parseInt(process.env.SLACK_RATE_LIMIT_MS ?? "1000", 10),
+
+    // Retry
+    maxRetries: parseInt(process.env.MAX_RETRIES ?? "3", 10),
+    retryDelayMs: parseInt(process.env.RETRY_DELAY_MS ?? "1000", 10),
+    retryBackoffMultiplier: parseFloat(process.env.RETRY_BACKOFF ?? "2"),
+  };
+}