Hats Protocol v1

This is a pre-release for Hats Protocol.

Hats Protocol v1 is a fully permissionless and immutable contract, with no upgradeability, adjustable parameters, or owner of any kind.

What's New

This version fixes a number of bugs and vulnerabilities surfaced in two audits: a private audit by Trust Security, and a Sherlock auditing contest.

New Features

• Linked top hats can now have Eligibility and Toggle modules — #113

Bug Fixes, Vulnerability Patches, and Smaller Changes

• Fix bug where hats created before their admin (ie skip-level hats) could be overwritten if/when their admin is later created — #109
• Prevent hats from being created with null levels, eg with hatId 0x00000001.0000.0002... — #108
• Prevent unlinked top hats from being "stolen" by admins in their previous parent tree — #113
• Prevent middle admins from "stealing" linked top hats via a relinking attack — #113
• Hat minting and transferring is now restricted to active hats and eligible recipients who do not already wear (or even have a static balance* of) the hat — #96 (also applies to the following 5 items) and #107
• Wearers with a static balance of a given hat can now renounce it via renounceHat()
• Fix an issue with imageURI fallback logic
• Eligibility and Toggle modules must not be set to the zero address (with an exception is for top hats)
• More robust validation of data returned from IHatsEligibility.getWearerStatus() and IHatsToggle.getHatStatus()
• isAdminOfHat() is now more gas efficient
• balanceOfBatch() is now supported for hats #118
• buildHatId() now correctly prevents callers from building hats after level 14 — #106
• Current hat status is now stored prior to changing a Toggle module — #116
• details and imageURI strings are now capped at 7000 characters to prevent a minor DOS vector — #114

*Note: "static balance" refers to the scenario where balanceOf() for a given wearer returns 0 but the hat token has not yet been fully burned.

Deployments

Network	Address
Goerli (testnet)	0x850f3384829D7bab6224D141AFeD9A559d745E3D
Sepolia (testnet)	0x850f3384829D7bab6224D141AFeD9A559d745E3D
Ethereum (mainnet)	0x850f3384829D7bab6224D141AFeD9A559d745E3D
Polygon	0x850f3384829D7bab6224D141AFeD9A559d745E3D
Gnosis Chain	0x850f3384829D7bab6224D141AFeD9A559d745E3D
Arbitrum	0x850f3384829D7bab6224D141AFeD9A559d745E3D
Optimism	0x850f3384829D7bab6224D141AFeD9A559d745E3D

All deployments are made to the same address using a CREATE2 factory, with the following parameters (also viewable in the DeployHats script):

• salt: 0x0000000000000000000000000000000000000000000000000000000000004a75
• name: "Hats Protocol v1"
• baseImageURI: "ipfs://bafybeigcimbqwfajsnhoq7fqnbdllz7kye7cpdy3adj2sob3wku2llu5bi"

Along with the deployments, top hat 0x0000001 was minted on each network to hatsprotocol.eth. This top hat has no authorities connected to the protocol.

Hats Protocol v1.0 (Deprecated)

This release has been deprecated. See Hats Protocol v1 for the latest release

What's New

This release addresses a minor issue found by a community member (see below for more details). While the issue does not impact regular usage of the protocol, after consulting community members and auditors, we have decided that the best course of action is to deploy a fix while protocol usage is still getting started. The newly deployed contract is versioned 1.0 to reflect the pre-launch nature of the change.

Hats Protocol has been audited twice, once by a top independent auditor on the Code4rena leaderboards, and again by a total of 152 auditors via an open contest on Sherlock (report available soon). We care deeply about security and are committed to strong audit practices and incentivizing the disclosure of vulnerabilities at the protocol level, and communicating this proactively to our community.

The Fixed Issue

Under some edge conditions, it was technically possible to unlink a linked (aka "grafted") top hat in such a way that it would have no wearer once unlinked. This would render the top hat non-operational.

Specifically, if a linked top hat had been configured with an eligibility and/or toggle module when linked, and the top hat had subsequently been revoked from its wearer (eligibility) or set to inactive (toggle), unlinking would have resulted in the newly-unlinked top hat not having a wearer and no way to gain one. This could also have occurred if the linked top hat's wearer renounced it. This could be relatively easily avoided by ensuring the top hat had an eligible wearer before unlinking, but the protocol did not explicitly protect against the failure to do so.

Version 1.0 explicitly prevents such mistakes by reverting the unlink function if the top hat does not have a wearer, ensuring that unlinked top hats will always be operational.

A big hat tip to @gershido, who found, reported, and helped review the fix for this issue!

New Features

Several convenience view functions have also been added:

• getHatEligibilityModule()
• getHatToggleModule()
• getHatMaxSupply()

Other Notes

• If you have already created hats on the original contract, please reach out and we'll assist you in recreating them on the new contract.
• v1.hatsprotocol.eth has been updated to point to the new v1.0 contract address.

Deployments

Network	Address
Goerli (testnet)	0x9d2dfd6066d5935267291718e8aa16c8ab729e9d
Sepolia (testnet)	0x9d2dfd6066d5935267291718e8aa16c8ab729e9d
Ethereum (mainnet)	0x9d2dfd6066d5935267291718e8aa16c8ab729e9d
Polygon	0x9d2dfd6066d5935267291718e8aa16c8ab729e9d
Gnosis Chain	0x9d2dfd6066d5935267291718e8aa16c8ab729e9d
Arbitrum	0x9d2dfd6066d5935267291718e8aa16c8ab729e9d
Optimism	0x9d2dfd6066d5935267291718e8aa16c8ab729e9d

All deployments are made to the same address using a CREATE2 factory, with the following parameters (also viewable in the DeployHats script):

• salt: 0x0000000000000000000000000000000000000000000000000000000000004a75
• name: "Hats Protocol v1.0"
• baseImageURI: "ipfs://bafybeigcimbqwfajsnhoq7fqnbdllz7kye7cpdy3adj2sob3wku2llu5bi"

Hats Protocol v1

This is the stable v1 release for Hats Protocol!

Hats Protocol v1 is a fully permissionless and immutable contract, with no upgradeability, adjustable parameters, or owner of any kind.

What's New

This newest release of Hats Protocol adds a single change: it inherits from Multicallable.sol to enable EOAs to batch multiple calls to Hats.sol into a single transaction.

This unlocks a number of new possibilities for apps to create better experiences for users, such as easier hat tree creation, forking other trees and templates, maturing a tree from testnet to mainnet, and making bulk edits to an existing tree.

No other changes have been made to the protocol. The ABI and IHats interface are otherwise exactly the same.

Other Notes

• v1.hatsprotocol.eth has been updated to point to the new v1 contract address (see below).

Deployments

Network	Address
Goerli (testnet)	0x3bc1A0Ad72417f2d411118085256fC53CBdDd137
Sepolia (testnet)	0x3bc1A0Ad72417f2d411118085256fC53CBdDd137
Holesky (testnet)	0x3bc1A0Ad72417f2d411118085256fC53CBdDd137
Ethereum (mainnet)	0x3bc1A0Ad72417f2d411118085256fC53CBdDd137
PGN	0x3bc1A0Ad72417f2d411118085256fC53CBdDd137
Polygon	0x3bc1A0Ad72417f2d411118085256fC53CBdDd137
Gnosis Chain	0x3bc1A0Ad72417f2d411118085256fC53CBdDd137
Arbitrum	0x3bc1A0Ad72417f2d411118085256fC53CBdDd137
Optimism	0x3bc1A0Ad72417f2d411118085256fC53CBdDd137
Scroll	0x3bc1A0Ad72417f2d411118085256fC53CBdDd137
Celo	0x3bc1A0Ad72417f2d411118085256fC53CBdDd137
Base	0x3bc1A0Ad72417f2d411118085256fC53CBdDd137

All deployments are made to the same address using a CREATE2 factory, with the following parameters (also viewable in the DeployHats script):

• salt: 0x0000000000000000000000000000000000000000000000000000000000004a75
• name: "Hats Protocol v1"
• baseImageURI: "ipfs://bafkreiflezpk3kjz6zsv23pbvowtatnd5hmqfkdro33x5mh2azlhne3ah4"

Hats Protocol v1-beta.1

What's New

• Hat trees can now be linked ("grafted") onto other trees — #79 and #85
• Wider hat trees: there are now 14 levels below the tophat, with up to 2^16 = 65,536 child hats per hat — #78
• Gas optimizations, in particular for mintHat — #84
• New event emitted when wearer standing changes — #81
• Prevent transfer of immutable hats — #80
• Enable tophats to change their own details and imageURI — #86
• Smart contract documentation is now auto-generated
• Bug fix: ensure transferHat recipient isn't already wearing the hat — #75 and #77

Deployments

Network	Address
Goerli	0x96bd657fcc04c71b47f896a829e5728415cbcaa1
Polygon	0x96bd657fcc04c71b47f896a829e5728415cbcaa1
Gnosis Chain	0x96bd657fcc04c71b47f896a829e5728415cbcaa1

All deployments are made to the same address using a CREATE2 factory, with the following parameters (also viewable in the DeployHats script):

• salt: 0x0000000000000000000000000000000000000000000000000000000000004a75
• name: "Hats Protocol v1-beta1"
• baseImageURI: "ipfs://bafybeigcimbqwfajsnhoq7fqnbdllz7kye7cpdy3adj2sob3wku2llu5bi"

Hats Protocol v0.6-beta

What's Changed

• Hats can now optionally be created as mutable
• Admins can change properties of mutable hats
• Removed createTopHatAndHat() and isActive() convenience functions due to contract size considerations
• Updated license to APGLv3
• Simpler imageURI tree and fallback logic

Deployments

Network	Address
Goerli	0xcf912a0193593f5cD55D81FF611c26c3ED63f924
Polygon	0x95647f88dcbc12986046fc4f49064edd11a25d38
Gnosis Chain	0x6B49b86D21aBc1D60611bD85c843a9766B5493DB