wagmi 中Actions.wallet.deposit实战指南带预填充字段的 Tempo 钱包充值流程【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmiwallet.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.transferTIP-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 } | undefinedreceipts可选充值流程中执行的所有链上操作对应的交易收据数组。之所以是数组是因为一次充值可能涉及多个链上步骤也可能没有任何链上操作例如仅打开 UI 用户取消此时receipts为undefined整体返回可能为undefined当流程未产生可确认结果如用户中途取消、未发生链上操作时返回undefined因此示例代码中使用可选链result?.receipts。这一点与wallet.swap不同——swap总是返回单一receipt见 wallet.swap 文档而deposit需要处理“零个或多个收据”的情况。参数详解所有参数均为可选。省略的字段会留给用户在钱包 UI 中自行填写。官方文档共列出 7 个参数参数类型必填说明addressAddress否预填充的充值目标地址chainIdnumber否预填充的源链 IDdisplayNamestring否人类可读的账户显示名称tokenAddress否预填充的代币合约地址省略则让用户选择valuestring否预填充的人类可读金额如1.5accountAccount \| Address \| null否连接器客户端使用的账户传null让钱包自行推断默认使用当前已连接的 Wagmi 账户connectorConnector否使用的连接器默认使用当前激活的连接器逐项深入说明address可选Type:Address预填充充值目标地址。省略时钱包 UI 中该字段留空由用户输入。chainId可选Type:number预填充的源链 ID文档明确其为“Source chain ID”。需要说明的是文档标注的类型为number而在源码层该参数会与ChainIdParameterconfig合并后透传给 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 depositconfig extends Config( config: config, parameters: deposit.Parametersconfig {}, ): Promisedeposit.ReturnValue { const { account, chainId, connector, ...rest } parameters const client await getConnectorClient(config, { account, assertChainId: false, chainId, connector, }) return Actions.wallet.deposit(client, { ...rest, chainId }) }关键调用链拆解参数解构先把 wagmi 层特有的account、chainId、connector从参数中取出剩余字段如address、token、value、displayName作为rest原样透传获取连接器客户端调用getConnectorClient(config, { account, assertChainId: false, chainId, connector })。assertChainId: false表明此处不强校验目标链与当前链一致允许为充值动作指定独立于当前链的源链委托给 viem拿到客户端后直接调用viem/tempo的Actions.wallet.deposit(client, { ...rest, chainId })最终由钱包连接器负责打开 UI、收集签名并提交链上交易。这也解释了为什么“签名与提交由已连接钱包处理”。类型定义与导出路径参数类型为UnionComputeChainIdParameterconfig ConnectorParameter AccountParameter OmitActions.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提供了两组测试可直接印证本文所述行为default预填充参数传入address、chainId: tempoLocal.id、displayName、token断言返回{ receipts: [TransactionReceipt] }其中收据包含blockNumber: 1n、status: success、type: tempo等字段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、源chainIdwallet.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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考