Metadata refresh

This guide explains how to trigger a metadata refresh once an existing NFT is updated

Sections

What is a metadata refresh call?
What is a metadata_id?
How to trigger a metadata refresh?
- Refresh the metadata of a specific or list of NFTs via token_id
- Refresh the metadata for a stack of NFTs via metadata_id
Metadata refresh limits
How do I know if my NFTs metadata has been updated?

What is a metadata refresh call?

Upon the initial minting of an NFT, the metadata associated with it is automatically indexed by the Blockchain Data API. However, gaming assets are inherently dynamic, subject to attribute changes driven by player actions such as crafting or in-game performance enhancements. These updates significantly contribute to the evolving in-game experience. Nevertheless, these alterations do not automatically propagate across Immutable's gaming ecosystem, leading to a lack of awareness among marketplaces, aggregators, and other third-party entities interconnected with the platform.

This unawareness has the potential to impact the perceived value of these assets. To address this, the metadata refresh service has been developed, primarily catering to game studios. Its core purpose is to serve as a means for these studios to inform the community of asset evolution, thereby enhancing transparency within the ecosystem. This, in turn, benefits players, as they gain the opportunity to be duly rewarded for any improvements made to their assets should they choose to list them on marketplaces.

What is a `metadata_id`?

All minted assets are assigned two key identifiers: a token_id and a metadata_id, both of which are accessible through the nft endpoint.

The token_id serves as a unique identifier for each asset within a specific collection. It distinguishes one asset from another within that collection. token_id can be game studio specified if mint() or batchMint() functions are used from Immutable's preset contract.
The metadata_id, on the other hand, uniquely identifies the metadata associated with one or more assets within the same collection. metadata_id are auto generated by Immutable.

Notably, NFTs that share identical metadata characteristics, often referred to as stacked assets, will all be linked to the same metadata_id, a process automatically managed by Immutable's Blockchain Data API.

For instance, consider two cards represented as NFTs, both possessing exactly the same features. Each of these cards would have its own distinct token_id, allowing them to be individually recognized within the collection. However, they would share the same metadata_id since their metadata attributes are identical.

Now, let's say one of these cards undergoes an upgrade through a crafting action. As a result, it would be assigned a new metadata_id, which can be accessed via the nft endpoint. Meanwhile, the other card would retain its original metadata_id. If the upgraded card is the only asset within the collection that possesses these unique metadata attributes, it will receive a new metadata_id. However, if there are other NFTs within the collection that share the same metadata attributes, the upgraded card will be assigned an existing metadata_id associated with these similar NFTs.

The below table demonstrates how metadata_id changes in different metadata update scenarios:

Situation	Metadata Change	Metadata Refresh By	Asset After Refresh	Metadata ID
1 asset with unique metadata	Update metadata	`token_id`	Unique metadata	New `metadata_id`
1 asset with unique metadata	Update metadata	`token_id`	Asset has metadata equal to a stack of assets assigned with `metadata_id`=X	Refreshed asset assigned `metadata_id`=X
1 asset with unique metadata	Update metadata	`metadata_id`	Unique metadata	No change to `metadata_id`
1 asset with unique metadata	Update metadata	`metadata_id`	Asset has metadata equal to a stack of assets assigned with `metadata_id`=X	Error generated. Cannot have 2 `metadata_ids` representing identical stacked assets
100 assets sharing metadata	Change 1 asset's metadata	`token_id`	Unique metadata	New `metadata_id`
100 assets sharing metadata	Change 1 asset's metadata	`token_id`	Asset has metadata equal to a stack of assets assigned with `metadata_id`=X	Refreshed asset assigned `metadata_id`=X
100 assets sharing metadata	Change 100 assets' metadata	`metadata_id`	Unique metadata for stack	No change to `metadata_id`
100 assets sharing metadata	Change 100 assets' metadata	`metadata_id`	Assets has metadata equal to a stack of assets assigned with `metadata_id`=X	Error generated. Cannot have 2 `metadata_ids` representing identical stacked assets

Once a metadata_id has been created it will persist even if there are no assets that currently have that metadata_id. If an asset is assigned metadata represented by a legacy metadata_id, it will be assigned the legacy metadata_id.

See the following example to illustrate this point:

An unique asset has the following metadata: Animal=Dragon, Colour=Green, Strength=10 -> assigned metadata_id=A1
This asset has its metadata updated to the following: Animal=Dragon, Colour=Red, Strength=10 -> assigned metadata_id=A2, no assets currently have metadata_id=A1
This asset has its metadata updated back to its original configuration: Animal=Dragon, Colour=Green, Strength=10 -> reassigned metadata_id=A1

노트

Immutable's system monitors the metadata for each asset in a collection and auto-identifies which assets have the same metadata; assigning those assets the same metadata_id.

Game studios do not set metadata_id themselves, they are generated by Immutable and can be identified through the nft endpoint.

How to trigger a metadata refresh?

To update the Blockchain Data API with the changes made to an existing asset the following steps should be followed.

When updating metadata, please remember to post the entire assets metadata when performing a refresh, not just the changed attributes. Submitting only the amended attributes will remove the metadata value you do not submit.

팁

If you have deployed your collection manually (i.e. not used Immutable's Hub to deploy a preset contract), you must link the collection to your Immutable Hub account.

The following tutorial will guide you through this process.

Refresh the metadata of a specific or list of NFTs via token_id

When initiating a metadata refresh request by referencing a specific or array of token_id, you will reindex the metadata of the specified tokens.

10 token_id can be present in a single metadata refresh batch update.

Here's an example of how you can execute this process:

Request parameters

Parameter	Description	Required
`chainName`	String representing the name of the chain. Testnet: `imtbl-zkevm-testnet` Mainnet: `imtbl-zkevm-mainnet`	Yes
`contractAddress`	The contract address of the ERC721 collection	Yes
`newName`	The new name of the NFT you are assigning	Yes
`apiKey`	Secret key to your environment. Follow this guide to set yours up	Yes
`publishableKey`	Public key to your environment. Follow this guide to set yours up	Yes

Use the following parameters in your function if you want to update the "name" property of a particular NFT:

import { config, blockchainData } from '@imtbl/sdk';

const API_KEY = 'YOUR_SECRET_API_KEY';
const PUBLISHABLE_KEY = 'YOUR_PUBLISHABLE_KEY';

const client = new blockchainData.BlockchainData({
  baseConfig: {
    environment: config.Environment.PRODUCTION,
    apiKey: API_KEY,
    publishableKey: PUBLISHABLE_KEY,
  },
});

const refreshNFTMetadata = async (
  client: blockchainData.BlockchainData,
  chainName: string,
  contractAddress: string,
  newName: string
) => {
  const nftMetadata: blockchainData.Types.RefreshMetadataByTokenID[] = [
    {
      name: newName,
      animation_url: null,
      image: null,
      external_url: null,
      youtube_url: null,
      description: null,
      attributes: [
        {
          trait_type: 'Power',
          value: 'Happy',
        },
      ],
      token_id: '1',
    },
  ];

  const updatedNFT = await client.refreshNFTMetadata({
    chainName,
    contractAddress,
    refreshNFTMetadataByTokenIDRequest: {
      nft_metadata: nftMetadata,
    },
  });
};

The result will return the rate limit details informing how many refreshes are available for a period of time

Using Immutable's API you can refresh the metadata of a list of NFTs with the following RefreshNFTMetadataByTokenID API call; which will produce a result in the below format.

📚API reference

RefreshNFTMetadataByTokenID

POST /chains/{chain_name}/collections/{contract_address}/nfts/refresh-metadata

Example response

{
  "imx_refreshes_limit": "10000",
  "imx_refresh_limit_reset": "2023-01-02 15:04:05",
  "imx_remaining_refreshes": "9000",
  "retry_after": "2-seconds"
}

💡Where is NFT metadata hosted?

When an asset is minted, its metadata is cached by Immutable's blockchain data indexer, making it accessible via the the Blockchain Data APIs.

When an NFT's metadata is updated, requesting a "metadata refresh" updates the cached information to ensure that changes are available via the API.

After this operation, the nft endpoint will accurately represent the updated metadata for all NFTs affected by this change. Additionally, the metadata refresh endpoint will reflect the new metadata attributes associated with the modified metadata_id.

Refresh the metadata for a stack of NFTs via metadata_id

주의

Updating metadata by metadata_id is not widely supported by Immutable's ecosystem partners, including marketplaces.

Immutable is enhancing this product to improve accessibility. Please check back on this page for updates.

When initiating a metadata refresh request by referencing a specific metadata_id, you will reindex all NFTs within the associated collection. This process can apply to a single asset or an entire stack of assets, making it the most efficient way to update the Blockchain Data API indexer when a group of NFTs undergo attribute changes.

10 metadata_id can be present in a single metadata refresh batch update.

Here's an example of how you can execute this process:

Use the following parameters in your function if you want to update the stacked metadata identified by `metadataID`:

import { blockchainData } from '@imtbl/sdk';

const refreshStackedMetadata = async (
  client: blockchainData.BlockchainData,
  chainName: string,
  contractAddress: string,
  newName: string
) => {
  const updatedMetadata = await client.refreshStackedMetadata({
    chainName,
    contractAddress,
    refreshMetadataByIDRequest: {
      metadata: [
        {
          name: newName,
          animation_url: null,
          image: null,
          external_url: null,
          youtube_url: null,
          description: null,
          attributes: [],
          metadata_id: '1',
        },
      ],
    },
  });
};

The result will return the rate limit details informing how many refreshes are available for a period of time

Using Immutable's API you can refresh a stacked metadata identified by its `metadataID` with the following RefreshMetadataByID API call; which will produce a result in the below format.

📚API reference

RefreshMetadataByID

POST /chains/{chain_name}/collections/{contract_address}/metadata/refresh-metadata