Skip to main content

On-Chain Holder/Wallet Management

Active Holder/Wallet management is conducted on-chain and autonomously, with multiple admin configurations that allow flexibility of transfer rule configuration. This greatly simplifies the off-chain accounting and effort required from Transfer (and other) Admins, removing the need to track Wallet holdings across different Holders.

Wallets are not programatically prohibited from assuming multiple Admin roles. We advise against this in practice; however, this must be enforced off-chain.

Holders are allowed to keep multiple Wallet addresses, which can be spread across multiple Transfer Groups (in which case, they would be added to each group's holder count) as well as within Transfer Groups. These Wallets are consolidated under a common holderId.

  • Ex.: Holder A can have 4 wallets spread across two Transfer Groups, X and Y. The Holder can have Wallets 1 & 2 in Group X, and Wallets 3 & 4 in Group Y. They will still count overall as one single Holder, but it will also be considered as a unique holder in Group X and one unique holder in Group Y.

To manage these Holders and their Wallets:

  • A hook has been overridden (_update) for mint/transfer/burn/freeze functions, automatically checking that recipient Wallet addresses of tokens are cataloged and assigned holderIds as needed.
  • If a "new" Wallet address receives a token, a new holderId is created for that Wallet address.
  • Admins can also separately create Holders from Wallet addresses and append Wallet addresses to existing Holder accounts

Maximum Number of Holders Allowed​

A single Holder may have unlimited Wallet addresses. This cannot be altered. The Issuer can only configure the maximum number of Holders allowed (via Transfer Admin) by calling setHolderMax. By default, this limit is set to 2**255-1.

setHolderMax(amount)

Remove holder and wallet from holder​

To efficiently remove unused holders and their associated wallets, transfer or wallet admins can call the removeHolder function, which iterates through all linked wallets and removes them. However, for holders with unusually large number of wallets, to avoid reaching block gas limit, it is possible first using batchRemoveWalletFromHolder and then calling removeHolder. If a user does not have ownership of a specific wallet, it can still be removed from the holder's list individually using the removeWalletFromHolder function.