@web3jskit/walletkit 0.4.5 → 0.5.1

package/README.md

@@ -1,213 +1,562 @@
-# WalletKit
+# @web3jskit/walletkit
 
-**WalletKit** 是一个轻量级的多链钱包连接工具包，旨在帮助开发者快速集成支持多条链的钱包插件，如 MetaMask、Phantom、TronLink、Gel Wallet 等。它提供了便捷的状态管理、自定义 Hooks 和统一的 API，使 DApp 开发更简单高效。
+A powerful React component library for multi-chain wallet connections, supporting EVM, Solana, Tron, and BTC blockchains with a unified API interface.
 
-**WalletKit** is a lightweight, multi-chain compatible wallet connection toolkit designed to help developers quickly integrate wallet plugins that support multiple chains, such as MetaMask, Phantom, TronLink, Gel Wallet, and more. It provides convenient state management, custom hooks, and a unified API, making DApp development simpler and more efficient.
+## Features
 
-## 架构 Architecture
+- 🔗 **Multi-Chain Support**: EVM, Solana, Tron, and BTC blockchains
+- 💼 **Wallet Connectors**: Support for MetaMask, OKX Wallet, Phantom, TronLink, Trust Wallet, Bitget Wallet, TokenPocket, and GelWallet
+- 🎨 **Theme & i18n**: Built-in dark/light theme switching and multilingual support (8 languages)
+- 📱 **Responsive Design**: Mobile-first design with desktop optimization
+- 🔄 **Auto Reconnection**: Automatic wallet reconnection on page refresh
+- 📝 **Contract Interaction**: Built-in contract read/write and multicall support
+- 🌐 **RPC Support**: Direct RPC calls without wallet connection
+- 🌍 **Domain Resolution**: ENS domain name resolution and reverse lookup
+- 🎯 **TypeScript**: Full TypeScript support with comprehensive type definitions
+- ⚡ **Performance**: Optimized bundle size with tree-shaking support
 
-WalletKit 由两个主要部分组成 / WalletKit consists of two main parts:
+## Installation
 
-1. **@web3jskit/wallethelper**: 底层钱包连接库，提供统一的钱包接口和状态管理 / Core wallet connection library providing unified wallet interfaces and state management
-
-   - 多链支持 / Multi-chain support (EVM, PUT, SOL, Tron, BTC)
-   - 钱包检测和连接 / Wallet detection and connection
-   - 统一的交易接口 / Unified transaction interface
-   - 状态管理 / State management
-
-2. **@web3jskit/walletkit**: React 组件库，提供开箱即用的 UI 组件 / React component library providing ready-to-use UI components
-   - 钱包连接按钮 / Wallet connection button
-   - 钱包选择模态框 / Wallet selection modal
-   - 链切换组件 / Chain switching component
-   - 自定义 Hooks / Custom hooks
-
-## 安装 Installation
-
-通过 npm、yarn 或 pnpm 安装 / Install via npm, yarn, or pnpm:
+### NPM Install
 
 ```bash
-# npm
 npm install @web3jskit/walletkit
-
-# yarn
+# or
 yarn add @web3jskit/walletkit
-
-# pnpm
+# or
 pnpm add @web3jskit/walletkit
 ```
 
-## 快速开始 Quick Start
+### CDN Import (UMD Format)
+
+```html
+<!-- Import styles -->
+<link rel="stylesheet" href="https://unpkg.com/@web3jskit/walletkit@latest/dist/style.css">
+
+<!-- Import React and ReactDOM -->
+<script crossorigin src="https://unpkg.com/react@18/umd/react.production.min.js"></script>
+<script crossorigin src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js"></script>
+
+<!-- Import WalletKit UMD version -->
+<script src="https://unpkg.com/@web3jskit/walletkit@latest/dist/index.umd.js"></script>
+
+<script>
+  const { WalletKitProvider, ConnectButton, useWalletKit, ChainType } = WalletKit;
+
+  // Use WalletKit components
+  function App() {
+    const { walletAddress, connect, disconnect } = useWalletKit();
+
+    return React.createElement('div', null, [
+      React.createElement('h1', null, 'WalletKit Example'),
+      React.createElement('p', null, `Wallet Address: ${walletAddress || 'Not Connected'}`),
+      React.createElement(ConnectButton)
+    ]);
+  }
+
+  ReactDOM.render(
+    React.createElement(WalletKitProvider, {
+      language: 'en',
+      defaultChainType: ChainType.EVM
+    }, React.createElement(App)),
+    document.getElementById('root')
+  );
+</script>
+```
+
+## Quick Start
 
-### 1. 导入并初始化 Import and Initialize
+### Basic Usage
 
-```javascript
-import { WalletKitProvider, ConnectButton } from '@web3jskit/walletkit';
+```tsx
+import { WalletKitProvider, ConnectButton, useWalletKit } from '@web3jskit/walletkit';
+// Import styles (required)
+import '@web3jskit/walletkit/style.css';
 
 function App() {
-	return (
-		<WalletKitProvider>
-			<ConnectButton />
-			{/* 其他组件 Other components */}
-		</WalletKitProvider>
-	);
+  return (
+    <WalletKitProvider>
+      <YourApp />
+    </WalletKitProvider>
+  );
+}
+
+function YourApp() {
+  const { connect, walletAddress, currentChainType, disconnect } = useWalletKit();
+
+  return (
+    <div>
+      <ConnectButton />
+      {walletAddress ? (
+        <div>
+          <p>Wallet connected: {walletAddress}</p>
+          <button onClick={disconnect}>Disconnect</button>
+        </div>
+      ) : (
+        <button onClick={connect}>Connect Wallet</button>
+      )}
+      <div>Current chain type: {currentChainType}</div>
+    </div>
+  );
 }
 ```
 
-### 2. 使用 Hooks Use Hooks
+> ⚠️ **Important**: Always import the CSS file `@web3jskit/walletkit/style.css` for proper styling.
 
-```javascript
-import { useWalletKit } from '@web3jskit/walletkit';
+## Styling
+
+The library includes built-in styles that are automatically loaded when you import the CSS file. The styles support both light and dark themes and are fully responsive.
+
+### CSS Import Methods
+
+```tsx
+// Method 1: Direct import (recommended)
+import '@web3jskit/walletkit/style.css';
+
+// Method 2: Import from dist
+import '@web3jskit/walletkit/dist/style.css';
+```
+
+### Theme Variables
 
-function MyComponent() {
-	const { openModal, currentChainType, setChainType, currentConnector, walletAddress, getProvider } = useWalletKit();
-
-	// 连接钱包 Connect wallet
-	const handleConnect = () => {
-		openModal(AppModal.ConnectModal);
-	};
-
-	// 断开连接 Disconnect
-	const handleDisconnect = () => {
-		currentConnector?.disconnect();
-	};
-
-	return (
-		<div>
-			<div>Chain: {currentChainType}</div>
-			<div>Wallet: {currentConnector?.name}</div>
-			<div>Address: {walletAddress}</div>
-		</div>
-	);
+The library uses CSS custom properties for theming. You can override these variables to customize the appearance:
+
+```css
+:root {
+  --walletkit-primary-color: #1890ff;
+  --walletkit-text-color: rgba(0, 0, 0, 0.88);
+  --walletkit-background-color: #ffffff;
+  /* ... more variables */
 }
 ```
 
-## 核心功能 Core Features
+## API Documentation
+
+### Components
+
+#### WalletKitProvider
+
+Provides wallet connection context. Must wrap your app at the top level.
+
+```tsx
+<WalletKitProvider
+  language="en" // Language: supports zh, en, ja, ko, ms, th, vi, zhTW
+  theme="light" // Theme: supports dark, light
+  defaultChainType={ChainType.EVM}
+  defaultChainId={1}
+  reconnect={true}
+  supportWallets={[]}
+  customEvmNetworks={[]}
+  showNetwork={true}
+  allowSwitchWallet={true}
+  productName="My App"
+>
+  <YourApp />
+</WalletKitProvider>
+```
 
-### 1. 钱包连接 Wallet Connection
+##### Props
 
-```javascript
-const { currentConnector, connectStatus } = useWalletKit();
+| Name                | Type                                              | Default         | Description                  |
+|---------------------|---------------------------------------------------|-----------------|------------------------------|
+| language            | 'zh'\|'en'\|'ja'\|'ko'\|'ms'\|'th'\|'vi'\|'zhTW' | 'zh'            | UI language                  |
+| theme               | 'dark'\|'light'                                   | 'light'         | Theme                        |
+| defaultChainType    | ChainType                                         | ChainType.EVM   | Default chain type           |
+| defaultChainId      | number                                            | 1               | Default chain ID             |
+| reconnect           | boolean                                           | true            | Auto reconnect last wallet   |
+| supportWallets      | SupportWallet[]                                   | all supported   | Supported wallet types       |
+| customEvmNetworks   | NetworkInfo[]                                     | []              | Custom EVM network list      |
+| showNetwork         | boolean                                           | false           | Show network switch          |
+| allowSwitchWallet   | boolean                                           | false           | Allow switching wallet       |
+| productName         | string                                            | undefined       | Product name for powered by   |
 
-// 连接钱包 Connect wallet
-await currentConnector.connect();
+#### ConnectButton
 
-// 断开连接 Disconnect
-await currentConnector.disconnect();
+Built-in wallet connect button component with responsive design.
 
-// 监听状态 Listen to status
-console.log(connectStatus); // 'connected' | 'connecting' | 'disconnected'
+```tsx
+<ConnectButton />
 ```
 
-### 2. 链切换 Chain Switching
+#### ConnectModal
 
-```javascript
-const { setChainType, currentChainType } = useWalletKit();
+Modal component for wallet selection and connection.
 
-// 切换链 Switch chain
-await setChainType(ChainType.EVM);
+```tsx
+<ConnectModal />
 ```
 
-### 3. 交易操作 Transaction Operations
+#### ThemeToggle
 
-```javascript
-const { currentConnector } = useWalletKit();
+Theme switching component.
 
-// 签名消息 Sign message
-const signature = await currentConnector.signMessage('Hello Web3');
+```tsx
+<ThemeToggle />
+```
 
-// 发送交易 Send transaction
-const txHash = await currentConnector.sendTransaction({
- to: '0x...',
- value: '0x...',
-});
+- See below for `ChainType`, `SupportWallet`, and `NetworkInfo` type definitions.
+
+### Hooks
+
+#### useWalletKit
+
+Provides all wallet connection state and methods.
+
+```tsx
+const {
+  connect,                // Connect wallet
+  disconnect,             // Disconnect wallet
+  currentChainType,       // Current chain type
+  setChainType,           // Set chain type
+  currentConnector,       // Current connector instance
+  theme,                  // Current theme
+  toggleTheme,            // Switch theme
+  language,               // Current language
+  setLanguage,            // Set language
+  walletAddress,          // Wallet address
+  currentNetwork,         // Current network info
+  setCurrentNetwork,      // Set current network
+  getProvider,            // Get provider
+  provider,               // Provider instance
+  showWalletInfo,         // Show wallet info modal
+  signMessage,            // Sign message
+  signTransaction,        // Sign transaction
+  sendTransaction,        // Send transaction
+  readContract,           // Read contract
+  writeContract,          // Write contract
+  multicall,              // Batch contract calls
+  switchNetwork,          // Switch network
+  waitForTransactionReceipt, // Wait for transaction receipt
+  getSupportNets          // Get supported network list
+} = useWalletKit();
+```
 
-// 合约调用 Contract call
-const result = await currentConnector.writeContract({
- address: '0x...',
- abi: [...],
- functionName: 'transfer',
- args: [...],
-});
+### Main API
+
+#### Connect & Disconnect
+
+- `connect()`: Connect wallet, returns Promise`<Connector>`
+- `disconnect()`: Disconnect wallet
+- `getProvider()`: Get current provider instance
+
+#### Chain & Network Management
+
+- `currentChainType`: Current chain type (EVM, SOL, Tron, BTC)
+- `setChainType(chainType)`: Set chain type
+- `currentNetwork`: Current network info
+- `setCurrentNetwork(networkId)`: Set current network
+- `switchNetwork(chainId)`: Switch network
+- `getSupportNets()`: Get supported network list
+
+#### Transaction & Contract
+
+- `signMessage(message)`: Sign message
+- `signTransaction(tx)`: Sign transaction
+- `sendTransaction(tx)`: Send transaction
+- `readContract(params)`: Read contract data
+- `writeContract(params)`: Write contract data
+- `multicall(calls, option)`: Batch contract calls
+- `waitForTransactionReceipt(hash, timeout?)`: Wait for transaction receipt
+
+#### UI Related
+
+- `theme`: Current theme
+- `toggleTheme()`: Switch theme
+- `language`: Current language
+- `setLanguage(lang)`: Set language
+- `showWalletInfo()`: Show wallet info modal
+
+#### Advanced Usage
+
+- `readContractRpc(params)`: Read contract directly via RPC (no wallet connection required)
+- `multicallRpc(calls, option)`: Batch read contracts via RPC
+- `evmSilentConnect(walletType, chainId)`: EVM silent connect
+- `getWalletKit()`: Get global walletKit instance (for non-React usage)
+
+## Type Definitions
+
+### Theme Type
+
+- `Theme`: 'dark' | 'light'
+
+### Language Type
+
+- `Locals`: 'zh' | 'en' | 'ja' | 'ko' | 'ms' | 'th' | 'vi' | 'zhTW'
+
+### Chain Type
+
+```ts
+import { ChainType } from '@web3jskit/walletkit';
+// ChainType.EVM    // EVM-compatible chains
+// ChainType.SOL    // Solana chain
+// ChainType.Tron   // Tron chain
+// ChainType.BTC    // Bitcoin chain
 ```
 
-## 支持的钱包 Supported Wallets
+### Wallet Type
 
-- MetaMask (EVM)
-- Phantom (SOL, BTC)
-- TronLink (TRON)
-- Gel Wallet (EVM, PUT, SOL)
-- OKX Wallet (EVM)
-- Trust Wallet (EVM)
-- TokenPocket (EVM)
-- Bitget Wallet (EVM)
-- Coinbase Wallet (EVM)
+```ts
+import { SupportWallet } from '@web3jskit/walletkit';
+// e.g. SupportWallet.METAMASK, SupportWallet.OKX_WALLET, etc.
+```
 
-## API 参考 API Reference
+### Network Type
 
-### useWalletKit Hook
+```ts
+import type { NetworkInfo } from '@web3jskit/walletkit';
+// chainId, chainName, rpcUrls, nativeCurrency, blockExplorerUrls, etc.
+```
 
-| 属性/方法 Property/Method | 描述 Description                        |
-| ------------------------- | --------------------------------------- |
-| `currentChainType`        | 当前链类型 Current chain type           |
-| `setChainType`            | 切换链类型 Switch chain type            |
-| `currentConnector`        | 当前钱包连接器 Current wallet connector |
-| `connectStatus`           | 连接状态 Connection status              |
-| `walletAddress`           | 钱包地址 Wallet address                 |
-| `getProvider`             | 获取 Provider Get provider              |
-| `openModal`               | 打开模态框 Open modal                   |
-| `closeModal`              | 关闭模态框 Close modal                  |
+## Supported Wallets
 
-### WalletConnector
+### EVM Wallets
 
-| 方法 Method             | 描述 Description          |
-| ----------------------- | ------------------------- |
-| `connect()`             | 连接钱包 Connect wallet   |
-| `disconnect()`          | 断开连接 Disconnect       |
-| `signMessage(message)`  | 签名消息 Sign message     |
-| `sendTransaction(tx)`   | 发送交易 Send transaction |
-| `writeContract(params)` | 合约写入 Write contract   |
-| `readContract(params)`  | 合约读取 Read contract    |
+- MetaMask
+- OKX Wallet
+- Trust Wallet
+- Bitget Wallet
+- TokenPocket
+- GelWallet
 
-## 贡献指南 Contributing
+### Solana Wallets
 
-欢迎提交 Issues 和功能请求！贡献步骤：
+- Phantom
+- OKX Wallet
+- Bitget Wallet
+- GelWallet
 
-We welcome issues and feature requests! Steps to contribute:
+### Tron Wallets
 
-1. Fork 本仓库 Fork this repository
-2. 创建功能分支 Create feature branch:
+- TronLink
+- OKX Wallet
+- GelWallet
 
-```bash
-git checkout -b feature/my-feature
+### Bitcoin Wallets
+
+- Phantom
+
+## Examples
+
+### Switch Chain Type
+
+```tsx
+import { ChainType, useWalletKit } from '@web3jskit/walletkit';
+
+function ChainSwitcher() {
+  const { setChainType, currentChainType } = useWalletKit();
+  return (
+    <div>
+      <button onClick={() => setChainType(ChainType.EVM)}>Switch to EVM</button>
+      <button onClick={() => setChainType(ChainType.SOL)}>Switch to Solana</button>
+      <button onClick={() => setChainType(ChainType.Tron)}>Switch to Tron</button>
+      <button onClick={() => setChainType(ChainType.BTC)}>Switch to BTC</button>
+      <div>Current chain type: {currentChainType}</div>
+    </div>
+  );
+}
 ```
 
-3. 提交更改 Commit changes:
+### Switch Network
 
-```bash
-git commit -m "Add some feature"
+```tsx
+import { useWalletKit } from '@web3jskit/walletkit';
+
+function NetworkSwitcher() {
+  const { getSupportNets, switchNetwork, setCurrentNetwork, provider, currentNetwork } = useWalletKit();
+  return (
+    <div>
+      <h3>Switch Network</h3>
+      <div>
+        {getSupportNets().map((net) => (
+          <button
+            key={net.chainId}
+            onClick={async () => {
+              if (provider) {
+                await switchNetwork(net.chainId);
+              } else {
+                setCurrentNetwork(net.chainId);
+              }
+            }}
+          >
+            Switch to {net.chainName}
+          </button>
+        ))}
+      </div>
+      <div>Current network: {currentNetwork?.chainName}</div>
+    </div>
+  );
+}
 ```
 
-4. 推送分支 Push branch:
+### Contract Interaction
 
-```bash
-git push origin feature/my-feature
+```tsx
+import { useWalletKit } from '@web3jskit/walletkit';
+
+function ContractInteraction() {
+  const { readContract, writeContract, multicall } = useWalletKit();
+
+  const handleReadContract = async () => {
+    const result = await readContract({
+      address: '0x...', // Contract address
+      abi: [...], // Contract ABI
+      functionName: 'balanceOf',
+      args: ['0x...'] // Arguments
+    });
+    console.log('Read result:', result);
+  };
+
+  const handleWriteContract = async () => {
+    const result = await writeContract({
+      address: '0x...', // Contract address
+      abi: [...], // Contract ABI
+      functionName: 'transfer',
+      args: ['0x...', 1000000] // Arguments
+    });
+    console.log('Write result:', result);
+  };
+
+  const handleMulticall = async () => {
+    const result = await multicall(
+      [
+        {
+          address: '0x...',
+          abi: [...],
+          functionName: 'balanceOf',
+          args: ['0x...']
+        },
+        {
+          address: '0x...',
+          abi: [...],
+          functionName: 'totalSupply'
+        }
+      ],
+      {
+        multicallAddress: '0x...',
+        multicallAbi: [...]
+      }
+    );
+    console.log('Batch call result:', result);
+  };
+
+  return (
+    <div>
+      <button onClick={handleReadContract}>Read Contract</button>
+      <button onClick={handleWriteContract}>Write Contract</button>
+      <button onClick={handleMulticall}>Batch Call</button>
+    </div>
+  );
+}
 ```
 
-5. 提交 Pull Request Submit Pull Request
+### Direct RPC Contract Calls
+
+```tsx
+import { readContractRpc, multicallRpc } from '@web3jskit/walletkit';
 
-## 许可证 License
+// Single contract read
+const res = await readContractRpc({
+  abi: [...],
+  address: '0x...',
+  functionName: 'balanceOf',
+  args: ['0x...'],
+  rpcUrl: 'https://<your-rpc-url>'
+});
+
+// Batch contract read
+const res2 = await multicallRpc(
+  [
+    {
+      address: '0x...',
+      abi: [...],
+      functionName: 'totalSupply'
+    },
+    {
+      address: '0x...',
+      abi: [...],
+      functionName: 'balanceOf',
+      args: ['0x...']
+    }
+  ],
+  {
+    multicallAddress: '0x...',
+    multicallAbi: [...],
+    rpcUrl: 'https://<your-rpc-url>'
+  }
+);
+```
 
-MIT License
+### Theme & Language (i18n)
+
+```tsx
+import { useWalletKit, supportedLanguages } from '@web3jskit/walletkit';
+import type { Locals } from '@web3jskit/walletkit';
+
+function ThemeAndLanguage() {
+  const { theme, toggleTheme, language, setLanguage } = useWalletKit();
+  return (
+    <div>
+      <div>Current theme: {theme}, current language: {language}</div>
+      <div>
+        <button onClick={() => toggleTheme()}>Switch Theme</button>
+        <select
+          value={language}
+          onChange={e => setLanguage(e.target.value as Locals)}
+        >
+          {supportedLanguages.map(lng => (
+            <option key={lng} value={lng}>
+              {lng}
+            </option>
+          ))}
+        </select>
+      </div>
+    </div>
+  );
+}
+```
 
-## 联系我们 Contact Us
+> `supportedLanguages` is the built-in language list, suitable for rendering language selection options dynamically.
 
-如有问题或建议，请通过以下方式联系我们：
+### Event Listening
 
-For questions or suggestions, please contact us:
+```tsx
+import { useEffect } from 'react';
+import { useWalletKit } from '@web3jskit/walletkit';
 
-- GitHub Issues
-- Email: <support@web3jskit.com>
+function EventListener() {
+  const { currentConnector } = useWalletKit();
+  useEffect(() => {
+    const handleConnect = (address) => {
+      console.log('Wallet connected:', address);
+    };
+    const handleChainChanged = (chainId) => {
+      console.log('Chain changed:', chainId);
+    };
+    const handleAccountChanged = (address) => {
+      console.log('Account changed:', address);
+    };
+    const handleDisconnect = () => {
+      console.log('Wallet disconnected');
+    };
+    if (currentConnector) {
+      currentConnector.on('connect', handleConnect);
+      currentConnector.on('chainChanged', handleChainChanged);
+      currentConnector.on('accountsChanged', handleAccountChanged);
+      currentConnector.on('disconnect', handleDisconnect);
+    }
+    return () => {
+      if (currentConnector) {
+        currentConnector.off('connect', handleConnect);
+        currentConnector.off('chainChanged', handleChainChanged);
+        currentConnector.off('accountsChanged', handleAccountChanged);
+        currentConnector.off('disconnect', handleDisconnect);
+      }
+    };
+  }, [currentConnector]);
+  return <div>Event listener example</div>;
+}
+```
 
-希望你喜欢使用 WalletKit！
+## License
 
-Hope you enjoy using WalletKit! 😊
+MIT