@earthworm/wallet-sdk 0.2.2 → 0.2.3

package/dist/index.d.ts

@@ -1,12 +1,12 @@
 import * as ethers from 'ethers';
-import { InterfaceAbi, Eip1193Provider, BrowserProvider, JsonRpcProvider, JsonRpcSigner } from 'ethers';
+import { Eip1193Provider, BrowserProvider, JsonRpcProvider, InterfaceAbi, JsonRpcSigner } from 'ethers';
 
 /**
- * 将 EVM 十六进制 chainId 转换为十进制 chainId。
- * 钱包 `chainChanged` / `eth_chainId` 返回的通常是 `0x` 前缀 hex 字符串。
- * @param chainId - 十六进制 chainId，如 `"0x38"`（56）或 `"0x61"`（97）。
- * @param fallback - 解析失败时的回退值；未传则返回 `NaN`。
- * @returns 十进制 chainId 数值，或 `fallback` / `NaN`。
+ * @en Convert hex chainId to decimal.
+ * @zh 将十六进制 chainId 转为十进制。
+ * @param {string} chainId @en Hex chainId, e.g. `"0x38"`. @zh 十六进制 chainId，如 `"0x38"`。
+ * @param {number} [fallback] @en Fallback when parse fails. @zh 解析失败时的回退值。
+ * @returns @en Decimal chainId or fallback / `NaN`. @zh 十进制 chainId 或回退值 / `NaN`。
  */
 declare function toChainIdDecimal(chainId: string, fallback?: number): number;
 
@@ -36,8 +36,10 @@ type ChainNativeCurrency = {
     symbol: string;
     decimals: number;
 };
+/** @en Supported BSC chain IDs: mainnet `0x38`, testnet `0x61`. @zh 支持的 BSC chainId：主网 `0x38`、测试网 `0x61`。 */
+type SupportedBscChainId = "0x38" | "0x61";
 type ChainConfig = {
-    chainId: string;
+    chainId: SupportedBscChainId;
     chainName: string;
     nativeCurrency: ChainNativeCurrency;
     rpcUrls: string[];
@@ -53,20 +55,15 @@ type Eip6963ProviderDetail = {
     info: Eip6963ProviderInfo;
     provider: Eip1193Provider;
 };
-type ContractConfig = {
+type UsdtInitConfig = {
+    /** @en USDT contract address. @zh USDT 合约地址。 */
     address: string;
-    abi: InterfaceAbi;
 };
 type WalletSdkInitOptions = {
-    /** `true` BSC 主网，`false` BSC 测试网 */
-    isMainnet: boolean;
-    contract: ContractConfig;
+    /** @en USDT contract address (mainnet or testnet, caller decides). @zh USDT 合约地址（主网/测试网由调用方决定）。 */
+    usdt: UsdtInitConfig;
 };
 type WalletSdkConfig = {
-    isMainnet: boolean;
-    chainId: string;
-    chain: ChainConfig;
-    contract: ContractConfig;
     usdt: {
         address: string;
         abi: InterfaceAbi;
@@ -75,373 +72,575 @@ type WalletSdkConfig = {
         decimals: number;
     };
 };
+type NetworkSwitchResult = {
+    chainId: SupportedBscChainId;
+    previousChainId: string;
+    /** @en `true` if switch was invoked; `false` if already on target chain. @zh `true` 已发起切链；`false` 已在目标链。 */
+    switched: boolean;
+};
+type ConnectWalletOptions = {
+    /** @en Switch wallet to this BSC chain after connect. @zh 连接后切换到指定 BSC 链。 */
+    chainId?: SupportedBscChainId;
+};
 
+declare enum Wallet6963Name {
+    MetaMask = "metamask",
+    Coinbase = "coinbase",
+    TokenPocket = "tokenpocket",
+    TronLink = "tronlink"
+}
+declare enum Wallet6963Rdns {
+    MetaMask = "io.metamask",
+    Coinbase = "com.coinbase.wallet",
+    TokenPocket = "com.tokenpocket",
+    /** @en TronLink browser extension rdns. @zh TronLink 浏览器扩展 rdns。 */
+    TronLink = "org.tronlink.www",
+    /** @en TronLink App WebView rdns. @zh TronLink App 内置 WebView rdns。 */
+    TronLinkAlt = "io.tronlink"
+}
 /**
- * 通过 EIP-6963 发现并收集浏览器中的钱包 provider。
- * 非浏览器环境直接返回空数组；多次调用共享同一次发现结果。
- * @param timeoutMs - 等待 `eip6963:announceProvider` 的超时毫秒数，默认 `500`。
- * @returns 已发现的 {@link Eip6963ProviderDetail} 列表。
+ * @en Discover wallet providers via EIP-6963 / TIP-6963.
+ * @zh 通过 EIP-6963 / TIP-6963 发现浏览器中的钱包 provider。
+ * @param {number} [timeoutMs] @en Timeout in ms, default `500`. @zh 等待 announce 的超时毫秒数，默认 `500`。
+ * @returns @en List of {@link Eip6963ProviderDetail}. @zh {@link Eip6963ProviderDetail} 列表。
  */
 declare function discoverWalletProviders(timeoutMs?: number): Promise<Eip6963ProviderDetail[]>;
 /**
- * 从已发现的 EIP-6963 provider 中按条件查找。
- * @param match - 匹配函数，入参为 {@link Eip6963ProviderDetail}。
- * @returns 匹配到的 EIP-1193 provider；未找到为 `undefined`。
+ * @en Find a provider from discovered EIP-6963 providers.
+ * @zh 从已发现的 EIP-6963 provider 中按条件查找。
+ * @param {(detail: Eip6963ProviderDetail) => boolean} match @en Match function. @zh 匹配函数。
+ * @returns @en EIP-1193 provider or `undefined`. @zh 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;
-/**
- * 查找 TokenPocket 的 EIP-6963 provider。
- * @returns TokenPocket EIP-1193 provider；未找到为 `undefined`。
- */
-declare function findTokenPocketEip6963Provider(): 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-6963 检测到 TokenPocket。
- * @returns 检测到为 `true`，否则 `false`。
- */
-declare function hasTokenPocketEip6963Provider(): boolean;
+/** @en Find MetaMask EIP-6963 provider. @zh 查找 MetaMask 的 EIP-6963 provider。 */
+declare const findMetaMaskEip6963Provider: () => ethers.Eip1193Provider | undefined;
+/** @en Find Coinbase Wallet EIP-6963 provider. @zh 查找 Coinbase Wallet 的 EIP-6963 provider。 */
+declare const findCoinbaseEip6963Provider: () => ethers.Eip1193Provider | undefined;
+/** @en Find TokenPocket EIP-6963 provider. @zh 查找 TokenPocket 的 EIP-6963 provider。 */
+declare const findTokenPocketEip6963Provider: () => ethers.Eip1193Provider | undefined;
+/** @en Find TronLink EIP/TIP-6963 provider. @zh 查找 TronLink 的 EIP/TIP-6963 provider。 */
+declare const findTronLinkEip6963Provider: () => ethers.Eip1193Provider | undefined;
+/** @en Whether MetaMask is detected via EIP-6963. @zh 是否通过 EIP-6963 检测到 MetaMask。 */
+declare const hasMetaMaskEip6963Provider: () => boolean;
+/** @en Whether Coinbase Wallet is detected via EIP-6963. @zh 是否通过 EIP-6963 检测到 Coinbase Wallet。 */
+declare const hasCoinbaseEip6963Provider: () => boolean;
+/** @en Whether TokenPocket is detected via EIP-6963. @zh 是否通过 EIP-6963 检测到 TokenPocket。 */
+declare const hasTokenPocketEip6963Provider: () => boolean;
+/** @en Whether TronLink is detected via EIP/TIP-6963. @zh 是否通过 EIP/TIP-6963 检测到 TronLink。 */
+declare const hasTronLinkEip6963Provider: () => boolean;
 
 /**
- * 获取与 EIP-1193 provider 绑定的共享 BrowserProvider（同一实例复用）。
- * @param ethereum - EIP-1193 provider，如 MetaMask 的 `window.ethereum`。
- * @returns ethers `BrowserProvider`。
+ * @en Get shared BrowserProvider bound to EIP-1193 provider.
+ * @zh 获取与 EIP-1193 provider 绑定的共享 BrowserProvider。
+ * @param {Eip1193Provider} ethereum @en EIP-1193 provider. @zh EIP-1193 provider。
+ * @returns @en ethers `BrowserProvider`. @zh ethers `BrowserProvider`。
  */
 declare function getSharedBrowserProvider(ethereum: Eip1193Provider): BrowserProvider;
 
 /**
- * 获取浏览器中所有 injected 以太坊 provider。
- * @returns {@link InjectedEthereumProvider} 数组；无 `window.ethereum` 时返回 `[]`。
+ * @en Get all injected Ethereum providers in the browser.
+ * @zh 获取浏览器中所有 injected 以太坊 provider。
+ * @returns @en Array of {@link InjectedEthereumProvider}. @zh {@link InjectedEthereumProvider} 数组。
  */
 declare function getInjectedEthereumProviders(): InjectedEthereumProvider[];
 /**
- * 解析 MetaMask injected provider（EIP-6963 → providerMap → providers 数组 → 根 ethereum）。
- * @returns MetaMask {@link WalletEventProvider}；未找到为 `undefined`。
+ * @en Resolve MetaMask injected provider.
+ * @zh 解析 MetaMask injected provider。
+ * @returns @en MetaMask {@link WalletEventProvider} or `undefined`. @zh MetaMask provider 或 `undefined`。
  */
 declare function resolveMetaMaskInjectedProvider(): WalletEventProvider | undefined;
 /**
- * 解析 Coinbase Wallet injected provider（扩展 → EIP-6963 → providerMap → providers 数组 → 根 ethereum）。
- * @returns Coinbase {@link WalletEventProvider}；未找到为 `undefined`。
+ * @en Resolve Coinbase Wallet injected provider.
+ * @zh 解析 Coinbase Wallet injected provider。
+ * @returns @en Coinbase {@link WalletEventProvider} or `undefined`. @zh Coinbase provider 或 `undefined`。
  */
 declare function resolveCoinbaseInjectedProvider(): WalletEventProvider | undefined;
 /**
- * 解析 TokenPocket injected provider（tokenpocket.ethereum → EIP-6963 → providers 数组 → 根 ethereum）。
- * @returns TokenPocket {@link WalletEventProvider}；未找到为 `undefined`。
+ * @en Resolve TokenPocket injected provider.
+ * @zh 解析 TokenPocket injected provider。
+ * @returns @en TokenPocket {@link WalletEventProvider} or `undefined`. @zh TokenPocket provider 或 `undefined`。
  */
 declare function resolveTokenPocketInjectedProvider(): WalletEventProvider | undefined;
 /**
- * 是否检测到 MetaMask injected provider。
- * @returns 检测到为 `true`，否则 `false`。
+ * @en Resolve TronLink injected provider.
+ * @zh 解析 TronLink injected provider。
+ * @returns @en TronLink {@link WalletEventProvider} or `undefined`. @zh TronLink provider 或 `undefined`。
+ */
+declare function resolveTronLinkInjectedProvider(): WalletEventProvider | undefined;
+/**
+ * @en Whether MetaMask injected provider is detected.
+ * @zh 是否检测到 MetaMask injected provider。
+ * @returns @en `true` if detected. @zh 检测到为 `true`。
  */
 declare function hasMetaMaskInjectedProvider(): boolean;
 /**
- * 是否检测到 Coinbase Wallet（扩展、request provider 或 injected）。
- * @returns 检测到为 `true`，否则 `false`。
+ * @en Whether Coinbase Wallet is detected.
+ * @zh 是否检测到 Coinbase Wallet。
+ * @returns @en `true` if detected. @zh 检测到为 `true`。
  */
 declare function hasCoinbaseInjectedProvider(): boolean;
 /**
- * 是否检测到 TokenPocket（扩展、tokenpocket.ethereum 或 injected）。
- * @returns 检测到为 `true`，否则 `false`。
+ * @en Whether TokenPocket is detected.
+ * @zh 是否检测到 TokenPocket。
+ * @returns @en `true` if detected. @zh 检测到为 `true`。
  */
 declare function hasTokenPocketInjectedProvider(): boolean;
 /**
- * 缓存当前可用的多钱包聚合根 provider（`ethereum.providers.length > 1`）。
- * 非浏览器环境无操作。
+ * @en Whether TronLink injected provider is detected.
+ * @zh 是否检测到 TronLink injected provider。
+ * @returns @en `true` if detected. @zh 检测到为 `true`。
+ */
+declare function hasTronLinkInjectedProvider(): boolean;
+/**
+ * @en Cache the current multi-wallet aggregator root provider.
+ * @zh 缓存当前可用的多钱包聚合根 provider。
  */
 declare function rememberAggregatorProvider(): void;
 /**
- * 是否存在可恢复的多钱包聚合 provider（当前页面或历史缓存）。
- * @returns 存在为 `true`，否则 `false`。
+ * @en Whether a recoverable multi-wallet aggregator provider exists.
+ * @zh 是否存在可恢复的多钱包聚合 provider。
+ * @returns @en `true` if exists. @zh 存在为 `true`。
  */
 declare function hasRecoverableAggregatorProvider(): boolean;
 /**
- * 获取聚合 injected provider（多钱包根节点或 TronLink + Coinbase 组合场景）。
- * @returns {@link InjectedEthereumProvider}；未找到为 `undefined`。
+ * @en Get aggregated injected provider.
+ * @zh 获取聚合 injected provider。
+ * @returns @en {@link InjectedEthereumProvider} or `undefined`. @zh provider 或 `undefined`。
  */
 declare function getAggregatedInjectedProvider(): WalletEventProvider | undefined;
 /**
- * 是否存在可用的聚合 injected 以太坊 provider。
- * @returns 存在为 `true`；非浏览器为 `false`。
+ * @en Whether an aggregated injected Ethereum provider is available.
+ * @zh 是否存在可用的聚合 injected 以太坊 provider。
+ * @returns @en `true` if available. @zh 存在为 `true`。
  */
 declare function hasAggregatedInjectedProvider(): boolean;
 
 declare const ERC20_DECIMALS_ABI: readonly ["function decimals() view returns (uint8)"];
+type Erc20BalanceResult = {
+    accountAddress: string;
+    balance: string;
+    decimals: number;
+};
 /**
- * 检查地址在链上是否已部署合约（有 bytecode 才算合约地址）。
- * @param readProvider - 只读 provider，ethers `BrowserProvider` 或 `JsonRpcProvider`。
- * @param address - 待检查的地址，如 `"0x..."`。
- * @returns 已部署为 `true`，无 bytecode 为 `false`。
+ * @en Check whether an address has deployed contract bytecode.
+ * @zh 检查地址在链上是否已部署合约。
+ * @param {EvmReadProvider} readProvider @en Read provider. @zh 只读 provider。
+ * @param {string} address @en Address to check. @zh 待检查的地址。
+ * @returns @en `true` if deployed. @zh 已部署为 `true`。
  */
 declare function hasDeployedContract(readProvider: EvmReadProvider, address: string): Promise<boolean>;
 /**
- * 读取 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 合约未部署时抛错。
+ * @en Read ERC20 token decimals.
+ * @zh 读取 ERC20 代币 decimals。
+ * @param {EvmReadProvider} readProvider @en Read provider. @zh 只读 provider。
+ * @param {string} tokenAddress @en ERC20 contract address. @zh ERC20 合约地址。
+ * @param {InterfaceAbi} [erc20Abi] @en Contract ABI. @zh 合约 ABI。
+ * @param {number} [fallback] @en Fallback when call fails. @zh 调用失败时的回退值。
+ * @returns @en Token decimals. @zh token decimals 数值。
  */
 declare function readErc20Decimals(readProvider: EvmReadProvider, tokenAddress: string, erc20Abi?: InterfaceAbi, fallback?: 18): Promise<number>;
+/**
+ * @en Read ERC20 token balance as formatted string.
+ * @zh 读取 ERC20 代币余额（格式化为人类可读字符串）。
+ * @param {EvmReadProvider} readProvider @en Read provider. @zh 只读 provider。
+ * @param {string} tokenAddress @en ERC20 contract address. @zh ERC20 合约地址。
+ * @param {string} accountAddress @en Holder account address. @zh 持有账户地址。
+ * @param {InterfaceAbi} [erc20Abi] @en Contract ABI. @zh 合约 ABI。
+ * @returns @en {@link Erc20BalanceResult}. @zh {@link Erc20BalanceResult}。
+ */
+declare function readErc20Balance(readProvider: EvmReadProvider, tokenAddress: string, accountAddress: string, erc20Abi?: InterfaceAbi): Promise<Erc20BalanceResult>;
 
 /**
- * 合约只读调用选项。
- * @property abi - 合约 ABI（`InterfaceAbi`），需包含目标读方法。
- * @property method - 要 `staticCall` 的合约方法名，如 `"decimals"`、`"getPrice"`。
+ * @en Clear JsonRpc read provider cache.
+ * @zh 清除 JsonRpc 只读 provider 缓存。
+ */
+declare function clearJsonRpcReadProviderCache(): void;
+/**
+ * @en Create and cache a JsonRpc read provider.
+ * @zh 创建并缓存 JsonRpc 只读 provider。
+ * @param {string} rpcUrl @en RPC node URL. @zh RPC 节点 URL。
+ * @param {string} chainIdHex @en Hex chainId. @zh 十六进制 chainId。
+ * @param {{ current: JsonRpcProvider | null }} [cache] @en Optional cache object. @zh 可选缓存对象。
+ * @returns @en ethers `JsonRpcProvider`. @zh ethers `JsonRpcProvider`。
+ */
+declare function createJsonRpcReadProvider(rpcUrl: string, chainIdHex: string, cache?: {
+    current: JsonRpcProvider | null;
+}): JsonRpcProvider;
+type ReadProviderRpcConfig = {
+    rpcUrls: string[];
+    chainId: string;
+};
+/**
+ * @en Get read provider: wallet BrowserProvider first, JsonRpc fallback.
+ * @zh 获取只读 provider：优先钱包 BrowserProvider，否则 JsonRpc 回退。
+ * @param {BrowserProvider | null} walletProvider @en Wallet BrowserProvider or `null`. @zh 钱包 BrowserProvider 或 `null`。
+ * @param {ReadProviderRpcConfig} rpcConfig @en RPC config. @zh RPC 配置。
+ * @param {string[]} rpcConfig.rpcUrls @en RPC URL list. @zh RPC 节点 URL 列表。
+ * @param {string} rpcConfig.chainId @en Hex chainId. @zh 十六进制 chainId。
+ * @param {{ current: JsonRpcProvider | null }} [fallbackCache] @en Optional JsonRpc cache. @zh 可选 JsonRpc 缓存。
+ * @returns @en {@link EvmReadProvider}. @zh {@link EvmReadProvider}。
+ */
+declare function getReadProviderWithFallback(walletProvider: BrowserProvider | null, rpcConfig: ReadProviderRpcConfig, fallbackCache?: {
+    current: JsonRpcProvider | null;
+}): EvmReadProvider;
+
+type GetConfiguredReadProviderOptions = {
+    /** @en BSC chain ID for JsonRpc fallback when wallet is not connected. @zh 未连接钱包时用于 JsonRpc 回退的 BSC chainId。 */
+    chainId?: SupportedBscChainId;
+};
+/**
+ * @en Options for contract read calls.
+ * @zh 合约只读调用选项。
+ * @property {InterfaceAbi} abi @en Contract ABI. @zh 合约 ABI。
+ * @property {string} method @en Method name for staticCall. @zh 用于 staticCall 的合约方法名。
  */
 type GetContractReadOptions = {
     abi: InterfaceAbi;
     method: string;
 };
 /**
- * 设置用于链上只读调用的钱包 BrowserProvider。
- * 设置后 `getConfiguredReadProvider` 会优先走钱包，否则回退到 init 配置中的 RPC。
- * @param provider - ethers `BrowserProvider`；传 `null` 则清除并回退到 RPC。
+ * @en Set wallet BrowserProvider for on-chain read calls.
+ * @zh 设置用于链上只读调用的钱包 BrowserProvider。
+ * @param {BrowserProvider | null} provider @en BrowserProvider or `null` to clear. @zh BrowserProvider；传 `null` 则清除。
  */
 declare function setWalletReadProvider(provider: BrowserProvider | null): void;
 /**
- * 获取当前配置的只读 provider。
- * 需先调用 `initWalletSdk`；优先返回已设置的钱包 BrowserProvider，否则使用 RPC fallback。
- * @returns ethers `BrowserProvider` 或 `JsonRpcProvider`。
- * @throws 未初始化 SDK，或 RPC 配置缺失时抛错。
+ * @en Rebuild wallet BrowserProvider after chain switch to avoid NETWORK_ERROR.
+ * @zh 切链后重建钱包 BrowserProvider，避免 ethers `NETWORK_ERROR`。
+ * @param {WalletEventProvider} eip1193 @en Current wallet EIP-1193 provider. @zh 当前钱包 EIP-1193 provider。
+ */
+declare function refreshWalletReadProvider(eip1193: WalletEventProvider): void;
+
+/**
+ * @en Get read provider: wallet first, otherwise JsonRpc via `chainId`.
+ * @zh 获取只读 provider：优先钱包，否则通过 `chainId` 使用 JsonRpc。
  */
-declare function getConfiguredReadProvider(): EvmReadProvider;
+declare function getConfiguredReadProvider(options?: GetConfiguredReadProviderOptions): EvmReadProvider;
 /**
- * 检查指定地址在当前链上是否已部署合约（是否存在 bytecode）。
- * @param contractAddress - 合约地址，如 `"0x55d398326f99059fF775485246999027B3197955"`。
- * @returns 已部署为 `true`，无 bytecode 为 `false`。
+ * @en Check whether a contract is deployed at the given address.
+ * @zh 检查指定地址在当前链上是否已部署合约。
+ * @param {string} contractAddress @en Contract address. @zh 合约地址。
+ * @returns @en `true` if deployed. @zh 已部署为 `true`。
  */
 declare function isContractDeployed(contractAddress: string): Promise<boolean>;
 /**
- * 读取 token 合约的 decimals。
- * @param contractAddress - 代币合约地址。
- * @param options - 读调用选项，见 {@link GetContractReadOptions}。
- * @param options.abi - 合约 ABI，需包含 `options.method` 对应的方法。
- * @param options.method - decimals 方法名，通常为 `"decimals"`。
- * @returns token decimals 数值，如 `18`。
- * @throws 合约未部署时抛错。
+ * @en Read token contract decimals.
+ * @zh 读取 token 合约的 decimals。
+ * @param {string} contractAddress @en Token contract address. @zh 代币合约地址。
+ * @param {GetContractReadOptions} options @en Read options. @zh 读调用选项。
+ * @returns @en Decimals number. @zh decimals 数值。
  */
 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 合约未部署时抛错。
+ * @en Read contract price formatted with token decimals.
+ * @zh 读取合约价格，并按 token decimals 格式化为人类可读字符串。
+ * @param {string} contractAddress @en Price contract address. @zh 价格合约地址。
+ * @param {GetContractReadOptions} options @en Read options. @zh 读调用选项。
+ * @returns @en Formatted price string. @zh 格式化后的价格字符串。
  */
 declare function getContractPrice(contractAddress: string, options: GetContractReadOptions): Promise<string>;
-
 /**
- * 确保钱包切换到目标网络；链未添加时自动调用 `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 错误会向上抛出。
+ * @en Read configured USDT decimals from `initWalletSdk`.
+ * @zh 读取 `initWalletSdk` 配置的 USDT decimals。
+ * @returns @en USDT decimals. @zh USDT decimals 数值。
+ */
+declare function readConfiguredUsdtDecimals(chainId?: SupportedBscChainId): Promise<number>;
+/**
+ * @en Read configured USDT balance from `initWalletSdk`.
+ * @zh 读取 `initWalletSdk` 配置的 USDT 余额。
+ * @param {string} accountAddress @en Holder account address. @zh 持有账户地址。
+ * @returns @en {@link Erc20BalanceResult}. @zh {@link Erc20BalanceResult}。
  */
-declare function ensureTargetNetwork(options: {
+declare function readUsdtBalance(accountAddress: string, chainId?: SupportedBscChainId): Promise<Erc20BalanceResult>;
+
+type EnsureTargetNetworkOptions = {
     targetChainId: string;
     getCurrentChainId: () => Promise<string>;
     switchChain: (chainId: string) => Promise<unknown>;
     addChain: (chainParams: Record<string, unknown>) => Promise<unknown>;
     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`。
+ * @en Ensure the wallet is on the target network; adds chain if missing.
+ * @zh 确保钱包切换到目标网络；链未添加时自动调用 `wallet_addEthereumChain`。
+ * @param {EnsureTargetNetworkOptions} options @en Network switch options. @zh 切链选项。
+ * @param {string} options.targetChainId @en Target hex chainId. @zh 目标十六进制 chainId。
+ * @param {() => Promise<string>} options.getCurrentChainId @en Async fn to get current chainId. @zh 获取当前 chainId 的异步函数。
+ * @param {(chainId: string) => Promise<unknown>} options.switchChain @en Async fn to switch chain. @zh 切换链的异步函数。
+ * @param {(chainParams: Record<string, unknown>) => Promise<unknown>} options.addChain @en Async fn to add chain. @zh 添加链的异步函数。
+ * @param {Record<string, unknown>} options.chainParams @en Chain params for addChain. @zh 传给 addChain 的链参数。
  */
-declare function createJsonRpcReadProvider(rpcUrl: string, chainIdHex: string, cache?: {
-    current: JsonRpcProvider | null;
-}): JsonRpcProvider;
+declare function ensureTargetNetwork(options: EnsureTargetNetworkOptions): Promise<void>;
 /**
- * 获取只读 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` 缺失时抛错。
+ * @en Switch wallet to specified BSC chain (`0x38` or `0x61`).
+ * @zh 将钱包切换到指定 BSC 链（主网 `0x38` / 测试网 `0x61`）。
  */
-declare function getReadProviderWithFallback(walletProvider: BrowserProvider | null, rpcConfig: {
-    rpcUrls: string[];
-    chainId: string;
-}, fallbackCache?: {
-    current: JsonRpcProvider | null;
-}): EvmReadProvider;
+declare function switchToConfiguredNetwork(chainId: SupportedBscChainId): Promise<NetworkSwitchResult>;
 
 /**
- * 将 EIP-1193 provider 绑定为 BrowserProvider 并写入缓存。
- * @param eip1193 - 钱包 EIP-1193 provider。
- * @param cache - BrowserProvider 缓存引用 `{ value: BrowserProvider | null }`。
- * @returns ethers `BrowserProvider`。
+ * @en Bind EIP-1193 provider as BrowserProvider and update cache.
+ * @zh 将 EIP-1193 provider 绑定为 BrowserProvider 并写入缓存。
+ * @param {WalletEventProvider} eip1193 @en Wallet EIP-1193 provider. @zh 钱包 EIP-1193 provider。
+ * @param {MutableRef<BrowserProvider | null>} cache @en BrowserProvider cache ref. @zh BrowserProvider 缓存引用。
+ * @returns @en ethers `BrowserProvider`. @zh 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` 的原始返回值。
+ * @en Send a JSON-RPC request to the wallet.
+ * @zh 向钱包发起 JSON-RPC 请求。
+ * @param {WalletEventProvider} eip1193 @en Wallet EIP-1193 provider. @zh 钱包 EIP-1193 provider。
+ * @param {string} method @en JSON-RPC method name. @zh JSON-RPC 方法名。
+ * @param {EthereumRequestParams} [params] @en Optional request params. @zh 可选请求参数。
+ * @returns @en Raw provider response. @zh provider 原始返回值。
  */
 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 钱包未返回账户时抛错。
+ * @en Connect wallet account and initialize signer.
+ * @zh 连接钱包账户并初始化 signer。
+ * @param {() => Promise<unknown>} requestAccounts @en Function to request accounts. @zh 请求账户的函数。
+ * @param {() => BrowserProvider} getProvider @en Function to get BrowserProvider. @zh 获取 BrowserProvider 的函数。
+ * @param {(signer: JsonRpcSigner) => void} setSigner @en Callback to set signer. @zh 设置 signer 的回调。
+ * @param {() => void} markConnected @en Callback to mark connected. @zh 标记已连接的回调。
+ * @returns @en `{ address, signer }`. @zh `{ address, signer }`。
  */
 declare function connectWalletAccount(requestAccounts: () => Promise<unknown>, getProvider: () => BrowserProvider, setSigner: (signer: JsonRpcSigner) => void, markConnected: () => void): Promise<{
     address: string;
     signer: JsonRpcSigner;
 }>;
+type ClearWalletRuntimeCache = {
+    provider: MutableRef<BrowserProvider | null>;
+    signer: MutableRef<JsonRpcSigner | null>;
+    selectedProvider?: MutableRef<WalletEventProvider | null>;
+};
 /**
- * 同步当前钱包账户地址与 signer（不触发授权弹窗）。
- * @param getProvider - 获取当前 BrowserProvider 的函数。
- * @param setSigner - 设置 signer 的回调。
- * @param markConnected - 标记已连接的回调。
- * @param nextAddress - 可选指定账户地址；未传则使用 provider 默认账户。
- * @returns 同步结果 `{ address: string; signer: JsonRpcSigner }`。
+ * @en Sync wallet account address and signer without authorization prompt.
+ * @zh 同步当前钱包账户地址与 signer（不触发授权弹窗）。
+ * @param {() => BrowserProvider} getProvider @en Function to get BrowserProvider. @zh 获取 BrowserProvider 的函数。
+ * @param {(signer: JsonRpcSigner) => void} setSigner @en Callback to set signer. @zh 设置 signer 的回调。
+ * @param {() => void} markConnected @en Callback to mark connected. @zh 标记已连接的回调。
+ * @param {string} [nextAddress] @en Optional account address. @zh 可选指定账户地址。
+ * @returns @en `{ address, signer }`. @zh `{ address, signer }`。
  */
 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 缓存引用。
+ * @en Clear wallet runtime cache.
+ * @zh 清除钱包运行时缓存。
+ * @param {ClearWalletRuntimeCache} cache @en Runtime cache object. @zh 运行时缓存对象。
+ * @param {MutableRef<BrowserProvider | null>} cache.provider @en BrowserProvider cache ref. @zh BrowserProvider 缓存引用。
+ * @param {MutableRef<JsonRpcSigner | null>} cache.signer @en Signer cache ref. @zh Signer 缓存引用。
+ * @param {MutableRef<WalletEventProvider | null>} [cache.selectedProvider] @en Optional selected EIP-1193 provider ref. @zh 可选选中的 EIP-1193 provider 引用。
  */
-declare function clearWalletRuntime(cache: {
-    provider: MutableRef<BrowserProvider | null>;
-    signer: MutableRef<JsonRpcSigner | null>;
-    selectedProvider?: MutableRef<WalletEventProvider | null>;
-}): void;
+declare function clearWalletRuntime(cache: ClearWalletRuntimeCache): void;
+
+/**
+ * @en Whether the wallet is connected.
+ * @zh 是否已连接钱包。
+ * @returns @en `true` if connected. @zh 已连接为 `true`。
+ */
+declare function isWalletConnected(): boolean;
+/**
+ * @en Get the connected signer.
+ * @zh 获取当前连接的 signer。
+ * @returns @en Connected {@link JsonRpcSigner}. @zh 已连接的 {@link JsonRpcSigner}。
+ */
+declare function getWalletSigner(): JsonRpcSigner;
+/**
+ * @en Get the connected account address.
+ * @zh 获取当前连接账户地址。
+ * @returns @en Account address string. @zh 账户地址字符串。
+ */
+declare function getConnectedAddress(): Promise<string>;
+/**
+ * @en Get the selected EIP-1193 provider.
+ * @zh 获取当前选中的 EIP-1193 provider。
+ * @returns @en {@link WalletEventProvider} or `null`. @zh {@link WalletEventProvider} 或 `null`。
+ */
+declare function getSelectedWalletProvider(): WalletEventProvider | null;
+/**
+ * @en Get the current BrowserProvider.
+ * @zh 获取当前 BrowserProvider。
+ * @returns @en `BrowserProvider` or `null`. @zh `BrowserProvider` 或 `null`。
+ */
+declare function getWalletBrowserProvider(): BrowserProvider | null;
+/**
+ * @en Bind the wallet provider.
+ * @zh 绑定钱包 provider。
+ * @param {WalletEventProvider} eip1193 @en Wallet EIP-1193 provider. @zh 钱包 EIP-1193 provider。
+ * @returns @en Bound `BrowserProvider`. @zh 绑定后的 `BrowserProvider`。
+ */
+declare function bindWalletProvider(eip1193: WalletEventProvider): BrowserProvider;
+/**
+ * @en Sync the wallet provider after chain switch.
+ * @zh 切链后同步钱包 provider。
+ */
+declare function syncWalletRuntimeProvider(): void;
+/**
+ * @en Connect the wallet; optionally switch to a BSC chain when `chainId` is provided.
+ * @zh 连接钱包；传入 `chainId` 时在连接后切换到对应 BSC 链。
+ */
+declare function connectWallet(eip1193: WalletEventProvider, options?: ConnectWalletOptions): Promise<{
+    address: string;
+    signer: JsonRpcSigner;
+}>;
+/**
+ * @en Sync the connected wallet signer.
+ * @zh 同步已连接钱包的 signer。
+ * @param {string} [nextAddress] @en Optional account address. @zh 可选账户地址。
+ * @returns @en `{ address, signer }`. @zh `{ address, signer }`。
+ */
+declare function syncConnectedWalletAccount(nextAddress?: string): Promise<{
+    address: string;
+    signer: JsonRpcSigner;
+}>;
+/**
+ * @en Get authorized accounts from the connected wallet (`eth_accounts`).
+ * @zh 获取已连接钱包的授权账户列表（`eth_accounts`）。
+ * @returns @en Account address strings. @zh 账户地址列表。
+ */
+declare function getWalletAccounts(): Promise<string[]>;
+/**
+ * @en Refresh authorized accounts from the wallet.
+ * @zh 向钱包重新请求授权账户；已连接时优先调用 `wallet_requestPermissions` 以弹出 MetaMask / Coinbase 账户选择。
+ * @returns @en Account address strings. @zh 账户地址列表。
+ */
+declare function refreshWalletAccounts(): Promise<string[]>;
+/**
+ * @en Switch the active signer to another authorized account address.
+ * @zh 切换到钱包内另一个已授权账户地址。
+ * @param {string} address @en Target account address. @zh 目标账户地址。
+ * @returns @en `{ address, signer }`. @zh `{ address, signer }`。
+ */
+declare function switchWalletAccount(address: string): Promise<{
+    address: string;
+    signer: JsonRpcSigner;
+}>;
+/**
+ * @en Disconnect the wallet.
+ * @zh 断开钱包连接。
+ */
+declare function disconnectWallet(): void;
+
+type SupportedWalletKey = "metamask" | "tronlink" | "coinbase" | "tokenpocket" | "unknown";
+/**
+ * @en Resolve wallet key from an injected EIP-1193 provider.
+ * @zh 从 injected EIP-1193 provider 解析钱包 key。
+ */
+declare function resolveWalletKey(provider: WalletEventProvider | null | undefined): SupportedWalletKey;
+
+type WalletNativeEvent<TPayload = unknown> = {
+    name: string;
+    payload: TPayload;
+    raw: unknown[];
+};
 
-type WalletProviderEventMap = {
+type WalletSdkEventMap = {
     accountsChanged: string[];
     chainChanged: string;
+    networkSwitched: NetworkSwitchResult;
 };
-type WalletProviderEventName = keyof WalletProviderEventMap;
-type WalletProviderEventListener<K extends WalletProviderEventName = WalletProviderEventName> = (payload: WalletProviderEventMap[K]) => void | Promise<void>;
+type WalletSdkEventName = keyof WalletSdkEventMap;
+type WalletScopedEventListener<K extends WalletSdkEventName = WalletSdkEventName> = (wallet: SupportedWalletKey, event: WalletNativeEvent<WalletSdkEventMap[K]>) => void | Promise<void>;
+/**
+ * @en Emit an SDK wallet event (e.g. `networkSwitched`).
+ * @zh 触发 SDK 钱包事件（如 `networkSwitched`）。
+ */
+declare function emitWalletEvent<K extends WalletSdkEventName>(sdkEvent: K, wallet: SupportedWalletKey, event: WalletNativeEvent<WalletSdkEventMap[K]>): void;
 /**
- * 设置当前钱包 EIP-1193 provider，供 `walletEvents` 事件监听使用。
- * @param provider - 钱包 EIP-1193 provider；传 `null` 则解除绑定。
+ * @en Set wallet EIP-1193 provider for `walletEvents` listening.
+ * @zh 设置当前钱包 EIP-1193 provider，供 `walletEvents` 事件监听使用。
  */
 declare function setWalletEventProvider(provider: WalletEventProvider | null): void;
 /**
- * 获取当前已设置的钱包 EIP-1193 provider。
- * @returns {@link WalletEventProvider}。
- * @throws 未调用 `setWalletEventProvider` 时抛错。
+ * @en Get the current wallet EIP-1193 provider.
+ * @zh 获取当前已设置的钱包 EIP-1193 provider。
  */
 declare function getWalletEventProvider(): WalletEventProvider;
-declare class WalletEventsEmitter {
-    on(event: "accountsChanged", listener: WalletProviderEventListener<"accountsChanged">): void;
-    on(event: "chainChanged", listener: WalletProviderEventListener<"chainChanged">): void;
-    on(event: WalletProviderEventName, listener: (...args: any[]) => void | Promise<void>): void;
-    off(event: "accountsChanged", listener: WalletProviderEventListener<"accountsChanged">): void;
-    off(event: "chainChanged", listener: WalletProviderEventListener<"chainChanged">): void;
-    off(event: WalletProviderEventName, listener?: (...args: any[]) => void | Promise<void>): void;
+/** @en Active wallet key for the bound provider. @zh 当前绑定 provider 的钱包 key。 */
+declare function getActiveWalletKey(): SupportedWalletKey;
+declare class WalletEvents {
+    on<K extends WalletSdkEventName>(event: K, listener: WalletScopedEventListener<K>): void;
+    off<K extends WalletSdkEventName>(event: K, listener?: WalletScopedEventListener<K>): void;
     clear(): void;
 }
-type WalletEvents = WalletEventsEmitter;
-/** 钱包事件总线，支持 `accountsChanged` / `chainChanged` 监听。需先 `setWalletEventProvider`。 */
-declare const walletEvents: WalletEventsEmitter;
+declare const walletEvents: WalletEvents;
+
+type WalletAccountsSyncResult = {
+    action: "synced" | "disconnected" | "ignored";
+    address?: string;
+};
+/**
+ * @en Apply wallet-specific account sync/disconnect side effects.
+ * @zh 按钱包类型应用账户同步/断开副作用。
+ */
+declare function applyWalletAccountsChangedEffect(wallet: SupportedWalletKey, accounts: string[]): Promise<WalletAccountsSyncResult>;
 
-/** 是否在浏览器环境（模块加载时判定一次）。 */
+/** @en Whether running in a browser environment. @zh 是否在浏览器环境。 */
 declare const isBrowser: boolean;
 /**
- * 断言当前为浏览器环境；非浏览器时抛错。
- * 检测类 API 请先用 {@link isBrowser} 判断后返回，而非调用此函数。
- * @param apiName - 调用方 API 名称，用于错误信息，如 `"walletEvents.on"`。
- * @throws 非浏览器环境时抛错。
+ * @en Assert browser environment; throws if not in browser.
+ * @zh 断言当前为浏览器环境；非浏览器时抛错。
+ * @param {string} apiName @en API name for error message. @zh 用于错误信息的 API 名称。
  */
 declare function assertBrowser(apiName: string): void;
 
 /**
- * 是否检测到 MetaMask（injected 或 EIP-6963）。
- * @returns 浏览器中检测到 MetaMask 为 `true`；非浏览器或未检测到为 `false`。
+ * @en Whether MetaMask is detected (injected or EIP-6963).
+ * @zh 是否检测到 MetaMask（injected 或 EIP-6963）。
+ * @returns @en `true` if detected. @zh 检测到为 `true`。
  */
 declare function isEthereumProvider(): boolean;
 /**
- * 是否检测到 Coinbase Wallet。
- * @returns 浏览器中检测到 Coinbase 为 `true`；非浏览器或未检测到为 `false`。
+ * @en Whether Coinbase Wallet is detected.
+ * @zh 是否检测到 Coinbase Wallet。
+ * @returns @en `true` if detected. @zh 检测到为 `true`。
  */
 declare function isCoinbaseProvider(): boolean;
 /**
- * 是否检测到 TokenPocket（injected 或 EIP-6963）。
- * @returns 浏览器中检测到 TokenPocket 为 `true`；非浏览器或未检测到为 `false`。
+ * @en Whether TokenPocket is detected (injected or EIP-6963).
+ * @zh 是否检测到 TokenPocket（injected 或 EIP-6963）。
+ * @returns @en `true` if detected. @zh 检测到为 `true`。
  */
 declare function isTokenPocketProvider(): boolean;
 /**
- * 是否检测到通用 injected 以太坊钱包（含多钱包聚合器）。
- * @returns 浏览器中存在可用 injected provider 为 `true`；否则 `false`。
+ * @en Whether a generic injected Ethereum wallet is detected.
+ * @zh 是否检测到通用 injected 以太坊钱包。
+ * @returns @en `true` if detected. @zh 检测到为 `true`。
  */
 declare function isInjectedProvider(): boolean;
 /**
- * 是否检测到 TronLink。
- * @returns 浏览器中 `window.tron` 或 `window.tronLink` 可用为 `true`；否则 `false`。
+ * @en Whether TronLink is detected (injected or EIP/TIP-6963).
+ * @zh 是否检测到 TronLink（injected 或 EIP/TIP-6963）。
+ * @returns @en `true` if detected. @zh 检测到为 `true`。
  */
 declare function isTronLinkProvider(): boolean;
 
 /**
- * 初始化 SDK 并将配置持久化到 `globalThis`，供各模块通过 `getWalletSdkConfig` 读取。
- * @param options - 初始化选项，见 {@link WalletSdkInitOptions}。
- * @param options.isMainnet - `true` 使用 BSC 主网，`false` 使用 BSC 测试网。
- * @param options.contract - 业务合约配置（`address` + `abi`）。
- * @returns 完整 SDK 配置 {@link WalletSdkConfig}。
+ * @en Initialize SDK and persist config to `globalThis`.
+ * @zh 初始化 SDK 并将配置持久化到 `globalThis`。
  */
 declare function initWalletSdk(options: WalletSdkInitOptions): WalletSdkConfig;
 /**
- * 读取已初始化的 SDK 配置。
- * @returns 当前 {@link WalletSdkConfig}。
- * @throws 未调用 `initWalletSdk` 时抛错。
+ * @en Get initialized SDK config.
+ * @zh 读取已初始化的 SDK 配置。
  */
 declare function getWalletSdkConfig(): WalletSdkConfig;
 /**
- * 判断 SDK 是否已完成初始化。
- * @returns 已调用 `initWalletSdk` 为 `true`，否则 `false`。
+ * @en Whether SDK is initialized.
+ * @zh 判断 SDK 是否已完成初始化。
  */
 declare function isWalletSdkInitialized(): boolean;
 /**
- * 清除已持久化的 SDK 配置（主要用于测试或热重载）。
+ * @en Reset persisted SDK config (mainly for tests or hot reload).
+ * @zh 清除已持久化的 SDK 配置与初始化状态。
  */
 declare function resetWalletSdkConfig(): void;
 
+/** @en BSC mainnet configuration. @zh BSC 主网配置。 */
 declare const BSC_NETWORK: {
-    chainId: string;
+    chainId: "0x38";
     chainName: string;
     nativeCurrency: {
         name: string;
@@ -451,8 +650,9 @@ declare const BSC_NETWORK: {
     rpcUrls: string[];
     blockExplorerUrls: string[];
 };
+/** @en BSC testnet configuration. @zh BSC 测试网配置。 */
 declare const BSC_TESTNET_NETWORK: {
-    chainId: string;
+    chainId: "0x61";
     chainName: string;
     nativeCurrency: {
         name: string;
@@ -463,37 +663,21 @@ declare const BSC_TESTNET_NETWORK: {
     blockExplorerUrls: string[];
 };
 
-/** 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;
+declare const SUPPORTED_BSC_CHAIN_IDS: ["0x38", "0x61"];
 /**
- * 根据是否主网解析 BSC USDT 合约地址。
- * @param isMainnet - `true` 主网 USDT，`false` 测试网 USDT。
- * @returns USDT 合约地址字符串。
+ * @en Normalize and validate supported BSC chainId (`0x38` or `0x61`).
+ * @zh 校验并规范化为支持的 BSC chainId（主网 `0x38` / 测试网 `0x61`）。
+ * @param {string | number} chainId @en Hex or decimal chainId. @zh 十六进制或十进制 chainId。
+ * @returns @en {@link SupportedBscChainId}. @zh {@link SupportedBscChainId}。
  */
-declare function resolveUsdtByMainnet(isMainnet: boolean): "0x55d398326f99059fF775485246999027B3197955" | "0x66E972502A34A625828C544a1914E8D8cc2A9dE5";
+declare function normalizeSupportedBscChainId(chainId: string | number): SupportedBscChainId;
 /**
- * 根据 chainId 解析 BSC 链配置。
- * @param chainId - 十六进制 chainId，如 `"0x38"` 或 `"0x61"`。
- * @returns {@link ChainConfig}。
- * @throws 不支持的 chainId 时抛错。
+ * @en Resolve BSC chain config by chainId.
+ * @zh 根据 chainId 解析 BSC 链配置。
+ * @param {SupportedBscChainId} chainId @en Supported BSC chain ID. @zh 支持的 BSC chainId。
+ * @returns @en {@link ChainConfig}. @zh {@link ChainConfig}。
  */
-declare function resolveChainConfig(chainId: string): ChainConfig;
+declare function resolveChainConfig(chainId: SupportedBscChainId): ChainConfig;
 
 declare const USDT_CONFIG: {
     readonly symbol: "USDT";
@@ -541,7 +725,7 @@ declare const USDT_CONFIG: {
         stateMutability?: undefined;
     })[];
 };
-/** BSC 上 ERC20 代币统一 decimals（如 USDT 为 18） */
+/** @en Unified ERC20 decimals on BSC (USDT is 18). @zh BSC 上 ERC20 代币统一 decimals（USDT 为 18）。 */
 declare const ERC20_DECIMALS: 18;
 
 declare const ERC20_ABI: ({
@@ -586,4 +770,4 @@ declare const ERC20_ABI: ({
     stateMutability?: undefined;
 })[];
 
-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, findTokenPocketEip6963Provider, getAggregatedInjectedProvider, getConfiguredReadProvider, getContractDecimals, getContractPrice, getInjectedEthereumProviders, getReadProviderWithFallback, getSharedBrowserProvider, getWalletEventProvider, getWalletSdkConfig, hasAggregatedInjectedProvider, hasCoinbaseEip6963Provider, hasCoinbaseInjectedProvider, hasDeployedContract, hasMetaMaskEip6963Provider, hasMetaMaskInjectedProvider, hasRecoverableAggregatorProvider, hasTokenPocketEip6963Provider, hasTokenPocketInjectedProvider, initWalletSdk, isBrowser, isCoinbaseProvider, isContractDeployed, isEthereumProvider, isInjectedProvider, isTokenPocketProvider, isTronLinkProvider, isWalletSdkInitialized, readErc20Decimals, rememberAggregatorProvider, requestWallet, resetWalletSdkConfig, resolveChainByMainnet, resolveChainConfig, resolveCoinbaseInjectedProvider, resolveMetaMaskInjectedProvider, resolveTokenPocketInjectedProvider, resolveUsdtByMainnet, resolveUsdtContractAddress, setWalletEventProvider, setWalletReadProvider, syncWalletAccountAddress, toChainIdDecimal, walletEvents };
+export { BSC_NETWORK, BSC_TESTNET_NETWORK, type ChainConfig, type ChainNativeCurrency, type ConnectWalletOptions, ERC20_ABI, ERC20_DECIMALS, ERC20_DECIMALS_ABI, type Eip6963ProviderDetail, type Eip6963ProviderInfo, type Erc20BalanceResult, type EthereumRequestParams, type EvmReadProvider, type GetConfiguredReadProviderOptions, type GetContractReadOptions, type InjectedEthereumProvider, type MutableRef, type NetworkSwitchResult, SUPPORTED_BSC_CHAIN_IDS, type SupportedBscChainId, type SupportedWalletKey, USDT_CONFIG, type UsdtInitConfig, Wallet6963Name, Wallet6963Rdns, type WalletAccountsSyncResult, type WalletEventProvider, WalletEvents, type WalletNativeEvent, type WalletScopedEventListener, type WalletSdkConfig, type WalletSdkEventMap, type WalletSdkEventName, type WalletSdkInitOptions, applyWalletAccountsChangedEffect, assertBrowser, bindBrowserProvider, bindWalletProvider, clearJsonRpcReadProviderCache, clearWalletRuntime, connectWallet, connectWalletAccount, createJsonRpcReadProvider, disconnectWallet, discoverWalletProviders, emitWalletEvent, ensureTargetNetwork, findCoinbaseEip6963Provider, findDiscoveredProvider, findMetaMaskEip6963Provider, findTokenPocketEip6963Provider, findTronLinkEip6963Provider, getActiveWalletKey, getAggregatedInjectedProvider, getConfiguredReadProvider, getConnectedAddress, getContractDecimals, getContractPrice, getInjectedEthereumProviders, getReadProviderWithFallback, getSelectedWalletProvider, getSharedBrowserProvider, getWalletAccounts, getWalletBrowserProvider, getWalletEventProvider, getWalletSdkConfig, getWalletSigner, hasAggregatedInjectedProvider, hasCoinbaseEip6963Provider, hasCoinbaseInjectedProvider, hasDeployedContract, hasMetaMaskEip6963Provider, hasMetaMaskInjectedProvider, hasRecoverableAggregatorProvider, hasTokenPocketEip6963Provider, hasTokenPocketInjectedProvider, hasTronLinkEip6963Provider, hasTronLinkInjectedProvider, initWalletSdk, isBrowser, isCoinbaseProvider, isContractDeployed, isEthereumProvider, isInjectedProvider, isTokenPocketProvider, isTronLinkProvider, isWalletConnected, isWalletSdkInitialized, normalizeSupportedBscChainId, readConfiguredUsdtDecimals, readErc20Balance, readErc20Decimals, readUsdtBalance, refreshWalletAccounts, refreshWalletReadProvider, rememberAggregatorProvider, requestWallet, resetWalletSdkConfig, resolveChainConfig, resolveCoinbaseInjectedProvider, resolveMetaMaskInjectedProvider, resolveTokenPocketInjectedProvider, resolveTronLinkInjectedProvider, resolveWalletKey, setWalletEventProvider, setWalletReadProvider, switchToConfiguredNetwork, switchWalletAccount, syncConnectedWalletAccount, syncWalletAccountAddress, syncWalletRuntimeProvider, toChainIdDecimal, walletEvents };