NFT metadata is the information that makes an NFT meaningful beyond its token ID — the name, description, image, and trait attributes that define what the NFT actually is. When you own “Bored Ape #1234,” the Ethereum blockchain stores only: your wallet address, the contract address, and the token ID (1234). All the actual content — the image of the ape, its trait properties (background color, fur type, accessories) — lives in metadata stored somewhere else. The token contract points to a URI (uniform resource identifier) — a URL or IPFS hash — that resolves to a JSON file describing the NFT. This architecture creates a critical vulnerability: if the server hosting that JSON or the images goes offline, your NFT still exists on Ethereum but displays as a broken link. The storage choice (centralized server, IPFS, Arweave, fully on-chain) dramatically affects the NFT’s longevity and true decentralization.
Metadata Structure (ERC-721 Standard)
“`json
{
“name”: “Bored Ape #1234”,
“description”: “A unique ape from the Bored Ape Yacht Club collection.”,
“image”: “ipfs://QmXyZ…/1234.png”,
“attributes”: [
{“trait_type”: “Background”, “value”: “Blue”},
{“trait_type”: “Fur”, “value”: “Brown”},
{“trait_type”: “Eyes”, “value”: “X Eyes”},
{“trait_type”: “Mouth”, “value”: “Bored”}
]
}
“`
The tokenURI(tokenId) function on an ERC-721 contract returns the URI pointing to this JSON.
Metadata Storage Options
| Storage Type | Permanence | Decentralization | Cost | Examples |
|---|---|---|---|---|
| Centralized server | Poor (offline risk) | None | Low | Early NFT projects |
| IPFS (pinned) | Good (if pinned) | High | Low | Most major NFTs |
| Arweave | Excellent (permanent) | High | Medium | Art NFTs, premium collections |
| Fully on-chain | Permanent | Complete | High (calldata) | CryptoPunks, Nouns |
Fully On-Chain NFTs
The gold standard for permanence — the image and metadata are stored directly in the contract (as base64-encoded SVG or HTML). No external storage dependency. Examples:
- CryptoPunks: Pixel images stored fully on-chain (retroactively after 2022 upgrade)
- Nouns DAO: SVG images generated deterministically from seed on-chain
- Autoglyphs: ASCII art generated by the contract itself
On-chain NFTs cannot be changed or destroyed as long as Ethereum exists.
Mutable vs. Immutable Metadata
When tokenURI points to a developer-controlled server, the developer can change the metadata — the image, traits, description. This “rug metadata” attack has occurred in real projects. Freezing/immutability best practices: point to IPFS CID (content-addressed hash) rather than a URL, and call freezeMetadata() to lock the URI permanently.
Social Media Sentiment
NFT metadata permanence is a frequently debated topic in NFT collector communities. “What happens if the server goes down?” is a common investor concern. On-chain and Arweave-hosted NFTs command premiums for perceived permanence. IPFS is widely accepted as a good solution, with caveats about pinning maintenance. Centralized hosting is viewed negatively for collector-grade NFTs.
Last updated: 2026-04
Related Terms
Sources
- “ERC-721: Non-Fungible Token Standard and Metadata Extension” — Ethereum EIP-721 Authors (2018). The original ERC-721 standard including the optional Metadata Extension — defining the
tokenURI,name, andsymbolfunctions and the expected JSON format for NFT metadata.
- “NFT Metadata Permanence: A Survey of Storage Solutions” — Protocol Labs / NFT.Storage (2022). Comprehensive analysis of NFT metadata storage on IPFS — comparing IPFS, Arweave, Filecoin, and centralized hosting for permanence, cost, and decentralization.
- “On-Chain NFT Art: Preserving Digital Culture on Ethereum” — Art Blocks / Nouns DAO Research (2022). Analysis of fully on-chain generative NFT art projects — documenting how on-chain storage works technically, the gas costs involved, and why certain projects choose on-chain for permanence.
- “Mutable Metadata Attacks: How NFT Projects Betray Collectors” — OpenSea Research / Web3 Security Researchers (2022). Documentation of real-world mutable metadata incidents — cases where project developers changed NFT images or traits after sale, deceiving buyers.
- “Dynamic NFT Metadata: ChainLink VRF, Oracle-Triggered Updates, and Evolving Tokens” — Chainlink Research (2022). Technical analysis of dynamic NFT implementations where metadata changes in response to real-world data, game events, or user actions — explaining oracle integration for dynamic on-chain state.