wagmi Tempopolicy.create完全指南用白名单/黑名单策略为 Token 转账做访问控制【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmi本文是 wagmi 仓库中 Tempo 模块policy.create动作Action的深度实战指南。policy.create用于创建一条全新的转账策略transfer policy实现 Token 层面的访问控制白名单策略只允许被列入的地址转账黑名单策略则允许除列入地址外的所有地址转账。读完本文你将掌握create/createSync两种调用形态的完整用法、全部参数语义、返回值结构以及它在核心包源码中的底层调用链与测试验证并了解与之配套的setAdmin、modifyWhitelist、modifyBlacklist、getData、isAuthorized、watchCreate等策略生命周期操作。1.policy.create是什么在 Tempo 协议TIP-403 相关规范中转账策略是一种用于 Token 访问控制的可编程规则。每条策略都有一个唯一 IDpolicyId并归属于一个管理员admin。策略决定了哪些地址被允许或禁止进行 Token 转账操作。policy.create是创建该策略的入口动作它支持两种策略类型类型行为whitelist仅允许被列入addresses的地址进行转账blacklist允许所有地址转账但被列入addresses的地址除外从源码结构看策略创建只是整个policy模块的一部分。在 packages/core/src/tempo/actions/policy.ts 中与create并列的还有setAdmin设置管理员、modifyWhitelist增删白名单成员、modifyBlacklist增删黑名单成员、getData读取策略数据、isAuthorized校验地址是否被授权以及watchCreate/watchAdminUpdated/watchWhitelistUpdated/watchBlacklistUpdated等事件监听函数共同构成策略的完整生命周期。本文对应仓库文档site/tempo/actions/policy.create.md。2. 环境准备创建 Tempo 链的 wagmi Config在调用任何 Tempo 动作之前需要先构造一个连接到 Tempo 链的 wagmi Config。仓库中的标准示例位于 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(), }, })要点说明tempoWallet()是仓库packages/connectors中提供的 Tempo 钱包连接器负责提供签名账户chains: [tempo]指定应用运行在 Tempo 链上multiInjectedProviderDiscovery: false关闭多注入 Provider 探测避免与 Tempo 钱包之外的浏览器钱包冲突transports中为 Tempo 链配置http()传输层用于读写链上数据。3. 同步用法Actions.policy.createSynccreateSync是create的同步变体它会等待交易被打包上链后再返回结果。适合对响应延迟不敏感、希望一步拿到策略 ID 和交易收据的场景。import { Actions } from wagmi/tempo import { config } from ./config const { policyId, policyType, receipt } await Actions.policy.createSync(config, { addresses: [ 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEbb, 0x70997970C51812dc3A010C7d01b50e0d17dc79C8, ], type: whitelist, }) console.log(Policy ID:, policyId) // log: Policy ID: 1n返回值中的receipt是完整的TransactionReceipt可用于进一步确认交易状态如receipt.transactionHash。从源码看createSync的实现位于 packages/core/src/tempo/actions/policy.tsexport async function createSyncconfig extends Config( config: config, parameters: createSync.Parametersconfig, ): PromiseActions.policy.createSync.ReturnValue { const { account, chainId, connector } parameters const client await getConnectorClient(config, { account, assertChainId: false, chainId, connector, }) return Actions.policy.createSync(client, parameters as never) }关键点它先通过getConnectorClient从 wagmi Config 中解析出连接器客户端支持account/chainId/connector覆盖assertChainId: false表示不强制校验当前链 ID允许调用方显式指定目标链随后将底层执行委托给 viem 的Actions.policy.createSync也就是说 wagmi 的 Tempo 动作是建立在 viem Tempo 动作之上的一层框架适配获取连接器客户端、注入 wagmi Config 上下文。4. 异步用法Actions.policy.create 手动等待如果你更关注性能不希望动作阻塞到交易确认则应使用非 Sync 版本的policy.create。它只返回交易哈希随后由你手动等待交易收据并通过事件解析出policyIdimport { Actions as viem_Actions } from viem/tempo import { Actions } from wagmi/tempo import { waitForTransactionReceipt } from wagmi/actions const hash await Actions.policy.create(config, { addresses: [ 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEbb, 0x70997970C51812dc3A010C7d01b50e0d17dc79C8, ], type: whitelist, }) const receipt await waitForTransactionReceipt(config, { hash }) const { args: { policyId } } viem_Actions.policy.create.extractEvent(receipt.logs)这种“先拿 hash、后查收据”的模式可以在交易在途pending期间继续做其他事情例如同时发起多笔策略操作或展示交易进度。extractEvent是 viem Tempo 动作提供的事件解析工具可从收据日志中精确提取PolicyCreated事件的参数。两种形态的选择建议需要尽快拿到policyId或对后续逻辑强依赖收据 → 用createSync需要并发执行多笔交易、优化吞吐 → 用createwaitForTransactionReceipt。5. 返回值结构Return Type无论create还是createSync最终返回的数据形状如下type ReturnType { /** ID of the created policy */ policyId: bigint /** Type of the policy (0 whitelist, 1 blacklist) */ policyType: number /** Transaction receipt */ receipt: TransactionReceipt /** Address that created the policy */ updater: Address }字段含义policyId新建策略的唯一 IDbigint后续setAdmin、modifyWhitelist、modifyBlacklist、getData、isAuthorized等动作都需要它作为入参policyType策略类型的数值编码0表示白名单、1表示黑名单receipt交易收据Sync 变体返回已确认的收据updater发起创建操作的地址通常即当前连接的账户地址。上述数值编码0 whitelist, 1 blacklist在仓库测试中也有印证见 packages/core/src/tempo/actions/policy.test.ts其中断言createSync创建白名单策略后policyType为0、黑名单策略后为1且updater等于当前连接的账户地址。6. 参数详解6.1 type必填类型whitelist | blacklist要创建的策略类型。白名单策略只允许被列入的地址黑名单策略允许除被列入地址之外的所有地址。这也是policyType返回值0 / 1对应的语义来源。6.2 addresses可选类型Address[]用于初始化策略的地址数组。创建时即把一批地址写入白名单或黑名单省去创建后再逐条modifyWhitelist/modifyBlacklist的步骤。6.3 通用写交易参数optional以下参数来自仓库中共享的参数说明文档 site/shared/tempo-write-parameters.md适用于包括policy.create在内的所有 Tempo 写动作参数类型说明accountAccount \| Address用于发送交易的账户默认使用已连接的 wagmi 账户feeTokenAddress \| bigint交易的费用 Token可以是 TIP-20 Token 地址或 IDfeePayerAccount \| true代付费用的账户可传 Viem Account若使用 Fee Payer Service 则传truegasbigint交易的 Gas 上限maxFeePerGasbigint交易的每单位 Gas 最高费用maxPriorityFeePerGasbigint交易的每单位 Gas 最高优先费小费noncenumber交易的 noncenonceKeyexpiring \| bigint交易的 nonce keyvalidBeforenumber交易必须被包含进区块的 Unix 时间戳上限validAfternumber交易可以被包含进区块的 Unix 时间戳下限throwOnReceiptRevertboolean默认true收据显示回滚时是否抛错仅对*Sync动作生效这些参数通过源码中的OptionalTransactionOverrides类型见 packages/core/src/tempo/actions/utils.ts被声明为可选从而在保持类型安全的同时让调用保持简洁。需要特别说明的是feeToken/feePayer体现了 Tempo 链的**代付sponsored transaction**能力应用可以为用户代付 Gas从而改善新用户的上手体验validBefore/validAfter是时间有效性窗口超出窗口交易将无法被打包throwOnReceiptRevert默认true意味着 Sync 变体在遇到链上回滚时会直接抛错避免拿到“已入块但失败”的静默结果。7. 源码级实现从 wagmi 到 viem 的委托链路policy.create与policy.createSync的实现非常简洁核心逻辑完全复用 viem 的 Tempo 动作create见 packages/core/src/tempo/actions/policy.ts解析account/chainId/connector→getConnectorClient获取客户端 → 委托Actions.policy.create(client, parameters)createSync见 packages/core/src/tempo/actions/policy.ts同样的链路只是委托给 viem 的createSync变体两者的Parameters类型均通过ChainIdParameter、ConnectorParameter与OptionalTransactionOverrides组合而来并剔除了底层 viem 参数中的chain | adminadmin由创建时的调用账户决定。这一层抽象的收益在于wagmi 负责框架集成Config、连接器、账户解析viem 负责链上协议细节交易组装、事件解析两者的分工清晰。8. 测试验证策略行为与特殊策略 ID仓库为策略模块提供了完整的集成测试见 packages/core/src/tempo/actions/policy.test.ts。与create直接相关的验证包括白名单创建第 15-35 行createSync(config, { type: whitelist })返回的policyType 0随后用getData读取到admin为当前账户、type为whitelist证明策略确实上链生效黑名单创建第 37-57 行policyType 1getData返回type: blacklist特殊策略 ID第 287-302 行测试还揭示了两个内置的特殊策略——policyId: 0n恒为拒绝always-rejectpolicyId: 1n恒为允许always-allow。这意味着即使尚未创建任何策略也可以通过固定 ID 快速引用“全局禁止/全局放行”的语义。测试流程统一为connect(config, { connector: config.connectors[0] })连接测试账户 → 执行createSync→ 用getData/isAuthorized反向验证结果形成一个完整的“创建-验证”闭环。9. React 声明式用法Hooks.policy.useCreate/useCreateSync如果你使用 React 框架仓库在wagmi/tempo入口中同时提供了对应的 Hooks 封装位于 packages/react/src/tempo/hooks/policy.tsimport { Hooks } from wagmi/tempo function App() { const { mutate, isPending } Hooks.policy.useCreateSync() return ( button onClick{() mutate({ type: whitelist })} disabled{isPending} Create Policy /button ) }实现要点见 policy.tsuseCreateSync内部通过useMutation封装Actions.policy.createSyncmutationKey为[createSync]useCreate对应非同步版本的Actions.policy.createmutationKey为[create]返回的是标准的 TanStack QueryUseMutationResult因此天然支持isPending、isError、error、onSuccess等状态管理同文件还提供了useSetAdmin、useModifyWhitelist、useModifyBlacklist、useData、useIsAuthorized以及useWatchCreate等系列 Hook可与useCreate组合成完整的策略管理界面。10. 相关动作与文档索引创建策略只是起点完整的策略生命周期还需要配合以下动作全部基于policyId操作动作用途文档policy.setAdmin更换策略管理员需当前管理员权限policy.setAdminpolicy.modifyWhitelist增删白名单成员allowed: true/falsepolicy.modifyWhitelistpolicy.modifyBlacklist增删黑名单成员restricted: true/falsepolicy.modifyBlacklistpolicy.getData读取策略数据admin、type 等policy.getDatapolicy.isAuthorized校验某个地址是否被策略授权policy.isAuthorizedpolicy.watchCreate监听策略创建事件policy.watchCreate典型组合流程为policy.createSync(config, { type: whitelist, addresses: [...] })创建策略并拿到policyIdpolicy.modifyWhitelist动态增删成员policy.isAuthorized在转账前校验地址权限需要转移管理权时调用policy.setAdmin。11. 注意事项与最佳实践*Sync与性能的权衡createSync会阻塞到交易上链在高频场景下优先使用非同步版本并配合waitForTransactionReceipt不要丢失policyId它是后续所有策略操作的唯一凭证建议创建成功后立即持久化例如关联到业务实体存储善用addresses初始化一次性初始化成员列表比创建后逐条 modify 更省 Gas理解throwOnReceiptRevert默认开启意味着 Sync 变体对链上回滚零容忍若你的业务希望宽容处理回滚可显式传入false特殊策略 ID0n恒拒绝与1n恒允许是内置策略可用来表达全局开关语义无需实际创建。延伸阅读Tempo 模块总览site/tempo/index.md、site/tempo/actions/index.md核心实现packages/core/src/tempo/actions/policy.ts集成测试packages/core/src/tempo/actions/policy.test.tsReact Hooks 实现packages/react/src/tempo/hooks/policy.ts共享写交易参数site/shared/tempo-write-parameters.md【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考