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

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

Returns

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

Returns

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

Returns

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

Returns

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

Returns

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

Returns

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

Returns

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

Returns

_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

Returns

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

Returns

renounceHat

Stop wearing a hat, aka "renounce" it

Burns the msg.sender's hat

function renounceHat(uint256 _hatId) external;

Parameters

_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

_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

Returns

_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

Returns

_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

_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

Returns

_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

makeHatImmutable

Set a mutable hat to immutable

Sets the second bit of hat.config to 0

function makeHatImmutable(uint256 _hatId) external;

Parameters

changeHatDetails

Change a hat's details

Hat must be mutable, except for tophats.

function changeHatDetails(uint256 _hatId, string calldata _newDetails) external;

Parameters

changeHatEligibility

Change a hat's details

Hat must be mutable

function changeHatEligibility(uint256 _hatId, address _newEligibility) external;

Parameters

changeHatToggle

Change a hat's details

Hat must be mutable

function changeHatToggle(uint256 _hatId, address _newToggle) external;

Parameters

changeHatImageURI

Change a hat's details

Hat must be mutable, except for tophats

function changeHatImageURI(uint256 _hatId, string calldata _newImageURI) external;

Parameters

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

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

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 approveLinkTopHatToTree(
    uint32 _topHatDomain,
    uint256 _newAdminHat,
    address _eligibility,
    address _toggle,
    string calldata _details,
    string calldata _imageURI
) external;

Parameters

unlinkTopHatFromTree

Unlink a Tree from the parent tree

*This can only be called by an admin of the tree root. Fails if the topHat to unlink has no non-zero wearer, which can occur if...

• It's wearer is in badStanding
• It has been revoked from its wearer (and possibly burned)˘
• It is not active (ie toggled off)*

function unlinkTopHatFromTree(uint32 _topHatDomain, address _wearer) external;

Parameters

relinkTopHatWithinTree

Move a tree root to a different position within the same parent tree, without a request. Valid destinations include within the same local tree as the origin, or to the local tree of the tippyTopHat. TippyTopHat wearers can bypass this restriction to relink to anywhere in its full tree.

Caller must be both an admin tree root and admin or wearer of _newAdminHat.

function relinkTopHatWithinTree(
    uint32 _topHatDomain,
    uint256 _newAdminHat,
    address _eligibility,
    address _toggle,
    string calldata _details,
    string calldata _imageURI
) external;

Parameters

_linkTopHatToTree

Internal function to link a Tree under a parent Tree, with protection against circular linkages and relinking to a separate Tree, with options to add eligibility or toggle modules and change its metadata

Linking _topHatDomain replaces any existing links

function _linkTopHatToTree(
    uint32 _topHatDomain,
    uint256 _newAdminHat,
    address _eligibility,
    address _toggle,
    string calldata _details,
    string calldata _imageURI
) internal;

Parameters

viewHat

View the properties of a given Hat

function viewHat(uint256 _hatId)
    public
    view
    returns (
        string memory details,
        uint32 maxSupply,
        uint32 supply,
        address eligibility,
        address toggle,
        string memory imageURI,
        uint16 lastHatId,
        bool mutable_,
        bool active
    );

Parameters

Returns

isWearerOfHat

Checks whether a given address wears a given Hat

Convenience function that wraps balanceOf

function isWearerOfHat(address _user, uint256 _hatId) public view returns (bool isWearer);

Parameters

Returns

isAdminOfHat

Checks whether a given address serves as the admin of a given Hat

Recursively checks if _user wears the admin Hat of the Hat in question. This is recursive since there may be a string of Hats as admins of Hats.

function isAdminOfHat(address _user, uint256 _hatId) public view returns (bool isAdmin);

Parameters

Returns

_isActive

Checks the active status of a hat

For internal use instead of isActive when passing Hat as param is preferable

function _isActive(Hat storage _hat, uint256 _hatId) internal view returns (bool active);

Parameters

Returns

isActive

Checks the active status of a hat

function isActive(uint256 _hatId) external view returns (bool active);

Parameters

Returns

_getHatStatus

Internal function to retrieve a hat's status from storage

reads the 0th bit of the hat's config

function _getHatStatus(Hat storage _hat) internal view returns (bool status);

Parameters

Returns

_isMutable

Internal function to retrieve a hat's mutability setting

reads the 1st bit of the hat's config

function _isMutable(Hat storage _hat) internal view returns (bool _mutable);

Parameters

Returns

isInGoodStanding

Checks whether a wearer of a Hat is in good standing

function isInGoodStanding(address _wearer, uint256 _hatId) public view returns (bool standing);

Parameters

Returns

_isEligible

Internal call to check whether an address is eligible for a given Hat

Tries an external call to the Hat's eligibility module, defaulting to existing badStandings state if the call fails (ie if the eligibility module address does not conform to the IHatsEligibility interface)

function _isEligible(address _wearer, Hat storage _hat, uint256 _hatId) internal view returns (bool eligible);

Parameters

Returns

isEligible

Checks whether an address is eligible for a given Hat

Public function for use when passing a Hat object is not possible or preferable

function isEligible(address _wearer, uint256 _hatId) public view returns (bool eligible);

Parameters

Returns

hatSupply

Gets the current supply of a Hat

Only tracks explicit burns and mints, not dynamic revocations

function hatSupply(uint256 _hatId) external view returns (uint32 supply);

Parameters

Returns

getHatEligibilityModule

Gets the eligibility module for a hat

function getHatEligibilityModule(uint256 _hatId) external view returns (address eligibility);

Parameters

Returns

getHatToggleModule

Gets the toggle module for a hat

function getHatToggleModule(uint256 _hatId) external view returns (address toggle);

Parameters

Returns

getHatMaxSupply

Gets the max supply for a hat

function getHatMaxSupply(uint256 _hatId) external view returns (uint32 maxSupply);

Parameters

Returns

getImageURIForHat

Gets the imageURI for a given hat

If this hat does not have an imageURI set, recursively get the imageURI from its admin

function getImageURIForHat(uint256 _hatId) public view returns (string memory _uri);

Parameters

Returns

_constructURI

Constructs the URI for a Hat, using data from the Hat struct

function _constructURI(uint256 _hatId) internal view returns (string memory _uri);

Parameters

Returns

balanceOf

Gets the Hat token balance of a user for a given Hat

Balance is dynamic based on the hat's status and wearer's eligibility, so off-chain balance data indexed from events may not be in sync

function balanceOf(address _wearer, uint256 _hatId) public view override(ERC1155, IHats) returns (uint256 balance);

Parameters

Returns

_mintHat

Internal call to mint a Hat token to a wearer

Unsafe if called when _wearer has a non-zero balance of _hatId

function _mintHat(address _wearer, uint256 _hatId) internal;

Parameters

_burnHat

Internal call to burn a wearer's Hat token

Unsafe if called when _wearer doesn't have a zero balance of _hatId

function _burnHat(address _wearer, uint256 _hatId) internal;

Parameters

setApprovalForAll

Approvals are not necessary for Hats since transfers are not handled by the wearer

Admins should use transferHat() to transfer

function setApprovalForAll(address, bool) public pure override;

safeTransferFrom

Safe transfers are not necessary for Hats since transfers are not handled by the wearer

Admins should use transferHat() to transfer

function safeTransferFrom(address, address, uint256, uint256, bytes calldata) public pure override;

safeBatchTransferFrom

Safe transfers are not necessary for Hats since transfers are not handled by the wearer

function safeBatchTransferFrom(address, address, uint256[] calldata, uint256[] calldata, bytes calldata)
    public
    pure
    override;

supportsInterface

ERC165 interface detection

While Hats Protocol conforms to the ERC1155 interface, it does not fully conform to the ERC1155 specification since it does not implement the ERC1155Receiver functionality. For this reason, this function overrides the ERC1155 implementation to return false for ERC1155.

function supportsInterface(bytes4 interfaceId) public pure override returns (bool);

Parameters

Returns

balanceOfBatch

Batch retrieval for wearer balances

Given the higher gas overhead of Hats balanceOf checks, large batches may be high cost or run into gas limits

function balanceOfBatch(address[] calldata _wearers, uint256[] calldata _hatIds)
    public
    view
    override(ERC1155, IHats)
    returns (uint256[] memory balances);

Parameters

uri

View the uri for a Hat

function uri(uint256 id) public view override(ERC1155, IHats) returns (string memory _uri);

Parameters

Returns

Structs

Hat

This contract's version is labeled v1. Previous versions labeled similarly as v1 and v1.0 are deprecated, and should be treated as beta deployments.

A Hat object containing the hat's properties

The members are packed to minimize storage costs

struct Hat {
    address eligibility;
    uint32 maxSupply;
    uint32 supply;
    uint16 lastHatId;
    address toggle;
    uint96 config;
    string details;
    string imageURI;
}