# Getting Started With Hats Protocol: A Walkthrough Guide

<img src="https://hackmd.io/_uploads/SyR9M0QH3.jpg" height="40%" width="40%"/>

Hats Protocol is a platform for programmatically creating, delegating, and managing DAO contributor roles, responsibilities, and permissions.

Following is a brief walkthrough guide to deploy your first Hats, to be used in conjunction with the [Hats tree creation spreadsheet](https://docs.google.com/spreadsheets/d/1Db1r-fWZ5V_7qe7Bd0_6MYjfRWlefEwzXen8Pux04-Y/edit?usp=sharing), the [Sobol Hats Tree Composer](https://sobol.io/d/labs/hats_composer), and/or the [Hats Protocol front-end app](app.hatsprotocol.xyz).

## What is Hats Protocol?
Hats Protocol enables the creation of flexible operational and governance structures that are controlled by a DAO or its designees.

Hats are organizational roles represented onchain by tokens that conform to the ERC-1155 standard. They are connected together in a tree structure (aka a "Hats tree") that can be visualized in any Hats front-end, including the [first front-end](app.hatsprotocol.xyz/) developed by the Hats Protocol team, as well as composable front-ends like [Sobol](sobol.io/) and (coming soon) [Nestr](https://nestr.io/).

Hats tokens can be held by any address including an EOA, multisig, or contract. When an address has a balance of 1 of a given Hat token, it is considered a "wearer" of that Hat. Then, by way of various token-gates, that address is granted the authorities that have been associated with that Hat by the DAO.

Each Hat can have any number of wearers up to the Hat’s max supply. Hats are granted and revoked by the DAO, or agents/smart contracts that are designated by the DAO. Wearers can renounce a Hat, but they cannot transfer it.

### DAOs that use Hats will:
- Delegate authorities to individuals or groups while retaining ultimate control by the collective
- Experience less pain and administrative costs associated with managing contributors and transferring authorities from one person or team to another
- Effectively hold contributors accountable to their commitments
- Clearly understand what’s *actually* happening across the DAO at any point in time, including where any gaps exist

### Contributors who wear Hats will:
- Feel clear about the roles and responsibilities they are accountable for
- Instantly have all the authorities they need to do their work (e.g., discord role, wiki admin rights, multisig signer, twitter access, etc.)
- Know who to go to for important information or decisions
- Understand which roles are not yet fulfilled that they could be eligible for


## Step 1: Defining Your DAO's Hats
Hats are roles, and roles are rich objects that compose a lot of things together, including: responsibilities, authorities, and accountabilities. Consider all the Hats you may want to represent onchain, and list them in the "Hats (Roles)" tab in the [Hats tree creation spreadsheet](https://docs.google.com/spreadsheets/d/1Db1r-fWZ5V_7qe7Bd0_6MYjfRWlefEwzXen8Pux04-Y/edit?usp=sharing).

Hats can represent roles at different levels of granularity. It can be helpful to start broad and get increasingly granular, listing each Hat as you go.

**The DAO:** The broadest authority of your Hats tree is represented by the Top Hat. This is the first Hat you will create; you can think of it as the superadmin of the entire Hats tree. _Top Hats should be worn by the highest-level governance surface of your DAO,_ but when you're just getting started it's usually OK to first mint the Top Hat to an address you control and then transfer the Top Hat to the DAO's address later.

**Group Roles:** Next, consider the roles held by groups, such as Councils, Workstreams, Guilds, and other organizational units. Any address can wear a Hat, so multisigs and pods can and often should be represented by Hats as well.

**Individual Roles:** What roles exist in your DAO that will be held by individual people? Roles can be broad and held by many people, as in a Community Member Hat or Guild Member Hat, or narrow and specific, as in a Workstream Facilitator Hat or Recognized Delegate Hat. Roles may also be ongoing, or bound to a specific project or deliverable.

**Discrete Authorities:** Consider any granular authorities that should be represented by a Hat to enable capture-resistant delegation and revocation of specific credentials. See the "Hat Authorities" section below for examples of the types of authorities that can be enabled by Hats.

**Claimable Hats:** By default, Hats are only delegated, revoked, and renounced, but not claimed. However, it is possible to make designated Hats claimable by adding a [ClaimsHatter Contract](https://github.com/Hats-Protocol/claims-hatter) Hat and making it an admin of any Hats you want to be claimable. If you think you'll want some of your Hats to be claimable, add a ClaimsHatter Contract Hat to your list.

Your Hats tree is meant to evolve with your DAO, so don't feel pressure to get it perfect from the start. For example, roles can continue to be added, removed, and changed over time (as long as they are *mutable* — see Step 4 for more on Hat mutability). The wearers of a given Hat may change over time as well, as a given Hat can be worn first by a single individual and later transferred to a group (via a multisig), or vice versa.

## Step 2: Identifying Hat Authorities
List the authorities you want to associate with your Hats in the "Hat Authorities" tab in the [Hats tree creation spreadsheet](https://docs.google.com/spreadsheets/d/1Db1r-fWZ5V_7qe7Bd0_6MYjfRWlefEwzXen8Pux04-Y/edit?usp=sharing). Authorities can include hard powers, such as explicit onchain or offchain permissions provided through token gates (see below), as well as soft powers provided through social agreements and other accountability mechanisms, such as the authority to facilitate a meeting, work on projects in a given domain, or hold admin rights for a specific app that can't yet be token-gated.

Because Hats are ERC-1155 tokens, they can be plugged into token gates to grant the wearers of that Hat specific authorities, as long as 1) the wearer's address is still eligible to wear the hat, and 2) the hat is still active. You'll attach these authorities to your Hats via token-gates in Step #6 after your Hats are deployed onchain.

Authorities can be linked to Hats in a number of ways, including via:
- **Token-gating platforms** including [Guild](https://guild.xyz/), [Collab.land](https://www.collab.land/), and [Lit Protocol](https://litprotocol.com/), which provide token-gating for apps like Discord, Telegram, Github, Google Workspace, and more.
- **Apps that integrate token-gating** to provide access to specific channels and read/write permissions, including [Charmverse](https://www.charmverse.io/), [Wonderverse](https://www.wonderverse.xyz/), [Coordinape](https://coordinape.com/) and [Commonwealth](https://commonwealth.im/)
- **Tools that read ERC1155s for modifying parameters**, such as using [Snapshot Strategies](https://snapshot.org/) to allow only certain Hats to vote in Snapshot proposals and/or give certain Hats greater voting weight in Snapshot proposals
- **[HatsSignerGate](https://github.com/Hats-Protocol/hats-zodiac), a Zodiac module that provides Safe multisig signing authority for a given set of Hats** (note: for security reasons, HatsSignerGate cannot be used in conjunction with any other Zodiac modules)
- **Social agreements or other accountability mechanisms**, including seasonal elections, staking requirements, and/or reputation systems. Authorities that can't be explicitly granted to a Hat via token-gating can still be granted to a Hat wearer by using the Hat as a signal of social agreement that the wearer has that authority.

## Step 3: Creating Your Hats Tree
After identifying an initial set of Hats for your DAO (don't worry, you can always add additional Hats or authorities later), your next step is to define the relationships between them. This creates your Hats tree, turning a set of individual roles into a coherent and purposeful structure.

To create your DAO's Hats tree, use the "Hats Tree" tab in the [Hats tree creation spreadsheet](https://docs.google.com/spreadsheets/d/1Db1r-fWZ5V_7qe7Bd0_6MYjfRWlefEwzXen8Pux04-Y/edit?usp=sharing).

### Defining Accountabilities

In Hats Protocol, the powers that are often bundled together in an admin role are decoupled into three distinct parts to enable greater flexibility. They are:
- **Admins:** specific Hats that can change a given Hat's details, image, max supply, eligibilty address, and toggle address — as long as that Hat is mutable (immutable Hats cannot be changed once deployed). Admin hats can also mint both mutable and immutable Hats to new wearers, and transfer mutable Hats from one address to another.
- **Eligibility:** an address that determines who can wear a given Hat, or whether a wearer should have their Hat revoked (this can be an agent or self-enforcing logic).
- **Toggle:** an address that determines whether and when a given Hat should continue to exist (this can be an agent or self-enforcing logic).

Each can be used in creative ways to cultivate a web of accountabilities across your DAO that ensures that people actually follow through on the responsibilities they're committing to by wearing a given Hat.

Admins, Eligibility, and Toggle are explained in more detail below.

### Admins

Start by setting the Admins for each Hat by connecting your Hats together in a tree structure, using Column D of the "Hats Tree" tab in the [Hats tree creation spreadsheet](https://docs.google.com/spreadsheets/d/1Db1r-fWZ5V_7qe7Bd0_6MYjfRWlefEwzXen8Pux04-Y/edit?usp=sharing).

In general, we recommend that the DAO's highest-level governance surface wear the Top Hat, Group Roles wear Level 1 Hats (just below the Top Hat), and Individual Role Hats and Discrete Authority Hats are located at the lower-levels of the tree*.

Note that each Hat is an admin of all other Hats linked directly below it, as seen in the diagram below:

**one exception to this guideline is if you want to establish a temporary Hats admin role just beneath the Top Hat, to enable an individual EOA to set up and manage the Hats tree for a period of time before that Hat is later transferred or deactivated.*

### Eligibility: Wearing & Revocation
A Hat’s eligibility module is an address that determines which addresses are eligible to wear that Hat, and can revoke the Hat if the wearer is no longer eligible. Eligibility modules can be humanistic (as in an EOA or multisig) or mechanistic (as in a contract with custom logic) to automaticaly and instantly revoke the hat based on pre-defined triggers.

Eligibility modules can also be combined with a ClaimsHatter Contract Hat to enable addresses to claim and wear a given hat *only if* they fulfill specific eligibility criteria.

**Eligibility criteria you may use to determine which addresses are and are not eligible to wear a given hat include:**
- **Assets** such as tokens, badges, and/or POAPs held by a given wallet address
- **Staking** requirements that specify an address must stake a minimum amount of a given token
- **Active subscription**, verifying whether or not an address is paying an ongoing fee (e.g., using Unlock Protocol)
- **Election results** specifying only the top N vote-getters of an election are eligible to wear a designated Hat
- **Delegated tokens or votes** that reach and/or stay above a given threshold
- **Contributions and attestations** such as those represented by Govrn contributions, Quests NFTs, or EAS attestations
- **Humanistic eligibility** based on specified criteria (e.g., an arbitration council or stewardship council rules on Hat eligibility according to predetermined rules)
- Any custom logic you can imagine that can be represented onchain

### Toggle: Activation & Deactivation
A Hat’s toggle module is an address that determines whether the hat is active or inactive for all wearers, which can also be humanistic or mechanistic.

**Toggle triggers you may use to determine whether or not a hat is active include:**
- **Seasonal or time-specific toggle** that automatically deactivates a Hat at the end of a given season or period of time
- **Circuit-breaker toggle** to safeguard the DAO's assets and deactivate a set of Hats and their associated authorities if certain conditions are met
- Any custom logic you can imagine that can be represented onchain

### Unsure of Where to Start?

If you're not sure what a particular Hat's eligibility or toggle modules should be at this point, consider: "who or what should this role be accountable to?"

For instance, it makes good sense to set the eligibility and toggle modules for the Product Workstream Facilitator Hat to the Product Workstream's multisig address. And, it makes sense to set the eligibility and toggle modules for the Product Workstream Hat to the DAO's contract address.

For any Hats you're still not sure about, we recommend setting their eligiblity and toggle modules to the DAO's contract address, at least to start. If the Hats in question are mutable, their admins can always change their eligibility and toggle modules later.

For more details on Hat Eligibility and Toggle Modules, see the [Hats Protocol docs](https://docs.hatsprotocol.xyz/#eligibility).

## Step 4: Setting Hat Properties

### Max Supply
Max supply is the maximum number of addresses that can wear a given Hat at once. Max supply could be set to 1 to ensure only one address is holding that role at a given time, or it could be set as high as 4.29 billion (2^32). Max supply can be changed by a Hat's admins, unless the Hat is immutable.

### Mutability
Mutability determines whether the Hat's properties (including name, description, max supply, mutability, image, and eligibility and toggle modules) can be changed by its admins. Immutable Hats cannot be made mutable later, so we generally recommend starting with mutable Hats, with the option to make them immutable later once your organization's structure soldifies and there is a need to limit the powers of a Hat's admins.

### Image
Like any other NFT, Hats have images. You can set a specific image for each Hat using an image URI (e.g., an ipfs hash or a link to an image stored on a website), or uploading the image directly into the [Hats Protocol App](app.hatsprotocol.xyz).

If no image is set for a Hat, it will adopt the image of its nearest admin.


## Step 5: Deploying Your Hats Onchain
Once you've created your Hats tree and specified the details for each Hat, it's time to deploy your Hats onchain, using the details specified in the "Full Tree Details" tab of the [Hats tree creation spreadsheet](https://docs.google.com/spreadsheets/d/1Db1r-fWZ5V_7qe7Bd0_6MYjfRWlefEwzXen8Pux04-Y/edit?usp=sharing). Hats Protocol is currently deployed to Ethereum mainnet, Optimism, Arbitrum, Polygon, Gnosis, and Goerli testnet.

To deploy your Hats one by one, use the [Hats app](app.hatsprotocol.xyz), which will allow you to upload a custom image for each Hat without pinning them to IPFS yourself.

Alternatively, to deploy your full Hats tree all at once, we recommend using the [Sobol Hats Tree Composer](https://sobol.io/d/labs/hats_composer). Start by creating a new Top Hat, or adding your tree to an existing Top Hat. You'll need to specify an address to mint the Top Hat to, but you won't need to identify wearers for any of the remaining Hats until Step 7. Then, continue adding new Hats and entering Hat details. Once you're satisfied with your tree, click "Deploy" and your tree will be deployed onchain. Once deployed onchain via the Sobol Hats Tree Composer, click the three dots in the upper-right of the Composer window (shown below) to view your tree in the [Hats Protocol app](app.hatsprotocol.xyz).


In the [Hats Protocol app](app.hatsprotocol.xyz) you will be able to manage your Hats tree, see the Hats you are wearing, make changes to Hats for which you are an admin, and revoke or deactivate Hats if you control their eligibility or toggle modules, respectively.

See [this 4m demo video](https://www.loom.com/share/4ee26c4a3dad469796f2e576b663a5c7) for an overview of how to use the Hats app.

## Step 6: Connecting Authorities to Hats
Hats are the tokens that give wearers access to token-gated permissions. Plugging a Hat's token ID into a token gate will give all wearers of that Hat access to the specified credential, as long as the wearer remains eligible to wear that Hat and the Hat remains active. See the "Identifying Hat Authorities" section above for examples of token-gated applications (like Charmverse) and token-gating platforms (like Guild.xyz and Collab.land) that you can plug your Hats into to give their wearers special permissions.

To connect a Hat to a token-gate, locate the token-gating permissions for the platform or application you wish to use. In many cases, the process requires that you create a specific role in the platform that has special permissions associated with that role, and then add a specific requirement necessary for a user to hold that role (e.g., holding a particular Hat token).

At guild.xyz, for example, which provides token-gating for Discord, Telegram, Github, and Google Workspace, you will create a role within your Guild, provide that Guild role with specific "rewards" (aka permissions), and then add a requirement that an address must have possession of a particular NFT to hold that Guild role.

<img src="https://hackmd.io/_uploads/BkTwIJXBn.png" height="40%" width="40%" /> <img src="https://hackmd.io/_uploads/By7qBkXHn.png" height="40%" width="40%" />

To connect a Hat to a token-gate, first add an NFT requirement. Then, you'll need to enter two details:
1. The Hats Protocol contract address for the chain you're using (see below), and
2. The Token ID (sometimes called a Custom ID) for the appropriate Hat

See below for these details.

### Hats Protocol Contract Addresses

**Ethereum (mainnet):** [0x9d2dfd6066d5935267291718e8aa16c8ab729e9d](https://etherscan.io/address/0x9d2dfd6066d5935267291718e8aa16c8ab729e9d)
**Arbitrum:** [0x9d2dfd6066d5935267291718e8aa16c8ab729e9d](https://arbiscan.io/address/0x9d2dfd6066d5935267291718e8aa16c8ab729e9d)
**Gnosis Chain:** [0x9d2dfd6066d5935267291718e8aa16c8ab729e9d](https://gnosisscan.io/address/0x9d2dfd6066d5935267291718e8aa16c8ab729e9d)
**Optimism:** [0x9d2dfd6066d5935267291718e8aa16c8ab729e9d](https://optimistic.etherscan.io/address/0x9d2dfd6066d5935267291718e8aa16c8ab729e9d)
**Polygon:** [0x9d2dfd6066d5935267291718e8aa16c8ab729e9d](https://polygonscan.com/address/0x9d2dfd6066d5935267291718e8aa16c8ab729e9d)
**Goerli (testnet):** [0x9d2dfd6066d5935267291718e8aa16c8ab729e9d](https://goerli.etherscan.io/address/0x9d2dfd6066d5935267291718e8aa16c8ab729e9d)
**Sepolia (testnet):** [0x9d2dfd6066d5935267291718e8aa16c8ab729e9d](https://sepolia.etherscan.io/address/0x9d2dfd6066d5935267291718e8aa16c8ab729e9d) *(note: Sepolia is not currently supported in the Hats app)*

### Finding a Hat's Token ID

To find a Hat's token ID, locate and select that Hat in the [Hats app](app.hatsprotocol.xyz) and click the copy icon right right of the Hat's "pretty ID".


Contact us at connect [at] hatsprotocol [dot] xyz if you have any issues connecting your Hats to token-gates.

## Step 7: Adding Wearers
[[via the Hats App; incorporate batchminting with v1.2]]
Once your Hats are connected to the appropriate token-gates, you are ready for the last step: adding wearers!

To add new wearers for a specific Hat, locate and select the Hat in the [Hats app](app.hatsprotocol.xyz), click the "Wearers" tab, and select "Mint to New Wearer". Then, add an address that is controlled by the intended wearer (note: ensure the address is on the same chain as your Hats tree), and select "Mint".

All the wearers of that Hat are shown in the Wearers tab.

To add multiple wearers with one transaction, use the Hats Protocol contracts linked above (batch minting functionality is coming to the Hats app soon).


Once wearers are added, your Hats tree is complete! Now any wearer can use the [Hats app](app.hatsprotocol.xyz) to view the Hats they're wearing, see the associated responsibilities and authorities they hold, renounce their Hat, create new child Hats, and make changes to any Hats they are an admin of.

Happy hatting! 🧢

## More Information
To learn more about Hats Protocol, check out the following links:
**Website:** [hatsprotocol.xyz](http://hatsprotocol.xyz)
**Open-source repo:** github.com/hats-protocol/hats-protocol
**Documentation:** [docs.hatsprotocol.xyz](http://docs.hatsprotocol.xyz)
**First front-end:** [app.hatsprotocol.xyz](http://app.hatsprotocol.xyz)
**Demo video (4min):** loom.com/share/4ee26c4a3dad469796f2e576b663a5c7
**Philosophy:** [Structure Without Capture](https://hats.mirror.xyz/sZjE4zm3jwV9pwUoiqkfbQzabTlWYcdTQqN46iiLkyw)
**Support:** Email us at connect [at] hatsprotocol [dot] xyz

>Page last edited: 2023-05-23