fix(checkout-widgets): resolve checkout stuck in Crunching Numbers when paying with IMX (Issue 3)

When fetching funding balances for native tokens (e.g. tIMX on zkEVM), the
primary-sales API returns zero address. The code used ERC20ItemRequirement
which calls getTokenContract().decimals() and fails for non-contract addresses,
causing CheckoutError and leaving the widget stuck in loading.

Use NativeItemRequirement for native tokens instead of ERC20ItemRequirement.

Author: rodrigo-fournier-immutable

packages/checkout/widgets-lib/src/lib/utils.test.ts

@@ -535,6 +535,10 @@ describe('utils', () => {
       expect(isNativeToken('NATIVE')).toBeTruthy();
     });
 
+    it('should return true if address is zero address (used by some APIs for native token)', () => {
+      expect(isNativeToken('0x0000000000000000000000000000000000000000')).toBeTruthy();
+    });
+
     it('should return false if address is not NATIVE', () => {
       expect(isNativeToken('0x123')).toBeFalsy();
     });

packages/checkout/widgets-lib/src/lib/utils.ts

@@ -183,9 +183,14 @@ export const isZkEvmChainId = (chainId: ChainId) => chainId === ChainId.IMTBL_ZK
 export const isL1EthChainId = (chainId: ChainId) => chainId === ChainId.SEPOLIA
   || chainId === ChainId.ETHEREUM;
 
+/** Zero address used by some APIs (e.g. primary-sales) to denote native token (e.g. tIMX on zkEVM) */
+const ZERO_ADDRESS = '0x0000000000000000000000000000000000000000';
+
 export const isNativeToken = (
   address: string | undefined,
-): boolean => !address || address.toLocaleLowerCase() === NATIVE;
+): boolean => !address
+  || address.toLocaleLowerCase() === NATIVE
+  || address.toLocaleLowerCase() === ZERO_ADDRESS;
 
 export function getRemoteImage(environment: Environment | undefined, path: string) {
   return `${CHECKOUT_CDN_BASE_URL[environment ?? Environment.PRODUCTION]}/v1/blob/img${path}`;

packages/checkout/widgets-lib/src/widgets/sale/functions/fetchFundingBalances.ts

@@ -2,7 +2,7 @@ import {
   Checkout, ItemBalance, WrappedBrowserProvider, TokenBalance, TransactionRequirement,
 } from '@imtbl/checkout-sdk';
 import { Environment } from '@imtbl/config';
-import { compareStr } from '../../../lib/utils';
+import { compareStr, isNativeToken } from '../../../lib/utils';
 import {
   OrderQuoteCurrency,
   FundingBalance,
@@ -11,6 +11,7 @@ import {
 import {
   getAlternativeFundingSteps,
   getERC20ItemRequirement,
+  getNativeItemRequirement,
   getFnToPushAndSortFundingBalances,
   getFundingBalances,
   getGasEstimate,
@@ -75,11 +76,9 @@ export const fetchFundingBalances = async (
         return null;
       }
 
-      const itemRequirements = getERC20ItemRequirement(
-        amount,
-        spenderAddress,
-        currency.address,
-      );
+      const itemRequirements = isNativeToken(currency.address)
+        ? getNativeItemRequirement(amount)
+        : getERC20ItemRequirement(amount, spenderAddress, currency.address);
 
       const transactionOrGasAmount = getIsGasless()
         ? undefined

packages/checkout/widgets-lib/src/widgets/sale/functions/fetchFundingBalancesUtils.ts

@@ -7,6 +7,7 @@ import {
   TransactionOrGasType,
   TokenInfo,
   ERC20ItemRequirement,
+  NativeItemRequirement,
   FundingRoute,
   RoutingOutcomeType,
   FundingStep,
@@ -41,6 +42,13 @@ export const getERC20ItemRequirement = (
   },
 ];
 
+export const getNativeItemRequirement = (amount: string): NativeItemRequirement[] => [
+  {
+    type: ItemType.NATIVE,
+    amount,
+  },
+];
+
 export const getGasEstimate = (): GasAmount => ({
   type: TransactionOrGasType.GAS,
   gasToken: {