Hats Protocol's permission management centers on a role tree structure. Each "Hat" represents an on-chain role, and roles are connected in a tree-like hierarchy through "admin" relationships: the admin of an upper-level Hat can create, modify, and revoke lower-level Hats. Permissions are not stored inside the Hat itself. Instead, they are bound to specific on-chain or off-chain permissions through token gating or external integrations. The most direct way to revoke a role's permissions is for the Hat's admin to burn the Hat from the holder's address, or for the holder to no longer meet the eligibility conditions, triggering automatic revocation.
A leading global cryptocurrency platform,suitable for both beginners and experienced traders.
New user benefit: 20% off trading fees upon registration!！
Role Tree: Top-Down Management Relationships
The Hats tree starts with the "Top Hat." The Top Hat is the highest governance authority of an organization. It manages itself and is the ultimate admin of every other Hat in the tree. The first step in creating a tree is to mint the Top Hat to an address, usually first to a wallet you control and later transferred to the organization's multisig or governance contract.
Below the Top Hat, the official recommendation is to first create an Autonomous Admin role as the parent of all subsequent roles. This role can be assigned to a smart contract or automation module to handle operations like allowing certain roles to be claimed by eligible addresses. Below that are workflow or team roles (Level 2), and then individual roles and specific discrete permission roles.
The key rule of this tree structure is that the admin of a Hat is the holder of the Hat directly above it, unless that Hat is set as immutable. The admin can modify the Hat's properties, mint it to new holders, transfer it from old holders, and revoke or burn it. Holders themselves cannot transfer a Hat to someone else. Hats are non-transferable ERC1155-type tokens.
Integration: Create Roles First, Then Bind Permissions
Integrating Hats can be done in two steps. The protocol also allows you to start with a single role without drawing the entire tree from the beginning.
The first step is creating a role. In the Hats App, create a tree or a Hat and set its name, description, image, and admin relationship. When creating it, you can choose between mutable or immutable. A mutable Hat can have its properties changed later by the admin. An immutable Hat cannot be changed once created, which is suitable for scenarios where holders need maximum certainty. If you are unsure, keep it mutable and adjust later.
The second step is binding permissions to the role. Hats itself does not execute permission logic. What it does is "role verification." In your own contract or application, you check whether an address holds a specific Hat ID. If it does, you allow the corresponding action. The official description is to connect Hats to on-chain permissions such as Safe signatures or voting, or off-chain permissions such as workspace access or communication channels, through token gates and integration libraries. For developers, Hats provides an SDK and contract interfaces so you can perform RBAC checks directly in your application.
A practical design consideration: do not put all permissions into one Hat. Hats' granular design allows you to separate "workflow membership" and "treasury signing authority" into two different Hats. This way, when you revoke someone's treasury authority, you do not need to touch their membership. The finer the granularity, the more precise the revocation, but the management cost also increases. The official "What Hats Do I Need" guide follows the same layered approach.
Revocation: Manual Burn and Automatic Expiry
Revoking an address's permissions depends on the Hat's eligibility and toggle settings.
The most direct method is manual revocation by the admin. The admin, meaning the holder of the parent Hat, calls burn or removes the Hat from the holder's address. The holder cannot refuse, nor can they transfer it away themselves. This is suitable for situations requiring human judgment, such as personnel departure or role changes.
A more automated approach is to set an eligibility module. The eligibility module is an address, which can be an EOA, a multisig, or a smart contract, that determines which addresses are eligible to hold the Hat and can automatically revoke it when a holder no longer meets the conditions. Official examples of conditions include holding a specific number of ERC20 or ERC721 tokens, winning a Snapshot or Tally election, holding another role, or completing staking. For example, you can set a Hat's eligibility to "must hold at least 100 of a certain token." When the holder sells tokens and the balance falls below the requirement, the Hat is automatically revoked.
The toggle module is another layer of control. Toggle determines whether a Hat itself is active or inactive. When a Hat is toggled to inactive, all holders' balances instantly become 0, with no need to revoke them one by one. This suits scenarios where an entire role is paused, such as temporarily disbanding a workflow. Toggle can be triggered manually by an EOA or multisig calling toggleHatStatus, or automatically by a logic contract based on conditions such as timestamps.
The entry point for setting eligibility and toggle is in the Hats App under "Edit Tree" mode. Select the target Hat, open the "Revocation & Eligibility" panel, and choose "Manually" or "Automatically" to configure it.
A Boundary Worth Noting
Hats revocation is an on-chain action, but whether the bound permissions actually stop working depends on whether your integration side correctly checks the Hat status. If you cache a boolean value like "this address is an admin" in your own contract instead of querying Hats.balanceOf in real time for every operation, then even if the Hat is revoked, your contract will still allow access. Hats' automatic revocation only takes effect when the reading side actively checks. When designing integration, permission checks should query the Hat balance at every critical operation, not be hardcoded during onboarding.
Also, be careful about depth when linking multiple trees. Official documentation warns that if nesting levels are too deep, operations by a high-level admin on the lowest-level Hat may become impractical due to gas costs, or even exceed block limits. It is recommended not to attach external permissions to trees nested beyond about 10 levels.
A leading global cryptocurrency platform,suitable for both beginners and experienced traders.
New user benefit: 20% off trading fees upon registration!！
References
- Hats Protocol Docs·Getting Started with Hats, 2026-10-22
- Hats Protocol Docs·Revocation & Eligibility: Requirements for Wearers, 2026-10-22
- Hats Protocol Docs·What Hats Do I Need?, 2026-10-22
- Hats Protocol Docs·Creating My First Hat, 2026-10-22
- Hats Protocol Docs·Essentials For Hat Wearers, 2026-10-22
- Hats Protocol Docs·Linking Hats Trees, 2026-10-22
- Hats Protocol·How It Works, 2026-10-22
- GitHub·Hats-Protocol/hats-protocol (Toggle and mutability notes), 2026-10-22
