@aspan/sdk 0.1.4

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

@@ -0,0 +1,287 @@
+/**
+ * Stats Monitor
+ * Reports protocol statistics to Slack every 5 minutes
+ * Skips report if no significant changes detected
+ */
+
+import type { AspanReadClient } from "../../client";
+import type { ProtocolStats, StabilityPoolStats } from "../../types";
+import { formatAmount, formatCR } from "../../index";
+import type { SlackService } from "../services/slack";
+import { SlackColors } from "../services/slack";
+import type { BotConfig } from "../config";
+import { withRetry } from "../services/rpc-client";
+
+interface LastReportState {
+  stats: ProtocolStats;
+  stabilityMode: number;
+  stabilityPoolStats: StabilityPoolStats;
+  apUSDMintDisabled: boolean;
+}
+
+export class StatsMonitor {
+  private client: AspanReadClient;
+  private slack: SlackService;
+  private config: BotConfig;
+  private intervalId?: ReturnType<typeof setInterval>;
+  private lastReport?: LastReportState;
+  private isFirstReport = true;
+
+  // Threshold for considering a change significant (0.1% = 10 basis points)
+  private readonly CHANGE_THRESHOLD_BPS = 10n;
+
+  constructor(
+    client: AspanReadClient,
+    slack: SlackService,
+    config: BotConfig
+  ) {
+    this.client = client;
+    this.slack = slack;
+    this.config = config;
+  }
+
+  start(): void {
+    console.log(
+      `[StatsMonitor] Starting with ${this.config.statsReportInterval / 1000}s interval`
+    );
+
+    // Send initial report immediately
+    this.reportStats();
+
+    // Schedule regular reports
+    this.intervalId = setInterval(
+      () => this.reportStats(),
+      this.config.statsReportInterval
+    );
+  }
+
+  stop(): void {
+    if (this.intervalId) {
+      clearInterval(this.intervalId);
+      this.intervalId = undefined;
+      console.log("[StatsMonitor] Stopped");
+    }
+  }
+
+  private async reportStats(): Promise<void> {
+    try {
+      const [stats, stabilityMode, fees, stabilityPoolStats] =
+        await Promise.all([
+          withRetry(
+            () => this.client.getProtocolStats(),
+            this.config,
+            "getProtocolStats"
+          ),
+          withRetry(
+            () => this.client.getStabilityMode(),
+            this.config,
+            "getStabilityMode"
+          ),
+          withRetry(
+            () => this.client.getCurrentFees(),
+            this.config,
+            "getCurrentFees"
+          ),
+          withRetry(
+            () => this.client.getStabilityPoolStats(),
+            this.config,
+            "getStabilityPoolStats"
+          ),
+        ]);
+
+      const currentState: LastReportState = {
+        stats,
+        stabilityMode: stabilityMode.mode,
+        stabilityPoolStats,
+        apUSDMintDisabled: fees.apUSDMintDisabled,
+      };
+
+      // Skip if no significant changes (except for first report)
+      if (!this.isFirstReport && !this.hasSignificantChange(currentState)) {
+        console.log(
+          `[StatsMonitor] No significant changes, skipping report - TVL: $${formatAmount(stats.tvlInUSD, 2)}, CR: ${formatCR(stats.collateralRatio)}`
+        );
+        return;
+      }
+
+      this.isFirstReport = false;
+      this.lastReport = currentState;
+
+      const modeLabels = ["Normal", "Mode 1 (Warning)", "Mode 2 (Critical)"];
+      const modeLabel = modeLabels[stabilityMode.mode] ?? "Unknown";
+
+      await this.slack.send({
+        attachments: [
+          {
+            color: this.getModeColor(stabilityMode.mode),
+            title: "Aspan Protocol Stats Report",
+            fields: [
+              {
+                title: "TVL (USD)",
+                value: `$${formatAmount(stats.tvlInUSD, 2)}`,
+                short: true,
+              },
+              {
+                title: "Collateral Ratio",
+                value: formatCR(stats.collateralRatio),
+                short: true,
+              },
+              {
+                title: "Stability Mode",
+                value: modeLabel,
+                short: true,
+              },
+              {
+                title: "Effective Leverage",
+                value: `${formatAmount(stats.effectiveLeverage, 2)}x`,
+                short: true,
+              },
+              {
+                title: "apUSD Supply",
+                value: formatAmount(stats.apUSDSupply, 2),
+                short: true,
+              },
+              {
+                title: "xBNB Supply",
+                value: formatAmount(stats.xBNBSupply, 4),
+                short: true,
+              },
+              {
+                title: "xBNB Price (BNB)",
+                value: formatAmount(stats.xBNBPriceBNB, 6),
+                short: true,
+              },
+              {
+                title: "xBNB Price (USD)",
+                value: `$${formatAmount(stats.xBNBPriceUSD, 2)}`,
+                short: true,
+              },
+              {
+                title: "Stability Pool Staked",
+                value: formatAmount(stabilityPoolStats.totalStaked, 2),
+                short: true,
+              },
+              {
+                title: "Exchange Rate",
+                value: formatAmount(stabilityPoolStats.exchangeRate, 6),
+                short: true,
+              },
+              {
+                title: "apUSD Mint Fee",
+                value: `${(fees.apUSDMintFee / 100).toFixed(2)}%${fees.apUSDMintDisabled ? " (Disabled)" : ""}`,
+                short: true,
+              },
+              {
+                title: "xBNB Redeem Fee",
+                value: `${(fees.xBNBRedeemFee / 100).toFixed(2)}%`,
+                short: true,
+              },
+            ],
+            ts: Math.floor(Date.now() / 1000),
+          },
+        ],
+      });
+
+      console.log(
+        `[StatsMonitor] Report sent - TVL: $${formatAmount(stats.tvlInUSD, 2)}, CR: ${formatCR(stats.collateralRatio)}`
+      );
+    } catch (error) {
+      console.error("[StatsMonitor] Failed to report stats:", error);
+    }
+  }
+
+  /**
+   * Check if current state has significant changes compared to last report
+   */
+  private hasSignificantChange(current: LastReportState): boolean {
+    if (!this.lastReport) {
+      return true;
+    }
+
+    const last = this.lastReport;
+
+    // Always report if stability mode changed
+    if (current.stabilityMode !== last.stabilityMode) {
+      console.log("[StatsMonitor] Stability mode changed");
+      return true;
+    }
+
+    // Always report if mint disabled status changed
+    if (current.apUSDMintDisabled !== last.apUSDMintDisabled) {
+      console.log("[StatsMonitor] Mint disabled status changed");
+      return true;
+    }
+
+    // Check for significant changes in key metrics
+    const checks = [
+      {
+        name: "TVL",
+        current: current.stats.tvlInUSD,
+        last: last.stats.tvlInUSD,
+      },
+      {
+        name: "CR",
+        current: current.stats.collateralRatio,
+        last: last.stats.collateralRatio,
+      },
+      {
+        name: "apUSD Supply",
+        current: current.stats.apUSDSupply,
+        last: last.stats.apUSDSupply,
+      },
+      {
+        name: "xBNB Supply",
+        current: current.stats.xBNBSupply,
+        last: last.stats.xBNBSupply,
+      },
+      {
+        name: "xBNB Price",
+        current: current.stats.xBNBPriceUSD,
+        last: last.stats.xBNBPriceUSD,
+      },
+      {
+        name: "Staked",
+        current: current.stabilityPoolStats.totalStaked,
+        last: last.stabilityPoolStats.totalStaked,
+      },
+    ];
+
+    for (const check of checks) {
+      if (this.hasSignificantValueChange(check.current, check.last)) {
+        console.log(`[StatsMonitor] Significant change detected in ${check.name}`);
+        return true;
+      }
+    }
+
+    return false;
+  }
+
+  /**
+   * Check if a value has changed by more than CHANGE_THRESHOLD_BPS (0.1%)
+   */
+  private hasSignificantValueChange(current: bigint, last: bigint): boolean {
+    if (last === 0n) {
+      return current !== 0n;
+    }
+
+    // Calculate absolute difference
+    const diff = current > last ? current - last : last - current;
+
+    // Check if diff > (last * threshold / 10000)
+    // Rearranged to avoid precision loss: diff * 10000 > last * threshold
+    return diff * 10000n > last * this.CHANGE_THRESHOLD_BPS;
+  }
+
+  private getModeColor(mode: number): string {
+    switch (mode) {
+      case 0:
+        return SlackColors.success;
+      case 1:
+        return SlackColors.warning;
+      case 2:
+        return SlackColors.danger;
+      default:
+        return SlackColors.neutral;
+    }
+  }
+}

package/src/bot/services/rpc-client.ts

@@ -0,0 +1,61 @@
+/**
+ * RPC Client with Retry and Fallback
+ */
+
+import { createPublicClient, http, fallback, type PublicClient } from "viem";
+import { bsc } from "viem/chains";
+import type { BotConfig } from "../config";
+
+/**
+ * Creates a robust public client with fallback RPC endpoints
+ */
+export function createRobustClient(config: BotConfig): PublicClient {
+  const transports = [
+    http(config.rpcUrl),
+    ...config.rpcFallbackUrls.map((url) => http(url)),
+  ];
+
+  return createPublicClient({
+    chain: bsc,
+    transport: fallback(transports, {
+      retryCount: config.maxRetries,
+      retryDelay: config.retryDelayMs,
+    }),
+  });
+}
+
+/**
+ * Retry utility for SDK/RPC calls with exponential backoff
+ */
+export async function withRetry<T>(
+  fn: () => Promise<T>,
+  config: BotConfig,
+  context: string = "operation"
+): Promise<T> {
+  let lastError: Error | undefined;
+  let delay = config.retryDelayMs;
+
+  for (let attempt = 1; attempt <= config.maxRetries; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error as Error;
+      console.warn(
+        `[${context}] Attempt ${attempt}/${config.maxRetries} failed: ${lastError.message}`
+      );
+
+      if (attempt < config.maxRetries) {
+        await sleep(delay);
+        delay = Math.floor(delay * config.retryBackoffMultiplier);
+      }
+    }
+  }
+
+  throw new Error(
+    `[${context}] Failed after ${config.maxRetries} attempts: ${lastError?.message}`
+  );
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/bot/services/slack.ts

@@ -0,0 +1,95 @@
+/**
+ * Slack Webhook Service
+ * Sends messages to Slack with rate limiting
+ */
+
+export interface SlackField {
+  title: string;
+  value: string;
+  short?: boolean;
+}
+
+export interface SlackAttachment {
+  color: string;
+  title: string;
+  text?: string;
+  fields?: SlackField[];
+  ts?: number;
+}
+
+export interface SlackMessage {
+  text?: string;
+  attachments?: SlackAttachment[];
+}
+
+export class SlackService {
+  private webhookUrl: string;
+  private rateLimitMs: number;
+  private lastSentAt: number = 0;
+  private queue: SlackMessage[] = [];
+  private isProcessing: boolean = false;
+
+  constructor(webhookUrl: string, rateLimitMs: number = 1000) {
+    this.webhookUrl = webhookUrl;
+    this.rateLimitMs = rateLimitMs;
+  }
+
+  async send(message: SlackMessage): Promise<void> {
+    this.queue.push(message);
+    await this.processQueue();
+  }
+
+  private async processQueue(): Promise<void> {
+    if (this.isProcessing || this.queue.length === 0) return;
+
+    this.isProcessing = true;
+
+    try {
+      while (this.queue.length > 0) {
+        const now = Date.now();
+        const timeSinceLastSend = now - this.lastSentAt;
+
+        if (timeSinceLastSend < this.rateLimitMs) {
+          await this.sleep(this.rateLimitMs - timeSinceLastSend);
+        }
+
+        const message = this.queue.shift()!;
+        await this.sendImmediate(message);
+        this.lastSentAt = Date.now();
+      }
+    } finally {
+      this.isProcessing = false;
+    }
+  }
+
+  private async sendImmediate(message: SlackMessage): Promise<void> {
+    try {
+      const response = await fetch(this.webhookUrl, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(message),
+      });
+
+      if (!response.ok) {
+        console.error(
+          `Slack webhook failed: ${response.status} ${response.statusText}`
+        );
+      }
+    } catch (error) {
+      console.error("Failed to send Slack message:", error);
+    }
+  }
+
+  private sleep(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+}
+
+// Color constants for different alert levels
+export const SlackColors = {
+  success: "#36a64f", // Green
+  warning: "#ffcc00", // Yellow
+  danger: "#ff0000", // Red
+  info: "#2196f3", // Blue
+  neutral: "#808080", // Gray
+} as const;