@hyperlane-xyz/rebalancer 0.1.0-beta.5a8bd28ab

package/src/utils/balanceUtils.test.ts

@@ -0,0 +1,74 @@
+import { expect } from 'chai';
+import { pino } from 'pino';
+import sinon from 'sinon';
+
+import { ChainName, Token, TokenStandard } from '@hyperlane-xyz/sdk';
+
+import { MonitorEvent } from '../interfaces/IMonitor.js';
+
+import { getRawBalances } from './balanceUtils.js';
+
+const testLogger = pino({ level: 'silent' });
+
+describe('getRawBalances', () => {
+  let chains: ChainName[];
+  let token: Token;
+  let tokenBridgedSupply: bigint;
+  let event: MonitorEvent;
+
+  beforeEach(() => {
+    chains = ['mainnet'];
+
+    token = {
+      chainName: 'mainnet',
+      addressOrDenom: '0xAddress',
+      isCollateralized: sinon.stub().returns(true),
+      standard: TokenStandard.EvmHypCollateral,
+    } as unknown as Token;
+
+    tokenBridgedSupply = 100n;
+
+    event = {
+      tokensInfo: [
+        {
+          token,
+          bridgedSupply: tokenBridgedSupply,
+        },
+      ],
+    };
+  });
+
+  it('should return the bridged supply for the token (EvmHypCollateral)', () => {
+    expect(getRawBalances(chains, event, testLogger)).to.deep.equal({
+      mainnet: tokenBridgedSupply,
+    });
+  });
+
+  it('should return the bridged supply for the token (EvmHypNative)', () => {
+    token.standard = TokenStandard.EvmHypNative;
+
+    expect(getRawBalances(chains, event, testLogger)).to.deep.equal({
+      mainnet: tokenBridgedSupply,
+    });
+  });
+
+  it('should ignore non supported token standards', () => {
+    token.standard = TokenStandard.EvmHypOwnerCollateral;
+
+    expect(getRawBalances(chains, event, testLogger)).to.deep.equal({});
+  });
+
+  it('should ignore tokens that are not in the chains list', () => {
+    chains = [];
+
+    expect(getRawBalances(chains, event, testLogger)).to.deep.equal({});
+  });
+
+  it('should throw if the bridged supply is undefined', () => {
+    delete event.tokensInfo[0].bridgedSupply;
+
+    expect(() => getRawBalances(chains, event, testLogger)).to.throw(
+      'bridgedSupply should not be undefined for collateralized token 0xAddress',
+    );
+  });
+});

package/src/utils/balanceUtils.ts

@@ -0,0 +1,69 @@
+import { Logger } from 'pino';
+
+import { ChainName, Token } from '@hyperlane-xyz/sdk';
+
+import { MonitorEvent } from '../interfaces/IMonitor.js';
+import { RawBalances } from '../interfaces/IStrategy.js';
+
+import { isCollateralizedTokenEligibleForRebalancing } from './tokenUtils.js';
+
+/**
+ * Returns the raw balances required by the strategies from the monitor event
+ * @param chains - The chains that should be included in the raw balances (e.g. the chains in the rebalancer config)
+ * @param event - The monitor event to extract the raw balances from
+ * @returns An object mapping chain names to their raw balances.
+ */
+export function getRawBalances(
+  chains: ChainName[],
+  event: MonitorEvent,
+  logger: Logger,
+): RawBalances {
+  const balances: RawBalances = {};
+  const chainSet = new Set(chains);
+
+  for (const tokenInfo of event.tokensInfo) {
+    const { token, bridgedSupply } = tokenInfo;
+
+    // Ignore tokens that are not in the provided chains list
+    if (!chainSet.has(token.chainName)) {
+      logger.info(
+        {
+          context: getRawBalances.name,
+          chain: token.chainName,
+          tokenSymbol: token.symbol,
+          tokenAddress: token.addressOrDenom,
+        },
+        'Skipping token: not in configured chains list',
+      );
+      continue;
+    }
+
+    // Ignore tokens that are not collateralized or are otherwise ineligible
+    if (!isCollateralizedTokenEligibleForRebalancing(token)) {
+      logger.info(
+        {
+          context: getRawBalances.name,
+          chain: token.chainName,
+          tokenSymbol: token.symbol,
+          tokenAddress: token.addressOrDenom,
+        },
+        'Skipping token: not collateralized or ineligible for rebalancing',
+      );
+      continue;
+    }
+
+    if (bridgedSupply === undefined) {
+      throw new Error(
+        `bridgedSupply should not be undefined for collateralized token ${token.addressOrDenom}`,
+      );
+    }
+
+    balances[token.chainName] = bridgedSupply;
+  }
+
+  return balances;
+}
+
+export function formatBigInt(warpToken: Token, num: bigint): number {
+  return warpToken.amount(num).getDecimalFormattedAmount();
+}

package/src/utils/bridgeUtils.test.ts

@@ -0,0 +1,92 @@
+import { expect } from 'chai';
+import { pino } from 'pino';
+
+import { ChainMap } from '@hyperlane-xyz/sdk';
+
+import {
+  type BridgeConfigWithOverride,
+  getBridgeConfig,
+} from './bridgeUtils.js';
+
+const testLogger = pino({ level: 'silent' });
+
+describe('bridgeConfig', () => {
+  it('should return the base bridge config when no overrides exist', () => {
+    const bridges: ChainMap<BridgeConfigWithOverride> = {
+      chain1: {
+        bridge: '0x1234567890123456789012345678901234567890',
+        bridgeMinAcceptedAmount: 1000,
+        bridgeIsWarp: true,
+      },
+      chain2: {
+        bridge: '0x0987654321098765432109876543210987654321',
+        bridgeMinAcceptedAmount: 2000,
+        bridgeIsWarp: true,
+      },
+    };
+
+    const result = getBridgeConfig(bridges, 'chain1', 'chain2', testLogger);
+
+    expect(result).to.deep.equal({
+      bridge: '0x1234567890123456789012345678901234567890',
+      bridgeMinAcceptedAmount: 1000,
+      bridgeIsWarp: true,
+    });
+  });
+
+  it('should merge base config with overrides when they exist', () => {
+    const bridges: ChainMap<BridgeConfigWithOverride> = {
+      chain1: {
+        bridge: '0x1234567890123456789012345678901234567890',
+        bridgeMinAcceptedAmount: 1000,
+        bridgeIsWarp: true,
+        override: {
+          chain2: {
+            bridgeMinAcceptedAmount: 5000,
+          },
+        },
+      },
+      chain2: {
+        bridge: '0x0987654321098765432109876543210987654321',
+        bridgeMinAcceptedAmount: 2000,
+        bridgeIsWarp: true,
+      },
+    };
+
+    const result = getBridgeConfig(bridges, 'chain1', 'chain2', testLogger);
+
+    expect(result).to.deep.equal({
+      bridge: '0x1234567890123456789012345678901234567890',
+      bridgeMinAcceptedAmount: 5000,
+      bridgeIsWarp: true,
+    });
+  });
+
+  it('should handle overrides that change the bridge address', () => {
+    const bridges: ChainMap<BridgeConfigWithOverride> = {
+      chain1: {
+        bridge: '0x1234567890123456789012345678901234567890',
+        bridgeMinAcceptedAmount: 1000,
+        bridgeIsWarp: true,
+        override: {
+          chain2: {
+            bridge: '0xABCDEF0123456789ABCDEF0123456789ABCDEF01',
+          },
+        },
+      },
+      chain2: {
+        bridge: '0x0987654321098765432109876543210987654321',
+        bridgeMinAcceptedAmount: 2000,
+        bridgeIsWarp: true,
+      },
+    };
+
+    const result = getBridgeConfig(bridges, 'chain1', 'chain2', testLogger);
+
+    expect(result).to.deep.equal({
+      bridge: '0xABCDEF0123456789ABCDEF0123456789ABCDEF01',
+      bridgeMinAcceptedAmount: 1000,
+      bridgeIsWarp: true,
+    });
+  });
+});

package/src/utils/bridgeUtils.ts

@@ -0,0 +1,42 @@
+import { Logger } from 'pino';
+
+import type { ChainMap, ChainName } from '@hyperlane-xyz/sdk';
+
+export type BridgeConfigWithOverride = BridgeConfig & {
+  override?: ChainMap<Partial<BridgeConfig>>;
+};
+
+export type BridgeConfig = {
+  bridge: string;
+  bridgeMinAcceptedAmount: string | number;
+  bridgeIsWarp: boolean;
+};
+
+/**
+ * Gets the bridge configuration for a specific chain pair, applying any overrides
+ * @param bridges The map of bridge configurations by chain
+ * @param fromChain The source chain
+ * @param toChain The destination chain
+ * @returns The bridge configuration with any overrides applied
+ */
+export function getBridgeConfig(
+  bridges: ChainMap<BridgeConfigWithOverride>,
+  fromChain: ChainName,
+  toChain: ChainName,
+  logger: Logger,
+): BridgeConfig {
+  const fromConfig = bridges[fromChain];
+
+  if (!fromConfig) {
+    logger.error({ fromChain }, 'Bridge config not found');
+    throw new Error(`Bridge config not found for chain ${fromChain}`);
+  }
+
+  const routeSpecificOverrides = fromConfig.override?.[toChain];
+
+  // Create a new object with the properties from bridgeConfig, excluding the overrides property
+  const { override: _, ...baseConfig } = fromConfig;
+
+  // Return a new object with the base config and any overrides
+  return { ...baseConfig, ...routeSpecificOverrides };
+}

package/src/utils/errors.ts

@@ -0,0 +1,5 @@
+export class WrappedError extends Error {
+  constructor(message: string, cause?: Error) {
+    super(message, cause ? { cause } : undefined);
+  }
+}

package/src/utils/files.ts

@@ -0,0 +1,276 @@
+import { input } from '@inquirer/prompts';
+import select from '@inquirer/select';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import {
+  DocumentOptions,
+  LineCounter,
+  ParseOptions,
+  SchemaOptions,
+  ToJSOptions,
+  parse,
+  stringify as yamlStringify,
+} from 'yaml';
+
+import { objMerge, rootLogger } from '@hyperlane-xyz/utils';
+
+const yamlParse = (
+  content: string,
+  options?: ParseOptions & DocumentOptions & SchemaOptions & ToJSOptions,
+) =>
+  // See stackoverflow.com/questions/63075256/why-does-the-npm-yaml-library-have-a-max-alias-number
+  parse(content, { maxAliasCount: -1, ...options });
+
+export const MAX_READ_LINE_OUTPUT = 250;
+
+export type FileFormat = 'yaml' | 'json';
+
+export type ArtifactsFile = {
+  filename: string;
+  description: string;
+};
+
+export function removeEndingSlash(dirPath: string): string {
+  if (dirPath.endsWith('/')) {
+    return dirPath.slice(0, -1);
+  }
+  return dirPath;
+}
+
+export function resolvePath(filePath: string): string {
+  if (filePath.startsWith('~')) {
+    const homedir = os.homedir();
+    return path.join(homedir, filePath.slice(1));
+  }
+  return filePath;
+}
+
+export function isFile(filepath: string): boolean {
+  if (!filepath) return false;
+  try {
+    return fs.existsSync(filepath) && fs.lstatSync(filepath).isFile();
+  } catch {
+    rootLogger.warn(`Error checking for file: ${filepath}`);
+    return false;
+  }
+}
+
+export function isDirectory(dirpath: string): boolean {
+  if (!dirpath) return false;
+  try {
+    return fs.existsSync(dirpath) && fs.lstatSync(dirpath).isDirectory();
+  } catch {
+    rootLogger.warn(`Error checking for directory: ${dirpath}`);
+    return false;
+  }
+}
+
+export function readFileAtPath(filepath: string): string {
+  if (!isFile(filepath)) {
+    throw Error(`File doesn't exist at ${filepath}`);
+  }
+  return fs.readFileSync(filepath, 'utf8');
+}
+
+export function writeFileAtPath(filepath: string, value: string): void {
+  const dirname = path.dirname(filepath);
+  if (!isDirectory(dirname)) {
+    fs.mkdirSync(dirname, { recursive: true });
+  }
+  fs.writeFileSync(filepath, value);
+}
+
+export function readJson<T>(filepath: string): T {
+  return JSON.parse(readFileAtPath(filepath)) as T;
+}
+
+export function tryReadJson<T>(filepath: string): T | null {
+  try {
+    return readJson(filepath) as T;
+  } catch {
+    return null;
+  }
+}
+
+export function writeJson(filepath: string, obj: any) {
+  writeFileAtPath(filepath, JSON.stringify(obj, null, 2) + '\n');
+}
+
+export function mergeJson<T extends Record<string, any>>(
+  filepath: string,
+  obj: T,
+) {
+  if (isFile(filepath)) {
+    const previous = readJson<T>(filepath);
+    writeJson(filepath, objMerge(previous, obj));
+  } else {
+    writeJson(filepath, obj);
+  }
+}
+
+export function readYaml<T>(filepath: string): T {
+  return yamlParse(readFileAtPath(filepath)) as T;
+}
+
+export function tryReadYamlAtPath<T>(filepath: string): T | null {
+  try {
+    return readYaml(filepath);
+  } catch {
+    return null;
+  }
+}
+
+export function writeYaml(filepath: string, obj: any) {
+  writeFileAtPath(
+    filepath,
+    yamlStringify(obj, { indent: 2, sortMapEntries: true }) + '\n',
+  );
+}
+
+export function mergeYaml<T extends Record<string, any>>(
+  filepath: string,
+  obj: T,
+) {
+  if (isFile(filepath)) {
+    const previous = readYaml<T>(filepath);
+    writeYaml(filepath, objMerge(previous, obj));
+  } else {
+    writeYaml(filepath, obj);
+  }
+}
+
+export function readYamlOrJson<T>(filepath: string, format?: FileFormat): T {
+  return resolveYamlOrJsonFn(filepath, readJson, readYaml, format);
+}
+
+export function writeYamlOrJson(
+  filepath: string,
+  obj: Record<string, any>,
+  format?: FileFormat,
+) {
+  return resolveYamlOrJsonFn(
+    filepath,
+    (f: string) => writeJson(f, obj),
+    (f: string) => writeYaml(f, obj),
+    format,
+  );
+}
+
+export function mergeYamlOrJson(
+  filepath: string,
+  obj: Record<string, any>,
+  format: FileFormat = 'yaml',
+) {
+  return resolveYamlOrJsonFn(
+    filepath,
+    (f: string) => mergeJson(f, obj),
+    (f: string) => mergeYaml(f, obj),
+    format,
+  );
+}
+
+function resolveYamlOrJsonFn(
+  filepath: string,
+  jsonFn: any,
+  yamlFn: any,
+  format?: FileFormat,
+) {
+  const fileFormat = resolveFileFormat(filepath, format);
+  if (!fileFormat) {
+    throw new Error(`Invalid file format for ${filepath}`);
+  }
+
+  if (fileFormat === 'json') {
+    return jsonFn(filepath);
+  }
+
+  return yamlFn(filepath);
+}
+
+export function resolveFileFormat(
+  filepath?: string,
+  format?: FileFormat,
+): FileFormat | undefined {
+  // early out if filepath is undefined
+  if (!filepath) {
+    return format;
+  }
+
+  if (format === 'json' || filepath?.endsWith('.json')) {
+    return 'json';
+  }
+
+  if (
+    format === 'yaml' ||
+    filepath?.endsWith('.yaml') ||
+    filepath?.endsWith('.yml')
+  ) {
+    return 'yaml';
+  }
+
+  return undefined;
+}
+
+export async function runFileSelectionStep(
+  folderPath: string,
+  description: string,
+  pattern?: string,
+) {
+  const noFilesErrorMessage = `No "${description}" found in ${folderPath}. Please confirm the path for "${description}". By default, the CLI writes to folders relative to where its run.`;
+  if (!fs.existsSync(folderPath)) throw new Error(noFilesErrorMessage);
+
+  let filenames = fs.readdirSync(folderPath);
+  if (pattern) {
+    filenames = filenames.filter((f) => f.includes(pattern));
+  }
+
+  if (filenames.length === 0) throw new Error(noFilesErrorMessage);
+
+  let filename = (await select({
+    message: `Select ${description} file`,
+    choices: [
+      ...filenames.map((f) => ({ name: f, value: f })),
+      { name: '(Other file)', value: null },
+    ],
+    pageSize: 20,
+  })) as string;
+
+  if (filename) return path.join(folderPath, filename);
+
+  filename = await input({
+    message: `Enter ${description} filepath`,
+  });
+
+  if (filename) return filename;
+  else throw new Error(`No filepath entered ${description}`);
+}
+
+export function indentYamlOrJson(str: string, indentLevel: number): string {
+  const indent = ' '.repeat(indentLevel);
+  return str
+    .split('\n')
+    .map((line) => indent + line)
+    .join('\n');
+}
+
+/**
+ * Logs the YAML representation of an object if the number of lines is less than the specified maximum.
+ *
+ * @param obj - The object to be converted to YAML.
+ * @param maxLines - The maximum number of lines allowed for the YAML representation.
+ * @param margin - The number of spaces to use for indentation (default is 2).
+ */
+export function logYamlIfUnderMaxLines(
+  obj: any,
+  maxLines: number = MAX_READ_LINE_OUTPUT,
+  margin: number = 2,
+): void {
+  const asYamlString = yamlStringify(obj, null, margin);
+  const lineCounter = new LineCounter();
+  yamlParse(asYamlString, { lineCounter });
+
+  if (lineCounter.lineStarts.length < maxLines) {
+    rootLogger.info(asYamlString);
+  }
+}

package/src/utils/generalUtils.ts

@@ -0,0 +1,13 @@
+import { Logger } from 'pino';
+
+export async function tryFn(
+  fn: () => Promise<void>,
+  context: string,
+  logger: Logger,
+) {
+  try {
+    await fn();
+  } catch (error) {
+    logger.error({ context, err: error as Error }, `Error in ${context}`);
+  }
+}

package/src/utils/index.ts

@@ -0,0 +1,4 @@
+export * from './balanceUtils.js';
+export * from './bridgeUtils.js';
+export * from './generalUtils.js';
+export * from './tokenUtils.js';

package/src/utils/tokenUtils.ts

@@ -0,0 +1,26 @@
+import { Token, TokenStandard } from '@hyperlane-xyz/sdk';
+
+const REBALANCEABLE_TOKEN_COLLATERALIZED_STANDARDS = new Set<TokenStandard>([
+  TokenStandard.EvmHypCollateral,
+  TokenStandard.EvmHypNative,
+]);
+
+/**
+ * @dev This function exists because the rebalancer currently only supports a subset of collateralized token standards
+ *   (see `REBALANCEABLE_TOKEN_COLLATERALIZED_STANDARDS` vs. all possible `TOKEN_COLLATERALIZED_STANDARDS`).
+ *
+ * @deprecated This function is conditionally deprecated. It is intended for removal once the rebalancer
+ *   achieves full support for all collateralized token standards.
+ *   After this condition is met and this function is removed, please use `token.isCollateralized()` as the alternative.
+ *
+ * @param token - The token to be checked for rebalancing eligibility.
+ * @returns `true` if the token is of a collateralized standard currently supported by the rebalancer, `false` otherwise.
+ */
+export function isCollateralizedTokenEligibleForRebalancing(
+  token: Token,
+): boolean {
+  return (
+    token.isCollateralized() &&
+    REBALANCEABLE_TOKEN_COLLATERALIZED_STANDARDS.has(token.standard)
+  );
+}