openzeppelin-contracts/docs/modules/api/pages/token/common.adoc

:github-icon: pass:[<svg class="icon"><use href="#github-icon"/></svg>]
:ERC2981: pass:normal[xref:token/common.adoc#ERC2981[`ERC2981`]]
:ERC721Royalty: pass:normal[xref:token/ERC721.adoc#ERC721Royalty[`ERC721Royalty`]]
:xref-ERC2981-supportsInterface-bytes4-: xref:token/common.adoc#ERC2981-supportsInterface-bytes4-
:xref-ERC2981-royaltyInfo-uint256-uint256-: xref:token/common.adoc#ERC2981-royaltyInfo-uint256-uint256-
:xref-ERC2981-_feeDenominator--: xref:token/common.adoc#ERC2981-_feeDenominator--
:xref-ERC2981-_setDefaultRoyalty-address-uint96-: xref:token/common.adoc#ERC2981-_setDefaultRoyalty-address-uint96-
:xref-ERC2981-_deleteDefaultRoyalty--: xref:token/common.adoc#ERC2981-_deleteDefaultRoyalty--
:xref-ERC2981-_setTokenRoyalty-uint256-address-uint96-: xref:token/common.adoc#ERC2981-_setTokenRoyalty-uint256-address-uint96-
:xref-ERC2981-_resetTokenRoyalty-uint256-: xref:token/common.adoc#ERC2981-_resetTokenRoyalty-uint256-
:xref-ERC2981-ERC2981InvalidDefaultRoyalty-uint256-uint256-: xref:token/common.adoc#ERC2981-ERC2981InvalidDefaultRoyalty-uint256-uint256-
:xref-ERC2981-ERC2981InvalidDefaultRoyaltyReceiver-address-: xref:token/common.adoc#ERC2981-ERC2981InvalidDefaultRoyaltyReceiver-address-
:xref-ERC2981-ERC2981InvalidTokenRoyalty-uint256-uint256-uint256-: xref:token/common.adoc#ERC2981-ERC2981InvalidTokenRoyalty-uint256-uint256-uint256-
:xref-ERC2981-ERC2981InvalidTokenRoyaltyReceiver-uint256-address-: xref:token/common.adoc#ERC2981-ERC2981InvalidTokenRoyaltyReceiver-uint256-address-
= Common (Tokens)

Functionality that is common to multiple token standards.

* {ERC2981}: NFT Royalties compatible with both ERC-721 and ERC-1155.
** For ERC-721 consider {ERC721Royalty} which clears the royalty information from storage on burn.

== Contracts

:RoyaltyInfo: pass:normal[xref:#ERC2981-RoyaltyInfo[`++RoyaltyInfo++`]]
:ERC2981InvalidDefaultRoyalty: pass:normal[xref:#ERC2981-ERC2981InvalidDefaultRoyalty-uint256-uint256-[`++ERC2981InvalidDefaultRoyalty++`]]
:ERC2981InvalidDefaultRoyaltyReceiver: pass:normal[xref:#ERC2981-ERC2981InvalidDefaultRoyaltyReceiver-address-[`++ERC2981InvalidDefaultRoyaltyReceiver++`]]
:ERC2981InvalidTokenRoyalty: pass:normal[xref:#ERC2981-ERC2981InvalidTokenRoyalty-uint256-uint256-uint256-[`++ERC2981InvalidTokenRoyalty++`]]
:ERC2981InvalidTokenRoyaltyReceiver: pass:normal[xref:#ERC2981-ERC2981InvalidTokenRoyaltyReceiver-uint256-address-[`++ERC2981InvalidTokenRoyaltyReceiver++`]]
:supportsInterface: pass:normal[xref:#ERC2981-supportsInterface-bytes4-[`++supportsInterface++`]]
:royaltyInfo: pass:normal[xref:#ERC2981-royaltyInfo-uint256-uint256-[`++royaltyInfo++`]]
:_feeDenominator: pass:normal[xref:#ERC2981-_feeDenominator--[`++_feeDenominator++`]]
:_setDefaultRoyalty: pass:normal[xref:#ERC2981-_setDefaultRoyalty-address-uint96-[`++_setDefaultRoyalty++`]]
:_deleteDefaultRoyalty: pass:normal[xref:#ERC2981-_deleteDefaultRoyalty--[`++_deleteDefaultRoyalty++`]]
:_setTokenRoyalty: pass:normal[xref:#ERC2981-_setTokenRoyalty-uint256-address-uint96-[`++_setTokenRoyalty++`]]
:_resetTokenRoyalty: pass:normal[xref:#ERC2981-_resetTokenRoyalty-uint256-[`++_resetTokenRoyalty++`]]

:supportsInterface-bytes4: pass:normal[xref:#ERC2981-supportsInterface-bytes4-[`++supportsInterface++`]]
:royaltyInfo-uint256-uint256: pass:normal[xref:#ERC2981-royaltyInfo-uint256-uint256-[`++royaltyInfo++`]]
:_feeDenominator-: pass:normal[xref:#ERC2981-_feeDenominator--[`++_feeDenominator++`]]
:_setDefaultRoyalty-address-uint96: pass:normal[xref:#ERC2981-_setDefaultRoyalty-address-uint96-[`++_setDefaultRoyalty++`]]
:_deleteDefaultRoyalty-: pass:normal[xref:#ERC2981-_deleteDefaultRoyalty--[`++_deleteDefaultRoyalty++`]]
:_setTokenRoyalty-uint256-address-uint96: pass:normal[xref:#ERC2981-_setTokenRoyalty-uint256-address-uint96-[`++_setTokenRoyalty++`]]
:_resetTokenRoyalty-uint256: pass:normal[xref:#ERC2981-_resetTokenRoyalty-uint256-[`++_resetTokenRoyalty++`]]

[.contract]
[[ERC2981]]
=== `++ERC2981++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.4.0/contracts/token/common/ERC2981.sol[{github-icon},role=heading-link]

[.hljs-theme-light.nopadding]
```solidity
import "@openzeppelin/contracts/token/common/ERC2981.sol";
```

Implementation of the NFT Royalty Standard, a standardized way to retrieve royalty payment information.

Royalty information can be specified globally for all token ids via {_setDefaultRoyalty}, and/or individually for
specific token ids via {_setTokenRoyalty}. The latter takes precedence over the first.

Royalty is specified as a fraction of sale price. {_feeDenominator} is overridable but defaults to 10000, meaning the
fee is specified in basis points by default.

IMPORTANT: ERC-2981 only specifies a way to signal royalty information and does not enforce its payment. See
https://eips.ethereum.org/EIPS/eip-2981#optional-royalty-payments[Rationale] in the ERC. Marketplaces are expected to
voluntarily pay royalties together with sales, but note that this standard is not yet widely supported.

[.contract-index]
.Functions
--
* {xref-ERC2981-supportsInterface-bytes4-}[`++supportsInterface(interfaceId)++`]
* {xref-ERC2981-royaltyInfo-uint256-uint256-}[`++royaltyInfo(tokenId, salePrice)++`]
* {xref-ERC2981-_feeDenominator--}[`++_feeDenominator()++`]
* {xref-ERC2981-_setDefaultRoyalty-address-uint96-}[`++_setDefaultRoyalty(receiver, feeNumerator)++`]
* {xref-ERC2981-_deleteDefaultRoyalty--}[`++_deleteDefaultRoyalty()++`]
* {xref-ERC2981-_setTokenRoyalty-uint256-address-uint96-}[`++_setTokenRoyalty(tokenId, receiver, feeNumerator)++`]
* {xref-ERC2981-_resetTokenRoyalty-uint256-}[`++_resetTokenRoyalty(tokenId)++`]

[.contract-subindex-inherited]
.ERC165

[.contract-subindex-inherited]
.IERC2981

[.contract-subindex-inherited]
.IERC165

--

[.contract-index]
.Errors
--
* {xref-ERC2981-ERC2981InvalidDefaultRoyalty-uint256-uint256-}[`++ERC2981InvalidDefaultRoyalty(numerator, denominator)++`]
* {xref-ERC2981-ERC2981InvalidDefaultRoyaltyReceiver-address-}[`++ERC2981InvalidDefaultRoyaltyReceiver(receiver)++`]
* {xref-ERC2981-ERC2981InvalidTokenRoyalty-uint256-uint256-uint256-}[`++ERC2981InvalidTokenRoyalty(tokenId, numerator, denominator)++`]
* {xref-ERC2981-ERC2981InvalidTokenRoyaltyReceiver-uint256-address-}[`++ERC2981InvalidTokenRoyaltyReceiver(tokenId, receiver)++`]

[.contract-subindex-inherited]
.ERC165

[.contract-subindex-inherited]
.IERC2981

[.contract-subindex-inherited]
.IERC165

--

[.contract-item]
[[ERC2981-supportsInterface-bytes4-]]
==== `[.contract-item-name]#++supportsInterface++#++(bytes4 interfaceId) → bool++` [.item-kind]#public#

Returns true if this contract implements the interface defined by
`interfaceId`. See the corresponding
https://eips.ethereum.org/EIPS/eip-165#how-interfaces-are-identified[ERC section]
to learn more about how these ids are created.

This function call must use less than 30 000 gas.

[.contract-item]
[[ERC2981-royaltyInfo-uint256-uint256-]]
==== `[.contract-item-name]#++royaltyInfo++#++(uint256 tokenId, uint256 salePrice) → address receiver, uint256 amount++` [.item-kind]#public#

Returns how much royalty is owed and to whom, based on a sale price that may be denominated in any unit of
exchange. The royalty amount is denominated and should be paid in that same unit of exchange.

NOTE: ERC-2981 allows setting the royalty to 100% of the price. In that case all the price would be sent to the
royalty receiver and 0 tokens to the seller. Contracts dealing with royalty should consider empty transfers.

[.contract-item]
[[ERC2981-_feeDenominator--]]
==== `[.contract-item-name]#++_feeDenominator++#++() → uint96++` [.item-kind]#internal#

The denominator with which to interpret the fee set in {_setTokenRoyalty} and {_setDefaultRoyalty} as a
fraction of the sale price. Defaults to 10000 so fees are expressed in basis points, but may be customized by an
override.

[.contract-item]
[[ERC2981-_setDefaultRoyalty-address-uint96-]]
==== `[.contract-item-name]#++_setDefaultRoyalty++#++(address receiver, uint96 feeNumerator)++` [.item-kind]#internal#

Sets the royalty information that all ids in this contract will default to.

Requirements:

- `receiver` cannot be the zero address.
- `feeNumerator` cannot be greater than the fee denominator.

[.contract-item]
[[ERC2981-_deleteDefaultRoyalty--]]
==== `[.contract-item-name]#++_deleteDefaultRoyalty++#++()++` [.item-kind]#internal#

Removes default royalty information.

[.contract-item]
[[ERC2981-_setTokenRoyalty-uint256-address-uint96-]]
==== `[.contract-item-name]#++_setTokenRoyalty++#++(uint256 tokenId, address receiver, uint96 feeNumerator)++` [.item-kind]#internal#

Sets the royalty information for a specific token id, overriding the global default.

Requirements:

- `receiver` cannot be the zero address.
- `feeNumerator` cannot be greater than the fee denominator.

[.contract-item]
[[ERC2981-_resetTokenRoyalty-uint256-]]
==== `[.contract-item-name]#++_resetTokenRoyalty++#++(uint256 tokenId)++` [.item-kind]#internal#

Resets royalty information for the token id back to the global default.

[.contract-item]
[[ERC2981-ERC2981InvalidDefaultRoyalty-uint256-uint256-]]
==== `[.contract-item-name]#++ERC2981InvalidDefaultRoyalty++#++(uint256 numerator, uint256 denominator)++` [.item-kind]#error#

The default royalty set is invalid (eg. (numerator / denominator) >= 1).

[.contract-item]
[[ERC2981-ERC2981InvalidDefaultRoyaltyReceiver-address-]]
==== `[.contract-item-name]#++ERC2981InvalidDefaultRoyaltyReceiver++#++(address receiver)++` [.item-kind]#error#

The default royalty receiver is invalid.

[.contract-item]
[[ERC2981-ERC2981InvalidTokenRoyalty-uint256-uint256-uint256-]]
==== `[.contract-item-name]#++ERC2981InvalidTokenRoyalty++#++(uint256 tokenId, uint256 numerator, uint256 denominator)++` [.item-kind]#error#

The royalty set for a specific `tokenId` is invalid (eg. (numerator / denominator) >= 1).

[.contract-item]
[[ERC2981-ERC2981InvalidTokenRoyaltyReceiver-uint256-address-]]
==== `[.contract-item-name]#++ERC2981InvalidTokenRoyaltyReceiver++#++(uint256 tokenId, address receiver)++` [.item-kind]#error#

The royalty receiver for `tokenId` is invalid.