@humanode-hyperlane/rebalancer 0.0.0-stage → 27.2.2-humanode.1

package/src/metrics/Metrics.ts

@@ -0,0 +1,335 @@
+import { type Logger } from 'pino';
+
+import {
+  type TokenPriceGetter,
+  getExtraLockboxBalance,
+  getExtraLockboxInfo,
+  getManagedLockBoxCollateralInfo,
+  getSealevelAtaPayerBalance,
+  getTokenBridgedBalance,
+  getXERC20Info,
+  startMetricsServer,
+} from '@humanode-hyperlane/metrics';
+import {
+  Token,
+  type TokenAmount,
+  TokenStandard,
+  TokenType,
+  type WarpCore,
+  type WarpRouteDeployConfig,
+} from '@humanode-hyperlane/sdk';
+import { ProtocolType, tryFn } from '@humanode-hyperlane/utils';
+
+import { type IMetrics } from '../interfaces/IMetrics.js';
+import { type MonitorEvent } from '../interfaces/IMonitor.js';
+import { type StrategyRoute } from '../interfaces/IStrategy.js';
+
+import { type PriceGetter } from './PriceGetter.js';
+import {
+  metricsRegister,
+  rebalancerActionsCreatedTotal,
+  rebalancerExecutionAmount,
+  rebalancerExecutionTotal,
+  rebalancerIntentsCreatedTotal,
+  rebalancerPollingErrorsTotal,
+  updateManagedLockboxBalanceMetrics,
+  updateNativeWalletBalanceMetrics,
+  updateTokenBalanceMetrics,
+  updateXERC20LimitsMetrics,
+} from './scripts/metrics.js';
+
+export class Metrics implements IMetrics {
+  private readonly logger: Logger;
+  private readonly priceGetter: TokenPriceGetter;
+
+  constructor(
+    private readonly tokenPriceGetter: PriceGetter,
+    private readonly warpDeployConfig: WarpRouteDeployConfig | null,
+    private readonly warpCore: WarpCore,
+    private readonly warpRouteId: string,
+    logger: Logger,
+  ) {
+    this.logger = logger.child({ class: Metrics.name });
+    startMetricsServer(metricsRegister);
+
+    // Wrap PriceGetter to match TokenPriceGetter interface
+    this.priceGetter = {
+      tryGetTokenPrice: async (token: Token) => {
+        return this.tokenPriceGetter.tryGetTokenPrice(token);
+      },
+    };
+  }
+
+  recordRebalancerSuccess() {
+    rebalancerExecutionTotal
+      .labels({ warp_route_id: this.warpRouteId, succeeded: 'true' })
+      .inc();
+  }
+
+  recordRebalanceAmount(route: StrategyRoute, originTokenAmount: TokenAmount) {
+    rebalancerExecutionAmount
+      .labels({
+        warp_route_id: this.warpRouteId,
+        origin: route.origin,
+        destination: route.destination,
+        token: originTokenAmount.token.symbol,
+      })
+      .inc(originTokenAmount.getDecimalFormattedAmount());
+  }
+
+  recordRebalancerFailure() {
+    rebalancerExecutionTotal
+      .labels({ warp_route_id: this.warpRouteId, succeeded: 'false' })
+      .inc();
+  }
+
+  recordPollingError() {
+    rebalancerPollingErrorsTotal
+      .labels({ warp_route_id: this.warpRouteId })
+      .inc();
+  }
+
+  recordIntentCreated(route: StrategyRoute, strategy: string) {
+    rebalancerIntentsCreatedTotal
+      .labels({
+        warp_route_id: this.warpRouteId,
+        strategy,
+        origin: route.origin,
+        destination: route.destination,
+      })
+      .inc();
+  }
+
+  recordActionAttempt(route: StrategyRoute, succeeded: boolean) {
+    rebalancerActionsCreatedTotal
+      .labels({
+        warp_route_id: this.warpRouteId,
+        origin: route.origin,
+        destination: route.destination,
+        succeeded: String(succeeded),
+      })
+      .inc();
+  }
+
+  async processToken({
+    token,
+    bridgedSupply,
+  }: MonitorEvent['tokensInfo'][number]) {
+    await tryFn(
+      async () => {
+        await this.updateTokenMetrics(token, bridgedSupply);
+      },
+      'Updating warp route metrics',
+      this.logger,
+    );
+  }
+
+  // Updates the metrics for a single token in a warp route.
+  private async updateTokenMetrics(
+    token: Token,
+    bridgedSupply?: bigint,
+  ): Promise<void> {
+    const promises = [
+      tryFn(
+        async () => {
+          const balanceInfo = await getTokenBridgedBalance(
+            this.warpCore,
+            token,
+            this.priceGetter,
+            this.logger,
+            bridgedSupply,
+          );
+
+          if (!balanceInfo) {
+            return;
+          }
+
+          updateTokenBalanceMetrics(
+            this.warpCore,
+            token,
+            balanceInfo,
+            this.warpRouteId,
+            this.logger,
+          );
+        },
+        'Getting bridged balance and value',
+        this.logger,
+      ),
+    ];
+
+    // For Sealevel collateral and synthetic tokens, there is an
+    // "Associated Token Account" (ATA) rent payer that has a balance
+    // that's used to pay for rent for the accounts that store user balances.
+    // This is necessary if the recipient has never received any tokens before.
+    if (token.protocol === ProtocolType.Sealevel && !token.isNative()) {
+      promises.push(
+        tryFn(
+          async () => {
+            const balance = await getSealevelAtaPayerBalance(
+              this.warpCore,
+              token,
+              this.warpRouteId,
+            );
+
+            updateNativeWalletBalanceMetrics(balance, this.logger);
+          },
+          'Getting ATA payer balance',
+          this.logger,
+        ),
+      );
+    }
+
+    if (token.isXerc20()) {
+      promises.push(
+        tryFn(
+          async () => {
+            const { limits, xERC20Address } = await getXERC20Info(
+              this.warpCore,
+              token,
+            );
+            const routerAddress = token.addressOrDenom;
+
+            updateXERC20LimitsMetrics(
+              token,
+              limits,
+              routerAddress,
+              token.standard,
+              xERC20Address,
+              this.logger,
+            );
+          },
+          'Getting xERC20 limits',
+          this.logger,
+        ),
+      );
+
+      if (!this.warpDeployConfig) {
+        this.logger.warn(
+          {
+            tokenSymbol: token.symbol,
+            chain: token.chainName,
+          },
+          "Can't read warp deploy config, skipping extra lockboxes",
+        );
+        return;
+      }
+
+      // If the current token is an xERC20, we need to check if there are any extra lockboxes
+      const currentTokenDeployConfig = this.warpDeployConfig[token.chainName];
+
+      if (
+        currentTokenDeployConfig.type !== TokenType.XERC20 &&
+        currentTokenDeployConfig.type !== TokenType.XERC20Lockbox
+      ) {
+        this.logger.error(
+          {
+            tokenSymbol: token.symbol,
+            chain: token.chainName,
+            expectedType: [TokenType.XERC20, TokenType.XERC20Lockbox],
+            actualType: currentTokenDeployConfig.type,
+          },
+          'Token type mismatch in deploy config for xERC20 token',
+        );
+        return;
+      }
+
+      const extraLockboxes =
+        currentTokenDeployConfig.xERC20?.extraBridges ?? [];
+
+      for (const lockbox of extraLockboxes) {
+        promises.push(
+          tryFn(
+            async () => {
+              const { limits, xERC20Address } = await getExtraLockboxInfo(
+                this.warpCore.multiProvider,
+                token,
+                lockbox.lockbox,
+              );
+
+              updateXERC20LimitsMetrics(
+                token,
+                limits,
+                lockbox.lockbox,
+                'EvmManagedLockbox',
+                xERC20Address,
+                this.logger,
+              );
+            },
+            'Getting extra lockbox limits',
+            this.logger,
+          ),
+          tryFn(
+            async () => {
+              const balance = await getExtraLockboxBalance(
+                this.warpCore.multiProvider,
+                token,
+                this.priceGetter,
+                lockbox.lockbox,
+                this.logger,
+              );
+
+              if (balance) {
+                const { tokenName, tokenAddress } =
+                  await getManagedLockBoxCollateralInfo(
+                    this.warpCore.multiProvider,
+                    token,
+                    lockbox.lockbox,
+                  );
+
+                updateManagedLockboxBalanceMetrics(
+                  this.warpCore,
+                  token.chainName,
+                  tokenName,
+                  tokenAddress,
+                  lockbox.lockbox,
+                  balance,
+                  this.warpRouteId,
+                  this.logger,
+                );
+              }
+            },
+            `Updating extra lockbox balance for contract at "${lockbox.lockbox}" on chain ${token.chainName}`,
+            this.logger,
+          ),
+        );
+      }
+    }
+
+    await Promise.all(promises);
+  }
+
+  static getWarpRouteCollateralTokenSymbol(tokens: Token[]): string {
+    // We need to have a deterministic way to determine the symbol of the warp route
+    // as its used to identify the warp route in metrics. This method should support routes where:
+    // - All tokens have the same symbol, token standards can be all collateral, all synthetic or a mix
+    // - All tokens have different symbol, but there is a collateral token to break the tie, where there are multiple collateral tokens, alphabetically first is chosen
+    // - All tokens have different symbol, but there is no collateral token to break the tie, pick the alphabetically first symbol
+
+    // Get all unique symbols from the tokens array
+    const uniqueSymbols = new Set(tokens.map((token) => token.symbol));
+
+    // If all tokens have the same symbol, return that symbol
+    if (uniqueSymbols.size === 1) {
+      return tokens[0].symbol;
+    }
+
+    // Find all collateralized tokens
+    const collateralTokens = tokens.filter(
+      (token) =>
+        token.isCollateralized() ||
+        token.standard === TokenStandard.EvmHypXERC20Lockbox,
+    );
+
+    if (collateralTokens.length === 0) {
+      // If there are no collateralized tokens, return the alphabetically first symbol
+      return [...uniqueSymbols].sort()[0];
+    }
+
+    // if there is a single unique collateral symbol return it or
+    // if there are multiple, return the alphabetically first symbol
+    const collateralSymbols = collateralTokens.map((token) => token.symbol);
+    const uniqueCollateralSymbols = [...new Set(collateralSymbols)];
+
+    return uniqueCollateralSymbols.sort()[0];
+  }
+}

package/src/metrics/PriceGetter.ts

@@ -0,0 +1,74 @@
+import { type Logger } from 'pino';
+
+import {
+  type ChainMap,
+  type ChainMetadata,
+  CoinGeckoTokenPriceGetter,
+  type Token,
+} from '@humanode-hyperlane/sdk';
+
+export class PriceGetter extends CoinGeckoTokenPriceGetter {
+  private readonly logger: Logger;
+
+  private constructor({
+    chainMetadata,
+    logger,
+    apiKey,
+    expirySeconds,
+    sleepMsBetweenRequests,
+  }: {
+    chainMetadata: ChainMap<ChainMetadata>;
+    logger: Logger;
+    apiKey?: string;
+    expirySeconds?: number;
+    sleepMsBetweenRequests?: number;
+  }) {
+    super({ chainMetadata, apiKey, expirySeconds, sleepMsBetweenRequests });
+    this.logger = logger;
+  }
+
+  public static create(
+    chainMetadata: ChainMap<ChainMetadata>,
+    logger: Logger,
+    coingeckoApiKey?: string,
+    expirySeconds?: number,
+    sleepMsBetweenRequests?: number,
+  ) {
+    return new PriceGetter({
+      chainMetadata,
+      logger,
+      apiKey: coingeckoApiKey,
+      expirySeconds,
+      sleepMsBetweenRequests,
+    });
+  }
+
+  // Tries to get the price of a token from CoinGecko. Returns undefined if there's no
+  // CoinGecko ID for the token.
+  async tryGetTokenPrice(token: Token): Promise<number | undefined> {
+    // We only get a price if the token defines a CoinGecko ID.
+    // This way we can ignore values of certain types of collateralized warp routes,
+    // e.g. Native warp routes on rollups that have been pre-funded.
+    const coinGeckoId = token.coinGeckoId;
+
+    if (!coinGeckoId) {
+      this.logger.debug(
+        {
+          tokenSymbol: token.symbol,
+          chain: token.chainName,
+          tokenAddress: token.addressOrDenom,
+        },
+        'CoinGecko ID missing for token',
+      );
+      return undefined;
+    }
+
+    return this.getCoingeckoPrice(coinGeckoId);
+  }
+
+  async getCoingeckoPrice(coingeckoId: string): Promise<number | undefined> {
+    const prices = await this.getTokenPriceByIds([coingeckoId]);
+    if (!prices) return undefined;
+    return prices[0];
+  }
+}

package/src/metrics/scripts/metrics.ts

@@ -0,0 +1,139 @@
+import { type Logger } from 'pino';
+import { Counter, Registry } from 'prom-client';
+
+import {
+  type NativeWalletBalance,
+  type WarpMetricsGauges,
+  type WarpRouteBalance,
+  type XERC20Limit,
+  createWarpMetricsGauges,
+  updateManagedLockboxBalanceMetrics as sharedUpdateManagedLockboxBalanceMetrics,
+  updateNativeWalletBalanceMetrics as sharedUpdateNativeWalletBalanceMetrics,
+  updateTokenBalanceMetrics as sharedUpdateTokenBalanceMetrics,
+  updateXERC20LimitsMetrics as sharedUpdateXERC20LimitsMetrics,
+} from '@humanode-hyperlane/metrics';
+import {
+  type ChainName,
+  type Token,
+  type WarpCore,
+} from '@humanode-hyperlane/sdk';
+import { type Address } from '@humanode-hyperlane/utils';
+
+export const metricsRegister = new Registry();
+
+// Create shared warp metrics gauges
+const gauges: WarpMetricsGauges = createWarpMetricsGauges(metricsRegister);
+
+// Rebalancer-specific metrics
+export const rebalancerExecutionTotal = new Counter({
+  name: 'hyperlane_rebalancer_executions_total',
+  help: 'Total number of rebalance execution attempts.',
+  registers: [metricsRegister],
+  labelNames: ['warp_route_id', 'succeeded'],
+});
+
+export const rebalancerExecutionAmount = new Counter({
+  name: 'hyperlane_rebalancer_execution_amount',
+  help: 'Total amount of tokens rebalanced.',
+  registers: [metricsRegister],
+  labelNames: ['warp_route_id', 'origin', 'destination', 'token'],
+});
+
+export const rebalancerPollingErrorsTotal = new Counter({
+  name: 'hyperlane_rebalancer_polling_errors_total',
+  help: 'Total number of errors during the monitor polling phase.',
+  registers: [metricsRegister],
+  labelNames: ['warp_route_id'],
+});
+
+export const rebalancerIntentsCreatedTotal = new Counter({
+  name: 'hyperlane_rebalancer_intents_created_total',
+  help: 'Total number of rebalancing intents (routes) created.',
+  registers: [metricsRegister],
+  labelNames: ['warp_route_id', 'strategy', 'origin', 'destination'],
+});
+
+export const rebalancerActionsCreatedTotal = new Counter({
+  name: 'hyperlane_rebalancer_actions_created_total',
+  help: 'Total number of rebalancing actions (transactions) attempted.',
+  registers: [metricsRegister],
+  labelNames: ['warp_route_id', 'origin', 'destination', 'succeeded'],
+});
+
+/**
+ * Updates token balance metrics for a warp route token.
+ */
+export function updateTokenBalanceMetrics(
+  warpCore: WarpCore,
+  token: Token,
+  balanceInfo: WarpRouteBalance,
+  warpRouteId: string,
+  logger: Logger,
+): void {
+  sharedUpdateTokenBalanceMetrics(
+    gauges,
+    warpCore,
+    token,
+    balanceInfo,
+    warpRouteId,
+    logger,
+  );
+}
+
+/**
+ * Updates managed lockbox balance metrics.
+ */
+export function updateManagedLockboxBalanceMetrics(
+  warpCore: WarpCore,
+  chainName: ChainName,
+  tokenName: string,
+  tokenAddress: string,
+  lockBoxAddress: string,
+  balanceInfo: WarpRouteBalance,
+  warpRouteId: string,
+  logger: Logger,
+): void {
+  sharedUpdateManagedLockboxBalanceMetrics(
+    gauges,
+    warpCore,
+    chainName,
+    tokenName,
+    tokenAddress,
+    lockBoxAddress,
+    balanceInfo,
+    warpRouteId,
+    logger,
+  );
+}
+
+/**
+ * Updates native wallet balance metrics.
+ */
+export function updateNativeWalletBalanceMetrics(
+  balance: NativeWalletBalance,
+  logger: Logger,
+): void {
+  sharedUpdateNativeWalletBalanceMetrics(gauges, balance, logger);
+}
+
+/**
+ * Updates xERC20 limits metrics.
+ */
+export function updateXERC20LimitsMetrics(
+  token: Token,
+  limits: XERC20Limit,
+  bridgeAddress: Address,
+  bridgeLabel: string,
+  xERC20Address: Address,
+  logger: Logger,
+): void {
+  sharedUpdateXERC20LimitsMetrics(
+    gauges,
+    token,
+    limits,
+    bridgeAddress,
+    bridgeLabel,
+    xERC20Address,
+    logger,
+  );
+}