Metadata Specification
GhostMarket NFT metadata reference.
Last updated
GhostMarket NFT metadata reference.
Last updated
Correctly specifying the Metadata for NFTs is a vital part of a NFT.
EVM: Throughout this section, EVM refers to platforms which support an Ethereum Virtual Machine smart contract environment (e.g. Ethereum, BSC, Polygon, Avalanche, Ethereum, etc)
Locked content: Content which is encrypted within the NFT and only accessible by the NFT owner.
On-Chain storage: The metadata associated with the NFT creation is stored within the smart contract on the blockchain. For EVM blockchains, this storage is expensive. For Phantasma, which is designed to store data, the cost is negligible, also very low for Neo N3.
Off-Chain storage: The metadata is not stored on the blockchain. The On-Chain NFT data contains a link to the Off-Chain metadata. Off-Chain storage may be located on any internet reachable URL, however it is preferred to use decentralized data stores, such as IPFS.
GhostMarket supports both On-Chain and Off-Chain storage of NFT metadata, however NFTs created directly on GhostMarket platform stores metadata, based on the chain they are created on, as follows:
| Blockchain | Metadata Storage |
|---|---|
EVM | Off-Chain |
Neo N3 | On-Chain |
Phantasma | On-Chain |
The media files (images, videos, soundtracks etc) are ALWAYS stored Off-Chain, preferably to an immutable data store such as IPFS
Following is workflow for retrieving the Image data, starting from the contract TokenURI.
GhostMarket metadata API handles the variance between blockchains and returns a standard JSON object, simplifying dApp implementations. For the full specification of the metadata API, see the API reference.
Below is an example of the JSON formatted metadata for an EVM chain NFT. The NFT is defined with 2 attributes (color and size):
| Field | Required by | Type | Description |
|---|---|---|---|
name | ERC721, ERC1155 | string | The title of the NFT |
description | No | string | Long description of the NFT |
image | GM | string | URL of the image file |
tokenURI | No | string | If unused, supply an empty string "" |
attributes | No* | array of attributes | Features which define the NFT - see Attributes table below. * If no attributes are specified, an empty array [] must be provided. |
properties | GM | object | An object containing GhostMarket specific NFT Properties - See Properties table below) |
For full specification of EVM NFTs, see the ERC-721 and ERC-1155 token standards.
GhostMarket stores all Neo N3 NFT metadata in JSON encoded form On-Chain. The NFT contract links directly to the URL of the media via the image property, passed to the contract when the token is minted.
| Field | Required by | Type | Description |
|---|---|---|---|
name | NEP-11 | string | The title of the NFT |
description | GM | string | Long description of the NFT |
image | GM | string | URL of the image file |
tokenURI | GM | string | Use an empty string "" |
attributes | No* | array of attributes | Features which define the NFT- see Attributes table below. * If no attributes are specified, an empty array [] must be provided. |
properties | GM | object | An object containing GhostMarket specific NFT Properties - See Properties table below) |
The metadata is retrieved from the Neo N3 contract using the contract's properties method, returning a serialized JSON string of all the NFT metadata.
For full specification of Neo N3 NFTs, see the NEP-11 specification.
GhostMarket stores all Phantasma NFT metadata On-Chain when the NFT is minted. The Phantasma NFT contract provides methods for accessing the Metadata via the getNFT RPC call. The returned metadata is encoded into the "ROM" field's value. Alternatively, you can use the GhostMarket metadata API endpoint to retrieve the metadata in standard format.
The Minting Data is sent as a parameter of the mintToken method of the "ghost" contract as an array object. Please see the Phantasma Developers Guide for step-by-step details for interacting with the contract.
The following table specifies the contents of the elements of the array.
| index | name | type | descr |
|---|---|---|---|
0 | editionId | number | 0 for new series // != 0 for existing series |
1 | editionMax | number | Maximum number possible |
2 | editionMode | number | 1 = duplicated, 2 = unique // only allow duplicate for now |
3 | creator | address | Address of the creator |
4 | royalties | number | Royalties in BPS (0.01%) - must be integer |
5 | mintTicker | string | |
6 | numOfNfts | number | number to mint |
7 | name | string | Short name of the NFT |
8 | description | string | long descriptive name of the NFT |
9 | type | number/integer | Genre of the NFT - see Genre reference |
10 | imageURL | string | URL of the image - ipfs://<hash> |
11 | infoURL | string | Currently unused |
12 | attrT1 | string | First attribute Type/Key, e.g. "color" |
13 | attrV1 | string | First attribute Value, e.g. "red" |
14 | attrT2 | string | Second attribute Type/Key |
15 | attrV2 | string | Second attribute Value |
16 | attrT3 | string | Third attribute Type/Key |
17 | attrV3 | string | Third attribute Value |
18 | lockedContent | string | String containing the encrypted content |
19 | listPrice | number | If listing with Mint, the listing price |
20 | listPriceCurrency | string | If listing with Mint, the listing currency, e.g. "KCAL" |
21 | listLastEndDate | timestamp | If listing with Mint, the Unix Epoch end time of listing |
22 | infusedAsset | string | If infusing, the asset being infused e.g. "KCAL", otherwise "" |
23 | infusedAmount | number | If infusing , the amount of infusedAsset to infuse, otherwise 0 |
24 | hasLocked | bool | True if lockedContent is specified, otherwise false |
The Phantasma NFT interface is not yet a published standard, however the Phantasma Blockchain Github defines the metadata specification for PEPE-12 tokens here.
The NFT contract provides methods for accessing the Metadata via the getNFT RPC call. The returned metadata is encoded into the "ROM" field's value.
Alternatively, you can use the GhostMarket metadata API endpoint to retrieve the metadata in standard format.
The Metadata attributes property specify creator defined custom attributes of the NFT. e.g. Color, Style, Background etc.
| Field | Required | Type | Description |
|---|---|---|---|
trait_type | No | string | A string containing an attribute name for the NFT |
value | Yes | string or number | The value of the attribute |
display_type | No | string | Defines the display format of the attribute. |
max_value | No | number | Defines the ceiling for a numerical trait's possible values. |
The GhostMarket platform UI allows users to specify and set 3 attributes, however the number of attributes configurable in the
attributesarray is unlimited.
trait_type is the name of the trait
value is the value of the trait, can be either string or number type, and is the only mandatory field
display_type is a field indicating how you would like it to be displayed. For string traits, you don't have to worry about display_type.
max_value is used for number type value and is used to define and show a max, optionally
For numeric traits, GhostMarket currently supports three different options:
number
boost_percentage
boost_number (similar to boost_percentage but doesn't show a percent sign).
Note: If you pass in a value that's a number and you don't set a display_type, the trait will appear in the Rankings section.
Adding an optional max_value sets a ceiling for a numerical trait's possible values.
GhostMarket also supports a date display_type. Traits of this type will appear in a dedicated section. Pass in a unix timestamp as the value.
If you don't want to have a trait_type for a particular trait, you can include just a value in the trait and it will be set as a generic property. For example,
You should include string attributes as strings (remember the quotes), and numeric properties as either floats or integers so that GhostMarket can display them appropriately. String properties should be human-readable strings.
The NFT Properties object contains Ghostmarket specific fields, which mirror the corresponding blockchain data. It is duplicated in the metadata to reduce the number of queries of the blockchain.
| Field | Required | Type | Description |
|---|---|---|---|
has_locked | No | boolean | True if the NFT content is locked and requires the owners signature to unlock. |
type | Yes | integer | ID of the GhostMarket specific genre of the NFT - see the Genre table below - Used for filtering |
The genre type specifies the content genre of the NFTs
| type | Genre Description |
|---|---|
1 | Generic |
2 | Art |
3 | Music |
4 | Game |
5 | NSFW |
6 | Book |
7 | Photography |
8 | Apparel |
Ghostmarket provides a metadata API end-point to directly return the NFT metadata for all chains in a standard form:
https://api.ghostmarket.io/api/v2/metadata?chain=<chain>&contract=<contract address>&tokenId=<tokenId>
| Parameters | Required | Type | Description |
|---|---|---|---|
chain | Yes | string | The chain short name e.g. ETH, BSC, NEO, PHA |
contract address | Yes | string | NFT contract Hash / Address |
id | Yes | integer | Token identifier e.g. 1 |
You can find full documentation on the Ghostmarket API here
GhostMarket supports the storage of NFT metadata on decentralized file networks such as IPFS. By storing metadata and images on IPFS, NFT owners can be assured that the data and image are immutable and permanent once minted. If you use IPFS to host your metadata, your URL should be in the format ipfs://<hash>.
For example, ipfs://QmTy8w65yBXgyfG2ZBg5TrfB2hPjrDQH3RCQFJGkARStJb.
We recommend Piñata for easily interacting with IPFS, which enables you to easily create and store data.
Here's a "Getting Started" tutorial by Chainlink: https://blog.chain.link/build-deploy-and-sell-your-own-dynamic-nft/.
