Package Exports

x0-react-sdk

Readme

X0Pay React SDK

A React SDK for integrating X0Pay functionality into web applications. This SDK provides a complete solution for handling cross-chain token transfers with server-side fee management.

Features

Cross-chain transfers: Support for multiple blockchain networks
Server-side fee management: Automatic fee calculation based on transfer amount
Order ID validation: Real-time validation with X0-worker API
Multi-wallet support: MetaMask and WalletConnect integration
Exchange rate handling: Automatic IDR to USD conversion
Progress tracking: Step-by-step transaction flow
Error handling: Comprehensive error management

Installation

npm install x0-react-sdk

Usage

Basic Usage

import React from 'react';
import { X0PayComponent } from 'x0-react-sdk';

function App() {
  const transactionParams = {
    orderId: 'ORDER123456', // Required: Order ID for validation
    transferAmount: 150000, // 150,000 IDR
    exchangeRate: 15000, // Optional: USD/IDR exchange rate
  };

  return (
    <X0PayComponent
      transactionParams={transactionParams}
      workerApiUrl="http://localhost:3000" // X0-worker API URL for fee calculation and order validation
      onSuccess={(txHash) => console.log('Success!', txHash)}
      onError={(err) => console.error('Error:', err.message)}
    />
  );
}

Order ID Validation

The SDK includes real-time order ID validation to prevent duplicate transactions. Order IDs are validated against the X0-worker API before allowing transactions to proceed.

Features

Real-time validation: Order IDs are validated as soon as they're entered
Duplicate prevention: Prevents transactions with existing order IDs
Visual feedback: Clear status indicators for order ID validation
Error handling: Comprehensive error messages for validation failures

Usage

const transactionParams = {
  orderId: 'ORDER123456', // Required: Unique order identifier
  transferAmount: 150000, // 150,000 IDR
  exchangeRate: 15000, // Optional: USD/IDR exchange rate
};

<X0PayComponent
  transactionParams={transactionParams}
  workerApiUrl="http://localhost:3000" // Required for order validation
  onSuccess={onSuccess}
  onError={onError}
/>

Validation States

Validating: Order ID is being checked
Available: Order ID is available for use (green indicator)
Exists: Order ID already exists (red indicator, transaction blocked)
Error: Validation failed (red indicator with error message)

Fee Management

The SDK now uses server-side fee calculation with automatic tiering based on transfer amount:

Fee Tiers

Tier 1: 10,000 - 4,999,999 IDR → 1% fee, minimum 2,000 IDR
Tier 2: 5,000,000 - 49,999,999 IDR → 0.75% fee, minimum 15,000 IDR
Tier 3: 50,000,000 - 200,000,000 IDR → 0.5% fee, minimum 50,000 IDR

Fee Calculation

Fees are always calculated as outer fees (added to transfer amount)
Total amount = Transfer Amount + Calculated Fee
Fee calculation is handled automatically by the X0-worker API

Example:

Transfer Amount: 150,000 IDR
Calculated Fee: 1,500 IDR (1% of 150,000 IDR)
Total Amount: 151,500 IDR

Transaction Parameters

interface X0PayTransactionParams {
  orderId: string; // Order identifier (required) - used for validation and tracking
  transferAmount: number; // Amount in IDR
  exchangeRate?: number; // Optional exchange rate (USD/IDR)
}

Order ID Requirements

Required: Every transaction must have a unique order ID
Validation: Order IDs are validated against the X0-worker API
Uniqueness: Order IDs must not have been used in previous transactions
Format: Order IDs can be any string format (alphanumeric, UUID, etc.)

Configuration

The SDK supports both default configurations and client-provided configurations. Client configurations can override or extend the default configurations.

Default Configuration

The SDK comes with pre-configured chains and tokens. If no custom configuration is provided, the SDK will use these defaults.

Client Configuration

You can provide custom chain and token configurations that override or extend the defaults:

import { X0PayComponent, X0PayClientConfig } from 'x0-react-sdk';

const clientConfig: X0PayClientConfig = {
  chains: [
    // Override existing chain
    {
      chainId: '0x89', // Polygon
      name: 'Polygon (Custom RPC)',
      rpcUrls: ['https://polygon-rpc.com/', 'https://rpc-mainnet.maticvigil.com/'],
      nativeCurrency: { name: 'Matic', symbol: 'MATIC', decimals: 18 },
      blockExplorerUrls: ['https://polygonscan.com/'],
    },
    // Add new chain
    {
      chainId: '0x1', // Ethereum mainnet
      name: 'Ethereum',
      rpcUrls: ['https://mainnet.infura.io/v3/YOUR-PROJECT-ID'],
      nativeCurrency: { name: 'Ether', symbol: 'ETH', decimals: 18 },
      blockExplorerUrls: ['https://etherscan.io/'],
    },
  ],
  chainTokenConfigs: [
    {
      chainId: '0x89', // Polygon
      chainName: 'Polygon (Custom RPC)',
      tokens: [
        {
          symbol: 'USDT',
          name: 'Tether USD (Custom)',
          address: '0xc2132D05D31c914a87C6611C10748AEb04B58e8F',
          decimals: 6,
          hypColAddress: '0x6316043b1EE191538A3903d95723506229B1e985',
        },
        // Add new token
        {
          symbol: 'USDC',
          name: 'USD Coin',
          address: '0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174',
          decimals: 6,
          hypColAddress: '0x1234567890123456789012345678901234567890',
        },
      ],
              hookAddress: '0x9B31d0eb6D852939Fe5A2BB8a66F3b5E6679A3a5',
        destinationDomain: 137,
    },
  ],
};

<X0PayComponent
  clientConfig={clientConfig}
  transactionParams={transactionParams}
  onSuccess={onSuccess}
  onError={onError}
/>

Legacy Configuration (Still Supported)

You can still provide custom configuration for specific transactions:

const config = {
  erc20TokenAddress: '0x...',
  hypColAddress: '0x...',
  recipient: '0x...',
  hookAddress: '0x...',
};

<X0PayComponent
  config={config}
  transactionParams={transactionParams}
  onSuccess={onSuccess}
  onError={onError}
/>

Configuration Manager

For advanced usage, you can use the configuration manager directly:

import { globalConfigManager, X0ConfigManager } from 'x0-react-sdk';

// Update global configuration
globalConfigManager.updateClientConfigs(clientChains, clientChainTokenConfigs);

// Or create a new instance
const configManager = new X0ConfigManager(clientChains, clientChainTokenConfigs);
const chains = configManager.getChains();
const configs = configManager.getChainTokenConfigs();

Recipient Address

The recipient address is automatically retrieved from the hook contract's vaultAddress() function and converted to bytes32 format for Hyperlane message compatibility. This ensures that the recipient is always up-to-date and matches the vault address configured in the hook contract.

Automatic Retrieval: The SDK automatically calls the hook contract to get the current vault address
Bytes Conversion: The address is automatically converted to bytes32 format using ethers.utils.hexZeroPad()
No Hardcoding: No need to hardcode recipient addresses in configurations
Dynamic Updates: If the vault address changes in the hook contract, the SDK will automatically use the new address

The recipient retrieval happens when:

A wallet is connected
The hook address is available in the configuration
The provider is ready to make contract calls

Note: The recipient is stored in bytes32 format (e.g., 0x00000000000000000000000076ad6ab8e9d4b10b27d949a414e9aa18c665ef9f) to ensure compatibility with Hyperlane message format.

Wallet Options

The SDK supports multiple wallet types with an intuitive UI for wallet selection.

Basic Usage (Auto-detect)

<X0PayComponent
  transactionParams={transactionParams}
  onSuccess={onSuccess}
  onError={onError}
/>

Enable WalletConnect with Project ID

<X0PayComponent
  transactionParams={transactionParams}
  onSuccess={onSuccess}
  onError={onError}
  walletConnectProjectId="YOUR_PROJECT_ID"
  enableWalletConnect={true}
/>

Wallet Selection Features

When enableWalletConnect is true, users can choose from:

Auto: Automatically selects the best wallet for the platform
MetaMask Web Extension: For desktop MetaMask users
Mobile Wallet (WalletConnect): For mobile wallet users

The SDK intelligently:

Shows only available wallet options
Handles chain switching for MetaMask
Provides QR codes for mobile wallets
Automatically detects the best wallet for the platform

Supported Networks

The SDK supports multiple blockchain networks including:

Polygon
Mumbai (Polygon Testnet)
Arbitrum
Optimism
Base
And more...

Exchange Rate

The SDK automatically fetches the current USD/IDR exchange rate from a reliable API. You can also provide a custom exchange rate in the transaction parameters.

Error Handling

The SDK provides comprehensive error handling for:

Network connection issues
Insufficient balance
Transaction failures
Exchange rate errors
Fee calculation errors
Wallet connection problems

Wallet Utilities

The SDK provides utility functions for wallet management:

import { 
  getAvailableWalletTypes, 
  createDefaultWalletConnectConfig,
  getRecommendedWalletType 
} from 'x0-react-sdk';

// Get available wallet types
const availableWallets = getAvailableWalletTypes(); // ['metamask', 'walletconnect']

// Get recommended wallet type for current platform
const recommendedWallet = getRecommendedWalletType(); // 'metamask' or 'walletconnect'

// Create default WalletConnect configuration
const walletConnectConfig = createDefaultWalletConnectConfig('YOUR_PROJECT_ID');

Styling

The SDK includes default styling that can be customized using CSS classes:

.x0pay-container
.x0pay-button
.x0pay-error
.x0pay-transaction-details

Development

To run the SDK in development mode:

cd X0-sdk
npm install
npm run dev

Testing

The test app demonstrates the new fee calculation functionality:

cd test-app
npm install
npm start

License

MIT License

Supported Token Addresses

Arbitrum One

USDC: 0xaf88d065e77c8cC2239327C5EDb3A432268e5831
- Hyperlane Collateral: 0x922D6956C99E12DFeB3224DEA977D0939758A1Fe
USDT: 0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9
- Hyperlane Collateral: 0x1234567890123456789012345678901234567890

Polygon

USDC: 0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174
- Hyperlane Collateral: 0x922D6956C99E12DFeB3224DEA977D0939758A1Fe
USDT: 0xc2132D05D31c914a87C6611C10748AEb04B58e8F
- Hyperlane Collateral: 0xabcdef1234567890abcdef1234567890abcdef12