⚠️ Draft Standards Track: ERC

ERC-7510: Cross-Contract Hierarchical NFT

An extension of ERC-721 to maintain hierarchical relationship between tokens from different contracts.

Authors	Ming Jiang (@minkyn), Zheng Han (@hanbsd), Fan Yang (@fayang)
Created	2023-08-24
Discussion Link	https://ethereum-magicians.org/t/eip-7510-cross-contract-hierarchical-nft/15687
Requires	EIP-721

Abstract
Motivation
Specification
Rationale
Backwards Compatibility
Test Cases
Reference Implementation
Security Considerations
Copyright

Abstract

This standard is an extension of ERC-721. It proposes a way to maintain hierarchical relationship between tokens from different contracts. This standard provides an interface to query the parent tokens of an NFT or whether the parent relation exists between two NFTs.

Motivation

Some NFTs want to generate derivative assets as new NFTs. For example, a 2D NFT image would like to publish its 3D model as a new derivative NFT. An NFT may also be derived from multiple parent NFTs. Such cases include a movie NFT featuring multiple characters from other NFTs. This standard is proposed to record such hierarchical relationship between derivative NFTs.

Existing ERC-6150 introduces a similar feature, but it only builds hierarchy between tokens within the same contract. More than often we need to create a new NFT collection with the derivative tokens, which requires cross-contract relationship establishment. In addition, deriving from multiple parents is very common in the scenario of IP licensing, but the existing standard doesn’t support that either.

Specification

Solidity interface available at IERC7510.sol:

/// @notice The struct used to reference a token in an NFT contract
struct Token {
    address collection;
    uint256 id;
}

interface IERC7510 {

    /// @notice Emitted when the parent tokens for an NFT is updated
    event UpdateParentTokens(uint256 indexed tokenId);

    /// @notice Get the parent tokens of an NFT
    /// @param tokenId The NFT to get the parent tokens for
    /// @return An array of parent tokens for this NFT
    function parentTokensOf(uint256 tokenId) external view returns (Token[] memory);

    /// @notice Check if another token is a parent of an NFT
    /// @param tokenId The NFT to check its parent for
    /// @param otherToken Another token to check as a parent or not
    /// @return Whether `otherToken` is a parent of `tokenId`
    function isParentToken(uint256 tokenId, Token memory otherToken) external view returns (bool);

    /// @notice Set the parent tokens for an NFT
    /// @param tokenId The NFT to set the parent tokens for
    /// @param parentTokens The parent tokens to set
    function setParentTokens(uint256 tokenId, Token[] memory parentTokens) external;

}

Rationale

This standard differs from ERC-6150 in mainly two aspects: supporting cross-contract token reference, and allowing multiple parents. But we try to keep the naming consistent overall.

In addition, we didn’t include child relation in the interface. An original NFT exists before its derivative NFTs. Therefore we know what parent tokens to include when minting derivative NFTs, but we wouldn’t know the children tokens when minting the original NFT. If we have to record the children, that means whenever we mint a derivative NFT, we need to call on its original NFT to add it as a child. However, those two NFTs may belong to different contracts and thus require different write permissions, making it impossible to combine the two operations into a single transaction in practice. As a result, we decide to only record the parent relation from the derivative NFTs.

Backwards Compatibility

No backwards compatibility issues found.

Test Cases

Test cases available at: ERC7510.test.ts:

import { loadFixture } from "@nomicfoundation/hardhat-toolbox/network-helpers";
import { expect } from "chai";
import { ethers } from "hardhat";

const NAME = "NAME";
const SYMBOL = "SYMBOL";
const TOKEN_ID = 1234;

const PARENT_1_COLLECTION = "0xDEAdBEEf00000000000000000123456789ABCdeF";
const PARENT_1_ID = 8888;
const PARENT_1_TOKEN = { collection: PARENT_1_COLLECTION, id: PARENT_1_ID };

const PARENT_2_COLLECTION = "0xBaDc0ffEe0000000000000000123456789aBCDef";
const PARENT_2_ID = 9999;
const PARENT_2_TOKEN = { collection: PARENT_2_COLLECTION, id: PARENT_2_ID };

describe("ERC7510", function () {

  async function deployContractFixture() {
    const [deployer, owner] = await ethers.getSigners();

    const contract = await ethers.deployContract("ERC7510", [NAME, SYMBOL], deployer);
    await contract.mint(owner, TOKEN_ID);

    return { contract, owner };
  }

  describe("Functions", function () {
    it("Should not set parent tokens if not owner or approved", async function () {
      const { contract } = await loadFixture(deployContractFixture);

      await expect(contract.setParentTokens(TOKEN_ID, [PARENT_1_TOKEN]))
        .to.be.revertedWith("ERC7510: caller is not owner or approved");
    });

    it("Should correctly query token without parents", async function () {
      const { contract } = await loadFixture(deployContractFixture);

      expect(await contract.parentTokensOf(TOKEN_ID)).to.have.lengthOf(0);

      expect(await contract.isParentToken(TOKEN_ID, PARENT_1_TOKEN)).to.equal(false);
    });

    it("Should set parent tokens and then update", async function () {
      const { contract, owner } = await loadFixture(deployContractFixture);

      await contract.connect(owner).setParentTokens(TOKEN_ID, [PARENT_1_TOKEN]);

      let parentTokens = await contract.parentTokensOf(TOKEN_ID);
      expect(parentTokens).to.have.lengthOf(1);
      expect(parentTokens[0].collection).to.equal(PARENT_1_COLLECTION);
      expect(parentTokens[0].id).to.equal(PARENT_1_ID);

      expect(await contract.isParentToken(TOKEN_ID, PARENT_1_TOKEN)).to.equal(true);
      expect(await contract.isParentToken(TOKEN_ID, PARENT_2_TOKEN)).to.equal(false);

      await contract.connect(owner).setParentTokens(TOKEN_ID, [PARENT_2_TOKEN]);

      parentTokens = await contract.parentTokensOf(TOKEN_ID);
      expect(parentTokens).to.have.lengthOf(1);
      expect(parentTokens[0].collection).to.equal(PARENT_2_COLLECTION);
      expect(parentTokens[0].id).to.equal(PARENT_2_ID);

      expect(await contract.isParentToken(TOKEN_ID, PARENT_1_TOKEN)).to.equal(false);
      expect(await contract.isParentToken(TOKEN_ID, PARENT_2_TOKEN)).to.equal(true);
    });

    it("Should burn and clear parent tokens", async function () {
      const { contract, owner } = await loadFixture(deployContractFixture);

      await contract.connect(owner).setParentTokens(TOKEN_ID, [PARENT_1_TOKEN, PARENT_2_TOKEN]);
      await contract.burn(TOKEN_ID);

      await expect(contract.parentTokensOf(TOKEN_ID)).to.be.revertedWith("ERC7510: query for nonexistent token");
      await expect(contract.isParentToken(TOKEN_ID, PARENT_1_TOKEN)).to.be.revertedWith("ERC7510: query for nonexistent token");
      await expect(contract.isParentToken(TOKEN_ID, PARENT_2_TOKEN)).to.be.revertedWith("ERC7510: query for nonexistent token");

      await contract.mint(owner, TOKEN_ID);

      expect(await contract.parentTokensOf(TOKEN_ID)).to.have.lengthOf(0);
      expect(await contract.isParentToken(TOKEN_ID, PARENT_1_TOKEN)).to.equal(false);
      expect(await contract.isParentToken(TOKEN_ID, PARENT_2_TOKEN)).to.equal(false);
    });
  });

  describe("Events", function () {
    it("Should emit event when set parent tokens", async function () {
      const { contract, owner } = await loadFixture(deployContractFixture);

      await expect(contract.connect(owner).setParentTokens(TOKEN_ID, [PARENT_1_TOKEN, PARENT_2_TOKEN]))
        .to.emit(contract, "UpdateParentTokens").withArgs(TOKEN_ID);
    });
  });

});

Reference Implementation

Reference implementation available at: ERC7510.sol:

// SPDX-License-Identifier: CC0-1.0

pragma solidity ^0.8.0;

import "@openzeppelin/contracts/token/ERC721/ERC721.sol";

import "./IERC7510.sol";

contract ERC7510 is ERC721, IERC7510 {

    mapping(uint256 => Token[]) private _parentTokens;
    mapping(uint256 => mapping(address => mapping(uint256 => bool))) private _isParentToken;

    constructor(
        string memory name, string memory symbol
    ) ERC721(name, symbol) {}

    function supportsInterface(
        bytes4 interfaceId
    ) public view virtual override returns (bool) {
        return interfaceId == type(IERC7510).interfaceId || super.supportsInterface(interfaceId);
    }

    function parentTokensOf(
        uint256 tokenId
    ) public view virtual override returns (Token[] memory) {
        require(_exists(tokenId), "ERC7510: query for nonexistent token");
        return _parentTokens[tokenId];
    }

    function isParentToken(
        uint256 tokenId, Token memory otherToken
    ) public view virtual override returns (bool) {
        require(_exists(tokenId), "ERC7510: query for nonexistent token");
        return _isParentToken[tokenId][otherToken.collection][otherToken.id];
    }

    function setParentTokens(
        uint256 tokenId, Token[] memory parentTokens
    ) public virtual override {
        require(_isApprovedOrOwner(_msgSender(), tokenId), "ERC7510: caller is not owner or approved");
        _clear(tokenId);
        for (uint256 i = 0; i < parentTokens.length; i++) {
            _parentTokens[tokenId].push(parentTokens[i]);
            _isParentToken[tokenId][parentTokens[i].collection][parentTokens[i].id] = true;
        }
        emit UpdateParentTokens(tokenId);
    }

    function _burn(
        uint256 tokenId
    ) internal virtual override {
        super._burn(tokenId);
        _clear(tokenId);
    }

    function _clear(
        uint256 tokenId
    ) private {
        Token[] storage parentTokens = _parentTokens[tokenId];
        for (uint256 i = 0; i < parentTokens.length; i++) {
            delete _isParentToken[tokenId][parentTokens[i].collection][parentTokens[i].id];
        }
        delete _parentTokens[tokenId];
    }

}

Security Considerations

Parent tokens of an NFT may point to invalid data for two reasons. First, parent tokens could be burned later. Second, a contract implementing setParentTokens might not check the validity of parentTokens arguments. For security consideration, applications that retrieve parent tokens of an NFT need to verify they exist as valid tokens.

Copyright

Citation

Please cite this document as:

Ming Jiang (@minkyn), Zheng Han (@hanbsd), Fan Yang (@fayang), "ERC-7510: Cross-Contract Hierarchical NFT [DRAFT]," Ethereum Improvement Proposals, no. 7510, August 2023. [Online serial]. Available: https://eips.ethereum.org/EIPS/eip-7510.