NFT Metadata and Immutable X

This first lesson is an introduction to NFT metadata and how it applies to ImmutableX.

Let's start with the basic question. What is NFTs metadata? Well, metadata in this case is additional information that you can add to your digital asset.

And this might include things like the title of the NFT, a description of it, the name of the creator, URLs to media files,

maybe some metadata about those media files like the file types and also any other arbitrary properties that you want to add to describe that digital asset.

This metadata can then be used by games and apps to store, retrieve and display information about that digital asset.

This metadata can then be used to provide context about the asset and also to help ensure and describe its provenance and

authenticity and uniqueness. So what might this look like? Let's have a look at an example.

So we've got this NFT that we've created here on ImmutableX for Ignis Emberstone. And we can see that there is a bunch of information

here, including that title Ignis Emberstone, an image here and some properties that you can see there. This is what the metadata payload for that

NFT looks like. You can see we've defined a name, the URL to the image and then some of those other properties.

One of the interesting things to talk about, if we're going to be talking about NFT metadata, is the concept of traits. Now traits are, for example, these properties that you can see

here. In this case, Ignis has a class of mage, magic score of ten and attack score of five, a defence score of

two, for instance. Now, traits basically codify an, often unique, set of attributes and characteristics that help describe that NFT

and, within the context of the collection within which it sits, basically help to identify the uniqueness of

that NFT. Typical things that might be described in traits might be things like colors, shapes, patterns, textures, stats.

But really, the sky's the limit. As I said, traits often play a key role in uniquely identifying

and determining the value of an NFT within the context of an NFT collection. Now, if we take a look at ImmutableX, there are a few key

life cycle moments that exist in the lifecycle of the creation of an NFT and the interactions

with it that really define the metadata of that NFT. And it's worth keeping in mind that the metadata will exist on both Ethereum as a layer one and ImmutableX

as a layer two, and the mechanisms that both of those two blockchains use to determine the metadata are slightly different.

So understanding these key lifecycle moments helps us to determine how we control the metadata on both of those two blockchains. The first thing that's important is the act of creating a

collection on ImmutableX that corresponds to a NFT contract on Ethereum.

And the key bit of information that you specify at this point in time is the metadata API URL, and we'll see in a second what impact defining that actually has.

The second key life cycle moment is the moment in time when you first mint the NFT on ImmutableX from that collection.

And at this point in time you define two key properties. One of them is the token ID and the second one is the blueprint. And you would have seen these in the labs in the previous chapter.

And thirdly, when you withdraw an NFT for the first time from ImmutableX into Etherium,

you at that point in time have the token ID and Blueprint passed to the smart contract by ImmutableX

and you're able to use that information within your smart contract to determine how to set the metadata from an Ethereum perspective.

And you have a lot of flexibility about how you want to do that. So these are the key bits of information that determine the metadata approach from both layer one and layer two, metadata API, URL,

token ID and blueprint. And these are the key lifecycle moments. Create mint and withdraw where you have control over how the metadata is determined.

Let's start by looking at how immutable X determines the metadata. This is done via the ImmutableX NFT metadata URL,

and this is calculated by taking the metadata API URL that's defined against the collection and the token ID

that's defined against the NFT. And these for each individual NFT are basically combined together to create a URL that then has the definition

of the metadata for that NFT. So as an example, if we had a metadata API URL of

https://myapi.com and then a token ID of three, then ImmutableX would go to myapi.com/3

To try and retrieve the metadata for that particular NFT. And the expectation is that the metadata at that URL is an ERC-721 compatible metadata payload.

The other key thing that controls metadata is the blueprint.

The blueprint is an immutable string that's defined at mint time. When you mint the NFT on ImmutableX and it is passed to the Ethereum when withdrawing an NFT

and used in the smart contract code to create or mint the actual underlying NFT in Etherium.

This string can be used to encode metadata and allow the owner of a token in

ImmutableX to have some sort of certainty about what the attributes of their NFT are going to be on Ethereum, assuming that they can read the smart contract code and interpret

what will happen. The blueprint is a required field when minting an NFT on ImmutableX.

So you'll note in the lab that we had in the previous chapter, the blueprint was one of the fields that was specified there, and it has to have a value.

We have a suggested pattern that you could use, which is that if you set an ipfs content ID of the metadata payload for your metadata into the blueprint,

then in your smart contract code, you could actually set the token URI to the IPFS URL.

And this conforms with best practice on Ethereum with representing metadata as an immutable IPFS URL.

In terms of the ERC-721 metadata schema, this is essentially the main definition of it. The schema itself is quite simple.

It's a JSON object that has three properties at the very least as required properties: name, description and image where name is the name or title of the NFT, description

is a description, and the image is a URL pointing to the image based media asset of that NFT.

Now, whilst this is the minimum representation of ERC-721 metadata payload, you can also add other properties to it as well.

Here's a simple example of what ERC-21 metadata payload might look like. Now, the interesting thing about metadata payloads is

that different marketplaces will have different formats that they support for the definition of other properties. Then these three in particular traits.

So for instance, if we look at Opensea, Opensea's ERC-721 metadata standard includes an attribute key, which is an

array of JavaScript objects that have a trait_type attribute with the name of the trait and a description attribute with the value.

So in this case, this particular one has a base of starfish and eyes of big. This same metadata payload would look like this

for ImmutableX. So ImmutableX has a concept of including traits as standard key value pairs at the root level of

the metadata payload. Naturally, this means that the two metadata schemas aren't compatible with each other. But the good thing is, if you wanted to create one

payload that works for both Opensea and Ethereum and ImmutableX, you can actually combine the two together and have something that looks like this along with an attributes property

in ImmutableX in order to differentiate which of the properties are actually traits or not.

There's a concept of a metadata schema that can be defined per collection. This facilitates efficient storage and retrieval of data,

enhances data interoperability, allows for consistent description and categorization of data, and supports searching

and filtering of that data. And essentially, there's a number of different types of data that you can specify. So you tell ImmutableX this property is of

this type, maybe it's an Enam or text or Boolean or just great value. And then you can also indicate whether or not that particular property is

filterable or not, which then translates into some of the user experiences that you will see in ImmutableX.

The final thing to talk about is the metadata APIs that ImmutableX exposes. There's 4 APIs to talk about.

The first one is the Assets API. This is the API that allows you to retrieve the cached metadata that ImmutableX holds for an NFT.

You can do this by looking up the token address and token ID. of that asset.

Secondly, the IMintable token API provides you with the parameters that were originally passed through when a given NFT was first minted on ImmutableX,

and this includes the blueprint value. Thirdly is the metadata API.

This is the API that allows you to specify and retrieve the metadata schema on ImmutableX for

a given collection. And finally, the metadata refresh API. This is an API that lets you trigger a refresh for a

set of tokens or NFTs within a given collection. Thanks for joining me to talk about metadata as it relates to

NFTs on ImmutableX. Next, let's dive into a lab so that we can actually put this knowledge to practice.