wagmi Tempo 系列dex.usePlaceFlipHook 完整实战指南——下单即翻转的 Flip 订单【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmidex.usePlaceFlip是 wagmi 中 Tempo 交易套件位于 packages/react/src/tempo/hooks/dex.ts提供的 React Mutation Hook用于在 Tempo 去中心化订单簿上挂出一笔翻转订单flip order当该订单被完全成交后系统会自动在相反方向挂出另一笔订单。本文以 site/tempo/hooks/dex.usePlaceFlip.md 为核心骨架结合源码实现与测试用例讲解其同步/异步两种用法、全部参数语义、返回类型、底层调用链并给出可直接运行的实战示例。什么是 Flip 订单Flip 订单是 Tempo 订单簿上一种特殊的挂单行为你以某个价格挂出一笔买单或卖单当它被对手方吃单成交后不需要再次签名或发起交易系统会自动在原方向的反面opposite side挂出一笔新订单。典型场景是网格/区间交易例如你希望在价格跌到 0.99 时买入 100 枚代币一旦成交就自动在 1.01 的价格挂出卖出单——这恰好是usePlaceFlip的参数语义tick是当前挂单价格flipTick是成交后翻转的目标价格。usePlaceFlip正是这一能力的 React Hook 封装它接收下单参数调用底层dex.placeFlip交易动作并把结果以 TanStack QueryuseMutation的形态暴露给组件层。基本用法usePlaceFlipSync完整示例文档给出的基础用法是*Sync变体它会在交易被打包进区块后才返回结果import { Hooks } from wagmi/tempo import { parseUnits } from viem import { Tick } from viem/tempo const placeFlipSync Hooks.dex.usePlaceFlipSync() // 在用户操作按钮点击、表单提交时调用 mutate placeFlipSync.mutate({ amount: parseUnits(100, 6), flipTick: Tick.fromPrice(1.01), tick: Tick.fromPrice(0.99), token: 0x20c0000000000000000000000000000000000001, type: buy, }) console.log(Flip order ID:, placeFlipSync.data?.orderId) // log: Flip order ID: 456n这段示例说明三件事参数来源amount使用 viem 的parseUnits把100按 6 位小数精度1_000_000转成biginttick与flipTick使用Tick.fromPrice()把价格字符串转为整数 tick。资金语义type: buy表示买入订单flipTick1.01必须大于tick0.99——买入成交后翻转挂到更高价位卖出反过来卖出单的flipTick必须小于tick。结果获取placeFlipSync.data?.orderId可直接读到新挂单的订单 ID。Sync变体的底层行为可以从源码确认在 packages/react/src/tempo/hooks/dex.ts 中usePlaceFlipSync的mutationFn直接调用Actions.dex.placeFlipSync(config, variables)该动作会等待交易确认详见下文底层调用链。与 React 组件结合源码的 JSDoc 示例展示了更贴近真实 UI 的写法packages/react/src/tempo/hooks/dex.tsimport { Hooks } from wagmi/tempo import { parseUnits } from viem import { Tick } from viem/tempo function App() { const { mutate, isPending } Hooks.dex.usePlaceFlip() return ( button onClick{() mutate({ amount: parseUnits(100, 6), flipTick: Tick.fromPrice(1.01), tick: Tick.fromPrice(0.99), token: 0x20c...11, type: buy, })} disabled{isPending} Place Flip Order /button ) }usePlaceFlip与usePlaceFlipSync都返回标准的 mutation 状态对象isPending可以在交易确认期间禁用按钮防止重复下单。异步用法非Sync变体 手动等待*Sync变体虽然使用方便但它会阻塞到交易上链才 resolve吞吐性能受限。文档明确建议如果追求性能应使用非 Sync 的dex.placeFlip动作自己手动等待交易确认。Hook 层同样提供非 Sync 变体usePlaceFlippackages/react/src/tempo/hooks/dex.ts它内部调用的是Actions.dex.placeFlip(config, variables)只返回交易哈希不等待打包。配合 wagmi 的useWaitForTransactionReceipt使用import { Hooks } from wagmi/tempo import { Actions } from viem/tempo import { parseUnits } from viem import { Tick } from viem/tempo import { useWaitForTransactionReceipt } from wagmi const placeFlip Hooks.dex.usePlaceFlip() const { data: receipt } useWaitForTransactionReceipt({ hash: placeFlip.data }) // 在用户操作时调用 mutate placeFlip.mutate({ amount: parseUnits(100, 6), flipTick: Tick.fromPrice(1.01), tick: Tick.fromPrice(0.99), token: 0x20c0000000000000000000000000000000000001, type: buy, }) if (receipt) { const { args: { orderId } } Actions.dex.placeFlip.extractEvent(receipt.logs) }关键点placeFlip.data是交易哈希将其交给useWaitForTransactionReceipt由 TanStack Query 自动轮询确认状态确认后通过 viem/tempo 的Actions.dex.placeFlip.extractEvent(receipt.logs)从回执日志中解析出FlipOrderPlaced事件参数拿到orderId这种先快速返回哈希、再异步等待的模式适合需要并发下单或高频操作的场景。参数详解usePlaceFlip/usePlaceFlipSync的参数分为两类mutation 变量下单参数传给mutate与hook 配置传给 hook 本身。下单参数mutation variables参数类型说明amountbigint放入订单的代币数量建议用parseUnits按代币精度生成flipTicknumber订单成交后翻转的目标 tick。买单必须大于tick卖单必须小于tickticknumber本笔订单的价格 tick用Tick.fromPrice()从价格字符串转换tokenAddress基础代币base token地址typebuy \| sell订单方向buy买入代币sell卖出代币关于flipTick的方向约束site/tempo/actions/dex.placeFlip.md 中有明确说明Must be greater thantickfor buy orders, less thantickfor sell orders。这一约束在测试中被验证测试用例以tick: Tick.fromPrice(1.001)、flipTick: Tick.fromPrice(1.002)挂买单packages/react/src/tempo/hooks/dex.test.ts并且断言结果中的isBid: true、flipTick: 200、tick: 100。注意除此之外文档还引用了共享的Tempo 写操作参数tempo-write-parameters.md即所有写操作共用的参数如 gas、chainId 等在实际项目中可一并查阅。Hook 配置参数configConfig | undefined。指定要使用的 wagmiConfig缺省时自动从最近的WagmiProvider上下文获取。从源码看usePlaceFlip内部通过useConfig(parameters)解析 configpackages/react/src/tempo/hooks/dex.ts。mutation透传给 TanStack QueryuseMutation的参数如onSuccess、onError、onSettled回调等。源码中通过...mutation展开合并进useMutation同上L1010-L1018。两个变体的 mutationKey 分别为[placeFlip]与[placeFlipSync]packages/react/src/tempo/hooks/dex.ts 与 L1093可用于查询缓存定位。返回类型与事件提取mutation 返回值usePlaceFlip的返回类型是UseMutationResult其data字段对应dex.placeFlip动作的 ReturnValuetype ReturnType { /** ID of the placed flip order */ orderId: bigint /** Address of the order maker */ maker: Address /** Address of the base token */ token: Address /** Amount of tokens in the order */ amount: bigint /** Whether this is a buy order */ isBid: boolean /** Price tick for the order */ tick: number /** Target tick to flip to when order is filled */ flipTick: number /** Transaction receipt */ receipt: TransactionReceipt }可以看到Sync变体的返回中直接带有receipt这就是它等待上链才返回的原因同时给出了orderId、maker、token、amount、方向isBid以及价格tick/flipTick。在测试快照packages/react/src/tempo/hooks/dex.test.ts中可以验证实际返回amount: 100000000n、flipTick: 200、tick: 100、isBid: true、maker: 0xf39F...2266。而mutate/mutateAsync的参数类型即上表的下单参数返回与动作的Parameters一致。与useWatchFlipOrderPlaced配合Flip 订单成交/事件也可以通过监听 Hook 感知。测试用例useWatchFlipOrderPlacedpackages/react/src/tempo/hooks/dex.test.ts演示了先usePlaceFlipSync挂单、再用useWatchFlipOrderPlaced监听FlipOrderPlaced事件的完整闭环事件参数同样包含flipTick、tick、isBid、amount是校验挂单是否成功的另一种手段。底层调用链从 Hook 到链上交易从源码看usePlaceFlip的完整调用链是Hook 层packages/react/src/tempo/hooks/dex.ts 中usePlaceFlip将参数包装为useMutationmutationFn委托给Actions.dex.placeFlip(config, variables)Action 层packages/core/src/tempo/actions/dex.ts 中placeFlip从 config 中解析出客户端getClient再转发给 viem/tempo 的同名动作Actions.dex.placeFlip(client, parameters)最终通过sendTransaction提交链上合约调用Sync 变体L1215-L1228 的placeFlipSync在调用后额外执行waitForTransactionReceipt因此返回类型中才带有receipt。也就是说usePlaceFlip→dex.placeFlip→ viem 的dex.placeFlip→ 合约sendTransactionusePlaceFlipSync则在最后多一步等回执。两个 action 在 core 层的ErrorType目前标注为BaseErrorType源码中留有// TODO: Actions.dex.placeFlip.ErrorType注释说明错误类型后续会进一步细分。运行环境准备要运行上述示例需要配置 Tempo 链与 Tempo 钱包连接器。仓库中的配置模板 site/snippets/react/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(), }, })要点tempoWallet()是 Tempo 专用的钱包连接器通过wagmi/tempo子路径导出chains: [tempo]声明 Tempo 链transports中为它配置默认http()传输将该 config 传给WagmiProviderReact后usePlaceFlip即可通过上下文自动获取 config无需手动传入。小结dex.usePlaceFlip以及其Sync变体把 Tempo 订单簿的翻转挂单能力封装成了标准的 React mutation Hook配合useWaitForTransactionReceipt、Actions.dex.placeFlip.extractEvent和useWatchFlipOrderPlaced可以构建完整的挂单—确认—事件感知链路。选择*Sync变体可获得开箱即用的回执结果选择非 Sync 变体则可获得更高的吞吐性能两者在参数与返回结构上保持一致可在同一项目中按场景混用。相关文档可继续参阅 site/tempo/actions/dex.placeFlip.md 与 site/tempo/hooks/dex.usePlace.md 系列页面。【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 wagmi Tempo 系列：`dex.usePlaceFlip` Hook 完整实战指南——下单即翻转的 Flip 订单
wagmi Tempo 系列dex.usePlaceFlipHook 完整实战指南——下单即翻转的 Flip 订单【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmidex.usePlaceFlip是 wagmi 中 Tempo 交易套件位于 packages/react/src/tempo/hooks/dex.ts提供的 React Mutation Hook用于在 Tempo 去中心化订单簿上挂出一笔翻转订单flip order当该订单被完全成交后系统会自动在相反方向挂出另一笔订单。本文以 site/tempo/hooks/dex.usePlaceFlip.md 为核心骨架结合源码实现与测试用例讲解其同步/异步两种用法、全部参数语义、返回类型、底层调用链并给出可直接运行的实战示例。什么是 Flip 订单Flip 订单是 Tempo 订单簿上一种特殊的挂单行为你以某个价格挂出一笔买单或卖单当它被对手方吃单成交后不需要再次签名或发起交易系统会自动在原方向的反面opposite side挂出一笔新订单。典型场景是网格/区间交易例如你希望在价格跌到 0.99 时买入 100 枚代币一旦成交就自动在 1.01 的价格挂出卖出单——这恰好是usePlaceFlip的参数语义tick是当前挂单价格flipTick是成交后翻转的目标价格。usePlaceFlip正是这一能力的 React Hook 封装它接收下单参数调用底层dex.placeFlip交易动作并把结果以 TanStack QueryuseMutation的形态暴露给组件层。基本用法usePlaceFlipSync完整示例文档给出的基础用法是*Sync变体它会在交易被打包进区块后才返回结果import { Hooks } from wagmi/tempo import { parseUnits } from viem import { Tick } from viem/tempo const placeFlipSync Hooks.dex.usePlaceFlipSync() // 在用户操作按钮点击、表单提交时调用 mutate placeFlipSync.mutate({ amount: parseUnits(100, 6), flipTick: Tick.fromPrice(1.01), tick: Tick.fromPrice(0.99), token: 0x20c0000000000000000000000000000000000001, type: buy, }) console.log(Flip order ID:, placeFlipSync.data?.orderId) // log: Flip order ID: 456n这段示例说明三件事参数来源amount使用 viem 的parseUnits把100按 6 位小数精度1_000_000转成biginttick与flipTick使用Tick.fromPrice()把价格字符串转为整数 tick。资金语义type: buy表示买入订单flipTick1.01必须大于tick0.99——买入成交后翻转挂到更高价位卖出反过来卖出单的flipTick必须小于tick。结果获取placeFlipSync.data?.orderId可直接读到新挂单的订单 ID。Sync变体的底层行为可以从源码确认在 packages/react/src/tempo/hooks/dex.ts 中usePlaceFlipSync的mutationFn直接调用Actions.dex.placeFlipSync(config, variables)该动作会等待交易确认详见下文底层调用链。与 React 组件结合源码的 JSDoc 示例展示了更贴近真实 UI 的写法packages/react/src/tempo/hooks/dex.tsimport { Hooks } from wagmi/tempo import { parseUnits } from viem import { Tick } from viem/tempo function App() { const { mutate, isPending } Hooks.dex.usePlaceFlip() return ( button onClick{() mutate({ amount: parseUnits(100, 6), flipTick: Tick.fromPrice(1.01), tick: Tick.fromPrice(0.99), token: 0x20c...11, type: buy, })} disabled{isPending} Place Flip Order /button ) }usePlaceFlip与usePlaceFlipSync都返回标准的 mutation 状态对象isPending可以在交易确认期间禁用按钮防止重复下单。异步用法非Sync变体 手动等待*Sync变体虽然使用方便但它会阻塞到交易上链才 resolve吞吐性能受限。文档明确建议如果追求性能应使用非 Sync 的dex.placeFlip动作自己手动等待交易确认。Hook 层同样提供非 Sync 变体usePlaceFlippackages/react/src/tempo/hooks/dex.ts它内部调用的是Actions.dex.placeFlip(config, variables)只返回交易哈希不等待打包。配合 wagmi 的useWaitForTransactionReceipt使用import { Hooks } from wagmi/tempo import { Actions } from viem/tempo import { parseUnits } from viem import { Tick } from viem/tempo import { useWaitForTransactionReceipt } from wagmi const placeFlip Hooks.dex.usePlaceFlip() const { data: receipt } useWaitForTransactionReceipt({ hash: placeFlip.data }) // 在用户操作时调用 mutate placeFlip.mutate({ amount: parseUnits(100, 6), flipTick: Tick.fromPrice(1.01), tick: Tick.fromPrice(0.99), token: 0x20c0000000000000000000000000000000000001, type: buy, }) if (receipt) { const { args: { orderId } } Actions.dex.placeFlip.extractEvent(receipt.logs) }关键点placeFlip.data是交易哈希将其交给useWaitForTransactionReceipt由 TanStack Query 自动轮询确认状态确认后通过 viem/tempo 的Actions.dex.placeFlip.extractEvent(receipt.logs)从回执日志中解析出FlipOrderPlaced事件参数拿到orderId这种先快速返回哈希、再异步等待的模式适合需要并发下单或高频操作的场景。参数详解usePlaceFlip/usePlaceFlipSync的参数分为两类mutation 变量下单参数传给mutate与hook 配置传给 hook 本身。下单参数mutation variables参数类型说明amountbigint放入订单的代币数量建议用parseUnits按代币精度生成flipTicknumber订单成交后翻转的目标 tick。买单必须大于tick卖单必须小于tickticknumber本笔订单的价格 tick用Tick.fromPrice()从价格字符串转换tokenAddress基础代币base token地址typebuy \| sell订单方向buy买入代币sell卖出代币关于flipTick的方向约束site/tempo/actions/dex.placeFlip.md 中有明确说明Must be greater thantickfor buy orders, less thantickfor sell orders。这一约束在测试中被验证测试用例以tick: Tick.fromPrice(1.001)、flipTick: Tick.fromPrice(1.002)挂买单packages/react/src/tempo/hooks/dex.test.ts并且断言结果中的isBid: true、flipTick: 200、tick: 100。注意除此之外文档还引用了共享的Tempo 写操作参数tempo-write-parameters.md即所有写操作共用的参数如 gas、chainId 等在实际项目中可一并查阅。Hook 配置参数configConfig | undefined。指定要使用的 wagmiConfig缺省时自动从最近的WagmiProvider上下文获取。从源码看usePlaceFlip内部通过useConfig(parameters)解析 configpackages/react/src/tempo/hooks/dex.ts。mutation透传给 TanStack QueryuseMutation的参数如onSuccess、onError、onSettled回调等。源码中通过...mutation展开合并进useMutation同上L1010-L1018。两个变体的 mutationKey 分别为[placeFlip]与[placeFlipSync]packages/react/src/tempo/hooks/dex.ts 与 L1093可用于查询缓存定位。返回类型与事件提取mutation 返回值usePlaceFlip的返回类型是UseMutationResult其data字段对应dex.placeFlip动作的 ReturnValuetype ReturnType { /** ID of the placed flip order */ orderId: bigint /** Address of the order maker */ maker: Address /** Address of the base token */ token: Address /** Amount of tokens in the order */ amount: bigint /** Whether this is a buy order */ isBid: boolean /** Price tick for the order */ tick: number /** Target tick to flip to when order is filled */ flipTick: number /** Transaction receipt */ receipt: TransactionReceipt }可以看到Sync变体的返回中直接带有receipt这就是它等待上链才返回的原因同时给出了orderId、maker、token、amount、方向isBid以及价格tick/flipTick。在测试快照packages/react/src/tempo/hooks/dex.test.ts中可以验证实际返回amount: 100000000n、flipTick: 200、tick: 100、isBid: true、maker: 0xf39F...2266。而mutate/mutateAsync的参数类型即上表的下单参数返回与动作的Parameters一致。与useWatchFlipOrderPlaced配合Flip 订单成交/事件也可以通过监听 Hook 感知。测试用例useWatchFlipOrderPlacedpackages/react/src/tempo/hooks/dex.test.ts演示了先usePlaceFlipSync挂单、再用useWatchFlipOrderPlaced监听FlipOrderPlaced事件的完整闭环事件参数同样包含flipTick、tick、isBid、amount是校验挂单是否成功的另一种手段。底层调用链从 Hook 到链上交易从源码看usePlaceFlip的完整调用链是Hook 层packages/react/src/tempo/hooks/dex.ts 中usePlaceFlip将参数包装为useMutationmutationFn委托给Actions.dex.placeFlip(config, variables)Action 层packages/core/src/tempo/actions/dex.ts 中placeFlip从 config 中解析出客户端getClient再转发给 viem/tempo 的同名动作Actions.dex.placeFlip(client, parameters)最终通过sendTransaction提交链上合约调用Sync 变体L1215-L1228 的placeFlipSync在调用后额外执行waitForTransactionReceipt因此返回类型中才带有receipt。也就是说usePlaceFlip→dex.placeFlip→ viem 的dex.placeFlip→ 合约sendTransactionusePlaceFlipSync则在最后多一步等回执。两个 action 在 core 层的ErrorType目前标注为BaseErrorType源码中留有// TODO: Actions.dex.placeFlip.ErrorType注释说明错误类型后续会进一步细分。运行环境准备要运行上述示例需要配置 Tempo 链与 Tempo 钱包连接器。仓库中的配置模板 site/snippets/react/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(), }, })要点tempoWallet()是 Tempo 专用的钱包连接器通过wagmi/tempo子路径导出chains: [tempo]声明 Tempo 链transports中为它配置默认http()传输将该 config 传给WagmiProviderReact后usePlaceFlip即可通过上下文自动获取 config无需手动传入。小结dex.usePlaceFlip以及其Sync变体把 Tempo 订单簿的翻转挂单能力封装成了标准的 React mutation Hook配合useWaitForTransactionReceipt、Actions.dex.placeFlip.extractEvent和useWatchFlipOrderPlaced可以构建完整的挂单—确认—事件感知链路。选择*Sync变体可获得开箱即用的回执结果选择非 Sync 变体则可获得更高的吞吐性能两者在参数与返回结构上保持一致可在同一项目中按场景混用。相关文档可继续参阅 site/tempo/actions/dex.placeFlip.md 与 site/tempo/hooks/dex.usePlace.md 系列页面。【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考