feat(InventoryClient): Support 1:many HubPool mappings

src/clients/InventoryClient.ts

@@ -25,7 +25,8 @@ import {
 } from "../utils";
 import { HubPoolClient, TokenClient, BundleDataClient } from ".";
 import { AdapterManager, CrossChainTransferClient } from "./bridges";
-import { InventoryConfig, V3Deposit } from "../interfaces";
+import { V3Deposit } from "../interfaces";
+import { InventoryConfig, isAliasConfig, TokenInventoryConfig } from "../interfaces/InventoryManagement";
 import lodash from "lodash";
 import { CONTRACT_ADDRESSES, SLOW_WITHDRAWAL_CHAINS } from "../common";
 import { CombinedRefunds } from "../dataworker/DataworkerUtils";
@@ -71,6 +72,21 @@ export class InventoryClient {
     this.formatWei = createFormatFunction(2, 4, false, 18);
   }
 
+  getTokenConfig(hubPoolToken: string, chainId: number, spokePoolToken?: string): TokenInventoryConfig | undefined {
+    const tokenConfig = this.inventoryConfig.tokenConfig[hubPoolToken];
+    assert(isDefined(tokenConfig), `getTokenConfig: No token config found for ${hubPoolToken}.`);
+
+    if (isAliasConfig(tokenConfig)) {
+      assert(
+        isDefined(spokePoolToken),
+        `Cannot resolve ambiguous ${getNetworkName(chainId)} token config for ${hubPoolToken}`
+      );
+      return tokenConfig[spokePoolToken]?.[chainId];
+    } else {
+      return tokenConfig[chainId];
+    }
+  }
+
   // Get the total balance across all chains, considering any outstanding cross chain transfers as a virtual balance on that chain.
   getCumulativeBalance(l1Token: string): BigNumber {
     return this.getEnabledChains()
@@ -86,17 +102,31 @@ export class InventoryClient {
       return bnZero;
     }
 
+    const balances = this.getDestinationTokensForL1Token(l1Token, chainId).map(
+      (token) => this.tokenClient.getBalance(Number(chainId), token) || bnZero
+    );
+
     // If the chain does not have this token (EG BOBA on Optimism) then 0.
-    const balance =
-      this.tokenClient.getBalance(chainId, this.getDestinationTokenForL1Token(l1Token, chainId)) || bnZero;
+    const balance = balances.reduce((acc, curr) => acc.add(curr), bnZero);
 
     // Consider any L1->L2 transfers that are currently pending in the canonical bridge.
     return balance.add(
       this.crossChainTransferClient.getOutstandingCrossChainTransferAmount(this.relayer, chainId, l1Token)
     );
   }
 
-  // Get the fraction of funds allocated on each chain.
+  // @note: l1Token is current needed because not all l2 tokens (USDC.e, USDbC, ...) map back to an L1 token.
+  getBalanceOnChain(chainId: number, l1Token: string, l2Token?: string): BigNumber {
+    l2Token ??= this.hubPoolClient.getL2TokenForL1TokenAtBlock(l1Token, chainId);
+    const balance = this.tokenClient.getBalance(chainId, l2Token);
+
+    // @todo: This will resolve all outstanding transfers for the L1 token, but it should be filtered for _only_
+    // transfers that apply to the specific L2 token. This needs to be fixed in the crossChainTransferClient
+    return balance.add(
+      this.crossChainTransferClient.getOutstandingCrossChainTransferAmount(this.relayer, chainId, l1Token)
+    );
+  }
+
   getChainDistribution(l1Token: string): { [chainId: number]: TokenDistribution } {
     const cumulativeBalance = this.getCumulativeBalance(l1Token);
     const distribution: { [chainId: number]: TokenDistribution } = {};
@@ -105,13 +135,18 @@ export class InventoryClient {
       // If token doesn't have entry on chain, skip creating an entry for it since we'll likely run into an error
       // later trying to grab the chain equivalent of the L1 token via the HubPoolClient.
       if (chainId === this.hubPoolClient.chainId || this._l1TokenEnabledForChain(l1Token, chainId)) {
-        const l2Token = this.getDestinationTokenForL1Token(l1Token, chainId);
-        if (cumulativeBalance.gt(bnZero)) {
-          distribution[chainId] ??= {};
-          distribution[chainId][l2Token] = this.getBalanceOnChainForL1Token(chainId, l1Token)
-            .mul(this.scalar)
-            .div(cumulativeBalance);
+        distribution[chainId] ??= {};
+
+        if (cumulativeBalance.eq(bnZero)) {
+          return;
         }
+
+        const l2Tokens = this.getDestinationTokensForL1Token(l1Token, chainId);
+        l2Tokens.forEach((l2Token) => {
+          // THe effective balance is the current balance + inbound bridge transfers.
+          const effectiveBalance = this.getBalanceOnChain(chainId, l1Token, l2Token);
+          distribution[chainId][l2Token] = effectiveBalance.mul(this.scalar).div(cumulativeBalance);
+        });
       }
     });
     return distribution;
@@ -125,28 +160,43 @@ export class InventoryClient {
   }
 
   // Get the balance of a given token on a given chain, including shortfalls and any pending cross chain transfers.
-  getCurrentAllocationPct(l1Token: string, chainId: number): BigNumber {
+  getCurrentAllocationPct(l1Token: string, chainId: number, l2Token?: string): BigNumber {
+    l2Token ??= this.hubPoolClient.getL2TokenForL1TokenAtBlock(l1Token, chainId);
+
     // If there is nothing over all chains, return early.
     const cumulativeBalance = this.getCumulativeBalance(l1Token);
     if (cumulativeBalance.eq(bnZero)) {
       return bnZero;
     }
 
-    const shortfall = this.getTokenShortFall(l1Token, chainId);
+    const shortfall = this.tokenClient.getShortfallTotalRequirement(chainId, l2Token);
     const currentBalance = this.getBalanceOnChainForL1Token(chainId, l1Token).sub(shortfall);
+
     // Multiply by scalar to avoid rounding errors.
     return currentBalance.mul(this.scalar).div(cumulativeBalance);
   }
 
   // Find how short a given chain is for a desired L1Token.
   getTokenShortFall(l1Token: string, chainId: number): BigNumber {
-    return this.tokenClient.getShortfallTotalRequirement(chainId, this.getDestinationTokenForL1Token(l1Token, chainId));
+    return this.getDestinationTokensForL1Token(l1Token, chainId)
+      .map((token) => this.tokenClient.getShortfallTotalRequirement(chainId, token))
+      .reduce((acc, curr) => acc.add(curr), bnZero);
   }
 
-  getDestinationTokenForL1Token(l1Token: string, chainId: number | string): string {
+  getRepaymentTokenForL1Token(l1Token: string, chainId: number | string): string {
     return this.hubPoolClient.getL2TokenForL1TokenAtBlock(l1Token, Number(chainId));
   }
 
+  getDestinationTokensForL1Token(l1Token: string, chainId: number | string): string[] {
+    const tokenConfig = this.inventoryConfig.tokenConfig[l1Token];
+
+    if (isAliasConfig(tokenConfig)) {
+      return Object.keys(tokenConfig).filter((k) => isDefined(tokenConfig[k][chainId]));
+    }
+
+    return [this.getRepaymentTokenForL1Token(l1Token, chainId)];
+  }
+
   getEnabledChains(): number[] {
     return this.chainIdList;
   }
@@ -209,7 +259,7 @@ export class InventoryClient {
     // Increase virtual balance by pending relayer refunds from the latest valid bundle and the
     // upcoming bundle. We can assume that all refunds from the second latest valid bundle have already
     // been executed.
-    let startTimer;
+    let startTimer: number;
     if (!isDefined(this.bundleRefundsPromise)) {
       startTimer = performance.now();
       // @dev Save this as a promise so that other parallel calls to this function don't make the same call.
@@ -219,9 +269,9 @@ export class InventoryClient {
     const totalRefundsPerChain = this.getEnabledChains().reduce(
       (refunds: { [chainId: string]: BigNumber }, chainId) => {
         if (!this.hubPoolClient.l2TokenEnabledForL1Token(l1Token, chainId)) {
-          refunds[chainId] = toBN(0);
+          refunds[chainId] = bnZero;
         } else {
-          const destinationToken = this.getDestinationTokenForL1Token(l1Token, chainId);
+          const destinationToken = this.getRepaymentTokenForL1Token(l1Token, chainId);
           refunds[chainId] = this.bundleDataClient.getTotalRefund(
             refundsToConsider,
             this.relayer,
@@ -329,8 +379,8 @@ export class InventoryClient {
           ` (${inputToken} != ${outputToken})`
       );
     }
+
     l1Token ??= this.hubPoolClient.getL1TokenForL2TokenAtBlock(inputToken, originChainId);
-    const tokenConfig = this.inventoryConfig?.tokenConfig?.[l1Token];
 
     // Consider any refunds from executed and to-be executed bundles. If bundle data client doesn't return in
     // time, return an object with zero refunds for all chains.
@@ -386,8 +436,8 @@ export class InventoryClient {
     for (const _chain of chainsToEvaluate) {
       assert(this._l1TokenEnabledForChain(l1Token, _chain), `Token ${l1Token} not enabled for chain ${_chain}`);
       // Destination chain:
-      const chainShortfall = this.getTokenShortFall(l1Token, _chain);
-      const chainVirtualBalance = this.getBalanceOnChainForL1Token(_chain, l1Token);
+      const chainShortfall = this.tokenClient.getShortfallTotalRequirement(_chain, outputToken);
+      const chainVirtualBalance = this.getBalanceOnChain(_chain, l1Token, outputToken);
       const chainVirtualBalanceWithShortfall = chainVirtualBalance.sub(chainShortfall);
       let cumulativeVirtualBalanceWithShortfall = cumulativeVirtualBalance.sub(chainShortfall);
       // @dev No need to factor in outputAmount when computing origin chain balance since funds only leave relayer
@@ -416,8 +466,10 @@ export class InventoryClient {
         .div(cumulativeVirtualBalanceWithShortfallPostRelay);
 
       // Consider configured buffer for target to allow relayer to support slight overages.
-      const thresholdPct = toBN(this.inventoryConfig.tokenConfig[l1Token][_chain].targetPct)
-        .mul(tokenConfig[_chain].targetOverageBuffer ?? toBNWei("1"))
+      const tokenConfig = this.getTokenConfig(l1Token, destinationChainId, outputToken);
+      assert(isDefined(tokenConfig), `No tokenConfig for ${l1Token} on ${_chain}.`);
+      const thresholdPct = toBN(tokenConfig.targetPct)
+        .mul(tokenConfig.targetOverageBuffer ?? toBNWei("1"))
         .div(fixedPointAdjustment);
       this.log(
         `Evaluated taking repayment on ${
@@ -487,12 +539,13 @@ export class InventoryClient {
         } else {
           runningBalanceForToken = leaf.runningBalances[l1TokenIndex];
         }
+
         // Approximate latest running balance as last known proposed running balance...
         // - minus total deposit amount on chain since the latest end block proposed
         // - plus total refund amount on chain since the latest end block proposed
         const upcomingDeposits = this.bundleDataClient.getUpcomingDepositAmount(
           chainId,
-          this.getDestinationTokenForL1Token(l1Token, chainId),
+          this.getRepaymentTokenForL1Token(l1Token, chainId),
           blockRange[1]
         );
         // Grab refunds that are not included in any bundle proposed on-chain. These are refunds that have not
@@ -502,7 +555,7 @@ export class InventoryClient {
         // If a chain didn't exist in the last bundle or a spoke pool client isn't defined, then
         // one of the refund entries for a chain can be undefined.
         const upcomingRefundForChain = Object.values(
-          upcomingRefunds?.[chainId]?.[this.getDestinationTokenForL1Token(l1Token, chainId)] ?? {}
+          upcomingRefunds?.[chainId]?.[this.getRepaymentTokenForL1Token(l1Token, chainId)] ?? {}
         ).reduce((acc, curr) => acc.add(curr), bnZero);
 
         // Updated running balance is last known running balance minus deposits plus upcoming refunds.
@@ -607,29 +660,34 @@ export class InventoryClient {
   }
 
   getPossibleRebalances(): Rebalance[] {
+    const chainIds = this.getEnabledChains();
     const rebalancesRequired: Rebalance[] = [];
 
-    // First, compute the rebalances that we would do assuming we have sufficient tokens on L1.
     for (const l1Token of this.getL1Tokens()) {
       const cumulativeBalance = this.getCumulativeBalance(l1Token);
       if (cumulativeBalance.eq(bnZero)) {
-        continue;
+        return;
       }
 
-      for (const chainId of this.getEnabledL2Chains()) {
-        // Skip if there's no configuration for l1Token on chainId. This is the case for BOBA and BADGER
-        // as they're not present on all L2s.
+      chainIds.forEach((chainId) => {
+        // Skip if there's no configuration for l1Token on chainId.
         if (!this._l1TokenEnabledForChain(l1Token, chainId)) {
-          continue;
+          return;
         }
 
-        const currentAllocPct = this.getCurrentAllocationPct(l1Token, chainId);
-        const { thresholdPct, targetPct } = this.inventoryConfig.tokenConfig[l1Token][chainId];
-        if (currentAllocPct.lt(thresholdPct)) {
+        const l2Tokens = this.getDestinationTokensForL1Token(l1Token, chainId);
+        l2Tokens.forEach((l2Token) => {
+          const currentAllocPct = this.getCurrentAllocationPct(l1Token, chainId, l2Token);
+          const tokenConfig = this.getTokenConfig(l1Token, chainId, l2Token);
+          const { thresholdPct, targetPct } = tokenConfig;
+
+          if (currentAllocPct.gte(thresholdPct)) {
+            return;
+          }
+
           const deltaPct = targetPct.sub(currentAllocPct);
           const amount = deltaPct.mul(cumulativeBalance).div(this.scalar);
           const balance = this.tokenClient.getBalance(this.hubPoolClient.chainId, l1Token);
-          const l2Token = this.getDestinationTokenForL1Token(l1Token, chainId);
           rebalancesRequired.push({
             chainId,
             l1Token,
@@ -641,9 +699,10 @@ export class InventoryClient {
             cumulativeBalance,
             amount,
           });
-        }
-      }
+        });
+      });
     }
+
     return rebalancesRequired;
   }
 
@@ -670,7 +729,6 @@ export class InventoryClient {
       }
 
       // Next, evaluate if we have enough tokens on L1 to actually do these rebalances.
-
       for (const rebalance of rebalancesRequired) {
         const { balance, amount, l1Token, chainId } = rebalance;
 
@@ -797,6 +855,10 @@ export class InventoryClient {
   }
 
   async unwrapWeth(): Promise<void> {
+    if (!this.isInventoryManagementEnabled()) {
+      return;
+    }
+
     // Note: these types are just used inside this method, so they are declared in-line.
     type ChainInfo = {
       chainId: number;
@@ -813,16 +875,14 @@ export class InventoryClient {
     const executedTransactions: ExecutedUnwrap[] = [];
 
     try {
-      if (!this.isInventoryManagementEnabled()) {
-        return;
-      }
       const l1Weth = TOKEN_SYMBOLS_MAP.WETH.addresses[this.hubPoolClient.chainId];
       const chains = await Promise.all(
         this.getEnabledChains()
           .map((chainId) => {
-            const unwrapWethThreshold =
-              this.inventoryConfig.tokenConfig?.[l1Weth]?.[chainId.toString()]?.unwrapWethThreshold;
-            const unwrapWethTarget = this.inventoryConfig.tokenConfig?.[l1Weth]?.[chainId.toString()]?.unwrapWethTarget;
+            const tokenConfig = this.getTokenConfig(l1Weth, chainId);
+            assert(isDefined(tokenConfig));
+
+            const { unwrapWethThreshold, unwrapWethTarget } = tokenConfig;
 
             // Ignore chains where ETH isn't the native gas token. Returning null will result in these being filtered.
             if (chainId === CHAIN_IDs.POLYGON || unwrapWethThreshold === undefined || unwrapWethTarget === undefined) {
@@ -1029,7 +1089,18 @@ export class InventoryClient {
   }
 
   _l1TokenEnabledForChain(l1Token: string, chainId: number): boolean {
-    return this.inventoryConfig.tokenConfig?.[l1Token]?.[String(chainId)] !== undefined;
+    const tokenConfig = this.inventoryConfig?.tokenConfig?.[l1Token];
+    if (!isDefined(tokenConfig)) {
+      return false;
+    }
+
+    // If tokenConfig directly references chainId, token is enabled.
+    if (!isAliasConfig(tokenConfig) && isDefined(tokenConfig[chainId])) {
+      return true;
+    }
+
+    // If any of the mapped symbols reference chainId, token is enabled.
+    return Object.keys(tokenConfig).some((symbol) => isDefined(tokenConfig[symbol][chainId]));
   }
 
   /**

src/interfaces/InventoryManagement.ts

@@ -1,20 +1,27 @@
-import { BigNumber } from "ethers";
+import { BigNumber, utils as ethersUtils } from "ethers";
+import { TOKEN_SYMBOLS_MAP } from "../utils";
+
+export type TokenInventoryConfig = {
+  targetOverageBuffer: BigNumber; // Max multiplier for targetPct, to give flexibility in repayment chain selection.
+  targetPct: BigNumber; // The desired amount of the given token on the L2 chainId.
+  thresholdPct: BigNumber; // Threshold, below which, we will execute a rebalance.
+  unwrapWethThreshold?: BigNumber; // Threshold for ETH to trigger WETH unwrapping to maintain ETH balance.
+  unwrapWethTarget?: BigNumber; // Amount of WETH to unwrap to refill ETH. Unused if unwrapWethThreshold is undefined.
+};
+
+export type ChainTokenConfig = {
+  [chainId: string]: TokenInventoryConfig;
+};
+
+// AliasConfig permits a single HubPool token to map onto multiple tokens on a remote chain.
+export type ChainTokenInventory = {
+  [symbol: string]: ChainTokenConfig;
+};
 
 export interface InventoryConfig {
-  tokenConfig: {
-    [l1Token: string]: {
-      [chainId: string]: {
-        targetOverageBuffer: BigNumber; // The relayer will be allowed to hold this multiple times the targetPct
-        // of the full token balance on this chain.
-        targetPct: BigNumber; // The desired amount of the given token on the L2 chainId.
-        thresholdPct: BigNumber; // Threshold, below which, we will execute a rebalance.
-        unwrapWethThreshold?: BigNumber; // Threshold for ETH on this chain to trigger WETH unwrapping to maintain
-        // ETH balance
-        unwrapWethTarget?: BigNumber; // Amount of WETH to unwrap to refill ETH balance. Unused if unwrapWethThreshold
-        // is undefined.
-      };
-    };
-  };
+  // tokenConfig can map to a single token allocation, or a set of allocations that all map to the same HubPool token.
+  tokenConfig: { [l1Token: string]: ChainTokenConfig } | { [l1Token: string]: ChainTokenInventory };
+
   // If ETH balance on chain is above threshold, wrap the excess over the target to WETH.
   wrapEtherTargetPerChain: {
     [chainId: number]: BigNumber;
@@ -25,3 +32,9 @@ export interface InventoryConfig {
   };
   wrapEtherThreshold: BigNumber;
 }
+
+export function isAliasConfig(config: ChainTokenConfig | ChainTokenInventory): config is ChainTokenInventory {
+  return (
+    Object.keys(config).every((k) => ethersUtils.isAddress(k)) || Object.keys(config).every((k) => TOKEN_SYMBOLS_MAP[k])
+  );
+}