HatsIdUtilities
Inherits: IHatsIdUtilities
Author: Haberdasher Labs
Functions for working with Hat Ids from Hats Protocol. Factored out of Hats.sol for easier use by other contracts.
State Variables
linkedTreeRequests
Mapping of tophats requesting to link to admin hats in other trees
Linkage only occurs if request is approved by the new admin
mapping(uint32 => uint256) public linkedTreeRequests;
linkedTreeAdmins
Mapping of approved & linked tophats to admin hats in other trees, used for grafting one hats tree onto another
Trees can only be linked to another tree via their tophat
mapping(uint32 => uint256) public linkedTreeAdmins;
TOPHAT_ADDRESS_SPACE
Hat Ids serve as addresses. A given Hat's Id represents its location in its hat tree: its level, its admin, its admin's admin (etc, all the way up to the tophat). The top level consists of 4 bytes and references all tophats. Each level below consists of 16 bits, and contains up to 65,536 child hats. A uint256 contains 4 bytes of space for tophat addresses, giving room for ((256 - 32) / 16) = 14 levels of delegation, with the admin at each level having space for 65,536 different child hats. A hat tree consists of a single tophat and has a max depth of 14 levels.
Number of bits of address space for tophat ids, ie the tophat domain
uint256 internal constant TOPHAT_ADDRESS_SPACE = 32;
LOWER_LEVEL_ADDRESS_SPACE
Number of bits of address space for each level below the tophat
uint256 internal constant LOWER_LEVEL_ADDRESS_SPACE = 16;
MAX_LEVELS
Maximum number of levels below the tophat, ie max tree depth (256 - TOPHAT_ADDRESS_SPACE) / LOWER_LEVEL_ADDRESS_SPACE;
uint256 internal constant MAX_LEVELS = 14;
Functions
buildHatId
Constructs a valid hat id for a new hat underneath a given admin
Reverts if the admin has already reached MAX_LEVELS
function buildHatId(uint256 _admin, uint16 _newHat) public pure returns (uint256 id);
Parameters
| Name | Type | Description |
|---|---|---|
_admin | uint256 | the id of the admin for the new hat |
_newHat | uint16 | the uint16 id of the new hat |
Returns
| Name | Type | Description |
|---|---|---|
id | uint256 | The constructed hat id |
getHatLevel
Identifies the level a given hat in its hat tree
function getHatLevel(uint256 _hatId) public view returns (uint32 level);
Parameters
| Name | Type | Description |
|---|---|---|
_hatId | uint256 | the id of the hat in question |
Returns
| Name | Type | Description |
|---|---|---|
level | uint32 | (0 to type(uint32).max) |
getLocalHatLevel
Identifies the level a given hat in its local hat tree
Similar to getHatLevel, but does not account for linked trees
function getLocalHatLevel(uint256 _hatId) public pure returns (uint32 level);
Parameters
| Name | Type | Description |
|---|---|---|
_hatId | uint256 | the id of the hat in question |
Returns
| Name | Type | Description |
|---|---|---|
level | uint32 | The local level, from 0 to 14 |
isTopHat
Checks whether a hat is a topHat
function isTopHat(uint256 _hatId) public view returns (bool _isTopHat);
Parameters
| Name | Type | Description |
|---|---|---|
_hatId | uint256 | The hat in question |
Returns
| Name | Type | Description |
|---|---|---|
_isTopHat | bool | Whether the hat is a topHat |
isLocalTopHat
Checks whether a hat is a topHat in its local hat tree
Similar to isTopHat, but does not account for linked trees
function isLocalTopHat(uint256 _hatId) public pure returns (bool _isLocalTopHat);
Parameters
| Name | Type | Description |
|---|---|---|
_hatId | uint256 | The hat in question |
Returns
| Name | Type | Description |
|---|---|---|
_isLocalTopHat | bool | Whether the hat is a topHat for its local tree |
isValidHatId
function isValidHatId(uint256 _hatId) public pure returns (bool validHatId);
getAdminAtLevel
Gets the hat id of the admin at a given level of a given hat
This function traverses trees by following the linkedTreeAdmin pointer to a hat located in a different tree
function getAdminAtLevel(uint256 _hatId, uint32 _level) public view returns (uint256 admin);
Parameters
| Name | Type | Description |
|---|---|---|
_hatId | uint256 | the id of the hat in question |
_level | uint32 | the admin level of interest |
Returns
| Name | Type | Description |
|---|---|---|
admin | uint256 | The hat id of the resulting admin |
getAdminAtLocalLevel
Gets the hat id of the admin at a given level of a given hat local to the tree containing the hat.
function getAdminAtLocalLevel(uint256 _hatId, uint32 _level) public pure returns (uint256 admin);
Parameters
| Name | Type | Description |
|---|---|---|
_hatId | uint256 | the id of the hat in question |
_level | uint32 | the admin level of interest |
Returns
| Name | Type | Description |
|---|---|---|
admin | uint256 | The hat id of the resulting admin |
getTopHatDomain
Gets the tophat domain of a given hat
A domain is the identifier for a given hat tree, stored in the first 4 bytes of a hat's id
function getTopHatDomain(uint256 _hatId) public pure returns (uint32 domain);
Parameters
| Name | Type | Description |
|---|---|---|
_hatId | uint256 | the id of the hat in question |
Returns
| Name | Type | Description |
|---|---|---|
domain | uint32 | The domain of the hat's tophat |
getTippyTopHatDomain
Gets the domain of the highest parent tophat — the "tippy tophat"
function getTippyTopHatDomain(uint32 _topHatDomain) public view returns (uint32 domain);
Parameters
| Name | Type | Description |
|---|---|---|
_topHatDomain | uint32 | the 32 bit domain of a (likely linked) tophat |
Returns
| Name | Type | Description |
|---|---|---|
domain | uint32 | The tippy tophat domain |
noCircularLinkage
Checks For any circular linkage of trees
function noCircularLinkage(uint32 _topHatDomain, uint256 _linkedAdmin) public view returns (bool notCircular);
Parameters
| Name | Type | Description |
|---|---|---|
_topHatDomain | uint32 | the 32 bit domain of the tree to be linked |
_linkedAdmin | uint256 | the hatId of the potential tree admin |
Returns
| Name | Type | Description |
|---|---|---|
notCircular | bool | circular link has not been found |
sameTippyTopHatDomain
Checks that a tophat domain and its potential linked admin are from the same tree, ie have the same tippy tophat domain
function sameTippyTopHatDomain(uint32 _topHatDomain, uint256 _newAdminHat) public view returns (bool sameDomain);
Parameters
| Name | Type | Description |
|---|---|---|
_topHatDomain | uint32 | The 32 bit domain of the tophat to be linked |
_newAdminHat | uint256 | The new admin for the linked tree |
Returns
| Name | Type | Description |
|---|---|---|
sameDomain | bool | Whether the _topHatDomain and the domain of its potential linked _newAdminHat domains are the same |