` | `bool` | bool True if the contract implements `interfaceId` and false otherwise |
#### 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*
```solidity
function balanceOfBatch(address[] calldata _wearers, uint256[] calldata _hatIds)
public
view
override(ERC1155, IHats)
returns (uint256[] memory balances);
```
**Parameters**
| Name | Type | Description |
| ---------- | ----------- | ------------------------------------------------------------ |
| `_wearers` | `address[]` | Array of addresses to check balances for |
| `_hatIds` | `uint256[]` | Array of Hat ids to check, using the same index as \_wearers |
#### uri
View the uri for a Hat
```solidity
function uri(uint256 id) public view override(ERC1155, IHats) returns (string memory _uri);
```
**Parameters**
| Name | Type | Description |
| ---- | --------- | ----------------- |
| `id` | `uint256` | The id of the Hat |
**Returns**
| Name | Type | Description |
| ------ | -------- | ------------------------------ |
| `_uri` | `string` | An 1155-compatible JSON object |
### 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*
```solidity
struct Hat {
address eligibility;
uint32 maxSupply;
uint32 supply;
uint16 lastHatId;
address toggle;
uint96 config;
string details;
string imageURI;
}
```
# HatsEvents.sol
## HatsEvents
[Git Source](https://github.com/Hats-Protocol/hats-protocol/blob/b43ad0d1dbe4a4190febc036ee8a2849e3f221b4/src/Interfaces/HatsEvents.sol)
### Events
#### HatCreated
Emitted when a new hat is created
```solidity
event HatCreated(
uint256 id, string details, uint32 maxSupply, address eligibility, address toggle, bool mutable_, string imageURI
);
```
#### WearerStandingChanged
Emitted when a hat wearer's standing is updated
*Eligibility is excluded since the source of truth for eligibility is the eligibility module and may change without a transaction*
```solidity
event WearerStandingChanged(uint256 hatId, address wearer, bool wearerStanding);
```
#### HatStatusChanged
Emitted when a hat's status is updated
```solidity
event HatStatusChanged(uint256 hatId, bool newStatus);
```
#### HatDetailsChanged
Emitted when a hat's details are updated
```solidity
event HatDetailsChanged(uint256 hatId, string newDetails);
```
#### HatEligibilityChanged
Emitted when a hat's eligibility module is updated
```solidity
event HatEligibilityChanged(uint256 hatId, address newEligibility);
```
#### HatToggleChanged
Emitted when a hat's toggle module is updated
```solidity
event HatToggleChanged(uint256 hatId, address newToggle);
```
#### HatMutabilityChanged
Emitted when a hat's mutability is updated
```solidity
event HatMutabilityChanged(uint256 hatId);
```
#### HatMaxSupplyChanged
Emitted when a hat's maximum supply is updated
```solidity
event HatMaxSupplyChanged(uint256 hatId, uint32 newMaxSupply);
```
#### HatImageURIChanged
Emitted when a hat's image URI is updated
```solidity
event HatImageURIChanged(uint256 hatId, string newImageURI);
```
#### TopHatLinkRequested
Emitted when a tophat linkage is requested by its admin
```solidity
event TopHatLinkRequested(uint32 domain, uint256 newAdmin);
```
#### TopHatLinked
Emitted when a tophat is linked to a another tree
```solidity
event TopHatLinked(uint32 domain, uint256 newAdmin);
```
# HatsErrors.sol
## HatsErrors
[Git Source](https://github.com/Hats-Protocol/hats-protocol/blob/b43ad0d1dbe4a4190febc036ee8a2849e3f221b4/src/Interfaces/HatsErrors.sol)
### Errors
#### NotAdmin
Emitted when `user` is attempting to perform an action on `hatId` but is not wearing one of `hatId`'s admin hats
*Can be equivalent to `NotHatWearer(buildHatId(hatId))`, such as when emitted by `approveLinkTopHatToTree` or `relinkTopHatToTree`*
```solidity
error NotAdmin(address user, uint256 hatId);
```
#### NotHatWearer
Emitted when attempting to perform an action as or for an account that is not a wearer of a given hat
```solidity
error NotHatWearer();
```
#### NotAdminOrWearer
Emitted when attempting to perform an action that requires being either an admin or wearer of a given hat
```solidity
error NotAdminOrWearer();
```
#### AllHatsWorn
Emitted when attempting to mint `hatId` but `hatId`'s maxSupply has been reached
```solidity
error AllHatsWorn(uint256 hatId);
```
#### MaxLevelsReached
Emitted when attempting to create a hat with a level 14 hat as its admin
```solidity
error MaxLevelsReached();
```
#### InvalidHatId
Emitted when an attempted hat id has empty intermediate level(s)
```solidity
error InvalidHatId();
```
#### AlreadyWearingHat
Emitted when attempting to mint `hatId` to a `wearer` who is already wearing the hat
```solidity
error AlreadyWearingHat(address wearer, uint256 hatId);
```
#### HatDoesNotExist
Emitted when attempting to mint a non-existant hat
```solidity
error HatDoesNotExist(uint256 hatId);
```
#### HatNotActive
Emmitted when attempting to mint or transfer a hat that is not active
```solidity
error HatNotActive();
```
#### NotEligible
Emitted when attempting to mint or transfer a hat to an ineligible wearer
```solidity
error NotEligible();
```
#### NotHatsToggle
Emitted when attempting to check or set a hat's status from an account that is not that hat's toggle module
```solidity
error NotHatsToggle();
```
#### NotHatsEligibility
Emitted when attempting to check or set a hat wearer's status from an account that is not that hat's eligibility module
```solidity
error NotHatsEligibility();
```
#### BatchArrayLengthMismatch
Emitted when array arguments to a batch function have mismatching lengths
```solidity
error BatchArrayLengthMismatch();
```
#### Immutable
Emitted when attempting to mutate or transfer an immutable hat
```solidity
error Immutable();
```
#### NewMaxSupplyTooLow
Emitted when attempting to change a hat's maxSupply to a value lower than its current supply
```solidity
error NewMaxSupplyTooLow();
```
#### CircularLinkage
Emitted when attempting to link a tophat to a new admin for which the tophat serves as an admin
```solidity
error CircularLinkage();
```
#### CrossTreeLinkage
Emitted when attempting to link or relink a tophat to a separate tree
```solidity
error CrossTreeLinkage();
```
#### LinkageNotRequested
Emitted when attempting to link a tophat without a request
```solidity
error LinkageNotRequested();
```
#### InvalidUnlink
Emitted when attempting to unlink a tophat that does not have a wearer
*This ensures that unlinking never results in a bricked tophat*
```solidity
error InvalidUnlink();
```
#### ZeroAddress
Emmited when attempting to change a hat's eligibility or toggle module to the zero address
```solidity
error ZeroAddress();
```
#### StringTooLong
Emmitted when attempting to change a hat's details or imageURI to a string with over 7000 bytes (\~characters)
*This protects against a DOS attack where an admin iteratively extend's a hat's details or imageURI to be so long that reading it exceeds the block gas limit, breaking `uri()` and `viewHat()`*
```solidity
error StringTooLong();
```
# HatsIdUtilities.sol
## HatsIdUtilities
[Git Source](https://github.com/Hats-Protocol/hats-protocol/blob/b43ad0d1dbe4a4190febc036ee8a2849e3f221b4/src/HatsIdUtilities.sol)
**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*
```solidity
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*
```solidity
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*
```solidity
uint256 internal constant TOPHAT_ADDRESS_SPACE = 32;
```
#### LOWER\_LEVEL\_ADDRESS\_SPACE
*Number of bits of address space for each level below the tophat*
```solidity
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;*
```solidity
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`*
```solidity
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
```solidity
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*
```solidity
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
```solidity
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*
```solidity
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
```solidity
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*
```solidity
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.
```solidity
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*
```solidity
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"
```solidity
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
```solidity
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
```solidity
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 |
# Interfaces
# IHats.sol
## IHats
[Git Source](https://github.com/Hats-Protocol/hats-protocol/blob/b43ad0d1dbe4a4190febc036ee8a2849e3f221b4/src/Interfaces/IHats.sol)
**Inherits:** IHatsIdUtilities, HatsErrors, HatsEvents
### Functions
#### mintTopHat
```solidity
function mintTopHat(address _target, string memory _details, string memory _imageURI)
external
returns (uint256 topHatId);
```
#### createHat
```solidity
function createHat(
uint256 _admin,
string calldata _details,
uint32 _maxSupply,
address _eligibility,
address _toggle,
bool _mutable,
string calldata _imageURI
) external returns (uint256 newHatId);
```
#### batchCreateHats
```solidity
function batchCreateHats(
uint256[] calldata _admins,
string[] calldata _details,
uint32[] calldata _maxSupplies,
address[] memory _eligibilityModules,
address[] memory _toggleModules,
bool[] calldata _mutables,
string[] calldata _imageURIs
) external returns (bool success);
```
#### getNextId
```solidity
function getNextId(uint256 _admin) external view returns (uint256 nextId);
```
#### mintHat
```solidity
function mintHat(uint256 _hatId, address _wearer) external returns (bool success);
```
#### batchMintHats
```solidity
function batchMintHats(uint256[] calldata _hatIds, address[] calldata _wearers) external returns (bool success);
```
#### setHatStatus
```solidity
function setHatStatus(uint256 _hatId, bool _newStatus) external returns (bool toggled);
```
#### checkHatStatus
```solidity
function checkHatStatus(uint256 _hatId) external returns (bool toggled);
```
#### setHatWearerStatus
```solidity
function setHatWearerStatus(uint256 _hatId, address _wearer, bool _eligible, bool _standing)
external
returns (bool updated);
```
#### checkHatWearerStatus
```solidity
function checkHatWearerStatus(uint256 _hatId, address _wearer) external returns (bool updated);
```
#### renounceHat
```solidity
function renounceHat(uint256 _hatId) external;
```
#### transferHat
```solidity
function transferHat(uint256 _hatId, address _from, address _to) external;
```
#### makeHatImmutable
```solidity
function makeHatImmutable(uint256 _hatId) external;
```
#### changeHatDetails
```solidity
function changeHatDetails(uint256 _hatId, string memory _newDetails) external;
```
#### changeHatEligibility
```solidity
function changeHatEligibility(uint256 _hatId, address _newEligibility) external;
```
#### changeHatToggle
```solidity
function changeHatToggle(uint256 _hatId, address _newToggle) external;
```
#### changeHatImageURI
```solidity
function changeHatImageURI(uint256 _hatId, string memory _newImageURI) external;
```
#### changeHatMaxSupply
```solidity
function changeHatMaxSupply(uint256 _hatId, uint32 _newMaxSupply) external;
```
#### requestLinkTopHatToTree
```solidity
function requestLinkTopHatToTree(uint32 _topHatId, uint256 _newAdminHat) external;
```
#### approveLinkTopHatToTree
```solidity
function approveLinkTopHatToTree(
uint32 _topHatId,
uint256 _newAdminHat,
address _eligibility,
address _toggle,
string calldata _details,
string calldata _imageURI
) external;
```
#### unlinkTopHatFromTree
```solidity
function unlinkTopHatFromTree(uint32 _topHatId, address _wearer) external;
```
#### relinkTopHatWithinTree
```solidity
function relinkTopHatWithinTree(
uint32 _topHatDomain,
uint256 _newAdminHat,
address _eligibility,
address _toggle,
string calldata _details,
string calldata _imageURI
) external;
```
#### viewHat
```solidity
function viewHat(uint256 _hatId)
external
view
returns (
string memory details,
uint32 maxSupply,
uint32 supply,
address eligibility,
address toggle,
string memory imageURI,
uint16 lastHatId,
bool mutable_,
bool active
);
```
#### isWearerOfHat
```solidity
function isWearerOfHat(address _user, uint256 _hatId) external view returns (bool isWearer);
```
#### isAdminOfHat
```solidity
function isAdminOfHat(address _user, uint256 _hatId) external view returns (bool isAdmin);
```
#### isInGoodStanding
```solidity
function isInGoodStanding(address _wearer, uint256 _hatId) external view returns (bool standing);
```
#### isEligible
```solidity
function isEligible(address _wearer, uint256 _hatId) external view returns (bool eligible);
```
#### getHatEligibilityModule
```solidity
function getHatEligibilityModule(uint256 _hatId) external view returns (address eligibility);
```
#### getHatToggleModule
```solidity
function getHatToggleModule(uint256 _hatId) external view returns (address toggle);
```
#### getHatMaxSupply
```solidity
function getHatMaxSupply(uint256 _hatId) external view returns (uint32 maxSupply);
```
#### hatSupply
```solidity
function hatSupply(uint256 _hatId) external view returns (uint32 supply);
```
#### getImageURIForHat
```solidity
function getImageURIForHat(uint256 _hatId) external view returns (string memory _uri);
```
#### balanceOf
```solidity
function balanceOf(address wearer, uint256 hatId) external view returns (uint256 balance);
```
#### balanceOfBatch
```solidity
function balanceOfBatch(address[] calldata _wearers, uint256[] calldata _hatIds)
external
view
returns (uint256[] memory);
```
#### uri
```solidity
function uri(uint256 id) external view returns (string memory _uri);
```
# IHatsIdUtilities.sol
## IHatsIdUtilities
[Git Source](https://github.com/Hats-Protocol/hats-protocol/blob/b43ad0d1dbe4a4190febc036ee8a2849e3f221b4/src/Interfaces/IHatsIdUtilities.sol)
### Functions
#### buildHatId
```solidity
function buildHatId(uint256 _admin, uint16 _newHat) external pure returns (uint256 id);
```
#### getHatLevel
```solidity
function getHatLevel(uint256 _hatId) external view returns (uint32 level);
```
#### getLocalHatLevel
```solidity
function getLocalHatLevel(uint256 _hatId) external pure returns (uint32 level);
```
#### isTopHat
```solidity
function isTopHat(uint256 _hatId) external view returns (bool _topHat);
```
#### isLocalTopHat
```solidity
function isLocalTopHat(uint256 _hatId) external pure returns (bool _localTopHat);
```
#### isValidHatId
```solidity
function isValidHatId(uint256 _hatId) external view returns (bool validHatId);
```
#### getAdminAtLevel
```solidity
function getAdminAtLevel(uint256 _hatId, uint32 _level) external view returns (uint256 admin);
```
#### getAdminAtLocalLevel
```solidity
function getAdminAtLocalLevel(uint256 _hatId, uint32 _level) external pure returns (uint256 admin);
```
#### getTopHatDomain
```solidity
function getTopHatDomain(uint256 _hatId) external view returns (uint32 domain);
```
#### getTippyTopHatDomain
```solidity
function getTippyTopHatDomain(uint32 _topHatDomain) external view returns (uint32 domain);
```
#### noCircularLinkage
```solidity
function noCircularLinkage(uint32 _topHatDomain, uint256 _linkedAdmin) external view returns (bool notCircular);
```
#### sameTippyTopHatDomain
```solidity
function sameTippyTopHatDomain(uint32 _topHatDomain, uint256 _newAdminHat) external view returns (bool sameDomain);
```
# IHatsEligibility.sol
## IHatsEligibility
[Git Source](https://github.com/Hats-Protocol/hats-protocol/blob/b43ad0d1dbe4a4190febc036ee8a2849e3f221b4/src/Interfaces/IHatsEligibility.sol)
### Functions
#### getWearerStatus
Returns the status of a wearer for a given hat
*If standing is false, eligibility MUST also be false*
```solidity
function getWearerStatus(address _wearer, uint256 _hatId) external view returns (bool eligible, bool standing);
```
**Parameters**
| Name | Type | Description |
|---|
_wearer | address | The address of the current or prospective Hat wearer |
_hatId | uint256 | The id of the hat in question |
**Returns**
| Name | Type | Description |
|---|
eligible | bool | Whether the _wearer is eligible to wear the hat |
standing | bool | Whether the _wearer is in goog standing |
# IHatsToggle.sol
## IHatsToggle
[Git Source](https://github.com/Hats-Protocol/hats-protocol/blob/b43ad0d1dbe4a4190febc036ee8a2849e3f221b4/src/Interfaces/IHatsToggle.sol)
### Functions
#### getHatStatus
```solidity
function getHatStatus(uint256 _hatId) external view returns (bool);
```
**Parameters**
| Name | Type | Description |
|---|
_hatId | uint256 | The id of the hat in question |
**Returns**
| Name | Type | Descriptiom |
|---|
| - | bool | Whether the hat is active (true) or inactive (false |
# v1 SDK
Hats Protocol v1 Core and Subgraph SDKs.
Check out the open source code [here](https://github.com/Hats-Protocol/sdk-v1-core).
{% content-ref url="/pages/pUKb4l3JsO7rntsovnrC" %}
[Core](/for-developers/v1-sdk/core)
{% endcontent-ref %}
{% content-ref url="/pages/DkoFNu5pTmYoaQdovnJb" %}
[Subgraph](/for-developers/v1-sdk/subgraph)
{% endcontent-ref %}
# Core
## Overview
The SDK is an open source JavaScript client that provides core Hats-Protocol v1 functionalities and was designed to work both in the browser and in Node.js.
## Contents
{% content-ref url="/pages/ToqLYs8PRb4PsPHjLi9w" %}
[Getting Started](/for-developers/v1-sdk/core/getting-started)
{% endcontent-ref %}
{% content-ref url="/pages/x9N21y6Zyhh2P66tkpCI" %}
[Onchain Reads](/for-developers/v1-sdk/core/onchain-reads)
{% endcontent-ref %}
{% content-ref url="/pages/MRAmuylwQsSk2ELQOQpi" %}
[Onchain Writes](/for-developers/v1-sdk/core/onchain-writes)
{% endcontent-ref %}
{% content-ref url="/pages/7WfzrhxyPzRDU66URymi" %}
[Multicall](/for-developers/v1-sdk/core/multicall)
{% endcontent-ref %}
{% content-ref url="/pages/m5B7GocTsrjNR0W6jmNf" %}
[Claiming Hats](/for-developers/v1-sdk/core/claiming-hats)
{% endcontent-ref %}
{% content-ref url="/pages/UvYqKn39gCYDXbvGBg6n" %}
[Utilities](/for-developers/v1-sdk/core/hat-and-tree-id-utilities)
{% endcontent-ref %}
# Getting Started
### *Install*
yarn:
```bash
yarn add @hatsprotocol/sdk-v1-core viem
```
npm:
```bash
npm install @hatsprotocol/sdk-v1-core viem
```
The SDK uses Viem in order to interact with the various chains and includes it as a peer dependency.
### *HatsClient Initialization*
Import and initialize HatsClient:
```typescript
import { HatsClient } from "@hatsprotocol/sdk-v1-core";
const hatsClient = new HatsClient({
chainId,
publicClient,
walletClient,
});
```
***Arguments***:
```typescript
{
chainId: number;
publicClient: PublicClient;
walletClient?: WalletClient;
}
```
* `chainId` - Client's chain ID. The client is initialized to work with one specific chain.
* `publicClient` - A Viem Public Client, used for onchain read operations.
* `walletClient` (Optional) - A Viem Wallet Client, used for onchain write operations. If not provided, then this Hats Client will support only read operations.
# Onchain Reads
### viewHat
Get a hat's properties.
```typescript
const hat = await hatsClient.viewHat(hatId);
```
***Arguments***:
```typescript
hatId: bigint
```
`hatId` - The hat ID.
***Response***:
```typescript
{
details: string;
maxSupply: number;
supply: number;
eligibility: Address;
toggle: Address;
imageUri: string;
numChildren: number;
mutable: boolean;
active: boolean;
}
```
* `details` - hat's details field.
* `maxSupply` - maximum amount of wearers.
* `supply` - current amount of wearers.
* `eligibility` - hat's eligibility address.
* `toggle` - hat's toggle address.
* `imageUri` - hat's image URI.
* `numChildren` - number of child hats.
* `mutable` - `true` if the hat is mutable, `false` otherwise.
* `active` - `true` if the hat is active, `false` otherwise.
### isWearerOfHat
Check if an address is a wearer of a specific hat. An address is considered a wearer of a hat if the following conditions are met:
* The address owns the hat's token ID (hat ID).
* The hat is active (controlled by the hat's toggle).
* The wearer is eligible for the hat (controlled by the hat's eligibility).
```typescript
const isWearer = await hatsClient.isWearerOfHat({
wearer,
hatId,
});
```
***Arguments***:
```typescript
{
wearer: Address;
hatId: bigint;
}
```
* `wearer` - wearer's address.
* `hatId` - hat's ID.
***Response***:
```typescript
boolean
```
`true` if the given address is a wearer of the hat, `false` otherwise.
### isAdminOfHat
Check if an address is an admin of a specific hat. An address is an admin of a hat if it wears one of the hat's predecessor hats.
```typescript
const isAdmin = await hatsClient.isAdminOfHat({
user,
hatId,
});
```
***Arguments***:
```typescript
{
user: Address;
hatId: bigint;
}
```
* `user` - address to check whether an admin.
* `hatId` - hat's ID.
***Response***:
```typescript
boolean
```
`true` if the given address is an admin of the hat, `false` otherwise.
### isActive
Check if a hat is active.
```typescript
const isActive = await hatsClient.isActive(hatId);
```
***Arguments***:
```typescript
hatId: bigint
```
`hatId` - hat's ID.
***Response***:
```typescript
boolean
```
`true` if the given hat is active, `false` otherwise.
### isInGoodStanding
Check if a wearer is in good standing for a given hat.
```typescript
const isGoodStanding = await hatsClient.isInGoodStanding({
wearer,
hatId,
});
```
***Arguments***:
```typescript
{
wearer: Address;
hatId: bigint;
}
```
* `wearer` - address to check whether in good standing.
* `hatId` - hat's ID.
***Response***:
```typescript
boolean
```
`true` if the given wearer is in good standing, `false` otherwise.
### isEligible
Check if an address is eligible for a specific hat.
```typescript
const isEligible = await hatsClient.isEligible({
wearer,
hatId,
});
```
***Arguments***:
```typescript
{
wearer: Address;
hatId: bigint;
}
```
* `wearer` - address to check whether is eligible.
* `hatId` - hat's ID.
***Response***:
```typescript
boolean
```
`true` if the given address is eligible for the hat, `false` otherwise.
### predictHatId
Predict the ID of a yet to be created hat.
```typescript
const hatId = await hatsClient.predictHatId(admin);
```
***Arguments***:
```typescript
admin: bigint
```
`admin` - parent hat of the would be created one.
***Response***:
```typescript
bigint
```
Hat ID of the would be created hat.
### getTreesCount
Get the number of existing trees.
```typescript
const numTrees = await hatsClient.getTreesCount();
```
***Response***:
```typescript
number
```
Current number of trees.
### getLinkageRequest
Get the linkage request of a tree.
```typescript
const requestedAdminHat = await hatsClient.getLinkageRequest(topHatDomain);
```
***Arguments***:
```typescript
topHatDomain: number
```
`topHatDomain` - the tree domain. The tree domain is the first four bytes of the tophat ID.
***Response***:
```typescript
bigint
```
If request exists, returns the requested new admin hat ID. If not, returns zero.
### getLinkedTreeAdmin
Get the admin of a linked tree (the hat which the tophat is linked to).
```typescript
const adminHat = await hatsClient.getLinkedTreeAdmin(topHatDomain);
```
***Arguments***:
```typescript
topHatDomain: number
```
`topHatDomain` - the tree domain. The tree domain is the first four bytes of the tophat ID.
***Response***:
```typescript
bigint
```
If tree is linked, returns the admin hat ID of the linked tree. If not, returns zero.
### getHatLevel
Get a hat's level. If the tree is linked, level is calculated in the global tree (comprised of all linked trees).
```typescript
const level = await hatsClient.getHatLevel(hatId);
```
***Arguments***:
```typescript
hatId: bigint
```
`hatId` - hat's ID.
***Response***:
```typescript
number
```
The hat's level in the global tree.
### getLocalHatLevel
Get a hat's level in its local tree (without considering linked trees).
```typescript
const level = await hatsClient.getLocalHatLevel(hatId);
```
***Arguments***:
```typescript
hatId: bigint
```
`hatId` - hat's ID.
***Response***:
```typescript
number
```
The hat's local level.
### getTopHatDomain
Get a hat's tree domain.
```typescript
const domain = await hatsClient.getTopHatDomain(hatId);
```
***Arguments***:
```typescript
hatId: bigint
```
`hatId` - hat's ID.
***Response***:
```typescript
number
```
The tree domain of the hat. The tree domain is the first four bytes of the tophat ID.
### getTippyTopHatDomain
Get the tree domain of the global's tree tophat (tippy top hat), which the provided tree is included in.
```typescript
const domain = await hatsClient.getTippyTopHatDomain(topHatDomain);
```
***Arguments***:
```typescript
topHatDomain: number
```
`topHatDomain` - The tree domain. The tree domain is the first four bytes of its tophat ID.
***Response***:
```typescript
number
```
The tree domain of the tippy top hat.
### getAdmin
Get the direct admin of a hat.
```typescript
const admin = await hatsClient.getAdmin(hatId);
```
***Arguments***:
```typescript
hatId: bigint
```
`hatId` - hat's ID.
***Response***:
```typescript
bigint
```
The admin's hat ID. If the provided hat is an unlinked tophat, then this top hat ID is returned, as it is the admin of itself. Otherwise, the hat's parent hat ID is returned.
### getChildrenHats
Get the children hats of a hat.
```typescript
const children = await hatsClient.getChildrenHats(hatId);
```
***Arguments***:
```typescript
hatId: bigint
```
`hatId` - hat's ID.
***Response***:
```typescript
bigint[]
```
The hat's children IDs.
# Onchain Writes
### mintTopHat
Create a new tophat (new tree).
```typescript
const mintTopHatResult = await hatsClient.mintTopHat({
account,
target,
details,
imageURI,
});
```
***Arguments***:
```typescript
{
account: Account | Address;
target: Address;
details: string;
imageURI?: string;
}
```
* `account` - Viem account (Address for JSON-RPC accounts or Account for other types).
* `target` - tophat's wearer address.
* `details` - tophat's details field.
* `imageURI` - optional tophat's image URI.
***Response***:
```typescript
{
status: "success" | "reverted";
transactionHash: `0x${string}`;
hatId: bigint;
}
```
* `status` - "success" if transaction was successful, "reverted" if transaction reverted.
* `transactionHash` - transaction's hash.
* `hatId` - ID of the created tophat.
### createHat
Create a hat.
```typescript
const createHatResult = await hatsClient.createHat({
account,
admin,
details,
maxSupply,
eligibility,
toggle,
mutable,
imageURI,
});
```
***Arguments***:
```typescript
{
account: Account | Address;
admin: bigint;
details: string;
maxSupply: number;
eligibility: Address;
toggle: Address;
mutable: boolean;
imageURI?: string;
}
```
* `account` - Viem account (Address for JSON-RPC accounts or Account for other types).
* `admin` - hat's admin ID.
* `details` - hat's details field.
* `maxSupply` - hat's maximum amount of possible wearers.
* `eligibility` - hat's eligibility address (zero address is not valid).
* `toggle` - hat's toggle address (zero address is not valid).
* `mutable` - true if the hat should be mutable, false otherwise.
* `imageURI` - optional hat's image URI.
***Response***:
```typescript
{
status: "success" | "reverted";
transactionHash: `0x${string}`;
hatId: bigint;
}
```
* `status` - "success" if transaction was successful, "reverted" if transaction reverted.
* `transactionHash` - transaction's hash.
* `hatId` - ID of the created hat.
### batchCreateHats
Create multiple hats.
```typescript
const batchCreateHatsResult = await hatsClient.batchCreateHats({
account,
admins,
details,
maxSupplies,
eligibilityModules,
toggleModules,
mutables,
imageURIs,
});
```
***Arguments***:
```typescript
{
account: Account | Address;
admins: bigint[];
details: string[];
maxSupplies: number[];
eligibilityModules: Address[];
toggleModules: Address[];
mutables: boolean[];
imageURIs?: string[];
}
```
* `account` - Viem account (Address for JSON-RPC accounts or Account for other types).
* `admins` - hats admin IDs.
* `details` - hats details fields.
* `maxSupplies` - hats maximum amounts of possible wearers.
* `eligibilityModules` - hats eligibility addresses (zero address is not valid).
* `toggleModules` - hats toggle addresses (zero address is not valid).
* `mutables` - true if the hat should be mutable, false otherwise.
* `imageURIs` - optional hats image URIs.
***Response***:
```typescript
{
status: "success" | "reverted";
transactionHash: `0x${string}`;
hatIds: bigint[];
}
```
* `status` - "success" if transaction was successful, "reverted" if transaction reverted.
* `transactionHash` - transaction's hash.
* `hatIds` - IDs of the created hats.
### mintHat
Mint a hat.
```typescript
const mintHatResult = await hatsClient.mintHat({
account,
hatId,
wearer,
});
```
***Arguments***:
```typescript
{
account: Account | Address;
hatId: bigint;
wearer: Address;
}
```
* `account` - Viem account (Address for JSON-RPC accounts or Account for other types).
* `hatId` - hat's ID.
* `wearer` - address of the new wearer.
***Response***:
```typescript
{
status: "success" | "reverted";
transactionHash: `0x${string}`;
}
```
* `status` - "success" if transaction was successful, "reverted" if transaction reverted.
* `transactionHash` - transaction's hash.
### batchMintHats
Mint multiple hats.
```typescript
const batchMintHatsResult = await hatsClient.batchMintHats({
account,
hatIds,
wearers,
});
```
***Arguments***:
```typescript
{
account: Account | Address;
hatIds: bigint[];
wearers: Address[];
}
```
* `account` - Viem account (Address for JSON-RPC accounts or Account for other types).
* `hatIds` - hats IDs.
* `wearers` - addresses of the new wearers.
***Response***:
```typescript
{
status: "success" | "reverted";
transactionHash: `0x${string}`;
}
```
* `status` - "success" if transaction was successful, "reverted" if transaction reverted.
* `transactionHash` - transaction's hash.
### setHatStatus
Set a hat's status to active/inactive.
```typescript
const setHatStatusResult = await hatsClient.setHatStatus({
account,
hatId,
newStatus,
});
```
***Arguments***:
```typescript
{
account: Account | Address;
hatId: bigint;
newStatus: boolean;
}
```
* `account` - Viem account (Address for JSON-RPC accounts or Account for other types).
* `hatId` - hat's ID.
* `newStatus` - hat's new status: `true` for active, `false` for inactive.
***Response***:
```typescript
{
status: "success" | "reverted";
transactionHash: `0x${string}`;
}
```
* `status` - "success" if transaction was successful, "reverted" if transaction reverted.
* `transactionHash` - transaction's hash.
### checkHatStatus
Check a hat's status by calling its toggle module, and updating the status as needed.
```typescript
const checkHatStatusResult = await hatsClient.checkHatStatus({
account,
hatId,
});
```
***Arguments***:
```typescript
{
account: Account | Address;
hatId: bigint;
}
```
* `account` - Viem account (Address for JSON-RPC accounts or Account for other types).
* `hatId` - hat's ID.
***Response***:
```typescript
{
status: "success" | "reverted";
transactionHash: `0x${string}`;
toggled: boolean;
newStatus?: "active" | "inactive";
}
```
* `status` - "success" if transaction was successful, "reverted" if transaction reverted.
* `transactionHash` - transaction's hash.
* `toggled` - true if the hat's status was changed (toggled), false otherwise.
* `newStatus` - if hat's status was changed (toggled), then contains its new status.
### setHatWearerStatus
Set a hat's wearer status.
```typescript
const setHatWearerStatusResult = await hatsClient.setHatWearerStatus({
account,
hatId,
wearer,
eligible,
standing,
});
```
***Arguments***:
```typescript
{
account: Account | Address;
hatId: bigint;
wearer: Address;
eligible: boolean;
standing: boolean;
}
```
* `account` - Viem account (Address for JSON-RPC accounts or Account for other types).
* `hatId` - hat's ID.
* `wearer` - wearer address.
* `eligible` - wearer's eligibility. `true` for eligible, `false` otherwise.
* `standing` - wearer's standing. `true` for good, `false` for bad.
***Response***:
```typescript
{
status: "success" | "reverted";
transactionHash: `0x${string}`;
}
```
* `status` - "success" if transaction was successful, "reverted" if transaction reverted.
* `transactionHash` - transaction's hash.
### checkHatWearerStatus
Check a hat's wearer status by calling the hat's eligibility module. If the wearer is non eligible and/or in bad standing, then its hat is burned.
```typescript
const checkHatWearerStatusResult = await hatsClient.checkHatWearerStatus({
account,
hatId,
wearer,
});
```
***Arguments***:
```typescript
{
account: Account | Address;
hatId: bigint;
wearer: Address;
}
```
* `account` - Viem account (Address for JSON-RPC accounts or Account for other types).
* `hatId` - hat's ID.
* `wearer` - wearer address.
***Response***:
```typescript
{
status: "success" | "reverted";
transactionHash: `0x${string}`;
wearerStandingUpdated: boolean;
hatBurned: boolean;
newWearerStanding?: "good" | "bad";
}
```
* `status` - "success" if transaction was successful, "reverted" if transaction reverted.
* `transactionHash` - Transaction's hash.
* `wearerStandingUpdated` - `true` if the wearer's standing was changed (toggled), `false` otherwise.
* `hatBurned` - `true` if the wearer's hat was burned in the transaction, `false` otherwise.
* `newWearerStanding` - if the wearer standing was changed, then contains the new standing status.
### renounceHat
Renounce a hat. This action burns the hat for the renouncing wearer (the caller).
```typescript
const renounceHatResult = await hatsClient.renounceHat({
account,
hatId,
});
```
***Arguments***:
```typescript
{
account: Account | Address;
hatId: bigint;
}
```
* `account` - Viem account (Address for JSON-RPC accounts or Account for other types).
* `hatId` - hat's ID.
***Response***:
```typescript
{
status: "success" | "reverted";
transactionHash: `0x${string}`;
}
```
* `status` - "success" if transaction was successful, "reverted" if transaction reverted.
* `transactionHash` - transaction's hash.
### transferHat
Transfer a hat from one wearer to another.
```typescript
const transferHatResult = await hatsClient.transferHat({
account,
hatId,
from,
to,
});
```
***Arguments***:
```typescript
{
account: Account | Address;
hatId: bigint;
from: Address;
to: Address;
}
```
* `account` - Viem account (Address for JSON-RPC accounts or Account for other types).
* `hatId` - hat's ID.
* `from` - current wearer address.
* `to` - new wearer address.
***Response***:
```typescript
{
status: "success" | "reverted";
transactionHash: `0x${string}`;
}
```
* `status` - "success" if transaction was successful, "reverted" if transaction reverted.
* `transactionHash` - transaction's hash.
### makeHatImmutable
Make a hat immutable.
```typescript
const makeHatImmutableResult = await hatsClient.makeHatImmutable({
account,
hatId,
});
```
***Arguments***:
```typescript
{
account: Account | Address;
hatId: bigint;
}
```
* `account` - Viem account (Address for JSON-RPC accounts or Account for other types).
* `hatId` - hat's ID.
***Response***:
```typescript
{
status: "success" | "reverted";
transactionHash: `0x${string}`;
}
```
* `status` - "success" if transaction was successful, "reverted" if transaction reverted.
* `transactionHash` - transaction's hash.
### changeHatDetails
Change a hat's details.
```typescript
const changeHatDetailsResult = await hatsClient.changeHatDetails({
account,
hatId,
newDetails,
});
```
***Arguments***:
```typescript
{
account: Account | Address;
hatId: bigint;
newDetails: string;
}
```
* `account` - Viem account (Address for JSON-RPC accounts or Account for other types).
* `hatId` - hat's ID.
* `newDetails` - hat's new details.
***Response***:
```typescript
{
status: "success" | "reverted";
transactionHash: `0x${string}`;
}
```
* `status` - "success" if transaction was successful, "reverted" if transaction reverted.
* `transactionHash` - transaction's hash.
### changeHatEligibility
Change a hat's eligibility.
```typescript
const changeHatEligibilityResult = await hatsClient.changeHatEligibility({
account,
hatId,
newEligibility,
});
```
***Arguments***:
```typescript
{
account: Account | Address;
hatId: bigint;
newEligibility: Address;
}
```
* `account` - Viem account (Address for JSON-RPC accounts or Account for other types).
* `hatId` - hat's ID.
* `newEligibility` - hat's new eligibility.
***Response***:
```typescript
{
status: "success" | "reverted";
transactionHash: `0x${string}`;
}
```
* `status` - "success" if transaction was successful, "reverted" if transaction reverted.
* `transactionHash` - transaction's hash.
### changeHatToggle
Change a hat's toggle.
```typescript
const changeHatToggleResult = await hatsClient.changeHatToggle({
account,
hatId,
newToggle,
});
```
***Arguments***:
```typescript
{
account: Account | Address;
hatId: bigint;
newToggle: Address;
}
```
* `account` - Viem account (Address for JSON-RPC accounts or Account for other types).
* `hatId` - hat's ID.
* `newToggle` - hat's new toggle.
***Response***:
```typescript
{
status: "success" | "reverted";
transactionHash: `0x${string}`;
}
```
* `status` - "success" if transaction was successful, "reverted" if transaction reverted.
* `transactionHash` - transaction's hash.
### changeHatImageURI
Change a hat's image URI.
```typescript
const changeHatImageURIResult = await hatsClient.changeHatImageURI({
account,
hatId,
newImageURI,
});
```
***Arguments***:
```typescript
{
account: Account | Address;
hatId: bigint;
newImageURI: string;
}
```
* `account` - Viem account (Address for JSON-RPC accounts or Account for other types).
* `hatId` - hat's ID.
* `newImageURI` - hat's new image URI.
***Response***:
```typescript
{
status: "success" | "reverted";
transactionHash: `0x${string}`;
}
```
* `status` - "success" if transaction was successful, "reverted" if transaction reverted.
* `transactionHash` - transaction's hash.
### changeHatMaxSupply
Change a hat's maximum supply.
```typescript
const changeHatMaxSupplyResult = await hatsClient.changeHatMaxSupply({
account,
hatId,
newMaxSupply,
});
```
***Arguments***:
```typescript
{
account: Account | Address;
hatId: bigint;
newMaxSupply: number;
}
```
* `account` - Viem account (Address for JSON-RPC accounts or Account for other types).
* `hatId` - hat's ID.
* `newMaxSupply` - hat's new maximum supply.
***Response***:
```typescript
{
status: "success" | "reverted";
transactionHash: `0x${string}`;
}
```
* `status` - "success" if transaction was successful, "reverted" if transaction reverted.
* `transactionHash` - transaction's hash.
### requestLinkTopHatToTree
Request a link from a tophat to a new admin hat.
```typescript
const requestLinkTopHatToTreeResult = await hatsClient.requestLinkTopHatToTree({
account,
topHatDomain,
requestedAdminHat,
});
```
***Arguments***:
```typescript
{
account: Account | Address;
topHatDomain: number;
requestedAdminHat: bigint;
}
```
* `account` - Viem account (Address for JSON-RPC accounts or Account for other types).
* `topHatDomain` - the tree domain of the requesting tree. The tree domain is the first four bytes of the tophat ID.
* `requestedAdminHat` - ID of the requested new admin hat.
***Response***:
```typescript
{
status: "success" | "reverted";
transactionHash: `0x${string}`;
}
```
* `status` - "success" if transaction was successful, "reverted" if transaction reverted.
* `transactionHash` - transaction's hash.
### approveLinkTopHatToTree
Approve a tophat's linkage request.
```typescript
const approveLinkTopHatToTreeResult = await hatsClient.approveLinkTopHatToTree({
account,
topHatDomain,
newAdminHat,
newEligibility,
newToggle,
newDetails,
newImageURI,
});
```
***Arguments***:
```typescript
{
account: Account | Address;
topHatDomain: number;
newAdminHat: bigint;
newEligibility?: Address;
newToggle?: Address;
newDetails?: string;
newImageURI?: string;
}
```
* `account` - Viem account (Address for JSON-RPC accounts or Account for other types).
* `topHatDomain` - the tree domain of the requesting tree. The tree domain is the first four bytes of the tophat ID.
* `newAdminHat` - ID of the new admin hat.
* `newEligibility` - optional new eligibility for the linked tophat.
* `newToggle` - optional new toggle for the linked tophat.
* `newDetails` - optional new details for the linked tophat.
* `newImageURI` - optional new image URI for the linked tophat.
***Response***:
```typescript
{
status: "success" | "reverted";
transactionHash: `0x${string}`;
}
```
* `status` - "success" if transaction was successful, "reverted" if transaction reverted.
* `transactionHash` - transaction's hash.
### unlinkTopHatFromTree
Unlink a tree.
```typescript
const unlinkTopHatFromTreeResult = await hatsClient.unlinkTopHatFromTree({
account,
topHatDomain,
wearer,
});
```
***Arguments***:
```typescript
{
account: Account | Address;
topHatDomain: number;
wearer: Address;
}
```
* `account` - Viem account (Address for JSON-RPC accounts or Account for other types).
* `topHatDomain` - the tree domain. The tree domain is the first four bytes of the tophat ID.
* `wearer` - The current wearer of the tophat that is about to be unlinked.
***Response***:
```typescript
{
status: "success" | "reverted";
transactionHash: `0x${string}`;
}
```
* `status` - "success" if transaction was successful, "reverted" if transaction reverted.
* `transactionHash` - transaction's hash.
### relinkTopHatWithinTree
Relink a tree within the same global tree that it is already part of.
```typescript
const relinkTopHatWithinTreeResult = await hatsClient.relinkTopHatWithinTree({
account,
topHatDomain,
newAdminHat,
newEligibility,
newToggle,
newDetails,
newImageURI,
});
```
***Arguments***:
```typescript
{
account: Account | Address;
topHatDomain: number;
newAdminHat: bigint;
newEligibility?: Address;
newToggle?: Address;
newDetails?: string;
newImageURI?: string;
}
```
* `account` - Viem account (Address for JSON-RPC accounts or Account for other types).
* `topHatDomain` - the tree domain of the relinked tree. The tree domain is the first four bytes of the tophat ID.
* `newAdminHat` - ID of the new admin hat.
* `newEligibility` - optional new eligibility for the linked tophat.
* `newToggle` - optional new toggle for the linked tophat.
* `newDetails` - optional new details for the linked tophat.
* `newImageURI` - optional new image URI for the linked tophat.
***Response***:
```typescript
{
status: "success" | "reverted";
transactionHash: `0x${string}`;
}
```
* `status` - "success" if transaction was successful, "reverted" if transaction reverted.
* `transactionHash` - transaction's hash.
# Multicall
For any write function, the SDK includes a corresponding call data version that returns the call data information instead of submitting a transaction. These objects can then be aggregated and passed into the [`multicall`](#multicall) function in order to batch multiple operations into one transaction.
### multicall
Batch multiple write operations in one transaction.
```typescript
const multicallResult = await hatsClient.multicall({
account,
calls,
});
```
***Arguments***:
```typescript
{
account: Account | Address;
calls: {
functionName: string;
callData: Hex;
}[];
}
```
* `account` - Viem account (Address for JSON-RPC accounts or Account for other types).
* `calls` - An array of call data objects, each one includes the function name and the call data to pass to the function.
***Response***:
```typescript
{
status: "success" | "reverted";
transactionHash: `0x${string}`;
gasUsed: bigint;
hatsCreated: bigint[];
hatsMinted: {
hatId: bigint;
wearer: `0x${string}`;
}[];
hatsBurned: {
hatId: bigint;
wearer: `0x${string}`;
}[];
hatStatusChanges: {
hatId: bigint;
newStatus: "active" | "inactive";
}[];
wearerStandingChanges: {
hatId: bigint;
wearer: `0x${string}`;
newStanding: "good" | "bad";
}[];
}
```
* `status` - "success" if transaction was successful, "reverted" if transaction reverted.
* `transactionHash` - transaction's hash.
* `gasUsed` - Amount of gas used in the transaction.
* `hatsCreated` - Hats IDs of any newly created hats.
* `hatsMinted` - For every hat minted, contains an object with the hat ID and the new wearer address.
* `hatsBurned` - For every hat burned, contains an object with the hat ID and the wearer address.
* `hatStatusChanges` - For every hat status change, contains on object with the hat ID and the new status.
* `wearerStandingChanges` - For every wearer standing status change, contains an object with the hat ID, the wearer address and the new standing.
***Example:***
Create a new top-hat, then create one child hat and mint the child hat to a new wearer.
```typescript
const mintTopHatCallData = await hatsClient.mintTopHatCallData({
target,
details,
imageURI,
});
const createHatCallData = await hatsClient.createHatCallData({
admin,
details,
maxSupply,
eligibility,
toggle,
mutable,
imageURI,
});
const mintHatCallData = await hatsClient.mintHatCallData({
hatId,
wearer,
});
const multiCallResult = await hatsClient.multicall({
account,
calls: [mintTopHatCallData, createHatCallData, mintHatCallData],
});
```
### multicallPreFlightCheck
Simulates the multicall function with the provided calls. The function has no return value, will revert on failure, with a custom error.
await hatsClient.multicallPreFlightCheck({
account,
calls,
});
***Arguments***:
```typescript
{
account: Account | Address;
calls: {
functionName: string;
callData: Hex;
}[];
}
```
* `account` - Viem account (Address for JSON-RPC accounts or Account for other types).
* `calls` - An array of call data objects, each one includes the function name and the call data to pass to the function.
# Claiming Hats
Hats can be made claimable by using the [Multi Claims Hatter](/hats-integrations/hatter-modules/making-hats-claimable) module.
The following functions support the claiming functionality enabled by this module.
### accountCanClaim
Check whether an account can claim a given hat.
```typescript
const canClaim = await hatsClient.accountCanClaim({
hatId,
account,
});
```
***Arguments***:
```typescript
{
hatId: bigint;
account: Address;
}
```
* `hatId` - The hat ID to claim.
* `account` - The claiming account's address.
***Response***:
```typescript
boolean
```
`true` if can claim, `false` otherwise.
### canClaimForAccount
Check whether a hat can be claimed on behalf of a given account.
```typescript
const canClaimFor = await hatsClient.canClaimForAccount({
hatId,
account,
});
```
***Arguments***:
```typescript
{
hatId: bigint;
account: Address;
}
```
* `hatId` - The hat ID to claim-for.
* `account` - The account address to claim on behalf of.
***Response***:
```typescript
boolean
```
`true` if can claim-for, `false` otherwise.
### claimHat
Claim a hat for the calling account.
```typescript
const claimHatResult = await hatsClient.claimHat({
account,
hatId,
});
```
***Arguments***:
```typescript
{
account: Account | Address;
hatId: bigint;
}
```
* `account` - Viem account (Address for JSON-RPC accounts or Account for other types).
* `hatId` - ID of the hat to claim.
***Response***:
```typescript
{
status: "success" | "reverted";
transactionHash: `0x${string}`;
}
```
* `status` - "success" if transaction was successful, "reverted" if transaction reverted.
* `transactionHash` - transaction's hash.
### claimHatFor
Claim a hat on behalf of a chosen account.
```typescript
const claimHatForResult = await hatsClient.claimHatFor({
account,
hatId,
wearer,
});
```
***Arguments***:
```typescript
{
account: Account | Address;
hatId: bigint;
wearer: Address;
}
```
* `account` - Viem account (Address for JSON-RPC accounts or Account for other types).
* `hatId` - ID of the hat to claim-for.
* `wearer` - Address for which to claim the hat for.
***Response***:
```typescript
{
status: "success" | "reverted";
transactionHash: `0x${string}`;
}
```
* `status` - "success" if transaction was successful, "reverted" if transaction reverted.
* `transactionHash` - transaction's hash.
### multiClaimHatFor
Claim a hat on behalf of multiple accounts.
```typescript
const claimHatForResult = await hatsClient.multiClaimHatFor({
account,
hatId,
wearers,
});
```
***Arguments***:
```typescript
{
account: Account | Address;
hatId: bigint;
wearers: Address[];
}
```
* `account` - Viem account (Address for JSON-RPC accounts or Account for other types).
* `hatId` - ID of the hat to claim-for.
* `wearers` - Addresses for which to claim the hat for.
***Response***:
```typescript
{
status: "success" | "reverted";
transactionHash: `0x${string}`;
}
```
* `status` - "success" if transaction was successful, "reverted" if transaction reverted.
* `transactionHash` - transaction's hash.
# Utilities
## Hat & Tree ID Utils
Following are utility functions to handle various hat & tree ID formats. More information about hat IDs can be found [here](/for-developers/hats-protocol-for-developers/hat-ids).
### hatIdDecimalToHex
Convert a hat ID from decimal to hex.
```typescript
import { hatIdDecimalToHex } from "@hatsprotocol/sdk-v1-core";
const hatIdHex = hatIdDecimalToHex(hatId);
```
***Arguments***:
```typescript
hatId: bigint
```
`hatId` - Hat ID in decimal format.
***Response***:
```typescript
`0x${string}`
```
Hat ID in a hex format.
### hatIdHexToDecimal
Convert a hat ID from hex to decimal.
```typescript
import { hatIdHexToDecimal } from "@hatsprotocol/sdk-v1-core";
const hatIdDecimal = hatIdHexToDecimal(hatId);
```
***Arguments***:
```typescript
hatId: string
```
`hatId` - Hat ID in hex format.
***Response***:
```typescript
bigint
```
Hat ID in a decimal format.
### treeIdDecimalToHex
Convert a tree ID from decimal to hex. A tree ID is the first 4 bytes in a hat ID.
```typescript
import { treeIdDecimalToHex } from "@hatsprotocol/sdk-v1-core";
const treeIdHex = treeIdDecimalToHex(treeId);
```
***Arguments***:
```typescript
treeId: number
```
`treeId` - Tree ID in decimal format.
***Response***:
```typescript
`0x${string}`
```
Tree ID in a hex format.
### treeIdHexToDecimal
Convert a tree ID from hex to decimal. A tree ID is the first 4 bytes in a hat ID.
```typescript
import { treeIdHexToDecimal } from "@hatsprotocol/sdk-v1-core";
const treeIdDecimal = treeIdHexToDecimal(treeId);
```
***Arguments***:
```typescript
treeId: string
```
`treeId` - Tree ID in hex format.
***Response***:
```typescript
number
```
Tree ID in a decimal format.
### treeIdToTopHatId
Convert a tree ID to its top-hat ID. A tree ID is the first 4 bytes in a hat ID.
```typescript
import { treeIdToTopHatId } from "@hatsprotocol/sdk-v1-core";
const tophatId = treeIdToTopHatId(treeId);
```
***Arguments***:
```typescript
treeId: number
```
`treeId` - Tree ID in decimal format.
***Response***:
```typescript
bigint
```
Top-hat ID in decimal format.
### hatIdToTreeId
Convert a hat ID to its tree ID. A tree ID is the first 4 bytes in a hat ID.
```typescript
import { hatIdToTreeId } from "@hatsprotocol/sdk-v1-core";
const treeId = hatIdToTreeId(hatId);
```
***Arguments***:
```typescript
hatId: bigint
```
`hatId` - Hat ID in decimal format.
***Response***:
```typescript
number
```
Tree ID of the hat, in a decimal format.
### hatIdDecimalToIp
The IP format may be used as a "pretty" hat ID format for presenting.
For example, a hat with a hex ID of:\
`0x00000001000a0002000000000000000000000000000000000000000000000000` will have an IP format of 1.10.2 - Each level is separated by a dot and presented as a decimal number, excluding zeros.
```typescript
import { hatIdDecimalToIp } from "@hatsprotocol/sdk-v1-core";
const hatIdIp = hatIdDecimalToIp(hatId);
```
***Arguments***:
```typescript
hatId: bigint
```
`hatId` - Hat ID in decimal format.
***Response***:
```typescript
string
```
Hat ID in IP format.
### hatIdIpToDecimal
Convert a hat ID from an IP format, to a decimal format.
import { hatIdIpToDecimal } from "@hatsprotocol/sdk-v1-core";
const hatIdDecimal = hatIdIpToDecimal(hatId);
***Arguments***:
```typescript
hatId: string
```
`hatId` - Hat ID in IP format.
***Response***:
```typescript
bigint
```
Hat ID in decimal format.
## Constants
Following are Hats-specific exported constant values.
import {
HATS_V1, // Hats-Protocol v1 contract address
MAX_LEVELS, // Max levels on a Hats tree
MAX_LEVEL_HATS, // Max amount of hats on each level (excluding level 0)
ZERO_ID, // The zero Hat ID in hex format
FALLBACK_ADDRESS, // The fallback address for eligibility and toggle
} from "@hatsprotocol/sdk-v1-core";
# Subgraph
## Overview
The SDK is an open source JavaScript client, providing utility functions for fetching data from the [Hats Protocol Subgraphs](/for-developers/v1-subgraphs) and is designed to work both in the browser and in Node.js.
{% content-ref url="/pages/ueP5evorHYPtLEgmBD2c" %}
[Getting Started](/for-developers/v1-sdk/subgraph/getting-started)
{% endcontent-ref %}
{% content-ref url="/pages/4VC5sGonIBmG2zIf78Bz" %}
[Fetching Hats](/for-developers/v1-sdk/subgraph/fetching-hats)
{% endcontent-ref %}
{% content-ref url="/pages/eViws1fSgrvWtPG98JHk" %}
[Fetching Wearers](/for-developers/v1-sdk/subgraph/fetching-wearers)
{% endcontent-ref %}
{% content-ref url="/pages/3452M4ahmHjfTyFMuMao" %}
[Fetching Trees](/for-developers/v1-sdk/subgraph/fetching-trees)
{% endcontent-ref %}
{% content-ref url="/pages/NcXAPNatBNTsPzQYGtgM" %}
[Misc](/for-developers/v1-sdk/subgraph/misc)
{% endcontent-ref %}
{% content-ref url="/pages/pg8eDgunNcJK3PMI2Exz" %}
[Types](/for-developers/v1-sdk/subgraph/types)
{% endcontent-ref %}
# Getting Started
### *Install*
yarn:
```bash
yarn add @hatsprotocol/sdk-v1-subgraph
```
npm:
```bash
npm install @hatsprotocol/sdk-v1-subgraph
```
### *HatsSubgraphClient Initialization*
Import and initialize HatsSubgraphClient.
Optionally configure the Subgraph endpoints to use, or use the default ones.
```typescript
import { HatsSubgraphClient } from "@hatsprotocol/sdk-v1-subgraph";
const hatsSubgraphClient = new HatsSubgraphClient({
config
});
```
***Arguments***:
```typescript
{ config?: EndpointsConfig }
```
* `config` - Optional subgraph endpoints configuration. If not provided, then the default, un-gated development endpoints will be used. See the `EndpointsConfig` type [here](/for-developers/v1-sdk/subgraph/types#endpointsconfig).
# Fetching Hats
### getHat
Get a Hat by its ID.
```typescript
const hat = await hatsSubgraphClient.getHat({
chainId,
hatId,
props,
});
```
***Arguments***:
```typescript
{
chainId: number;
hatId: bigint;
props: HatPropsConfig;
}
```
* `chainId` - ID of the chain to fetch from.
* `hatId` - ID of the Hat to fetch.
* `props` - Hat's properties to fetch, including the ones of nested objects. Check the [HatPropsConfig](/for-developers/v1-sdk/subgraph/types#hatpropsconfig) type for the available properties and query filters.
***Response***:
```typescript
Hat
```
A [Hat object](/for-developers/v1-sdk/subgraph/types#hat), containing the chosen properties.
***Example***:
```typescript
const res = await client.getHat({
chainId: 10, // optimism
hatId: BigInt(
"0x0000000100020001000100000000000000000000000000000000000000000000"
),
props: {
maxSupply: true, // get the maximum amount of wearers for the hat
wearers: { // get the hat's wearers
props: {}, // for each wearer, include only its ID (address)
},
events: { // get the hat's events
props: {
transactionID: true, // for each event, include the transaction ID
},
filters: {
first: 10, // fetch only the latest 10 events
},
},
},
});
```
### getHatsByIds
Get Hats by their IDs.
const hats = await hatsSubgraphClient.getHatsByIds({
chainId,
hatIds,
props,
});
***Arguments***:
```typescript
{
chainId: number;
hatIds: bigint[];
props: HatPropsConfig;
}
```
* `chainId` - ID of the chain to fetch from.
* `hatIds` - IDs of the Hats to fetch.
* `props` - Hat's properties to fetch, including the ones of nested objects. Check the [HatPropsConfig](/for-developers/v1-sdk/subgraph/types#hatpropsconfig) type for the available properties and query filters.
***Response***:
```typescript
Hat[]
```
An array of [Hat objects](/for-developers/v1-sdk/subgraph/types#hat), containing the chosen properties.
***Example***:
```typescript
const res = await client.getHatsByIds({
chainId: 10, // optimism
hatIds: [
BigInt("0x0000000100020001000100000000000000000000000000000000000000000000"),
BigInt("0x0000000100020001000000000000000000000000000000000000000000000000"),
],
props: {
wearers: { // get each hat's wearers
props: {
currentHats: { // for each wearer, get its hats
props: {}, // for each hat, include only its ID
},
},
},
},
});
```
# Fetching Wearers
### getWearer
Get a Wearer by its address.
```typescript
const wearer = await hatsSubgraphClient.getWearer({
chainId,
wearerAddress,
props,
});
```
***Arguments***:
```typescript
{
chainId: number;
wearerAddress:`0x${string}`;
props: WearerPropsConfig;
}
```
* `chainId` - ID of the chain to fetch from.
* `wearerAddress` - Wearer's address.
* `props` - Wearer's properties to fetch, including the ones of nested objects. Check the [WearerPropsConfig](/for-developers/v1-sdk/subgraph/types#wearerpropsconfig) type for the available properties and query filters.
***Response***:
```typescript
Wearer
```
A [Wearer object](/for-developers/v1-sdk/subgraph/types#wearer), containing the chosen properties.
***Example:***
```typescript
const res = await client.getWearer({
chainId: 10, // optimism
wearerAddress: "0x1230000000000000000000000000000000000000",
props: {
currentHats: { // get the wearer's hats
props: {
status: true, // for each hat, include its status (active/inactive)
},
},
mintEvent: { // get the wearer's hat minting events
props: {
blockNumber: true, // for each event, include its block number
},
filters: {
first: 1, // fetch only the latest event
},
},
},
});
```
### getWearersOfHatPaginated
Paginate over the Wearers of a Hat.
```typescript
const wearers = await hatsSubgraphClient.getWearersOfHatPaginated({
chainId,
hatId,
props,
page,
perPage,
});
```
***Arguments***:
```typescript
{
chainId: number;
hatId: bigint;
props: WearerPropsConfig;
page: number;
perPage: number;
}
```
* `chainId` - ID of the chain to fetch from.
* `hatId` - ID of the hat of which wearers to fetch.
* `props` - Wearer's properties to fetch, including the ones of nested objects. Check the [WearerPropsConfig](/for-developers/v1-sdk/subgraph/types#wearerpropsconfig) type for the available properties and query filters.
* `page` - Number of page to fetch.
* `perPage` - Number of Wearers to fetch in each page.
***Response***:
```typescript
Wearer[]
```
An array of [Wearer objects](/for-developers/v1-sdk/subgraph/types#wearer), containing the chosen properties.
***Example:***
```typescript
// get the first 10 wearers of a given hat
const res = await client.getWearersOfHatPaginated({
chainId: 10,
props: {}, // for each wearer, include only its ID (address)
hatId: BigInt("0x0000000100020001000100000000000000000000000000000000000000000000"),
page: 0,
perPage: 10,
});
```
---
[Next Page](/llms-full.txt/1)
