Royalty Module

Manages ERC-2981 royalty information for tokens

Key Features

• Implements logic for ERC-2981 royaltyInfo function.
• Uses diamond storage pattern for shared royalty data.
• Provides internal functions for setting, resetting, and deleting royalties.
• Handles both token-specific and default royalty configurations.

Module Usage

This module provides internal functions for use in your custom facets. Import it to access shared logic and storage.

Overview

This module provides internal functions for managing ERC-2981 royalty information within a diamond. It allows facets to set, retrieve, and reset both default and token-specific royalties using shared diamond storage. This ensures consistent royalty handling across all facets interacting with the same token data.

Storage

RoyaltyInfo

Structure containing royalty information. Properties

Definition

struct RoyaltyInfo {
  address receiver;
  uint96 royaltyFraction;
}

---

RoyaltyStorage

storage-location: erc8042:erc2981

Definition

struct RoyaltyStorage {
  RoyaltyInfo defaultRoyaltyInfo;
  mapping(uint256 tokenId => RoyaltyInfo) tokenRoyaltyInfo;
}

State Variables

Property	Type	Description
STORAGE_POSITION	bytes32	Diamond storage slot position for this module (Value: keccak256("erc2981"))
FEE_DENOMINATOR	uint96	(Value: 10000)

Functions

deleteDefaultRoyalty

Removes default royalty information. After calling this function, royaltyInfo will return (address(0), 0) for tokens without specific royalty.

function deleteDefaultRoyalty() ;

---

getStorage

Returns the royalty storage struct from its predefined slot. Uses inline assembly to access diamond storage location.

function getStorage() pure returns (RoyaltyStorage storage s);

Returns:

Property	Type	Description
s	RoyaltyStorage	The storage reference for royalty state variables.

---

resetTokenRoyalty

Resets royalty information for a specific token to use the default setting. Clears token-specific royalty storage, causing fallback to default royalty.

function resetTokenRoyalty(uint256 _tokenId) ;

Parameters:

Property	Type	Description
_tokenId	uint256	The token ID to reset royalty configuration for.

---

royaltyInfo

Queries royalty information for a given token and sale price. Returns token-specific royalty or falls back to default royalty. Royalty amount is calculated as a percentage of the sale price using basis points. Implements the ERC-2981 royaltyInfo function logic.

function royaltyInfo(uint256 _tokenId, uint256 _salePrice) view returns (address receiver, uint256 royaltyAmount);

Parameters:

Property	Type	Description
_tokenId	uint256	The NFT asset queried for royalty information.
_salePrice	uint256	The sale price of the NFT asset.

Returns:

Property	Type	Description
receiver	address	The address designated to receive the royalty payment.
royaltyAmount	uint256	The royalty payment amount for _salePrice.

---

setDefaultRoyalty

Sets the default royalty information that applies to all tokens. Validates receiver and fee, then updates default royalty storage.

function setDefaultRoyalty(address _receiver, uint96 _feeNumerator) ;

Parameters:

Property	Type	Description
_receiver	address	The royalty recipient address.
_feeNumerator	uint96	The royalty fee in basis points.

---

setTokenRoyalty

Sets royalty information for a specific token, overriding the default. Validates receiver and fee, then updates token-specific royalty storage.

function setTokenRoyalty(uint256 _tokenId, address _receiver, uint96 _feeNumerator) ;

Parameters:

Property	Type	Description
_tokenId	uint256	The token ID to configure royalty for.
_receiver	address	The royalty recipient address.
_feeNumerator	uint96	The royalty fee in basis points.

Errors

Thrown when default royalty fee exceeds 100% (10000 basis points).

Signature:

error ERC2981InvalidDefaultRoyalty(uint256 _numerator, uint256 _denominator);

Thrown when default royalty receiver is the zero address.

Signature:

error ERC2981InvalidDefaultRoyaltyReceiver(address _receiver);

Thrown when token-specific royalty fee exceeds 100% (10000 basis points).

Signature:

error ERC2981InvalidTokenRoyalty(uint256 _tokenId, uint256 _numerator, uint256 _denominator);

Thrown when token-specific royalty receiver is the zero address.

Signature:

error ERC2981InvalidTokenRoyaltyReceiver(uint256 _tokenId, address _receiver);

Best Practices

Best Practice

• Ensure receiver addresses are valid and fee numerators are within acceptable bounds before calling setDefaultRoyalty or setTokenRoyalty.
• Use royaltyInfo to retrieve royalty details for a token, falling back to default if token-specific royalties are not set.
• Call resetTokenRoyalty to revert a token's royalty settings to the default, ensuring predictable behavior after changes.

Integration Notes

Shared Storage

This module interacts with diamond storage at the STORAGE_POSITION defined by keccak256("erc2981"). The RoyaltyStorage struct, containing defaultRoyaltyInfo, is accessed via inline assembly. Functions like setDefaultRoyalty and setTokenRoyalty modify this shared storage. The royaltyInfo function reads from this storage to determine applicable royalties, first checking for token-specific settings and then falling back to default settings. Changes made by this module are immediately visible to any facet that reads from the same storage position.

Was this helpful?

Last updated:March 13, 2026