wagmi Tempo 系列指南token.useHasRole角色查询 Hook 的使用与源码解析【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmitoken.useHasRole是 wagmi Tempo 模块中用于检查某个账户是否持有 TIP-20 代币特定角色的响应式 Hook适用于权限校验、管理面板按钮显隐、审批流前置判断等场景。本文以官方文档 site/tempo/hooks/token.useHasRole.md 为主体结合 wagmi 仓库中 Action 与 Hook 的源码实现、测试用例系统讲解其参数、返回值、响应式行为与底层调用链帮助你准确地在 React 应用中落地角色权限查询。一、背景TIP-20 代币的角色体系在展开 Hook 本身之前先明确它解决的问题。TIP-20 是 Tempo 网络上的代币标准对应文档中的 TIP-20 token其代币合约内建了一套基于角色的权限模型用来控制谁能执行铸造、销毁、暂停等管理操作。token.hasRole系列 API 就是这套权限模型的只读查询入口——它不做任何状态变更只回答一个问题这个地址是否拥有这个角色从 packages/core/src/tempo/actions/token.ts 与官方文档的参数定义看当前 TIP-20 代币支持以下五种角色角色值语义从角色命名与代币管理功能推断defaultAdmin默认管理员拥有最高管理权限通常由代币创建者持有pause可暂停代币转账/操作unpause可解除暂停状态issuer可铸造发行新代币burnBlocked用于标识被禁止销毁的场景或账户token.useHasRole就是针对issuer这类角色的查询 Hook。在真实业务中典型场景包括只有issuer角色才能显示铸造按钮、只有defaultAdmin才能进入合约管理页面等。二、Hook 用法一个最小可运行示例原文档给出的用法非常简洁核心调用只有一次 Hook 调用。下面按原文档结构完整展开import { Hooks } from wagmi/tempo const { data: hasRole } Hooks.token.useHasRole({ account: 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEbb, role: issuer, token: 0x20c0000000000000000000000000000000000011, }) console.log(Has issuer role:, hasRole) // log: Has issuer role: true在组件中使用时配合 TanStack Query 的isLoading/data字段即可完成权限驱动的 UI 渲染import { Hooks } from wagmi/tempo function App() { const { data, isLoading } Hooks.token.useHasRole({ account: 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEbb, role: issuer, token: 0x20c0000000000000000000000000000000000011, }) if (isLoading) return divLoading.../div return divHas Role: {data ? Yes : No}/div }使用该 Hook 前需要通过createConfig创建包含 Tempo 链与tempoWallet连接器的配置并把它挂载到应用的WagmiProvider上。仓库中官方配置示例见 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链否则查询会因链不匹配而失败tempoWallet()是 Tempo 网络的钱包连接器useHasRole依赖其提供的客户端与账户上下文传入的account可以是任意地址不要求当前已连接钱包——因为hasRole是纯只读链上查询。三、参数详解token.useHasRole的参数分两部分业务参数透传给底层 Action与query 参数控制 TanStack Query 行为。业务参数参数类型必填说明accountAddress是要检查是否持有角色的地址即谁拥有该角色roledefaultAdmin \| pause \| unpause \| issuer \| burnBlocked是要检查的角色必须是上述五种枚举值之一tokenAddress \| bigint是TIP-20 代币的地址或 ID即在哪个代币上检查补充细节account与token均来自 viem 的Address类型0x开头的 20 字节十六进制地址token同时接受bigint说明 TIP-20 代币在 Tempo 网络中既可以通过合约地址、也可以通过代币 ID 定位五个角色值均为字面量联合类型TypeScript 会在编译期拦截拼写错误写role: Issuer这类大小写错误的写法会直接报类型错误参数类型定义位于 packages/core/src/tempo/actions/token.ts 中的hasRole.Parameters并叠加了ChainIdParameter可选chainId与 Hook 层追加的ConfigParameter。query 参数原文档明确说明query 相关参数遵循 TanStack Query v5 的useQuery约定可参考 TanStack Query 官方useQuery参考文档。常用选项包括enabled是否自动发起查询select对返回的boolean做二次转换例如映射为可铸造 | 不可铸造等业务文案staleTime/refetchInterval控制缓存新鲜度与轮询刷新适合角色被动态授予/撤销的场景。这些参数与业务参数同时传入 HookHooks.token.useHasRole({ account, role: issuer, token, query: { enabled: isConnected, staleTime: 30_000, }, })四、返回值详解useHasRole的返回值是 TanStack Query 的查询结果对象核心字段如下字段类型说明databoolean \| undefined账户是否持有该角色查询未完成时为undefinedisLoading/isPendingboolean首次加载中isFetchingboolean是否正在请求含后台刷新isSuccessboolean查询是否成功完成isError/errorboolean/Error查询失败状态与错误对象refetchfunction手动重新查询其中data的语义对应底层 Action 的返回值——boolean表示账户是否拥有该角色。这一点在 packages/core/src/tempo/actions/token.ts 的类型定义中得到印证export type ReturnValue Actions.token.hasRole.ReturnValue而在官方 Action 文档 site/tempo/actions/token.hasRole.md 中返回类型被明确为type ReturnType boolean // Whether the account has the role五、源码解析Hook 到底做了什么把官方文档与仓库源码对照可以还原useHasRole的完整调用链Hook → queryOptions → Action → viem Action → Tempo 节点。1. Hook 层React 响应式入口实现位于 packages/react/src/tempo/hooks/token.tsexport function useHasRoleconfig, selectData( parameters: useHasRole.Parametersconfig, selectData, ): useHasRole.ReturnValueselectData { const config useConfig(parameters) const chainId useChainId({ config }) const options Actions.token.hasRole.queryOptions(config, { ...parameters, chainId: parameters.chainId ?? chainId, } as never) return useQuery(options) as never }关键行为useConfig从 React 上下文取得 wagmi 配置useChainId取得当前激活链 ID业务代码未显式传chainId时自动使用当前链最终委托给 TanStack Query 的useQuery因此 Hook 天然具备缓存、去重、重试、窗口聚焦刷新等能力。2. queryOptions 层查询配置组装同一 Action 模块内定义了queryOptionspackages/core/src/tempo/actions/token.tsexport function queryOptions(config, parameters) { const { query, ...rest } parameters return { ...query, enabled: Boolean( rest.token rest.role rest.account (query?.enabled ?? true), ), queryKey: queryKey(rest), async queryFn(context) { const [, parameters] context.queryKey return await hasRole(config, parameters) }, } }值得注意的细节自动禁用enabled只要token、role、account三者任一为空查询就会自动处于禁用状态不会发起无意义的链上请求。这一点在测试用例 packages/react/src/tempo/hooks/token.test.ts 中得到了验证——当account为undefined时fetchStatus保持idledata为undefinedqueryKey 稳定queryKey 由[hasRole, parameters]构成见hasRole.queryKey意味着参数不变时查询结果会被缓存复用多次渲染不会重复请求queryFn 从 queryKey 反解参数查询函数直接从context.queryKey中取出参数再调用底层 Action保证请求与缓存键严格一致。3. Action 层wagmi 核心动作packages/core/src/tempo/actions/token.ts 中的hasRole实现非常轻量export function hasRoleconfig extends Config( config: config, parameters: hasRole.Parametersconfig, ): PromisehasRole.ReturnValue { const { chainId, ...rest } parameters const client config.getClient({ chainId }) return Actions.token.hasRole(client, rest) }config.getClient({ chainId })负责从 wagmi 配置中解析出对应链的 viem Clienttransport、链信息、账户环境均在此注入随后直接转发给 viem 的Actions.token.hasRole。也就是说真正的 RPC 读取逻辑由 viem 的 tempo 模块完成wagmi 层只负责配置解析与框架适配。六、与Actions.token.hasRole的配合使用useHasRole是响应式版本其底层是命令式版本Actions.token.hasRole。两者参数与返回语义完全一致区别仅在于调用方式import { Actions } from wagmi/tempo import { config } from ./config const hasRole await Actions.token.hasRole(config, { account: 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEbb, role: issuer, token: 0x20c0000000000000000000000000000000000011, }) console.log(Has issuer role:, hasRole) // log: Has issuer role: true完整示例见 site/tempo/actions/token.hasRole.md。使用建议UI 层优先使用useHasRole自动跟随链切换、参数变化响应式重查、结果自动缓存事件回调 / 一次性逻辑如点击按钮后校验一次使用Actions.token.hasRole直接await拿到boolean不引入查询状态两者共用同一套参数类型与queryKey从 Hook 迁移到 Action 无需修改业务参数结构。七、测试与验证仓库如何保证正确性wagmi 仓库为useHasRole提供了详尽的测试覆盖位于 packages/react/src/tempo/hooks/token.test.ts主要包括两类默认查询连接钱包后通过useCreateSync创建代币创建者自动成为defaultAdmin再调用useHasRole({ account, token, role: defaultAdmin })等待isSuccess后断言data true响应式行为先以account: undefined渲染断言查询处于禁用状态data为undefined、isPending为true随后传入真实account重新渲染验证查询被自动启用并返回正确结果。这两个用例分别验证了查询结果正确性与参数缺失时自动禁用、参数补齐后自动恢复的响应式契约——正是第四节提到的enabled逻辑在实际运行时的表现。八、常见问题与注意事项data为undefined而非false查询尚未完成或处于禁用状态时data是undefined请用isLoading/isPending区分加载中与确实没有角色避免把加载态误渲染为无权限角色名区分大小写role是字面量联合类型仅接受defaultAdmin、pause、unpause、issuer、burnBlocked五种小写写法查询自动禁用account、token、role任一缺失时不会发请求若希望强制查询请先确保三个参数均有值角色可能动态变化若角色的授予/撤销发生在查询之后可通过query.refetchInterval轮询或手动refetch刷新结果只读操作无 Gas 消耗hasRole是视图查询只读 RPC 调用不产生交易、不需要签名钱包未连接也可对任意地址执行查询。总结token.useHasRole是 wagmi Tempo 权限体系中查询角色的标准答案对外提供声明式、响应式的 Hook 接口内部则由queryOptions → hasRole Action → viem三级调用链完成配置注入与链上只读查询。理解其参数语义account/role/token、返回语义boolean以及参数缺失自动禁用的响应式契约即可在管理后台、铸造入口等场景中安全、高效地实现基于 TIP-20 角色的权限控制。相关源码与测试可继续查阅 packages/core/src/tempo/actions/token.ts、packages/react/src/tempo/hooks/token.ts 与 packages/react/src/tempo/hooks/token.test.ts。【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 wagmi Tempo 系列指南：`token.useHasRole` 角色查询 Hook 的使用与源码解析
wagmi Tempo 系列指南token.useHasRole角色查询 Hook 的使用与源码解析【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmitoken.useHasRole是 wagmi Tempo 模块中用于检查某个账户是否持有 TIP-20 代币特定角色的响应式 Hook适用于权限校验、管理面板按钮显隐、审批流前置判断等场景。本文以官方文档 site/tempo/hooks/token.useHasRole.md 为主体结合 wagmi 仓库中 Action 与 Hook 的源码实现、测试用例系统讲解其参数、返回值、响应式行为与底层调用链帮助你准确地在 React 应用中落地角色权限查询。一、背景TIP-20 代币的角色体系在展开 Hook 本身之前先明确它解决的问题。TIP-20 是 Tempo 网络上的代币标准对应文档中的 TIP-20 token其代币合约内建了一套基于角色的权限模型用来控制谁能执行铸造、销毁、暂停等管理操作。token.hasRole系列 API 就是这套权限模型的只读查询入口——它不做任何状态变更只回答一个问题这个地址是否拥有这个角色从 packages/core/src/tempo/actions/token.ts 与官方文档的参数定义看当前 TIP-20 代币支持以下五种角色角色值语义从角色命名与代币管理功能推断defaultAdmin默认管理员拥有最高管理权限通常由代币创建者持有pause可暂停代币转账/操作unpause可解除暂停状态issuer可铸造发行新代币burnBlocked用于标识被禁止销毁的场景或账户token.useHasRole就是针对issuer这类角色的查询 Hook。在真实业务中典型场景包括只有issuer角色才能显示铸造按钮、只有defaultAdmin才能进入合约管理页面等。二、Hook 用法一个最小可运行示例原文档给出的用法非常简洁核心调用只有一次 Hook 调用。下面按原文档结构完整展开import { Hooks } from wagmi/tempo const { data: hasRole } Hooks.token.useHasRole({ account: 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEbb, role: issuer, token: 0x20c0000000000000000000000000000000000011, }) console.log(Has issuer role:, hasRole) // log: Has issuer role: true在组件中使用时配合 TanStack Query 的isLoading/data字段即可完成权限驱动的 UI 渲染import { Hooks } from wagmi/tempo function App() { const { data, isLoading } Hooks.token.useHasRole({ account: 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEbb, role: issuer, token: 0x20c0000000000000000000000000000000000011, }) if (isLoading) return divLoading.../div return divHas Role: {data ? Yes : No}/div }使用该 Hook 前需要通过createConfig创建包含 Tempo 链与tempoWallet连接器的配置并把它挂载到应用的WagmiProvider上。仓库中官方配置示例见 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链否则查询会因链不匹配而失败tempoWallet()是 Tempo 网络的钱包连接器useHasRole依赖其提供的客户端与账户上下文传入的account可以是任意地址不要求当前已连接钱包——因为hasRole是纯只读链上查询。三、参数详解token.useHasRole的参数分两部分业务参数透传给底层 Action与query 参数控制 TanStack Query 行为。业务参数参数类型必填说明accountAddress是要检查是否持有角色的地址即谁拥有该角色roledefaultAdmin \| pause \| unpause \| issuer \| burnBlocked是要检查的角色必须是上述五种枚举值之一tokenAddress \| bigint是TIP-20 代币的地址或 ID即在哪个代币上检查补充细节account与token均来自 viem 的Address类型0x开头的 20 字节十六进制地址token同时接受bigint说明 TIP-20 代币在 Tempo 网络中既可以通过合约地址、也可以通过代币 ID 定位五个角色值均为字面量联合类型TypeScript 会在编译期拦截拼写错误写role: Issuer这类大小写错误的写法会直接报类型错误参数类型定义位于 packages/core/src/tempo/actions/token.ts 中的hasRole.Parameters并叠加了ChainIdParameter可选chainId与 Hook 层追加的ConfigParameter。query 参数原文档明确说明query 相关参数遵循 TanStack Query v5 的useQuery约定可参考 TanStack Query 官方useQuery参考文档。常用选项包括enabled是否自动发起查询select对返回的boolean做二次转换例如映射为可铸造 | 不可铸造等业务文案staleTime/refetchInterval控制缓存新鲜度与轮询刷新适合角色被动态授予/撤销的场景。这些参数与业务参数同时传入 HookHooks.token.useHasRole({ account, role: issuer, token, query: { enabled: isConnected, staleTime: 30_000, }, })四、返回值详解useHasRole的返回值是 TanStack Query 的查询结果对象核心字段如下字段类型说明databoolean \| undefined账户是否持有该角色查询未完成时为undefinedisLoading/isPendingboolean首次加载中isFetchingboolean是否正在请求含后台刷新isSuccessboolean查询是否成功完成isError/errorboolean/Error查询失败状态与错误对象refetchfunction手动重新查询其中data的语义对应底层 Action 的返回值——boolean表示账户是否拥有该角色。这一点在 packages/core/src/tempo/actions/token.ts 的类型定义中得到印证export type ReturnValue Actions.token.hasRole.ReturnValue而在官方 Action 文档 site/tempo/actions/token.hasRole.md 中返回类型被明确为type ReturnType boolean // Whether the account has the role五、源码解析Hook 到底做了什么把官方文档与仓库源码对照可以还原useHasRole的完整调用链Hook → queryOptions → Action → viem Action → Tempo 节点。1. Hook 层React 响应式入口实现位于 packages/react/src/tempo/hooks/token.tsexport function useHasRoleconfig, selectData( parameters: useHasRole.Parametersconfig, selectData, ): useHasRole.ReturnValueselectData { const config useConfig(parameters) const chainId useChainId({ config }) const options Actions.token.hasRole.queryOptions(config, { ...parameters, chainId: parameters.chainId ?? chainId, } as never) return useQuery(options) as never }关键行为useConfig从 React 上下文取得 wagmi 配置useChainId取得当前激活链 ID业务代码未显式传chainId时自动使用当前链最终委托给 TanStack Query 的useQuery因此 Hook 天然具备缓存、去重、重试、窗口聚焦刷新等能力。2. queryOptions 层查询配置组装同一 Action 模块内定义了queryOptionspackages/core/src/tempo/actions/token.tsexport function queryOptions(config, parameters) { const { query, ...rest } parameters return { ...query, enabled: Boolean( rest.token rest.role rest.account (query?.enabled ?? true), ), queryKey: queryKey(rest), async queryFn(context) { const [, parameters] context.queryKey return await hasRole(config, parameters) }, } }值得注意的细节自动禁用enabled只要token、role、account三者任一为空查询就会自动处于禁用状态不会发起无意义的链上请求。这一点在测试用例 packages/react/src/tempo/hooks/token.test.ts 中得到了验证——当account为undefined时fetchStatus保持idledata为undefinedqueryKey 稳定queryKey 由[hasRole, parameters]构成见hasRole.queryKey意味着参数不变时查询结果会被缓存复用多次渲染不会重复请求queryFn 从 queryKey 反解参数查询函数直接从context.queryKey中取出参数再调用底层 Action保证请求与缓存键严格一致。3. Action 层wagmi 核心动作packages/core/src/tempo/actions/token.ts 中的hasRole实现非常轻量export function hasRoleconfig extends Config( config: config, parameters: hasRole.Parametersconfig, ): PromisehasRole.ReturnValue { const { chainId, ...rest } parameters const client config.getClient({ chainId }) return Actions.token.hasRole(client, rest) }config.getClient({ chainId })负责从 wagmi 配置中解析出对应链的 viem Clienttransport、链信息、账户环境均在此注入随后直接转发给 viem 的Actions.token.hasRole。也就是说真正的 RPC 读取逻辑由 viem 的 tempo 模块完成wagmi 层只负责配置解析与框架适配。六、与Actions.token.hasRole的配合使用useHasRole是响应式版本其底层是命令式版本Actions.token.hasRole。两者参数与返回语义完全一致区别仅在于调用方式import { Actions } from wagmi/tempo import { config } from ./config const hasRole await Actions.token.hasRole(config, { account: 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEbb, role: issuer, token: 0x20c0000000000000000000000000000000000011, }) console.log(Has issuer role:, hasRole) // log: Has issuer role: true完整示例见 site/tempo/actions/token.hasRole.md。使用建议UI 层优先使用useHasRole自动跟随链切换、参数变化响应式重查、结果自动缓存事件回调 / 一次性逻辑如点击按钮后校验一次使用Actions.token.hasRole直接await拿到boolean不引入查询状态两者共用同一套参数类型与queryKey从 Hook 迁移到 Action 无需修改业务参数结构。七、测试与验证仓库如何保证正确性wagmi 仓库为useHasRole提供了详尽的测试覆盖位于 packages/react/src/tempo/hooks/token.test.ts主要包括两类默认查询连接钱包后通过useCreateSync创建代币创建者自动成为defaultAdmin再调用useHasRole({ account, token, role: defaultAdmin })等待isSuccess后断言data true响应式行为先以account: undefined渲染断言查询处于禁用状态data为undefined、isPending为true随后传入真实account重新渲染验证查询被自动启用并返回正确结果。这两个用例分别验证了查询结果正确性与参数缺失时自动禁用、参数补齐后自动恢复的响应式契约——正是第四节提到的enabled逻辑在实际运行时的表现。八、常见问题与注意事项data为undefined而非false查询尚未完成或处于禁用状态时data是undefined请用isLoading/isPending区分加载中与确实没有角色避免把加载态误渲染为无权限角色名区分大小写role是字面量联合类型仅接受defaultAdmin、pause、unpause、issuer、burnBlocked五种小写写法查询自动禁用account、token、role任一缺失时不会发请求若希望强制查询请先确保三个参数均有值角色可能动态变化若角色的授予/撤销发生在查询之后可通过query.refetchInterval轮询或手动refetch刷新结果只读操作无 Gas 消耗hasRole是视图查询只读 RPC 调用不产生交易、不需要签名钱包未连接也可对任意地址执行查询。总结token.useHasRole是 wagmi Tempo 权限体系中查询角色的标准答案对外提供声明式、响应式的 Hook 接口内部则由queryOptions → hasRole Action → viem三级调用链完成配置注入与链上只读查询。理解其参数语义account/role/token、返回语义boolean以及参数缺失自动禁用的响应式契约即可在管理后台、铸造入口等场景中安全、高效地实现基于 TIP-20 角色的权限控制。相关源码与测试可继续查阅 packages/core/src/tempo/actions/token.ts、packages/react/src/tempo/hooks/token.ts 与 packages/react/src/tempo/hooks/token.test.ts。【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考