Proposal for initial best practices for ICRC7 metadata

[skilesare]

To provide a standardized approach to handling metadata for NFTs within the Internet Computer ecosystem, the ICRCX metadata standard has been designed. This standard facilitates multiple methods for specifying and verifying metadata, accommodating diverse NFT use cases and ensuring interoperability with existing standards. Below is a comprehensive description of the ICRCX metadata standard's specifications:

ICRCX Metadata Standard Specification

Metadata Retrieval Methods

The ICRCX standard supports several methods for associating metadata with NFTs. Each method caters to different storage preferences and application requirements:

1. URI-based Metadata (IcrcX:metadata:uri):

   • Description: Metadata is hosted externally and accessible via a specified URI. The URI points to a JSON file containing the metadata.
   • Structure: #Text containing the URI.

2. Embedded JSON Metadata (icrcX:metadata:json):

   • Description: Metadata is directly embedded within the NFT as a JSON string.
   • Structure: #Text containing JSON data.

3. Direct Value Metadata (icrcX:metadata:value):

   • Description: Metadata is provided directly as a map within the NFT, using the Value type to support complex structures.
   • Structure: Value type, typically a map containing key-value pairs.

4. Image Only Metadata (icrcX:metadata:image):

   • Description: Only an image URL is provided as the NFT's metadata.
   • Structure: #Text containing the image URL.
   • or `Array[#Text(url),#Text(mimetype)]

5. Canister-based Metadata (icrcX:metadata:canister):

   • Description: Metadata is fetched from a specified Internet Computer canister.
   • Structure: Array containing #Text(canisterID) and #Text(path) and an optional #Text(path) format which shuld be json or candid.
   • This type is important because IC based smart contracts can pull these resources via http_request without an http outcall.

Optional Verification via Hash

To ensure the integrity and authenticity of the metadata, especially when it is stored externally, a hash can optionally be provided:

• Metadata Hash (icrcX:metadata:hash):
  • Description: Accompanies any of the metadata retrieval methods to provide a verifiable hash of the metadata content.
  • Structure: #Blob containing the hash value.

Standard Items for icrcX:metadata:value

When using the direct value method for metadata (icrcX:metadata:value), the following standard items are recommended within the metadata map:

• icrcX:name: Text — Name of the NFT.
• icrcX:description: Text — Description of the NFT.
• icrcX:image: Text — URL or data URL pointing to an image representing the NFT.
• icrcX:preview: Text — URL or data URL pointing to a thumbnail image of the NFT.
• icrcX:experience: Text — URL or data URL pointing to a dapp for interacting with the NFT.
• icrcX:attributes: Array of Maps — Each attribute is a map containing properties like trait type, value, and display type.

JSON Format Compliance

When metadata is represented in JSON format (either embedded or via URI), it should adhere to widely accepted standards such as those established for ERC-721 or ERC-1155:

• The JSON structure should generally omit the "icrcX:" prefix used in direct value maps.
• An optional field, icrcX:metadata:format, may be used to specify the metadata standard or version being followed (e.g., "erc721", "enjin", "opensea").

Summary

This standardized approach ensures flexibility in how metadata is stored and accessed while promoting consistency in its structure and verification. It supports both on-chain and off-chain storage strategies, caters to different levels of complexity in metadata content, and facilitates interoperability with existing blockchain ecosystems through compliance with popular standards like ERC-721 and ERC-1155.

[skilesare]

Updated in response to the 20240521 Working Group meeting:

To provide a standardized approach to handling metadata for NFTs within the Internet Computer ecosystem, the ICRC-76 metadata standard has been designed. This standard facilitates a bi-modal for specifying and verifying metadata, accommodating diverse NFT use cases, and ensuring interoperability with existing standards. The initial standards are purposely simple and MAY be extended through additional ICRC Extensions to target specific systems, standards, and protocols. Below is a comprehensive description of the ICRC-76 metadata standard's specifications:

ICRC-76 Metadata Standard Specification

Metadata Retrieval Methods

The ICRCX standard supports two methods for associating metadata with NFTs. Each method caters to different storage preferences and application requirements:

1. URI-based Metadata (IcrcX:metadata:uri):

   • Description: Metadata is hosted externally and accessible via a specified URI. The URI points to either a JSON file containing the metadata or, alternately, a data URI as specified in RFC 2397.
   • Structure:
     • #Text containing the URI.
   • Limits: Response from the Internet Computer are currently limited to 2MB in size. Any data of significant files may need to be held off-chain or at an IC-URI(described later).
   • Examples
     • Text Data: #Text(data:text/plain,Hello%20World)
     • IPFS: #Text(ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi/dir/file.json)
     • JSON Data: #Text("data:application/json,{'name':'example','value':'data'}")
     • Image Data: #Text("data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA...")
     • IC-URI: #Text(icdata://2222s-4iaaa-aaaaf-ax2uq-cai/item/64/data.json) - An IC canister can retrieve this data in a trusted manner using http_request without having to resort to http-outcalls.
     • URL: #Text("https://foo.com/id/64/data.json") - When a URL is encountered, the metadata should be loaded from this URL.

2. Direct Value Metadata (icrcX:metadata:value):

   • Description: Metadata is provided directly as a map within the NFT, using the Value type to support complex structures.
   • Structure: Value type, typically a map containing key-value pairs.
   • Off-chain nodes: Text values that correspond to an internet addressable URI, IC-URI, or IPFS locations should be followed to retrieve additional metadata.

//todo: Some outstanding questions on what to do about data in metadata that is Text, a URI, but NOT supposed to be traversed and included in the metadata. (Choice one is to have a specific tag in a map for this type of data ie icrc76:no_follow or two to have a tag for followable links ie icrc76:metadata:follow).

IC-URI specification

Locations that hold data on the IC that are both addressable from the IC and from https can use the IC-URI specification as follows:

ic-http://{canister_id}/{path}?[__icrc76hash={hash}&__icrc76mime={mimetype} where

• The query string parameter __icrc76hash is optional but should match the hash of the retrieved file if present.
• The query string parameter __icrc76mime is optional and should have no effect but to tell the retrieving program how to treat the data.
• The data should be accessible via an IC HTTP gateway and via a call the the indicated canister's http_request method.

Optional Verification via Hash

To ensure the integrity and authenticity of the metadata, especially when it is stored externally, a hash can optionally be provided:

• Metadata Hash (icrcX:metadata:hash):

  • Description: Accompanies any data URL that needs that does not support a query string parameter of __icrc76hash.
  • Structure: #Blob containing the sha256 hash value.

• Query String Paramater (__icrc76hash):

  • Description: Appended to URLs that can be retrieved. Tells the server the expected has so that it can be matched server side if desired.
  • Structure: `?__icrc76hash={sha256 hash} in hex representation

Standard Items for icrcX:metadata:value and/or JSON structure.

ICRC-76 does not specifically specify these structures but encourages the extension of ICRC-76 via other ICRC proposals that will allow for standardization of data useful for parsing and interoperating with other systems.

Examples:

• A standard that matches the OpenSea Standard for NFTs.
• A standard that matches the Enjin Standard for NFTs.
• A custom standard that extends basic NFT standards with features usually only available to the Internet Computer Blockchain.

Summary

This standardized approach ensures flexibility in how metadata is stored and accessed while promoting consistency in its structure and verification. It supports both on-chain and off-chain storage strategies, caters to different levels of complexity in metadata content, and facilitates interoperability with existing blockchain ecosystems through compliance with popular standards like ERC-721 and ERC-1155.

[dietersommer]

This is already in a great shape, please find some comments in the forum to further improve it.

[sea-snake]

External metadata

ICRC-3 extension that defines a value that is a record that points to external json metadata:

Map {
   icrc123_url: Text; // Path to external json
   hash?: '8o3vfuaowrgva' // Optional SHA-256 hash of external json UTF-8 string
   path?: 'a.c.[2].d' // Optional path to json value within above json
}

Standardized urls for http assets on the IC

The following url format:

ic-http://{canister_id}/{path}

Details like mime etc are not included since main purpose is to have urls that point to IC http urls without relying on a gateway in the url.