@earthworm/wallet-sdk 0.1.0 → 0.2.1

package/README.md

@@ -1,6 +1,6 @@
 # @earthworm/wallet-sdk
 
-Browser EVM wallet SDK for DApps (MetaMask, Coinbase, TronLink, EIP-6963, contract reads).
+Browser EVM wallet SDK for DApps (MetaMask, Coinbase, TronLink, TokenPocket, contract reads).
 
 ## Install
 
@@ -11,10 +11,10 @@ pnpm add @earthworm/wallet-sdk ethers
 ## Usage
 
 ```ts
-import { initWalletSdk, getWalletSdkConfig, walletEvents } from "@earthworm/wallet-sdk";
+import { initWalletSdk, walletEvents } from "@earthworm/wallet-sdk";
 
 initWalletSdk({
-  isMainnet: true,
+  isMainnet: true, // Set to true for mainnet, false for testnet
   contract: { address: "0x...", abi: [] },
 });
 
@@ -22,16 +22,3 @@ walletEvents.on("accountsChanged", (accounts) => {
   console.log(accounts);
 });
 ```
-
-## Develop
-
-```bash
-pnpm install
-pnpm run build
-```
-
-## Publish
-
-```bash
-pnpm publish
-```

package/dist/index.d.ts

@@ -2,8 +2,11 @@ import * as ethers from 'ethers';
 import { InterfaceAbi, Eip1193Provider, BrowserProvider, JsonRpcProvider, JsonRpcSigner } from 'ethers';
 
 /**
- * 将 EVM 十六进制 chainId（如 0x61）转换为十进制 chainId（如 97）。
- * 钱包 `chainChanged` / `eth_chainId` 返回的通常是 0x 前缀 hex 字符串。
+ * 将 EVM 十六进制 chainId 转换为十进制 chainId。
+ * 钱包 `chainChanged` / `eth_chainId` 返回的通常是 `0x` 前缀 hex 字符串。
+ * @param chainId - 十六进制 chainId，如 `"0x38"`（56）或 `"0x61"`（97）。
+ * @param fallback - 解析失败时的回退值；未传则返回 `NaN`。
+ * @returns 十进制 chainId 数值，或 `fallback` / `NaN`。
  */
 declare function toChainIdDecimal(chainId: string, fallback?: number): number;
 
@@ -27,14 +30,17 @@ type MutableRef<T> = {
     value: T;
 };
 type EthereumRequestParams = unknown[] | Record<string, unknown>;
+type ChainNativeCurrency = {
+    name: string;
+    symbol: string;
+    decimals: number;
+};
 type ChainConfig = {
     chainId: string;
     chainName: string;
-    nativeCurrencyName: string;
-    nativeCurrencySymbol: string;
-    nativeCurrencyDecimals: string | number;
-    rpcUrl: string;
-    blockExplorerUrl: string;
+    nativeCurrency: ChainNativeCurrency;
+    rpcUrls: string[];
+    blockExplorerUrls: string[];
 };
 type Eip6963ProviderInfo = {
     uuid: string;
@@ -69,57 +75,172 @@ type WalletSdkConfig = {
     };
 };
 
+/**
+ * 通过 EIP-6963 发现并收集浏览器中的钱包 provider。
+ * 非浏览器环境直接返回空数组；多次调用共享同一次发现结果。
+ * @param timeoutMs - 等待 `eip6963:announceProvider` 的超时毫秒数，默认 `500`。
+ * @returns 已发现的 {@link Eip6963ProviderDetail} 列表。
+ */
 declare function discoverWalletProviders(timeoutMs?: number): Promise<Eip6963ProviderDetail[]>;
+/**
+ * 从已发现的 EIP-6963 provider 中按条件查找。
+ * @param match - 匹配函数，入参为 {@link Eip6963ProviderDetail}。
+ * @returns 匹配到的 EIP-1193 provider；未找到为 `undefined`。
+ */
 declare function findDiscoveredProvider(match: (detail: Eip6963ProviderDetail) => boolean): ethers.Eip1193Provider | undefined;
+/**
+ * 查找 MetaMask 的 EIP-6963 provider。
+ * @returns MetaMask EIP-1193 provider；未找到为 `undefined`。
+ */
 declare function findMetaMaskEip6963Provider(): ethers.Eip1193Provider | undefined;
+/**
+ * 查找 Coinbase Wallet 的 EIP-6963 provider。
+ * @returns Coinbase EIP-1193 provider；未找到为 `undefined`。
+ */
 declare function findCoinbaseEip6963Provider(): ethers.Eip1193Provider | undefined;
+/**
+ * 是否通过 EIP-6963 检测到 MetaMask。
+ * @returns 检测到为 `true`，否则 `false`。
+ */
 declare function hasMetaMaskEip6963Provider(): boolean;
+/**
+ * 是否通过 EIP-6963 检测到 Coinbase Wallet。
+ * @returns 检测到为 `true`，否则 `false`。
+ */
 declare function hasCoinbaseEip6963Provider(): boolean;
 
+/**
+ * 获取与 EIP-1193 provider 绑定的共享 BrowserProvider（同一实例复用）。
+ * @param ethereum - EIP-1193 provider，如 MetaMask 的 `window.ethereum`。
+ * @returns ethers `BrowserProvider`。
+ */
 declare function getSharedBrowserProvider(ethereum: Eip1193Provider): BrowserProvider;
 
+/**
+ * 获取浏览器中所有 injected 以太坊 provider。
+ * @returns {@link InjectedEthereumProvider} 数组；无 `window.ethereum` 时返回 `[]`。
+ */
 declare function getInjectedEthereumProviders(): InjectedEthereumProvider[];
+/**
+ * 解析 MetaMask injected provider（EIP-6963 → providerMap → providers 数组 → 根 ethereum）。
+ * @returns MetaMask {@link WalletEventProvider}；未找到为 `undefined`。
+ */
 declare function resolveMetaMaskInjectedProvider(): WalletEventProvider | undefined;
+/**
+ * 解析 Coinbase Wallet injected provider（扩展 → EIP-6963 → providerMap → providers 数组 → 根 ethereum）。
+ * @returns Coinbase {@link WalletEventProvider}；未找到为 `undefined`。
+ */
 declare function resolveCoinbaseInjectedProvider(): WalletEventProvider | undefined;
+/**
+ * 是否检测到 MetaMask injected provider。
+ * @returns 检测到为 `true`，否则 `false`。
+ */
 declare function hasMetaMaskInjectedProvider(): boolean;
+/**
+ * 是否检测到 Coinbase Wallet（扩展、request provider 或 injected）。
+ * @returns 检测到为 `true`，否则 `false`。
+ */
 declare function hasCoinbaseInjectedProvider(): boolean;
+/**
+ * 缓存当前可用的多钱包聚合根 provider（`ethereum.providers.length > 1`）。
+ * 非浏览器环境无操作。
+ */
 declare function rememberAggregatorProvider(): void;
+/**
+ * 是否存在可恢复的多钱包聚合 provider（当前页面或历史缓存）。
+ * @returns 存在为 `true`，否则 `false`。
+ */
 declare function hasRecoverableAggregatorProvider(): boolean;
+/**
+ * 获取聚合 injected provider（多钱包根节点或 TronLink + Coinbase 组合场景）。
+ * @returns {@link InjectedEthereumProvider}；未找到为 `undefined`。
+ */
 declare function getAggregatedInjectedProvider(): WalletEventProvider | undefined;
+/**
+ * 是否存在可用的聚合 injected 以太坊 provider。
+ * @returns 存在为 `true`；非浏览器为 `false`。
+ */
 declare function hasAggregatedInjectedProvider(): boolean;
 
 declare const ERC20_DECIMALS_ABI: readonly ["function decimals() view returns (uint8)"];
-/** 检查地址在链上是否已部署合约（有 bytecode 才算合约地址） */
+/**
+ * 检查地址在链上是否已部署合约（有 bytecode 才算合约地址）。
+ * @param readProvider - 只读 provider，ethers `BrowserProvider` 或 `JsonRpcProvider`。
+ * @param address - 待检查的地址，如 `"0x..."`。
+ * @returns 已部署为 `true`，无 bytecode 为 `false`。
+ */
 declare function hasDeployedContract(readProvider: EvmReadProvider, address: string): Promise<boolean>;
-/** 读取 ERC20 代币 decimals；合约未部署直接报错，调用失败时返回 fallback */
+/**
+ * 读取 ERC20 代币 decimals。
+ * @param readProvider - 只读 provider，ethers `BrowserProvider` 或 `JsonRpcProvider`。
+ * @param tokenAddress - ERC20 合约地址。
+ * @param erc20Abi - 合约 ABI，默认 {@link ERC20_DECIMALS_ABI}。
+ * @param fallback - `decimals()` 调用失败时的回退值，默认 {@link ERC20_DECIMALS}（18）。
+ * @returns token decimals 数值。
+ * @throws 合约未部署时抛错。
+ */
 declare function readErc20Decimals(readProvider: EvmReadProvider, tokenAddress: string, erc20Abi?: InterfaceAbi, fallback?: 18): Promise<number>;
 
+/**
+ * 合约只读调用选项。
+ * @property abi - 合约 ABI（`InterfaceAbi`），需包含目标读方法。
+ * @property method - 要 `staticCall` 的合约方法名，如 `"decimals"`、`"getPrice"`。
+ */
 type GetContractReadOptions = {
     abi: InterfaceAbi;
     method: string;
 };
-/** 设置钱包 BrowserProvider，链上读取优先走钱包 */
+/**
+ * 设置用于链上只读调用的钱包 BrowserProvider。
+ * 设置后 `getConfiguredReadProvider` 会优先走钱包，否则回退到 init 配置中的 RPC。
+ * @param provider - ethers `BrowserProvider`；传 `null` 则清除并回退到 RPC。
+ */
 declare function setWalletReadProvider(provider: BrowserProvider | null): void;
+/**
+ * 获取当前配置的只读 provider。
+ * 需先调用 `initWalletSdk`；优先返回已设置的钱包 BrowserProvider，否则使用 RPC fallback。
+ * @returns ethers `BrowserProvider` 或 `JsonRpcProvider`。
+ * @throws 未初始化 SDK，或 RPC 配置缺失时抛错。
+ */
 declare function getConfiguredReadProvider(): EvmReadProvider;
-/** 检查合约是否已部署 */
+/**
+ * 检查指定地址在当前链上是否已部署合约（是否存在 bytecode）。
+ * @param contractAddress - 合约地址，如 `"0x55d398326f99059fF775485246999027B3197955"`。
+ * @returns 已部署为 `true`，无 bytecode 为 `false`。
+ */
 declare function isContractDeployed(contractAddress: string): Promise<boolean>;
-/** 读取合约 decimals */
+/**
+ * 读取 token 合约的 decimals。
+ * @param contractAddress - 代币合约地址。
+ * @param options - 读调用选项，见 {@link GetContractReadOptions}。
+ * @param options.abi - 合约 ABI，需包含 `options.method` 对应的方法。
+ * @param options.method - decimals 方法名，通常为 `"decimals"`。
+ * @returns token decimals 数值，如 `18`。
+ * @throws 合约未部署时抛错。
+ */
 declare function getContractDecimals(contractAddress: string, options: GetContractReadOptions): Promise<number>;
-/** 读取合约价格 */
+/**
+ * 读取合约价格，并按 token decimals 格式化为人类可读字符串。
+ * 内部会额外调用 `decimals()` 做 `formatUnits` 换算。
+ * @param contractAddress - 价格合约地址。
+ * @param options - 读调用选项，见 {@link GetContractReadOptions}。
+ * @param options.abi - 合约 ABI，需包含价格读方法与 `decimals` 方法。
+ * @param options.method - 价格读方法名，如 `"getPrice"`。
+ * @returns 格式化后的价格字符串（ethers `formatUnits` 结果）。
+ * @throws 合约未部署时抛错。
+ */
 declare function getContractPrice(contractAddress: string, options: GetContractReadOptions): Promise<string>;
 
-declare function buildEthereumChainParams(config: ChainConfig): {
-    chainId: string;
-    chainName: string;
-    nativeCurrency: {
-        name: string;
-        symbol: string;
-        decimals: number;
-    };
-    rpcUrls: string[];
-    blockExplorerUrls: string[];
-};
-/** 确保钱包切换到目标网络（不存在时自动 addEthereumChain） */
+/**
+ * 确保钱包切换到目标网络；链未添加时自动调用 `wallet_addEthereumChain`。
+ * @param options - 切链选项。
+ * @param options.targetChainId - 目标十六进制 chainId，如 `"0x38"`。
+ * @param options.getCurrentChainId - 获取当前 chainId 的异步函数（通常 `eth_chainId`）。
+ * @param options.switchChain - 切换链的异步函数（通常 `wallet_switchEthereumChain`）。
+ * @param options.addChain - 添加链的异步函数（通常 `wallet_addEthereumChain`）；参数为 {@link ChainConfig} 兼容对象。
+ * @param options.chainParams - 传给 `addChain` 的链参数，可直接使用 `getWalletSdkConfig().chain`。
+ * @returns 已在目标链上或切链成功时 resolve；非 4902 错误会向上抛出。
+ */
 declare function ensureTargetNetwork(options: {
     targetChainId: string;
     getCurrentChainId: () => Promise<string>;
@@ -128,27 +249,80 @@ declare function ensureTargetNetwork(options: {
     chainParams: Record<string, unknown>;
 }): Promise<void>;
 
+/**
+ * 创建并缓存 JsonRpc 只读 provider。
+ * @param rpcUrl - RPC 节点 URL，如 `"https://bsc-dataseed.binance.org/"`。
+ * @param chainIdHex - 十六进制 chainId，如 `"0x38"`（BSC 主网）或 `"0x61"`（测试网）。
+ * @param cache - 可选缓存对象；传入后复用同一 `JsonRpcProvider` 实例。
+ * @returns ethers `JsonRpcProvider`。
+ */
 declare function createJsonRpcReadProvider(rpcUrl: string, chainIdHex: string, cache?: {
     current: JsonRpcProvider | null;
 }): JsonRpcProvider;
-/** 优先使用钱包 BrowserProvider，否则回退到 JsonRpcProvider */
+/**
+ * 获取只读 provider：优先使用钱包 BrowserProvider，否则回退到 JsonRpcProvider。
+ * @param walletProvider - 钱包 BrowserProvider；为 `null` 时使用 RPC fallback。
+ * @param rpcConfig - RPC 配置。
+ * @param rpcConfig.rpcUrls - RPC 节点 URL 列表，取第一个作为 fallback。
+ * @param rpcConfig.chainId - 十六进制 chainId，如 `"0x38"`。
+ * @param fallbackCache - 可选 JsonRpc provider 缓存。
+ * @returns ethers `BrowserProvider` 或 `JsonRpcProvider`。
+ * @throws `rpcUrls[0]` 或 `chainId` 缺失时抛错。
+ */
 declare function getReadProviderWithFallback(walletProvider: BrowserProvider | null, rpcConfig: {
-    rpcUrl: string;
+    rpcUrls: string[];
     chainId: string;
 }, fallbackCache?: {
     current: JsonRpcProvider | null;
 }): EvmReadProvider;
 
+/**
+ * 将 EIP-1193 provider 绑定为 BrowserProvider 并写入缓存。
+ * @param eip1193 - 钱包 EIP-1193 provider。
+ * @param cache - BrowserProvider 缓存引用 `{ value: BrowserProvider | null }`。
+ * @returns ethers `BrowserProvider`。
+ */
 declare function bindBrowserProvider(eip1193: WalletEventProvider, cache: MutableRef<BrowserProvider | null>): BrowserProvider;
+/**
+ * 向钱包发起 JSON-RPC 请求。
+ * @param eip1193 - 钱包 EIP-1193 provider。
+ * @param method - JSON-RPC 方法名，如 `"eth_requestAccounts"`。
+ * @param params - 可选请求参数，数组或对象。
+ * @returns provider `request` 的原始返回值。
+ */
 declare function requestWallet(eip1193: WalletEventProvider, method: string, params?: EthereumRequestParams): Promise<any>;
+/**
+ * 连接钱包账户并初始化 signer。
+ * @param requestAccounts - 请求账户的函数，通常调用 `eth_requestAccounts`。
+ * @param getProvider - 获取当前 BrowserProvider 的函数。
+ * @param setSigner - 设置 signer 的回调。
+ * @param markConnected - 标记已连接的回调。
+ * @returns 连接结果 `{ address: string; signer: JsonRpcSigner }`。
+ * @throws 钱包未返回账户时抛错。
+ */
 declare function connectWalletAccount(requestAccounts: () => Promise<unknown>, getProvider: () => BrowserProvider, setSigner: (signer: JsonRpcSigner) => void, markConnected: () => void): Promise<{
     address: string;
     signer: JsonRpcSigner;
 }>;
+/**
+ * 同步当前钱包账户地址与 signer（不触发授权弹窗）。
+ * @param getProvider - 获取当前 BrowserProvider 的函数。
+ * @param setSigner - 设置 signer 的回调。
+ * @param markConnected - 标记已连接的回调。
+ * @param nextAddress - 可选指定账户地址；未传则使用 provider 默认账户。
+ * @returns 同步结果 `{ address: string; signer: JsonRpcSigner }`。
+ */
 declare function syncWalletAccountAddress(getProvider: () => BrowserProvider, setSigner: (signer: JsonRpcSigner) => void, markConnected: () => void, nextAddress?: string): Promise<{
     address: string;
     signer: JsonRpcSigner;
 }>;
+/**
+ * 清除钱包运行时缓存（provider、signer、可选 selectedProvider）。
+ * @param cache - 运行时缓存对象。
+ * @param cache.provider - BrowserProvider 缓存引用。
+ * @param cache.signer - Signer 缓存引用。
+ * @param cache.selectedProvider - 可选，当前选中的 EIP-1193 provider 缓存引用。
+ */
 declare function clearWalletRuntime(cache: {
     provider: MutableRef<BrowserProvider | null>;
     signer: MutableRef<JsonRpcSigner | null>;
@@ -161,8 +335,16 @@ type WalletProviderEventMap = {
 };
 type WalletProviderEventName = keyof WalletProviderEventMap;
 type WalletProviderEventListener<K extends WalletProviderEventName = WalletProviderEventName> = (payload: WalletProviderEventMap[K]) => void | Promise<void>;
-/** 设置当前钱包 EIP-1193 provider，供事件监听使用 */
+/**
+ * 设置当前钱包 EIP-1193 provider，供 `walletEvents` 事件监听使用。
+ * @param provider - 钱包 EIP-1193 provider；传 `null` 则解除绑定。
+ */
 declare function setWalletEventProvider(provider: WalletEventProvider | null): void;
+/**
+ * 获取当前已设置的钱包 EIP-1193 provider。
+ * @returns {@link WalletEventProvider}。
+ * @throws 未调用 `setWalletEventProvider` 时抛错。
+ */
 declare function getWalletEventProvider(): WalletEventProvider;
 declare class WalletEventsEmitter {
     on(event: "accountsChanged", listener: WalletProviderEventListener<"accountsChanged">): void;
@@ -174,64 +356,117 @@ declare class WalletEventsEmitter {
     clear(): void;
 }
 type WalletEvents = WalletEventsEmitter;
+/** 钱包事件总线，支持 `accountsChanged` / `chainChanged` 监听。需先 `setWalletEventProvider`。 */
 declare const walletEvents: WalletEventsEmitter;
 
-/** 是否在浏览器环境（模块加载时判定一次） */
+/** 是否在浏览器环境（模块加载时判定一次）。 */
 declare const isBrowser: boolean;
-/** 仅浏览器可用的操作入口；检测类 API 请用 isBrowser 后 return false */
+/**
+ * 断言当前为浏览器环境；非浏览器时抛错。
+ * 检测类 API 请先用 {@link isBrowser} 判断后返回，而非调用此函数。
+ * @param apiName - 调用方 API 名称，用于错误信息，如 `"walletEvents.on"`。
+ * @throws 非浏览器环境时抛错。
+ */
 declare function assertBrowser(apiName: string): void;
 
-/** 是否检测到 MetaMask */
+/**
+ * 是否检测到 MetaMask（injected 或 EIP-6963）。
+ * @returns 浏览器中检测到 MetaMask 为 `true`；非浏览器或未检测到为 `false`。
+ */
 declare function isEthereumProvider(): boolean;
-/** 是否检测到 Coinbase Wallet */
+/**
+ * 是否检测到 Coinbase Wallet。
+ * @returns 浏览器中检测到 Coinbase 为 `true`；非浏览器或未检测到为 `false`。
+ */
 declare function isCoinbaseProvider(): boolean;
-/** 是否检测到通用 Injected 钱包 */
+/**
+ * 是否检测到通用 injected 以太坊钱包（含多钱包聚合器）。
+ * @returns 浏览器中存在可用 injected provider 为 `true`；否则 `false`。
+ */
 declare function isInjectedProvider(): boolean;
-/** 是否检测到 TronLink */
+/**
+ * 是否检测到 TronLink。
+ * @returns 浏览器中 `window.tron` 或 `window.tronLink` 可用为 `true`；否则 `false`。
+ */
 declare function isTronLinkProvider(): boolean;
 
-/** 初始化并持久化配置，任意模块均可通过 getWalletSdkConfig 读取 */
+/**
+ * 初始化 SDK 并将配置持久化到 `globalThis`，供各模块通过 `getWalletSdkConfig` 读取。
+ * @param options - 初始化选项，见 {@link WalletSdkInitOptions}。
+ * @param options.isMainnet - `true` 使用 BSC 主网，`false` 使用 BSC 测试网。
+ * @param options.contract - 业务合约配置（`address` + `abi`）。
+ * @returns 完整 SDK 配置 {@link WalletSdkConfig}。
+ */
 declare function initWalletSdk(options: WalletSdkInitOptions): WalletSdkConfig;
+/**
+ * 读取已初始化的 SDK 配置。
+ * @returns 当前 {@link WalletSdkConfig}。
+ * @throws 未调用 `initWalletSdk` 时抛错。
+ */
 declare function getWalletSdkConfig(): WalletSdkConfig;
+/**
+ * 判断 SDK 是否已完成初始化。
+ * @returns 已调用 `initWalletSdk` 为 `true`，否则 `false`。
+ */
 declare function isWalletSdkInitialized(): boolean;
+/**
+ * 清除已持久化的 SDK 配置（主要用于测试或热重载）。
+ */
 declare function resetWalletSdkConfig(): void;
 
 declare const BSC_NETWORK: {
     chainId: string;
     chainName: string;
-    nativeCurrencyName: string;
-    nativeCurrencySymbol: string;
-    nativeCurrencyDecimals: string;
-    rpcUrl: string;
-    blockExplorerUrl: string;
+    nativeCurrency: {
+        name: string;
+        symbol: string;
+        decimals: number;
+    };
+    rpcUrls: string[];
+    blockExplorerUrls: string[];
 };
 declare const BSC_TESTNET_NETWORK: {
     chainId: string;
     chainName: string;
-    nativeCurrencyName: string;
-    nativeCurrencySymbol: string;
-    nativeCurrencyDecimals: string;
-    rpcUrl: string;
-    blockExplorerUrl: string;
-};
-declare function getDefaultBscConfig(isProd?: boolean): {
-    chainId: string;
-    chainName: string;
-    nativeCurrencyName: string;
-    nativeCurrencySymbol: string;
-    nativeCurrencyDecimals: string;
-    rpcUrl: string;
-    blockExplorerUrl: string;
+    nativeCurrency: {
+        name: string;
+        symbol: string;
+        decimals: number;
+    };
+    rpcUrls: string[];
+    blockExplorerUrls: string[];
 };
 
-/** BSC USDT 合约地址 */
+/** BSC 主网 / 测试网 USDT 合约地址，key 为十六进制 chainId。 */
 declare const USDT_CONTRACT_ADDRESSES: {
     readonly [BSC_NETWORK.chainId]: "0x55d398326f99059fF775485246999027B3197955";
     readonly [BSC_TESTNET_NETWORK.chainId]: "0x66E972502A34A625828C544a1914E8D8cc2A9dE5";
 };
+/**
+ * 根据 chainId 解析 BSC USDT 合约地址。
+ * @param chainId - 十六进制 chainId，如 `"0x38"` 或 `"0x61"`。
+ * @returns USDT 合约地址字符串。
+ * @throws 不支持的 chainId 时抛错。
+ */
 declare function resolveUsdtContractAddress(chainId: string): "0x55d398326f99059fF775485246999027B3197955" | "0x66E972502A34A625828C544a1914E8D8cc2A9dE5";
+/**
+ * 根据是否主网解析 BSC 链配置。
+ * @param isMainnet - `true` 返回 BSC 主网，`false` 返回 BSC 测试网。
+ * @returns {@link ChainConfig}。
+ */
 declare function resolveChainByMainnet(isMainnet: boolean): ChainConfig;
+/**
+ * 根据是否主网解析 BSC USDT 合约地址。
+ * @param isMainnet - `true` 主网 USDT，`false` 测试网 USDT。
+ * @returns USDT 合约地址字符串。
+ */
 declare function resolveUsdtByMainnet(isMainnet: boolean): "0x55d398326f99059fF775485246999027B3197955" | "0x66E972502A34A625828C544a1914E8D8cc2A9dE5";
+/**
+ * 根据 chainId 解析 BSC 链配置。
+ * @param chainId - 十六进制 chainId，如 `"0x38"` 或 `"0x61"`。
+ * @returns {@link ChainConfig}。
+ * @throws 不支持的 chainId 时抛错。
+ */
 declare function resolveChainConfig(chainId: string): ChainConfig;
 
 declare const USDT_CONFIG: {
@@ -325,4 +560,4 @@ declare const ERC20_ABI: ({
     stateMutability?: undefined;
 })[];
 
-export { BSC_NETWORK, BSC_TESTNET_NETWORK, type ChainConfig, type ContractConfig, ERC20_ABI, ERC20_DECIMALS, ERC20_DECIMALS_ABI, type Eip6963ProviderDetail, type Eip6963ProviderInfo, type EthereumRequestParams, type EvmReadProvider, type GetContractReadOptions, type InjectedEthereumProvider, type MutableRef, USDT_CONFIG, USDT_CONTRACT_ADDRESSES, type WalletEventProvider, type WalletEvents, type WalletProviderEventListener, type WalletProviderEventMap, type WalletProviderEventName, type WalletSdkConfig, type WalletSdkInitOptions, assertBrowser, bindBrowserProvider, buildEthereumChainParams, clearWalletRuntime, connectWalletAccount, createJsonRpcReadProvider, discoverWalletProviders, ensureTargetNetwork, findCoinbaseEip6963Provider, findDiscoveredProvider, findMetaMaskEip6963Provider, getAggregatedInjectedProvider, getConfiguredReadProvider, getContractDecimals, getContractPrice, getDefaultBscConfig, getInjectedEthereumProviders, getReadProviderWithFallback, getSharedBrowserProvider, getWalletEventProvider, getWalletSdkConfig, hasAggregatedInjectedProvider, hasCoinbaseEip6963Provider, hasCoinbaseInjectedProvider, hasDeployedContract, hasMetaMaskEip6963Provider, hasMetaMaskInjectedProvider, hasRecoverableAggregatorProvider, initWalletSdk, isBrowser, isCoinbaseProvider, isContractDeployed, isEthereumProvider, isInjectedProvider, isTronLinkProvider, isWalletSdkInitialized, readErc20Decimals, rememberAggregatorProvider, requestWallet, resetWalletSdkConfig, resolveChainByMainnet, resolveChainConfig, resolveCoinbaseInjectedProvider, resolveMetaMaskInjectedProvider, resolveUsdtByMainnet, resolveUsdtContractAddress, setWalletEventProvider, setWalletReadProvider, syncWalletAccountAddress, toChainIdDecimal, walletEvents };
+export { BSC_NETWORK, BSC_TESTNET_NETWORK, type ChainConfig, type ChainNativeCurrency, type ContractConfig, ERC20_ABI, ERC20_DECIMALS, ERC20_DECIMALS_ABI, type Eip6963ProviderDetail, type Eip6963ProviderInfo, type EthereumRequestParams, type EvmReadProvider, type GetContractReadOptions, type InjectedEthereumProvider, type MutableRef, USDT_CONFIG, USDT_CONTRACT_ADDRESSES, type WalletEventProvider, type WalletEvents, type WalletProviderEventListener, type WalletProviderEventMap, type WalletProviderEventName, type WalletSdkConfig, type WalletSdkInitOptions, assertBrowser, bindBrowserProvider, clearWalletRuntime, connectWalletAccount, createJsonRpcReadProvider, discoverWalletProviders, ensureTargetNetwork, findCoinbaseEip6963Provider, findDiscoveredProvider, findMetaMaskEip6963Provider, getAggregatedInjectedProvider, getConfiguredReadProvider, getContractDecimals, getContractPrice, getInjectedEthereumProviders, getReadProviderWithFallback, getSharedBrowserProvider, getWalletEventProvider, getWalletSdkConfig, hasAggregatedInjectedProvider, hasCoinbaseEip6963Provider, hasCoinbaseInjectedProvider, hasDeployedContract, hasMetaMaskEip6963Provider, hasMetaMaskInjectedProvider, hasRecoverableAggregatorProvider, initWalletSdk, isBrowser, isCoinbaseProvider, isContractDeployed, isEthereumProvider, isInjectedProvider, isTronLinkProvider, isWalletSdkInitialized, readErc20Decimals, rememberAggregatorProvider, requestWallet, resetWalletSdkConfig, resolveChainByMainnet, resolveChainConfig, resolveCoinbaseInjectedProvider, resolveMetaMaskInjectedProvider, resolveUsdtByMainnet, resolveUsdtContractAddress, setWalletEventProvider, setWalletReadProvider, syncWalletAccountAddress, toChainIdDecimal, walletEvents };

package/dist/index.js

@@ -1,6 +1,6 @@
 import { BrowserProvider, Contract, JsonRpcProvider, formatUnits } from 'ethers';
 
-// src/chain.ts
+// src/utils/chain.ts
 function toChainIdDecimal(chainId, fallback) {
   const decimal = Number.parseInt(chainId, 16);
   if (Number.isFinite(decimal)) return decimal;
@@ -8,7 +8,7 @@ function toChainIdDecimal(chainId, fallback) {
   return Number.NaN;
 }
 
-// src/env.ts
+// src/utils/env.ts
 var isBrowser = typeof window !== "undefined";
 function assertBrowser(apiName) {
   if (!isBrowser) {
@@ -16,7 +16,7 @@ function assertBrowser(apiName) {
   }
 }
 
-// src/eip6963.ts
+// src/wallet/eip6963.ts
 var METAMASK_RDNS = "io.metamask";
 var COINBASE_RDNS = "com.coinbase.wallet";
 var discoveredProviders = [];
@@ -76,7 +76,7 @@ function getSharedBrowserProvider(ethereum) {
   return provider;
 }
 
-// src/injected-providers.ts
+// src/wallet/injected-providers.ts
 var isRequestableProvider = (provider) => {
   return Boolean(provider && typeof provider.request === "function");
 };
@@ -528,24 +528,33 @@ var ERC20_ABI = [
 var BSC_NETWORK = {
   chainId: "0x38",
   chainName: "BNB Smart Chain",
-  nativeCurrencyName: "BNB",
-  nativeCurrencySymbol: "BNB",
-  nativeCurrencyDecimals: "18",
-  rpcUrl: "https://bsc-dataseed.binance.org/",
-  blockExplorerUrl: "https://bscscan.com"
+  nativeCurrency: {
+    name: "BNB",
+    symbol: "BNB",
+    decimals: 18
+  },
+  rpcUrls: [
+    "https://bsc-dataseed.binance.org/",
+    "https://bsc-dataseed1.binance.org/",
+    "https://bsc-dataseed2.binance.org/"
+  ],
+  blockExplorerUrls: ["https://bscscan.com"]
 };
 var BSC_TESTNET_NETWORK = {
   chainId: "0x61",
   chainName: "BNB Smart Chain Testnet",
-  nativeCurrencyName: "tBNB",
-  nativeCurrencySymbol: "tBNB",
-  nativeCurrencyDecimals: "18",
-  rpcUrl: "https://data-seed-prebsc-1-s1.bnbchain.org:8545/",
-  blockExplorerUrl: "https://testnet.bscscan.com"
+  nativeCurrency: {
+    name: "tBNB",
+    symbol: "tBNB",
+    decimals: 18
+  },
+  rpcUrls: [
+    "https://data-seed-prebsc-1-s1.bnbchain.org:8545/",
+    "https://data-seed-prebsc-2-s1.bnbchain.org:8545/",
+    "https://data-seed-prebsc-1-s2.bnbchain.org:8545/"
+  ],
+  blockExplorerUrls: ["https://testnet.bscscan.com"]
 };
-function getDefaultBscConfig(isProd = typeof process !== "undefined" && process.env.NODE_ENV === "production") {
-  return isProd ? BSC_NETWORK : BSC_TESTNET_NETWORK;
-}
 
 // src/config/resolve-chain.ts
 var USDT_CONTRACT_ADDRESSES = {
@@ -584,7 +593,7 @@ var USDT_CONFIG = {
 };
 var ERC20_DECIMALS = USDT_CONFIG.decimals;
 
-// src/contract.ts
+// src/core/contract.ts
 var ERC20_DECIMALS_ABI = ["function decimals() view returns (uint8)"];
 async function hasDeployedContract(readProvider, address) {
   const code = await readProvider.getCode(address);
@@ -603,7 +612,7 @@ async function readErc20Decimals(readProvider, tokenAddress, erc20Abi = ERC20_DE
   }
 }
 
-// src/init.ts
+// src/core/init.ts
 var CONFIG_KEY = "__WALLET_SDK_CONFIG__";
 function getStoredConfig() {
   return globalThis[CONFIG_KEY] ?? null;
@@ -660,13 +669,14 @@ function createJsonRpcReadProvider(rpcUrl, chainIdHex, cache) {
 }
 function getReadProviderWithFallback(walletProvider, rpcConfig, fallbackCache) {
   if (walletProvider) return walletProvider;
-  if (!rpcConfig.rpcUrl || !rpcConfig.chainId) {
+  const rpcUrl = rpcConfig.rpcUrls[0];
+  if (!rpcUrl || !rpcConfig.chainId) {
     throw new Error("RPC config is missing");
   }
-  return createJsonRpcReadProvider(rpcConfig.rpcUrl, rpcConfig.chainId, fallbackCache);
+  return createJsonRpcReadProvider(rpcUrl, rpcConfig.chainId, fallbackCache);
 }
 
-// src/contract-read.ts
+// src/core/contract-read.ts
 var readProviderCache = { current: null };
 var walletReadProvider = null;
 function setWalletReadProvider(provider) {
@@ -699,20 +709,7 @@ async function getContractPrice(contractAddress, options) {
   return formatUnits(price, decimals);
 }
 
-// src/network.ts
-function buildEthereumChainParams(config) {
-  return {
-    chainId: config.chainId,
-    chainName: config.chainName,
-    nativeCurrency: {
-      name: config.nativeCurrencyName,
-      symbol: config.nativeCurrencySymbol,
-      decimals: Number(config.nativeCurrencyDecimals) || 18
-    },
-    rpcUrls: [config.rpcUrl],
-    blockExplorerUrls: [config.blockExplorerUrl]
-  };
-}
+// src/core/network.ts
 async function ensureTargetNetwork(options) {
   const currentChainId = await options.getCurrentChainId();
   if (currentChainId.toLowerCase() === options.targetChainId.toLowerCase()) return;
@@ -770,7 +767,7 @@ function clearWalletRuntime(cache) {
   }
 }
 
-// src/wallet-events.ts
+// src/wallet/events.ts
 var eventHandlers = {};
 var providerBridges = /* @__PURE__ */ new WeakMap();
 var walletEventProvider = null;
@@ -866,7 +863,7 @@ var WalletEventsEmitter = class {
 };
 var walletEvents = new WalletEventsEmitter();
 
-// src/wallet-detection.ts
+// src/wallet/detection.ts
 function isEthereumProvider() {
   if (!isBrowser) return false;
   return hasMetaMaskInjectedProvider() || hasMetaMaskEip6963Provider();
@@ -884,4 +881,4 @@ function isTronLinkProvider() {
   return Boolean(window.tron?.request || window.tronLink);
 }
 
-export { BSC_NETWORK, BSC_TESTNET_NETWORK, ERC20_ABI, ERC20_DECIMALS, ERC20_DECIMALS_ABI, USDT_CONFIG, USDT_CONTRACT_ADDRESSES, assertBrowser, bindBrowserProvider, buildEthereumChainParams, clearWalletRuntime, connectWalletAccount, createJsonRpcReadProvider, discoverWalletProviders, ensureTargetNetwork, findCoinbaseEip6963Provider, findDiscoveredProvider, findMetaMaskEip6963Provider, getAggregatedInjectedProvider, getConfiguredReadProvider, getContractDecimals, getContractPrice, getDefaultBscConfig, getInjectedEthereumProviders, getReadProviderWithFallback, getSharedBrowserProvider, getWalletEventProvider, getWalletSdkConfig, hasAggregatedInjectedProvider, hasCoinbaseEip6963Provider, hasCoinbaseInjectedProvider, hasDeployedContract, hasMetaMaskEip6963Provider, hasMetaMaskInjectedProvider, hasRecoverableAggregatorProvider, initWalletSdk, isBrowser, isCoinbaseProvider, isContractDeployed, isEthereumProvider, isInjectedProvider, isTronLinkProvider, isWalletSdkInitialized, readErc20Decimals, rememberAggregatorProvider, requestWallet, resetWalletSdkConfig, resolveChainByMainnet, resolveChainConfig, resolveCoinbaseInjectedProvider, resolveMetaMaskInjectedProvider, resolveUsdtByMainnet, resolveUsdtContractAddress, setWalletEventProvider, setWalletReadProvider, syncWalletAccountAddress, toChainIdDecimal, walletEvents };
+export { BSC_NETWORK, BSC_TESTNET_NETWORK, ERC20_ABI, ERC20_DECIMALS, ERC20_DECIMALS_ABI, USDT_CONFIG, USDT_CONTRACT_ADDRESSES, assertBrowser, bindBrowserProvider, clearWalletRuntime, connectWalletAccount, createJsonRpcReadProvider, discoverWalletProviders, ensureTargetNetwork, findCoinbaseEip6963Provider, findDiscoveredProvider, findMetaMaskEip6963Provider, getAggregatedInjectedProvider, getConfiguredReadProvider, getContractDecimals, getContractPrice, getInjectedEthereumProviders, getReadProviderWithFallback, getSharedBrowserProvider, getWalletEventProvider, getWalletSdkConfig, hasAggregatedInjectedProvider, hasCoinbaseEip6963Provider, hasCoinbaseInjectedProvider, hasDeployedContract, hasMetaMaskEip6963Provider, hasMetaMaskInjectedProvider, hasRecoverableAggregatorProvider, initWalletSdk, isBrowser, isCoinbaseProvider, isContractDeployed, isEthereumProvider, isInjectedProvider, isTronLinkProvider, isWalletSdkInitialized, readErc20Decimals, rememberAggregatorProvider, requestWallet, resetWalletSdkConfig, resolveChainByMainnet, resolveChainConfig, resolveCoinbaseInjectedProvider, resolveMetaMaskInjectedProvider, resolveUsdtByMainnet, resolveUsdtContractAddress, setWalletEventProvider, setWalletReadProvider, syncWalletAccountAddress, toChainIdDecimal, walletEvents };

package/package.json

@@ -1,9 +1,12 @@
 {
   "name": "@earthworm/wallet-sdk",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "EVM wallet utilities for browser DApps",
   "type": "module",
   "sideEffects": false,
+  "engines": {
+    "node": ">=20.0.0"
+  },
   "publishConfig": {
     "access": "public"
   },
@@ -21,10 +24,10 @@
   },
   "keywords": [
     "ethereum",
-    "wallet",
-    "eip6963",
     "ethers",
-    "dapp"
+    "dapp",
+    "wallets",
+    "bsc"
   ],
   "license": "MIT",
   "author": "Alex",
@@ -38,6 +41,10 @@
   },
   "scripts": {
     "build": "tsup",
-    "dev": "tsup --watch"
+    "dev": "tsup --watch",
+    "release": "pnpm publish --access public",
+    "release:patch": "npm version patch && pnpm run release",
+    "release:minor": "npm version minor && pnpm run release",
+    "release:major": "npm version major && pnpm run release"
   }
 }