Merge pull request #122 from hyperweb-io/demo-convert

denomination improvement

Author: sdqede

networks/ethereum/src/utils/denominations.ts

@@ -1,96 +1,135 @@
 /**
- * Ethereum denominations and conversion utilities
+ * Utility functions for handling Ethereum denominations
+ * Provides conversion between ETH/tokens and their smallest units (wei/base units)
  */
 
-// Denomination constants with their values in wei
-export const DENOMINATIONS = {
-  wei: '1',
-  kwei: '1000',
-  mwei: '1000000',
-  gwei: '1000000000',
-  microether: '1000000000000',
-  milliether: '1000000000000000',
-  ether: '1000000000000000000',
-} as const;
+// Constants
+const ETHER_DECIMALS = 18;
 
-export type EthDenomination = keyof typeof DENOMINATIONS;
-
-// Unit type can be either a predefined denomination or a number representing decimal places
-export type UnitType = EthDenomination | number;
+/**
+ * Converts a string or number representing ETH to wei (the smallest unit)
+ * @param etherStr - The ETH amount as a string or number
+ * @returns The amount in wei as BigInt
+ */
+export function parseEther(etherStr: string | number): bigint {
+  return parseUnits(etherStr, ETHER_DECIMALS);
+}
 
 /**
- * Gets the wei value for a given unit
- * @param unit - The unit (either a predefined denomination or a decimal precision number)
- * @returns The wei value as BigInt
+ * Converts wei (the smallest unit) to a string representing ETH
+ * @param wei - The amount in wei as BigInt or string
+ * @returns The amount in ETH as a decimal string
  */
-function getWeiValue(unit: UnitType): bigint {
-  if (typeof unit === 'number') {
-    return BigInt(10) ** BigInt(unit);
-  }
-  return BigInt(DENOMINATIONS[unit]);
+export function formatEther(wei: bigint | string): string {
+  return formatUnits(wei, ETHER_DECIMALS);
 }
 
 /**
- * Converts from one unit to another
- * @param amount - The amount to convert
- * @param fromUnit - The source unit (denomination name or decimal precision)
- * @param toUnit - The target unit (denomination name or decimal precision)
- * @returns The converted amount as string
+ * Converts a human-readable token amount to its smallest unit
+ * @param amount - The token amount as a string or number
+ * @param decimals - The number of decimals the token uses
+ * @returns The amount in the smallest unit as BigInt
  */
-export function convert(
-  amount: string | number,
-  fromUnit: UnitType,
-  toUnit: UnitType
-): string {
-  const amountStr = typeof amount === 'string' ? amount : amount.toString();
-
-  // Get wei values for each unit
-  const fromWei = getWeiValue(fromUnit);
-  const toWei = getWeiValue(toUnit);
-
-  // Handle decimal points in the input
-  let [whole, decimal] = amountStr.split('.');
-  whole = whole || '0';
-  decimal = decimal || '';
-
-  // Calculate base-10 decimals in fromUnit
-  const fromDecimals = typeof fromUnit === 'number'
-    ? fromUnit
-    : DENOMINATIONS[fromUnit].length - 1;
-
-  // Convert to BigInt with proper decimal handling
-  let valueInSmallestUnit;
-  if (decimal) {
-    // Scale the decimal part properly
-    const scaledDecimal = decimal.padEnd(Number(fromDecimals), '0').slice(0, Number(fromDecimals));
-    // Convert decimal part to equivalent wei value
-    const decimalValue = BigInt(scaledDecimal) * BigInt(10) ** BigInt(Math.max(0, Number(fromDecimals) - decimal.length));
-    valueInSmallestUnit = BigInt(whole) * fromWei + decimalValue;
+export function parseUnits(amount: string | number, decimals: number): bigint {
+  // Validate inputs
+  if (decimals < 0 || !Number.isInteger(decimals)) {
+    throw new Error('Decimals must be a non-negative integer');
+  }
+
+  // Convert amount to string
+  const amountStr = amount.toString();
+
+  // Handle scientific notation if present
+  if (amountStr.includes('e')) {
+    // Parse scientific notation directly without recursion
+    const [mantissa, exponentStr] = amountStr.split('e');
+    const exponent = parseInt(exponentStr);
+
+    // Handle the mantissa with its own decimal places
+    let [intPart, fracPart = ''] = mantissa.split('.');
+
+    if (exponent >= 0) {
+      // Positive exponent - shift decimal point to the right
+      if (fracPart.length <= exponent) {
+        // Pad with zeros as needed
+        const result = intPart + fracPart.padEnd(exponent, '0');
+        return parseUnits(result, decimals);
+      } else {
+        // Move decimal point within the fraction
+        const result = intPart + fracPart.substring(0, exponent) + '.' + fracPart.substring(exponent);
+        return parseUnits(result, decimals);
+      }
+    } else {
+      // Negative exponent - shift decimal point to the left
+      const absExponent = Math.abs(exponent);
+      if (intPart.length <= absExponent) {
+        // Result is < 1
+        const padding = '0'.repeat(absExponent - intPart.length);
+        const result = '0.' + padding + intPart + fracPart;
+        return parseUnits(result, decimals);
+      } else {
+        // Insert decimal point in the integer part
+        const splitPoint = intPart.length - absExponent;
+        const result = intPart.substring(0, splitPoint) + '.' + intPart.substring(splitPoint) + fracPart;
+        return parseUnits(result, decimals);
+      }
+    }
+  }
+
+  // Split the decimal string
+  let [integerPart, fractionPart = ''] = amountStr.split('.');
+
+  // Remove leading zeros from the integer part (but keep at least one digit)
+  integerPart = integerPart.replace(/^0+(?=\d)/, '');
+  if (integerPart === '') integerPart = '0';
+
+  // Pad or truncate the fraction part according to decimals
+  if (fractionPart.length > decimals) {
+    fractionPart = fractionPart.slice(0, decimals);
   } else {
-    valueInSmallestUnit = BigInt(whole) * fromWei;
+    fractionPart = fractionPart.padEnd(decimals, '0');
   }
 
-  // Convert to target unit using uniform division
-  const result = valueInSmallestUnit / toWei;
-  return result.toString();
-}
+  // Combine integer and fraction parts without decimal point
+  const result = integerPart + fractionPart;
 
-/**
- * Converts from ETH to any unit
- * @param amount - The amount in ETH
- * @param toUnit - The target unit (denomination name or decimal precision)
- * @returns The converted amount as string
- */
-export function ethToUnit(amount: string | number, toUnit: UnitType): string {
-  return convert(amount, 'ether', toUnit);
+  // Convert to BigInt - remove leading zeros to prevent octal interpretation
+  return BigInt(result.replace(/^0+(?=\d)/, '') || '0');
 }
 
 /**
- * Converts from any unit to ETH
- * @param amount - The amount in the source unit
- * @param fromUnit - The source unit (denomination name or decimal precision)
- * @returns The amount in ETH as string
+ * Converts an amount in smallest units to a human-readable token amount
+ * @param amount - The amount in the smallest units as BigInt or string
+ * @param decimals - The number of decimals the token uses
+ * @returns The human-readable token amount as a decimal string
  */
-export function unitToEth(amount: string | number, fromUnit: UnitType): string {
-  return convert(amount, fromUnit, 'ether');
+export function formatUnits(amount: bigint | string, decimals: number): string {
+  // Validate inputs
+  if (decimals < 0 || !Number.isInteger(decimals)) {
+    throw new Error('Decimals must be a non-negative integer');
+  }
+
+  // Convert amount to string
+  const amountStr = amount.toString();
+
+  // If amount is 0, return "0"
+  if (amountStr === '0') return '0';
+
+  // Pad with leading zeros to ensure we have at least 'decimals' digits
+  const padded = amountStr.padStart(decimals, '0');
+
+  // Calculate the integer part and fractional part positions
+  const integerPartLength = Math.max(0, padded.length - decimals);
+
+  // Extract the integer and fraction parts
+  const integerPart = integerPartLength > 0 ? padded.slice(0, integerPartLength) : '0';
+  const fractionPart = padded.slice(integerPartLength);
+
+  // Trim trailing zeros from fraction part
+  const trimmedFraction = fractionPart.replace(/0+$/, '');
+
+  // Combine the parts with a decimal point if necessary
+  return trimmedFraction.length > 0
+    ? `${integerPart}.${trimmedFraction}`
+    : integerPart;
 }

networks/ethereum/starship/__tests__/utils.test.ts

@@ -1,5 +1,5 @@
 import { isValidEthereumAddress, toChecksumAddress } from '../../src/utils/address';
-import { convert, ethToUnit, unitToEth, DENOMINATIONS } from '../../src/utils/denominations';
+import { parseEther, formatEther, parseUnits, formatUnits } from '../../src/utils/denominations';
 import { utf8ToHex, hexToUtf8 } from '../../src/utils/encoding';
 
 describe('address utils', () => {
@@ -34,54 +34,107 @@ describe('address utils', () => {
   });
 });
 
+describe('parseEther', () => {
+  test('should convert ETH to wei', () => {
+    expect(parseEther('1.0').toString()).toBe('1000000000000000000');
+    expect(parseEther('2.5').toString()).toBe('2500000000000000000');
+    expect(parseEther('0.000000000000000001').toString()).toBe('1');
+  });
+
+  test('should handle zero', () => {
+    expect(parseEther('0').toString()).toBe('0');
+    expect(parseEther('0.0').toString()).toBe('0');
+  });
+
+  test('should handle string and number inputs', () => {
+    expect(parseEther('5').toString()).toBe(parseEther(5).toString());
+  });
+
+  test('should handle scientific notation', () => {
+    expect(parseEther('1e18').toString()).toBe('1000000000000000000000000000000000000');
+    expect(parseEther('2e-18').toString()).toBe('2');
+  });
+
+  test('should truncate excess decimals beyond 18 places', () => {
+    // Should truncate, not round
+    expect(parseEther('1.0000000000000000005').toString()).toBe('1000000000000000000');
+    expect(parseEther('0.0000000000000000001').toString()).toBe('0');
+  });
+});
+
+describe('formatEther', () => {
+  test('should convert wei to ETH', () => {
+    expect(formatEther(BigInt('1000000000000000000'))).toBe('1');
+    expect(formatEther('1000000000000000000')).toBe('1');
+    expect(formatEther(BigInt('2500000000000000000'))).toBe('2.5');
+  });
+
+  test('should handle zero', () => {
+    expect(formatEther(BigInt('0'))).toBe('0');
+    expect(formatEther('0')).toBe('0');
+  });
 
-describe('denominations utils', () => {
-  test('DENOMINATIONS constants', () => {
-    expect(DENOMINATIONS.wei).toBe('1');
-    expect(DENOMINATIONS.ether).toBe('1000000000000000000');
+  test('should format with correct precision', () => {
+    expect(formatEther(BigInt('1'))).toBe('0.000000000000000001');
+    expect(formatEther(BigInt('100000000'))).toBe('0.0000000001');
   });
 
-  test('convert wei to ether', () => {
-    expect(convert('1000000000000000000', 'wei', 'ether')).toBe('1');
+  test('should remove trailing zeros', () => {
+    expect(formatEther(BigInt('1000000000000000000'))).toBe('1');  // Not '1.000000000000000000'
+    expect(formatEther(BigInt('1100000000000000000'))).toBe('1.1'); // Not '1.100000000000000000'
+  });
+});
+
+describe('parseUnits', () => {
+  test('should convert amount to smallest units with custom decimals', () => {
+    expect(parseUnits('1.0', 6).toString()).toBe('1000000'); // 6 decimals (USDC)
+    expect(parseUnits('2.5', 8).toString()).toBe('250000000'); // 8 decimals (WBTC)
+    expect(parseUnits('1', 0).toString()).toBe('1'); // 0 decimals
   });
 
-  test('convert gwei to ether', () => {
-    expect(convert('1000000000', 'gwei', 'ether')).toBe('1');
+  test('should handle more decimal places than specified', () => {
+    expect(parseUnits('1.123456789', 6).toString()).toBe('1123456'); // Truncate to 6 decimals
+    expect(parseUnits('0.1234567890123456789', 10).toString()).toBe('1234567890'); // Truncate to 10 decimals
   });
 
-  test('convert ether to ether', () => {
-    expect(convert('2', 'ether', 'ether')).toBe('2');
+  test('should handle leading and trailing zeros', () => {
+    expect(parseUnits('01.100', 6).toString()).toBe('1100000');
+    expect(parseUnits('000.0010', 6).toString()).toBe('1000');
   });
 
-  test('ethToUnit and unitToEth coherence', () => {
-    const amountEth = '3';
-    const amountWei = DENOMINATIONS.ether;
-    expect(ethToUnit(amountEth, 'wei')).toBe(convert(amountEth, 'ether', 'wei'));
-    expect(unitToEth(amountWei, 'wei')).toBe(convert(amountWei, 'wei', 'ether'));
+  test('should throw for negative decimals', () => {
+    expect(() => parseUnits('1.0', -1)).toThrow('Decimals must be a non-negative integer');
+  });
+
+  test('should handle very large values', () => {
+    expect(parseUnits('1000000000000000000', 18).toString()).toBe('1000000000000000000000000000000000000');
+  });
+});
+
+describe('formatUnits', () => {
+  test('should convert smallest units to human-readable form with custom decimals', () => {
+    expect(formatUnits(BigInt('1000000'), 6)).toBe('1');
+    expect(formatUnits(BigInt('250000000'), 8)).toBe('2.5');
+    expect(formatUnits(BigInt('1'), 0)).toBe('1');
   });
 
-  test('convert numeric unit (11) to wei and back', () => {
-    // 1 * 10^11 = 100000000000 wei
-    expect(convert('1', 11, 'wei')).toBe('100000000000');
-    // 100000000000 wei / 10^11 = 1
-    expect(convert('100000000000', 'wei', 11)).toBe('1');
+  test('should handle string inputs', () => {
+    expect(formatUnits('1000000', 6)).toBe('1');
+    expect(formatUnits('250000000', 8)).toBe('2.5');
   });
 
-  test('convert using numeric unit (5) precision', () => {
-    // 1.23456 * 10^5 = 123456
-    expect(convert('1.23456', 5, 'wei')).toBe('123456');
-    // 123456 wei / 10^5 = 1
-    expect(convert('123456', 'wei', 5)).toBe('1');
+  test('should handle zero values', () => {
+    expect(formatUnits(BigInt('0'), 18)).toBe('0');
+    expect(formatUnits('0', 6)).toBe('0');
   });
 
-  test('truncate decimals beyond 18 places for ether to wei', () => {
-    // Only first 18 decimal digits are used
-    expect(convert('0.01234567890123456789', 'ether', 'wei')).toBe('12345678901234567');
+  test('should handle small values', () => {
+    expect(formatUnits(BigInt('1'), 18)).toBe('0.000000000000000001');
+    expect(formatUnits(BigInt('10'), 18)).toBe('0.00000000000000001');
   });
 
-  test('convert truncated wei back to ether (floor)', () => {
-    // Truncated wei divided by 1e18 yields 0 (integer division)
-    expect(convert('12345678901234567', 'wei', 'ether')).toBe('0');
+  test('should throw for negative decimals', () => {
+    expect(() => formatUnits(BigInt('1'), -1)).toThrow('Decimals must be a non-negative integer');
   });
 });