@aspan/sdk 0.1.4

package/src/bot/index.ts

@@ -0,0 +1,133 @@
+/**
+ * Aspan Protocol Monitoring Bot
+ * Main entry point
+ */
+
+import "dotenv/config";
+import { createAspanReadClient } from "../index";
+import { loadConfig } from "./config";
+import { SlackService } from "./services/slack";
+import { createRobustClient } from "./services/rpc-client";
+import { StatsMonitor } from "./monitors/stats-monitor";
+import { CRMonitor } from "./monitors/cr-monitor";
+import { MempoolMonitor } from "./monitors/mempool-monitor";
+
+class AspanMonitoringBot {
+  private config = loadConfig();
+  private slack: SlackService;
+  private statsMonitor: StatsMonitor;
+  private crMonitor: CRMonitor;
+  private mempoolMonitor: MempoolMonitor;
+  private isRunning = false;
+
+  constructor() {
+    console.log("Initializing Aspan Monitoring Bot...");
+
+    // Initialize Slack service
+    this.slack = new SlackService(
+      this.config.slackWebhookUrl,
+      this.config.slackRateLimitMs
+    );
+
+    // Create SDK client
+    const aspanClient = createAspanReadClient(
+      this.config.diamondAddress,
+      this.config.rpcUrl
+    );
+
+    // Create robust public client for event watching
+    const publicClient = createRobustClient(this.config);
+
+    // Initialize monitors
+    this.statsMonitor = new StatsMonitor(aspanClient, this.slack, this.config);
+    this.crMonitor = new CRMonitor(aspanClient, this.slack, this.config);
+    this.mempoolMonitor = new MempoolMonitor(
+      aspanClient,
+      publicClient,
+      this.slack,
+      this.config
+    );
+
+    console.log(`Diamond Address: ${this.config.diamondAddress}`);
+    console.log(`RPC URL: ${this.config.rpcUrl}`);
+  }
+
+  async start(): Promise<void> {
+    if (this.isRunning) {
+      console.warn("Bot is already running");
+      return;
+    }
+
+    console.log("\nStarting Aspan Monitoring Bot...\n");
+
+    // Send startup notification
+    await this.slack.send({
+      text: ":robot_face: Aspan Monitoring Bot started",
+    });
+
+    // Start all monitors
+    this.statsMonitor.start();
+    this.crMonitor.start();
+    await this.mempoolMonitor.start();
+
+    this.isRunning = true;
+    console.log("\nAll monitors started successfully!\n");
+  }
+
+  async stop(): Promise<void> {
+    if (!this.isRunning) {
+      return;
+    }
+
+    console.log("\nStopping Aspan Monitoring Bot...");
+
+    // Stop all monitors
+    this.statsMonitor.stop();
+    this.crMonitor.stop();
+    this.mempoolMonitor.stop();
+
+    // Send shutdown notification
+    await this.slack.send({
+      text: ":wave: Aspan Monitoring Bot stopped",
+    });
+
+    this.isRunning = false;
+    console.log("Bot stopped\n");
+  }
+}
+
+// Main execution
+async function main() {
+  const bot = new AspanMonitoringBot();
+
+  // Graceful shutdown handlers
+  const shutdown = async (signal: string) => {
+    console.log(`\nReceived ${signal}, shutting down gracefully...`);
+    await bot.stop();
+    process.exit(0);
+  };
+
+  process.on("SIGINT", () => shutdown("SIGINT"));
+  process.on("SIGTERM", () => shutdown("SIGTERM"));
+
+  process.on("uncaughtException", (error) => {
+    console.error("Uncaught exception:", error);
+    shutdown("uncaughtException");
+  });
+
+  process.on("unhandledRejection", (reason) => {
+    console.error("Unhandled rejection:", reason);
+    shutdown("unhandledRejection");
+  });
+
+  // Start the bot
+  await bot.start();
+
+  // Keep process alive
+  console.log("Bot is running. Press Ctrl+C to stop.\n");
+}
+
+main().catch((error) => {
+  console.error("Fatal error:", error);
+  process.exit(1);
+});

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

@@ -0,0 +1,182 @@
+/**
+ * CR (Collateral Ratio) Monitor
+ * Monitors CR and alerts when thresholds are breached
+ */
+
+import type { AspanReadClient } from "../../client";
+import { 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 AlertState {
+  mode1Triggered: boolean;
+  mode2Triggered: boolean;
+  lastAlertTime: number;
+  lastCR: bigint;
+}
+
+export class CRMonitor {
+  private client: AspanReadClient;
+  private slack: SlackService;
+  private config: BotConfig;
+  private intervalId?: ReturnType<typeof setInterval>;
+  private state: AlertState = {
+    mode1Triggered: false,
+    mode2Triggered: false,
+    lastAlertTime: 0,
+    lastCR: 0n,
+  };
+
+  // Cooldown between repeat alerts (5 minutes)
+  private readonly ALERT_COOLDOWN_MS = 5 * 60 * 1000;
+
+  constructor(
+    client: AspanReadClient,
+    slack: SlackService,
+    config: BotConfig
+  ) {
+    this.client = client;
+    this.slack = slack;
+    this.config = config;
+  }
+
+  start(): void {
+    console.log(
+      `[CRMonitor] Starting with ${this.config.crCheckInterval / 1000}s interval`
+    );
+    console.log(
+      `[CRMonitor] Thresholds - Mode1: ${formatCR(this.config.crThresholdMode1)}, Mode2: ${formatCR(this.config.crThresholdMode2)}`
+    );
+
+    // Initial check
+    this.checkCR();
+
+    // Schedule regular checks
+    this.intervalId = setInterval(
+      () => this.checkCR(),
+      this.config.crCheckInterval
+    );
+  }
+
+  stop(): void {
+    if (this.intervalId) {
+      clearInterval(this.intervalId);
+      this.intervalId = undefined;
+      console.log("[CRMonitor] Stopped");
+    }
+  }
+
+  private async checkCR(): Promise<void> {
+    try {
+      const stabilityMode = await withRetry(
+        () => this.client.getStabilityMode(),
+        this.config,
+        "getStabilityMode"
+      );
+
+      const currentCR = stabilityMode.currentCR;
+      const now = Date.now();
+
+      // Check Mode 2 threshold (< 130%)
+      if (currentCR < this.config.crThresholdMode2) {
+        if (!this.state.mode2Triggered || this.shouldRepeatAlert(now)) {
+          await this.sendCriticalAlert(currentCR);
+          this.state.mode2Triggered = true;
+          this.state.mode1Triggered = true; // Also in mode1 range
+          this.state.lastAlertTime = now;
+        }
+      }
+      // Check Mode 1 threshold (< 150% but >= 130%)
+      else if (currentCR < this.config.crThresholdMode1) {
+        // If recovering from Mode 2
+        if (this.state.mode2Triggered) {
+          await this.sendRecoveryAlert(currentCR, "Mode 2", "Mode 1");
+          this.state.mode2Triggered = false;
+        }
+
+        if (!this.state.mode1Triggered || this.shouldRepeatAlert(now)) {
+          await this.sendWarningAlert(currentCR);
+          this.state.mode1Triggered = true;
+          this.state.lastAlertTime = now;
+        }
+      }
+      // CR is healthy (>= 150%)
+      else {
+        if (this.state.mode1Triggered || this.state.mode2Triggered) {
+          const fromMode = this.state.mode2Triggered ? "Mode 2" : "Mode 1";
+          await this.sendRecoveryAlert(currentCR, fromMode, "Normal");
+          this.state.mode1Triggered = false;
+          this.state.mode2Triggered = false;
+        }
+      }
+
+      this.state.lastCR = currentCR;
+    } catch (error) {
+      console.error("[CRMonitor] CR check failed:", error);
+    }
+  }
+
+  private shouldRepeatAlert(now: number): boolean {
+    return now - this.state.lastAlertTime > this.ALERT_COOLDOWN_MS;
+  }
+
+  private async sendWarningAlert(cr: bigint): Promise<void> {
+    console.log(`[CRMonitor] Sending Mode 1 warning alert - CR: ${formatCR(cr)}`);
+
+    await this.slack.send({
+      attachments: [
+        {
+          color: SlackColors.warning,
+          title: ":warning: CR Warning - Mode 1 Threshold Breached",
+          text: "Collateral Ratio has dropped below 150%. Protocol entering stability mode.",
+          fields: [
+            { title: "Current CR", value: formatCR(cr), short: true },
+            { title: "Threshold", value: "150%", short: true },
+          ],
+          ts: Math.floor(Date.now() / 1000),
+        },
+      ],
+    });
+  }
+
+  private async sendCriticalAlert(cr: bigint): Promise<void> {
+    console.log(`[CRMonitor] Sending Mode 2 CRITICAL alert - CR: ${formatCR(cr)}`);
+
+    await this.slack.send({
+      attachments: [
+        {
+          color: SlackColors.danger,
+          title: ":rotating_light: CRITICAL - Mode 2 Threshold Breached",
+          text: "Collateral Ratio has dropped below 130%! Stability Mode 2 may trigger forced conversion.",
+          fields: [
+            { title: "Current CR", value: formatCR(cr), short: true },
+            { title: "Threshold", value: "130%", short: true },
+          ],
+          ts: Math.floor(Date.now() / 1000),
+        },
+      ],
+    });
+  }
+
+  private async sendRecoveryAlert(
+    cr: bigint,
+    from: string,
+    to: string
+  ): Promise<void> {
+    console.log(`[CRMonitor] CR recovered from ${from} to ${to} - CR: ${formatCR(cr)}`);
+
+    await this.slack.send({
+      attachments: [
+        {
+          color: SlackColors.success,
+          title: `:white_check_mark: CR Recovered - ${from} -> ${to}`,
+          text: "Collateral Ratio has recovered above threshold.",
+          fields: [{ title: "Current CR", value: formatCR(cr), short: true }],
+          ts: Math.floor(Date.now() / 1000),
+        },
+      ],
+    });
+  }
+}

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

@@ -0,0 +1,167 @@
+/**
+ * Mempool/TVL Monitor
+ * Monitors contract events for large TVL changes
+ *
+ * Note: BSC doesn't expose public mempool, so we use event-based monitoring
+ * which is reactive (post-confirmation) rather than proactive
+ */
+
+import type { PublicClient, Log } from "viem";
+import type { AspanReadClient } from "../../client";
+import { DiamondABI, formatAmount } from "../../index";
+import type { SlackService } from "../services/slack";
+import { SlackColors } from "../services/slack";
+import type { BotConfig } from "../config";
+import { withRetry } from "../services/rpc-client";
+
+export class MempoolMonitor {
+  private client: AspanReadClient;
+  private publicClient: PublicClient;
+  private slack: SlackService;
+  private config: BotConfig;
+  private unwatch?: () => void;
+  private lastKnownTVL: bigint = 0n;
+
+  constructor(
+    client: AspanReadClient,
+    publicClient: PublicClient,
+    slack: SlackService,
+    config: BotConfig
+  ) {
+    this.client = client;
+    this.publicClient = publicClient;
+    this.slack = slack;
+    this.config = config;
+  }
+
+  async start(): Promise<void> {
+    console.log(
+      `[MempoolMonitor] Starting with ${this.config.tvlImpactThresholdPercent}% TVL impact threshold`
+    );
+
+    // Get initial TVL
+    this.lastKnownTVL = await withRetry(
+      () => this.client.getTVLInUSD(),
+      this.config,
+      "getTVLInUSD"
+    );
+    console.log(
+      `[MempoolMonitor] Initial TVL: $${formatAmount(this.lastKnownTVL, 2)}`
+    );
+
+    // Watch for contract events
+    this.unwatch = this.publicClient.watchContractEvent({
+      address: this.config.diamondAddress,
+      abi: DiamondABI,
+      onLogs: (logs) => this.handleLogs(logs),
+      onError: (error) => console.error("[MempoolMonitor] Event watch error:", error),
+    });
+
+    console.log("[MempoolMonitor] Event watcher started");
+  }
+
+  stop(): void {
+    if (this.unwatch) {
+      this.unwatch();
+      this.unwatch = undefined;
+      console.log("[MempoolMonitor] Stopped");
+    }
+  }
+
+  private async handleLogs(logs: Log[]): Promise<void> {
+    for (const log of logs) {
+      // Check if this is a TVL-impacting event by looking at event signature
+      await this.checkTVLImpact(log);
+    }
+  }
+
+  private async checkTVLImpact(log: Log): Promise<void> {
+    try {
+      // Get current TVL
+      const currentTVL = await withRetry(
+        () => this.client.getTVLInUSD(),
+        this.config,
+        "getTVLInUSD"
+      );
+
+      if (this.lastKnownTVL === 0n) {
+        this.lastKnownTVL = currentTVL;
+        return;
+      }
+
+      const tvlChange = currentTVL - this.lastKnownTVL;
+      const impactPercent =
+        this.lastKnownTVL > 0n
+          ? Number((tvlChange * 10000n) / this.lastKnownTVL) / 100
+          : 0;
+
+      const previousTVL = this.lastKnownTVL;
+      this.lastKnownTVL = currentTVL;
+
+      // Check if impact exceeds threshold
+      if (Math.abs(impactPercent) >= this.config.tvlImpactThresholdPercent) {
+        const isDecrease = tvlChange < 0n;
+        await this.sendImpactAlert(
+          log.transactionHash ?? "unknown",
+          previousTVL,
+          currentTVL,
+          impactPercent,
+          isDecrease
+        );
+      }
+    } catch (error) {
+      console.error("[MempoolMonitor] Error checking TVL impact:", error);
+    }
+  }
+
+  private async sendImpactAlert(
+    txHash: string,
+    previousTVL: bigint,
+    currentTVL: bigint,
+    impactPercent: number,
+    isDecrease: boolean
+  ): Promise<void> {
+    const direction = isDecrease ? "DECREASE" : "INCREASE";
+    const emoji = isDecrease
+      ? ":chart_with_downwards_trend:"
+      : ":chart_with_upwards_trend:";
+    const color = isDecrease ? SlackColors.danger : SlackColors.success;
+
+    console.log(
+      `[MempoolMonitor] Large TVL ${direction}: ${impactPercent.toFixed(2)}% - TX: ${txHash.slice(0, 18)}...`
+    );
+
+    await this.slack.send({
+      attachments: [
+        {
+          color,
+          title: `${emoji} Large TVL ${direction} Detected`,
+          text: `A transaction caused a ${Math.abs(impactPercent).toFixed(2)}% ${direction.toLowerCase()} in TVL`,
+          fields: [
+            {
+              title: "Impact",
+              value: `${impactPercent >= 0 ? "+" : ""}${impactPercent.toFixed(2)}%`,
+              short: true,
+            },
+            {
+              title: "Previous TVL",
+              value: `$${formatAmount(previousTVL, 2)}`,
+              short: true,
+            },
+            {
+              title: "Current TVL",
+              value: `$${formatAmount(currentTVL, 2)}`,
+              short: true,
+            },
+            {
+              title: "Transaction",
+              value: `\`${txHash.slice(0, 18)}...\``,
+              short: true,
+            },
+          ],
+          ts: Math.floor(Date.now() / 1000),
+        },
+      ],
+    });
+  }
+}