wagmi 核心 Action 详解prepareTransactionRequest 交易请求预处理器【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmiprepareTransactionRequest是wagmi/core提供的核心 Action用于在交易签名前自动补齐一笔交易请求所需的全部必要字段——包括 nonce交易序号、gas limitGas 上限、手续费参数gasPrice/maxFeePerGas/maxPriorityFeePerGas以及交易类型如eip1559。本指南将围绕该 Action 的完整参数体系、返回类型、错误处理并结合仓库源码与测试用例讲解其在 wagmi 应用中为转账、合约调用、批量调用calls等场景准备交易请求的实战方法读完即可在自己的项目中安全、准确地使用该能力。一、Action 概述为什么要“预处理”交易请求在以太坊上发起一笔交易转账或合约调用时除了to、value、data等业务字段外交易还依赖链上状态才能被矿工接受例如nonce从链上读取的账户交易计数防止交易重放gas limit交易执行所需的 Gas 上限手续费Legacy 交易的gasPrice或 EIP-1559 交易的maxFeePerGas/maxPriorityFeePerGas交易类型根据链与账户状态自动选择如eip1559、legacy。prepareTransactionRequest正是负责“补齐”这些链上依赖字段的 Action。它本质上是对 viem 同名 Action 的 wagmi 封装但额外集成了 wagmi 的Config、链选择与连接器Connector体系并返回带chainId的交易请求。在发送交易sendTransaction之前先经过它是构建健壮 dApp 的常见做法。二、安装与导入该 Action 由wagmi/core包导出无需额外安装依赖import { prepareTransactionRequest } from wagmi/core同时可导入配套的类型定义import { type PrepareTransactionRequestParameters, type PrepareTransactionRequestReturnType, type PrepareTransactionRequestErrorType, } from wagmi/core其导出位置见 actions 导出文件类型定义与实现均位于 prepareTransactionRequest 源码。三、基本用法在调用前需要先通过createConfig创建 wagmi 配置chains与transports是必填项示例配置如下摘自 配置片段import { createConfig, http } from wagmi/core import { mainnet, sepolia } from wagmi/core/chains export const config createConfig({ chains: [mainnet, sepolia], transports: { [mainnet.id]: http(), [sepolia.id]: http(), }, })之后即可准备一笔向指定地址转账 1 ETH 的交易请求import { prepareTransactionRequest } from wagmi/core import { parseEther } from viem import { config } from ./config await prepareTransactionRequest(config, { to: 0x70997970c51812dc3a010c7d01b50e0d17dc79c8, value: parseEther(1), })函数签名见 源码为prepareTransactionRequestconfig, chainId, request( config: config, parameters: PrepareTransactionRequestParametersconfig, chainId, request, ): PromisePrepareTransactionRequestReturnTypeconfig, chainId, request其中config为第一步创建的 wagmi 配置parameters是交易请求参数下面逐一展开。四、参数详解PrepareTransactionRequestParameters所有参数均为可选由 TypeScript 类型系统按场景约束导入类型import { type PrepareTransactionRequestParameters } from wagmi/core从源码看该参数类型通过UnionStrictOmit移除了 viem 的chain字段并混入ChainIdParameter链 ID与ConnectorParameter连接器最终以按链展开的联合类型[key in keyof chains]形式提供精确的类型推导。4.1 account类型Account | Address | undefined作用发送交易的账户Account 对象或地址字符串。不传时使用当前已连接账户。await prepareTransactionRequest(config, { account: 0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266, to: 0x70997970c51812dc3a010c7d01b50e0d17dc79c8, value: parseEther(1), })源码行为提示从 实现 可见当account是type local的本地账户对象时直接通过config.getClient({ chainId })取客户端否则通过getConnectorClient获取连接器客户端并传入account可能为undefined此时使用连接器当前账户。4.2 to类型0x${string} | undefined作用交易接收方或合约地址。await prepareTransactionRequest(config, { account: 0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266, to: 0x70997970c51812dc3a010c7d01b50e0d17dc79c8, value: parseEther(1), })注意如果使用calls批量调用而非to则to可省略见 类型定义 中calls与to的互斥联合。4.3 accessList类型AccessList | undefined作用访问列表Access List用于预先声明交易将访问的合约地址与存储槽可优化 Gas 费用。await prepareTransactionRequest(config, { accessList: [ { address: 0x1, storageKeys: [0x1], }, ], account: 0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266, to: 0x70997970c51812dc3a010c7d01b50e0d17dc79c8, value: parseEther(1), })4.4 chainId类型config[chains][number][id] | undefined作用为指定链准备交易请求。不传时使用当前活动链。import { mainnet } from wagmi/core/chains await prepareTransactionRequest(config, { chainId: mainnet.id, account: 0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266, to: 0x70997970c51812dc3a010c7d01b50e0d17dc79c8, value: parseEther(1), })类型推导亮点由于chainId被限定为config[chains][number][id]wagmi/core会根据config中配置的链集合如mainnet、sepolia做字面量类型推导传入未配置的链 ID 会在编译期报错。4.5 data类型0x${string} | undefined作用合约哈希方法调用method call与编码后的参数即合约 calldata。可用于构造合约交互交易。await prepareTransactionRequest(config, { data: 0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2, account: 0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266, to: 0x70997970c51812dc3a010c7d01b50e0d17dc79c8, value: parseEther(1), })4.6 gasPrice类型bigint | undefined作用每单位 Gas 支付的价格以 wei 为单位。仅适用于 Legacy 交易即非 EIP-1559 链或 EIP-1559 不可用时的回退场景。import { parseEther, parseGwei } from viem await prepareTransactionRequest(config, { account: 0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266, gasPrice: parseGwei(20), to: 0x70997970c51812dc3a010c7d01b50e0d17dc79c8, value: parseEther(1), })parseGwei(20)返回20000000000n即以 20 Gwei 作为 Gas 单价。4.7 maxFeePerGas类型bigint | undefined作用每单位 Gas 的总费用上限以 wei 为单位已包含maxPriorityFeePerGas。仅适用于 EIP-1559 交易。await prepareTransactionRequest(config, { account: 0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266, maxFeePerGas: parseGwei(20), to: 0x70997970c51812dc3a010c7d01b50e0d17dc79c8, value: parseEther(1), })4.8 maxPriorityFeePerGas类型bigint | undefined作用每单位 Gas 的矿工优先小费上限以 wei 为单位。仅适用于 EIP-1559 交易。通常与maxFeePerGas搭配使用且应满足maxFeePerGas maxPriorityFeePerGas。await prepareTransactionRequest(config, { account: 0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266, maxFeePerGas: parseGwei(20), maxPriorityFeePerGas: parseGwei(2), to: 0x70997970c51812dc3a010c7d01b50e0d17dc79c8, value: parseEther(1), })4.9 nonce类型number | undefined作用标识该交易的唯一序号。通常由链上账户交易计数自动填充手动指定可用于覆盖replacepending 交易等高级场景。await prepareTransactionRequest(config, { account: 0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266, to: 0x70997970c51812dc3a010c7d01b50e0d17dc79c8, value: parseEther(1), nonce: 5, })4.10 parameters类型(fees | gas | nonce | type)[] | undefined作用指定需要预处理的参数子集。例如传入[gas, nonce]时仅补齐gas与nonce其余字段如type、手续费保持用户传入的值不变。await prepareTransactionRequest(config, { account: 0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266, parameters: [gas, nonce], to: 0x70997970c51812dc3a010c7d01b50e0d17dc79c8, value: parseEther(1), })该参数在精细化控制“哪些字段由链上补齐、哪些字段保持自定义”时非常有用例如在需要严格自定义手续费但希望自动填充 nonce 与 gas 上限的场景。4.11 value类型bigint | undefined作用交易转账金额以 wei 为单位。文档中原文描述为“the transaction recipient or contract address”结合源码与常规语义其实际含义为转账金额可用parseEther等工具转换await prepareTransactionRequest(config, { account: 0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266, to: 0x70997970c51812dc3a010c7d01b50e0d17dc79c8, value: parseEther(1), })4.12 calls批量调用除上述参数外从 源码类型定义 可以看到PrepareTransactionRequestParameters还支持calls: Callsreadonly unknown[]形式的批量调用参数此时to变为可选。这使该 Action 同样可以服务于 EIP-7702 / 批量调用等场景适合构造复杂的多操作交易请求。五、返回类型PrepareTransactionRequestReturnTypeimport { type PrepareTransactionRequestReturnType } from wagmi/core返回值为一个完整的TransactionRequest交易请求对象包含补齐后的字段例如account、from、to、value、nonce、gas、gasPrice/maxFeePerGas/maxPriorityFeePerGas、type等。从 类型定义 看返回值在 viem 的PrepareTransactionRequestReturnType基础上额外固定携带chainId字段 { chainId: chains[key][id] }并按链展开为联合类型便于下游sendTransaction等 Action 直接消费。参考仓库测试 prepareTransactionRequest.test.ts一次默认调用的返回快照大致为{ account: { address: 0x95132632579b073D12a6673e18Ab05777a6B86f8, type: json-rpc }, chainId: 1, from: 0x95132632579b073D12a6673e18Ab05777a6B86f8, to: 0x70997970c51812dc3a010c7d01b50e0d17dc79c8, type: eip1559, value: 1000000000000000000n, // 以及被测试解构忽略的 gas / gasPrice / maxFeePerGas / maxPriorityFeePerGas / nonce 等字段 }可以看到在连接器json-rpc 账户场景下返回的交易类型被自动确定为eip1559chainId为1mainnetvalue为1 ETH对应的1000000000000000000n。六、错误处理PrepareTransactionRequestErrorTypeimport { type PrepareTransactionRequestErrorType } from wagmi/core该类型直接复用 viem 的PrepareTransactionRequestErrorType见 源码覆盖如账户不存在、链未配置、RPC 请求失败、Gas 估算失败等异常场景。实践中建议配合 try/catch 或错误边界处理并可结合 wagmi 的错误体系errors 文档统一展示。七、与 TanStack Query 集成/query 子路径wagmi/core为便于缓存与响应式刷新还导出了 TanStack Query 相关的工具函数导入方式import { type PrepareTransactionRequestData, type PrepareTransactionRequestOptions, type PrepareTransactionRequestQueryFnData, type PrepareTransactionRequestQueryKey, prepareTransactionRequestQueryKey, prepareTransactionRequestQueryOptions, } from wagmi/core/query实现在 query/prepareTransactionRequest.tsprepareTransactionRequestQueryOptions(config, options)构造 query 配置。其enabled逻辑要求to或非空calls存在时才启用查询L52-L57queryFn内部在缺少to且无calls时抛出to or calls is required错误。prepareTransactionRequestQueryKey(options)生成查询键[prepareTransactionRequest, { ...过滤后的参数 }]参数变化会自动触发重新查询。配套类型PrepareTransactionRequestData、PrepareTransactionRequestOptions等用于类型安全的 query 使用。八、React 框架下的 Hook 封装在wagmi/react中该能力被封装为usePrepareTransactionRequestHook实现见 usePrepareTransactionRequest.tsimport { usePrepareTransactionRequest } from wagmi const result usePrepareTransactionRequest({ to: 0x70997970c51812dc3a010c7d01b50e0d17dc79c8, value: parseEther(1), })Hook 内部通过useConfig获取配置、useChainId获取当前链并在未显式传入chainId时自动回退到当前链L71-L77。其返回值是基于 TanStack Query 的UseQueryReturnType因此天然具备 loading、error、data 等状态管理能力。九、底层调用链与实现原理从 核心实现 可以梳理出完整的调用链账户分支判断若account为type local的本地账户如privateKeyToAccount创建的账户直接通过config.getClient({ chainId })获取客户端跳过连接器否则进入连接器路径。获取连接器客户端通过getConnectorClient(config, { account, assertChainId: false, chainId, connector })获取与连接器绑定的 viem 客户端。assertChainId: false意味着允许在目标链与当前连接链不一致时继续处理。Action 分发使用getAction工具将 viem 的prepareTransactionRequest绑定到客户端上调用避免重复实例化。参数透传将account若提供与原参数一并透传给 viem 实现由 viem 负责 RPC 读取nonce、gas、手续费建议值并组装最终请求。测试用例prepareTransactionRequest.test.ts覆盖了三种典型场景可作为行为依据默认场景连接器 json-rpc 账户tovalue返回补齐后的请求显式 account 场景传入地址字符串时返回的account为地址、from为该地址本地账户场景privateKeyToAccount(privateKey)构造的本地账户account返回完整的本地账户对象含publicKey、sign等验证了“本地账户不走连接器”的分支逻辑。十、典型使用流程总结在实际 dApp 中建议按以下流程使用通过createConfig配置好chains与transports见配置片段用户连接钱包后调用prepareTransactionRequest(config, { to, value, ... })或usePrepareTransactionRequest获取补齐字段的交易请求将返回值交给sendTransaction等发送类 Action 完成签名与广播如需精细控制使用parameters限定补齐的字段子集如需为特定链准备请求显式传入chainId。该 Action 的完整行为还可参考 TanStack Query 集成文档 与 发送交易指南 等仓库内文档结合使用可获得更完整的交易构建体验。【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考