Address PR review comments: scale validation and overflow handling

- Add .gt(0) validation for scale numerator in TypeScript schema (Cursor comment)
- Support string representation for large scale values (> MAX_SAFE_INTEGER)
- Update fetchScale to safely handle BigNumber overflow with try/catch
- Update deploy.ts, decimals.ts, and TokenMetadataMap.ts to handle string scale values

Fractional scaling tests already exist in HypERC20.t.sol (CodeRabbit flagged incorrectly)

Author: yorhodes

typescript/sdk/src/token/EvmERC20WarpRouteReader.ts

@@ -1091,11 +1091,16 @@ export class EvmERC20WarpRouteReader extends EvmRouterReader {
    * for contracts >= 11.0.0, otherwise reads legacy scale value.
    *
    * @param tokenRouterAddress - The address of the TokenRouter contract.
-   * @returns The scale as either a number (for old contracts or when denominator is 1) or an object with numerator/denominator.
+   * @returns The scale as either a number/string (for old contracts or when denominator is 1) or an object with numerator/denominator.
    */
   async fetchScale(
     tokenRouterAddress: Address,
-  ): Promise<number | { numerator: number; denominator: number } | undefined> {
+  ): Promise<
+    | number
+    | string
+    | { numerator: number | string; denominator: number | string }
+    | undefined
+  > {
     const packageVersion = await this.fetchPackageVersion(tokenRouterAddress);
     const hasScaleFractionInterface =
       compareVersions(packageVersion, SCALE_FRACTION_VERSION) >= 0;
@@ -1105,21 +1110,32 @@ export class EvmERC20WarpRouteReader extends EvmRouterReader {
       this.provider,
     );
 
+    // Helper to safely convert BigNumber to number or string
+    // Uses string representation for values > Number.MAX_SAFE_INTEGER
+    const safeToNumberOrString = (bn: BigNumber): number | string => {
+      try {
+        return bn.toNumber();
+      } catch {
+        // Value exceeds Number.MAX_SAFE_INTEGER, return as string
+        return bn.toString();
+      }
+    };
+
     if (hasScaleFractionInterface) {
       // Read new format (scaleNumerator and scaleDenominator)
       const [numerator, denominator] = await Promise.all([
         tokenRouter.scaleNumerator(),
         tokenRouter.scaleDenominator(),
       ]);
 
-      // If denominator is 1, return as a simple number for backward compatibility
+      // If denominator is 1, return as a simple number/string for backward compatibility
       if (denominator.eq(1)) {
-        return numerator.toNumber();
+        return safeToNumberOrString(numerator);
       }
 
       return {
-        numerator: numerator.toNumber(),
-        denominator: denominator.toNumber(),
+        numerator: safeToNumberOrString(numerator),
+        denominator: safeToNumberOrString(denominator),
       };
     } else {
       // Read old format (single scale value) using low-level call
@@ -1133,7 +1149,7 @@ export class EvmERC20WarpRouteReader extends EvmRouterReader {
         this.provider,
       );
       const scale = await legacyContract.scale();
-      return scale.toNumber();
+      return safeToNumberOrString(scale);
     }
   }
 

typescript/sdk/src/token/TokenMetadataMap.ts

@@ -46,7 +46,11 @@ export class TokenMetadataMap {
 
   getScale(
     chain: string,
-  ): number | { numerator: number; denominator: number } | undefined {
+  ):
+    | number
+    | string
+    | { numerator: number | string; denominator: number | string }
+    | undefined {
     return this.tokenMetadataMap.get(chain)?.scale;
   }
 

typescript/sdk/src/token/deploy.ts

@@ -153,8 +153,16 @@ abstract class TokenDeployer<
     const scale = config.scale ?? 1;
 
     // Convert scale to numerator/denominator format
-    const { numerator, denominator } =
-      typeof scale === 'number' ? { numerator: scale, denominator: 1 } : scale;
+    // Handle number, string, and object formats
+    let numerator: number | string;
+    let denominator: number | string;
+    if (typeof scale === 'number' || typeof scale === 'string') {
+      numerator = scale;
+      denominator = 1;
+    } else {
+      numerator = scale.numerator;
+      denominator = scale.denominator;
+    }
 
     if (isCollateralTokenConfig(config) || isXERC20TokenConfig(config)) {
       return [config.token, numerator, denominator, config.mailbox];

typescript/sdk/src/token/types.ts

@@ -39,10 +39,11 @@ export const TokenMetadataSchema = z.object({
   decimals: z.number().gt(0).optional(),
   scale: z
     .union([
-      z.number(),
+      z.number().gt(0),
+      z.string(), // string representation for large values
       z.object({
-        numerator: z.number(),
-        denominator: z.number().gt(0),
+        numerator: z.union([z.number().gt(0), z.string()]),
+        denominator: z.union([z.number().gt(0), z.string()]),
       }),
     ])
     .optional(),

typescript/sdk/src/utils/decimals.ts

@@ -15,7 +15,10 @@ export function verifyScale(
       : configMap;
   const decimalsByChain: ChainMap<{
     decimals: number;
-    scale?: number | { numerator: number; denominator: number };
+    scale?:
+      | number
+      | string
+      | { numerator: number | string; denominator: number | string };
   }> = objMap(chainDecimalConfigPairs, (chain, config) => {
     assert(
       config.decimals,
@@ -40,8 +43,18 @@ export function verifyScale(
           scaleValue = 1;
         } else if (typeof config.scale === 'number') {
           scaleValue = config.scale;
+        } else if (typeof config.scale === 'string') {
+          scaleValue = Number(config.scale);
         } else {
-          scaleValue = config.scale.numerator / config.scale.denominator;
+          const numerator =
+            typeof config.scale.numerator === 'string'
+              ? Number(config.scale.numerator)
+              : config.scale.numerator;
+          const denominator =
+            typeof config.scale.denominator === 'string'
+              ? Number(config.scale.denominator)
+              : config.scale.denominator;
+          scaleValue = numerator / denominator;
         }
 
         if (calculatedScale !== scaleValue) {
@@ -56,7 +69,10 @@ export function verifyScale(
 function areDecimalsUniform(
   configMap: ChainMap<{
     decimals: number;
-    scale?: number | { numerator: number; denominator: number };
+    scale?:
+      | number
+      | string
+      | { numerator: number | string; denominator: number | string };
   }>,
 ): boolean {
   const values = [...Object.values(configMap)];