Token Metadata

Dynamic NFTs have metadata that changes based on external conditions or on-chain events. Implementation patterns include:

• Oracle-Driven Updates: A smart contract uses a decentralized oracle (e.g., Chainlink) to fetch external data (weather, sports scores) and triggers a metadata update.
• Cross-Chain State: A bridge or messaging protocol (like LayerZero or Wormhole) can relay state from another blockchain to alter an NFT's traits.
• On-Chain Logic: The NFT's metadata URI or attributes change based on in-game actions or the passage of time, with logic executed directly by the smart contract.

While basic ERC-20 tokens have minimal fields (name, symbol, decimals), extensions provide richer metadata.

• ERC-1363 (Payable Token): Defines metadata for token callbacks, enabling more complex interactions.
• ERC-884 (Corporate Shares): Includes metadata fields for shareholder governance and compliance.
• EIP-4524 (Ethereum Name Service - ENS): Allows tokens to be identified by a human-readable ENS name (e.g., token.eth). These standards enhance discoverability and functionality for DeFi tokens, governance tokens, and real-world asset (RWA) tokens.

Wallets and explorers must verify the integrity and source of metadata. This involves:

• Hash Verification: Confirming the fetched data matches the on-chain hash (e.g., tokenURI hash).
• Source Attestation: Checking if the metadata is signed by a trusted party (developer, DAO).
• Schema Validation: Ensuring the JSON follows a standard schema (like ERC-721 Metadata) to prevent malformed data from causing application errors.

Many token contracts use a mutable baseURI or a proxy pattern to allow metadata updates. This introduces governance risk: who controls the update key? A malicious or compromised upgrade could point metadata to phishing sites or inappropriate content. Secure implementations use timelocks and multi-signature wallets controlled by a decentralized autonomous organization (DAO) for any changes.

Even with secure on-chain metadata, the presentation layer (websites, wallets) is vulnerable. Attackers can create fake interfaces that display spoofed metadata for legitimate tokens, tricking users into malicious interactions. Users must verify domain authenticity, and developers should implement strict origin policies and use EIP-712 typed data signing to provide clear transaction context.

The ERC-20 and ERC-721 standards define the foundational metadata schema for fungible and non-fungible tokens on Ethereum and EVM-compatible chains.

• ERC-20: Includes name, symbol, decimals, and totalSupply.
• ERC-721: Extends this with tokenURI, which points to a JSON file containing the NFT's name, description, image, and custom attributes.

These standards ensure wallets like MetaMask can correctly display token balances and NFTs.

Some NFTs use dynamic metadata, where the tokenURI points to an API or smart contract that can return updated metadata based on on-chain conditions.

• Example: An NFT representing a character in a game might update its image and attributes (e.g., level, strength) as the player progresses.
• This is often implemented via the ERC-1155 standard or by having the tokenURI function execute logic before returning a metadata URL.

For an NFT (like a Bored Ape), the tokenURI function returns a pointer (often an IPFS hash like ipfs://Qmb...) to a JSON file. That file contains the core metadata:

jsonCopy
{
  "name": "Bored Ape Yacht Club #1234",
  "description": "Ape 1234 from the BAYC collection.",
  "image": "ipfs://Qmb.../ape1234.png",
  "attributes": [
    { "trait_type": "Background", "value": "Blue" },
    { "trait_type": "Fur", "value": "Golden Brown" }
  ]
}

This structure is parsed by marketplaces like OpenSea to render the NFT's page.

Bridged or wrapped assets (e.g., Wrapped BTC on Ethereum) must maintain consistent metadata across chains to avoid user confusion.

• The metadata (name, symbol, decimals) for WBTC is intentionally kept identical to Bitcoin's familiar BTC.
• This consistency is crucial for DeFi protocols and aggregators that need to recognize the asset as "Bitcoin" regardless of the underlying chain, relying on the standardized symbol and decimals.

When you add a custom token to a wallet, you provide its contract address. The wallet then fetches the metadata (name, symbol, decimals) directly from the token's smart contract.

• If the decimals value is incorrect (e.g., reporting 18 for a token that actually has 6), your wallet balance will be displayed with 12 extra zeros.
• This demonstrates how critical accurate, on-chain metadata is for basic financial readability.

The uniform resource identifier stored on-chain that points to a token's metadata JSON file. This is the critical link between the blockchain and the descriptive data.

• On-Chain Reference: A string value (e.g., ipfs://Qm... or https://api.example.com/token/1) stored in the token's smart contract.
• Resolution: Wallets and marketplaces fetch this URI to display the token's name, image, and attributes.

The structured data format that defines the required and optional fields for token metadata. Adherence to a common schema ensures interoperability across platforms like OpenSea and Rarible.

• Common Fields: name, description, image, and attributes array.
• Extensions: Standards like ERC-721 Metadata JSON Schema and OpenSea Metadata Standards add specific fields for traits, levels, and stats.

A unique integer identifier assigned to each token within a smart contract. For NFTs (ERC-721), this ID is unique and points to specific metadata. For fungible tokens, it often represents a whole class of identical items.

• On-Chain Key: The primary lookup key used in contract functions like ownerOf(tokenId) or balanceOf(account, tokenId).
• Metadata Mapping: The contract logic uses this ID to return the correct Token URI for that specific asset.

The de facto standard for the JSON file referenced by a token's URI. Common fields include:

• name: The token's title.
• description: A detailed explanation.
• image: A URI to the visual asset.
• attributes: An array of trait objects (e.g., {"trait_type": "Rarity", "value": "Legendary"}).
• external_url: A link to a permanent web page for the asset. This schema is used by major marketplaces like OpenSea for display.

A critical architectural decision for token projects:

• On-Chain Metadata: Stored directly within the smart contract's storage or as Base64-encoded data in the token URI. Benefits include immutability and censorship resistance, but costs more gas and limits complexity.
• Off-Chain Metadata: Stored on external servers (centralized) or decentralized networks like IPFS or Arweave. This is cost-effective and flexible but introduces a dependency on the availability of that external resource.

Beyond NFTs, metadata is crucial for DeFi and governance tokens. Standards like ERC-1363 (Payable Token) and ERC-5269 (EIPs Discovery) extend token functionality with metadata. It enables wallets and dApps to:

• Display custom token symbols, logos, and decimals.
• Discover interfaces a contract supports.
• Provide user-friendly information for staking, vesting, and governance proposals, integrating financial data directly into the token's identity.