wagmi 中 estimateMaxPriorityFeePerGas 详解：在 @wagmi/core 中估算最大优先费（max priority fee per gas）-育师

wagmi 中 estimateMaxPriorityFeePerGas 详解：在 @wagmi/core 中估算最大优先费（max priority fee per gas）

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

本篇技术指南围绕 wagmi 提供的estimateMaxPriorityFeePerGasaction 展开：介绍如何在@wagmi/core中获取"下一区块内交易大概率被打包"所需的最大优先费估算值（以 wei 为单位），完整覆盖导入方式、调用示例、chainId参数、返回类型、错误类型与 TanStack Query 集成方式。读完本文后，你可以直接在自己的 wagmi 应用中读取 EIP-1559 优先费估算，并结合源码理解其底层调用链。

一、功能定位：EIP-1559 下的优先费估算

在 EIP-1559 的 gas 模型中，一笔交易的费用由两部分构成：

基础费（base fee）：由网络自动确定、随区块被销毁；
优先费（priority fee，即小费 tip）：用户为激励验证者优先打包交易而额外支付的部分。

estimateMaxPriorityFeePerGas返回的正是这笔优先费的上限估算值（单位 wei），表示"为了让交易在下一个区块中被包含进去，需要设置的最大优先费大概是多少"。它对应@wagmi/core中一个独立的异步 action，是构建交易参数（尤其是与estimateFeesPerGas配合使用时）的重要基础。

从源码看，该 action 位于 packages/core/src/actions/estimateMaxPriorityFeePerGas.ts，是对 viem 同名 action 的 wagmi 封装：

export async function estimateMaxPriorityFeePerGas< config extends Config, chainId extends config['chains'][number]['id'] = config['chains'][number]['id'], >( config: config, parameters: EstimateMaxPriorityFeePerGasParameters<config, chainId> = {}, ): Promise<EstimateMaxPriorityFeePerGasReturnType> { const { chainId } = parameters const client = config.getClient({ chainId }) const action = getAction( client, viem_estimateMaxPriorityFeePerGas, 'estimateMaxPriorityFeePerGas', ) return action({ chain: client.chain }) }

它通过config.getClient({ chainId })按链解析客户端，再借助getAction工具把 viem 的estimateMaxPriorityFeePerGas挂到对应 client 上执行，最后以client.chain作为链上下文完成调用。

二、导入与基础用法

1. 导入

在@wagmi/core中导入该 action 及其配套类型：

import { estimateMaxPriorityFeePerGas } from '@wagmi/core' import { type EstimateMaxPriorityFeePerGasParameters, type EstimateMaxPriorityFeePerGasReturnType, type EstimateMaxPriorityFeePerGasErrorType, } from '@wagmi/core'

2. 基础调用

最低限度只需要传入通过createConfig创建的config对象：

import { estimateMaxPriorityFeePerGas } from '@wagmi/core' import { config } from './config' const result = await estimateMaxPriorityFeePerGas(config)

返回的result是一个bigint，即下一区块所需最大优先费的估算值（wei）。示例中的config使用createConfig创建，配置了mainnet与sepolia两条链，完整写法参见 site/snippets/core/config.ts：

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(), }, })

仓库测试 packages/core/src/actions/estimateMaxPriorityFeePerGas.test.ts 中即用该配置验证了"默认调用可正常解析出值"：

test('default', async () => { await expect(estimateMaxPriorityFeePerGas(config)).resolves.toBeDefined() })

三、参数详解：chainId

EstimateMaxPriorityFeePerGasParameters在 viem 参数基础上通过UnionLooseOmit去掉了chain字段，并注入了 wagmi 的ChainIdParameter，其核心参数为：

参数	类型	说明
`chainId`	`config['chains'][number]['id'] \\| undefined`	获取数据时使用的链 ID

chainId用于显式指定在哪条链上执行估算；不传时使用config的默认链。显式指定示例（配合@wagmi/core/chains中导出的链定义）：

import { estimateMaxPriorityFeePerGas } from '@wagmi/core' import { mainnet } from '@wagmi/core/chains' import { config } from './config' const result = await estimateMaxPriorityFeePerGas(config, { chainId: mainnet.id, })

测试中同样覆盖了指定chainId的路径：

test('parameters: chainId', async () => { await expect( estimateMaxPriorityFeePerGas(config, { chainId: chain.mainnet2.id, }), ).resolves.toBeDefined() })

调用链说明：从源码可见chainId只用于config.getClient({ chainId })选择客户端；真正的估算请求由 viem 的estimateMaxPriorityFeePerGas在client.chain上发出。也就是说 wagmi 层只负责"解析客户端 + 路由参数"，底层协议估算逻辑全部交给 viem，因此两种调用方式最终都返回同一语义的结果：Promise<bigint>（单位 wei）。

四、返回类型

EstimateMaxPriorityFeePerGasReturnType直接复用了 viem 的返回类型：

export type EstimateMaxPriorityFeePerGasReturnType = viem_EstimateMaxPriorityFeePerGasReturnType

其值为：

bigint

即"下一区块中交易被包含所需最大优先费"的估算值（wei）。实际使用时通常需要配合formatGwei/formatWei之类的格式化工具转成可读单位，再填入交易参数（如maxPriorityFeePerGas）。

五、错误类型与 TanStack Query 集成

1. 错误类型

EstimateMaxPriorityFeePerGasErrorType同样是 viem 错误类型的别名：

export type EstimateMaxPriorityFeePerGasErrorType = viem_EstimateMaxPriorityFeePerGasErrorType

在@wagmi/core中它涵盖底层 RPC 调用可能抛出的错误（如链未配置、RPC 请求失败等），便于在try/catch或 TanStack Query 的错误通道中做类型化处理。

2. TanStack Query（@wagmi/core/query）

wagmi 为每个 action 都提供了 Query 集成层。从 packages/core/src/query/estimateMaxPriorityFeePerGas.ts 可以看到它暴露了如下工具：

import { type EstimateMaxPriorityFeePerGasData, type EstimateMaxPriorityFeePerGasOptions, type EstimateMaxPriorityFeePerGasQueryFnData, type EstimateMaxPriorityFeePerGasQueryKey, estimateMaxPriorityFeePerGasQueryKey, estimateMaxPriorityFeePerGasQueryOptions, } from '@wagmi/core/query'

其核心是estimateMaxPriorityFeePerGasQueryOptions：它把参数收敛进 queryKey（['estimateMaxPriorityFeePerGas', options]），并用queryFn内部调用 action：

return { ...options.query, queryFn: async (context) => { const [, { scopeKey: _, ...parameters }] = context.queryKey return estimateMaxPriorityFeePerGas(config, parameters) }, queryKey: estimateMaxPriorityFeePerGasQueryKey(options), }

测试 packages/core/src/query/estimateMaxPriorityFeePerGas.test.ts 确认了 queryKey 的形态：

// 默认：queryKey 为 ['estimateMaxPriorityFeePerGas', {}] // 指定 chainId: 1 时：queryKey 为 ['estimateMaxPriorityFeePerGas', { chainId: 1 }]

3. React Hook：useEstimateMaxPriorityFeePerGas

在 React 框架适配层（@wagmi/react）中，useEstimateMaxPriorityFeePerGas封装了上述 Query 层，未显式传chainId时会自动回退到当前激活链useChainId()：

const chainId = useChainId({ config }) const options = estimateMaxPriorityFeePerGasQueryOptions(config, { ...parameters, chainId: parameters.chainId ?? chainId, }) return useQuery(options)

这意味着在组件中你可以这样读取优先费估算：

import { useEstimateMaxPriorityFeePerGas } from 'wagmi' const { data, isPending, error } = useEstimateMaxPriorityFeePerGas() // data: bigint | undefined —— 最大优先费估算值（wei）

六、适用前提与限制说明

适用链：仅适用于支持 EIP-1559（或类似优先费机制）的网络；在非 EIP-1559 网络上该估算语义可能不适用，请以实际 RPC 返回为准。
依赖 viem：本 action 是 viem 同名 action 的薄封装，实际 RPC 逻辑由 viem 完成；具体底层实现细节可参考 viem 的estimateMaxPriorityFeePerGas文档。
返回单位：返回值始终为 wei（bigint），展示给用户前需自行格式化。
实测参考：仓库测试对默认调用与chainId显式指定两条路径均有覆盖（见 estimateMaxPriorityFeePerGas.test.ts 与 estimateMaxPriorityFeePerGas.test.ts），可作为集成验证依据。

七、总结

estimateMaxPriorityFeePerGas是 wagmi 中获取 EIP-1559 最大优先费估算的核心 action：

使用：await estimateMaxPriorityFeePerGas(config, { chainId? })；
参数：chainId可选，决定在哪个链上估算；
返回：bigint（wei）类型的安全估算值；
错误处理：EstimateMaxPriorityFeePerGasErrorType类型化错误；
生态集成：@wagmi/core/query提供 Query 工具，React 侧对应useEstimateMaxPriorityFeePerGasHook。