ERC-4910 - Royalty Bearing NFTs

Created 2022-03-14
Status Final
Category ERC
Type Standards Track
Authors
Requires

Extension of ERC-721 to correctly define, process, and pay (hierarchical) onchain NFT royalties.

Abstract

The proposal directly connects NFTs and royalties in a smart contract architecture extending the ERC-721 standard, with the aim of precluding central authorities from manipulating or circumventing payments to those who are legally entitled to them.

The proposal builds upon the OpenZeppelin Smart Contract Toolbox architecture, and extends it to include royalty account management (CRUD), royalty balance and payments management, simple trading capabilities -- Listing/De-Listing/Buying -- and capabilities to trace trading on exchanges. The royalty management capabilities allow for hierarchical royalty structures, referred to herein as royalty trees, to be established by logically connecting a "parent" NFT to its "children", and recursively enabling NFT "children" to have more children.

Motivation

The management of royalties is an age-old problem characterized by complex contracts, opaque management, plenty of cheating and fraud.

The above is especially true for a hierarchy of royalties, where one or more assets is derived from an original asset such as a print from an original painting, or a song is used in the creation of another song, or distribution rights and compensation are managed through a series of affiliates.

In the example below, the artist who created the original is eligible to receive proceeds from every sale, and resale, of a print.

Fig1

The basic concept for hierarchical royalties utilizing the above "ancestry concept" is demonstrated in the figure below.

Fig2

In order to solve for the complicated inheritance problem, this proposal breaks down the recursive problem of the hierarchy tree of depth N into N separate problems, one for each layer. This allows us to traverse the tree from its lowest level upwards to its root most efficiently.

This affords creators, and the distributors of art derived from the original, the opportunity to achieve passive income from the creative process, enhancing the value of an NFT, since it now not only has intrinsic value but also comes with an attached cash flow.

Specification

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.

Outline

This proposal introduces several new concepts as extensions to the ERC-721 standard that warrant explanation:

Below a non-normative overview is given of the data structures and functionality that are covered by the requirements in this document.

Data Structures

In order to create an interconnected data structure linking NFTs to RAs certain global data structures are required:

Royalty Account Functions

Definitions and interfaces for the Royalty Account RUD (Read-Update-Delete) functions. Because the RA is created in the minting function, there is no need to have a function to create a royalty account separately.

Minting of a Royalty Bearing NFT

When an NFT is minted, an RA must be created and associated with the NFT and the NFT owner, and, if there is an ancestor, with the ancestor's RA. To this end the specification utilizes the _safemint function in a newly defined mint function and applies various business rules on the input variables.

Listing NFTs for Sale and removing a Listing

Authorized user addresses can list NFTs for sale for non-exchange mediated NFT purchases.

Payment Function from Buyer to Seller

To avoid royalty circumvention, a buyer will always pay the NFT contract directly and not the seller. The seller is paid through the royalty distribution and can later request a payout.

The payment process depends on whether the payment is received in ETH or an ERC-20 token:

Modified NFT Transfer Function including required Trade data to allocate Royalties

The input parameters must satisfy several requirements for the NFT to be transferred AFTER the royalties have been properly distributed. Furthermore, the ability to transfer more than one token at a time is also considered.

The proposal defines:

Lastly, the approach to distributing royalties is to break down the hierarchical structure of interconnected Royalty Accounts into layers and then process one layer at time, where each relationship between a token and its ancestor is utilized to traverse the Royalty Account chain until the root ancestor and associated RA is reached.

Paying out Royalties to the NFT Owner -- from address in safeTransferFrom Function

This is the final part of the proposal.

There are two versions of the payout function -- a public function and an internal function.

The public function has the following interface:

function royaltyPayOut (uint256 tokenId, address RAsubaccount, address payable payoutAccount, uint256 amount) public virtual nonReentrant returns (bool)

where we only need the tokenId, the RA Sub Account address, _RAsubaccount which is the owner, and the amount to be paid out, _amount. Note that the function has nonReentrant modifier protection, because funds are being payed out.

To finally send a Payout payment, the following steps need to be taken:

Data Structures

Royalty Account and Royalty Sub Accounts

In order to create an interconnected data structure linking NFTs to RAs that is search optimized requires to make the following additions to the global data structures of an ERC-721.

Note, a Royalty Account is defined as a collection of Royalty Sub Accounts linked to a meta account. This meta account is comprised of general account identifiers particular to the NFT it is linked to such as asset identifier, parent identifier etc.

[R1] One or more Royalty Sub-Account MUST be linked to a Royalty Account.

[R2] The account identifier of a Royalty Account, raAccountId, MUST be unique.

[R3] The tokenId of a NFT MUST be linked to a raAccountID in order to connect an raAccountId to a tokenId.

Print (Child) NFTs

The set of requirement to manage Parent-Child NFT Relationships and constraints at each level of the NFT (family) tree e.g. number of children permitted, NFT parents have to be linked to their immediate NFT children are as follows.

[R4] There MUST be a link for direct parent-child relationships

NFT Payment Tokens

In order to capture royalties, an NFT contract must be involved in NFT trading. Therefore, the NFT contract needs to be aware of NFT payments, which in turn requires the NFT contract to be aware which tokens can be used for trading.

[R5] There MUST be a listing of supported token types

Since the NFT contract is managing royalty distributions and payouts as well as sales, it needs to track the last available balances of the allowed token types owned by the contract.

[R6] There MUST be a link of the last validated balance of an allowed token type in the contract to the respective allowed token contract.

NFT Listings and Payments

Since the contract is directly involved in the sales process, a capability to list one or more NFTs for sale is required.

[R7] There MUST be a list of NFTs for sale.

[R8] A sales listing MUST have a unique identifier.

Besides listings, the contract is required to manage sales as well. This requires the capability to register a payment, either for immediate execution or for later payment such as in an auction situation.

[R9] There MUST be a listing for registered payments

[R10] A registered payment MUST have a unique identifier.

Contract Constructor and Global Variables and their update functions

This standard extends the current ERC-721 constructor, and adds several global variables to recognize the special role of the creator of an NFT, and the fact that the contract is now directly involved in managing sales and royalties.

[R11] The minimal contract constructor MUST contain the following input elements.

///
/// @dev Definition of the contract constructor
///
/// @param name as in ERC-721
/// @param symbol as in ERC-721
/// @param baseTokenURI as in ERC-721
/// @param allowedTokenTypes is the array of allowed tokens for payment

constructor(
        string memory name,
        string memory symbol,
        string memory baseTokenURI,
        address[] memory allowedTokenTypes
    ) ERC721(name, symbol) {...}

Royalty Account Management

Below are the definitions and interfaces for the Royalty Account RUD (Read-Update-Delete) functions. Since a Royalty Account is created in the NFT minting function, there is no need to have a separate function to create a royalty account.

Get a Royalty Account

There is only one get function required because a Royalty Account and its sub accounts can be retrieved through the tokenId in the ancestry field of the Royalty Account.

[R12] The getRoyaltyAccount function interface MUST adhere to the definition below:

/// @dev Function to fetch a Royalty Account for a given tokenId
/// @param tokenId is the identifier of the NFT to which a Royalty Account is attached
/// @param RoyaltyAccount is a data structure containing the royalty account information
/// @param RASubAccount[] is an array of data structures containing the information of the royalty sub accounts associated with the royalty account

function getRoyaltyAccount (uint256 tokenId) public view virtual returns (address,
            RoyaltyAccount memory,
            RASubAccount[] memory);

[R13] The following business rules MUST be enforced in the getRoyaltyAccount function:

Update a Royalty Account

In order to update a Royalty Account, the caller must have both the 'tokenId' and the RoyaltyAccount itself which can be obtained from the Royalty Account getter function.

[R14] The updateRoyaltyAccount function interface MUST adhere to the definition below:

/// @dev Function to update a Royalty Account and its Sub Accounts
/// @param tokenId is the identifier of the NFT to which the Royalty Account to be updated is attached
/// @param RoyaltyAccount is the Royalty Account and associated Royalty Sub Accounts with updated values  

function updateRoyaltyAccount (uint256 _tokenId, `RoyaltyAccount memory _raAccount) public virtual returns (bool)

The update functionality of a Royalty Account, while straightforward, is also highly nuanced. To avoid complicated change control rules such as multi-signature rules, Royalty Account changes are kept simple.

[R15] The business rules for the update function are as follows:

  1. An NFTs asset identifier MUST NOT be changed.
  2. An NFTs ancestor MUST NOT be updated.
  3. An NFTs token type accepted for payment MUST NOT be updated.
  4. The royalty balance in a Royalty Sub Account MUST NOT be changed.
  5. The royalty split inherited by the children from the NFT parent MUST NOT be changed.
  6. New royalty split values MUST be larger than, or less than, or equal to any established boundary value for royalty splits, if it exists.
  7. The number of existing Royalty Sub Account plus the number of new Royalty Sub Accounts to be added MUST be smaller or equal to an established boundary value, if it exists.
  8. The sum of all royalty splits across all existing and new Royalty Sub Accounts MUST equal to 1 or its equivalent numerical value at all times.

  9. 'msg.sender` MUST be equal to an account identifier in the Royalty Sub Account of the Royalty Account to be modified and that royalty sub account must be identified as not belonging to the parent NFT

    9.1 the Sub Account belonging to the account identifier MUST NOT be removed

    9.2 A royalty split MUST only be decreased, and either the existing sub account's royalty split MUST be increased accordingly such that the sum of all royalty splits remains equal to 1 or its numerical equivalent, or one or more new Royalty Sub Accounts MUST be added according to rule 10.

    9.3 a royalty balance MUST NOT be changed

    9.4 an account identifier MUST NOT be NULL

  10. If msg.sender is equal to the account identifier of one of the Sub Account owners which is not the parent NFT, an additional Royalty Sub Accounts MAY be added

    10.1 if the royalty split of the Royalty Sub Account belonging to msg.sender is reduced

    • then the royalty balance in each new Royalty Sub Account MUST be zero

    • and the sum of the new royalty splits data MUST be equal to the royalty split of the Royalty Sub Account of msg.sender before it was modified

    10.2 new account identifier MUST not be NULL

  11. If the Royalty Account update is correct, the function returns true, otherwise false.

Deleting a Royalty Account

While sometimes deleting a Royalty Account is necessary, even convenient, it is a very costly function in terms of gas, and should not be used unless one is absolutely sure that the conditions enumerated below are met.

[R16] The deleteRoyaltyAccount function interface MUST adhere to the definition below:

/// @dev Function to delete a Royalty Account
/// @param tokenId is the identifier of the NFT to which the Royalty Account to be updated is attached

function deleteRoyaltyAccount (uint256 _tokenId) public virtual returns (bool)

[R17] The business rules for this function are as follows:

NFT Minting

In extension to the ERC-721 minting capability, a Royalty Account with Royalty Sub Accounts are required to be added during the minting, besides establishing the NFT token specific data structures supporting constraints such as the maximum number of children an NFT can have.

[R18] When a new NFT is minted a Royalty Account with one or more Royalty Sub Accounts MUST be created and associated with the NFT and the NFT owner, and, if there is an ancestor, with the ancestor's Royalty Account.

To this end the specification utilizes the ERC-721 _safemint function in a newly defined mint function, and applies various business rules on the function's input variables.

[D1] Note, that the mint function SHOULD have the ability to mint more than one NFT at a time.

[R19] Also, note that the owner of a new NFT MUST be the NFT contract itself.

[R20] The non-contract owner of the NFT MUST be set as isApproved which allows the non-contract owner to operate just like the owner.

This strange choice in the two requirements above is necessary, because the NFT contract functions as an escrow for payments and royalties, and, hence, needs to be able to track payments received from buyers and royalties due to recipients, and to associate them with a valid tokenId.

[R21] For compactness of the input, and since the token meta data might vary from token to token the MUST be a minimal data structure containing:

/// @param parent is the parent tokenId of the (child) token, and if set to 0 then there is no parent.
/// @param canBeParent indicates if a tokenId can have children or not.
/// @param maxChildren defines how many children an NFT can have.
/// @param royaltySplitForItsChildren is the royalty percentage split that a child has to pay to its parent.
/// @param uri is the unique token URI of the NFT

[R22] The mint function interface MUST adhere to the definition below:

/// @dev Function creates one or more new NFTs with its relevant meta data necessary for royalties, and a Royalty Account with its associated met data for `to` address. The tokenId(s) will be automatically assigned (and available on the emitted {IERC-721-Transfer} event).
/// @param to is the address to which the NFT(s) are minted
/// @param nfttoken is an array of struct type NFTToken for the meta data of the minted NFT(s)
/// @param tokenType is the type of allowed payment token for the NFT

function mint(address to, NFTToken[] memory nfttoken, address tokenType) public virtual

[R23] The following business rules for the mint function's input data MUST be fulfilled:

Listing and De-Listing of NFTs for Direct Sales

In the sales process, we need to minimally distinguish two types of transactions

The first type of transaction does not require that the smart contract is aware of a sales listing since the exchange contract will trigger payment and transfer transactions directly with the NFT contract as the owner. However, for the latter transaction type it is essential, since direct sales are required to be mediated at every step by the smart contract.

[R24] For direct sales, NFT listing, und de-listing, transactions MUST be executed through the NFT smart contract.

Exchange-mediated sales will be discussed when this document discusses payments.

In direct sales, authorized user addresses can list NFTs for sale, see the business rules below.

[R25] The listNFT function interface MUST adhere to the definition below:

/// @dev Function to list one or more NFTs for direct sales
/// @param tokenIds is the array of tokenIds to be included in the listing
/// @param price is the price set by the owner for the listed NFT(s)
/// @param tokenType is the payment token type allowed for the listing

function listNFT (uint256[] calldata tokenIds, uint256 price, address tokenType) public virtual returns (bool)

The Boolean return value is true for a successful function execution, and false for an unsuccessful function execution.

[R26] The business rules of the listNFT function are as follows:

[R27] If the conditions in [R26] are met, then the NFT sales list MUST be updated.

Authorized user addresses can also remove a direct sale listing of NFTs.

[R28] The removeNFTListing function interface MUST adhere to the definition below:

/// @dev Function to de-list one or more NFTs for direct sales
/// @param listingId is the identifier of the NFT listing

function removeNFTListing (uint256 listingId) public virtual returns (bool)

The Boolean return value is true for a successful function execution, and false for an unsuccessful function execution.

[R29] The business rules of the removeNFTListing function below MUST be adhered to:

[R30] If the conditions in [R29] are met, then the NFT sales listing MUST be removed.

Payments for NFT Sales

As noted before, a buyer will always pay the NFT contract directly and not the seller. The seller is paid through the royalty distribution and can later request a payout to their wallet.

[R31] The payment process requires either one or two steps:

  1. For an ERC-20 token
    • The buyer MUST approve the NFT contract for the purchase price, payment, for the selected payment token type.
    • The buyer MUST call the executePayment function.
  2. For a protocol token
    • The buyer MUST call a payment fallback function with msg.data not NULL.

[R32] For an ERC-20 token type, the required executePayment function interface MUST adhere to the definition below:

/// @dev Function to make a NFT direct sales or exchange-mediate sales payment
/// @param receiver is the address of the receiver of the payment
/// @param seller is the address of the NFT seller 
/// @param tokenIds are the tokenIds of the NFT to be bought
/// @param payment is the amount of that payment to be made
/// @param tokenType is the type of payment token
/// @param trxnType is the type of payment transaction -- minimally direct sales or exchange-mediated

function executePayment (address receiver, address seller, uint 256[] tokenIds, uint256 payment, string tokenType, int256 trxnType) public virtual nonReentrant returns (bool)

The Boolean return value is true for a successful function execution, and false for an unsuccessful function execution.

[R33] Independent of trxnType, the business rules for the input data are as follows:

In the following, this document will only discuss the differences between the two minimally required transaction types.

[R34] For trxnType = 0, the payment data MUST to be validated against the listing, based on the following rules:

[R35] If all checks in [R33], and in [R34] for trxnType = 0, are passed, the executePayment function MUST call the transfer function in the ERC-20 contract identified by tokenType with recipient = address(this) and amount = payment.

Note the NFT contract pays itself from the available allowance set in the approve transaction from the buyer.

[R36] For trxnType = 1, and for a successful payment, the registeredPayment mapping MUST updated with the payment, such that it can be validated when the NFT is transferred in a separate safeTransferFrom call, and true MUST be returned as the return value of the function, if successful, false otherwise.

[R37] For trxnType = 0, an internal version of the safeTransferFrom function with message data MUST be called to transfer the NFTs to the buyer, and upon success, the buyer MUST be given the MINTER_ROLE, unless the buyer already has that role.

Note, the _safeTransferFrom function has the same structure as safeTransferFrom but skips the input data validation.

[R38] For trxnType = 0, and if the NFT transfer is successful, the listing of the NFT MUST be removed.

[R39] For a protocol token as a payment token, and independent of trxnType, the buyer MUST send protocol tokens to the NFT contract as the escrow, and msg.data MUST encode the array of paid for NFTs uint256[] tokenIds.

[R40] For the NFT contract to receive a protocol token, a payable fallback function (fallback() external payable) MUST be implemented.

Note that since the information for which NFTs the payment was for must be passed, a simple receive() fallback function cannot be allowed since it does not allow for msg.data to be sent with the transaction.

[R41] msg.data for the fallback function MUST minimally contain the following data: address memory seller, uint256[] memory _tokenId, address memory receiver, int256 memory trxnType

[R42] If trxnType is not equal to either '0' or '1', or another supported type, then the fallback function MUST revert.

[R43] For trxnType equal to either '0' or '1', the requirements [R33] through [R38] MUST be satisfied for the fallback function to successfully execute, otherwise the fallback function MUST revert.

[R44] In case of a transaction failure (for direct sales, trxnType = 0), or the buyer of the NFT listing changing their mind (for exchange-mediated sales, trxnType = 1), the submitted payment MUST be able to revert using the reversePayment function where the function interface is defined below:

/// @dev Definition of the function enabling the reversal of a payment before the sale is complete
/// @param paymentId is the unique identifier for which a payment was made
/// @param tokenType is the type of payment token used in the payment
function reversePayment(uint256 paymentId, string memory tokenType) public virtual returns (bool)

The Boolean return value is true for a successful function execution, and false for an unsuccessful function execution.

Note, reentrancy protection through e.g. nonReentrant from the Open Zeppelin library is strongly advised since funds are being paid out.

[R45] The business rules for the reversePayment function are as follows:

Modified NFT Transfer function

This document adheres to the ERC-721 interface format for the safeTransferFrom function as given below:

function safeTransferFrom(address from, address to, uint256 tokenId, bytes memory _data) external virtual override

Note, that the input parameters must satisfy several requirements for the NFT(s) to be transferred AFTER royalties have been properly distributed. Note also, that the ability to transfer more than one token at a time is required. However, the standard interface only allows one token to be transferred at a time. In order to remain compliant with the ERC-721 standard, this document uses tokenId only for the first NFT to be transferred. All other transfer relevant data is encoded in _data.

The high-level requirements are as follows:

Also, note that in order to avoid royalty circumvention attacks, there is only one NFT transfer function.

[R46] Therefore, transferFrom and safeTransferFrom without data MUST be disabled.

This can be achieved through for example a revert statement in an override function.

[R47] The requirements on input parameters of the function are as follows:

Note, that in the context of this document only the scenario where the calling contract is still being created, i.e., the constructor being executed is a possible attack vector, and should to be carefully treated in the transfer scenario.

Turning to the _data object.

[R48] The _data object MUST minimally contain the following payment parameters:

[R49] The following business rules MUST be met for the payment data in '_data':

Distributing Royalties in the Transfer Function

The approach to distributing royalties is to break down the hierarchical structure of interconnected Royalty Accounts into layers, and then process one layer at time, where each relationship between a NFT and its ancestor is utilized to traverse the Royalty Account chain until the root ancestor and its associated Royalty Account.

Note, that the distribution function assumes that the payment made is for ALL tokens in the requested transfer. That means, that payment for the distribution function is equally divided between all NFTs included in the payment.

[R50] *The distributePayment function interface MUST adhere to the definition below:

/// @dev Function to distribute a payment as royalties to a chain of Royalty Accounts
/// @param tokenId is a tokenId included in the sale and used to look up the associated Royalty Account
/// @param payment is the payment (portion) to be distributed as royalties

function distributePayment (uint256 tokenId, uint265 payment) internal virtual returns (bool)

The Boolean return value is true for a successful function execution, and false for an unsuccessful function execution.

As mentioned before, the internal distributePayment function is called within the modified safeTransferFrom function.

Note, that it is necessary to multiply two uint256 numbers with each other -- the payment amount with the royalty split percentage expressed as a whole number e.g. 10000 = 100%. And then divide the result by the whole number representing 100% in order to arrive at the correct application of the royalty split percentage to the payment amount. This requires careful treatment of numbers in the implementation to prevent issues such as buffer over or under runs.

[R51] The processing logic of distributePayment function MUST be as follows:

Update Royalty Sub Account Ownership with Payout to approved Address (from)

In order to simplify the ownership transfer, first the approved address -- the non-contract NFT owner --, from, is paid out its share of the royalties. And then the Royalty Sub Account is updated with the new owner, to. This step repeats for each token to be transferred.

[R52] The business rules are as follows:

The last step in the process chain is transferring the NFTs in the purchase to the to address.

[R53] For every NFT (in the batch) the 'to' address MUST be `approved' (ERC-721 function) to complete the ownership transfer: 

_approve(to, tokenId[i]);

The technical NFT owner remains the NFT contract.

Removing the Payment Entry after successful Transfer

Only after the real ownership of the NFT, the approved address, has been updated, the payment registry entry can be removed to allow the transferred NFTs to be sold again.

[R54] After the approve relationship has been successfully updated to the to address, the registered payment MUST be removed.

Paying out Royalties to the from Address in safeTransferFrom Function

There are two versions of the payout function -- a public and an internal function -- depending on whether there is a payout during a purchase, or a payout is requested by a Royalty Sub Account owner.

[R55] The public royaltyPayOut function interface MUST adhere to the definition below:

/// @dev Function to payout a royalty payment
/// @param tokenId is the identifier of the NFT token
/// @param RAsubaccount is the address of the Royalty Sub Account from which the payout should happen
/// @param receiver is the address to receive the payout
/// @param amount is the amount to be paid out

function royaltyPayOut (uint256 tokenId, address RAsubaccount, address payable payoutAccount, uint256 amount) public virtual nonReentrant returns (bool)

The Boolean return value is true for a successful function execution, and false for an unsuccessful function execution.

Note, that the function has reentrancy protection through nonReentrant from the Open Zeppelin library since funds are being paid out.

[R56] The input parameters of the royaltyPayOut function MUST satisfy the following requirements:

[R57] The internal _royaltyPayOut function interface MUST adhere to the definition below:

function _royaltyPayOut (uint256 tokenId, address RAsubaccount, address payable payoutAccount, uint256 amount) public virtual returns (bool)

[R58] *The internal _royaltyPayOut function MUST perform the following actions:

[R59] The following steps MUST be taken to send out a royalty payment to its recipient:

Rationale

Royalties for NFTs is at its core a distribution licensing problem. A buyer obtains the right to an asset/content which might or might not be reproducible, alterable etc. by the buyer or agents of the buyer. Therefore, a comprehensive specification must address a hierarchy of royalties, where one or more assets are derived from an original asset as described in the Motivation section in detail. Consequently, a design must solve for a multi-level inheritance, and thus, recursion problem.

In order to solve for the complicated inheritance problem, this proposal design breaks down the recursive problem of the hierarchy first into a tree of depth N. And the further breaks down the tree structure into N separate problems, one for each layer. This design allows one to traverse the tree from its lowest level upwards to its root most efficiently. This is achieved with the design for the distributePayment function and the NFT data structures allowing for the tree structure e.g. ancestry,royaltyAccount, RAsubaccount.

In order to avoid massive gas costs during the payout of royalties, possibly exceeding block gas limits for large royalty trees, the design needed to create a royalty accounting system to maintain royalty balances for recipients as done with the royaltyAccount, 'RAsubaccount' data structures and the associated CRUD operations, as well as require that royalty payouts are done by individual and by request, only, as is achieved with the royaltyPayout function design.

Furthermore, the design had to ensure that in order to account for and payout royalties the smart contract must be in the "know" of all buying and selling of an NFT including the exchange of monies. This buying and selling can be either direct through the NFT contract or can be exchange-mediated as is most often the case today -- which is a centralizing factor! The chosen design for purchasing is accounting for those two modes.

Keeping the NFT contract in the "know" at the beginning of the purchase process requires that authorized user addresses can list NFTs for sale for direct sales , whereas for exchange-mediated purchases, a payment must be registered with the NFT contract before the purchase can be completed.

The design needed to avoid royalty circumvention during the purchase process, therefore, the NFT must be kept in the "know", a buyer will always have to pay the NFT contract directly and not the seller for both purchasing modes. The seller is subsequently paid through the royalty distribution function in the NFT contract. As a consequence, and a key design choice, and to stay compliant with ERC-721, the NFT contract must be the owner of the NFT, and the actual owner is an approved address.

The specification design also needed to account for that the payment process depends on whether the payment is received in ETH or an ERC-20 token:

In addition, the executePayment function had to be designed to handle both direct sales (through the NFT contract) and exchange-mediated sales which required the introduction of an indicator whether the purchase is direct or exchange-mediated.

The executePayment function also has to handle the NFT transfer and purchase clean up -- removal of a listing, or removal of a registered payment, distribution of royalties, payment to the seller, and finally transfer to the seller.

To stay compliant with the ERC-721 design but avoid royalty circumvention, all transfer functions must be disabled save the one that allows for additional information to be submitted with the function in order to manage the complicated purchase cleanup process -- safeTransferFrom. To ensure safety, the design enforces that input parameters must satisfy several requirements for the NFT to be transferred AFTER the royalties have been properly distributed, not before. The design accounts for the fact that we need to treat transfer somewhat differently for direct sales versus exchange mediated sales.

Finally the specification needed to take into account that NFTs must be able to be minted and burned to maintain compliance with the ERC-721 specification while also having to set up all the data structures for the tree.

The design enforces that when an NFT is minted, a royalty account for that NFT must be created and associated with the NFT and the NFT owner, and, if there is an ancestor of the NFT with the ancestor's royalty account to enforces the tree structure. To this end the specification utilizes the ERC-721 _safemint function in a newly defined mint function and applies various business rules on the input variables required to ensure proper set-up.

An NFT with a royalty account can be burned. However, several things have to be true to avoid locking funds not only for the royalty account of the NFT but also its descendants, if they exist. That means that all royalties for the NFT and its descendants, if they exists, must be paid out. Furthermore, if descendants exist, they must have been burned before an ancestor can be burned. If those rules are not enforced the cleanly, the hierarchical royalty structure in part of the tree can break down and lead to lost funds, not paid out royalties etc.

Backwards Compatibility

This EIP is backwards compatible to the ERC-721 standard introducing new interfaces and functionality but retaining the core interfaces and functionality of the ERC-721 standard.

Test Cases

A full test suite is part of the reference implementation.

Reference Implementation

The Treetrunk reference implementation of the standard can be found in the public treetrunkio Github repo under treetrunk-nft-reference-implementation.

Security Considerations

Given that this EIP introduces royalty collection, distribution, and payouts to the ERC-721 standard, the number of attack vectors increases. The most important attack vector categories and their mitigation are discussed below:

Besides the usage of professional security analysis tools, it is also recommended that each implementation performs a security audit of its implementation.

Copyright

Copyright and related rights waived via CC0.