@tokenup/walletkit

一个强大的多链多钱包连接组件，支持 EVM、Solana、Tron 和 BTC 等多种区块链网络。

特性

• 支持多种区块链网络：EVM、Solana、Tron、BTC
• 支持多种主流钱包连接器
• 提供统一的 API 接口
• 支持主题切换和多语言（国际化）
• 内置多链交易与合约交互能力
• 支持批量调用（multicall）
• 响应式设计，适配移动端和桌面端

安装

npm install @tokenup/walletkit
# 或
yarn add @tokenup/walletkit
# 或
pnpm add @tokenup/walletkit

快速开始

基本用法

import { WalletKitProvider, ConnectButton, useWalletKit } from '@tokenup/walletkit';

function App() {
  return (
    <WalletKitProvider>
      <YourApp />
    </WalletKitProvider>
  );
}

function YourApp() {
  const { connect, walletAddress, currentChainType } = useWalletKit();

  return (
    <div>
      <ConnectButton />
      {walletAddress ? (
        <div>已连接钱包: {walletAddress}</div>
      ) : (
        <button onClick={connect}>连接钱包</button>
      )}
      <div>当前链类型: {currentChainType}</div>
    </div>
  );
}

⚠️ 如遇到模块解析错误，请确保 tsconfig.json 中 esModuleInterop 和 allowSyntheticDefaultImports 都为 true，或使用 dynamic 导入方式。

API 文档

组件

WalletKitProvider

提供钱包连接上下文，必须包裹在应用最外层。

<WalletKitProvider
  language="zh" // 多语言，支持 zh、en、ja、ko、ms、th、vi、zhTW
  theme="darkMode" // 主题，支持 darkMode、lightMode
  defaultChainType={ChainType.EVM}
  defaultChainId={1}
  reconnect={true}
  connectButtonSlots={[]}
  supportWallets={[]}
  customEvmNetworks={[]}
  showNetwork={true}
  allowSwitchWallet={true}
>
  <YourApp />
</WalletKitProvider>

参数

| 参数名 | 类型 | 默认值 | 描述 | |---------------------|---------------------------------------------------|------------------|------------------------------| | language | 'zh'|'en'|'ja'|'ko'|'ms'|'th'|'vi'|'zhTW' | 'zh' | 界面语言 | | theme | 'darkMode'|'lightMode' | 'lightMode' | 主题 | | defaultChainType | ChainType | ChainType.EVM | 默认链类型 | | defaultChainId | number | 1 | 默认链 ID | | reconnect | boolean | true | 是否自动重连 | | connectButtonSlots | ReactNode[] | [] | 连接按钮自定义插槽 | | supportWallets | SupportWallet[] | 全部支持 | 支持的钱包类型 | | customEvmNetworks | NetworkInfo[] | [] | 自定义 EVM 网络列表 | | showNetwork | boolean | false | 是否显示网络切换 | | allowSwitchWallet | boolean | false | 是否允许切换钱包 |

• ChainType、SupportWallet、NetworkInfo 类型见下文。

ConnectButton

内置钱包连接按钮组件。

<ConnectButton />

Hooks

useWalletKit

提供钱包连接相关的所有状态和方法。

const {
  connect,                // 连接钱包
  disconnect,             // 断开钱包
  currentChainType,       // 当前链类型
  setChainType,           // 设置链类型
  currentConnector,       // 当前连接器实例
  theme,                  // 当前主题
  toggleTheme,            // 切换主题
  language,               // 当前语言
  setLanguage,            // 设置语言
  walletAddress,          // 钱包地址
  currentNetwork,         // 当前网络信息
  setCurrentNetwork,      // 设置当前网络
  getProvider,            // 获取 provider
  provider,               // provider 实例
  showWalletInfo,         // 显示钱包信息弹窗
  signMessage,            // 签名消息
  signTransaction,        // 签名交易
  sendTransaction,        // 发送交易
  readContract,           // 读取合约
  writeContract,          // 写入合约
  multicall,              // 批量调用合约
  switchNetwork,          // 切换网络
  waitForTransactionReceipt, // 等待交易收据
  getSupportNets          // 获取支持的网络列表
} = useWalletKit();

主要 API 说明

连接与断开

• connect(): 连接钱包，返回 Promise<Connector>
• disconnect(): 断开钱包连接
• getProvider(): 获取当前 provider 实例

链和网络管理

• currentChainType: 当前链类型 (EVM, SOL, Tron, BTC)
• setChainType(chainType): 设置链类型
• currentNetwork: 当前网络信息
• setCurrentNetwork(networkId): 设置当前网络
• switchNetwork(chainId): 切换网络
• getSupportNets(): 获取支持的网络列表

交易与合约

• signMessage(message): 签名消息
• signTransaction(tx): 签名交易
• sendTransaction(tx): 发送交易
• readContract(params): 读取合约数据
• writeContract(params): 写入合约数据
• multicall(calls, option): 批量调用合约
• waitForTransactionReceipt(hash, timeout?): 等待交易收据

UI 相关

• theme: 当前主题
• toggleTheme(): 切换主题
• language: 当前语言
• setLanguage(lang): 设置语言
• showWalletInfo(): 显示钱包信息弹窗

其他高级用法

• readContractRpc(params): 直接通过 RPC 读取合约（无需连接钱包）
• multicallRpc(calls, option): 直接通过 RPC 批量读取合约
• evmSilentConnect(walletType, chainId): EVM 静默连接
• getWalletKit(): 获取全局 walletKit 实例（适合非 React 场景）

类型说明

主题类型

• Theme: 'darkMode' | 'lightMode'

语言类型

• Locals: 'zh' | 'en' | 'ja' | 'ko' | 'ms' | 'th' | 'vi' | 'zhTW'

链类型

import { ChainType } from '@tokenup/walletkit';
// ChainType.EVM    // 以太坊虚拟机链
// ChainType.SOL    // Solana 链
// ChainType.Tron   // Tron 链
// ChainType.BTC    // 比特币链

钱包类型

import { SupportWallet } from '@tokenup/walletkit';
// 例如：SupportWallet.METAMASK、SupportWallet.OKX_WALLET 等

网络类型

import type { NetworkInfo } from '@tokenup/walletkit';
// chainId, chainName, rpcUrls, nativeCurrency, blockExplorerUrls 等

示例

切换链类型

import { ChainType, useWalletKit } from '@tokenup/walletkit';

function ChainSwitcher() {
  const { setChainType, currentChainType } = useWalletKit();
  return (
    <div>
      <button onClick={() => setChainType(ChainType.EVM)}>切换到EVM</button>
      <button onClick={() => setChainType(ChainType.SOL)}>切换到Solana</button>
      <button onClick={() => setChainType(ChainType.Tron)}>切换到Tron</button>
      <button onClick={() => setChainType(ChainType.BTC)}>切换到BTC</button>
      <div>当前链类型: {currentChainType}</div>
    </div>
  );
}

切换网络

import { useWalletKit } from '@tokenup/walletkit';

function NetworkSwitcher() {
  const { getSupportNets, switchNetwork, setCurrentNetwork, provider, currentNetwork } = useWalletKit();
  return (
    <div>
      <h3>切换网络</h3>
      <div>
        {getSupportNets().map((net) => (
          <button
            key={net.chainId}
            onClick={async () => {
              if (provider) {
                await switchNetwork(net.chainId);
              } else {
                setCurrentNetwork(net.chainId);
              }
            }}
          >
            切换到 {net.chainName}
          </button>
        ))}
      </div>
      <div>当前网络: {currentNetwork?.chainName}</div>
    </div>
  );
}

合约交互

import { useWalletKit } from '@tokenup/walletkit';

function ContractInteraction() {
  const { readContract, writeContract, multicall } = useWalletKit();

  const handleReadContract = async () => {
    const result = await readContract({
      address: '0x...', // 合约地址
      abi: [...], // 合约ABI
      functionName: 'balanceOf',
      args: ['0x...'] // 参数
    });
    console.log('读取结果:', result);
  };

  const handleWriteContract = async () => {
    const result = await writeContract({
      address: '0x...', // 合约地址
      abi: [...], // 合约ABI
      functionName: 'transfer',
      args: ['0x...', 1000000] // 参数
    });
    console.log('写入结果:', 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('批量调用结果:', result);
  };

  return (
    <div>
      <button onClick={handleReadContract}>读取合约</button>
      <button onClick={handleWriteContract}>写入合约</button>
      <button onClick={handleMulticall}>批量调用</button>
    </div>
  );
}

直接 RPC 合约调用

import { readContractRpc, multicallRpc } from '@tokenup/walletkit';

// 单个合约读取
const res = await readContractRpc({
  abi: [...],
  address: '0x...',
  functionName: 'balanceOf',
  args: ['0x...'],
  rpcUrl: 'https://rpc.xone.org/'
});

// 批量合约读取
const res2 = await multicallRpc(
  [
    {
      address: '0x...',
      abi: [...],
      functionName: 'totalSupply'
    },
    {
      address: '0x...',
      abi: [...],
      functionName: 'balanceOf',
      args: ['0x...']
    }
  ],
  {
    multicallAddress: '0x...',
    multicallAbi: [...],
    rpcUrl: 'https://rpc.xone.org/'
  }
);

主题和国际化

import { useWalletKit, supportedLanguages } from '@tokenup/walletkit';
import type { Locals } from '@tokenup/walletkit';

function ThemeAndLanguage() {
  const { theme, toggleTheme, language, setLanguage } = useWalletKit();
  return (
    <div>
      <div>当前主题: {theme}，当前语言: {language}</div>
      <div>
        <button onClick={() => toggleTheme()}>切换主题</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>
  );
}

supportedLanguages 为内置多语言列表，可用于动态渲染语言选择项。

事件监听

import { useEffect } from 'react';
import { useWalletKit } from '@tokenup/walletkit';

function EventListener() {
  const { currentConnector } = useWalletKit();
  useEffect(() => {
    const handleConnect = (address) => {
      console.log('钱包已连接:', address);
    };
    const handleChainChanged = (chainId) => {
      console.log('链已更改:', chainId);
    };
    const handleAccountChanged = (address) => {
      console.log('账户已更改:', address);
    };
    const handleDisconnect = () => {
      console.log('钱包已断开连接');
    };
    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>事件监听示例</div>;
}

许可证

MIT