One E-Wallet OTC UI Component Library

A React + TypeScript + Vite component library for OTC (Over-The-Counter) trading, providing OTC trading and withdrawal functionality components.

📦 Installation

npm install one-ewallet-otc-ui
# or
yarn add one-ewallet-otc-ui
# or
pnpm add one-ewallet-otc-ui

🔧 Dependencies

This component library requires the following peer dependencies. Please ensure they are installed in your project:

• react >= 18.2.0
• react-dom >= 18.2.0

Additionally, the component library uses the following dependencies internally. If your project also uses these libraries, it's recommended to use the same versions to avoid conflicts:

• @onelabs/dapp-kit ^0.15.5
• @tanstack/react-query ^5.83.0
• antd ^5.12.5
• axios ^1.13.2

🚀 Quick Start

1. Setup SuiClientProvider (Required)

Since the components use @onelabs/dapp-kit, you need to set up SuiClientProvider and QueryClientProvider at the top level of your application:

import { SuiClientProvider, createNetworkConfig } from '@onelabs/dapp-kit'
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import { OtcModal, Withdraw } from 'one-ewallet-otc-ui'

// Create Sui network configuration
const { networkConfig } = createNetworkConfig({
  mainnet: { url: 'https://fullnode.mainnet.sui.io:443' },
  testnet: { url: 'https://fullnode.testnet.sui.io:443' },
  devnet: { url: 'https://fullnode.devnet.sui.io:443' },
})

// Create React Query client
const queryClient = new QueryClient()

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <SuiClientProvider networks={networkConfig} defaultNetwork="mainnet">
        {/* Your app content */}
      </SuiClientProvider>
    </QueryClientProvider>
  )
}

2. Import Styles (Required)

Important: You must import the component library's styles in your application entry file:

// In your main.tsx or App.tsx
import 'one-ewallet-otc-ui/style.css'
// or
import 'one-ewallet-otc-ui/dist/style.css'

3. Using OtcModal Component

OtcModal is an OTC trading modal component:

import { OtcModal } from 'one-ewallet-otc-ui'

function MyComponent() {
  return (
    <OtcModal
      baseUrl="/api"                    // API base URL
      authToken="your-auth-token"       // User authentication token
      userAddress="user-sui-address"    // User Sui address
      lang="EN"                         // Language: 'ZH' | 'EN' | 'VI', default is 'EN'
    >
      <button>Open OTC Trading</button>
    </OtcModal>
  )
}

OtcModal Props

| Property | Type | Required | Default | Description | |----------|------|----------|----------|-------------| | children | React.ReactNode | ✅ | - | Element that triggers the modal to open | | baseUrl | string | ✅ | - | API base URL | | authToken | string | ✅ | - | User authentication token | | userAddress | string | ✅ | - | User Sui wallet address | | lang | 'ZH' \| 'EN' \| 'VI' | ❌ | 'EN' | Interface language | | channel | string | ❌ | 'RWA' |Interface channel | | currencyListApi | string | ❌ | '/ext/ewallet/currencyList' | Currency list API endpoint path | | getAddressApi | string | ❌ | '/ext/ewallet/getOtcAddress' | Get OTC address API endpoint path | | listRecordsApi | string | ❌ | '/ext/ewallet/list' | List records API endpoint path | | applyDepositApi | string | ❌ | '/ext/ewallet/applyDeposit' | Apply deposit API endpoint path | | defaultCurrency | string | ❌ | - | Default currency for deposit/recharge (e.g., 'USDH') |

4. Using Withdraw Component

Withdraw is a withdrawal component that requires SuiClient support:

import { Withdraw } from 'one-ewallet-otc-ui'
import { useSuiClient } from '@onelabs/dapp-kit'

function MyComponent() {
  const suiClient = useSuiClient()
  
  const handleWithdraw = (withdrawData: {
    network: string;      // Network/chain name
    currency: string;     // Payment token
    address: string;      // Withdrawal address
    amount: string;       // Withdrawal amount
    areaCode: string;     // Area code (for HPAY network)
    toCurrency: string;   // Token to receive
    minAmount: number;    // Minimum withdrawal amount
  }, callback: () => void) => {
    // Handle withdrawal logic
    console.log('Withdrawal data:', withdrawData)
    // Execute withdrawal operation...
    // Call callback when done
    callback()
  }

  return (
    <Withdraw
      baseUrl="/api"
      authToken="your-auth-token"
      userAddress="user-sui-address"
      suiClient={suiClient}
      tokenCoinTypeList={[
        { name: 'USDH', coinType: '0x72eba41c73c4c2ce2bcfc6ec1dc0896ba1b5c17bfe7ae7c6c779943f84912b41::usdh::USDH', decimals: 9 }
      ]}
      onSubmit={handleWithdraw}
      lang="EN"
      currencyListApi="/ext/ewallet/currencyList"
      getWithdrawAddressApi="/ext/ewallet/getWithdrawAddress"
      listRecordsApi="/ext/ewallet/list"
    >
      <button>Open Withdrawal</button>
    </Withdraw>
  )
}

Withdraw Props

| Property | Type | Required | Default | Description | |----------|------|----------|----------|-------------| | children | React.ReactNode | ✅ | - | Element that triggers the withdrawal modal to open | | baseUrl | string | ✅ | - | API base URL | | authToken | string | ✅ | - | User authentication token | | userAddress | string | ✅ | - | User Sui wallet address | | suiClient | ReturnType<typeof useSuiClient> | ✅ | - | SuiClient instance (obtained via useSuiClient() hook) | | tokenCoinTypeList | tokenCoinType[] | ✅ | - | Token coin type list, each item contains name, coinType, decimals | | onSubmit | (withdrawData: WithdrawData, callback: () => void) => void | ✅ | - | Withdrawal submit callback function | | lang | 'ZH' \| 'EN' \| 'VI' | ❌ | 'EN' | Interface language | | channel | string | ❌ | 'RWA' |Interface channel | | currencyListApi | string | ❌ | '/ext/ewallet/currencyList' | Currency list API endpoint path | | getWithdrawAddressApi | string | ❌ | '/ext/ewallet/getWithdrawAddress' | Get withdrawal address API endpoint path | | listRecordsApi | string | ❌ | '/ext/ewallet/list' | List records API endpoint path | | defaultCurrency | string | ❌ | - | Default currency for withdrawal (e.g., 'USDH') |

Type Definitions

tokenCoinType Interface:

interface tokenCoinType {
  name: string;      // Token name (e.g., 'USDH', 'USDT')
  coinType: string;  // Sui coin type (e.g., '0x72eba41c73c4c2ce2bcfc6ec1dc0896ba1b5c17bfe7ae7c6c779943f84912b41::usdh::USDH')
  decimals: number;  // Token decimal places (e.g., 9)
}

WithdrawData Interface:

The withdrawData parameter passed to onSubmit callback has the following structure:

interface WithdrawData {
  network: string;      // Network/chain name (e.g., 'HPAY', 'BSC', 'ETH', 'TRX')
  currency: string;     // Payment token (e.g., 'USDH')
  address: string;      // Withdrawal address
  amount: string;       // Withdrawal amount
  areaCode: string;     // Area code (for HPAY network, e.g., '+855')
  toCurrency: string;   // Token to receive (e.g., 'USDT', 'USD')
  minAmount: number;    // Minimum withdrawal amount
}

📝 Complete Example

import React from 'react'
import { createRoot } from 'react-dom/client'
import { SuiClientProvider, createNetworkConfig, useSuiClient } from '@onelabs/dapp-kit'
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import { OtcModal, Withdraw } from 'one-ewallet-otc-ui'
// Import styles
import 'one-ewallet-otc-ui/style.css'

// Create Sui network configuration
const { networkConfig } = createNetworkConfig({
  mainnet: { url: 'https://fullnode.mainnet.sui.io:443' },
  testnet: { url: 'https://fullnode.testnet.sui.io:443' },
  devnet: { url: 'https://fullnode.devnet.sui.io:443' },
})

const queryClient = new QueryClient()

// Inner component: use hook inside Provider
const AppContent = () => {
  const suiClient = useSuiClient()
  
  const handleWithdraw = (withdrawData: any, callback: () => void) => {
    console.log('Withdrawal data:', withdrawData)
    // Execute withdrawal logic...
    callback()
  }

  return (
    <div>
      <h1>My Application</h1>
      
      <OtcModal
        baseUrl="/api"
        authToken="your-auth-token"
        userAddress="0x..."
        lang="EN"
        channel="RWA"
        currencyListApi="/ext/ewallet/currencyList"
        getAddressApi="/ext/ewallet/getOtcAddress"
        listRecordsApi="/ext/ewallet/list"
        applyDepositApi="/ext/ewallet/applyDeposit"
      >
        <button>OTC Trading</button>
      </OtcModal>
      
      <Withdraw
        baseUrl="/api"
        authToken="your-auth-token"
        userAddress="0x..."
        suiClient={suiClient}
        tokenCoinTypeList={[
          { name: 'USDH', coinType: '0x72eba41c73c4c2ce2bcfc6ec1dc0896ba1b5c17bfe7ae7c6c779943f84912b41::usdh::USDH', decimals: 9 }
        ]}
        onSubmit={handleWithdraw}
        lang="EN"
        channel="RWA"
        currencyListApi="/ext/ewallet/currencyList"
        getWithdrawAddressApi="/ext/ewallet/getWithdrawAddress"
        listRecordsApi="/ext/ewallet/list"
      >
        <button>Withdraw</button>
      </Withdraw>
    </div>
  )
}

// Root component
const App = () => {
  return (
    <QueryClientProvider client={queryClient}>
      <SuiClientProvider networks={networkConfig} defaultNetwork="mainnet">
        <AppContent />
      </SuiClientProvider>
    </QueryClientProvider>
  )
}

createRoot(document.getElementById('root')!).render(<App />)

🎨 Styling

Important: You must import the component library's styles in your application entry file:

// In your main.tsx or App.tsx
import 'one-ewallet-otc-ui/style.css'
// or
import 'one-ewallet-otc-ui/dist/style.css'

The component library includes built-in styles written in SCSS. The styles are automatically bundled into dist/style.css during the build process. Make sure to import this CSS file in your application for the components to display correctly.

🔌 API Endpoints

The components require the following API endpoints. You can customize the API paths by passing the corresponding props:

OtcModal Required Endpoints

• POST {baseUrl}{currencyListApi} - Get currency list (default: /ext/ewallet/currencyList)
• POST {baseUrl}{getAddressApi} - Get OTC address (default: /ext/ewallet/getOtcAddress)
• POST {baseUrl}{listRecordsApi} - List transaction records (default: /ext/ewallet/list)
• POST {baseUrl}{applyDepositApi} - Apply deposit (default: /ext/ewallet/applyDeposit)

Withdraw Required Endpoints

• POST {baseUrl}{currencyListApi} - Get currency list (default: /ext/ewallet/currencyList)
• POST {baseUrl}{getWithdrawAddressApi} - Get withdrawal address (default: /ext/ewallet/getWithdrawAddress)
• POST {baseUrl}{listRecordsApi} - List transaction records (default: /ext/ewallet/list)

You can customize these endpoints by passing the corresponding API path props to the components.

🛠️ Development

# Install dependencies
npm install

# Start development server
npm run dev

# Build
npm run build

# Preview build
npm run preview

⚠️ Troubleshooting

Error: Cannot read properties of undefined (reading 'ReactCurrentDispatcher')

这个错误通常是由于 React 版本不匹配或存在多个 React 实例导致的。解决方法：

1. 确保 React 版本匹配

确保你的项目使用的 React 版本与组件库的 peerDependencies 匹配（React >= 18.2.0）：

# 检查 React 版本
npm list react react-dom

# 如果版本不匹配，更新到正确版本
npm install react@^18.2.0 react-dom@^18.2.0

2. 解决多个 React 实例问题

如果项目中存在多个 React 实例，可以使用以下方法解决：

使用 npm/yarn/pnpm 的 resolutions/overrides：

在 package.json 中添加：

{
  "resolutions": {
    "react": "^18.2.0",
    "react-dom": "^18.2.0"
  }
}

或者使用 npm overrides（npm 8.3+）：

{
  "overrides": {
    "react": "^18.2.0",
    "react-dom": "^18.2.0"
  }
}

3. 检查 node_modules

删除 node_modules 和锁文件，重新安装：

rm -rf node_modules package-lock.json
npm install

4. 确保正确导入样式

确保在项目入口文件中导入了组件库的样式：

import 'one-ewallet-otc-ui/style.css'

5. Next.js 项目特殊处理

如果使用 Next.js，可能需要配置 next.config.js：

module.exports = {
  webpack: (config) => {
    config.resolve.alias = {
      ...config.resolve.alias,
      react: require.resolve('react'),
      'react-dom': require.resolve('react-dom'),
    }
    return config
  },
}

📝 Changelog

Latest Updates

1. 支持越南语 (Vietnamese Language Support)

• 新增支持 'VI' 语言选项
• OtcModal 和 Withdraw 组件现在都支持 lang="VI" 参数
• 所有界面文本已翻译为越南语

2. 接口路径可配置化 (Configurable API Endpoints)

• OtcModal 组件新增以下可选参数：

  • currencyListApi: 币种列表接口路径（默认: '/ext/ewallet/currencyList'）
  • getAddressApi: 获取OTC地址接口路径（默认: '/ext/ewallet/getOtcAddress'）
  • listRecordsApi: 交易记录列表接口路径（默认: '/ext/ewallet/list'）
  • applyDepositApi: 申请充值接口路径（默认: '/ext/ewallet/applyDeposit'）

• Withdraw 组件新增以下可选参数：

  • currencyListApi: 币种列表接口路径（默认: '/ext/ewallet/currencyList'）
  • getWithdrawAddressApi: 获取提现地址接口路径（默认: '/ext/ewallet/getWithdrawAddress'）
  • listRecordsApi: 交易记录列表接口路径（默认: '/ext/ewallet/list'）

• Withdraw 组件参数变更：

  • USDH_COIN_TYPE 和 USDH_DECIMALS 已合并为 tokenCoinTypeList 参数
  • tokenCoinTypeList 类型为 tokenCoinType[]，支持多个代币配置
  • 每个 tokenCoinType 包含：name（代币名称）、coinType（代币类型）、decimals（小数位数）

• onSubmit 回调参数类型：

  • withdrawData 参数现在有明确的类型定义，包含以下字段：
    • network: 网络/链名称
    • currency: 支付代币
    • address: 提现地址
    • amount: 提现金额
    • areaCode: 区号（HPAY网络使用）
    • toCurrency: 接收代币
    • minAmount: 最小提现金额

3. 新增 defaultCurrency 参数 (New defaultCurrency Prop)

• OtcModal 和 Withdraw 组件新增 defaultCurrency 可选参数
• 用于指定进入页面时默认选中的充值或提现币种（例如：defaultCurrency="USDH"）

📄 License

MIT

🤝 Contributing

Issues and Pull Requests are welcome!