diff --git a/src/standard/TIP-4/2.md b/src/standard/TIP-4/2.md index 4e50af415..291e7ad3f 100644 --- a/src/standard/TIP-4/2.md +++ b/src/standard/TIP-4/2.md @@ -10,23 +10,23 @@ Requires: [TIP-6.1](./../TIP-6/1.md) ## 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. +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. Metadata of an NFT can be modified after it has been minted. -This standard provides optional JSON fields and contract interface. +This standard provides optional JSON fields and contract interfaces. ## Motivation A standard fields facilitate displaying of NFT data for: wallets, explorers, marketplaces, etc. -## Specification +Unlike ers721, we can store metadata in a smart contract. We have a way for the smart contract layer to communicate with a storage layer and provides a way for potential NFT collectors on Ethereum to verify that their NFT will not be modify. -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](https://datatracker.ietf.org/doc/html/rfc2119) +For the development of GameFi direction, you can use the concept of dynamic NFT metadata. Changes to a dynamic NFT metadata can be triggered by a smart contract. Typically, an oracle will send external data to the smart contract, which triggers a change in the NFT's metadata. The characteristics of that NFT, like its appearance, will then be updated. -## JSON metadata +## Specification -Return the metadata as JSON +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](https://datatracker.ietf.org/doc/html/rfc2119) -Every TIP4.2 compliant contract must implement the `TIP4_2JSON_Metadata` interface and [TIP-6.1](./../TIP-6/1.md) interfaces +Every TIP4.2 compliant contract “MUST” implement the `TIP4_2JSON_Metadata` interface and [TIP-6.1](./../TIP-6/1.md) interfaces ```solidity pragma ton-solidity >= 0.58.0; @@ -41,13 +41,38 @@ interface TIP4_2JSON_Metadata { ``` **NOTE** The [TIP-6.1](./../TIP-6/1.md) identifier for this interface is `0x24D7D5F5`. -### TIP4_2JSON_Metadata.getJson() +Every TIP4.2 compliant contract "MAY" implement the `TIP4_2DYNAMIC_JSON_Metadata` interface and [TIP-6.1](./../TIP-6/1.md) interfaces ```solidity -function getJson() external view responsible returns (string json); +pragma ton-solidity >= 0.58.0; + +interface TIP4_2DYNAMIC_JSON_Metadata { + + /// @notice This event emits when NFT metadata changed + event MetadataChanged(); + + /// @notice This event emits when NFT metadata frozen + /// @param frozen Metadata frozen status + event MetadataFrozen(bool frozen); + + /// @notice metadata in JSON format + /// @return frozen Metadata frozen status + function metadataFrozen() external view responsible returns (bool frozen); +} ``` -* `json` (`string`) - The JSON string with metadata +**NOTE** The [TIP-6.1](./../TIP-6/1.md) identifier for this interface is `0xXXXXXXXX`. + +The implementer of `TIP4_2DYNAMIC_JSON_Metadata` MUST emit ```MetadataFrozen``` event when NFT minted. + +The implementer of `TIP4_2DYNAMIC_JSON_Metadata` MUST emit ```MetadataFrozen``` event every time when frozen status changed. + +The implementer of `TIP4_2DYNAMIC_JSON_Metadata` SHOULD emit ```MetadataChanged``` event every time when NFT metadata changed. + +## Dynamic NFT +The dynamic metadata extension is OPTIONAL for TIP-4.2 -The function return metadata as a JSON string. +Dynamic NFT is an NFT that can change metadata based on external conditions. You can use dynamic NFT for game objects, nft breeding, change coordinates for physical objects, ticket statuses etc + +Change metadata function's signature is not included in the specification. Your contract may implement these by other means. ## Empty JSON metadata @@ -57,7 +82,7 @@ Empty JSON metadata is represented as a blank JSON object or an empty string. {} ``` -## JSON metadata type +## JSON metadata types Not empty JSON must have "type" field @@ -67,7 +92,7 @@ Not empty JSON must have "type" field Application that read JSON metadata use "type" field for parsing standard or custom JSON fields. -## JSON metadata type: "Basic NFT" +### 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. @@ -86,7 +111,7 @@ The `Basic NFT` describes fields that must be in JSON | **file.mimetype** | string || [Mime type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of object | | | **external_url** | string || URL to website | | -### Example +**Example** ```JSON { @@ -109,7 +134,7 @@ The `Basic NFT` describes fields that must be in JSON You can extend `Basic NFT` type for your custom fields. -## JSON metadata type: `metaverse.region` +### JSON metadata type: `metaverse.region` The `metaverse.region` JSON object stores the unique reference to a specific region (bundle of regions) inside a metaverse. @@ -153,7 +178,7 @@ The `metaverse.region` JSON object stores the unique reference to a specific reg } ``` -### Region metadata +#### Region metadata This section must contain at least a minimum of the required information about the metaverse server where the region is located. @@ -164,7 +189,7 @@ This section must contain at least a minimum of the required information about t | **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 +#### Region shape types The reference implementation is inspired by Minecraft's Worldedit primitive region models. @@ -175,13 +200,13 @@ The reference implementation is inspired by Minecraft's Worldedit primitive regi | **sphere** | Spheric-shaped region | [Link](https://github.com/EngineHub/WorldEdit/blob/b8a9c0070c72bbdd0d2c77fa8c537c01b0f73f85/worldedit-core/src/main/java/com/sk89q/worldedit/regions/selector/SphereRegionSelector.java) | | **polygon2d** | 2D-polygonal-shaped region | [Link](https://github.com/EngineHub/WorldEdit/blob/b8a9c0070c72bbdd0d2c77fa8c537c01b0f73f85/worldedit-core/src/main/java/com/sk89q/worldedit/regions/Polygonal2DRegion.java#L39) | -#### Cuboid +##### 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 +**Cuboid object specification** | Field name | Type | Description | Value | | --- | --- | --- | --: | @@ -189,7 +214,7 @@ It is defined by X, Y and Z coordinates of two points in the space (the order is | **params.position1** | [xyz](#xyz) | First vertex of the cuboid | | | **params.position2** | [xyz](#xyz) | Second vertex of the cuboid | | -##### Example usage +**Example** ```json { @@ -216,13 +241,13 @@ It is defined by X, Y and Z coordinates of two points in the space (the order is } ``` -#### Cylinder +##### 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 +**Cylinder object specification** | Field name | Type | Description | Value | | --- | --- | --- | --: | @@ -231,7 +256,7 @@ They are defined by coordinates of basic central point, radius, and height. | **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 +**Example** ```json { @@ -255,13 +280,13 @@ They are defined by coordinates of basic central point, radius, and height. } ``` -#### Sphere +##### 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 +**Spherical object specification** | Field name | Type | Description | Value | | --- | --- | --- | --: | @@ -269,7 +294,7 @@ Sphere is described by coordinates of central point and radius. | **params.center** | [xyz](#xyz) | Basic central point of the sphere | | | **params.radius** | string | Radius of the sphere (number in string format for maximum compatibility) | | -##### Example usage +**Example** ```json { @@ -292,13 +317,13 @@ Sphere is described by coordinates of central point and radius. } ``` -#### 2D polygon +##### 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 +** 2D polygon object specification** | Field name | Type | Description | Value | | --- | --- | --- | --: | @@ -306,7 +331,6 @@ Sphere is described by coordinates of central point and radius. | **params.points** | [list<xyz>](#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 @@ -316,7 +340,7 @@ Sphere is described by coordinates of central point and radius. | **y** | string | Y coordinate | 0 | | **z** | string | Z coordinate | 0 | -#### Standard conventions +**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;