Skip to main content

Non-Fungible Token JSON Metadata (TIP-4.2.2)

author: ELena Khramtsova <Helen.Andrianova@gmail.com>, Aleksandr Khramtsov <aleksandr.hramcov@gmail.com>
type: Contract
created: 2024-06-07
Requires: TIP-6

Abstract​

This is an alternative standard for storing metadata, but in a more familiar form for EVM users of such networks. It is not compatible with basic Tip4.2

This standard proposes storing metadata outside the blockchain (centralized backing, ipfs, etc.)

Motivation​

The implementation below solves several problems at once:

  • For Mystery-type collections, it makes reveal cheap and makes it easier to execute
  • Helps avoid storing json onchain. Storing and replacing json in a contract is expensive.
  • Makes it possible to change metadata without making a bunch of transactions to the blockchain
  • Familiar metadata format for those who have already released collections on EVM
  • In the future, this will make it easier to bridge/issue NFT on multiple blockchains

Specification​

The keywords “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

TIP4_2_2Collection​

New features appear in the collection.

pragma ever-solidity >= 0.62.0;

interface ITIP4_2_2Collection {

    /// The TIP-6.1 identifier for this interface is 0x244a5200

    /// @notice The event emits when set or change collection metadata
    event collectionMetadataUpdated();

    /// @notice The event emits when set or change NFTs metadata
    event nftMetadataUpdated();

    /// @notice build url to get metadata for NFT
    /// @return nftUrl - url to get metadata for NFT
    /// @param parts is TvmCell from NFT for build the link to metadata
    function getNftUrl(TvmCell parts) external responsible returns (string nftUrl);

    /// @notice build url to get metadata for NFT
    /// @return collectionUrl - url to get metadata for NFT
    function getCollectionUrl() external view responsible returns (string collectionUrl);

}

NOTE The TIP-6.1 identifier for this interface is 0x244a5200.

TIP4_2_2Collection.getNftUrl()​

function getNftUrl(TvmCell parts) external responsible returns (string nftUrl);
  • parts (TvmCell) - is TvmCell from NFT for build the link to metadata

The function, based on the main link and the part it received, builds the final link to the NFT metadata. In the case of collections, mystery box can describe more complex logic in which the display of the final link will depend on the flag the sale of the collection is completed or not.

TIP4_2_2Collection.getCollectionUrl()​

function getCollectionUrl() external view responsible returns (string collectionUrl);

The function is analogous to the getJson function in the Type4.2 standard but returns not json but a link to the json metadata of the collection.

event collectionMetadataUpdated();
event nftMetadataUpdated();

You must emit them when you change the metadata of collection or NFT.

TIP4_2_2NFT​

Each NFT now stores only a part of the link by which the metadata for it can be uniquely identified, and the metadata can be obtained by attaching this part to the collection function getNftUrl(TvmCell parts).

NOTE The TIP-6.1 identifier for this interface is 0x7239d7b1.

pragma ever-solidity >= 0.62.0;

interface ITIP4_2_2NFT {


    /// The TIP-6.1 identifier for this interface is 0x7239d7b1.

    /// @notice event emits when update NFT part.
    event metadataUpdated();

    /// @notice NFT part to get metadata
    /// @return part - TvmCell allows to build URL with metadata for this NFT
    function getUrlParts() external view responsible returns (TvmCell part);

}

ITIP4_2_2NFT.getUrlParts()​

function getUrlParts() external view responsible returns (TvmCell part);

The function returns the part identifying the NFT in the form of a TvmCell, which gives greater variability. In the simplest version, this could be id.

You must emit event metadataUpdated() when NFT part update.

Metadata format​

JSON metadata type: "Basic NFT"

The Basic NFT use for links to files stores in web. JSON fields contain information about item, files and preview info.

The Basic NFT describes fields that must be in JSON. The attributes field may not be present in the JSON metadata.

Field nametypeValueDescription
typestring"Basic NFT"Constant name for this type
namestringName of the object
descriptionstringDescription of the object
previewobjectObject preview
preview.sourcestringLink to object. Contains protocol and data source. Delimiter is :
preview.mimetypestringMime type of object
filesarrayArray of objects.
file.sourcestringLink to object. Contains protocol and data source. Delimiter is :
file.mimetypestringMime type of object
attributesarrayArray of objects.
attributes.trait_typestringType of attribute (Base, Eyes ...)
attributes.valuestringValue of attribute (Starfish, Blue ...)
external_urlstringURL to website

Example​

{
    "type": "Basic NFT",
    "name": "Sample Name",
    "description": "Hello world!",
    "preview": {
        "source": "https://everscale.network/images/Backgrounds/Main/main-hero.png",
        "mimetype": "image/png"
    },
    "files": [
        {
            "source": "https://everscale.network/images/Backgrounds/Main/main-hero.png",
            "mimetype": "image/png"
        }
    ],
     "attributes": [
         {
              "trait_type": "Base", 
              "value": "Starfish"
         }, 
         {
              "trait_type": "Eyes", 
              "value": "blue"
         } ]
    "external_url": "https://everscale.network"
}

You can extend Basic NFT type for your custom fields.

How to add the new JSON metadata type?​

For added new metadata type of TIP-4.2.2

  • Create product that use new JSON type.
  • Send PR for change the docs.
  • Explain why it will be in Standard.

References​