ERC-7510 Cross-contract hierarchical NFTs (Cross-Contract Hierarchical NFT)
Draft · NFTs & multi-token · created 2023-08-24
An ERC-721 extension standard that lets parent-child relationships be recorded and queried between NFTs that live in different contracts.
Why it is needed
Sometimes you want to mint a derivative work of an NFT as a new NFT, such as releasing a 3D model as a new NFT derived from a 2D artwork NFT, or creating a movie NFT that features several character NFTs together. However, the existing ERC-6150 standard can only establish hierarchical relationships between tokens within the same contract. Derivative tokens are usually minted as a new collection, i.e. a new contract, so a relationship that crosses contracts is needed. It is also common for a single derivative NFT to come from multiple originals, as with intellectual property (IP) licensing, but the existing standard does not support having multiple parents either. Without this standard, there is no standardized on-chain way to record and verify which NFT is derived from which original.
What to implement
event UpdateParentTokens(uint256 indexed tokenId);: An event emitted when an NFT's list of parent tokens is updated.function parentTokensOf(uint256 tokenId) external view returns (Token[] memory);: Returns the array of parent tokens for the given NFT.function isParentToken(uint256 tokenId, Token memory otherToken) external view returns (bool);: Returns whether another token is a parent of the given NFT.function setParentTokens(uint256 tokenId, Token[] memory parentTokens) external;: Sets the list of parent tokens for the given NFT.
In depth
Cross-contract references via the Token struct
A Token struct is defined to reference tokens in other contracts. It has two fields: collection (address) and id (uint256). Since a token ID alone within the same contract cannot specify a token in an external collection, references are made as a pair of contract address and token ID. parentTokensOf, isParentToken, and setParentTokens all use this struct.
Why only parents are recorded, not children
A child relationship is not included in the interface. Since the original NFT exists before the derivative NFT, at the time the derivative NFT is minted the parent is already known, but at the time the original is minted, what its children will be is not yet known. Recording children as well would require calling the original NFT contract to add a child every time a derivative NFT is minted, but since the two NFTs can belong to different contracts with different write permissions, bundling both operations into a single transaction is effectively impossible. So it was decided that only the parent relationship would be recorded, on the derivative NFT's side.
Differences from ERC-6150
The existing ERC-6150 also provides token hierarchy functionality, but it can only establish hierarchies between tokens within the same contract. This standard differs in two ways: it supports cross-contract token references and allows multiple parents. That said, an effort was made to keep the naming generally consistent with ERC-6150.
The storage structure and update approach of the reference implementation
The reference implementation manages _parentTokens (an array of Token structs per tokenId) together with _isParentToken (a triple mapping of tokenId, collection, id). setParentTokens checks that the caller is the owner or an approved address via _isApprovedOrOwner, then clears all existing parent records with _clear and replaces them with the new list, emitting an UpdateParentTokens event. In other words, this is a full replacement, not an addition. When a token is _burn'd, its parent records are cleared along with it, and queries for a nonexistent token revert. supportsInterface responds that it supports the IERC7510 interface ID.
Backward compatibility
This standard is an extension of ERC-721, and no backward compatibility issues have been found.
Proposal status
This ERC was created on August 24, 2023, and its current status is Draft. It is a proposal that has not been finalized and its contents may change.
Things to watch out for
- The parent token may be invalid: The parent token may later be burned, and a contract implementing setParentTokens may not validate the parentTokens argument. Applications that consume an NFT's parent tokens must therefore verify that those tokens are actually valid and exist.