HatsIdUtilities.sol

HatsIdUtilities

Git Source

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