feat(api): field outputAmount + param allowUnmatchedDecimals (#1562)

* feat(api): field `outputAmount` + param `allowUnmatchedDecimals`

There might be edge cases where the decimals for the same token do not match on different chains (USDC/USDT on BNB).
To handle these cases we add a correctly scaled `outputAmount` response field.
We also let consumers opt-in for these routes via the query param `allowUnmatchedDecimals`.

* fixup

* fixup

* add `inputToken` and `outputToken`

* Update api/_utils.ts

Co-authored-by: Gerhard Steenkamp <[email protected]>

* review requests

---------

Co-authored-by: Gerhard Steenkamp <[email protected]>

Author: dohaki

api/_utils.ts

@@ -235,6 +235,7 @@ export const validateChainAndTokenParams = (
     outputToken: string;
     originChainId: string;
     destinationChainId: string;
+    allowUnmatchedDecimals: string;
   }>
 ) => {
   let {
@@ -243,6 +244,7 @@ export const validateChainAndTokenParams = (
     outputToken: outputTokenAddress,
     originChainId,
     destinationChainId: _destinationChainId,
+    allowUnmatchedDecimals: _allowUnmatchedDecimals,
   } = queryParams;
 
   if (!_destinationChainId) {
@@ -272,6 +274,7 @@ export const validateChainAndTokenParams = (
   outputTokenAddress = outputTokenAddress
     ? _getAddressOrThrowInputError(outputTokenAddress, "outputToken")
     : undefined;
+  const allowUnmatchedDecimals = _allowUnmatchedDecimals === "true";
 
   const { l1Token, outputToken, inputToken, resolvedOriginChainId } =
     getRouteDetails(
@@ -295,12 +298,25 @@ export const validateChainAndTokenParams = (
     });
   }
 
+  if (!allowUnmatchedDecimals && inputToken.decimals !== outputToken.decimals) {
+    throw new InvalidParamError({
+      message:
+        `Decimals of input and output tokens do not match. ` +
+        `This is likely due to unmatched decimals for USDC/USDT on BNB Chain. ` +
+        `Make sure to have followed the migration guide: ` +
+        `https://docs.across.to/introduction/migration-guides/bnb-chain-migration-guide ` +
+        `and set the query param 'allowUnmatchedDecimals=true' to allow this.`,
+      param: "allowUnmatchedDecimals",
+    });
+  }
+
   return {
     l1Token,
     inputToken,
     outputToken,
     destinationChainId,
     resolvedOriginChainId,
+    allowUnmatchedDecimals,
   };
 };
 
@@ -926,7 +942,8 @@ export const getCachedLimits = async (
   amount?: string,
   recipient?: string,
   relayer?: string,
-  message?: string
+  message?: string,
+  allowUnmatchedDecimals?: boolean
 ): Promise<{
   minDeposit: string;
   maxDeposit: string;
@@ -954,6 +971,7 @@ export const getCachedLimits = async (
         message,
         recipient,
         relayer,
+        allowUnmatchedDecimals,
       },
     })
   ).data;
@@ -2057,17 +2075,21 @@ export async function fetchStakingPool(
   };
 }
 
-// Copied from @uma/common
+/**
+ * Factory function that creates a function that converts an amount from one number of decimals to another.
+ * Copied from @uma/common
+ * @param fromDecimals The number of decimals of the input amount.
+ * @param toDecimals The number of decimals of the output amount.
+ * @returns A function that converts an amount from `fromDecimals` to `toDecimals`.
+ */
 export const ConvertDecimals = (fromDecimals: number, toDecimals: number) => {
-  // amount: string, BN, number - integer amount in fromDecimals smallest unit that want to convert toDecimals
-  // returns: string with toDecimals in smallest unit
-  return (amount: BigNumber): string => {
+  return (amount: BigNumber): BigNumber => {
     amount = BigNumber.from(amount);
-    if (amount.isZero()) return amount.toString();
+    if (amount.isZero()) return amount;
     const diff = fromDecimals - toDecimals;
-    if (diff === 0) return amount.toString();
-    if (diff > 0) return amount.div(BigNumber.from("10").pow(diff)).toString();
-    return amount.mul(BigNumber.from("10").pow(-1 * diff)).toString();
+    if (diff === 0) return amount;
+    if (diff > 0) return amount.div(BigNumber.from("10").pow(diff));
+    return amount.mul(BigNumber.from("10").pow(-1 * diff));
   };
 };
 

api/limits.ts

@@ -39,6 +39,7 @@ import {
   getCachedNativeGasCost,
   getCachedOpStackL1DataFee,
   getLimitCap,
+  boolStr,
 } from "./_utils";
 import { MissingParamError } from "./_errors";
 import { getEnvs } from "./_env";
@@ -58,6 +59,7 @@ const LimitsQueryParamsSchema = type({
   message: optional(string()),
   recipient: optional(validAddress()),
   relayer: optional(validAddress()),
+  allowUnmatchedDecimals: optional(boolStr()),
 });
 
 type LimitsQueryParams = Infer<typeof LimitsQueryParamsSchema>;
@@ -124,7 +126,7 @@ const handler = async (
       );
     }
     const amount = BigNumber.from(
-      amountInput ?? ethers.BigNumber.from("10").pow(l1Token.decimals)
+      amountInput ?? ethers.BigNumber.from("10").pow(inputToken.decimals)
     );
     let minDepositUsdForDestinationChainId = Number(
       getEnvs()[`MIN_DEPOSIT_USD_${destinationChainId}`] ?? MIN_DEPOSIT_USD
@@ -200,9 +202,9 @@ const handler = async (
     const [
       opStackL1GasCost,
       multicallOutput,
-      fullRelayerBalances,
-      transferRestrictedBalances,
-      fullRelayerMainnetBalances,
+      _fullRelayerBalances,
+      _transferRestrictedBalances,
+      _fullRelayerMainnetBalances,
     ] = await Promise.all([
       nativeGasCost && sdk.utils.chainIsOPStack(destinationChainId)
         ? // Only use cached gas units if message is not defined, i.e. standard for standard bridges
@@ -261,7 +263,7 @@ const handler = async (
       relayerFeeDetails,
     });
 
-    let { liquidReserves } = multicallOutput[1];
+    const { liquidReserves: _liquidReserves } = multicallOutput[1];
     const [liteChainIdsEncoded] = multicallOutput[2];
     const liteChainIds: number[] =
       liteChainIdsEncoded === "" ? [] : JSON.parse(liteChainIdsEncoded);
@@ -271,6 +273,23 @@ const handler = async (
     const routeInvolvesLiteChain =
       originChainIsLiteChain || destinationChainIsLiteChain;
 
+    // Base every amount on the input token decimals.
+    let liquidReserves = ConvertDecimals(
+      l1Token.decimals,
+      inputToken.decimals
+    )(_liquidReserves);
+    const fullRelayerBalances = _fullRelayerBalances.map((balance) =>
+      ConvertDecimals(outputToken.decimals, inputToken.decimals)(balance)
+    );
+    const fullRelayerMainnetBalances = _fullRelayerMainnetBalances.map(
+      (balance) =>
+        ConvertDecimals(l1Token.decimals, inputToken.decimals)(balance)
+    );
+    const transferRestrictedBalances = _transferRestrictedBalances.map(
+      (balance) =>
+        ConvertDecimals(outputToken.decimals, inputToken.decimals)(balance)
+    );
+
     const transferBalances = fullRelayerBalances.map((balance, i) =>
       balance.add(fullRelayerMainnetBalances[i])
     );
@@ -283,7 +302,7 @@ const handler = async (
       : ethers.utils
           .parseUnits(
             minDepositUsdForDestinationChainId.toString(),
-            l1Token.decimals
+            inputToken.decimals
           )
           .mul(ethers.utils.parseUnits("1"))
           .div(tokenPriceUsd);
@@ -299,10 +318,14 @@ const handler = async (
     ); // balances on destination chain + mainnet
 
     if (!routeInvolvesLiteChain) {
-      const lpCushion = ethers.utils.parseUnits(
+      const _lpCushion = ethers.utils.parseUnits(
         getLpCushion(l1Token.symbol, computedOriginChainId, destinationChainId),
         l1Token.decimals
       );
+      const lpCushion = ConvertDecimals(
+        l1Token.decimals,
+        inputToken.decimals
+      )(_lpCushion);
       liquidReserves = maxBN(
         liquidReserves.sub(lpCushion),
         ethers.BigNumber.from(0)
@@ -407,8 +430,8 @@ const handler = async (
     }
 
     const limitCap = getLimitCap(
-      l1Token.symbol,
-      l1Token.decimals,
+      inputToken.symbol,
+      inputToken.decimals,
       destinationChainId
     );
 

api/suggested-fees.ts

@@ -28,6 +28,7 @@ import {
   OPT_IN_CHAINS,
   parseL1TokenConfigSafe,
   getL1TokenConfigCache,
+  ConvertDecimals,
 } from "./_utils";
 import { selectExclusiveRelayer } from "./_exclusivity";
 import {
@@ -100,6 +101,7 @@ const handler = async (
       outputToken,
       destinationChainId,
       resolvedOriginChainId: computedOriginChainId,
+      allowUnmatchedDecimals,
     } = validateChainAndTokenParams(query);
 
     relayer = relayer
@@ -224,7 +226,8 @@ const handler = async (
         // likely to hit the /limits cache using the above parameters that are not specific to this deposit.
         depositWithMessage ? recipient : undefined,
         depositWithMessage ? relayer : undefined,
-        depositWithMessage ? message : undefined
+        depositWithMessage ? message : undefined,
+        allowUnmatchedDecimals
       ),
       getFillDeadline(destinationChainId),
     ]);
@@ -279,6 +282,11 @@ const handler = async (
       relayerFeeDetails.relayFeePercent
     ).add(lpFeePct);
 
+    const outputAmount = ConvertDecimals(
+      inputToken.decimals,
+      outputToken.decimals
+    )(amount.sub(totalRelayFee));
+
     const { exclusiveRelayer, exclusivityPeriod: exclusivityDeadline } =
       await selectExclusiveRelayer(
         computedOriginChainId,
@@ -364,6 +372,19 @@ const handler = async (
         recommendedDepositInstant: limits.recommendedDepositInstant,
       },
       fillDeadline: fillDeadline.toString(),
+      outputAmount: outputAmount.toString(),
+      inputToken: {
+        address: inputToken.address,
+        symbol: inputToken.symbol,
+        decimals: inputToken.decimals,
+        chainId: computedOriginChainId,
+      },
+      outputToken: {
+        address: outputToken.address,
+        symbol: outputToken.symbol,
+        decimals: outputToken.decimals,
+        chainId: destinationChainId,
+      },
     };
 
     logger.info({