feat(relayFeeCalculator): add support for origin chain config override (#1021)

Signed-off-by: Gerhard Steenkamp <gerhard@umaproject.org>

Author: gsteenkamp89

src/relayFeeCalculator/relayFeeCalculator.ts

@@ -50,6 +50,7 @@ export interface CapitalCostConfigOverride {
   default: CapitalCostConfig;
   routeOverrides?: Record<ChainIdAsString, Record<ChainIdAsString, CapitalCostConfig>>;
   destinationChainOverrides?: Record<ChainIdAsString, CapitalCostConfig>;
+  originChainOverrides?: Record<ChainIdAsString, CapitalCostConfig>;
 }
 export type RelayCapitalCostConfig = CapitalCostConfigOverride | CapitalCostConfig;
 export interface BaseRelayFeeCalculatorConfig {
@@ -155,6 +156,8 @@ export class RelayFeeCalculator {
     );
     assert(Object.keys(this.capitalCostsConfig).length > 0, "capitalCostsConfig must have at least one entry");
     this.logger = logger || DEFAULT_LOGGER;
+    // warn developer of any possible conflicting config overrides
+    this.checkAllConfigConflicts();
   }
 
   /**
@@ -194,8 +197,11 @@ export class RelayFeeCalculator {
     for (const toChainIdRoutes of Object.values(config.routeOverrides || {})) {
       Object.values(toChainIdRoutes).forEach(this.validateCapitalCostsConfig);
     }
+    // Validate origin chain overrides
+    Object.values(config.originChainOverrides || {}).forEach(this.validateCapitalCostsConfig);
     // Validate destination chain overrides
     Object.values(config.destinationChainOverrides || {}).forEach(this.validateCapitalCostsConfig);
+
     return config;
   }
 
@@ -326,9 +332,26 @@ export class RelayFeeCalculator {
     // bound to an upper bound. After the kink, the fee % increase will be fixed, and slowly approach the upper bound
     // for very large amount inputs.
     else {
-      const destinationChainOverride = tokenCostConfig?.destinationChainOverrides?.[_destinationRoute || ""];
+      // Order of specificity (most specific to least specific):
+      // 1. Route overrides (both origin and destination)
+      // 2. Destination chain overrides
+      // 3. Origin chain overrides
+      // 4. Default config
       const routeOverride = tokenCostConfig?.routeOverrides?.[_originRoute || ""]?.[_destinationRoute || ""];
-      const config: CapitalCostConfig = routeOverride ?? destinationChainOverride ?? tokenCostConfig.default;
+      const destinationChainOverride = tokenCostConfig?.destinationChainOverrides?.[_destinationRoute || ""];
+      const originChainOverride = tokenCostConfig?.originChainOverrides?.[_originRoute || ""];
+      const config: CapitalCostConfig =
+        routeOverride ?? destinationChainOverride ?? originChainOverride ?? tokenCostConfig.default;
+
+      // Check and log warnings for configuration conflicts
+      this.warnIfConfigConflicts(
+        _tokenSymbol,
+        _originRoute || "",
+        _destinationRoute || "",
+        routeOverride,
+        destinationChainOverride,
+        originChainOverride
+      );
 
       // Scale amount "y" to 18 decimals.
       const y = toBN(_amountToRelay).mul(toBNWei("1", 18 - config.decimals));
@@ -356,6 +379,88 @@ export class RelayFeeCalculator {
     }
   }
 
+  /**
+   * Checks for configuration conflicts across all token symbols and their associated chain configurations.
+   * This method examines the capital costs configuration for each token and identifies any overlapping
+   * or conflicting configurations between route overrides, destination chain overrides, and origin chain overrides.
+   * If conflicts are found, warnings will be logged via the warnIfConfigConflicts method.
+   */
+  private checkAllConfigConflicts(): void {
+    for (const [tokenSymbol, tokenConfig] of Object.entries(this.capitalCostsConfig)) {
+      // Get all origin chains that have specific configurations
+      const originChains = new Set<string>(Object.keys(tokenConfig.originChainOverrides || {}));
+      // Get all destination chains that have specific configurations
+      const destChains = new Set<string>(Object.keys(tokenConfig.destinationChainOverrides || {}));
+
+      // Add all chains from route overrides
+      if (tokenConfig.routeOverrides) {
+        Object.keys(tokenConfig.routeOverrides).forEach((originChain) => {
+          originChains.add(originChain);
+          Object.keys(tokenConfig.routeOverrides![originChain]).forEach((destChain) => {
+            destChains.add(destChain);
+          });
+        });
+      }
+
+      // If there are no specific chain configurations, just check the default case
+      if (originChains.size === 0 && destChains.size === 0) {
+        continue;
+      }
+
+      // Check for conflicts between all combinations of origin and destination chains
+      for (const originChain of Array.from(originChains)) {
+        for (const destChain of Array.from(destChains)) {
+          const routeOverride = tokenConfig.routeOverrides?.[originChain]?.[destChain];
+          const destinationChainOverride = tokenConfig.destinationChainOverrides?.[destChain];
+          const originChainOverride = tokenConfig.originChainOverrides?.[originChain];
+
+          this.warnIfConfigConflicts(
+            tokenSymbol,
+            originChain,
+            destChain,
+            routeOverride,
+            destinationChainOverride,
+            originChainOverride
+          );
+        }
+      }
+    }
+  }
+
+  /**
+   * Log a warning if multiple configuration types apply to the same route
+   * @private
+   */
+  private warnIfConfigConflicts(
+    tokenSymbol: string,
+    originChain: string,
+    destChain: string,
+    routeOverride?: CapitalCostConfig,
+    destinationChainOverride?: CapitalCostConfig,
+    originChainOverride?: CapitalCostConfig
+  ): void {
+    const overrideCount = [routeOverride, destinationChainOverride, originChainOverride].filter(Boolean).length;
+
+    if (overrideCount > 1) {
+      const configUsed = routeOverride
+        ? "route override"
+        : destinationChainOverride
+        ? "destination chain override"
+        : originChainOverride
+        ? "origin chain override"
+        : "default override";
+
+      this.logger.warn({
+        at: "RelayFeeCalculator",
+        message: `Multiple configurations found for token ${tokenSymbol} from chain ${originChain} to chain ${destChain}`,
+        configUsed,
+        routeOverride,
+        destinationChainOverride,
+        originChainOverride,
+      });
+    }
+  }
+
   /**
    * Retrieves the relayer fee details for a deposit.
    * @param deposit A valid deposit object to reason about

test/relayFeeCalculator.test.ts

@@ -293,6 +293,14 @@ describe("RelayFeeCalculator", () => {
           cutoff: toBNWei("15").toString(),
           decimals: token.decimals,
         },
+        originChainOverrides: {
+          [CHAIN_IDs.MAINNET]: {
+            lowerBound: toBNWei("0.0004").toString(),
+            upperBound: toBNWei("0.005").toString(),
+            cutoff: toBNWei("12").toString(),
+            decimals: token.decimals,
+          },
+        },
         destinationChainOverrides: {
           // Override for destination chain ARBITRUM
           [CHAIN_IDs.ARBITRUM]: {
@@ -323,14 +331,30 @@ describe("RelayFeeCalculator", () => {
 
     // Get config values for cleaner assertions
     const defaultConfig = customCapitalCostsConfig[token.symbol].default;
-    const chainOverride = customCapitalCostsConfig[token.symbol].destinationChainOverrides[CHAIN_IDs.ARBITRUM];
+    const originChainOverride = customCapitalCostsConfig[token.symbol].originChainOverrides[CHAIN_IDs.MAINNET];
+    const destChainOverride = customCapitalCostsConfig[token.symbol].destinationChainOverrides[CHAIN_IDs.ARBITRUM];
     const routeOverride = customCapitalCostsConfig[token.symbol].routeOverrides[CHAIN_IDs.MAINNET][CHAIN_IDs.ARBITRUM];
 
     // Test using default config (no routes specified)
     const defaultFee = client.capitalFeePercent(toBNWei("1", token.decimals), token.symbol);
     assert.ok(toBN(defaultFee).gte(toBN(defaultConfig.lowerBound)), "Default fee should be at least the lower bound");
     assert.ok(toBN(defaultFee).lt(toBN(defaultConfig.upperBound)), "Default fee should be less than the upper bound");
 
+    // Test using origin chain override only
+    const originFee = client.capitalFeePercent(
+      toBNWei("1", token.decimals),
+      token.symbol,
+      CHAIN_IDs.MAINNET.toString()
+    );
+    assert.ok(
+      toBN(originFee).gte(toBN(originChainOverride.lowerBound)),
+      "Origin override fee should be at least its lower bound"
+    );
+    assert.ok(
+      toBN(originFee).lt(toBN(originChainOverride.upperBound)),
+      "Origin override fee should be less than its upper bound"
+    );
+
     // Test using destination chain override (only destination specified)
     const destinationFee = client.capitalFeePercent(
       toBNWei("1", token.decimals),
@@ -339,11 +363,11 @@ describe("RelayFeeCalculator", () => {
       CHAIN_IDs.ARBITRUM.toString()
     );
     assert.ok(
-      toBN(destinationFee).gte(toBN(chainOverride.lowerBound)),
+      toBN(destinationFee).gte(toBN(destChainOverride.lowerBound)),
       "Destination override fee should be at least its lower bound"
     );
     assert.ok(
-      toBN(destinationFee).lt(toBN(chainOverride.upperBound)),
+      toBN(destinationFee).lt(toBN(destChainOverride.upperBound)),
       "Destination override fee should be less than its upper bound"
     );
 
@@ -363,20 +387,51 @@ describe("RelayFeeCalculator", () => {
       "Route override fee should be less than its upper bound"
     );
 
-    // Test fallback to destination chain override when a route is not specifically overridden
-    const fallbackToDestFee = client.capitalFeePercent(
+    // Test priority order: when both origin and destination chain are specified but no route override exists,
+    // destination chain override should take priority over origin chain override
+    const destOverOriginFee = client.capitalFeePercent(
       toBNWei("1", token.decimals),
       token.symbol,
       CHAIN_IDs.OPTIMISM.toString(),
       CHAIN_IDs.ARBITRUM.toString()
     );
     assert.ok(
-      toBN(fallbackToDestFee).gte(toBN(chainOverride.lowerBound)),
-      "Fallback to destination fee should be at least the destination lower bound"
+      toBN(destOverOriginFee).gte(toBN(destChainOverride.lowerBound)),
+      "Destination should take priority over origin - fee should match destination lower bound"
+    );
+    assert.ok(
+      toBN(destOverOriginFee).lt(toBN(destChainOverride.upperBound)),
+      "Destination should take priority over origin - fee should match destination upper bound"
+    );
+
+    // Test priority order: route override takes priority over both origin and destination chain overrides
+    const routeOverBothFee = client.capitalFeePercent(
+      toBNWei("1", token.decimals),
+      token.symbol,
+      CHAIN_IDs.MAINNET.toString(),
+      CHAIN_IDs.ARBITRUM.toString()
+    );
+    assert.ok(
+      toBN(routeOverBothFee).gte(toBN(routeOverride.lowerBound)),
+      "Route should take priority over both origin and destination - fee should match route lower bound"
     );
     assert.ok(
-      toBN(fallbackToDestFee).lt(toBN(chainOverride.upperBound)),
-      "Fallback to destination fee should be less than the destination upper bound"
+      toBN(routeOverBothFee).lt(toBN(routeOverride.upperBound)),
+      "Route should take priority over both origin and destination - fee should match route upper bound"
+    );
+
+    // Verify that route override != origin override
+    assert.notEqual(
+      routeOverBothFee.toString(),
+      originFee.toString(),
+      "Route override fee should be different from origin override fee"
+    );
+
+    // Verify that route override != destination override
+    assert.notEqual(
+      routeOverBothFee.toString(),
+      destinationFee.toString(),
+      "Route override fee should be different from destination override fee"
     );
 
     // Test fallback to default when route doesn't match and no destination chain override exists