Metadata Specification

GhostMarket NFT metadata reference.

Correctly specifying the Metadata for NFTs is a vital part of a NFT.

Definitions

• 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.

Metadata storage

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

Metadata Flow

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.

EVM JSON Metadata Example

Below is an example of the JSON formatted metadata for an EVM chain NFT. The NFT is defined with 2 attributes (color and size):

{
  "name": "Sample NFT",
  "description": "NFT showing example of Ghostmarket Metadata.",
  "image": "ipfs://QmZ17AYCByTQhVhrtgdV7sectZ8v6LfvL4iAY1K8QPbYXK",
  "attributes": [
    { "trait_type": "color", "value": "red",
    { "trait_type": "size", "value": "small"
  ],
  "properties": {
    "has_locked": false,
    "type": 7
  }
}

JSON Metadata Field Description

EVM Metadata

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.

Neo N3 Metadata

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.

Phantasma Metadata

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.

NFT Attributes

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 attributes array 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

Numeric Traits

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.

Date Traits

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.

Attributes guidelines

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.

NFT Properties

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

Genres

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

Retrieve Metadata via API query

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/.