Metadata Attributes

The foundational smart contract standards that define the structure for NFT metadata. ERC-721 (Non-Fungible Token Standard) mandates a tokenURI function that returns a URI pointing to a JSON file containing the token's metadata. ERC-1155 (Multi Token Standard) uses a similar uri() function, allowing a single contract to manage multiple token types, each with its own metadata set. These standards ensure wallets and marketplaces can reliably fetch and display asset information.

The standardized JSON schema for NFT metadata, as defined by community conventions and platforms like OpenSea. Essential attributes include:

• name: The title of the asset.
• description: A human-readable description.
• image: A URI pointing to the asset's primary visual representation.
• attributes: An array of trait objects (e.g., {"trait_type": "Background", "value": "Blue"}) used for filtering and rarity.
• external_url: A link to a permanent web page for the asset.

A critical architectural decision for metadata. Off-chain storage (e.g., IPFS, Arweave) stores the JSON file and media assets on decentralized networks, referenced by a URI in the smart contract. This is cost-effective but creates a dependency on the persistence of that external data. On-chain storage encodes metadata directly into the contract's storage or calldata (e.g., using SVG or Base64), guaranteeing permanence and atomicity with the token itself, at a higher gas cost.

Metadata that can change post-mint based on on-chain conditions or external inputs. This is enabled by:

• Centralized API tokenURI: The smart contract's tokenURI function returns a URL to a server that generates metadata dynamically.
• On-chain Logic: The contract itself computes or updates metadata attributes based on state changes (e.g., a game character's level).
• Chainlink Oracles: External data feeds (like weather or sports scores) can be written to the contract to update traits, enabling reactive NFTs.

Extensions to the base metadata schema that enable advanced functionality across the ecosystem.

• ERC-4906: A standard for emitting metadata update events, allowing frontends to automatically refresh when an NFT's visual or trait data changes.
• ERC-7496: Defines a standard interface for NFTs with dynamic traits, providing a clear structure for on-chain and off-chain systems to read and write trait data.
• OpenSea Collection & Attribute Standards: De-facto marketplace conventions for defining collection-level metadata (banner, fees) and attribute display types (boost, date).

Mechanisms to ensure the authenticity and integrity of metadata. IPFS Content Identifiers (CIDs) provide cryptographic hashes of the metadata file, guaranteeing immutability—if the file changes, the CID changes, breaking the link from the token. Platforms and wallets verify that the fetched metadata matches the expected hash. For on-chain art (e.g., Art Blocks), the generative script and seed are stored on-chain, making the metadata and output verifiably deterministic from the transaction that minted it.

The location of metadata is a fundamental security decision. On-chain metadata is stored directly in the smart contract or transaction data, guaranteeing immutability and permanence as part of the blockchain's state. Off-chain metadata (e.g., stored on IPFS or a centralized server) is referenced by a URI. While flexible and cost-effective, it introduces dependency risks—if the hosting service fails or the link changes, the asset's properties can be lost or altered.

A core promise of blockchain is immutable records. For metadata, this means attributes should be tamper-proof once committed. Considerations include:

• Smart Contract Upgradability: Can the contract owner change the metadata logic or base URI after minting?
• Centralized URI Risks: A mutable HTTP URL gives the issuer control to change the underlying data, breaking the link to the immutable token.
• Data Hashing: Using cryptographic hashes (like IPFS Content Identifiers - CIDs) ensures the referenced data is exactly what was originally published.

Provenance is the complete, verifiable record of an asset's origin and history. For metadata, this involves:

• Immutable Recording: The initial metadata hash should be recorded on-chain at mint time.
• Avoiding Post-Mint Changes: Any alteration to the visual or trait data after reveal can break provenance and devalue the asset.
• Transparency: The entire metadata history should be publicly auditable on-chain to prevent fraudulent substitutions (e.g., swapping a rare image for a common one after a sale).

The smart contract managing metadata can be an attack surface.

• Reentrancy Attacks: Malicious contracts could intercept calls to fetch metadata.
• URI Manipulation: If the tokenURI() function logic is flawed, it could return incorrect data.
• Owner Privileges: Excessive centralized control (e.g., an owner role that can change all token URIs) is a critical risk. Best practice is to renounce ownership or lock metadata post-reveal.

Blockchain permanence is meaningless if the metadata disappears. This is a digital preservation challenge.

• Link Rot: HTTP URLs will almost certainly fail over decades.
• Protocol Obsolescence: Will IPFS, Arweave, or today's storage protocols be supported in 20 years?
• Solutions involve redundancy: Storing metadata on multiple decentralized networks and ensuring the resolution logic (the tokenURI function) is simple and durable enough to be interpretable far into the future.

Some NFTs use dynamic metadata where attributes change based on external conditions or on-chain logic.

• Art Blocks Curated: Generative art projects where the tokenURI and image are derived from a seed stored on-chain.
• GameFi Assets: In games like Axie Infinity, an NFT's attributes (stats, level) can be updated by the game's smart contract based on gameplay outcomes, reflecting the asset's evolving state.

Metadata attributes are not just for NFTs; they describe financial instruments in DeFi.

• ERC-20 Tokens: Include basic attributes like name, symbol, and decimals in the contract.
• LP Position NFTs: Protocols like Uniswap V3 mint NFTs representing liquidity positions, with metadata encoding critical parameters like the fee tier, tick range, and token pair.
• Vesting Schedules: Tokens can have metadata defining lock-up periods and release schedules.

Metadata attributes form the basis for Soulbound Tokens (SBTs) and verifiable credentials, encoding claims about an identity.

• Proof-of-Attendance Protocol (POAP): Each badge is an NFT with metadata specifying the event name, date, and location, serving as a verifiable record of participation.
• Decentralized Identifiers (DIDs): Attributes can represent credentials (e.g., university degree, KYC status) that are cryptographically verifiable without a central issuer.

Formal specifications that define the structure and location of metadata for tokens. ERC-721 and ERC-1155 for NFTs include standard metadata JSON schemas, while ERC-20 tokens often use separate registries. These standards ensure interoperability between wallets, marketplaces, and explorers by providing a predictable format for attributes like name, image, and traits.

A key distinction in how attribute data is stored.

• On-Chain: Data is stored directly in contract storage or calldata, providing immutability and self-containment at the cost of higher gas fees. Used for critical, immutable traits.
• Off-Chain: Data is stored on decentralized (e.g., IPFS, Arweave) or centralized servers, referenced by a URI in the contract. This is cost-effective for large files like images but introduces a dependency on the URI's availability.

A specific, discrete property within a metadata attribute set. In an NFT collection, traits are the individual characteristics that make each token unique, such as Background: Space, Fur: Blue, or Accessory: Sword. Traits are the fundamental building blocks that are aggregated and scored by rarity algorithms to determine an item's overall rarity rank and market value.

A numerical value derived from the statistical frequency of an item's metadata attributes and traits. It quantifies scarcity within a collection. Common calculation methods include:

• Trait Rarity: 1 / (Trait Frequency)
• Statistical Rarity: The product of the probabilities of all traits.
• Rarity Ranking: The ordinal rank of an item's total score within the collection. This score is a primary market driver.

A service that provides external, real-world data to a blockchain. While not storing static metadata, oracles are crucial for dynamic metadata attributes that change based on off-chain events. For example, an NFT's power_level attribute could be updated by an oracle feed based on sports statistics or weather data, enabling reactive and programmable digital assets.

A non-transferable token that represents credentials, affiliations, or reputation. Its metadata attributes act as a verifiable, on-chain resume. Attributes might include degree_earned, protocol_contributor, or governance_voting_power. SBTs emphasize persistent, identity-linked metadata that cannot be sold, creating a new paradigm for attribute-based reputation systems.