ERC-5521 — Referable NFT

Back to Token Standards

ERC-5521: Referable NFT

ERC-5521 lets NFTs reference each other in a directed graph. A new NFT's mint can declare which NFTs it "refers to" (citations, remixes, parent works); each NFT exposes both its forward references (what it cites) and its backward references (what cites it). Used for:

• Citation graphs — academic NFTs citing other research NFTs.
• Remix attribution — derivative NFTs pointing back to originals (eligible for royalty splits).
• Influencer / referral economies — NFTs minted via a referral link record the referrer.
• Wikipedia-style NFT-as-encyclopedia — articles citing other articles via NFT references.

Required Interface

interface IERC5521 {
    event UpdateNode(uint256 indexed tokenId, address indexed owner,
                     uint256[] referring, uint256[] referred);

    function safeMint(uint256 tokenId, uint256[] calldata referrers) external;
    function setNode(uint256 tokenId, uint256[] calldata referrers) external;

    function referringOf(address contract_, uint256 tokenId)
        external view returns (uint256[] memory);
    function referredOf(address contract_, uint256 tokenId)
        external view returns (uint256[] memory);
    function createdTimestampOf(address contract_, uint256 tokenId) external view returns (uint256);
}

When a new NFT is minted with referrers, the contract automatically updates each referrer's "referred" list to include the new NFT. Forms a citation graph queryable from either direction.

Neo Equivalent: NEP-11 + Referring/Referred Edge Storage

public static void SafeMintWithReferrers(UInt160 to, ByteString tokenId, ByteString[] referrers)
{
    if (!Runtime.CheckWitness(GetIssuer())) throw new Exception("NEP11:NotIssuer");
    Mint(tokenId, new TokenState { Owner = to });  // NEP-11 base: Mint(tokenId, TokenState)

    // Store outgoing edges (this token → referrers).
    Storage.Put(Storage.CurrentContext, ReferringKey(tokenId), StdLib.Serialize(referrers));
    Storage.Put(Storage.CurrentContext, CreatedKey(tokenId), Runtime.Time);

    // Update reverse edges (referrers → this token).
    for (var i = 0; i < referrers.Length; i++)
    {
        var existing = ReferredOf(referrers[i]);
        var updated  = new ByteString[existing.Length + 1];
        for (var j = 0; j < existing.Length; j++) updated[j] = existing[j];
        updated[existing.Length] = tokenId;
        Storage.Put(Storage.CurrentContext, ReferredKey(referrers[i]), StdLib.Serialize(updated));
    }
    OnUpdateNode(tokenId, to, referrers, new ByteString[0]);
}

ERC-5521 (Ethereum)	Neo Equivalent	Notes
safeMint(tokenId, referrers[])	SafeMintWithReferrers(...)	Atomic mint + edge updates
referringOf(contract, tokenId)	ReferringOf(tokenId) (single-contract)	Outgoing edges
referredOf(contract, tokenId)	ReferredOf(tokenId) (single-contract)	Incoming edges
createdTimestampOf(contract, tokenId)	CreatedTimestampOf(tokenId)	Timestamp at mint
UpdateNode event	OnUpdateNode notification

The contract parameter in the Solidity interface lets you reference NFTs across contracts; the simplest Neo port is single-contract (cross-contract referrals require a separate graph contract).

Composition

• ERC-2981 — royalty. Royalty splits propagate back through the citation graph (a remix pays royalty to its referenced originals).
• ERC-5375 — author + consent. Citations preserve attribution to the cited NFTs' authors.
• ERC-7007 — AI-generated content. AI-generated NFTs cite their prompt source NFTs.
• ERC-6150 — hierarchical NFTs. Hierarchies are parent-child trees; citations are arbitrary directed graphs.

Migration Notes

For citation/remix-economy NFT collections:

1. The reverse-edge update at mint is the expensive part — for N referrers, that's N storage writes. Cap the referrer list size at mint to bound cost.
2. Cross-contract references need a separate graph contract that maintains (contractA, tokenA, contractB, tokenB) edges; the Neo port supports this via a registry pattern similar to ERC-6551.
3. Citation graphs can be queried off-chain for analytics; the on-chain storage is the source of truth.

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

contract ERC5521 {
    mapping(uint256 => uint256[]) internal _referring;
    mapping(uint256 => uint256[]) internal _referred;
    mapping(uint256 => uint256)   internal _created;

    event UpdateNode(uint256 indexed tokenId, address indexed owner,
                     uint256[] referring, uint256[] referred);

    function safeMint(uint256 tokenId, uint256[] calldata referrers) external {
        // ... base mint ...
        _referring[tokenId] = referrers;
        _created[tokenId]   = block.timestamp;
        for (uint256 i = 0; i < referrers.length; ++i) {
            _referred[referrers[i]].push(tokenId);
        }
        emit UpdateNode(tokenId, msg.sender, referrers, new uint256[](0));
    }

    function referringOf(address /*c*/, uint256 tokenId) external view returns (uint256[] memory) {
        return _referring[tokenId];
    }
    function referredOf(address /*c*/, uint256 tokenId) external view returns (uint256[] memory) {
        return _referred[tokenId];
    }
}

using System;
using System.ComponentModel;
using System.Numerics;
using Neo;
using Neo.SmartContract.Framework;
using Neo.SmartContract.Framework.Attributes;
using Neo.SmartContract.Framework.Native;
using Neo.SmartContract.Framework.Services;

namespace R3E.Examples;

[DisplayName("ReferableNFT")]
[ContractPermission("*", "*")]
[SupportedStandards(NepStandard.Nep11)]
public class ReferableNFT : Nep11Token<TokenState>
{
    public override string Symbol => "REFR";

    private const byte Prefix_Referring = 0xC0;
    private const byte Prefix_Referred  = 0xC1;
    private const byte Prefix_Created   = 0xC2;
    private const byte Prefix_Issuer    = 0xff;

    [DisplayName("UpdateNode")]
    public static event Action<ByteString, UInt160, ByteString[], ByteString[]> OnUpdateNode;

    public static void SafeMintWithReferrers(UInt160 to, ByteString tokenId, ByteString[] referrers)
    {
        var issuer = (UInt160)Storage.Get(Storage.CurrentContext, new byte[] { Prefix_Issuer });
        if (!Runtime.CheckWitness(issuer)) throw new Exception("NEP11:NotIssuer");
        if (referrers.Length > 50)         throw new Exception("NEP11:TooManyReferrers");

        Mint(tokenId, new TokenState { Owner = to });  // NEP-11 base: Mint(tokenId, TokenState)
        Storage.Put(Storage.CurrentContext, ReferringKey(tokenId), StdLib.Serialize(referrers));
        Storage.Put(Storage.CurrentContext, CreatedKey(tokenId),   Runtime.Time);

        for (var i = 0; i < referrers.Length; i++)
        {
            var existing = ReferredOf(referrers[i]);
            var updated  = new ByteString[existing.Length + 1];
            for (var j = 0; j < existing.Length; j++) updated[j] = existing[j];
            updated[existing.Length] = tokenId;
            Storage.Put(Storage.CurrentContext, ReferredKey(referrers[i]), StdLib.Serialize(updated));
        }
        OnUpdateNode(tokenId, to, referrers, new ByteString[0]);
    }

    public static ByteString[] ReferringOf(ByteString tokenId)
    {
        var raw = Storage.Get(Storage.CurrentContext, ReferringKey(tokenId));
        return raw is null ? new ByteString[0] : (ByteString[])StdLib.Deserialize((ByteString)raw);
    }

    public static ByteString[] ReferredOf(ByteString tokenId)
    {
        var raw = Storage.Get(Storage.CurrentContext, ReferredKey(tokenId));
        return raw is null ? new ByteString[0] : (ByteString[])StdLib.Deserialize((ByteString)raw);
    }

    public static BigInteger CreatedTimestampOf(ByteString tokenId)
        => (BigInteger)(Storage.Get(Storage.CurrentContext, CreatedKey(tokenId)) ?? ByteString.Empty);

    private static byte[] ReferringKey(ByteString tokenId) => new byte[] { Prefix_Referring }.Concat(tokenId);
    private static byte[] ReferredKey(ByteString tokenId)  => new byte[] { Prefix_Referred  }.Concat(tokenId);
    private static byte[] CreatedKey(ByteString tokenId)   => new byte[] { Prefix_Created   }.Concat(tokenId);
}