@humanode-hyperlane/metrics 0.0.0-stage → 0.2.8

package/dist/update.js

@@ -0,0 +1,163 @@
+import { TokenStandard, } from '@humanode-hyperlane/sdk';
+import { isNullish } from '@humanode-hyperlane/utils';
+/**
+ * Updates token balance metrics for a warp route token.
+ *
+ * @param gauges - The warp metrics gauges to update
+ * @param warpCore - The WarpCore instance for the route
+ * @param token - The token to update metrics for
+ * @param balanceInfo - The balance information for the token
+ * @param warpRouteId - The warp route identifier
+ * @param logger - The logger instance
+ */
+export function updateTokenBalanceMetrics(gauges, warpCore, token, balanceInfo, warpRouteId, logger) {
+    const allChains = warpCore.getTokenChains().sort();
+    const relatedChains = allChains.filter((chainName) => chainName !== token.chainName);
+    const metrics = {
+        chain_name: token.chainName,
+        token_address: balanceInfo.tokenAddress,
+        token_name: token.name,
+        wallet_address: 
+        // the balance for an EvmHypERC20 token is returned as the total supply of the xERC20 token,
+        // therefore we set the wallet address to the token address,
+        // we follow the same pattern or synthetic tokens
+        token.standard !== TokenStandard.EvmHypXERC20
+            ? token.addressOrDenom
+            : balanceInfo.tokenAddress,
+        token_standard: 
+        // as we are reporting the total supply for clarity we report the standard as xERC20
+        token.standard !== TokenStandard.EvmHypXERC20 ? token.standard : 'xERC20',
+        warp_route_id: warpRouteId,
+        // TODO: consider deprecating this label given that we have the value at risk metric
+        related_chain_names: relatedChains.join(','),
+    };
+    gauges.warpRouteTokenBalance.labels({ ...metrics }).set(balanceInfo.balance);
+    logger.info({
+        labels: metrics,
+        balance: balanceInfo.balance,
+    }, 'Wallet balance updated for token');
+    if (!isNullish(balanceInfo.valueUSD)) {
+        // TODO: consider deprecating this metric in favor of the value at risk metric
+        gauges.warpRouteCollateralValue
+            .labels({ ...metrics })
+            .set(balanceInfo.valueUSD);
+        logger.info({
+            labels: metrics,
+            valueUSD: balanceInfo.valueUSD,
+        }, 'Wallet value updated for token');
+        for (const chainName of allChains) {
+            const labels = {
+                chain_name: chainName,
+                collateral_chain_name: metrics.chain_name,
+                token_address: metrics.token_address,
+                token_name: metrics.token_name,
+                collateral_token_standard: metrics.token_standard,
+                warp_route_id: metrics.warp_route_id,
+            };
+            gauges.warpRouteValueAtRisk
+                .labels({ ...labels })
+                .set(balanceInfo.valueUSD);
+            logger.info({
+                labels,
+                valueUSD: balanceInfo.valueUSD,
+            }, `Value at risk on ${chainName} updated for token`);
+        }
+    }
+}
+/**
+ * Updates managed lockbox balance metrics.
+ *
+ * @param gauges - The warp metrics gauges to update
+ * @param warpCore - The WarpCore instance for the route
+ * @param chainName - The chain name where the lockbox is deployed
+ * @param tokenName - The name of the collateral token
+ * @param tokenAddress - The address of the collateral token
+ * @param lockBoxAddress - The address of the managed lockbox
+ * @param balanceInfo - The balance information for the lockbox
+ * @param warpRouteId - The warp route identifier
+ * @param logger - The logger instance
+ */
+export function updateManagedLockboxBalanceMetrics(gauges, warpCore, chainName, tokenName, tokenAddress, lockBoxAddress, balanceInfo, warpRouteId, logger) {
+    const metrics = {
+        chain_name: chainName,
+        token_address: tokenAddress,
+        token_name: tokenName,
+        wallet_address: lockBoxAddress,
+        token_standard: 'EvmManagedLockbox', // TODO: we should eventually add a new TokenStandard for this
+        warp_route_id: warpRouteId,
+        related_chain_names: warpCore
+            .getTokenChains()
+            .filter((_chainName) => _chainName !== chainName)
+            .sort()
+            .join(','),
+    };
+    gauges.warpRouteTokenBalance.labels({ ...metrics }).set(balanceInfo.balance);
+    logger.info({
+        labels: metrics,
+        balance: balanceInfo.balance,
+    }, 'ManagedLockbox collateral balance updated');
+    if (!isNullish(balanceInfo.valueUSD)) {
+        gauges.warpRouteCollateralValue
+            .labels({ ...metrics })
+            .set(balanceInfo.valueUSD);
+        logger.info({
+            labels: metrics,
+            valueUSD: balanceInfo.valueUSD,
+        }, 'ManagedLockbox value updated for token');
+    }
+}
+/**
+ * Updates native wallet balance metrics.
+ *
+ * @param gauges - The warp metrics gauges to update
+ * @param balance - The native wallet balance information
+ * @param logger - The logger instance
+ */
+export function updateNativeWalletBalanceMetrics(gauges, balance, logger) {
+    gauges.walletBalanceGauge
+        .labels({
+        chain: balance.chain,
+        wallet_address: balance.walletAddress,
+        wallet_name: balance.walletName,
+        token_address: 'native',
+        token_symbol: 'Native',
+        token_name: 'Native',
+    })
+        .set(balance.balance);
+    logger.info('Native wallet balance updated', {
+        balanceInfo: balance,
+    });
+}
+/**
+ * Updates xERC20 limits metrics.
+ *
+ * @param gauges - The warp metrics gauges to update
+ * @param token - The token to update metrics for
+ * @param limits - The xERC20 limits
+ * @param bridgeAddress - The address of the bridge
+ * @param bridgeLabel - A label for the bridge (e.g., token standard)
+ * @param xERC20Address - The address of the xERC20 token
+ * @param logger - The logger instance
+ */
+export function updateXERC20LimitsMetrics(gauges, token, limits, bridgeAddress, bridgeLabel, xERC20Address, logger) {
+    const labels = {
+        chain_name: token.chainName,
+        token_name: token.name,
+        bridge_address: bridgeAddress,
+        token_address: xERC20Address,
+        bridge_label: bridgeLabel,
+    };
+    for (const [limitType, limit] of Object.entries(limits)) {
+        gauges.xERC20LimitsGauge
+            .labels({
+            ...labels,
+            limit_type: limitType,
+        })
+            .set(limit);
+    }
+    logger.info({
+        ...labels,
+        limits,
+    }, 'xERC20 limits updated for bridge on token');
+}
+//# sourceMappingURL=update.js.map

package/dist/update.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"update.js","sourceRoot":"","sources":["../src/update.ts"],"names":[],"mappings":"AAEA,OAAO,EAGL,aAAa,GAEd,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAgB,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAUpE;;;;;;;;;GASG;AACH,MAAM,UAAU,yBAAyB,CACvC,MAAyB,EACzB,QAAkB,EAClB,KAAY,EACZ,WAA6B,EAC7B,WAAmB,EACnB,MAAc;IAEd,MAAM,SAAS,GAAG,QAAQ,CAAC,cAAc,EAAE,CAAC,IAAI,EAAE,CAAC;IACnD,MAAM,aAAa,GAAG,SAAS,CAAC,MAAM,CACpC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,KAAK,KAAK,CAAC,SAAS,CAC7C,CAAC;IAEF,MAAM,OAAO,GAA0B;QACrC,UAAU,EAAE,KAAK,CAAC,SAAS;QAC3B,aAAa,EAAE,WAAW,CAAC,YAAY;QACvC,UAAU,EAAE,KAAK,CAAC,IAAI;QACtB,cAAc;QACZ,4FAA4F;QAC5F,4DAA4D;QAC5D,iDAAiD;QACjD,KAAK,CAAC,QAAQ,KAAK,aAAa,CAAC,YAAY;YAC3C,CAAC,CAAC,KAAK,CAAC,cAAc;YACtB,CAAC,CAAC,WAAW,CAAC,YAAY;QAC9B,cAAc;QACZ,oFAAoF;QACpF,KAAK,CAAC,QAAQ,KAAK,aAAa,CAAC,YAAY,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ;QAC3E,aAAa,EAAE,WAAW;QAC1B,oFAAoF;QACpF,mBAAmB,EAAE,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC;KAC7C,CAAC;IAEF,MAAM,CAAC,qBAAqB,CAAC,MAAM,CAAC,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC,GAAG,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;IAC7E,MAAM,CAAC,IAAI,CACT;QACE,MAAM,EAAE,OAAO;QACf,OAAO,EAAE,WAAW,CAAC,OAAO;KAC7B,EACD,kCAAkC,CACnC,CAAC;IAEF,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC,QAAQ,CAAC,EAAE,CAAC;QACrC,8EAA8E;QAC9E,MAAM,CAAC,wBAAwB;aAC5B,MAAM,CAAC,EAAE,GAAG,OAAO,EAAE,CAAC;aACtB,GAAG,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;QAC7B,MAAM,CAAC,IAAI,CACT;YACE,MAAM,EAAE,OAAO;YACf,QAAQ,EAAE,WAAW,CAAC,QAAQ;SAC/B,EACD,gCAAgC,CACjC,CAAC;QAEF,KAAK,MAAM,SAAS,IAAI,SAAS,EAAE,CAAC;YAClC,MAAM,MAAM,GAAG;gBACb,UAAU,EAAE,SAAS;gBACrB,qBAAqB,EAAE,OAAO,CAAC,UAAU;gBACzC,aAAa,EAAE,OAAO,CAAC,aAAa;gBACpC,UAAU,EAAE,OAAO,CAAC,UAAU;gBAC9B,yBAAyB,EAAE,OAAO,CAAC,cAAc;gBACjD,aAAa,EAAE,OAAO,CAAC,aAAa;aACrC,CAAC;YAEF,MAAM,CAAC,oBAAoB;iBACxB,MAAM,CAAC,EAAE,GAAG,MAAM,EAAE,CAAC;iBACrB,GAAG,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;YAC7B,MAAM,CAAC,IAAI,CACT;gBACE,MAAM;gBACN,QAAQ,EAAE,WAAW,CAAC,QAAQ;aAC/B,EACD,oBAAoB,SAAS,oBAAoB,CAClD,CAAC;QACJ,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,kCAAkC,CAChD,MAAyB,EACzB,QAAkB,EAClB,SAAoB,EACpB,SAAiB,EACjB,YAAoB,EACpB,cAAsB,EACtB,WAA6B,EAC7B,WAAmB,EACnB,MAAc;IAEd,MAAM,OAAO,GAA0B;QACrC,UAAU,EAAE,SAAS;QACrB,aAAa,EAAE,YAAY;QAC3B,UAAU,EAAE,SAAS;QACrB,cAAc,EAAE,cAAc;QAC9B,cAAc,EAAE,mBAAmB,EAAE,8DAA8D;QACnG,aAAa,EAAE,WAAW;QAC1B,mBAAmB,EAAE,QAAQ;aAC1B,cAAc,EAAE;aAChB,MAAM,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,UAAU,KAAK,SAAS,CAAC;aAChD,IAAI,EAAE;aACN,IAAI,CAAC,GAAG,CAAC;KACb,CAAC;IAEF,MAAM,CAAC,qBAAqB,CAAC,MAAM,CAAC,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC,GAAG,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;IAC7E,MAAM,CAAC,IAAI,CACT;QACE,MAAM,EAAE,OAAO;QACf,OAAO,EAAE,WAAW,CAAC,OAAO;KAC7B,EACD,2CAA2C,CAC5C,CAAC;IAEF,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC,QAAQ,CAAC,EAAE,CAAC;QACrC,MAAM,CAAC,wBAAwB;aAC5B,MAAM,CAAC,EAAE,GAAG,OAAO,EAAE,CAAC;aACtB,GAAG,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;QAC7B,MAAM,CAAC,IAAI,CACT;YACE,MAAM,EAAE,OAAO;YACf,QAAQ,EAAE,WAAW,CAAC,QAAQ;SAC/B,EACD,wCAAwC,CACzC,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,gCAAgC,CAC9C,MAAyB,EACzB,OAA4B,EAC5B,MAAc;IAEd,MAAM,CAAC,kBAAkB;SACtB,MAAM,CAAC;QACN,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,cAAc,EAAE,OAAO,CAAC,aAAa;QACrC,WAAW,EAAE,OAAO,CAAC,UAAU;QAC/B,aAAa,EAAE,QAAQ;QACvB,YAAY,EAAE,QAAQ;QACtB,UAAU,EAAE,QAAQ;KACrB,CAAC;SACD,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IACxB,MAAM,CAAC,IAAI,CAAC,+BAA+B,EAAE;QAC3C,WAAW,EAAE,OAAO;KACrB,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,yBAAyB,CACvC,MAAyB,EACzB,KAAY,EACZ,MAAmB,EACnB,aAAsB,EACtB,WAAmB,EACnB,aAAsB,EACtB,MAAc;IAEd,MAAM,MAAM,GAAG;QACb,UAAU,EAAE,KAAK,CAAC,SAAS;QAC3B,UAAU,EAAE,KAAK,CAAC,IAAI;QACtB,cAAc,EAAE,aAAa;QAC7B,aAAa,EAAE,aAAa;QAC5B,YAAY,EAAE,WAAW;KAC1B,CAAC;IAEF,KAAK,MAAM,CAAC,SAAS,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QACxD,MAAM,CAAC,iBAAiB;aACrB,MAAM,CAAC;YACN,GAAG,MAAM;YACT,UAAU,EAAE,SAAS;SACtB,CAAC;aACD,GAAG,CAAC,KAAK,CAAC,CAAC;IAChB,CAAC;IAED,MAAM,CAAC,IAAI,CACT;QACE,GAAG,MAAM;QACT,MAAM;KACP,EACD,2CAA2C,CAC5C,CAAC;AACJ,CAAC"}

package/dist/utils.d.ts

@@ -0,0 +1,7 @@
+import type { Token } from '@humanode-hyperlane/sdk';
+/**
+ * Formats a bigint value to a number using the token's decimal precision.
+ * Returns 0 if the result is non-finite (NaN, Infinity) to avoid Prometheus dropping the metric.
+ */
+export declare function formatBigInt(token: Token, num: bigint): number;
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,yBAAyB,CAAC;AAErD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAG9D"}

package/dist/utils.js

@@ -0,0 +1,9 @@
+/**
+ * Formats a bigint value to a number using the token's decimal precision.
+ * Returns 0 if the result is non-finite (NaN, Infinity) to avoid Prometheus dropping the metric.
+ */
+export function formatBigInt(token, num) {
+    const result = Number(token.amount(num).getDecimalFormattedAmount());
+    return Number.isFinite(result) ? result : 0;
+}
+//# sourceMappingURL=utils.js.map

package/dist/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,KAAY,EAAE,GAAW;IACpD,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,yBAAyB,EAAE,CAAC,CAAC;IACrE,OAAO,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;AAC9C,CAAC"}

package/package.json

@@ -1,6 +1,55 @@
 {
   "name": "@humanode-hyperlane/metrics",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.8",
+  "description": "Shared Prometheus metrics utilities for Hyperlane monitoring",
+  "keywords": [
+    "hyperlane",
+    "metrics",
+    "monitoring",
+    "prometheus",
+    "warp-route"
+  ],
+  "license": "Apache-2.0",
+  "author": "Abacus Works, Inc.",
+  "repository": "https://github.com/humanode-network/hyperlane-monorepo",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "dependencies": {
+    "ethers": "^5.8.0",
+    "pino": "^8.19.0",
+    "prom-client": "^14.0.1",
+    "@humanode-hyperlane/core": "11.2.0",
+    "@humanode-hyperlane/sdk": "30.0.0",
+    "@humanode-hyperlane/utils": "30.0.0"
+  },
+  "devDependencies": {
+    "@types/chai": "^4.3.11",
+    "@types/mocha": "^10.0.1",
+    "@types/node": "^24.10.9",
+    "@types/sinon": "^17.0.1",
+    "chai": "^4.5.0",
+    "mocha": "^11.5.0",
+    "oxfmt": "^0.42.0",
+    "sinon": "^13.0.2",
+    "tsx": "^4.19.1",
+    "typescript": "6.0.2",
+    "@humanode-hyperlane/tsconfig": "^30.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "dev": "tsc --watch",
+    "lint": "oxlint -c ../../oxlint.json",
+    "format": "oxfmt --write ./src",
+    "test": "mocha --config .mocharc.json './src/**/*.test.ts' --exit",
+    "test:ci": "pnpm test"
+  }
 }

package/src/balance.ts

@@ -0,0 +1,380 @@
+import { Contract, type PopulatedTransaction } from 'ethers';
+import type { Logger } from 'pino';
+
+import { IXERC20VS__factory } from '@humanode-hyperlane/core';
+import {
+  type EvmHypXERC20Adapter,
+  type EvmHypXERC20LockboxAdapter,
+  EvmTokenAdapter,
+  type IHypXERC20Adapter,
+  type MultiProtocolProvider,
+  type SealevelHypTokenAdapter,
+  Token,
+  TokenStandard,
+  type WarpCore,
+} from '@humanode-hyperlane/sdk';
+import { type Address, ProtocolType } from '@humanode-hyperlane/utils';
+
+import type {
+  NativeWalletBalance,
+  WarpRouteBalance,
+  XERC20Info,
+  XERC20Limit,
+} from './types.js';
+import { formatBigInt } from './utils.js';
+
+/**
+ * Minimal ABI for managed lockbox contracts.
+ */
+export const MANAGED_LOCKBOX_MINIMAL_ABI = [
+  'function XERC20() view returns (address)',
+  'function ERC20() view returns (address)',
+] as const;
+
+/**
+ * Interface for token price getter to allow different implementations.
+ */
+export interface TokenPriceGetter {
+  tryGetTokenPrice(token: Token): Promise<number | undefined>;
+}
+
+/**
+ * Gets the bridged balance and value of a token in a warp route.
+ *
+ * @param warpCore - The WarpCore instance for the route
+ * @param token - The token to get the balance for
+ * @param tokenPriceGetter - Price getter for calculating USD value
+ * @param logger - Logger instance
+ * @param bridgedSupply - Optional pre-fetched bridged supply
+ * @returns The balance information or undefined if not available
+ */
+export async function getTokenBridgedBalance(
+  warpCore: WarpCore,
+  token: Token,
+  tokenPriceGetter: TokenPriceGetter,
+  logger: Logger,
+  bridgedSupply?: bigint,
+): Promise<WarpRouteBalance | undefined> {
+  if (!token.isHypToken()) {
+    logger.warn(
+      { token: token.symbol, chain: token.chainName },
+      'No support for bridged balance on non-Hyperlane token',
+    );
+    return undefined;
+  }
+
+  const adapter = token.getHypAdapter(warpCore.multiProvider);
+  let tokenAddress = token.collateralAddressOrDenom ?? token.addressOrDenom;
+
+  // If bridged supply is not provided, fetch it
+  const supply = bridgedSupply ?? (await adapter.getBridgedSupply());
+  if (supply === undefined) {
+    logger.warn(
+      { token: token.symbol, chain: token.chainName },
+      'Failed to get bridged supply',
+    );
+    return undefined;
+  }
+
+  const balance = token.amount(supply).getDecimalFormattedAmount();
+
+  let tokenPrice;
+  // Only record value for collateralized and xERC20 lockbox tokens.
+  if (
+    token.isCollateralized() ||
+    token.standard === TokenStandard.EvmHypXERC20Lockbox ||
+    token.standard === TokenStandard.EvmHypVSXERC20Lockbox
+  ) {
+    tokenPrice = await tokenPriceGetter.tryGetTokenPrice(token);
+  }
+
+  if (
+    token.standard === TokenStandard.EvmHypXERC20Lockbox ||
+    token.standard === TokenStandard.EvmHypVSXERC20Lockbox
+  ) {
+    tokenAddress = (await (adapter as EvmHypXERC20LockboxAdapter).getXERC20())
+      .address;
+  }
+
+  return {
+    balance,
+    valueUSD: tokenPrice ? balance * tokenPrice : undefined,
+    tokenAddress,
+  };
+}
+
+/**
+ * Gets the native balance of the ATA payer for Sealevel tokens.
+ *
+ * @param warpCore - The WarpCore instance for the route
+ * @param token - The Sealevel token
+ * @param warpRouteId - The warp route identifier
+ * @returns The native wallet balance information
+ */
+export async function getSealevelAtaPayerBalance(
+  warpCore: WarpCore,
+  token: Token,
+  warpRouteId: string,
+): Promise<NativeWalletBalance> {
+  if (token.protocol !== ProtocolType.Sealevel || token.isNative()) {
+    throw new Error(
+      `Unsupported ATA payer protocol type ${token.protocol} or standard ${token.standard}`,
+    );
+  }
+  const adapter = token.getHypAdapter(
+    warpCore.multiProvider,
+  ) as SealevelHypTokenAdapter;
+
+  const ataPayer = adapter.deriveAtaPayerAccount().toString();
+  const nativeToken = Token.FromChainMetadataNativeToken(
+    warpCore.multiProvider.getChainMetadata(token.chainName),
+  );
+  const ataPayerBalance = await nativeToken.getBalance(
+    warpCore.multiProvider,
+    ataPayer,
+  );
+
+  return {
+    chain: token.chainName,
+    walletAddress: ataPayer.toString(),
+    walletName: `${warpRouteId}/ata-payer`,
+    balance: ataPayerBalance.getDecimalFormattedAmount(),
+  };
+}
+
+/**
+ * Gets xERC20 information for a token.
+ *
+ * @param warpCore - The WarpCore instance for the route
+ * @param token - The xERC20 token
+ * @returns The xERC20 info including limits and address
+ */
+export async function getXERC20Info(
+  warpCore: WarpCore,
+  token: Token,
+): Promise<XERC20Info> {
+  if (
+    token.protocol !== ProtocolType.Ethereum &&
+    token.protocol !== ProtocolType.Tron
+  ) {
+    throw new Error(`Unsupported XERC20 protocol type ${token.protocol}`);
+  }
+
+  if (
+    token.standard === TokenStandard.EvmHypXERC20 ||
+    token.standard === TokenStandard.EvmHypVSXERC20 ||
+    token.standard == TokenStandard.TronHypVSXERC20 ||
+    token.standard == TokenStandard.TronHypXERC20
+  ) {
+    const adapter = token.getAdapter(
+      warpCore.multiProvider,
+    ) as EvmHypXERC20Adapter;
+    return {
+      limits: await getXERC20Limit(token, adapter),
+      xERC20Address: (await adapter.getXERC20()).address,
+    };
+  } else if (
+    token.standard === TokenStandard.EvmHypXERC20Lockbox ||
+    token.standard === TokenStandard.EvmHypVSXERC20Lockbox ||
+    token.standard === TokenStandard.TronHypXERC20Lockbox ||
+    token.standard === TokenStandard.TronHypVSXERC20Lockbox
+  ) {
+    const adapter = token.getAdapter(
+      warpCore.multiProvider,
+    ) as EvmHypXERC20LockboxAdapter;
+    return {
+      limits: await getXERC20Limit(token, adapter),
+      xERC20Address: (await adapter.getXERC20()).address,
+    };
+  }
+
+  throw new Error(`Unsupported XERC20 token standard ${token.standard}`);
+}
+
+/**
+ * Gets xERC20 limits from an adapter.
+ *
+ * @param token - The token to get limits for
+ * @param xerc20 - The xERC20 adapter
+ * @returns The xERC20 limits
+ */
+export async function getXERC20Limit(
+  token: Token,
+  xerc20: IHypXERC20Adapter<PopulatedTransaction>,
+): Promise<XERC20Limit> {
+  const [mintCurrent, mintMax, burnCurrent, burnMax] = await Promise.all([
+    xerc20.getMintLimit(),
+    xerc20.getMintMaxLimit(),
+    xerc20.getBurnLimit(),
+    xerc20.getBurnMaxLimit(),
+  ]);
+
+  return {
+    mint: formatBigInt(token, mintCurrent),
+    mintMax: formatBigInt(token, mintMax),
+    burn: formatBigInt(token, burnCurrent),
+    burnMax: formatBigInt(token, burnMax),
+  };
+}
+
+/**
+ * Gets a managed lockbox contract instance.
+ *
+ * @param multiProvider - The multi-protocol provider
+ * @param chainName - The chain name
+ * @param lockboxAddress - The lockbox contract address
+ * @returns The Contract instance
+ */
+export function getManagedLockBox(
+  multiProvider: MultiProtocolProvider,
+  chainName: string,
+  lockboxAddress: Address,
+): Contract {
+  const provider = multiProvider.getEthersV5Provider(chainName);
+  return new Contract(lockboxAddress, MANAGED_LOCKBOX_MINIMAL_ABI, provider);
+}
+
+/**
+ * Gets extra lockbox information for xERC20 tokens.
+ *
+ * @param multiProvider - The multi-protocol provider
+ * @param warpToken - The warp token
+ * @param lockboxAddress - The lockbox contract address
+ * @returns The xERC20 info for the lockbox
+ */
+export async function getExtraLockboxInfo(
+  multiProvider: MultiProtocolProvider,
+  warpToken: Token,
+  lockboxAddress: Address,
+): Promise<XERC20Info> {
+  const currentChainProvider = multiProvider.getEthersV5Provider(
+    warpToken.chainName,
+  );
+  const lockboxInstance = getManagedLockBox(
+    multiProvider,
+    warpToken.chainName,
+    lockboxAddress,
+  );
+
+  const xERC20Address = await lockboxInstance['XERC20']();
+  const vsXERC20Instance = IXERC20VS__factory.connect(
+    xERC20Address,
+    currentChainProvider,
+  );
+
+  const [mintMax, burnMax, mint, burn] = await Promise.all([
+    vsXERC20Instance.mintingMaxLimitOf(lockboxAddress),
+    vsXERC20Instance.burningMaxLimitOf(lockboxAddress),
+    vsXERC20Instance.mintingCurrentLimitOf(lockboxAddress),
+    vsXERC20Instance.burningCurrentLimitOf(lockboxAddress),
+  ]);
+
+  return {
+    limits: {
+      burn: formatBigInt(warpToken, burn.toBigInt()),
+      burnMax: formatBigInt(warpToken, burnMax.toBigInt()),
+      mint: formatBigInt(warpToken, mint.toBigInt()),
+      mintMax: formatBigInt(warpToken, mintMax.toBigInt()),
+    },
+    xERC20Address,
+  };
+}
+
+/**
+ * Gets the balance of an extra lockbox.
+ *
+ * @param multiProvider - The multi-protocol provider
+ * @param warpToken - The warp token
+ * @param tokenPriceGetter - Price getter for calculating USD value
+ * @param lockboxAddress - The lockbox contract address
+ * @param logger - Logger instance
+ * @returns The balance information or undefined if not available
+ */
+export async function getExtraLockboxBalance(
+  multiProvider: MultiProtocolProvider,
+  warpToken: Token,
+  tokenPriceGetter: TokenPriceGetter,
+  lockboxAddress: Address,
+  logger: Logger,
+): Promise<WarpRouteBalance | undefined> {
+  if (!warpToken.isXerc20()) {
+    return undefined;
+  }
+
+  const lockboxInstance = getManagedLockBox(
+    multiProvider,
+    warpToken.chainName,
+    lockboxAddress,
+  );
+
+  const erc20TokenAddress = await lockboxInstance['ERC20']();
+  const erc20tokenAdapter = new EvmTokenAdapter(
+    warpToken.chainName,
+    multiProvider,
+    {
+      token: erc20TokenAddress,
+    },
+  );
+
+  let balance;
+  try {
+    balance = await erc20tokenAdapter.getBalance(lockboxAddress);
+  } catch (err) {
+    logger.error(
+      {
+        err,
+        chain: warpToken.chainName,
+        token: warpToken.symbol,
+        lockboxAddress,
+        erc20TokenAddress,
+      },
+      'Failed to get balance for contract at lockbox address',
+    );
+    return undefined;
+  }
+
+  const tokenPrice = await tokenPriceGetter.tryGetTokenPrice(warpToken);
+  const balanceNumber = formatBigInt(warpToken, balance);
+
+  return {
+    balance: balanceNumber,
+    valueUSD: tokenPrice ? balanceNumber * tokenPrice : undefined,
+    tokenAddress: erc20TokenAddress,
+  };
+}
+
+/**
+ * Gets collateral info for a managed lockbox.
+ *
+ * @param multiProvider - The multi-protocol provider
+ * @param warpToken - The warp token
+ * @param lockBoxAddress - The lockbox contract address
+ * @returns The token name and address of the collateral
+ */
+export async function getManagedLockBoxCollateralInfo(
+  multiProvider: MultiProtocolProvider,
+  warpToken: Token,
+  lockBoxAddress: Address,
+): Promise<{ tokenName: string; tokenAddress: Address }> {
+  const lockBoxInstance = getManagedLockBox(
+    multiProvider,
+    warpToken.chainName,
+    lockBoxAddress,
+  );
+
+  const collateralTokenAddress = await lockBoxInstance['ERC20']();
+  const collateralTokenAdapter = new EvmTokenAdapter(
+    warpToken.chainName,
+    multiProvider,
+    {
+      token: collateralTokenAddress,
+    },
+  );
+
+  const { name } = await collateralTokenAdapter.getMetadata();
+
+  return {
+    tokenName: name,
+    tokenAddress: collateralTokenAddress,
+  };
+}