Efficient metadata design, storage, and retrieval
- On-chain vs off-chain metadata
- Examples of attributes to store on-chain and off-chain
Introduction
Metadata is the heart of your game. It’s where you define how rare an asset is, what that asset looks like, and most importantly, how that asset behaves in your game. The most important distinction in designing your metadata is deciding which fields will be on-chain and which fields will be off-chain.
On-chain vs off-chain metadata
On-chain metadata is stored directly on the blockchain, which is more tamper-proof and transparent. However, this also means that updates will cost gas and have non-instant finality.
Off-chain metadata, on the other hand, is stored in a standard database server instead of the blockchain. This makes the data easier to update as has no gas cost and instant finality, but also makes it not tamper-proof and less transparent.
| On-chain | Off-chain | |
|---|---|---|
| Tamper-proof | Yes | No |
| Transparent | Yes | Permissioned (dev must expose database publicly) |
| Update cost | Gas fee | None |
| Update speed | Slow (requires consensus) | Instant |
We recommend minimizing the amount of metadata stored on-chain to keep gas costs lower. On-chain metadata should be updated infrequently (or never). Metadata that need to be frequently updated should be kept off-chain
Examples
Good on-chain metadata attributes:
- Asset ID (Theoretically will never get updated)
- Rarity (Should change very infrequently)
Good off-chain metadata attributes:
- Asset Name and Description (Can be very long, not necessary to have strong security properties)
- Image URL (Often changed as assets are upgraded or modified)
- Equipment or gear (Often changed based on user interaction)
- Combat attributes(Often changed as characters equip new gear or level up)
- Interactive attributes (Often changed based on user interaction)
Metadata Retrieval
Immutable provides the Blockchain Data API to query NFT metadata and NFT Collection metadata.
Note that on-chain metadata is not indexed by our indexer. In order to search on-chain metadata, please duplicate those attributes in your off-chain metadata set.
Technical documentation
Please see Metadata technical documentation for technical details on how to implement your game’s metadata.