# (EVM) Name Token Contract API Abstract base contract for name NFTs in the DOMA protocol. *This contract implements an ERC721 NFT that represents tokenized names. Features include expiration tracking, transfer locking, name capabilities management, royalty support (ERC2981), and integration with proxy DOMA record contracts.* {% file src="" %} OwnershipToken Contract ABI {% endfile %} ## Errors #### TransferLocked ```solidity error TransferLocked(uint256 tokenId) ``` Thrown when attempting to transfer a token that is locked for transfers. **Parameters** | Name | Type | Description | | ------- | ------- | -------------------------- | | tokenId | uint256 | The ID of the locked token | #### OwnerBurnNotSupported ```solidity error OwnerBurnNotSupported() ``` Thrown when owner attempts to use burn functionality that is not supported. #### ProxyDomaRecordNotSet ```solidity error ProxyDomaRecordNotSet() ``` Thrown when proxy DOMA record address is not set but required for operation. #### ZeroAddress ```solidity error ZeroAddress() ``` Thrown when a zero address is provided where a valid address is required. #### InvalidRoyaltyReceiver ```solidity error InvalidRoyaltyReceiver() ``` Thrown when an invalid royalty receiver address is provided. #### InvalidRoyaltyFraction ```solidity error InvalidRoyaltyFraction(uint96 feeNumerator, uint96 feeDenominator) ``` Thrown when royalty fraction exceeds the maximum allowed value. **Parameters** | Name | Type | Description | | -------------- | ------ | -------------------------------------------- | | feeNumerator | uint96 | The provided fee numerator | | feeDenominator | uint96 | The fee denominator (10000 for basis points) | #### ArrayLengthMismatch ```solidity error ArrayLengthMismatch() ``` Thrown when array parameters have mismatched lengths. ## Events #### OwnershipTokenMinted ```solidity event OwnershipTokenMinted(uint256 tokenId, uint256 registrarIanaId, address to, string sld, string tld, uint256 expiresAt, string correlationId) ``` Emitted when an ownership token is minted. Emitted together with standard ERC-721 Transfer event, but contains additional information. **Parameters** | Name | Type | Description | | --------------- | ------- | --------------------------------------------------------------------------------------------- | | tokenId | uint256 | The ID of the ownership token. | | registrarIanaId | uint256 | The IANA ID of a sponsoring registrar. | | to | address | The address that received the ownership token. | | sld | string | The second-level domain of the name. E.g. "example" in "example.com". | | tld | string | The top-level domain of the name. E.g. "com" in "example.com". | | expiresAt | uint256 | The expiration date of the name (UNIX seconds). | | correlationId | string | Correlation id associated with a mint event. Used by registrars to track on-chain operations. | #### NameTokenRenewed ```solidity event NameTokenRenewed(uint256 tokenId, uint256 expiresAt, string correlationId) ``` Emitted when name token is renewed. **Parameters** | Name | Type | Description | | ------------- | ------- | ------------------------------------------------------------------------------------------------ | | tokenId | uint256 | The ID of the name token. | | expiresAt | uint256 | The expiration date of the name token (UNIX seconds). | | correlationId | string | Correlation id associated with a renewal event. Used by registrars to track on-chain operations. | #### NameTokenBurned ```solidity event NameTokenBurned(uint256 tokenId, address owner, string correlationId) ``` Emitted when name token is burned. Similar to ERC721 `Transfer` event with zero `to`, but with an additional correlation id included. **Parameters** | Name | Type | Description | | ------------- | ------- | --------------------------------------------------------------------------------------------- | | tokenId | uint256 | The ID of the name token. | | owner | address | Owner address at the time of burning. | | correlationId | string | Correlation id associated with a burn event. Used by registrars to track on-chain operations. | #### LockStatusChanged ```solidity event LockStatusChanged(uint256 tokenId, bool isTransferLocked, string correlationId) ``` Emitted when name token is locked or unlocked. **Parameters** | Name | Type | Description | | ---------------- | ------- | ----------------------------------------------------------------------------------------------------------- | | tokenId | uint256 | The ID of the name token. | | isTransferLocked | bool | Whether token transfer is locked or not. | | correlationId | string | Correlation id associated with a lock status change event. Used by registrars to track on-chain operations. | #### MetadataUpdate ```solidity event MetadataUpdate(uint256 tokenId) ``` Emitted when metadata is updated for a token. Can happen when token is renewed. Follows IERC4906 Metadata Update Extension. #### DomainCapabilitiesUpdated ```solidity event DomainCapabilitiesUpdated(uint256 tokenId, uint256 capabilities, string correlationId) ``` Emitted when domain-level capabilities are updated for a token. **Parameters** | Name | Type | Description | | ------------- | ------- | --------------------------------------- | | tokenId | uint256 | The ID of the name token. | | capabilities | uint256 | The new domain capabilities bitmask. | | correlationId | string | Correlation id for tracking operations. | #### burn ```solidity function burn(uint256) public virtual ``` User-initiated burn is not supported. *This override prevents direct token burning by users. Only the bulkBurn function should be used by authorized minters to ensure proper cleanup and event emission. Base class (ERC721BurnableUpgradeable) is kept for compatibility with previous storage layout.* #### expirationOf ```solidity function expirationOf(uint256 id) external view returns (uint256) ``` Returns expiration date for a token. After this date, token transfer will be blocked. **Parameters** | Name | Type | Description | | ---- | ------- | ----------- | | id | uint256 | Token ID. | **Return Values** | Name | Type | Description | | ---- | ------- | ---------------------------------- | | \[0] | uint256 | uint256 Unix timestamp in seconds. | #### registrarOf ```solidity function registrarOf(uint256 id) external view returns (uint256) ``` Returns registrar IANA ID for a token. **Parameters** | Name | Type | Description | | ---- | ------- | ----------- | | id | uint256 | Token ID. | **Return Values** | Name | Type | Description | | ---- | ------- | -------------------------- | | \[0] | uint256 | uint256 Registrar IANA ID. | #### lockStatusOf ```solidity function lockStatusOf(uint256 id) external view returns (bool) ``` Returns transfer lock status for a token. If 'true', token cannot be transferred. **Parameters** | Name | Type | Description | | ---- | ------- | ----------- | | id | uint256 | Token ID. | #### domainCapabilitiesOf ```solidity function domainCapabilitiesOf(uint256 id) external view returns (uint256) ``` Returns domain-level capabilities for a token. These are the capabilities supported by this specific domain. **Parameters** | Name | Type | Description | | ---- | ------- | ----------- | | id | uint256 | Token ID. | **Return Values** | Name | Type | Description | | ---- | ------- | ------------------------------------ | | \[0] | uint256 | uint256 Domain capabilities bitmask. | #### hasCapability ```solidity function hasCapability(uint256 id, uint256 requiredCapability) external view returns (bool) ``` Check if a token has a specific capability. **Parameters** | Name | Type | Description | | ------------------ | ------- | --------------------------------- | | id | uint256 | Token ID. | | requiredCapability | uint256 | The required capability bit mask. | **Return Values** | Name | Type | Description | | ---- | ---- | ------------------------------------------ | | \[0] | bool | bool True if the token has the capability. | #### exists ```solidity function exists(uint256 id) external view returns (bool) ``` Returns true if a token with the given ID exists. **Parameters** | Name | Type | Description | | ---- | ------- | ----------- | | id | uint256 | Token ID. | #### royaltyInfo ```solidity function royaltyInfo(uint256, uint256 salePrice) external view virtual returns (address receiver, uint256 royaltyAmount) ``` Get royalty information for a token sale (ERC2981). *Returns the royalty receiver and amount for a given sale price. Royalty is calculated as (salePrice \* royaltyFraction) / 10000.* **Parameters** | Name | Type | Description | | --------- | ------- | --------------------------- | | | uint256 | | | salePrice | uint256 | The sale price of the token | **Return Values** | Name | Type | Description | | ------------- | ------- | --------------------------------------------------- | | receiver | address | The address that should receive the royalty payment | | royaltyAmount | uint256 | The royalty amount to be paid |