Widget Light 钱包管理

在 Widget Light 中，主机应用拥有所有钱包连接。运行在 iframe 内的 widget 从不直接接触浏览器扩展或私钥。取而代之的是，生态系统处理器将来自 iframe 的 RPC 请求桥接到你的钱包 provider。

钱包桥接的工作原理

当 iframe 内的 widget 需要执行钱包操作（发送交易、签名消息、切换链）时，它会通过 postMessage 发送一条 RPC_REQUEST 消息。主机端的处理器使用你的钱包 provider 处理该请求，并将结果作为 RPC_RESPONSE 发送回来。

Widget (iframe)                         Host (your app)
     |                                       |
     |-- RPC_REQUEST (eth_sendTransaction) ->|
     |                                       |-- wagmi sends tx
     |                                       |<- tx hash
     |<- RPC_RESPONSE (tx hash) ------------|

钱包状态变化（账户切换、链更改、连接/断开连接）也会通过 EVENT 消息自动从主机推送到 iframe。

IframeEcosystemHandler 接口

每个生态系统处理器都实现 IframeEcosystemHandler 接口：

interface IframeEcosystemHandler {
  /** Chain type identifier: 'EVM' | 'SVM' | 'UTXO' | 'MVM' | 'TVM' */
  chainType: WidgetLightChainType

  /** Returns initial wallet state sent with the INIT handshake */
  getInitState(): EcosystemInitState | null

  /** Handles an RPC request forwarded from the iframe */
  handleRequest(id: string, method: string, params?: unknown): Promise<unknown>

  /** Subscribes to wallet state changes; returns an unsubscribe function */
  subscribe(emit: (event: string, data: unknown) => void): () => void
}

生态系统处理器

EVM — `useEthereumIframeHandler()`

import { useEthereumIframeHandler } from '@lifi/widget-light/ethereum'

EVM 处理器会自动从你的 wagmi 上下文中读取钱包状态。无需任何参数。

const ethHandler = useEthereumIframeHandler()

细节	值
链类型	`EVM`
读取来源	wagmi 上下文（`useConnection`、`useWalletClient`、`usePublicClient`、`useSwitchChain`）
对等依赖	`wagmi`、`viem`、`@wagmi/core`
参数	无

支持的 RPC 方法：

方法	说明
`eth_accounts`	返回已连接的账户
`eth_requestAccounts`	请求账户访问权限
`eth_chainId`	返回当前链 ID（十六进制）
`net_version`	返回当前网络版本
`eth_sendTransaction`	发送交易（支持 EIP-1559 和 legacy gas）
`personal_sign`	签名任意消息
`eth_sign`	签名数据
`eth_signTypedData_v4`	签名 EIP-712 类型化数据
`wallet_switchEthereumChain`	切换到另一条链
`wallet_addEthereumChain`	向钱包添加新链
`wallet_sendCalls`	发送批处理调用（EIP-5792）
`wallet_getCallsStatus`	获取批处理调用的状态（EIP-5792）
`wallet_showCallsStatus`	显示批处理调用状态 UI（EIP-5792）
`wallet_getCapabilities`	查询钱包能力（EIP-5792）

任何无法识别的方法都会被转发到公共客户端（例如 eth_getBalance、eth_call）。 发出的钱包事件： accountsChanged、chainChanged、connect

Solana — `useSolanaIframeHandler(params)`

import { useSolanaIframeHandler } from '@lifi/widget-light/solana'

Solana 处理器与具体库无关。你需要显式传入钱包状态，因此它可以与任何提供 wallet-standard Wallet 实例的 Solana 钱包库配合使用。

const solHandler = useSolanaIframeHandler({
  address: solanaAddress,     // string | null
  connected: solanaConnected, // boolean
  wallet: solanaWallet,       // Wallet from @wallet-standard/base | null
})

细节	值
链类型	`SVM`
对等依赖	`@wallet-standard/base`

参数：

参数	类型	说明
`address`	`string \| null`	已连接的钱包地址
`connected`	`boolean`	是否已连接钱包
`wallet`	`Wallet \| null`	wallet-standard 的 `Wallet` 实例

支持的 RPC 方法：

方法	说明
`getAccount`	返回当前账户地址
`signTransaction`	签名序列化的交易（base64）
`signMessage`	签名任意消息（base64）
`signAndSendTransaction`	签名并发送交易（base64）

发出的钱包事件： accountsChanged、connect、disconnect

Bitcoin — `useBitcoinIframeHandler()`

import { useBitcoinIframeHandler } from '@lifi/widget-light/bitcoin'

Bitcoin 处理器会自动从 @bigmi/react 上下文中读取钱包状态。无需任何参数。

const btcHandler = useBitcoinIframeHandler()

细节	值
链类型	`UTXO`
读取来源	`@bigmi/react` 上下文（`useAccount`、`useConfig`）
对等依赖	`@bigmi/client`、`@bigmi/react`
参数	无

支持的 RPC 方法：

方法	说明
`getAccount`	返回当前账户地址和公钥
其他方法	通过 `client.request()` 转发到钱包客户端

发出的钱包事件： accountsChanged、connect、disconnect

Sui — `useSuiIframeHandler()`

import { useSuiIframeHandler } from '@lifi/widget-light/sui'

Sui 处理器会自动从 @mysten/dapp-kit-react 钩子中读取钱包状态。无需任何参数。

const suiHandler = useSuiIframeHandler()

细节	值
链类型	`MVM`
读取来源	`@mysten/dapp-kit-react` 钩子（`useCurrentWallet`、`useDAppKit`、`useWalletConnection`）
对等依赖	`@mysten/dapp-kit-react`
参数	无

支持的 RPC 方法：

方法	说明
`getAccount`	返回当前账户地址
`signTransaction`	签名交易块（base64）
`signPersonalMessage`	签名任意消息（base64）
`signAndExecuteTransaction`	签名并执行交易块

发出的钱包事件： accountsChanged、connect、disconnect

Tron — `useTronIframeHandler(params)`

import { useTronIframeHandler } from '@lifi/widget-light/tron'

Tron 处理器与具体库无关。你需要显式传入钱包状态，因此它可以与任何提供兼容适配器的 Tron 钱包库配合使用。

const tronHandler = useTronIframeHandler({
  address: tronAddress,     // string | null
  connected: tronConnected, // boolean
  adapter: tronAdapter,     // TronAdapter | null
})

细节	值
链类型	`TVM`
对等依赖	无（适配器状态需显式传入）

参数：

参数	类型	说明
`address`	`string \| null`	已连接的钱包地址
`connected`	`boolean`	是否已连接钱包
`adapter`	`TronAdapter \| null`	带有 `signTransaction` 和 `signMessage` 方法的钱包适配器

支持的 RPC 方法：

方法	说明
`getAccount`	返回当前账户地址
`signTransaction`	签名 TronWeb 交易对象（JSON）
`signMessage`	签名任意消息字符串

发出的钱包事件： accountsChanged、connect、disconnect

子路径导入

每个生态系统处理器都通过子路径导入暴露，以支持 tree-shaking。如果你只使用 EVM，则 Solana、Bitcoin、Sui 和 Tron 处理器（及其对等依赖）永远不会包含在你的 bundle 中：

// Only includes EVM handler code
import { useEthereumIframeHandler } from '@lifi/widget-light/ethereum'

// Only includes Solana handler code
import { useSolanaIframeHandler } from '@lifi/widget-light/solana'

// Only includes Bitcoin handler code
import { useBitcoinIframeHandler } from '@lifi/widget-light/bitcoin'

// Only includes Sui handler code
import { useSuiIframeHandler } from '@lifi/widget-light/sui'

// Only includes Tron handler code
import { useTronIframeHandler } from '@lifi/widget-light/tron'

组合多个处理器

将你的所有处理器作为数组传入。widget 会将每个 RPC 请求路由到与该请求 chainType 匹配的处理器：

import { LiFiWidgetLight } from '@lifi/widget-light'
import { useEthereumIframeHandler } from '@lifi/widget-light/ethereum'
import { useSolanaIframeHandler } from '@lifi/widget-light/solana'
import { useMemo } from 'react'

function App() {
  const ethHandler = useEthereumIframeHandler()
  const solHandler = useSolanaIframeHandler({
    address: solanaAddress,
    connected: solanaConnected,
    wallet: solanaWallet,
  })

  const handlers = useMemo(
    () => [ethHandler, solHandler],
    [ethHandler, solHandler]
  )

  return (
    <LiFiWidgetLight
      config={{ integrator: 'my-app' }}
      handlers={handlers}
    />
  )
}

外部钱包管理

如果你的应用有自己的钱包连接 UI（连接按钮、弹窗等），请使用 onConnect prop 来拦截来自 widget 的钱包连接请求。当提供了 onConnect 时，widget 会向主机发送 CONNECT_WALLET_REQUEST，而不是打开其内置的钱包菜单。

import { LiFiWidgetLight } from '@lifi/widget-light'
import type { ConnectWalletArgs } from '@lifi/widget-light'
import { useCallback } from 'react'

function App() {
  const handleConnect = useCallback((args?: ConnectWalletArgs) => {
    // args.chainId - the chain the widget wants to connect to (optional)
    // args.chainType - the chain type ('EVM', 'SVM', 'UTXO', 'MVM', 'TVM') (optional)
    openYourWalletModal(args)
  }, [])

  return (
    <LiFiWidgetLight
      config={{ integrator: 'my-app' }}
      handlers={handlers}
      onConnect={handleConnect}
    />
  )
}

ConnectWalletArgs 类型包含：

字段	类型	说明
`chainId`	`number \| undefined`	widget 想要连接到的链 ID
`chainType`	`WidgetChainType \| undefined`	链类型（`'EVM'`、`'SVM'`、`'UTXO'`、`'MVM'`、`'TVM'`）

当提供了 onConnect 时，主机会在发送到 iframe 的配置中自动设置 walletConfig.useExternalWalletManagement: true。你无需手动设置它。

入门

基本设置

高级

Widget Light (iframe)

其他

Widget Light 钱包管理

钱包桥接的工作原理

IframeEcosystemHandler 接口

生态系统处理器

EVM — `useEthereumIframeHandler()`

Solana — `useSolanaIframeHandler(params)`

Bitcoin — `useBitcoinIframeHandler()`

Sui — `useSuiIframeHandler()`

Tron — `useTronIframeHandler(params)`

子路径导入

组合多个处理器

外部钱包管理

​钱包桥接的工作原理

​IframeEcosystemHandler 接口

​生态系统处理器

​EVM — useEthereumIframeHandler()

​Solana — useSolanaIframeHandler(params)

​Bitcoin — useBitcoinIframeHandler()

​Sui — useSuiIframeHandler()

​Tron — useTronIframeHandler(params)

​子路径导入

​组合多个处理器

​外部钱包管理

钱包桥接的工作原理

IframeEcosystemHandler 接口

生态系统处理器

EVM — `useEthereumIframeHandler()`

Solana — `useSolanaIframeHandler(params)`

Bitcoin — `useBitcoinIframeHandler()`

Sui — `useSuiIframeHandler()`

Tron — `useTronIframeHandler(params)`

子路径导入

组合多个处理器

外部钱包管理