Skip to main content

Metadata

On this page, we dive into the intricacies of how NFT metadata can be managed on Immutable.

We cover topics like royalties, the significance of metadata, defining off-chain metadata in ERC721 contracts, serving metadata, updating the indexer for new and existing assets (NFTs & collections), and verifying the accuracy of indexed metadata.

Sections

Metadata allows us to define characteristics of NFT collections and individual NFTs. On Immutable, this information can be queried via our Blockchain Data APIs in a standardized format.

What is metadata?​

Metadata are the characteristics attributed to an NFT or NFT collection. It provides additional information not essential for blockchain operation but can play a crucial role in determining an asset's behavior within a Web3 game. Depending on the contract specification, metadata can exist in both on-chain and off-chain forms.

Metadata is pivotal in defining the context, characteristics, and aesthetics of NFTs or contracts. It empowers potential buyers to assess value, authenticity, and uniqueness, while also shaping game logic and driving various aspects of a user's gameplay experience.

What is the difference between off-chain and on-chain metadata?​

Metadata
blockchain minting api asset relationships

Metadata can be stored on-chain or off-chain, each with its own benefits and drawbacks.

On-chain metadata is directly stored on the blockchain. It cannot be altered unless authorized parties call specific smart contract functions. While on-chain metadata ensures the permanent and secure storage of NFT properties, updating it incurs gas fees, making it less practical for frequent changes. On-chain metadata is best suited for crucial attributes that require permanent and tamper-proof records, ensuring the NFT's uniqueness and verifiability.

Off-chain metadata, on the other hand, refers to attributes of the asset that are not stored on the blockchain itself. This approach provides game studios with greater flexibility in managing and updating information associated with assets, as it only requires off-chain database calls. Additionally, off-chain storage is typically more cost-effective, allowing games to incorporate richer and more diverse metadata, including larger file sizes, multimedia content, and interactive elements. Off-chain metadata is particularly useful for values that may undergo frequent updates or require more extensive storage space.

As a best practice, game studios are encouraged to minimize on-chain metadata for NFTs. Storing attributes off-chain allows for more frequent updates and cost-effective storage. For tasks like game rebalancing, which necessitate frequent metadata updates, storing such data on-chain can prove to be a costly endeavor for game studios. By leveraging off-chain storage for non-essential attributes, game developers can strike a balance between security and efficiency, enhancing the overall Web3 gaming experience.

💡Only off-chain metadata is indexed
Immutable's metadata search engine indexes on and off-chain metadata for collections, but it does not index on-chain metadata for NFTs. To ensure indexing of on-chain metadata for NFTs, it should be duplicated in the off-chain metadata values so it is picked up by the indexer.

How should off-chain metadata be referenced on an ERC721 contract?​

An NFT's off-chain metadata is represented on-chain by a baseURI (Uniform Resource Identifier) that points to the location of where the off-chain metadata is stored (ie. URL where the data can be accessed).

This URI is defined in a token’s smart contract, which is set during deployment and will determine the off-chain metadata root URL for all NFTs minted by that collection.

If Immutable's preset contracts are used a token's external metadata URL is defined through concatenation of the following attributes:

[baseURI]/[tokenID]

  • The baseURI is specified in a collection's smart contract at time of deployment. In standard collection implementations, all NFTs belonging to a collection will have the same baseURI.
  • The tokenID is generated during the minting process, and when appended to the baseURI will provide the unique location of an NFTs metadata.

e.g.

tip

Blockscout currently requires a '/' at the end of the baseURI to index metadata correctly. Immutable's Blockchain Data API does not require this, however for consistency we recommend adding a '/' to the end of the baseURL for Blockscout compatibility.

Token 1's metadata is located at https://peach-dear-wildfowl-698.mypinata.cloud/ipfs/QmVhfy6QYWBzwUZfDSJGvScLScaWKHEyUKBax8AmYqd4Sr/nft-metadata/1

If you are using preset ERC721 contracts; make sure you define baseURI when you are configuring the deploy.ts file prior to deploying your smart contract.

More details can be found by following our contract deployment and minting tutorial.

How should you retrieve and display off-chain metadata?​

Metadata of individual NFTs or NFT collections can be obtained via the NFTs or Collections endpoints of the Blockchain Data API.

Calling these functions will return the metadata in JSON format.

How should metadata be formatted?​

See article on metadata format.

How do you upload and host metadata for your collection?​

When managing metadata for your application, you have the flexibility to host it on various platforms, such as your game backend, AWS S3, InterPlanetary File System (IPFS), or other data hosting solutions. It's essential to choose a solution that aligns with the performance requirements of your application.

If your application involves the need for subgraphs, IPFS is specifically recommended.

To help you get started and for testing purposes, you can fork our sample metadata repository here.

What happens if I change my metadata​

When an NFT collection (smart contract) is deployed on Immutable zkEVM the indexer caches both the on- and off-chain metadata.

When an NFT is minted from a previously deployed collection the indexer caches only the off-chain metadata.

If metadata is changed post-mint, collection owners should trigger a "metadata refresh" event and submit the NFTs new metadata to the Blockchain Data API service to ensure members of Immutable's ecosystem are aware of the updates.

See our guide on metadata refresh.

danger

In the event that alterations are made to an asset's metadata, and such changes are not promptly communicated to the Blockchain Data API, it results in a lack of awareness within Immutable's blockchain community regarding the update.

To ensure that marketplaces, aggregators, and other third-party entities remain informed about these significant updates, which inherently impact the value of the associated NFT, it is imperative to initiate a metadata refresh call. This call serves as a vital mechanism for maintaining transparency and disseminating critical information throughout the ecosystem

Verifying if metadata has been indexed correctly​

Query the NFTs or Collections endpoints of the Blockchain Data API and examine the last_metadata_synced_at parameter of the response returned:

  • If this value is null, metadata has not yet been refreshed
  • If this value is not null, but no metadata is present, then there was error with the metadata refresh

Changing the metadata root location (baseURI) in a previously deployed contract​

With Immutable's preset contracts, the collection owner has the ability to modify the metadata root directory for all existing and future tokens by updating the baseURI field in the collection.

Follow the steps below to update the baseURI for a collection you have deployed:

  1. Prepare the new metadata hosting service so that individual token's metadata can be located in a URL adhering to the following format: [New baseURI]/[TokenID]. You can follow the guide here.
  2. Ensure that you have all your collections NFTs metadata files in this new baseURI root directory; with the corresponding metadata json files named by tokenID.
  3. Visit the associated collection within the Hub. If your collection is not linked to the Hub, you must do this first within the Hub.
  4. Update the Base URI field with the URL you prepared above and follow the on-screen steps.
URIs

Changing the collection metadata (contractURI) in a previously deployed contract​

With Immutable's preset contracts, the collection owner has the ability to modify the contract metadata by updating the contractURI field in the collection.

Follow the steps below to update the contractURI for a collection you have deployed:

  1. Prepare the new metadata hosting service so that there is a json file that contains populated metadata for the collection. You can follow the guide here.
  2. Visit the associated collection within the Hub. If your collection is not linked to the Hub, you must do this first within the Hub.
  3. Update the Contract URI field with the URL you prepared above and follow the on-screen steps.
URIs