Links

Hats.sol

Hats

​Git Source​
Inherits: IHats, ERC1155, Multicallable, HatsIdUtilities
Author: Haberdasher Labs
Hats are DAO-native, revocable, and programmable roles that are represented as non-transferable ERC-1155-similar tokens for composability
This is a multi-tenant contract that can manage all hats for a given chain. While it fully implements the ERC1155 interface, it does not fully comply with the ERC1155 standard.

State Variables

name

The name of the contract, typically including the version
string public name;

lastTopHatId

The first 4 bytes of the id of the last tophat created.
uint32 public lastTopHatId;

baseImageURI

The fallback image URI for hat tokens with no imageURI specified in their branch
string public baseImageURI;

_hats

Internal mapping of hats to hat ids. See HatsIdUtilities.sol for more info on how hat ids work
mapping(uint256 => Hat) internal _hats;

badStandings

Mapping of wearers in bad standing for certain hats
Used by external contracts to trigger penalties for wearers in bad standing hatId => wearer => !standing
mapping(uint256 => mapping(address => bool)) public badStandings;

Functions

constructor

All arguments are immutable; they can only be set once during construction
constructor(string memory _name, string memory _baseImageURI);
Parameters
Name
Type
Description
_name
string
The name of this contract, typically including the version
_baseImageURI
string
The fallback image URI

mintTopHat

Creates and mints a Hat that is its own admin, i.e. a "topHat"
A topHat has no eligibility and no toggle
function mintTopHat(address _target, string calldata _details, string calldata _imageURI)
public
returns (uint256 topHatId);
Parameters
Name
Type
Description
_target
address
The address to which the newly created topHat is minted
_details
string
A description of the Hat [optional]. Should not be larger than 7000 bytes (enforced in changeHatDetails)
_imageURI
string
The image uri for this top hat and the fallback for its downstream hats [optional]. Should not be large than 7000 bytes (enforced in changeHatImageURI)
Returns
Name
Type
Description
topHatId
uint256
The id of the newly created topHat

createHat

Creates a new hat. The msg.sender must wear the _admin hat.
Initializes a new Hat struct, but does not mint any tokens.
function createHat(
uint256 _admin,
string calldata _details,
uint32 _maxSupply,
address _eligibility,
address _toggle,
bool _mutable,
string calldata _imageURI
) public returns (uint256 newHatId);
Parameters
Name
Type
Description
_admin
uint256
The id of the Hat that will control who wears the newly created hat
_details
string
A description of the Hat. Should not be larger than 7000 bytes (enforced in changeHatDetails)
_maxSupply
uint32
The total instances of the Hat that can be worn at once
_eligibility
address
The address that can report on the Hat wearer's status
_toggle
address
The address that can deactivate the Hat
_mutable
bool
Whether the hat's properties are changeable after creation
_imageURI
string
The image uri for this hat and the fallback for its downstream hats [optional]. Should not be larger than 7000 bytes (enforced in changeHatImageURI)
Returns
Name
Type
Description
newHatId
uint256
The id of the newly created Hat

batchCreateHats

Creates new hats in batch. The msg.sender must be an admin of each hat.
This is a convenience function that loops through the arrays and calls createHat.
function batchCreateHats(
uint256[] calldata _admins,
string[] calldata _details,
uint32[] calldata _maxSupplies,
address[] memory _eligibilityModules,
address[] memory _toggleModules,
bool[] calldata _mutables,
string[] calldata _imageURIs
) public returns (bool success);
Parameters
Name
Type
Description
_admins
uint256[]
Array of ids of admins for each hat to create
_details
string[]
Array of details for each hat to create
_maxSupplies
uint32[]
Array of supply caps for each hat to create
_eligibilityModules
address[]
Array of eligibility module addresses for each hat to create
_toggleModules
address[]
Array of toggle module addresses for each hat to create
_mutables
bool[]
Array of mutable flags for each hat to create
_imageURIs
string[]
Array of imageURIs for each hat to create
Returns
Name
Type
Description
success
bool
True if all createHat calls succeeded

getNextId

Gets the id of the next child hat of the hat _admin
Does not incrememnt lastHatId
function getNextId(uint256 _admin) public view returns (uint256 nextId);
Parameters
Name
Type
Description
_admin
uint256
The id of the hat to serve as the admin for the next child hat
Returns
Name
Type
Description
nextId
uint256
The new hat id

mintHat

Mints an ERC1155-similar token of the Hat to an eligible recipient, who then "wears" the hat
The msg.sender must wear an admin Hat of _hatId, and the recipient must be eligible to wear _hatId
function mintHat(uint256 _hatId, address _wearer) public returns (bool success);
Parameters
Name
Type
Description
_hatId
uint256
The id of the Hat to mint
_wearer
address
The address to which the Hat is minted
Returns
Name
Type
Description
success
bool
Whether the mint succeeded

batchMintHats

Mints new hats in batch. The msg.sender must be an admin of each hat.
This is a convenience function that loops through the arrays and calls mintHat.
function batchMintHats(uint256[] calldata _hatIds, address[] calldata _wearers) public returns (bool success);
Parameters
Name
Type
Description
_hatIds
uint256[]
Array of ids of hats to mint
_wearers
address[]
Array of addresses to which the hats will be minted
Returns
Name
Type
Description
success
bool
True if all mintHat calls succeeded

setHatStatus

Toggles a Hat's status from active to deactive, or vice versa
The msg.sender must be set as the hat's toggle
function setHatStatus(uint256 _hatId, bool _newStatus) external returns (bool toggled);
Parameters
Name
Type
Description
_hatId
uint256
The id of the Hat for which to adjust status
_newStatus
bool
The new status to set
Returns
Name
Type
Description
toggled
bool
Whether the status was toggled

checkHatStatus

Checks a hat's toggle module and processes the returned status
May change the hat's status in storage
function checkHatStatus(uint256 _hatId) public returns (bool toggled);
Parameters
Name
Type
Description
_hatId
uint256
The id of the Hat whose toggle we are checking
Returns
Name
Type
Description
toggled
bool
Whether there was a new status

_pullHatStatus

function _pullHatStatus(Hat storage _hat, uint256 _hatId) internal view returns (bool success, bool newStatus);

setHatWearerStatus

Report from a hat's eligibility on the status of one of its wearers and, if false, revoke their hat
Burns the wearer's hat, if revoked
function setHatWearerStatus(uint256 _hatId, address _wearer, bool _eligible, bool _standing)
external
returns (bool updated);
Parameters
Name
Type
Description
_hatId
uint256
The id of the hat
_wearer
address
The address of the hat wearer whose status is being reported
_eligible
bool
Whether the wearer is eligible for the hat (will be revoked if false)
_standing
bool
False if the wearer is no longer in good standing (and potentially should be penalized)
Returns
Name
Type
Description
updated
bool
Whether the report succeeded

checkHatWearerStatus

Check a hat's eligibility for a report on the status of one of the hat's wearers and, if false, revoke their hat
Burns the wearer's hat, if revoked
function checkHatWearerStatus(uint256 _hatId, address _wearer) public returns (bool updated);
Parameters
Name
Type
Description
_hatId
uint256
The id of the hat
_wearer
address
The address of the Hat wearer whose status report is being requested
Returns
Name
Type
Description
updated
bool
Whether the wearer's status was altered

renounceHat

Stop wearing a hat, aka "renounce" it
Burns the msg.sender's hat
function renounceHat(uint256 _hatId) external;
Parameters
Name
Type
Description
_hatId
uint256
The id of the Hat being renounced

_createHat

Internal call for creating a new hat
Initializes a new Hat in storage, but does not mint any tokens
function _createHat(
uint256 _id,
string calldata _details,
uint32 _maxSupply,
address _eligibility,
address _toggle,
bool _mutable,
string calldata _imageURI
) internal;
Parameters
Name
Type
Description
_id
uint256
ID of the hat to be stored
_details
string
A description of the hat
_maxSupply
uint32
The total instances of the Hat that can be worn at once
_eligibility
address
The address that can report on the Hat wearer's status
_toggle
address
The address that can deactivate the hat [optional]
_mutable
bool
Whether the hat's properties are changeable after creation
_imageURI
string
The image uri for this top hat and the fallback for its downstream hats [optional]

_processHatStatus

Internal function to process hat status
Updates a hat's status if different from current
function _processHatStatus(uint256 _hatId, bool _newStatus) internal returns (bool updated);
Parameters
Name
Type
Description
_hatId
uint256
The id of the Hat in quest
_newStatus
bool
The status to potentially change to
Returns
Name
Type
Description
updated
bool
- Whether the status was updated

_processHatWearerStatus

Internal call to process wearer status from the eligibility module
Burns the wearer's Hat token if _eligible is false, and updates badStandings state if necessary
function _processHatWearerStatus(uint256 _hatId, address _wearer, bool _eligible, bool _standing)
internal
returns (bool updated);
Parameters
Name
Type
Description
_hatId
uint256
The id of the Hat to revoke
_wearer
address
The address of the wearer in question
_eligible
bool
Whether _wearer is eligible for the Hat (if false, this function will revoke their Hat)
_standing
bool
Whether _wearer is in good standing (to be recorded in storage)
Returns
Name
Type
Description
updated
bool
Whether the wearer standing was updated

_setHatStatus

Internal function to set a hat's status in storage
Flips the 0th bit of _hat.config via bitwise operation
function _setHatStatus(Hat storage _hat, bool _status) internal;
Parameters
Name
Type
Description
_hat
Hat
The hat object
_status
bool
The status to set for the hat

_staticBalanceOf

Internal function to retrieve an account's internal "static" balance directly from internal storage,
This function bypasses the dynamic _isActive and _isEligible checks
function _staticBalanceOf(address _account, uint256 _hatId) internal view returns (uint256 staticBalance);
Parameters
Name
Type
Description
_account
address
The account to check
_hatId
uint256
The hat to check
Returns
Name
Type
Description
staticBalance
uint256
The account's static of the hat, from internal storage

_checkAdmin

Checks whether msg.sender is an admin of a hat, and reverts if not
function _checkAdmin(uint256 _hatId) internal view;

_checkAdminOrWearer

checks whether the msg.sender is either an admin or wearer or a hat, and reverts the appropriate error if not
function _checkAdminOrWearer(uint256 _hatId) internal view;

transferHat

Transfers a hat from one wearer to another eligible wearer
The hat must be mutable, and the transfer must be initiated by an admin
function transferHat(uint256 _hatId, address _from, address _to) public;
Parameters
Name
Type
Description
_hatId
uint256
The hat in question
_from
address
The current wearer
_to
address
The new wearer

makeHatImmutable

Set a mutable hat to immutable
Sets the second bit of hat.config to 0
function makeHatImmutable(uint256 _hatId) external;
Parameters
Name
Type
Description
_hatId
uint256
The id of the Hat to make immutable

changeHatDetails

Change a hat's details
Hat must be mutable, except for tophats.
function changeHatDetails(uint256 _hatId, string calldata _newDetails) external;
Parameters
Name
Type
Description
_hatId
uint256
The id of the Hat to change
_newDetails
string
The new details. Must not be larger than 7000 bytes.

changeHatEligibility

Change a hat's details
Hat must be mutable
function changeHatEligibility(uint256 _hatId, address _newEligibility) external;
Parameters
Name
Type
Description
_hatId
uint256
The id of the Hat to change
_newEligibility
address
The new eligibility module

changeHatToggle

Change a hat's details
Hat must be mutable
function changeHatToggle(uint256 _hatId, address _newToggle) external;
Parameters
Name
Type
Description
_hatId
uint256
The id of the Hat to change
_newToggle
address
The new toggle module

changeHatImageURI

Change a hat's details
Hat must be mutable, except for tophats
function changeHatImageURI(uint256 _hatId, string calldata _newImageURI) external;
Parameters
Name
Type
Description
_hatId
uint256
The id of the Hat to change
_newImageURI
string
The new imageURI. Must not be larger than 7000 bytes.

changeHatMaxSupply

Change a hat's details
Hat must be mutable; new max supply cannot be less than current supply
function changeHatMaxSupply(uint256 _hatId, uint32 _newMaxSupply) external;
Parameters
Name
Type
Description
_hatId
uint256
The id of the Hat to change
_newMaxSupply
uint32
The new max supply

requestLinkTopHatToTree

Submits a request to link a Hat Tree under a parent tree. Requests can be submitted by either... a) the wearer of a topHat, previous to any linkage, or b) the admin(s) of an already-linked topHat (aka tree root), where such a request is to move the tree root to another admin within the same parent tree
A topHat can have at most 1 request at a time. Submitting a new request will replace the existing request.
function requestLinkTopHatToTree(uint32 _topHatDomain, uint256 _requestedAdminHat) external;
Parameters
Name
Type
Description
_topHatDomain
uint32
The domain of the topHat to link
_requestedAdminHat
uint256
The hat that will administer the linked tree

approveLinkTopHatToTree

Approve a request to link a Tree under a parent tree, with options to add eligibility or toggle modules and change its metadata
Requests can only be approved by wearer or an admin of the _newAdminHat, and there can only be one link per tree root at a given time.
function