ERC-7160 — ERC-721 Multi-Metadata Extension

Back to Token Standards

ERC-7160: ERC-721 Multi-Metadata Extension

ERC-7160 lets a single NFT expose multiple metadata URIs, with one "active" URI returned by the canonical tokenURI(tokenId) call. Used by:

• Evolving NFTs — character art that changes with story progression; the contract tracks the chapter index, marketplaces show the active one.
• Dynamic-state NFTs — game items with multiple visual states (default / equipped / damaged); state changes flip the active index.
• Multi-vendor NFTs — collections that ship with both a canonical artwork URI and licensed remix URIs from different artists.
• Versioned metadata — V1 / V2 / V3 metadata snapshots, with the contract tracking which is current.

The key advantage over "just call setTokenURI": ERC-7160 keeps all historical URIs available at distinct indices, so off-chain consumers can show "this NFT used to look like X, now looks like Y" or roll back to a previous version.

Required Interface

interface IERC7160 {
    event TokenUriPinned(uint256 indexed tokenId, uint256 indexed index);
    event TokenUriUnpinned(uint256 indexed tokenId);

    /// Returns (URI list, active index, isPinned).
    function tokenURIs(uint256 tokenId)
        external view returns (uint256 index, string[] memory uris, bool pinned);

    function pinTokenURI(uint256 tokenId, uint256 index) external;
    function unpinTokenURI(uint256 tokenId) external;

    function hasPinnedTokenURI(uint256 tokenId) external view returns (bool);
}

The pin / unpin distinction matters: an unpinned NFT defaults to a contract-defined active URI (often the last one added); a pinned NFT sticks to a specific index until explicitly unpinned.

Neo Equivalent: NEP-11 + URI List + Active-Index Storage

NEP-11's properties(tokenId) → Map returns the metadata; ERC-7160 adds a URI list and a per-token active index. The Neo port stores both as prefixed keys:

public static (BigInteger, ByteString[], bool) TokenUris(ByteString tokenId)
{
    var uris   = GetUris(tokenId);
    var index  = GetActiveIndex(tokenId);
    var pinned = IsPinned(tokenId);
    return (index, uris, pinned);
}

public static void PinTokenUri(ByteString tokenId, BigInteger index)
{
    if (!Runtime.CheckWitness(OwnerOf(tokenId))) throw new Exception("NEP11:NoAuth");
    var uris = GetUris(tokenId);
    if (index >= uris.Length) throw new Exception("NEP11:IndexOutOfRange");
    SetActiveIndex(tokenId, index);
    SetPinned(tokenId, true);
    OnTokenUriPinned(tokenId, index);
}

ERC-7160 (Ethereum)	Neo Equivalent	Notes
tokenURIs(tokenId) returning (index, uris[], pinned)	TokenUris(tokenId) returning the same triple	Direct shape
pinTokenURI(tokenId, index)	PinTokenUri(tokenId, index) with witness check	Owner-only
unpinTokenURI(tokenId)	UnpinTokenUri(tokenId) resets to contract-default
tokenURI(tokenId) returns active URI	NEP-11 properties(tokenId)["uri"] returns active URI	Maintains NEP-11 compatibility
TokenUriPinned / Unpinned events	OnTokenUriPinned / OnTokenUriUnpinned notifications

Composition

• ERC-4906 — NFT metadata update event. ERC-7160's pin/unpin should emit ERC-4906's MetadataUpdate(tokenId) event so marketplaces refresh their cached metadata.
• ERC-2981 — royalties. Active URI changes don't affect royalty calculations.
• ERC-5114 + ERC-5192 — soulbound NFTs that evolve. Pin index might be governed by external logic (achievement contract, chapter-progression contract).

Migration Notes

Porting an ERC-7160 collection to Neo:

1. Add a per-token URI list storage prefix.
2. Add a per-token active-index storage prefix (defaults to 0 if absent).
3. Add a per-token pinned-flag storage prefix.
4. Override NEP-11's properties(tokenId)["uri"] to return the active URI.
5. Implement PinTokenUri / UnpinTokenUri / TokenUris per the shape above.
6. Emit ERC-4906's metadata-update event on every pin/unpin change.

The on-chain cost is per-URI storage; for collections with many URIs per token, consider storing only the IPFS / HTTPS path and computing the full URI from a contract-level base.

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

contract MultiMetadataNFT {
    mapping(uint256 => address) public ownerOf;
    mapping(uint256 => string[]) internal _uris;
    mapping(uint256 => uint256)  internal _activeIndex;
    mapping(uint256 => bool)     internal _pinned;

    event TokenUriPinned(uint256 indexed tokenId, uint256 indexed index);
    event TokenUriUnpinned(uint256 indexed tokenId);
    event MetadataUpdate(uint256 _tokenId);  // ERC-4906

    function tokenURIs(uint256 tokenId)
        external view returns (uint256, string[] memory, bool)
    {
        return (_activeIndex[tokenId], _uris[tokenId], _pinned[tokenId]);
    }

    function tokenURI(uint256 tokenId) external view returns (string memory) {
        string[] memory uris = _uris[tokenId];
        require(uris.length > 0, "no uris");
        return uris[_activeIndex[tokenId]];
    }

    function pinTokenURI(uint256 tokenId, uint256 index) external {
        require(msg.sender == ownerOf[tokenId], "not owner");
        require(index < _uris[tokenId].length, "out of range");
        _activeIndex[tokenId] = index;
        _pinned[tokenId] = true;
        emit TokenUriPinned(tokenId, index);
        emit MetadataUpdate(tokenId);
    }

    function unpinTokenURI(uint256 tokenId) external {
        require(msg.sender == ownerOf[tokenId], "not owner");
        _pinned[tokenId] = false;
        // Active index stays where it was; just no longer pinned.
        emit TokenUriUnpinned(tokenId);
        emit MetadataUpdate(tokenId);
    }

    function hasPinnedTokenURI(uint256 tokenId) external view returns (bool) {
        return _pinned[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("MultiMetadataNFT")]
[ContractPermission("*", "*")]
[SupportedStandards(NepStandard.Nep11)]
public class MultiMetadataNFT : Nep11Token<TokenState>
{
    public override string Symbol => "MULTI";

    private const byte Prefix_UriList   = 0x50;  // tokenId -> serialized string[]
    private const byte Prefix_ActiveIdx = 0x51;
    private const byte Prefix_Pinned    = 0x52;

    [DisplayName("TokenUriPinned")]
    public static event Action<ByteString, BigInteger> OnTokenUriPinned;

    [DisplayName("TokenUriUnpinned")]
    public static event Action<ByteString> OnTokenUriUnpinned;

    [DisplayName("MetadataUpdate")]
    public static event Action<ByteString> OnMetadataUpdate;  // ERC-4906 mirror

    public static (BigInteger, string[], bool) TokenUris(ByteString tokenId)
        => (GetActiveIndex(tokenId), GetUris(tokenId), IsPinned(tokenId));

    public static void AddUri(ByteString tokenId, string uri)
    {
        // Admin-only; appends to URI list.
        if (!Runtime.CheckWitness(GetAdmin())) throw new Exception("admin only");
        var uris = GetUris(tokenId);
        var newList = new string[uris.Length + 1];
        for (var i = 0; i < uris.Length; i++) newList[i] = uris[i];
        newList[uris.Length] = uri;
        SetUris(tokenId, newList);
        OnMetadataUpdate(tokenId);
    }

    public static void PinTokenUri(ByteString tokenId, BigInteger index)
    {
        if (!Runtime.CheckWitness(OwnerOf(tokenId))) throw new Exception("NEP11:NoAuth");
        var uris = GetUris(tokenId);
        if (index < 0 || index >= uris.Length) throw new Exception("NEP11:IndexOutOfRange");
        SetActiveIndex(tokenId, index);
        SetPinned(tokenId, true);
        OnTokenUriPinned(tokenId, index);
        OnMetadataUpdate(tokenId);
    }

    public static void UnpinTokenUri(ByteString tokenId)
    {
        if (!Runtime.CheckWitness(OwnerOf(tokenId))) throw new Exception("NEP11:NoAuth");
        SetPinned(tokenId, false);
        OnTokenUriUnpinned(tokenId);
        OnMetadataUpdate(tokenId);
    }

    [Safe]
    public static bool HasPinnedTokenUri(ByteString tokenId) => IsPinned(tokenId);

    // Helpers
    private static string[] GetUris(ByteString tokenId)
    {
        var raw = Storage.Get(Storage.CurrentContext, UriListKey(tokenId));
        return raw is null ? new string[0] : (string[])StdLib.Deserialize((ByteString)raw);
    }
    private static void SetUris(ByteString tokenId, string[] uris)
        => Storage.Put(Storage.CurrentContext, UriListKey(tokenId), StdLib.Serialize(uris));

    private static BigInteger GetActiveIndex(ByteString tokenId)
        => (BigInteger)(Storage.Get(Storage.CurrentContext, ActiveKey(tokenId)) ?? ByteString.Empty);
    private static void SetActiveIndex(ByteString tokenId, BigInteger idx)
        => Storage.Put(Storage.CurrentContext, ActiveKey(tokenId), idx);

    private static bool IsPinned(ByteString tokenId)
        => Storage.Get(Storage.CurrentContext, PinnedKey(tokenId)) is not null;
    private static void SetPinned(ByteString tokenId, bool pinned)
    {
        var k = PinnedKey(tokenId);
        if (pinned) Storage.Put(Storage.CurrentContext, k, 1);
        else        Storage.Delete(Storage.CurrentContext, k);
    }

    private static byte[] UriListKey(ByteString tokenId) => new byte[] { Prefix_UriList   }.Concat(tokenId);
    private static byte[] ActiveKey(ByteString tokenId)  => new byte[] { Prefix_ActiveIdx }.Concat(tokenId);
    private static byte[] PinnedKey(ByteString tokenId)  => new byte[] { Prefix_Pinned    }.Concat(tokenId);

    private static UInt160 GetAdmin() => (UInt160)"0x0000000000000000000000000000000000000000";
}

Use With Game / Story State

A game contract that tracks character progression can call PinTokenUri(tokenId, chapterIndex) whenever the player advances. The NFT contract emits MetadataUpdate(tokenId) and marketplaces / wallets refresh — the visual changes everywhere without the contract needing to push to each consumer individually.

For "evolve over time" patterns, store the unpinned-default-index formula in the contract (e.g. GetUris(tokenId).Length - 1 always returns the latest); leaving the NFT unpinned means it auto-updates as new URIs are added.