wagmi Tempo 事件监听实战使用policy.watchBlacklistUpdated监控 TIP403 黑名单变更【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmipolicy.watchBlacklistUpdated是 wagmi Tempo 模块中用于监听 TIP403 Registry 黑名单更新事件的响应式原语。本文以官方文档 site/tempo/actions/policy.watchBlacklistUpdated.md 为主体骨架结合仓库内核心实现、React Hook 封装与端到端测试完整讲解该 Action 的用法、全部参数语义、底层调用链与最佳实践。读完本文你将能够在自己的 wagmi 应用中实时捕获黑名单账户变更事件并据此驱动风控、审计或 UI 状态刷新逻辑。背景TIP403 与黑名单策略Tempo 网络通过TIP403 转移策略Transfer Policy管控资产流动策略分为白名单whitelist与黑名单blacklist两类。黑名单策略由管理员维护一份受限账户列表凡被加入黑名单的账户将受到转移限制。policy.watchBlacklistUpdated正是面向该场景的「订阅端」原语它持续监听链上BlacklistUpdated事件一旦策略黑名单发生任何增删账户被加入或移出黑名单回调函数便会携带事件参数与原始日志触发。该事件与写入端 Action 成对出现Actions.policy.modifyBlacklist/modifyBlacklistSync负责修改黑名单写入事件Actions.policy.watchBlacklistUpdated负责订阅事件消费事件。两者配合即可构建「修改—感知」的完整闭环例如在测试用例 packages/core/src/tempo/actions/policy.test.ts 中先创建type: blacklist策略再连续执行两次modifyBlacklistSync分别设置restricted: true与restricted: false监听器即捕获到两条事件。前置准备配置 Tempo 客户端在使用任何 Tempo Action 之前需要先通过createConfig创建 wagmi 配置并注册 tempo 链与tempoWallet连接器。官方推荐的最小配置见 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(), }, })其中multiInjectedProviderDiscovery: false用于禁用多注入提供方自动发现确保仅使用显式声明的tempoWallet连接器transports为 tempo 链配置 HTTP 传输层。该配置对象将作为watchBlacklistUpdated的第一个参数传入。基本用法订阅并退订黑名单事件Actions.policy.watchBlacklistUpdated的调用形态非常简洁传入配置对象与参数返回一个用于停止监听的退订函数。import { Actions } from wagmi/tempo import { config } from ./config const unwatch Actions.policy.watchBlacklistUpdated(config, { onBlacklistUpdated(args, log) { console.log(args:, args) }, }) // Later, stop watching unwatch()回调签名中的args携带结构化事件参数log为对应的原始日志对象Log可用于进一步解析区块、交易哈希等元信息。返回类型退订函数类型() void每次调用watchBlacklistUpdated都会建立一条独立的订阅通道并立即返回退订函数。组件卸载、页面切换或业务不再关心该事件时务必调用unwatch()释放资源避免回调泄漏与重复触发。参数详解onBlacklistUpdated必填类型functiondeclare function onBlacklistUpdated(args: Args, log: Log): void type Args { /** Address of the account */ account: Address /** ID of the policy */ policyId: bigint /** Whether the account is restricted */ restricted: boolean /** Address that updated the blacklist */ updater: Address }每次黑名单更新时触发。四个字段语义如下字段类型含义accountAddress被加入/移出黑名单的账户地址policyIdbigint发生变更的策略 IDrestrictedbooleantrue表示账户被限制加入黑名单false表示解除限制移出黑名单updaterAddress执行本次黑名单修改的地址通常为策略管理员测试用例 packages/core/src/tempo/actions/policy.test.ts 验证了事件参数的真实形态连续两次修改同一账户的黑名单状态后events[0].args.restricted为true、events[1].args.restricted为false且policyId、updater、account均与写入端参数一致。args可选事件过滤类型objecttype Args { /** Filter by policy ID */ policyId?: bigint | bigint[] | null /** Filter by updater address */ updater?: Address | Address[] | null /** Filter by account address */ account?: Address | Address[] | null }可选过滤参数用于收窄监听范围。每个字段既可以是单个值也可以是数组匹配多个目标传入null表示不按该维度过滤。例如只关注某一策略下特定账户的状态变化const unwatch Actions.policy.watchBlacklistUpdated(config, { args: { policyId: 1n, account: 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEbb, }, onBlacklistUpdated(args) { console.log(Blacklist updated:, args) }, })合理使用过滤参数可以显著减少不相关事件的回调开销。fromBlock可选类型bigint指定开始监听的起始区块高度。默认从当前区块开始如需回溯历史黑名单变更例如应用启动时补全错过的状态可显式传入更早的区块号。onError可选类型functiondeclare function onError(error: Error): void当尝试获取新区块失败时调用用于异常兜底与可观测性记录。建议在生产环境提供该回调并配合日志/监控系统上报错误。poll可选类型true启用轮询模式。默认实现基于订阅推送但在某些受限网络环境下可设置poll: true强制改用定时轮询方式获取新区块。pollingInterval可选类型number轮询频率单位为毫秒ms。仅在poll: true时生效若不传默认使用 Client 配置中的pollingInterval即createConfig时设置的值。底层实现从 wagmi 到 viem 的委托调用链从源码结构看Actions.policy.watchBlacklistUpdated在 wagmi 中是一个轻量包装层真正的链上监听逻辑由 viem 的 Tempo 模块实现。核心包装代码位于 packages/core/src/tempo/actions/policy.tsexport function watchBlacklistUpdatedconfig extends Config( config: config, parameters: watchBlacklistUpdated.Parametersconfig, ) { const { chainId, ...rest } parameters const client config.getClient({ chainId }) return Actions.policy.watchBlacklistUpdated(client, rest) }调用链可概括为从参数中解构出chainId可选默认取配置的活动链其余参数透传通过config.getClient({ chainId })获取对应的 viem 客户端将客户端与剩余参数一并委托给viem/tempo的Actions.policy.watchBlacklistUpdated将 viem 返回的退订函数原样透传给调用方。这意味着 wagmi 层主要负责「配置 → 客户端」的桥接与类型推导事件监听的轮询、区块扫描、日志解析等繁重工作在 viem 层完成两层 API 签名保持一致迁移成本极低。React 集成useWatchBlacklistUpdatedHook对于 React 应用wagmi 提供了配套的声明式 HookHooks.policy.useWatchBlacklistUpdated封装了挂载订阅、依赖追踪与卸载退订的生命周期管理。实现见 packages/react/src/tempo/hooks/policy.tsimport { Hooks } from wagmi/tempo function App() { Hooks.policy.useWatchBlacklistUpdated({ onBlacklistUpdated(args) { console.log(Blacklist updated:, args) }, }) return divWatching for blacklist updates.../div }Hook 内部的关键行为enabled 开关enabled默认true置为false时跳过订阅可在条件不满足如未连接钱包时优雅禁用onBlacklistUpdated 必填未提供回调时直接跳过useEffect副作用避免空订阅chainId 自动推导通过useConfig与useChainId获取当前配置与活动链未显式传chainId时自动沿用依赖追踪fromBlock、onError、poll、pollingInterval均被列入useEffect依赖数组任一变化都会重建订阅自动清理副作用函数直接返回 viem 的退订函数组件卸载或依赖变化时 React 自动调用。类型层面Hook 的参数在 viem 参数基础上追加了ConfigParameter可选config与enabled字段见 packages/react/src/tempo/hooks/policy.test-d.ts 的类型测试回调中的args与log均保证为对象类型。端到端验证测试用例如何证明行为仓库提供了完整的单元与集成测试是理解该 Action 行为契约的最佳参考core 层测试packages/core/src/tempo/actions/policy.test.ts连接钱包 →createSync({ type: blacklist })创建黑名单策略 → 注册监听 → 两次modifyBlacklistSync加入再移出黑名单→vi.waitFor断言捕获 ≥2 条事件并逐字段核对policyId、updater、account、restrictedReact 层测试packages/react/src/tempo/hooks/policy.test.ts通过renderHook挂载useWatchBlacklistUpdated配合useCreateSync/useModifyBlacklistSync复现同一场景验证 Hook 化后的行为与 core 层一致。这两个测试共同构成「写入端触发事件 → 订阅端捕获事件」的闭环证据也展示了该 Action 的典型联调套路。与相关 Action 的配合policy.modifyBlacklist/modifyBlacklistSync黑名单修改的写入端返回account、policyId、restricted、updater与交易回执参考 site/tempo/actions/policy.modifyBlacklist.md。其中*Sync变体等待交易上链后返回便于「修改后立即校验事件」policy.watchWhitelistUpdated白名单事件的对称监听原语回调参数为account、allowed、policyId、updater参考 site/tempo/actions/policy.watchWhitelistUpdated.mdpolicy.watchCreate、policy.watchAdminUpdated策略创建与管理员变更的同类监听原语共同构成 TIP403 策略模块的完整事件体系。注意事项与最佳实践务必退订无论使用 Actions 还是 Hook都要在合适的时机调用unwatch()Hook 已自动处理卸载清理Actions 手动调用时请结合组件生命周期或页面路由守卫善用过滤参数大策略集场景下通过args限定policyId/updater/account减少无关回调与 RPC 压力区分restricted语义true表示「加入黑名单限制」false表示「移出黑名单解除限制」切勿与白名单的allowed混淆同步配合若需在界面即时反馈可使用modifyBlacklistSync等待交易上链后再刷新本地状态若追求性能则用非 Sync 变体 waitForTransactionReceipt参见 site/tempo/actions/policy.modifyBlacklist.md 中的异步用法示例轮询兜底在事件订阅不可靠的环境中设置poll: true与合适的pollingInterval并配合onError做异常告警。通过本文的讲解你现在应该能够独立完成 Tempo 黑名单事件的订阅、过滤、退订与 React 集成并将watchBlacklistUpdated与modifyBlacklist等写入端 Action 组合成完整的策略风控闭环。【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考