Skip to content

2_1.md

Latest commit

 

History

History
342 lines (264 loc) · 12.7 KB

2_1.md

File metadata and controls

342 lines (264 loc) · 12.7 KB
Raw
title 4.2. On-chain JSON Metadata
sidebar_position 2
slug /standard/TIP-4.2.1

Non-Fungible Token on-chain JSON Metadata (TIP-4.2.1)

Requires: TIP-6.1

Abstract

Token-specific metadata is stored as a string in smart contract. To facilitate an off-chain working with metadata, it is JSON object. The below metadata structure allows the marketplaces to read and display the details about the assets which your NFTs represent.

This standard provides optional JSON fields and contract interface.

Motivation

A standard fields facilitate displaying of NFT data for: wallets, explorers, marketplaces, etc.

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

JSON metadata

Return the metadata as JSON

Every TIP4.2.1 compliant contract must implement the TIP4_2JSON_Metadata interface and TIP-6.1 interfaces

pragma ton-solidity >= 0.58.0;

interface TIP4_2JSON_Metadata {

    /// @notice metadata in JSON format
    /// @return json The JSON string with metadata
    function getJson() external view responsible returns (string json);

}

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

TIP4_2JSON_Metadata.getJson()

function getJson() external view responsible returns (string json);
  • json (string) - The JSON string with metadata

The function return metadata as a JSON string.

Empty JSON metadata

Empty JSON metadata is represented as a blank JSON object or an empty string.

{}

JSON metadata type

Not empty JSON must have "type" field

{"type":"string"}

Application that read JSON metadata use "type" field for parsing standard or custom JSON fields.

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

Field name type Value Description
type string "Basic NFT" Constant name for this type
name string Name of the object
description string Description of the object
preview object Object preview
preview.source string Link to object. Contains protocol and data source. Delimiter is :
preview.mimetype string Mime type of object
files array Array of objects.
file.source string Link to object. Contains protocol and data source. Delimiter is :
file.mimetype string Mime type of object
external_url string URL 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"
        }
    ],
    "external_url": "https://everscale.network"
}

You can extend Basic NFT type for your custom fields.

JSON metadata type: metaverse.region

The metaverse.region JSON object stores the unique reference to a specific region (bundle of regions) inside a metaverse.

Field name Type Description Value
type string NFT type metaverse.region
version string Model version (for future compatibility) 1.0
meta object Region metadata
regions array<object> Region parameters (multi-component regions allowed)

Example

{
	"type": "metaverse.region",
	"version": "1.0",
	"meta": {
		"server": {
			"type": "minecraft",
			"url": "http://10.10.10.10:25565",
			"pubkey": "c843d424bba89625d64fb592975180023e46b499388856fa832e287484adc4aa"
		},
		"signature": "cc9d3377f78d33a3d2d412d173f2b6e9e6dd06af19749d95032ea7c78eb07d873ddfe0b241a190900422732207dbbdc987b1bbcfd74d56404f0ab0d65d4f930e"
	},
	"regions": [
		{
			"shape": "cuboid",
			"params": {
				"position1": {
					"x": "0",
					"y": "-50",
					"z": "0"
				},
				"position2": {
					"x": "16",
					"y": "200",
					"z": "16"
				}
			}
		}
	]
}

Region metadata

This section must contain at least a minimum of the required information about the metaverse server where the region is located.

Field name Type Description Example value
server.type string Type of metaverse that has issued the NFT token minecraft
server.url uri (optional) Address where the server is located. Typically, the URL, from which the server actual metadata like name, description, etc. can be extracted. 10.10.10.10:25565
server.pubkey string Public key issued by the compatible NFT adapter used to sign the NFT content data
signature string HEX representation of the signature, generated using ed25519 algorithm based on the contents of regions array content (without the object name) and server private key.

Before generation, the base JSON array must be compacted (i.e. all the whitespace and line breaks must be removed). In the example above, it will look as follows:

[{"shape":"cuboid","params":{"position1":{"x":"0","y":"-50","z":"0"},"position2":{"x":"16","y":"200","z":"16"}}}]

Region shape types

The reference implementation is inspired by Minecraft's Worldedit primitive region models.

Type Description Reference model
cuboid Box-shaped region Link
cylinder Cylinder-shaped region Link
sphere Spheric-shaped region Link
polygon2d 2D-polygonal-shaped region Link

Cuboid

Cuboid is the simplest and the most popular shape of a region typically used in most metaverses.

It is defined by X, Y and Z coordinates of two points in the space (the order is insignificant), one of which is considered as the start (bottom, minimum) and the other one as the end (top, maximum) of the region.

Cuboid object specification
Field name Type Description Value
shape string Type of shape cuboid
params.position1 xyz First vertex of the cuboid
params.position2 xyz Second vertex of the cuboid
Example usage
{
	"type": "metaverse.region",
	"version": "1.0",
	"meta": {},
	"regions": [
		{
			"shape": "cuboid",
			"params": {
				"position1": {
					"x": "0",
					"y": "-50",
					"z": "0"
				},
				"position2": {
					"x": "16",
					"y": "200",
					"z": "16"
				}
			}
		}
	]
}

Cylinder

Cylinders are commonly used in central areas of large objects (lize plazas, fountains, etc).

They are defined by coordinates of basic central point, radius, and height.

Cylinder object specification
Field name Type Description Value
shape string Type of shape cylinder
params.center xyz Basic central point of the cylinder
params.radius string Radius of the cylinder (number in string format for maximum compatibility)
params.height string Height of the cylinder (number in string format for maximum compatibility)

For the avoidance of doubt, the Y coordinate of the opposite cylinder's side is calculated as Y_basic + height
Example usage
{
	"type": "metaverse.region",
	"version": "1.0",
	"meta": {},
	"regions": [
		{
			"shape": "cylinder",
			"params": {
				"center": {
					"x": "0",
					"y": "-50",
					"z": "0"
				},
				"radius": "16",
				"height": "100"
			}
		}
	]
}

Sphere

Spheres are typically used as parts of complex objects like sculptures, buildings, etc.

Sphere is described by coordinates of central point and radius.

Spherical object specification
Field name Type Description Value
shape string Type of shape sphere
params.center xyz Basic central point of the sphere
params.radius string Radius of the sphere (number in string format for maximum compatibility)
Example usage
{
	"type": "metaverse.region",
	"version": "1.0",
	"meta": {},
	"regions": [
		{
			"shape": "sphere",
			"params": {
				"center": {
					"x": "0",
					"y": "-50",
					"z": "0"
				},
				"radius": "16"
			}
		}
	]
}

2D polygon

Polygons can represent an arbitrary set of vertices.

2D polygons assume that all vertices lay on the same plane. The whole object can be extended in height.

2D polygon object specification
Field name Type Description Value
shape string Type of shape polygon2d
params.points list<xyz> Coordinates of polygon vetices
params.height string Height of the object (number in string format for maximum compatibility).

For the avoidance of doubt, the Y coordinate of the opposite object's side is calculated as Y_basic + height, where Y_basic is the Y coordinate of the first vertex in the array above.

Shared models

XYZ
Field name Type Description Default value
x string X coordinate 0
y string Y coordinate 0
z string Z coordinate 0

Standard conventions

  • Numbers and coordinates interpretation depends on the specific metaverse defined in the meta section of the NFT. For this standard purpose, the following convention is applied:
    • X axis is a horizontal one pointing East;
    • Y axis is a vertical one pointing up;
    • Z is the orthogonal axis pointing south;

  • Numbers are stored as strings to ensure maximum compatibility;
  • Numbers must not use scientific notation.

How to add the new JSON metadata type?

For added new metadata type of TIP-4.2.1

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

References