feat: allow per-curator notifications

Author: doomsower

package.json

@@ -21,18 +21,18 @@
     "pino-pretty": "^13.1.3"
   },
   "devDependencies": {
-    "@aws-sdk/client-s3": "^3.971.0",
+    "@aws-sdk/client-s3": "^3.972.0",
     "@biomejs/biome": "^2.3.11",
     "@commander-js/extra-typings": "^14.0.0",
     "@commitlint/cli": "^20.3.1",
     "@commitlint/config-conventional": "^20.3.1",
     "@gearbox-protocol/biome-config": "^1.0.17",
-    "@gearbox-protocol/cli-utils": "^5.67.0",
+    "@gearbox-protocol/cli-utils": "^5.68.2",
     "@gearbox-protocol/liquidator-contracts": "^1.36.0-experimental.67",
     "@gearbox-protocol/liquidator-v2-contracts": "^2.4.0",
-    "@gearbox-protocol/sdk": "12.5.0",
+    "@gearbox-protocol/sdk": "12.5.2",
     "@gearbox-protocol/types": "^1.14.8",
-    "@types/node": "^25.0.9",
+    "@types/node": "^25.0.10",
     "@uniswap/sdk-core": "^7.10.1",
     "@uniswap/v3-sdk": "^3.27.0",
     "@vlad-yakovlev/telegram-md": "^2.1.0",
@@ -46,7 +46,7 @@
     "lint-staged": "^16.2.7",
     "nanoid": "^5.1.6",
     "node-pty": "^1.1.0",
-    "pino": "^10.2.0",
+    "pino": "^10.2.1",
     "tsx": "4.21.0",
     "typescript": "^5.9.3",
     "viem": "^2.44.4",

src/config/common.ts

@@ -10,6 +10,7 @@ import {
 import { MAX_UINT256, WAD } from "@gearbox-protocol/sdk";
 import { type Hex, isHex } from "viem";
 import { z } from "zod/v4";
+import { NotificationsConfig } from "./notifications.js";
 
 export const CommonSchema = z.object({
   ...ProvidersSchema.shape,
@@ -399,55 +400,9 @@ export const CommonSchema = z.object({
   }),
 
   /**
-   * Telegram bot token used to send notifications
+   * Notifications, global and per-curator
    */
-  telegramBotToken: z
-    .string()
-    .transform(CensoredString.transform)
-    .optional()
-    .register(zommandRegistry, {
-      flags: "--telegram-bot-token <token>",
-      description: "Telegram bot token used to send notifications",
-      env: "TELEGRAM_BOT_TOKEN",
-    }),
-  /**
-   * Telegram channel where bot will post critical notifications
-   */
-  telegramAlertsChannel: z
-    .string()
-    .startsWith("-")
-    .optional()
-    .register(zommandRegistry, {
-      flags: "--telegram-alerts-channel <channel>",
-      description:
-        "Telegram channel where bot will post critical notifications",
-      env: "TELEGRAM_ALERTS_CHANNEL",
-    }),
-  /**
-   * Telegram channel where bot will post non-critical notifications
-   */
-  telegramNotificationsChannel: z
-    .string()
-    .startsWith("-")
-    .optional()
-    .register(zommandRegistry, {
-      flags: "--telegram-notifications-channel <channel>",
-      description:
-        "Telegram channel where bot will post non-critical notifications",
-      env: "TELEGRAM_NOTIFICATIONS_CHANNEL",
-    }),
-  /**
-   * Notification cooldown in minutes
-   */
-  notificationCooldown: z.coerce
-    .number()
-    .nonnegative()
-    .default(4 * 60)
-    .register(zommandRegistry, {
-      flags: "--notification-cooldown <cooldown>",
-      description: "Notification cooldown in minutes",
-      env: "NOTIFICATION_COOLDOWN",
-    }),
+  ...NotificationsConfig.shape,
 });
 
 export type CommonSchema = z.infer<typeof CommonSchema>;

src/config/index.ts

@@ -3,5 +3,6 @@ export type * from "./common.js";
 export * from "./config.js";
 export type * from "./deleverage-liquidator.js";
 export type * from "./full-liquidator.js";
+export { NotificationsConfig } from "./notifications.js";
 export type * from "./partial-liquidator.js";
 export { ConfigSchema } from "./schema.js";

src/config/notifications.ts

@@ -0,0 +1,24 @@
+import { NotificationConfig } from "@gearbox-protocol/cli-utils";
+import type { Curator } from "@gearbox-protocol/sdk";
+import { z } from "zod/v4";
+
+const extendedOptions = NotificationConfig.options.map(o =>
+  o.extend({
+    /**
+     * When undefined, defaults to all curators together (aka Gearbox internal)
+     */
+    curator: z.custom<Curator>(s => typeof s === "string").optional(),
+  }),
+);
+
+export const NotificationsConfig = z.object({
+  notifications: z.array(
+    z.discriminatedUnion(
+      NotificationConfig.def.discriminator,
+      extendedOptions as [
+        (typeof extendedOptions)[0],
+        ...(typeof extendedOptions)[number][],
+      ],
+    ),
+  ),
+});

src/services/Client.ts

@@ -1,5 +1,5 @@
 import { nextTick } from "node:process";
-
+import type { INotificationService } from "@gearbox-protocol/cli-utils";
 import { chains, formatBN, PERCENTAGE_FACTOR } from "@gearbox-protocol/sdk";
 import type {
   AnvilClient,
@@ -32,15 +32,13 @@ import {
   WaitForTransactionReceiptTimeoutError,
 } from "viem";
 import { privateKeyToAccount } from "viem/accounts";
-
 import type { Config } from "../config/index.js";
 import { DI } from "../di.js";
 import { errorAbis } from "../errors/abis.js";
 import { TransactionRevertedError } from "../errors/TransactionRevertedError.js";
 import { type ILogger, Logger } from "../log/index.js";
 import type { StatusCode } from "../utils/index.js";
-import type { INotifier } from "./notifier/index.js";
-import { LowBalanceMessage } from "./notifier/index.js";
+import { LowBalanceNotification } from "./notifier/index.js";
 
 const GAS_X = 5000n;
 
@@ -50,7 +48,7 @@ export default class Client {
   config!: Config;
 
   @DI.Inject(DI.Notifier)
-  notifier!: INotifier;
+  notifier!: INotificationService;
 
   @DI.Inject(DI.Transport)
   transport!: Transport<"revolver", RevolverTransportValue>;
@@ -270,7 +268,12 @@ export default class Client {
     this.logger.debug(`liquidator balance is ${formatEther(balance)}`);
     if (balance < this.config.minBalance) {
       this.notifier.alert(
-        new LowBalanceMessage(this.address, balance, this.config.minBalance),
+        new LowBalanceNotification(
+          this.config.network,
+          this.address,
+          balance,
+          this.config.minBalance,
+        ),
       );
     }
   }

src/services/Scanner.ts

@@ -1,3 +1,4 @@
+import type { INotificationService } from "@gearbox-protocol/cli-utils";
 import type {
   CreditAccountData,
   GetCreditAccountsOptions,
@@ -20,7 +21,7 @@ import { type ILogger, Logger } from "../log/index.js";
 import type Client from "./Client.js";
 import type DeleverageService from "./DeleverageService.js";
 import type { ILiquidatorService } from "./liquidate/index.js";
-import { type INotifier, ZeroHFAccountsMessage } from "./notifier/index.js";
+import { ZeroHFAccountsNotification } from "./notifier/ZeroHFAccountsNotification.js";
 
 const RESTAKING_CMS: Partial<Record<NetworkType, Address>> = {
   Mainnet:
@@ -50,7 +51,7 @@ export class Scanner {
   deleverage!: DeleverageService;
 
   @DI.Inject(DI.Notifier)
-  notifier!: INotifier;
+  notifier!: INotificationService;
 
   #processing: bigint | null = null;
   #restakingCMAddr?: Address;
@@ -59,7 +60,6 @@ export class Scanner {
   #maxHealthFactor = MAX_UINT256;
   #minHealthFactor = 0n;
   #unwatch?: () => void;
-  #lastZeroHFNotification = 0;
   #liquidatableAccounts = 0;
 
   public async launch(): Promise<void> {
@@ -265,14 +265,13 @@ export class Scanner {
             }
           }
         }
-        const badTokensStr = badTokens
-          .asArray()
-          .map(t => this.caService.sdk.tokensMeta.get(t)?.symbol ?? t)
-          .join(", ");
-        this.log.warn(
-          `found ${zeroHFAccs.length} accounts with HF=0 and ${badTokens.size} bad tokens: ${badTokensStr}`,
+        this.notifier.alert(
+          new ZeroHFAccountsNotification(
+            this.caService.sdk,
+            zeroHFAccs.length,
+            badTokens,
+          ),
         );
-        this.#notifyOnZeroHFAccounts(zeroHFAccs.length, badTokensStr);
       }
     }
 
@@ -424,16 +423,6 @@ export class Scanner {
     );
   }
 
-  #notifyOnZeroHFAccounts(count: number, badTokens: string): void {
-    const now = Date.now();
-    if (now - this.#lastZeroHFNotification < 1000 * 60 * 5) {
-      return;
-    }
-    this.#lastZeroHFNotification = now;
-    this.log.debug("notifying on zero HF accounts");
-    this.notifier.alert(new ZeroHFAccountsMessage(count, badTokens));
-  }
-
   public get lastUpdated(): bigint {
     return this.#lastUpdated;
   }

src/services/liquidate/AbstractLiquidator.ts

@@ -1,3 +1,4 @@
+import type { INotificationService } from "@gearbox-protocol/cli-utils";
 import type {
   CreditAccountData,
   GearboxSDK,
@@ -6,14 +7,13 @@ import type {
 import { filterDustUSD } from "@gearbox-protocol/sdk";
 import type { OptimisticResult } from "@gearbox-protocol/types/optimist";
 import { type Address, erc20Abi } from "viem";
-
 import type { CommonSchema, LiqduiatorConfig } from "../../config/index.js";
 import { DI } from "../../di.js";
 import { ErrorHandler } from "../../errors/index.js";
 import type { ILogger } from "../../log/index.js";
 import { Logger } from "../../log/index.js";
 import type Client from "../Client.js";
-import { type INotifier, StartedMessage } from "../notifier/index.js";
+import { ServiceStartedNotification } from "../notifier/index.js";
 import type { IOptimisticOutputWriter } from "../output/index.js";
 import type { ISwapper } from "../swap/index.js";
 import AccountHelper from "./AccountHelper.js";
@@ -34,7 +34,7 @@ export default abstract class AbstractLiquidator<
   creditAccountService!: ICreditAccountsService;
 
   @DI.Inject(DI.Notifier)
-  notifier!: INotifier;
+  notifier!: INotificationService;
 
   @DI.Inject(DI.Config)
   config!: LiqduiatorConfig<TConfig>;
@@ -58,7 +58,7 @@ export default abstract class AbstractLiquidator<
   public async launch(asFallback?: boolean): Promise<void> {
     this.#errorHandler = new ErrorHandler(this.config, this.logger);
     if (!asFallback) {
-      this.notifier.notify(new StartedMessage());
+      this.notifier.notify(new ServiceStartedNotification());
     }
   }
 

src/services/liquidate/BatchLiquidator.ts

@@ -23,9 +23,9 @@ import type { Address, TransactionReceipt } from "viem";
 import { encodeFunctionData, parseEventLogs } from "viem";
 import type { BatchLiquidatorSchema } from "../../config/index.js";
 import {
-  BatchLiquidationErrorMessage,
-  BatchLiquidationFinishedMessage,
-} from "../notifier/messages.js";
+  BatchLiquidationErrorNotification,
+  BatchLiquidationFinishedNotification,
+} from "../notifier/index.js";
 import AbstractLiquidator from "./AbstractLiquidator.js";
 import type { ILiquidatorService } from "./types.js";
 import type {
@@ -77,13 +77,17 @@ export default class BatchLiquidator
           batches.length,
         );
         this.notifier.notify(
-          new BatchLiquidationFinishedMessage(receipt, results),
+          new BatchLiquidationFinishedNotification(this.sdk, receipt, results),
         );
       } catch (e) {
         const decoded = await this.errorHandler.explain(e);
         this.logger.error(`cant liquidate: ${decoded.shortMessage}`);
         this.notifier.notify(
-          new BatchLiquidationErrorMessage(batch, decoded.shortMessage),
+          new BatchLiquidationErrorNotification(
+            this.sdk,
+            batch,
+            decoded.shortMessage,
+          ),
         );
       }
     }

src/services/liquidate/SingularLiquidator.ts

@@ -15,9 +15,9 @@ import type {
 import { TransactionRevertedError } from "../../errors/index.js";
 import { LoggerFactory } from "../../log/index.js";
 import {
-  LiquidationErrorMessage,
-  LiquidationStartMessage,
-  LiquidationSuccessMessage,
+  LiquidationErrorNotification,
+  LiquidationStartNotification,
+  LiquidationSuccessNotification,
 } from "../notifier/index.js";
 import AbstractLiquidator, {
   type ExecutorBalance,
@@ -103,8 +103,6 @@ export default class SingularLiquidator
       LoggerFactory.setLogContext({ account: ca.creditAccount });
       await this.#liquidateOne(ca);
       LoggerFactory.clearLogContext();
-      // success or no, silence the notifier for this account for a while
-      this.notifier.setCooldown(ca.creditAccount.toLowerCase());
     }
   }
 
@@ -152,7 +150,7 @@ export default class SingularLiquidator
     let pathHuman: string[] | undefined;
     let skipOnFailure = false;
 
-    this.notifier.notify(new LiquidationStartMessage(ca));
+    this.notifier.notify(new LiquidationStartNotification(this.sdk, ca));
 
     for (const s of this.#strategies) {
       if (!s.isApplicable(ca)) {
@@ -171,7 +169,13 @@ export default class SingularLiquidator
         const receipt = await this.client.liquidate(request);
         if (receipt.status === "success") {
           this.notifier.alert(
-            new LiquidationSuccessMessage(ca, s.name, receipt, pathHuman),
+            new LiquidationSuccessNotification(
+              this.sdk,
+              ca,
+              receipt,
+              s.name,
+              pathHuman,
+            ),
           );
           return;
         } else {
@@ -183,7 +187,8 @@ export default class SingularLiquidator
           `cant liquidate with ${s.name}: ${decoded.shortMessage}`,
         );
         this.notifier.alert(
-          new LiquidationErrorMessage(
+          new LiquidationErrorNotification(
+            this.sdk,
             ca,
             s.name,
             decoded.shortMessage,