@reown/appkit-common-react-native 2.0.0-alpha.0 → 2.0.0-alpha.2

package/src/adapters/EvmAdapter.ts

@@ -0,0 +1,259 @@
+import { BlockchainAdapter } from './BlockchainAdapter';
+import { NumberUtil } from '../utils/NumberUtil';
+import type { AppKitNetwork } from '../utils/TypeUtil';
+
+// Type definitions for writeContract
+export interface WriteContractData {
+  tokenAddress: `0x${string}`;
+  receiverAddress: `0x${string}`;
+  tokenAmount: bigint;
+  fromAddress: `0x${string}`;
+  method: 'transfer' | 'transferFrom' | 'approve';
+  abi?: any; // Optional ABI for future extensibility
+  spenderAddress?: `0x${string}`; // Required for transferFrom and approve
+  network: AppKitNetwork;
+}
+
+export interface SendTransactionData {
+  address: `0x${string}`;
+  network: AppKitNetwork;
+  to: `0x${string}`;
+  value: string;
+  data: string;
+}
+
+// Simple ABI encoder for ERC20 functions
+function encodeERC20Function(method: string, params: any[]): string {
+  const functionSelectors = {
+    transfer: '0xa9059cbb', // transfer(address,uint256)
+    transferFrom: '0x23b872dd', // transferFrom(address,address,uint256)
+    approve: '0x095ea7b3' // approve(address,uint256)
+  };
+
+  const selector = functionSelectors[method as keyof typeof functionSelectors];
+  if (!selector) {
+    throw new Error(`EVMAdapter:encodeERC20Function - unsupported method: ${method}`);
+  }
+
+  let encodedParams = '';
+
+  switch (method) {
+    case 'transfer':
+      if (params.length !== 2) throw new Error('transfer requires 2 parameters: to, amount');
+      const [to, amount] = params;
+      encodedParams =
+        to.toLowerCase().slice(2).padStart(64, '0') + amount.toString(16).padStart(64, '0');
+      break;
+
+    case 'transferFrom':
+      if (params.length !== 3)
+        throw new Error('transferFrom requires 3 parameters: from, to, amount');
+      const [from, toTransferFrom, amountTransferFrom] = params;
+      encodedParams =
+        from.toLowerCase().slice(2).padStart(64, '0') +
+        toTransferFrom.toLowerCase().slice(2).padStart(64, '0') +
+        amountTransferFrom.toString(16).padStart(64, '0');
+      break;
+
+    case 'approve':
+      if (params.length !== 2) throw new Error('approve requires 2 parameters: spender, amount');
+      const [spender, amountApprove] = params;
+      encodedParams =
+        spender.toLowerCase().slice(2).padStart(64, '0') +
+        amountApprove.toString(16).padStart(64, '0');
+      break;
+
+    default:
+      throw new Error(`EVMAdapter:encodeERC20Function - unsupported method: ${method}`);
+  }
+
+  return selector + encodedParams;
+}
+
+export abstract class EVMAdapter extends BlockchainAdapter {
+  override subscribeToEvents(): void {
+    super.subscribeToEvents();
+    const provider = this.getProvider();
+    if (!provider) return;
+
+    // provider.on('reown_updateEmail', (info: any) => {
+    //   // this.emit('updateEmail', email);
+    //   //TODO: check this
+    //   // console.log('reown_updateEmail', info);
+    // });
+  }
+
+  async signMessage(address: string, message: string, chain?: string): Promise<string> {
+    const provider = this.getProvider();
+
+    if (!provider) {
+      throw new Error('EVMAdapter:signMessage - provider is undefined');
+    }
+
+    const signature = await provider.request(
+      {
+        method: 'personal_sign',
+        params: [message, address]
+      },
+      `eip155:${chain}`
+    );
+
+    return signature as string;
+  }
+  async estimateGas({ address, to, data, chainNamespace }: any): Promise<bigint> {
+    const provider = this.getProvider();
+
+    if (!provider) {
+      throw new Error('EVMAdapter:estimateGas - provider is undefined');
+    }
+
+    if (!address) {
+      throw new Error('EVMAdapter:estimateGas - from address is undefined');
+    }
+
+    if (chainNamespace && chainNamespace !== 'eip155') {
+      throw new Error('EVMAdapter:estimateGas - chainNamespace is not eip155');
+    }
+
+    try {
+      const txParams = {
+        from: address,
+        to,
+        data,
+        type: '0x0' // optional, legacy type
+      };
+
+      const estimatedGasHex = await provider.request({
+        method: 'eth_estimateGas',
+        params: [txParams]
+      });
+
+      return BigInt(estimatedGasHex as string);
+    } catch (error) {
+      throw new Error('EVMAdapter:estimateGas - eth_estimateGas RPC failed');
+    }
+  }
+
+  async sendTransaction(data: SendTransactionData): Promise<`0x${string}` | null> {
+    const { address, network } = data || {};
+
+    if (!this.getProvider()) {
+      throw new Error('EVMAdapter:sendTransaction - provider is undefined');
+    }
+
+    if (!address) {
+      throw new Error('EVMAdapter:sendTransaction - address is undefined');
+    }
+
+    if (!network) {
+      throw new Error('EVMAdapter:sendTransaction - network is undefined');
+    }
+
+    const txParams = {
+      from: address,
+      to: data.to,
+      value: NumberUtil.convertNumericToHexString(data.value),
+      data: data.data, // hex-encoded bytecode
+      type: '0x0' // optional: legacy transaction type
+    };
+
+    const txHash = await this.getProvider().request(
+      {
+        method: 'eth_sendTransaction',
+        params: [txParams]
+      },
+      network.caipNetworkId
+    );
+
+    return txHash as `0x${string}` | null;
+  }
+
+  async writeContract(data: WriteContractData): Promise<`0x${string}` | null> {
+    const {
+      tokenAddress,
+      receiverAddress,
+      tokenAmount,
+      method,
+      fromAddress,
+      spenderAddress,
+      network
+    } = data;
+
+    if (!this.getProvider()) {
+      throw new Error('EVMAdapter:writeContract - provider is undefined');
+    }
+
+    if (!fromAddress) {
+      throw new Error('EVMAdapter:writeContract - fromAddress is undefined');
+    }
+
+    if (!tokenAddress) {
+      throw new Error('EVMAdapter:writeContract - tokenAddress is undefined');
+    }
+
+    if (!tokenAmount) {
+      throw new Error('EVMAdapter:writeContract - tokenAmount is undefined');
+    }
+
+    if (!method) {
+      throw new Error('EVMAdapter:writeContract - method is undefined');
+    }
+
+    // Validate method-specific parameters
+    if (method === 'transfer' && !receiverAddress) {
+      throw new Error('EVMAdapter:writeContract - receiverAddress is required for transfer method');
+    }
+
+    if ((method === 'transferFrom' || method === 'approve') && !spenderAddress) {
+      throw new Error(`EVMAdapter:writeContract - spenderAddress is required for ${method} method`);
+    }
+
+    // Encode the function call data based on method
+    let encodedData: string;
+
+    switch (method) {
+      case 'transfer':
+        encodedData = encodeERC20Function('transfer', [receiverAddress, tokenAmount]);
+        break;
+      case 'transferFrom':
+        encodedData = encodeERC20Function('transferFrom', [
+          fromAddress,
+          receiverAddress,
+          tokenAmount
+        ]);
+        break;
+      case 'approve':
+        encodedData = encodeERC20Function('approve', [spenderAddress, tokenAmount]);
+        break;
+      default:
+        throw new Error(`EVMAdapter:writeContract - method '${method}' is not supported`);
+    }
+
+    // Create transaction parameters
+    const txParams = {
+      from: fromAddress,
+      to: tokenAddress,
+      data: encodedData,
+      value: '0x0', // No ETH value for token operations
+      type: '0x0' // legacy transaction type
+    };
+
+    try {
+      // Send the transaction
+      const txHash = await this.getProvider().request(
+        {
+          method: 'eth_sendTransaction',
+          params: [txParams]
+        },
+        network.caipNetworkId
+      );
+
+      return txHash as `0x${string}` | null;
+    } catch (error) {
+      if (error instanceof Error) {
+        throw new Error(`EVMAdapter:writeContract - ${error.message}`);
+      }
+      throw new Error('EVMAdapter:writeContract - unknown error occurred');
+    }
+  }
+}

package/src/adapters/SolanaBaseAdapter.ts

@@ -0,0 +1,6 @@
+import { BlockchainAdapter } from './BlockchainAdapter';
+
+export abstract class SolanaBaseAdapter extends BlockchainAdapter {
+  abstract signTransaction(data: any): Promise<string | null>;
+  abstract sendTransaction(data: any): Promise<string | null>;
+}

package/src/adapters/__tests__/EvmAdapter.test.ts

@@ -0,0 +1,126 @@
+import { EVMAdapter } from '../EvmAdapter';
+import type { AppKitNetwork, CaipAddress } from '../../utils/TypeUtil';
+
+const network: AppKitNetwork = {
+  id: 1,
+  name: 'Ethereum',
+  nativeCurrency: { name: 'Ether', symbol: 'ETH', decimals: 18 },
+  rpcUrls: {
+    default: {
+      http: ['https://eth.merkle.io']
+    }
+  },
+  blockExplorers: {
+    default: {
+      name: 'Etherscan',
+      url: 'https://etherscan.io'
+    }
+  },
+  chainNamespace: 'eip155',
+  caipNetworkId: 'eip155:1'
+};
+
+// Mock implementation for testing
+class MockEVMAdapter extends EVMAdapter {
+  private mockProvider: any;
+
+  constructor() {
+    super({ projectId: 'test', supportedNamespace: 'eip155', adapterType: 'ethers' });
+    this.mockProvider = {
+      request: jest.fn(),
+      on: jest.fn(),
+      off: jest.fn()
+    };
+  }
+
+  setMockProvider(provider: any) {
+    this.mockProvider = provider;
+  }
+
+  override getProvider() {
+    return this.mockProvider;
+  }
+
+  async disconnect(): Promise<void> {}
+  getSupportedNamespace() {
+    return 'eip155' as const;
+  }
+  async getBalance() {
+    return { amount: '0', symbol: 'ETH' };
+  }
+  getAccounts(): CaipAddress[] | undefined {
+    return ['eip155:1:0x1234567890123456789012345678901234567890'];
+  }
+  async switchNetwork() {}
+}
+
+describe('EVMAdapter', () => {
+  let adapter: MockEVMAdapter;
+
+  beforeEach(() => {
+    adapter = new MockEVMAdapter();
+  });
+
+  describe('writeContract', () => {
+    it('should encode transfer function correctly', async () => {
+      const mockProvider = {
+        request: jest.fn().mockResolvedValueOnce('0x1234567890abcdef') // eth_sendTransaction
+      };
+      adapter.setMockProvider(mockProvider);
+
+      const result = await adapter.writeContract({
+        tokenAddress: '0x1234567890123456789012345678901234567890',
+        receiverAddress: '0xabcdefabcdefabcdefabcdefabcdefabcdefabcd',
+        tokenAmount: BigInt(1000000000000000000), // 1 token with 18 decimals
+        fromAddress: '0x1234567890123456789012345678901234567890',
+        method: 'transfer',
+        network
+      });
+
+      expect(result).toBe('0x1234567890abcdef');
+      expect(mockProvider.request).toHaveBeenCalledWith(
+        {
+          method: 'eth_sendTransaction',
+          params: [
+            {
+              from: '0x1234567890123456789012345678901234567890',
+              to: '0x1234567890123456789012345678901234567890',
+              data: '0xa9059cbb000000000000000000000000abcdefabcdefabcdefabcdefabcdefabcdefabcd0000000000000000000000000000000000000000000000000de0b6b3a7640000',
+              value: '0x0',
+              type: '0x0'
+            }
+          ]
+        },
+        'eip155:1'
+      );
+    });
+
+    it('should throw error for unsupported method', async () => {
+      await expect(
+        adapter.writeContract({
+          tokenAddress: '0x1234567890123456789012345678901234567890',
+          receiverAddress: '0xabcdefabcdefabcdefabcdefabcdefabcdefabcd',
+          tokenAmount: BigInt(1000000000000000000),
+          fromAddress: '0x1234567890123456789012345678901234567890',
+          method: 'unsupported' as any,
+          network
+        })
+      ).rejects.toThrow("method 'unsupported' is not supported");
+    });
+
+    it('should throw error when provider is undefined', async () => {
+      adapter.setMockProvider(undefined);
+
+      await expect(
+        adapter.writeContract({
+          tokenAddress: '0x1234567890123456789012345678901234567890',
+          receiverAddress: '0xabcdefabcdefabcdefabcdefabcdefabcdefabcd',
+          tokenAmount: BigInt(1000000000000000000),
+          fromAddress: '0x1234567890123456789012345678901234567890',
+          method: 'transfer',
+          network
+        })
+      ).rejects.toThrow('provider is undefined');
+    });
+  });
+});

package/src/index.ts

@@ -8,4 +8,9 @@ export { PresetsUtil } from './utils/PresetsUtil';
 export { StringUtil } from './utils/StringUtil';
 export { ErrorUtil } from './utils/ErrorUtil';
 export { erc20ABI } from './contracts/erc20';
+export { solana, solanaDevnet, solanaTestnet } from './networks/solana';
+export { bitcoin, bitcoinTestnet } from './networks/bitcoin';
+export { BlockchainAdapter } from './adapters/BlockchainAdapter';
+export { EVMAdapter } from './adapters/EvmAdapter';
+export { SolanaBaseAdapter } from './adapters/SolanaBaseAdapter';
 export * from './utils/TypeUtil';

package/src/networks/bitcoin.ts

@@ -0,0 +1,32 @@
+import type { AppKitNetwork } from '../utils/TypeUtil';
+
+export const bitcoin: AppKitNetwork = {
+  id: '000000000019d6689c085ae165831e93',
+  caipNetworkId: 'bip122:000000000019d6689c085ae165831e93',
+  chainNamespace: 'bip122',
+  name: 'Bitcoin',
+  nativeCurrency: {
+    name: 'Bitcoin',
+    symbol: 'BTC',
+    decimals: 8
+  },
+  rpcUrls: {
+    default: { http: ['https://rpc.walletconnect.org/v1'] }
+  }
+};
+
+export const bitcoinTestnet: AppKitNetwork = {
+  id: '000000000933ea01ad0ee984209779ba',
+  caipNetworkId: 'bip122:000000000933ea01ad0ee984209779ba',
+  chainNamespace: 'bip122',
+  name: 'Bitcoin Testnet',
+  nativeCurrency: {
+    name: 'Bitcoin',
+    symbol: 'BTC',
+    decimals: 8
+  },
+  rpcUrls: {
+    default: { http: ['https://rpc.walletconnect.org/v1'] }
+  },
+  testnet: true
+};

package/src/networks/solana.ts

@@ -0,0 +1,44 @@
+import type { AppKitNetwork } from '../utils/TypeUtil';
+
+export const solana: AppKitNetwork = {
+  id: '5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp',
+  name: 'Solana',
+  nativeCurrency: { name: 'Solana', symbol: 'SOL', decimals: 9 },
+  rpcUrls: {
+    default: {
+      http: ['https://rpc.walletconnect.org/v1']
+    }
+  },
+  blockExplorers: { default: { name: 'Solscan', url: 'https://solscan.io' } },
+  chainNamespace: 'solana',
+  caipNetworkId: 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp',
+  deprecatedCaipNetworkId: 'solana:4sGjMW1sUnHzSxGspuhpqLDx6wiyjNtZ',
+  testnet: false
+};
+
+export const solanaDevnet: AppKitNetwork = {
+  id: 'EtWTRABZaYq6iMfeYKouRu166VU2xqa1',
+  name: 'Solana Devnet',
+  nativeCurrency: { name: 'Solana', symbol: 'SOL', decimals: 9 },
+  rpcUrls: {
+    default: { http: ['https://rpc.walletconnect.org/v1'] }
+  },
+  blockExplorers: { default: { name: 'Solscan', url: 'https://solscan.io' } },
+  chainNamespace: 'solana',
+  caipNetworkId: 'solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1',
+  deprecatedCaipNetworkId: 'solana:8E9rvCKLFQia2Y35HXjjpWzj8weVo44K',
+  testnet: true
+};
+
+export const solanaTestnet: AppKitNetwork = {
+  id: '4uhcVJyU9pJkvQyS88uRDiswHXSCkY3z',
+  name: 'Solana Testnet',
+  nativeCurrency: { name: 'Solana', symbol: 'SOL', decimals: 9 },
+  rpcUrls: {
+    default: { http: ['https://rpc.walletconnect.org/v1'] }
+  },
+  blockExplorers: { default: { name: 'Solscan', url: 'https://solscan.io' } },
+  chainNamespace: 'solana',
+  caipNetworkId: 'solana:4uhcVJyU9pJkvQyS88uRDiswHXSCkY3z',
+  testnet: true
+};

package/src/utils/ConstantsUtil.ts

@@ -1,5 +1,5 @@
 export const ConstantsUtil = {
-  VERSION: '2.0.0-alpha.0',
+  VERSION: '2.0.0-alpha.2',
 
   EIP155: 'eip155',
   ADD_CHAIN_METHOD: 'wallet_addEthereumChain',
@@ -11,12 +11,14 @@ export const ConstantsUtil = {
   BLOCKCHAIN_API_RPC_URL_STAGING: 'https://staging.rpc.walletconnect.org',
   PULSE_API_URL: 'https://pulse.walletconnect.org',
   API_URL: 'https://api.web3modal.org',
-
-  WALLET_CONNECT_CONNECTOR_ID: 'walletConnect',
-  COINBASE_CONNECTOR_ID: 'coinbaseWallet',
-  AUTH_CONNECTOR_ID: 'appKitAuth',
+  WEB_WALLET_URL: 'https://web-wallet.walletconnect.org',
+  SECURE_SITE_DASHBOARD: `https://secure.reown.com/dashboard`,
+  SECURE_SITE_ICON: `https://secure.reown.com/images/favicon.png`,
 
   COINBASE_EXPLORER_ID: 'fd20dc426fb37566d803205b19bbc1d4096b248ac04548e3cfb6b3a38bd033aa',
+  PHANTOM_EXPLORER_ID: 'a797aa35c0fadbfc1a53e7f675162ed5226968b44a19ee3d24385c64d1d3c393',
+
+  WALLET_CONNECT_IMAGE_ID: 'ef1a1fcf-7fe8-4d69-bd6d-fda1345b4400',
 
   USDT_CONTRACT_ADDRESSES: [
     // Mainnet
@@ -33,5 +35,30 @@ export const ConstantsUtil = {
     '0x55d398326f99059fF775485246999027B3197955',
     // Arbitrum
     '0xfd086bc7cd5c481dcc9c85ebe478a1c0b69fcbb9'
-  ]
+  ],
+
+  PHANTOM_CUSTOM_WALLET: {
+    id: 'a797aa35c0fadbfc1a53e7f675162ed5226968b44a19ee3d24385c64d1d3c393',
+    name: 'Phantom Wallet',
+    image_id: 'b6ec7b81-bb4f-427d-e290-7631e6e50d00',
+    mobile_link: 'phantom://'
+  },
+
+  // Storage Keys
+  STORAGE_KEYS: {
+    WC_DEEPLINK: 'WALLETCONNECT_DEEPLINK_CHOICE', //dont change this one
+    RECENT_WALLET: '@appkit/recent_wallet',
+    CONNECTED_WALLET_IMAGE_URL: '@appkit/connected_wallet_image_url',
+    CONNECTED_CONNECTORS: '@appkit/connected_connectors',
+    CONNECTED_SOCIAL: '@appkit/connected_social',
+    ONRAMP_PREFERRED_COUNTRY: '@appkit/onramp_preferred_country',
+    ONRAMP_COUNTRIES: '@appkit/onramp_countries',
+    ONRAMP_SERVICE_PROVIDERS: '@appkit/onramp_service_providers',
+    ONRAMP_FIAT_LIMITS: '@appkit/onramp_fiat_limits',
+    ONRAMP_FIAT_CURRENCIES: '@appkit/onramp_fiat_currencies',
+    ONRAMP_PREFERRED_FIAT_CURRENCY: '@appkit/onramp_preferred_fiat_currency',
+    ONRAMP_COUNTRIES_DEFAULTS: '@appkit/onramp_countries_defaults',
+    ACTIVE_NAMESPACE: '@appkit/active_namespace',
+    COINBASE_CONNECTOR_SESSION: '@appkit/coinbase_connector/session'
+  }
 };

package/src/utils/ErrorUtil.ts

@@ -16,12 +16,12 @@ export const ErrorUtil = {
   ALERT_ERRORS: {
     INVALID_APP_CONFIGURATION: {
       shortMessage: 'Invalid App Configuration',
-      longMessage: `Bundle ID not found on Allowlist - Please verify that your bundle ID is allowed at https://cloud.reown.com`
+      longMessage: `Bundle ID not found on Allowlist - Please verify that your bundle ID is allowed at https://dashboard.reown.com`
     },
     SOCIALS_TIMEOUT: {
       shortMessage: 'Invalid App Configuration',
       longMessage:
-        'There was an issue loading the embedded wallet. Please verify that your bundle ID is allowed at https://cloud.reown.com'
+        'There was an issue loading the embedded wallet. Please verify that your bundle ID is allowed at https://dashboard.reown.com'
     },
     JWT_TOKEN_NOT_VALID: {
       shortMessage: 'Session Expired',

package/src/utils/NumberUtil.ts

@@ -1,6 +1,12 @@
 import * as BigNumber from 'bignumber.js';
 
 export const NumberUtil = {
+  /**
+   * Creates a BigNumber instance from a given value.
+   * If the value is a string, commas are removed before conversion.
+   * @param value - The input value (string, number, or BigNumber) to convert to a BigNumber.
+   * @returns A BigNumber instance.
+   */
   bigNumber(value: BigNumber.BigNumber.Value) {
     if (typeof value === 'string') {
       return new BigNumber.BigNumber(value.replace(/,/g, ''));
@@ -10,10 +16,11 @@ export const NumberUtil = {
   },
 
   /**
-   * Multiply two numbers represented as strings with BigNumber to handle decimals correctly
-   * @param a string
-   * @param b string
-   * @returns
+   * Multiplies two numbers using BigNumber for precision, especially with decimals.
+   * Handles undefined inputs by returning BigNumber(0).
+   * @param a - The first multiplicand (string, number, or BigNumber). Commas are removed if it's a string.
+   * @param b - The second multiplicand (string, number, or BigNumber). Commas are removed if it's a string.
+   * @returns The product as a BigNumber instance, or BigNumber(0) if either input is undefined.
    */
   multiply(a: BigNumber.BigNumber.Value | undefined, b: BigNumber.BigNumber.Value | undefined) {
     if (a === undefined || b === undefined) {
@@ -26,6 +33,13 @@ export const NumberUtil = {
     return aBigNumber.multipliedBy(bBigNumber);
   },
 
+  /**
+   * Rounds a number to a specified number of decimal places if its string representation meets a certain length threshold.
+   * @param number - The number to potentially round.
+   * @param threshold - The minimum string length of the number to trigger rounding.
+   * @param fixed - The number of decimal places to round to.
+   * @returns The rounded number (as a string if rounded, otherwise the original number) or the original number.
+   */
   roundNumber(number: number, threshold: number, fixed: number) {
     const roundedNumber =
       number.toString().length >= threshold ? Number(number).toFixed(fixed) : number;
@@ -33,6 +47,12 @@ export const NumberUtil = {
     return roundedNumber;
   },
 
+  /**
+   * Calculates the next multiple of ten greater than or equal to the given amount.
+   * Defaults to 10 if no amount is provided or if the calculated multiple is less than 10.
+   * @param amount - The number for which to find the next multiple of ten. Optional.
+   * @returns The next multiple of ten, at least 10.
+   */
   nextMultipleOfTen(amount?: number) {
     if (!amount) return 10;
 
@@ -40,10 +60,10 @@ export const NumberUtil = {
   },
 
   /**
-   * Format the given number or string to human readable numbers with the given number of decimals
-   * @param value - The value to format. It could be a number or string. If it's a string, it will be parsed to a float then formatted.
-   * @param decimals - number of decimals after dot
-   * @returns
+   * Formats a number or string to a human-readable string with a specified number of decimal places, using US locale formatting.
+   * @param value - The value to format (string, number, or undefined). If undefined, returns '0.00'.
+   * @param decimals - The number of decimal places to display. Defaults to 2.
+   * @returns A locale-formatted string representation of the number.
    */
   formatNumberToLocalString(value: string | number | undefined, decimals = 2) {
     if (value === undefined) {
@@ -62,10 +82,11 @@ export const NumberUtil = {
       minimumFractionDigits: decimals
     });
   },
+
   /**
-   * Parse a formatted local string back to a number
-   * @param value - The formatted string to parse
-   * @returns
+   * Parses a locale-formatted numeric string (e.g., with commas) back into a number.
+   * @param value - The formatted string to parse. If undefined, returns 0.
+   * @returns The parsed number, or 0 if the input is undefined.
    */
   parseLocalStringToNumber(value: string | undefined) {
     if (value === undefined) {
@@ -74,5 +95,27 @@ export const NumberUtil = {
 
     // Remove any commas used as thousand separators and parse the float
     return parseFloat(value.replace(/,/gu, ''));
+  },
+
+  /**
+   * Converts a numeric value (BigInt, number, or string representation of a number) to a 0x-prefixed hexadecimal string.
+   * This is often required for Ethereum RPC parameters like value, gas, gasPrice.
+   * @param value - The value to convert. Can be BigInt, number, or a string (decimal or hex).
+   * @returns A 0x-prefixed hexadecimal string, or undefined if the input is undefined or null.
+   * @throws Error if the value cannot be converted to BigInt.
+   */
+  convertNumericToHexString: (value: any): string | undefined => {
+    if (value === undefined || value === null) {
+      return undefined;
+    }
+    try {
+      // This handles BigInt, number, or string representation of a number (decimal or hex)
+      const bigIntValue = BigInt(value);
+      // Ethereum RPC spec requires "0x0" for zero, and other values to be 0x-prefixed hex.
+
+      return '0x' + bigIntValue.toString(16);
+    } catch (error) {
+      throw new Error(`NumberUtil: Invalid parameter, cannot convert to hex: ${value}`);
+    }
   }
 };