wagmi Tempo 黑名单策略管理实战policy.useModifyBlacklistHook 使用与原理详解【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmi本篇技术指南以 wagmi 仓库中 Tempo 模块的 React HookHooks.policy.useModifyBlacklist为核心讲解如何在基于 Tempo 的 EVM 应用中向「黑名单型转账策略blacklist-type transfer policy」添加或移除受限地址。读完本文你将掌握同步*Sync与异步两种调用方式、完整参数与返回值语义、底层 Action 调用链以及如何借助测试用例验证黑名单是否真正生效并能在自己的 React 应用中直接落地这一能力。背景Tempo 的转账策略与黑名单Tempo 是 wagmi / viem 生态中面向链上转账合规控制的能力模块。在 Tempo 的policy体系中转账策略分为白名单whitelist与黑名单blacklist两类两者都以policyId标识并由策略管理员admin维护。其中黑名单策略的语义是被加入黑名单的地址将不再被授权进行转账其余地址默认放行。Hooks.policy.useModifyBlacklist正是负责修改黑名单策略的 React Hook它把目标地址加入restricted: true或移出restricted: false黑名单并且要求调用者拥有策略管理员角色policy admin role——这一点与白名单操作useModifyWhitelist、管理员变更useSetAdmin一致属于典型的权限敏感型操作。该 Hook 有两个形态Hooks.policy.useModifyBlacklist()异步形态只返回交易哈希由调用方自行等待交易上链Hooks.policy.useModifyBlacklistSync()同步形态内部等待交易被区块包含后才返回直接给出交易回执与事件数据。环境准备Tempo 配置在使用该 Hook 前需要先创建指向 Tempo 链的 wagmi 配置。仓库文档片段中给出的标准配置如下原文片段见 site/snippets/react/config-tempo.tsimport { 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(), }, })要点说明chains: [tempo]将 Tempo 链注册进配置这是所有 Tempo Action/Hook 生效的前提connectors: [tempoWallet()]通过 Tempo 钱包连接账户之后由useConnect建立连接transports[tempo.id] http()使用 HTTP 传输层与链交互multiInjectedProviderDiscovery: false关闭多注入 Provider 探测避免与 Tempo 钱包之外的注入式钱包冲突。快速上手同步形态useModifyBlacklistSync原文档给出的主示例使用*Sync变体它会在事务被包含进区块后返回结果适合对一致性要求高的场景例如点击按钮后立刻在 UI 中展示回执import { Hooks } from wagmi/tempo const modifyBlacklistSync Hooks.policy.useModifyBlacklistSync() // 在用户动作按钮点击、表单提交中调用 mutate modifyBlacklistSync.mutate({ address: 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEbb, policyId: 1n, restricted: true, }) console.log(Transaction hash:, modifyBlacklistSync.data?.receipt.transactionHash) // log: Transaction hash: 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef在这个示例中policyId: 1n是目标黑名单策略的 IDbigint类型address是要被限制的目标账户restricted: true表示把该地址加入黑名单mutate触发一次链上写操作成功后data中会携带receipt可直接读取receipt.transactionHash。由于返回的是 TanStack Query 的UseMutationResult你还可以使用isPending、isError、error等状态驱动 UI例如在提交按钮上禁用并显示加载态import { Hooks } from wagmi/tempo function BlacklistButton() { const { mutate, isPending } Hooks.policy.useModifyBlacklistSync() return ( button onClick{() mutate({ policyId: 1n, address: 0x..., restricted: true })} disabled{isPending} {isPending ? 提交中... : 加入黑名单} /button ) }异步形态非 Sync 变体 手动等待回执*Sync变体虽然方便但会在内部等待区块包含对性能敏感的交互可能希望尽快拿到交易哈希并交给后台处理。此时应使用非 Sync 的policy.modifyBlacklist再配合useWaitForTransactionReceipt手动等待上链并可从回执日志中提取事件参数import { Hooks } from wagmi/tempo import { Actions } from viem/tempo import { useWaitForTransactionReceipt } from wagmi const modifyBlacklist Hooks.policy.useModifyBlacklist() const { data: receipt } useWaitForTransactionReceipt({ hash: modifyBlacklist.data }) // 在用户动作中调用 mutate modifyBlacklist.mutate({ address: 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEbb, policyId: 1n, restricted: true, }) if (receipt) { const { args } Actions.policy.modifyBlacklist.extractEvent(receipt.logs) }这种「先拿哈希、后等回执」的写法把上链等待从提交路径中剥离出来避免阻塞用户操作extractEvent则从回执日志中解析出BlacklistUpdated事件的参数account、policyId、restricted、updater等便于在 UI 中提示具体的变更内容。参数详解address类型Address必填要加入或移出黑名单的目标账户地址。在测试中加入与移出通常针对同一个地址进行见下文测试章节。policyId类型bigint必填要修改的黑名单策略 ID。注意 Tempo 存在两个特殊策略policyId: 0n为「始终拒绝always-reject」policyId: 1n为「始终允许always-allow」二者由协议内置不应作为modifyBlacklist的目标正常业务策略 ID 从2n开始递增。restricted类型boolean必填true表示将address加入黑名单限制转账false表示将其移出黑名单解除限制。是否生效可通过Hooks.policy.useIsAuthorized({ policyId, user })或Actions.policy.isAuthorized进行验证。可选交易参数除上述三个必填参数外modifyBlacklist还接受一组可选的交易级参数其完整说明定义在共享文档 site/shared/tempo-write-parameters.md 中此处整理为速查表参数类型默认值说明accountAccount \| Address已连接的 wagmi 账户发送交易的账户feeTokenAddress \| bigint—交易费用代币可为 TIP-20 代币地址或 IDfeePayerAccount \| true—费用支付方传true表示使用 Fee Payer 服务代付gasbigint—交易 Gas 上限maxFeePerGasbigint—每单位 Gas 的最高费用maxPriorityFeePerGasbigint—每单位 Gas 的最高优先费用noncenumber—交易 noncenonceKeyexpiring \| bigint—交易 nonce keyvalidBeforenumber—交易必须在此时刻Unix 时间戳之前被打包validAfternumber—交易只能在此时刻Unix 时间戳之后被打包throwOnReceiptRevertbooleantrue若回执表明交易被 revert 则抛出错误仅*Sync形态适用这些参数在*Sync与非 Sync 形态下均可使用其中throwOnReceiptRevert只对*Sync变体有意义因为只有它会在内部读取回执。返回值useModifyBlacklist的返回值遵循 TanStack Query v5 的useMutation规范官方文档指向 TanStack Query mutation docs核心字段包括data成功后的返回数据类型与底层 Actionpolicy.modifyBlacklist的 Return Type 一致完整定义见 site/tempo/actions/policy.modifyBlacklist.md其结构为type ReturnType { /** 被加入/移出黑名单的地址 */ account: Address /** 策略 ID */ policyId: bigint /** 交易回执 */ receipt: TransactionReceipt /** 该地址是否处于受限状态 */ restricted: boolean /** 修改黑名单的地址操作者 */ updater: Address }mutate/mutateAsync触发修改的提交函数入参即上文「参数详解」中的参数集合address、policyId、restricted及可选交易参数。二者区别在于mutate不返回 Promise适合事件回调中使用mutateAsync返回 Promise适合在async/await流程中串行编排测试代码中即大量使用mutateAsync。此外还有isPending、isError、error、reset等UseMutationResult标准字段用于状态管理。Hook 级参数config类型Config | undefined默认情况下Hook 会从最近的WagmiProvider上下文读取配置传入该参数可以显式指定要使用的Config对应 wagmi 的createConfig返回值覆盖 Provider 提供的默认值。mutation类型UseMutationParameters透传给 TanStack QueryuseMutation的选项例如onSuccess、onError、onSettled回调以及gcTime、retry等行为配置。在源码实现中Hook 通过{ ...mutation, mutationFn, mutationKey }的方式与内部选项合并。源码级剖析从 Hook 到链上交易的调用链理解底层实现有助于排查问题与性能调优。React Hook 的实现位于 packages/react/src/tempo/hooks/policy.tsuseModifyBlacklist/useModifyBlacklistSync两个函数其核心逻辑极简const config useConfig(parameters) return useMutation({ ...mutation, async mutationFn(variables) { return Actions.policy.modifyBlacklist(config, variables as never) }, mutationKey: [modifyBlacklist], }) as never即从上下文解析Config然后调用wagmi/core/tempo的Actions.policy.modifyBlacklist(config, variables)并包裹为 TanStack Query mutation。useModifyBlacklistSync与其唯一区别是调用Actions.policy.modifyBlacklistSync且mutationKey为[modifyBlacklistSync]。Core 层 Action 的实现位于 packages/core/src/tempo/actions/policy.ts关键调用链如下export async function modifyBlacklistconfig extends Config( config: config, parameters: modifyBlacklist.Parametersconfig, ): PromiseActions.policy.modifyBlacklist.ReturnValue { const { account, chainId, connector } parameters const client await getConnectorClient(config, { account, assertChainId: false, chainId, connector, }) return Actions.policy.modifyBlacklist(client, parameters as never) }从源码结构可以推断出如下调用链从parameters中解构account、chainId、connector通过getConnectorClient获取与当前连接器绑定的 viem 客户端注意assertChainId: false即不强校验链 ID兼容 Tempo 链的交互方式将事务委托给 viem 层viem/tempo的Actions.policy.modifyBlacklist(client, parameters)真正执行链上写入。而modifyBlacklistSync则调用Actions.policy.modifyBlacklistSync后者在 viem 层内部完成「发送交易 → 等待区块包含 → 解析回执与事件」的全流程这正是*Sync形态能够直接返回receipt的原因。与之对应非 Sync 形态仅返回交易哈希上链等待交由调用方处理。在类型层面两者的Parameters均由ChainIdParameterconfig ConnectorParameter OptionalTransactionOverrides...组合而来并通过UnionLooseOmit剔除chain字段链由chainId指定ReturnValue直接透传 viem 层的返回类型确保端到端类型安全。测试验证黑名单行为如何被保障仓库为该 Hook 提供了完整的端到端测试位于 packages/react/src/tempo/hooks/policy.test.ts 的useModifyBlacklist用例其测试路径完整覆盖了「加入黑名单 → 验证生效 → 移出黑名单 → 验证恢复」是理解语义的最佳范本建立连接connect.mutateAsync({ connector: config.connectors[0] })连接测试账户创建黑名单策略createSync.mutateAsync({ type: blacklist })得到policyId测试快照中为6npolicyType: 1对应黑名单类型初始状态验证Actions.policy.isAuthorized(config, { policyId, user: account2.address })返回true——未进黑名单默认被授权加入黑名单modifyBlacklistSync.mutateAsync({ policyId, address: account2.address, restricted: true })断言回执存在且返回数据{ account, policyId, restricted: true, updater }与快照一致再次验证isAuthorized返回false——地址被限制移出黑名单modifyBlacklistSync.mutateAsync({ ..., restricted: false })断言restricted: false恢复验证isAuthorized返回true——地址重新获得授权。与之配套Core 层测试 packages/core/src/tempo/actions/policy.test.ts 中modifyBlacklist用例验证了同一行为且useWatchBlacklistUpdated用例证明每次修改都会触发onBlacklistUpdated事件events[0].restricted true、events[1].restricted false说明黑名单变更可被实时监听。这一「修改 → 验证 → 回滚 → 再验证」的闭环也给出了生产环境的最佳实践在把modifyBlacklist接入 UI 之前务必用useIsAuthorized/Actions.policy.isAuthorized确认策略语义与预期一致避免黑白名单语义混淆造成误放行或误拦截。常见使用模式与注意事项权限前置modifyBlacklist要求调用者是策略 admin否则链上会 revert。若当前账户不是 admin应先通过Hooks.policy.useSetAdmin变更管理员注意该操作同样需要 admin 权限。白名单与黑名单不可混用policyId必须指向type: blacklist的策略对白名单策略使用restricted参数没有意义应使用Hooks.policy.useModifyWhitelist参数为allowed。性能取舍交互要求即时反馈用*Sync高并发、需要自行控制等待时机用非 Sync 变体 useWaitForTransactionReceipt。实时同步配合Hooks.policy.useWatchBlacklistUpdated文档见 site/tempo/hooks/policy.useWatchBlacklistUpdated.md可以在多端场景下监听黑名单变更事件。相关联动能力创建策略用Hooks.policy.useCreatetype: blacklist、查询策略数据用Hooks.policy.useData、校验授权用Hooks.policy.useIsAuthorized完整 Hook 清单见 site/tempo/hooks/index.md。延伸阅读底层 Action 完整文档site/tempo/actions/policy.modifyBlacklist.mdReact Hook 源码packages/react/src/tempo/hooks/policy.tsCore Action 源码packages/core/src/tempo/actions/policy.tsReact Hook 测试packages/react/src/tempo/hooks/policy.test.tsCore Action 测试packages/core/src/tempo/actions/policy.test.ts可选交易参数规范site/shared/tempo-write-parameters.mdTempo 配置示例site/snippets/react/config-tempo.ts【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考