Tempo 与 Wagmi 集成实战：在 React/Core 中接入 Tempo L1 支付链
【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmi
Tempo 是一条为支付场景量身定制的 Layer 1 区块链，将代币管理（TIP20）、Fee AMM、稳定币 DEX 与全新的 Tempo 交易类型直接内置到协议层。本文以仓库文档 site/tempo/getting-started.md 为主线，讲解如何通过 Wagmi（React 与 Core 两套 API）完成 Tempo 的安装、链配置、钱包连接，并使用批量交易、费用赞助、并发交易等 Tempo 专属能力；读完本文，你将掌握从零接入 Tempo 并读写 TIP20 代币的完整方案。
Overview：Tempo 是什么
Tempo 是一条专注于支付场景的 Layer 1 区块链（官方介绍），其核心特性并非通过智能合约堆叠实现，而是直接“内置于协议”（enshrined）：
- 代币管理：Tempo 原生支持 TIP20 代币标准，代币的创建、铸造、转账、角色权限等均在协议层完成；
- Fee AMM：费用代币的定价与交换由协议内置的 AMM 机制驱动，而非第三方合约；
- 稳定币 DEX：协议内置的去中心化交易所，用于稳定币的发行与兑换；
- Tempo 交易类型：一种特殊的交易格式，支持批量调用（batch calls）、费用赞助（fee sponsorship）、可配置费用代币（configurable fee tokens）、并发交易（concurrent transactions）、访问密钥（access keys）与定时执行（scheduled execution）。
在 Wagmi 生态中，React 与 Core 对 Tempo 均提供了一等公民（first-class）支持：通过 Tempo Hooks 与 Tempo Actions 两组入口，开发者可以像使用普通 Wagmi API 一样调用 Tempo 协议能力。仓库源码中，Tempo 相关实现集中于 packages/core/src/tempo/（Core Actions 与连接器）和 packages/react/src/tempo/（React Hooks）。
Setup：环境要求与安装
接入 Tempo 之前，请先按 React 快速上手 或 Core 快速上手 完成 Wagmi 基础初始化，并确保项目中 Viem 版本满足要求。
版本要求
根据 packages/connectors/package.json 中的peerDependencies声明（第 37–47 行），需要额外安装两个依赖：
| 依赖 | 版本要求 | 作用 |
|---|---|---|
viem | >=2.55.2 | Tempo 链底层 RPC 客户端，Tempo Actions 均是对 Viem Tempo Actions 的封装 |
accounts | ~0.14 | Tempo 钱包账户 SDK，驱动tempoWallet、webAuthn、dangerous_secp256k1三个连接器 |
安装命令
在项目根目录执行以下任一命令：
pnpm add viem@>=2.55.2 accounts@~0.14npm install viem@>=2.55.2 accounts@~0.14yarn add viem@>=2.55.2 accounts@~0.14bun add viem@>=2.55.2 accounts@~0.14安装完成后，可通过 Viem 的 Tempo 文档深入了解协议层实现细节。
配置 Config：接入 Tempo 链与钱包
无论使用 React 还是 Core，都需要先通过createConfig构建 Wagmi 配置。核心配置包含三个要点：
- 链：从
wagmi/chains导入tempo链； - 连接器：使用
tempoWallet()作为钱包连接器； - 关闭多注入发现：由于
tempoWallet属于 injected 类型连接器，需要通过multiInjectedProviderDiscovery: false禁用 EIP-6963 多注入提供者发现，避免与浏览器中其他钱包扩展冲突。
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(), }, })若使用 Core（无 React 环境），请将导入路径替换为@wagmi/core、@wagmi/core/chains与@wagmi/core/tempo：
import { createConfig, http } from '@wagmi/core' import { tempo } from '@wagmi/core/chains' import { tempoWallet } from '@wagmi/core/tempo' export const config = createConfig({ connectors: [tempoWallet()], chains: [tempo], multiInjectedProviderDiscovery: false, transports: { [tempo.id]: http(), }, })tempoWallet 连接器参数
查看 packages/core/src/tempo/Connectors.ts 第 62–91 行，tempoWallet()底层调用accountsSDK 的dialog适配器，可配置以下参数：
| 参数 | 类型 | 说明 |
|---|---|---|
dialog | 对象 | 透传给accounts.dialog的对话框配置 |
host | 字符串 | 钱包服务 host 地址 |
icon | 字符串 | 连接器图标（data URL 或远程 URL），默认内置 Tempo 图标，用于 EIP-6963 公告 |
name | 字符串 | 连接器显示名称，默认Tempo Wallet |
rdns | 字符串 | EIP-6963 reverse-DNS 标识，默认xyz.tempo，同时作为连接器id |
theme | 对象 | 对话框主题 |
tempoWallet的连接器type为'injected'，id默认为xyz.tempo。在连接流程中（第 221–287 行），它会通过wallet_connectRPC 方法请求账户，并在重连（isReconnecting）时复用eth_accounts中已授权的账户。
使用 Wagmi Hooks：批量交易、费用赞助与并发交易
Tempo 的最大价值在于：普通 Wagmi Hooks 即可直接使用 Tempo 交易类型。以useSendTransactionSync为例，该 Hook 基于@tanstack/react-query的useMutation封装（见 packages/react/src/hooks/useSendTransactionSync.ts），在常规sendTransaction基础上增加了 Tempo 专属属性：
calls：批量交易数组，一次签名提交多笔调用；feePayer：费用赞助地址，交易 gas 由第三方代付；nonceKey：并发交易标识，允许同一账户并发发起多笔互不阻塞的交易。
除此之外还有可配置费用代币、访问密钥、定时执行等属性。下面的组件一次性向三个地址批量发送调用，同时由赞助地址代付费用、并用nonceKey: 1337n标记并发交易：
import { useSendTransactionSync } from 'wagmi' export function TokenMetadata() { const sendTransactionSync = useSendTransactionSync() return ( <button onClick={() => sendTransactionSync.mutate({ calls: [ { data: '0xcafebabe00000000000000000000000000000001', to: '0xdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef' }, { data: '0xdeadbeef00000000000000000000000000000002', to: '0xfeedfacefeedfacefeedfacefeedfacefeedface' }, { data: '0xfeedface00000000000000000000000000000003', to: '0xfeedfacefeedfacefeedfacefeedfacefeedface' }, ], feePayer: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045', nonceKey: 1337n, }) } > Send transaction </button> ) }注意*Sync后缀的语义：同步变体（Sync）会等待交易被打包上链后才返回响应，并返回交易回执及解析出的事件数据。对应的非 Sync 变体（如sendTransaction）则只提交交易、返回交易哈希，不等待确认。这一约定在 packages/core/src/tempo/AGENTS.md 中有明确说明：所有写类 Action 均同时实现标准变体与*Sync变体。
useSendTransactionSync需要挂在WagmiProvider与QueryClientProvider之下才能正常工作：
import { QueryClient, QueryClientProvider } from '@tanstack/react-query' import { WagmiProvider } from 'wagmi' import { config } from './config' import { TokenMetadata } from './tokenMetadata' const queryClient = new QueryClient() function App() { return ( <WagmiProvider config={config}> <QueryClientProvider client={queryClient}> <TokenMetadata /> </QueryClientProvider> </WagmiProvider> ) }使用 Tempo Hooks：读取 TIP20 代币元数据
除了用普通 Wagmi Hooks 操作 Tempo 交易，还可以通过wagmi/tempo入口使用Tempo 专属 Hooks。入口文件 packages/react/src/exports/tempo.ts 将 Hooks 统一挂载在Hooks命名空间下；而 packages/react/src/tempo/hooks/index.ts 则把 Hooks 按协议模块组织为 10 个命名空间：amm、dex、faucet、fee、nonce、policy、reward、token、wallet、zone。
下面的组件通过Hooks.token.useGetMetadata读取 TIP20 代币（以 AlphaUSD 为例）的元数据：
import { Hooks } from 'wagmi/tempo' const alphaUsd = '0x20c0000000000000000000000000000000000001' export function TokenMetadata() { const { data: metadata, ...metadataQuery } = Hooks.token.useGetMetadata({ token: alphaUsd }) if (metadataQuery.isError) return <div>Error fetching metadata: {metadataQuery.error.message}</div> if (metadataQuery.isLoading) return <div>Loading metadata...</div> return <div>{metadata.name} ({metadata.symbol})</div> }从源码看，useGetMetadata的实现（packages/react/src/tempo/hooks/token.ts 第 967–980 行）本质是调用 Core 层Actions.token.getMetadata的queryOptions并交给useQuery托管，因此天然具备 TanStack Query 的缓存、重试、失效与select能力。其配套的app.tsx与config.ts与上一节完全一致（WagmiProvider+QueryClientProvider+ Tempo 配置）。
使用 Tempo Actions：在 React 与 Core 中直接调用
如果不需要 Hooks 的响应式状态管理，也可以直接调用 Tempo Actions。Tempo Actions 暴露在两个入口：
- React：
wagmi/tempo（即Actions命名空间）； - Core：
@wagmi/core/tempo（与 React 入口共享同一份 Actions 实现）。
入口 packages/core/src/exports/tempo.ts 将 packages/core/src/tempo/actions/index.ts 中的 10 个命名空间整体导出为Actions，同时导出tempoWallet、webAuthn、dangerous_secp256k1三个连接器。
React 用法：
import { Actions } from 'wagmi/tempo' import { config } from './config' const alphaUsd = '0x20c0000000000000000000000000000000000001' const metadata = await Actions.token.getMetadata(config, { token: alphaUsd, }) console.log('Token:', metadata.name, `(${metadata.symbol})`)React 的config.ts与前面一致（从wagmi、wagmi/chains、wagmi/tempo导入）。
Core 用法：
import { Actions } from '@wagmi/core/tempo' import { config } from './config' const alphaUsd = '0x20c0000000000000000000000000000000000001' const metadata = await Actions.token.getMetadata(config, { token: alphaUsd, }) console.log('Token:', metadata.name, `(${metadata.symbol})`)Core 的config.ts从@wagmi/core、@wagmi/core/chains、@wagmi/core/tempo导入。
Actions 的底层实现
查看 packages/core/src/tempo/actions/token.ts 第 923–930 行，getMetadata是典型的只读（query-based）Action：
export function getMetadata<config extends Config>( config: config, parameters: getMetadata.Parameters<config>, ): Promise<getMetadata.ReturnValue> { const { chainId, ...rest } = parameters const client = config.getClient({ chainId }) return Actions.token.getMetadata(client, rest) }它从 Wagmiconfig中取出对应chainId的 Viem 客户端，再调用viem/tempo的同名 Action 完成 RPC 请求，本质是 Wagmi 对 Viem Tempo Actions 的一层薄封装。此外，只读 Action 的命名空间内还附带queryKey与queryOptions两个工具函数（第 940–960 行），用于与 TanStack Query 集成：queryKey生成稳定的缓存键，queryOptions会在必需的响应式参数（如token）缺失时自动将enabled置为false，避免发起无效请求。
而对于写类（mutation-based）Action，则通过getConnectorClient获取已连接的钱包客户端发起交易。仓库测试 packages/core/src/tempo/actions/token.test.ts 对getMetadata的默认场景与queryOptions场景均有覆盖，可直接作为使用参考。
进阶：Tempo 链与默认费用代币
Tempo 生态提供多条链，均可从wagmi/chains导入（详见 site/tempo/chains.md）：
import { tempo, tempoDevnet, tempoLocalnet, tempoTestnet, } from 'wagmi/chains'设置默认费用代币
Tempo 支持为链设置默认费用代币（default fee token）：通过在链对象上扩展feeToken属性，该链上所有交易将默认使用该代币支付费用，除非在单笔交易层面显式覆盖：
import { tempo } from 'wagmi/chains' const chain = tempo.extend({ feeToken: '0x20c0000000000000000000000000000000000001', })这是一个非常实用的配置：对于只接受单一稳定币作为 gas 的应用，可以省去每笔交易重复指定费用代币的样板代码。
其他连接器与生态入口
除tempoWallet外，packages/core/src/tempo/Connectors.ts 还提供两个基于accountsSDK 的额外连接器：
webAuthn()（第 115–132 行）：WebAuthn EOA 连接器，通过authUrl（ceremony 模式）或ceremony配置生物识别登录，连接器type为'webAuthn'；dangerous_secp256k1()（第 151–167 行）：Secp256k1 EOA 连接器，以明文存储私钥并绑定会话存储生命周期，源码明确警告不推荐用于生产环境，仅适合本地开发调试。
完整的 Tempo 连接器文档位于 site/tempo/connectors/，更多协议模块的 Hooks 与 Actions 列表可查阅 site/tempo/hooks/ 与 site/tempo/actions/。
Next Steps：下一步可以做什么
完成 Tempo 与 Wagmi 的接入后，你可以进一步探索：
- 指南与示例：阅读官方指南，学习如何使用账户、发起支付、发行稳定币、进行稳定币兑换等完整业务流程；
- Tempo React Hooks：浏览全部 Hooks（
amm.*、dex.*、fee.*、token.*、wallet.*、zone.*等 10 大模块）并了解各 Hook 的参数与返回值； - Tempo Core Actions：在非 React 场景下直接使用
@wagmi/core/tempo的 Actions，配合 TanStack Query 手动管理数据流。
建议的实践路径是：先通过本文的tempoWallet+Hooks.token.useGetMetadata打通第一条只读链路，再用useSendTransactionSync的calls/feePayer/nonceKey组合验证批量交易与费用赞助，最后按业务模块逐个引入dex、fee、policy等命名空间的能力。
【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmi
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
