@web3jskit/wallethelper NPM

WalletHelper

WalletHelper 是一个多链钱包连接的底层工具库，为 DApp 开发提供统一的钱包接口和状态管理。它是 WalletKit 的核心依赖库。

WalletHelper is a multi-chain wallet connection utility library that provides unified wallet interfaces and state management for DApp development. It is the core dependency of WalletKit.

特性 Features

多链支持 / Multi-chain support (EVM, PUT, SOL, Tron, BTC)
统一的钱包接口 / Unified wallet interface
钱包自动检测 / Automatic wallet detection
状态管理 / State management
TypeScript 支持 / TypeScript support
轻量级设计 / Lightweight design

安装 Installation

# npm
npm install @web3jskit/wallethelper

# yarn
yarn add @web3jskit/wallethelper

# pnpm
pnpm add @web3jskit/wallethelper

使用方法 Usage

1. 创建钱包连接器 Create Wallet Connector

import { createConnector, ChainType } from '@web3jskit/wallethelper';

// 创建特定链的钱包连接器
const connectors = await createConnector(ChainType.EVM);

2. 检测钱包环境 Detect Wallet Environment

import { detectWalletBrowser } from '@web3jskit/wallethelper';

const walletInfo = detectWalletBrowser();
if (walletInfo) {
	console.log('Detected wallet:', walletInfo.type);
	console.log('Provider:', walletInfo.provider);
}

3. 状态管理 State Management

import { walletHelperStore } from '@web3jskit/wallethelper';

// 获取状态
const state = walletHelperStore.getState();

// 订阅状态变化
const unsubscribe = walletHelperStore.subscribe(state => {
	console.log('Wallet state changed:', state);
});

// 更新状态
walletHelperStore.setState({
	connectStatus: ConnectStatus.Connected,
	walletAddress: '0x...'
});

4. 交易操作 Transaction Operations

// 获取当前连接器
const connector = walletHelperStore.getState().currentConnector;

// 签名消息
const signature = await connector.signMessage('Hello Web3');

// 发送交易
const txHash = await connector.sendTransaction({
  to: '0x...',
  value: '0x...'
});

// 合约调用
const result = await connector.writeContract({
  address: '0x...',
  abi: [...],
  functionName: 'transfer',
  args: [...]
});

API 参考 API Reference

Connector 接口 Connector Interface

interface Connector {
	// 基本属性 Basic properties
	readonly provider: any;
	readonly name: string;
	readonly icon: string;
	readonly deepLink?: string;
	readonly walletAddress: string;
	readonly chainType?: ChainType;
	readonly connectorType?: ConnectorType;

	// 核心方法 Core methods
	connect(): Promise<string>;
	disconnect(): Promise<void>;
	reconnection(): Promise<void>;

	// 交易方法 Transaction methods
	signMessage?(message: string): Promise<string>;
	signTransaction?(transaction: any): Promise<string>;
	sendTransaction?(transaction: any): Promise<string>;
	writeContract?(contract: any): Promise<string>;
	readContract?(contract: any): Promise<string>;

	// 其他方法 Other methods
	getProvider(): Promise<any>;
	getWalletAddress(): string;
	switchNetwork?(chainId: number): Promise<string>;
}

Store 状态定义 Store State Definition

interface WalletHelperState {
	// 连接状态 Connection status
	connectStatus: ConnectStatus;
	currentConnector: Connector | null;
	walletAddress: string;

	// 链相关 Chain related
	currentChainType: ChainType;
	currentNetworkId: number;
	currentNetwork: NetworkInfo | null;

	// Provider
	provider: any;

	// 方法 Methods
	getProvider(): Promise<any>;
	disconnect(): Promise<void>;
	signMessage(message: string): Promise<any>;
	sendTransaction(transaction: any): Promise<any>;
	// ... 更多方法 more methods
}

支持的钱包 Supported Wallets

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)

错误处理 Error Handling

WalletHelper 提供了标准的错误类型和处理机制：

WalletHelper provides standard error types and handling mechanisms:

// RPC 请求错误 RPC request error
class RpcRequestError extends BaseError {
	code: number;
	// ...
}

// 连接错误 Connection error
class ConnectionError extends BaseError {
	// ...
}

// 超时错误 Timeout error
class TimeoutError extends BaseError {
	// ...
}