Abstract
This standard is an extension of ERC-721. It proposes two referable indicators, referring and referred, and a time-based indicator createdTimestamp. The relationship between each NFT forms a directed acyclic graph (DAG). The standard allows users to query, track and analyze their relationships.
Motivation
Many scenarios require the inheritance, reference, and extension of NFTs. For instance, an artist may develop his NFT work based on a previous NFT, or a DJ may remix his record by referring to two pop songs, etc. A gap in existing NFT standards is the absence of established relationships between an NFT and its original creator. This void isolates NFTs, rendering the sale of each one a one-off transaction, thereby obstructing creators from accruing the full value of their intellectual property over time.
In this sense, proposing a referable solution for existing NFTs that enables efficient queries on cross-references is necessary. By introducing a reference relationship between NFTs, a sustainable economic model can be established to incentivize continued engagement in creating, using, and promoting NFTs.
This standard accordingly introduces a new concept, referable NFT (rNFT), which can transform static NFTs into a dynamically extensible network. We embed reference information, including referring and referred relationships, aiding in the formation of a Direct Acyclic Graph (DAG)-based NFT network. This structure provides a transparent graphical historical record and allows users to query, trace, and analyze relationships. It can enable NFT creators to build upon existing works without the need to start anew.
An intuitive example: users can create new NFTs (C, D, E) by referencing existing ones (A, B), while the referred function informs the original NFTs (A, B) about their citations (e.g., A ← D; C ← E; B ← E, and A ← E). Here, the createdTimestamp (block-level) serves as an indicator for the creation time of NFTs (A, B, C, D, E).
Key Takeaways
This standard provides several advantages:
Clear ownership inheritance: This standard extends the static NFT into a virtually extensible NFT network. Artists do not have to create work isolated from others. The ownership inheritance avoids reinventing the same wheel.
Incentive Compatibility: This standard clarifies the referable relationship across different NFTs, helping to integrate multiple up-layer incentive models for both original NFT owners and new creators.
Easy Integration: This standard makes it easier for the existing token standards or third-party protocols. For instance, the rNFT can be applied to rentable scenarios (cf. ERC-5006 to build a hierarchical rental market, where multiple users can rent the same NFT during the same time or one user can rent multiple NFTs during the same duration).
Scalable Interoperability: This standard enables cross-contract references, giving a scalable adoption for the broader public with stronger interoperability.
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.
UpdateNode: event emitted whensetNodeis invoked;safeMint: mint a new rNFT;setNode: set the referring list of an rNFT and update the referred list of each one in the referring list;setNodeReferring: set the referring list of an rNFT;setNodeReferred: set the referred list of the given rNFTs sourced from different contracts;setNodeReferredExternal: set the referred list of the given rNFTs sourced from external contracts;
referringOf: get the referring list of an rNFT;referredOf: get the referred list of an rNFT;createdTimestampOf: get the timestamp of an rNFT when it is being created.
Implementers of this standard MUST have all of the following functions:
pragma solidity ^0.8.4;
import "@openzeppelin/contracts/utils/introspection/IERC165.sol";
interface IERC_5521 is IERC165 {
/// Logged when a node in the rNFT gets referred and changed.
/// @notice Emitted when the `node` (i.e., an rNFT) is changed.
event UpdateNode(uint256 indexed tokenId,
address indexed owner,
address[] _address_referringList,
uint256[][] _tokenIds_referringList,
address[] _address_referredList,
uint256[][] _tokenIds_referredList
);
/// @notice set the referred list of an rNFT associated with different contract addresses and update the referring list of each one in the referred list. Checking the duplication of `addresses` and `tokenIds` is **RECOMMENDED**.
/// @param `tokenId` of rNFT being set. `addresses` of the contracts in which rNFTs with `tokenIds` being referred accordingly.
/// @requirement
/// - the size of `addresses` **MUST** be the same as that of `tokenIds`;
/// - once the size of `tokenIds` is non-zero, the inner size **MUST** also be non-zero;
/// - the `tokenId` **MUST** be unique within the same contract;
/// - the `tokenId` **MUST NOT** be the same as `tokenIds[i][j]` if `addresses[i]` is essentially `address(this)`.
function setNode(uint256 tokenId, address[] memory addresses, uint256[][] memory tokenIds) external;
/// @notice get the referring list of an rNFT.
/// @param `tokenId` of the rNFT being focused, `_address` of contract address associated with the focused rNFT.
/// @return the referring mapping of the rNFT.
function referringOf(address _address, uint256 tokenId) external view returns(address[] memory, uint256[][] memory);
/// @notice get the referred list of an rNFT.
/// @param `tokenId` of the rNFT being focused, `_address` of contract address associated with the focused rNFT.
/// @return the referred mapping of the rNFT.
function referredOf(address _address, uint256 tokenId) external view returns(address[] memory, uint256[][] memory);
/// @notice get the timestamp of an rNFT when is being created.
/// @param `tokenId` of the rNFT being focused, `_address` of contract address associated with the focused rNFT.
/// @return the timestamp of the rNFT when is being created with uint256 format.
function createdTimestampOf(address _address, uint256 tokenId) external view returns(uint256);
/// @notice check supported interfaces, adhereing to ERC165.
function supportsInterface(bytes4 interfaceId) external view returns (bool);
}
interface TargetContract is IERC165 {
/// @notice set the referred list of an rNFT associated with external contract addresses.
/// @param `_tokenIds` of rNFTs associated with the contract address `_address` being referred by the rNFT with `tokenId`.
/// @requirement
/// - `_address` **MUST NOT** be the same as `address(this)` where `this` is executed by an external contract where `TargetContract` interface is implemented.
function setNodeReferredExternal(address _address, uint256 tokenId, uint256[] memory _tokenIds) external;
function referringOf(address _address, uint256 tokenId) external view returns(address[] memory, uint256[][] memory);
function referredOf(address _address, uint256 tokenId) external view returns(address[] memory, uint256[][] memory);
function createdTimestampOf(address _address, uint256 tokenId) external view returns(uint256);
function supportsInterface(bytes4 interfaceId) external view returns (bool);
}
Rationale
Is this event informative enough?
UpdateNode: This event disseminates crucial information, including the rNFT ID, its owner, and lists of contract addresses/IDs with rNFTs referring to or referred by the subject rNFT. This data set enables stakeholders to efficiently manage and navigate the complex web of relationships inherent in the rNFT ecosystem.
Implementers are free to choose to use a struct (a recommended struct is given in the Reference Implementation), or several separate mappings, or whatever other storage mechanism. Whichever mechanism chosen has no observable effect on the behaviour of the contract, as long as its output can fulfill the UpdateNode event.
Why createdTimestampOf?
createdTimestamp: A key principle of this standard is that an rNFT should reference content already accepted by the community (a time-based sequence known by participants). Global timestamps for rNFTs are thus essential, serving to prevent conflicting states (akin to concurrency issues in transaction processing and block organization). We define a block-level timestamp where createdTimestamp = block.timestamp Note that, given that the granularity of references is tied to the block timestamp, it is impractical to discern the order of two rNFTs within the same block.
How is cross-contract reference performed?
setNodeReferredExternal: This function operates conditionally, dependent on successful interface verification in external contracts. Such selective invocation ensures backward compatibility and integration with existing contracts, provided they adhere to specified interfaces.
Backwards Compatibility
This standard can be fully ERC-721 compatible by adding an extension function set.
Test Cases
Test cases are included in ERC_5521.test.js
Reference Implementation
The recommended implementation is demonstrated as follows:
Relationship: a structure that containsreferring,referred,referringKeys,referredKeys,createdTimestamp, and other customized and optional attributes (i.e., not necessarily included in the standard) such asprivityOfAgreementrecording the ownerships of referred NFTs at the time the Referable NFTs (rNFTs) were being created orprofitSharingrecording the profit sharing ofreferring.referring: an out-degree indicator, used to show the users this NFT refers to;referred: an in-degree indicator, used to show the users who have refereed this NFT;referringKeys: a helper for mapping conversion of out-degree indicators, used for events;referredKeys: a helper for mapping conversion of in-degree indicators, used for events;createdTimestamp: a time-based indicator, used to compare the timestamp of mint, which should not be editable anyhow by callers.referringOfandreferredOf: First, the currentreferringOfandreferredOfallow cross-contract looking up, while this cannot be done by directly accessing_relationship. Secondly, only if privacy is not a concern, making_relationshippublic simplifies the contract by relying on Solidity’s automatically generated getters. However, if you need to control the visibility of the data, keeping the state variable private and providing specific getter functions would be the best approach. For example, if_relationshipincludes details about specific users’ interactions or transactions or some private extensible parameters (in the updated version, we specifically highlight theRelationshipcan be extended to meet different requirements), always making this data public could reveal users’ behavior patterns or preferences, leading to potential privacy breaches.convertMap: This function is essential for retrieving the full mapping contents within a struct. Even if_relationshipis public, The getters only allow retrieval of individual values for specific keys. Since we need comprehensive access to all stored addresses,convertMapis necessary to fulfill our event emission requirements.
pragma solidity ^0.8.4;
import "@openzeppelin/contracts/token/ERC721/ERC721.sol";
import "./IERC_5521.sol";
contract ERC_5521 is ERC721, IERC_5521, TargetContract {
struct Relationship {
mapping (address => uint256[]) referring;
mapping (address => uint256[]) referred;
address[] referringKeys;
address[] referredKeys;
uint256 createdTimestamp; // unix timestamp when the rNFT is being created
// extensible parameters
// ...
}
mapping (uint256 => Relationship) internal _relationship;
address contractOwner = address(0);
constructor(string memory name_, string memory symbol_) ERC721(name_, symbol_) {
contractOwner = msg.sender;
}
function safeMint(uint256 tokenId, address[] memory addresses, uint256[][] memory _tokenIds) public {
// require(msg.sender == contractOwner, "ERC_rNFT: Only contract owner can mint");
_safeMint(msg.sender, tokenId);
setNode(tokenId, addresses, _tokenIds);
}
/// @notice set the referred list of an rNFT associated with different contract addresses and update the referring list of each one in the referred list
/// @param tokenIds array of rNFTs, recommended to check duplication at the caller's end
function setNode(uint256 tokenId, address[] memory addresses, uint256[][] memory tokenIds) public virtual override {
require(
addresses.length == tokenIds.length,
"Addresses and TokenID arrays must have the same length"
);
for (uint i = 0; i < tokenIds.length; i++) {
if (tokenIds[i].length == 0) { revert("ERC_5521: the referring list cannot be empty"); }
}
setNodeReferring(addresses, tokenId, tokenIds);
setNodeReferred(addresses, tokenId, tokenIds);
}
/// @notice set the referring list of an rNFT associated with different contract addresses
/// @param _tokenIds array of rNFTs associated with addresses, recommended to check duplication at the caller's end
function setNodeReferring(address[] memory addresses, uint256 tokenId, uint256[][] memory _tokenIds) private {
require(_isApprovedOrOwner(msg.sender, tokenId), "ERC_5521: transfer caller is not owner nor approved");
Relationship storage relationship = _relationship[tokenId];
for (uint i = 0; i < addresses.length; i++) {
if (relationship.referring[addresses[i]].length == 0) { relationship.referringKeys.push(addresses[i]); } // Add the address if it's a new entry
relationship.referring[addresses[i]] = _tokenIds[i];
}
relationship.createdTimestamp = block.timestamp;
emitEvents(tokenId, msg.sender);
}
/// @notice set the referred list of an rNFT associated with different contract addresses
/// @param _tokenIds array of rNFTs associated with addresses, recommended to check duplication at the caller's end
function setNodeReferred(address[] memory addresses, uint256 tokenId, uint256[][] memory _tokenIds) private {
for (uint i = 0; i < addresses.length; i++) {
if (addresses[i] == address(this)) {
for (uint j = 0; j < _tokenIds[i].length; j++) {
Relationship storage relationship = _relationship[_tokenIds[i][j]];
if (relationship.referred[addresses[i]].length == 0) { relationship.referredKeys.push(addresses[i]); } // Add the address if it's a new entry
require(tokenId != _tokenIds[i][j], "ERC_5521: self-reference not allowed");
if (relationship.createdTimestamp >= block.timestamp) { revert("ERC_5521: the referred rNFT needs to be a predecessor"); } // Make sure the reference complies with the timing sequence
relationship.referred[address(this)].push(tokenId);
emitEvents(_tokenIds[i][j], ownerOf(_tokenIds[i][j]));
}
} else {
TargetContract targetContractInstance = TargetContract(addresses[i]);
bool isSupports = targetContractInstance.supportsInterface(type(TargetContract).interfaceId);
if (isSupports) {
// The target contract supports the interface, safe to call functions of the interface.
targetContractInstance.setNodeReferredExternal(address(this), tokenId, _tokenIds[i]);
}
}
}
}
/// @notice set the referred list of an rNFT associated with different contract addresses
/// @param _tokenIds array of rNFTs associated with addresses, recommended to check duplication at the caller's end
function setNodeReferredExternal(address _address, uint256 tokenId, uint256[] memory _tokenIds) external {
for (uint i = 0; i < _tokenIds.length; i++) {
Relationship storage relationship = _relationship[_tokenIds[i]];
if (relationship.referred[_address].length == 0) { relationship.referredKeys.push(_address); } // Add the address if it's a new entry
require(_address != address(this), "ERC_5521: this must be an external contract address");
if (relationship.createdTimestamp >= block.timestamp) { revert("ERC_5521: the referred rNFT needs to be a predecessor"); } // Make sure the reference complies with the timing sequence
relationship.referred[_address].push(tokenId);
emitEvents(_tokenIds[i], ownerOf(_tokenIds[i]));
}
}
/// @notice Get the referring list of an rNFT
/// @param tokenId The considered rNFT, _address The corresponding contract address
/// @return The referring mapping of an rNFT
function referringOf(address _address, uint256 tokenId) external view virtual override(IERC_5521, TargetContract) returns (address[] memory, uint256[][] memory) {
address[] memory _referringKeys;
uint256[][] memory _referringValues;
if (_address == address(this)) {
require(_exists(tokenId), "ERC_5521: token ID not existed");
(_referringKeys, _referringValues) = convertMap(tokenId, true);
} else {
TargetContract targetContractInstance = TargetContract(_address);
require(targetContractInstance.supportsInterface(type(TargetContract).interfaceId), "ERC_5521: target contract not supported");
(_referringKeys, _referringValues) = targetContractInstance.referringOf(_address, tokenId);
}
return (_referringKeys, _referringValues);
}
/// @notice Get the referred list of an rNFT
/// @param tokenId The considered rNFT, _address The corresponding contract address
/// @return The referred mapping of an rNFT
function referredOf(address _address, uint256 tokenId) external view virtual override(IERC_5521, TargetContract) returns (address[] memory, uint256[][] memory) {
address[] memory _referredKeys;
uint256[][] memory _referredValues;
if (_address == address(this)) {
require(_exists(tokenId), "ERC_5521: token ID not existed");
(_referredKeys, _referredValues) = convertMap(tokenId, false);
} else {
TargetContract targetContractInstance = TargetContract(_address);
require(targetContractInstance.supportsInterface(type(TargetContract).interfaceId), "ERC_5521: target contract not supported");
(_referredKeys, _referredValues) = targetContractInstance.referredOf(_address, tokenId);
}
return (_referredKeys, _referredValues);
}
/// @notice Get the timestamp of an rNFT when is being created.
/// @param `tokenId` of the rNFT being focused, `_address` of contract address associated with the focused rNFT.
/// @return The timestamp of the rNFT when is being created with uint256 format.
function createdTimestampOf(address _address, uint256 tokenId) external view returns(uint256) {
uint256 memory createdTimestamp;
if (_address == address(this)) {
require(_exists(tokenId), "ERC_5521: token ID not existed");
Relationship storage relationship = _relationship[tokenId];
createdTimestamp = relationship.createdTimestamp;
} else {
TargetContract targetContractInstance = TargetContract(_address);
require(targetContractInstance.supportsInterface(type(TargetContract).interfaceId), "ERC_5521: target contract not supported");
createdTimestamp = targetContractInstance.createdTimestampOf(_address, tokenId);
}
return createdTimestamp;
}
/// @dev See {IERC165-supportsInterface}.
function supportsInterface(bytes4 interfaceId) public view virtual override (ERC721, IERC_5521, TargetContract) returns (bool) {
return interfaceId == type(IERC_5521).interfaceId
|| interfaceId == type(TargetContract).interfaceId
|| super.supportsInterface(interfaceId);
}
// @notice Emit an event of UpdateNode
function emitEvents(uint256 tokenId, address sender) private {
(address[] memory _referringKeys, uint256[][] memory _referringValues) = convertMap(tokenId, true);
(address[] memory _referredKeys, uint256[][] memory _referredValues) = convertMap(tokenId, false);
emit UpdateNode(tokenId, sender, _referringKeys, _referringValues, _referredKeys, _referredValues);
}
// @notice Convert a specific `local` token mapping to a key array and a value array
function convertMap(uint256 tokenId, bool isReferring) private view returns (address[] memory, uint256[][] memory) {
Relationship storage relationship = _relationship[tokenId];
address[] memory returnKeys;
uint256[][] memory returnValues;
if (isReferring) {
returnKeys = relationship.referringKeys;
returnValues = new uint256[][](returnKeys.length);
for (uint i = 0; i < returnKeys.length; i++) {
returnValues[i] = relationship.referring[returnKeys[i]];
}
} else {
returnKeys = relationship.referredKeys;
returnValues = new uint256[][](returnKeys.length);
for (uint i = 0; i < returnKeys.length; i++) {
returnValues[i] = relationship.referred[returnKeys[i]];
}
}
return (returnKeys, returnValues);
}
}
Security Considerations
Timestamp
The createdTimestamp only covers the block-level timestamp (based on block headers), which does not support fine-grained comparisons such as transaction-level.
Ownership and Reference
The change of ownership has nothing to do with the reference relationship. Normally, the distribution of profits complies with the agreement when the NFT was being created regardless of the change of ownership unless specified in the agreement.
Referring a token will not refer to its descendants by default. In the case that only a specific child token gets referred, it means the privity of the contract will involve nobody other than the owner of this specific child token. Alternatively, a chain-of-reference all the way from the root token to a specific very bottom child token (from root to leaf) can be constructed and recorded in the referring to explicitly define the distribution of profits.
Open Minting and Relationship Risks
The safeMint function has been deliberately designed to allow unrestricted minting and relationship setting, akin to the open referencing system seen in platforms such as Google Scholar. This decision facilitates strong flexibility, enabling any user to create and define relationships between NFTs without centralized control. While this design aligns with the intended openness of the system, it inherently carries certain risks. Unauthorized or incorrect references can be created, mirroring the challenges faced in traditional scholarly referencing, where erroneous citations may occur. Additionally, the open nature may expose the system to potential abuse by malicious actors, who might manipulate relationships or inflate the token supply. It is important to recognize that these risks are not considered design flaws but intentional trade-offs, which balance the system's flexibility against potential reliability concerns.
Stakeholders should be aware that the on-chain data integrity guarantees extend only to what has been recorded on the blockchain and do not preclude the possibility of off-chain errors or manipulations. Thus, users and integrators should exercise caution and judgment in interpreting and using the relationships and other data provided by this system.
Copyright
Copyright and related rights waived via CC0.