Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

ICRC-97: Non-Fungible Token (NFT) Metadata Standard #98

Open
wants to merge 9 commits into
base: main
Choose a base branch
from
Open

ICRC-97: Non-Fungible Token (NFT) Metadata Standard #98

Changes from 2 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
7bee2e0
Create ICRC-97.md
sea-snake Aug 13, 2024
ba2e7d9
Update ICRC-97.md
sea-snake Aug 13, 2024
d8b9ba3
Update ICRC-97.md
sea-snake Oct 15, 2024
4aafbfe
Update ICRC-97.md
sea-snake Oct 15, 2024
f030e36
Update ICRC-97.md
sea-snake Oct 15, 2024
ac1b5f3
Update ICRC-97.md
sea-snake Oct 15, 2024
a79d8d3
Update ICRC-97.md
sea-snake Oct 15, 2024
0fabfd7
Update ICRC-97.md
sea-snake Oct 15, 2024
af41f95
Update ICRC-97.md
sea-snake Oct 15, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
95 changes: 95 additions & 0 deletions ICRCs/ICRC-97/ICRC-97.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,95 @@
| ICRC | Title | Author | Discussions | Status | Type | Category | Created |
|:----:|:------------------------------------------:|:--------------------------------------------------------------------------------:|:-----------------------------------------:|:------:|:---------------:|:--------:|:----------:|
| 97 | Non-Fungible Token (NFT) Metadata Standard | Thomas (@sea-snake), Austin Fatheree (@skilesare), Dieter Sommer (@dietersommer) | https://github.com/dfinity/ICRC/issues/97 | Draft | Standards Track | | 2024-08-13 |

# ICRC-97: Non-Fungible Token (NFT) Metadata Standard

ICRC-97 is a metadata standard for the implementation of Non-Fungible Tokens (NFTs) on
the [Internet Computer](https://internetcomputer.org).

The standard is designed to allow for multiple assets with different data types with various purposes. Where additional
asset purposes and attribute display types can be standardized in ICRC-97 extensions.

sea-snake marked this conversation as resolved.
Show resolved Hide resolved
## Extending the ICRC-7 Standard with Token Metadata
sea-snake marked this conversation as resolved.
Show resolved Hide resolved

The [`icrc7_token_metadata`](https://github.com/dfinity/ICRC/blob/main/ICRCs/ICRC-7/ICRC-7.md#icrc7_token_metadata)
method returns the token metadata for `token_ids`, a list of token ids. Each tuple in
the response vector comprises an optional `metadata` element with the metadata expressed as vector of `text` and `Value`
pairs.

ICRC-7 does not specify the representation of token metadata any further than that it is represented in a generic manner
as a vector of (text, Value)-pairs. The ICRC-97 standard extends the ICRC-7 standard with a token metadata
sea-snake marked this conversation as resolved.
Show resolved Hide resolved
standard.

### Entrypoint

The following metadata property MUST be defined in the root of the token metadata if we want to return on-chain
metadata.

| Root Metadata Property | ICRC-3 Type | Description |
|------------------------|-----------------|----------------------------------------|
| icrc97:metadata | variant { Map } | Contains on-chain metadata properties. |

Alternatively the following metadata property MUST be defined in the root of the token metadata if we want to return
external
off-chain metadata instead of on-chain metadata.

| Root Metadata Property | ICRC-3 Type | Description |
|--------------------------|-----------------|---------------------------------------------------|
| icrc97:external_metadata | variant { Map } | Contains below external JSON metadata properties. |
Comment on lines +31 to +41
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this does not prevent defining both, right?

Copy link
Contributor Author

@sea-snake sea-snake Oct 23, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The metadata ICRC-3 structure doesn't prevent any dev from not following the spec, but you're right, according to the ICRC-97 spec only of one these should be defined. I'll clarify this in the spec.


| External Metadata Property | Optional | ICRC-3 Type | Description |
|----------------------------|----------|------------------|--------------------------------------------------------------------------------|
| url | No | variant { Text } | URL that returns the metadata in JSON format (protocol is not limited to HTTP) |
| sha256_hash | Yes | variant { Blob } | SHA-256 hash of HTTP response body bytes returned from above url. |
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

in case the icrc97:external_metadata changes, the hash needs to be updated if provided. right?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes that's what I meant with SHA-256 hash of HTTP response body bytes returned from above url..

I'll clarify this further, keep in mind the hash is optional, so a dev can opt to not have it.

Overall, immutability on the IC is only truly something one could trust if the contract code is public, build are reproducible and the canister doesn't have controllers defined (or blackholed). As I mentioned earlier, some method(s) could indicate that things are immutable, but unless above is true, you can't fully trust it.


### Metadata properties

Below table list all (optional) metadata properties defined in this standard. Each property is defined in both ICRC-3
sea-snake marked this conversation as resolved.
Show resolved Hide resolved
and JSON type to support both on-chain `Value` and off-chain JSON metadata respectively.
sea-snake marked this conversation as resolved.
Show resolved Hide resolved

| Metadata Property | Optional | ICRC-3 Type | JSON Type | Description |
|-------------------|----------|-----------------------------------------|-----------|---------------------------------------------------------|
| external_url | Yes | variant { Text } | string | URL that allows the user to view the item on your site. |
| name | Yes | variant { Text } | string | Plain text. |
| description | Yes | variant { Text } | string | Markdown. |
| assets | Yes | variant { Array = vec variant { Map } } | object[] | List of assets ordered by priority descending. |
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this allows to provide multiple different assets that belong to a specific NFT, right? I am wondering how consumers would select the "default" asset, or do we expect creators to use the first asset explicitly as preview? I see that there is also the possibility to define a purpose of the asset 🤔

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

List of assets ordered by priority descending.

The order of the list of assets matters, dapps are expected to prioritize assets higher in the list.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

so as a consumer (e.g. explorer or marketplace) I would use the first occurrence of an asset with type image (or preview if existing), right? assuming that the NFT has an image attached.

if we can have more than one asset with purpose irc97:preview, I'd expect that irc97:preview differs from its corresponding irc97:image. otherwise the consumer could just resize the irc97:image to the needs.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would use the first occurrence of an asset with type image (or preview if existing), right?

Yes, I'll clarify this in the spec a bit further.

otherwise the consumer could just resize the irc97:image to the needs

I'll also clarify in the spec that irc97:image should be used if irc97:preview is missing.

| attributes | Yes | variant { Array = vec variant { Map } } | object[] | List of attributes ordered by priority descending. |
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

are the attributes expected to be immutable? otherwise we might want to distinguish between mutable and immutable attributes

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the term "immutable" is of course tricky, given the nature of canisters living on ICP.

did you generally discuss to track the history of metadata changes so far? 🤔

Copy link
Contributor Author

@sea-snake sea-snake Oct 23, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good points, there's the update schema in ICRC-7 for the purpose of tracking metadata updates. I'll mention how to make the metadata immutable, basically by not returning above block type in ICRC-3 supported block types. I'll also mention how ICRC-97 metadata updates should be encoded as blobs in the update schema in case the metadata is not immutable.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think I need to read more about ICRC-3 🤔

note: the link is not working.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

note: the link is not working.

Fixed


The following table list all (optional) asset properties.

| Asset Property | Optional | ICRC-3 Type | JSON Type | Description |
|----------------|----------|------------------|-----------------|--------------------------------------------------------------------------------|
| url | No | variant { Text } | string | URL that returns the asset e.g. a PNG image (protocol is not limited to HTTP). |
| mime | No | variant { Text } | string | Mime type as defined in RFC 6838. |
| sha256_hash | Yes | variant { Blob } | string (base64) | SHA-256 hash of HTTP response body bytes returned from above url. |
| purpose | Yes | variant { Text } | string | Indicate purpose of asset. |

Below list of purpose values are part of the ICRC-97 standard, this list could be extended by other standards.
Purpose values can define additional asset properties.

| Purpose Value | Description |
|----------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------|
| icrc97:image | Original size image that is shown on e.g. item details page. Additional optional `width` and `height` properties define the dimensions in number of pixels. |
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

can you provide an example on how this would be defined?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'll add examples to the spec

| icrc97:preview | Small image meant as preview within e.g. a list of items. Additional optional `width` and `height` properties define the dimensions in number of pixels. |

The following table list all (optional) attribute properties.
sea-snake marked this conversation as resolved.
Show resolved Hide resolved

| Attribute Property | Optional | ICRC-3 Type | JSON Type | Description |
|--------------------|----------|----------------------------|------------------|---------------------------------------------|
| value | No | variant { Text; Nat; Int } | string \| number | Value of the trait. |
| trait_type | No | variant { Text } | string | Name of the trait. |
| display_type | Yes | variant { Text } | string | Indicate how attribute should be displayed. |

Below list of display types are part of the ICRC-97 standard, this list could be extended by other standards.
Display types can define additional attribute properties.

| Display Type Value | Description |
|-------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------|
| icrc97:property | Shows attribute as property with e.g. rarity, this is the default display type. |
| icrc97:date | Shows attribute as date, expects epoch timestamp number in milliseconds. |
| icrc97:time | Shows attribute as date with time, expects epoch timestamp number in milliseconds. |
| icrc97:rank | Shows attribute as progress rank e.g. 4 of 10, expects number and additional `max_value` property with a number. |
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

can you provide an example on how 4 of 10 would be defined?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'll add examples to the spec

| icrc97:stat | Show attribute as stat e.g. 1 out of 2, expects number and additional `max_value` property with a number. |
| icrc97:boost | Shows attribute as boost e.g. +10, expects number and optional additional `min_value` and `max_value` properties. Numbers can be either positive or negative. |
| icrc97:boost_percentage | Same as `icrc97:boost` but shows values with %. |
Loading