企业官网建设流程全解析

wagmi 中Actions.wallet.deposit实战指南：带预填充字段的 Tempo 钱包充值流程

【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmi

wallet.deposit是 wagmi Tempo 系列动作中负责“打开钱包充值（Deposit）流程”的核心 API。它把签名、提交等繁琐步骤全部交给已连接的钱包处理，并允许你通过一组全可选参数预填充充值表单（如充值地址、源链、代币与金额），用户只需在钱包 UI 中确认即可完成充值。读完本文，你将掌握该动作的完整调用方式、返回结构、每个参数的语义，以及它在 wagmi 源码 中的底层实现与测试验证。

wallet.deposit是什么

在 Tempo 生态中，充值（deposit）通常涉及跨链 / 托管场景下的资金转入操作。wagmi 提供的Actions.wallet.deposit动作封装了从已连接钱包发起充值的一整套流程：

• 打开钱包充值界面：调用后由钱包侧展示充值表单，所有未提供的字段会留给用户手动填写；
• 签名与提交由钱包负责：动作本身不直接构造裸交易，而是把rest参数透传给底层viem/tempo的实现；
• 返回链上操作收据：若充值流程中发生了链上操作，会以TransactionReceipt[]的形式返回，方便前端展示交易哈希、区块号等确认信息。

从仓库的 Tempo 动作索引 看，wallet.deposit属于Wallet Actions分组，与wallet.swap（钱包兑换流程）、wallet.transfer（TIP-20 代币转账）并列，三者共同构成“钱包主导的资产操作”入口。

快速上手：完整调用示例

wallet.deposit从wagmi/tempo命名空间导入，属于Actions对象上的方法。参考官方文档示例：

import { Actions } from 'wagmi/tempo' import { config } from './config' const result = await Actions.wallet.deposit(config, { address: '0x20c0000000000000000000000000000000000001', chainId: 1, displayName: 'My Account', token: '0x20c0000000000000000000000000000000000002', value: '1.5', }) console.log('Receipts:', result?.receipts) // @log: Receipts: [...]

其中的config即 wagmi 的createConfig返回值。针对 Tempo 场景，仓库在 config-tempo.ts 配置片段 中给出了完整可用的最小配置：

import { createConfig, http } from 'wagmi' import { tempo } from 'wagmi/chains' import { tempoWallet } from 'wagmi/tempo' export const config = createConfig({ connectors: [tempoWallet()], chains: [tempo], multiInjectedProviderDiscovery: false, transports: { [tempo.id]: http(), }, })

要点说明：

• connectors：注册tempoWallet()，它是 wagmi 针对 Tempo 钱包对话框封装的连接器（定义见 Connectors.ts），充值流程正是经由该连接器获取的客户端执行；
• chains / transports：配置tempo链及对应的http()传输层，保证动作能解析目标链并发出 RPC 请求；
• multiInjectedProviderDiscovery：显式关闭多注入提供方发现，避免浏览器其他钱包扩展干扰 Tempo 钱包连接。

返回类型解读

wallet.deposit的返回类型（取自文档，与 源码 中deposit.ReturnValue一致）为：

type ReturnType = | { /** Receipts of any onchain operations performed during the deposit. */ receipts?: readonly TransactionReceipt[] | undefined } | undefined

• receipts（可选）：充值流程中执行的所有链上操作对应的交易收据数组。之所以是数组，是因为一次充值可能涉及多个链上步骤；也可能没有任何链上操作（例如仅打开 UI 用户取消），此时receipts为undefined；
• 整体返回可能为undefined：当流程未产生可确认结果（如用户中途取消、未发生链上操作）时返回undefined，因此示例代码中使用可选链result?.receipts。

这一点与wallet.swap不同——swap总是返回单一receipt（见 wallet.swap 文档），而deposit需要处理“零个或多个收据”的情况。

参数详解

所有参数均为可选。省略的字段会留给用户在钱包 UI 中自行填写。官方文档共列出 7 个参数：

逐项深入说明：

address（可选）

• Type:Address
• 预填充充值目标地址。省略时钱包 UI 中该字段留空，由用户输入。

chainId（可选）

• Type:number
• 预填充的源链 ID（文档明确其为“Source chain ID”）。需要说明的是：文档标注的类型为number，而在源码层该参数会与ChainIdParameter<config>合并后透传给 viem 的wallet.deposit（见下文源码分析），因此实际取值应落在你createConfig配置的链 ID 集合内。

displayName（可选）

• Type:string
• 人类可读的账户显示名称，例如'My Account'。主要用于钱包 UI 中展示充值目标账户的备注名。

token（可选）

• Type:Address
• 预填充的代币合约地址。若省略，用户可在钱包 UI 中自行选择充值的代币种类。

value（可选）

• Type:string
• 预填充的人类可读金额，注意是字符串而非 BigInt，例如'1.5'。这与wallet.swap的amount参数风格一致，均由钱包负责按代币精度做内部换算。

account（可选）

• Type:Account | Address | null
• 指定用于连接器客户端的账户。传null表示让钱包自行推断账户；默认使用当前已连接的 Wagmi 账户。该参数在源码中定义于 wallet.ts 顶部的AccountParameter类型。

connector（可选）

• Type:Connector
• 指定使用的连接器，默认使用当前激活的连接器。当应用同时注册了多个连接器、需要强制走 Tempo 钱包时显式传入。

源码实现：从调用到链上确认的调用链

要理解wallet.deposit的本质，可以直接阅读其实现 packages/core/src/tempo/actions/wallet.ts。核心代码可简化为：

export async function deposit<config extends Config>( config: config, parameters: deposit.Parameters<config> = {}, ): Promise<deposit.ReturnValue> { const { account, chainId, connector, ...rest } = parameters const client = await getConnectorClient(config, { account, assertChainId: false, chainId, connector, }) return Actions.wallet.deposit(client, { ...rest, chainId }) }

关键调用链拆解：

1. 参数解构：先把 wagmi 层特有的account、chainId、connector从参数中取出，剩余字段（如address、token、value、displayName）作为rest原样透传；
2. 获取连接器客户端：调用getConnectorClient(config, { account, assertChainId: false, chainId, connector })。assertChainId: false表明此处不强校验目标链与当前链一致，允许为充值动作指定独立于当前链的源链；
3. 委托给 viem：拿到客户端后，直接调用viem/tempo的Actions.wallet.deposit(client, { ...rest, chainId })，最终由钱包连接器负责打开 UI、收集签名并提交链上交易。这也解释了为什么“签名与提交由已连接钱包处理”。

类型定义与导出路径

• 参数类型为UnionCompute<ChainIdParameter<config> & ConnectorParameter & AccountParameter & Omit<Actions.wallet.deposit.Parameters, 'chainId'>>：它把 wagmi 层的链/连接器/账户参数与 viem 层其余参数合并，并显式Omit掉 viem 自带的chainId，避免类型冲突；
• 错误类型为GetConnectorClientErrorType | BaseErrorType | Actions.wallet.deposit.ErrorType，即连接器客户端获取失败、通用错误与底层 viem 错误的并集；
• 导出链路为：wagmi/tempo入口 exports/tempo.ts 中的export * as Actions from '../tempo/actions/index.js'→ tempo/actions/index.ts 中的export * as wallet from './wallet.js'，最终暴露Actions.wallet.deposit。

测试用例验证

仓库在 wallet.test.ts 中为deposit提供了两组测试，可直接印证本文所述行为：

1. default（预填充参数）：传入address、chainId: tempoLocal.id、displayName、token，断言返回{ receipts: [TransactionReceipt] }，其中收据包含blockNumber: 1n、status: 'success'、type: 'tempo'等字段；
2. default: no parameters：直接调用wallet.deposit(config)（不传任何参数），断言result?.receipts有定义，验证“全参数可选、空调用不抛错”的契约。

测试中还使用了config.connectors[2]!作为固定连接器，并在beforeEach中先disconnect再connect，说明该动作依赖已建立连接的会话状态——这正对应文档中account参数“默认使用已连接的 Wagmi 账户”的语义。

与wallet.swap、wallet.transfer的差异

同属 Wallet Actions 分组，三者形态相近但返回值与定位不同，便于对照使用：

• wallet.deposit：打开充值流程，返回收据数组（可能为undefined），参数聚焦充值目标（address、token、value、displayName、源chainId）；
• wallet.swap：打开兑换流程，返回单一收据，参数聚焦交易对（token、pairToken、amount、slippage、type），见 wallet.swap 文档；
• wallet.transfer：默认以只读方式直接提交 TIP-20 代币转账（不展示可编辑 UI），只有传入editable: true才会打开钱包发送界面，见 源码注释 中的示例。

实践建议与注意事项

• 预填充尽量克制：所有字段都是可选的，核心设计意图是“只预填你有把握的值”。例如你有确定的收款地址和金额就填address/value，否则留空让用户在钱包 UI 中选择，体验更自然；
• 妥善处理undefined返回：由于结果可能为undefined，消费方务必使用可选链或判空，避免在未发生链上操作时访问receipts抛错；
• 确认链配置：chainId语义为源链 ID，确保其包含在createConfig的chains中，否则连接器客户端可能因链未配置而失败（可参考 ChainNotConfiguredError 相关逻辑）；
• 使用 Tempo 钱包连接器：该流程面向钱包主导的交互，配合tempoWallet()连接器（Connectors.ts）使用可保证 UI 与签名链路一致。

延伸阅读

• Tempo 动作总览（含 Wallet Actions 分组）
• wallet.swap 文档
• wallet.transfer 源码与示例
• Tempo 配置示例
• wagmi Tempo 入口导出
• Tempo 连接器实现

【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmi