NFT Metadata Development: On-Chain and Off-Chain Architecture

NFT Metadata Development (on-chain/off-chain)

A wrong metadata architecture choice leads to data loss or unnecessarily high gas during minting. We are a team of blockchain engineers experienced in smart contract and NFT collection development. We help you choose the architecture: on-chain for maximum decentralization or off-chain on IPFS for complex visuals. We develop metadata for your collection—from concept to deployment.

tokenURI() returns a string—a URL or base64-encoded JSON. Behind this simplicity lies an architectural decision that will determine the collection's fate for years. Metadata on a centralized IPFS gateway is not decentralized; it's a link to a Pinata server that could disappear. An NFT with metadata on the contract will outlive any hosting. The average deployment cost of an on-chain collection of 10,000 tokens is about 0.1 ETH with optimal packing, whereas off-chain is less than 0.01 ETH.

On-chain or off-chain: which to choose?

Fully on-chain

Metadata is stored directly in the smart contract. tokenURI() generates JSON and SVG at runtime via string concatenation:

function tokenURI(uint256 tokenId) public view override returns (string memory) {
    string memory json = Base64.encode(bytes(string(abi.encodePacked(
        '{"name":"Token #', Strings.toString(tokenId),
        '","description":"On-chain NFT","image":"data:image/svg+xml;base64,',
        Base64.encode(bytes(_generateSVG(tokenId))),
        '"}'
    ))));
    return string(abi.encodePacked("data:application/json;base64,", json));
}

Advantage: complete permanence, no reliance on external services. Disadvantage: deployment gas grows with SVG size. For simple generative collections (Loot, Nouns-style) this works. For photographs—no.

Storing attributes in storage: mapping tokenId → struct with trait values. Each attribute is uint8 or bytes32 to save slots. uint8 attributes pack 32 into one storage slot.

IPFS off-chain

Standard approach for most collections. Metadata is uploaded to IPFS, tokenURI() returns ipfs://CID/tokenId.json. Critical requirement: do not use an HTTP gateway in the URI.

Correct: ipfs://QmHash/1.json Incorrect: https://ipfs.io/ipfs/QmHash/1.json

The second is a link to a specific HTTP server—it may disappear. The first is a content address that works with any IPFS gateway.

For pinning—Pinata + Web3.Storage as backup. For the most important collections—Filecoin via NFT.Storage for long-term storage with cryptographic guarantee.

Comparison of on-chain and off-chain

On-chain metadata is 3 times more reliable than off-chain when using a single pinning service without backup. However, for collections with hundreds of megabytes of media, off-chain remains the only realistic option.

How to optimize gas for on-chain metadata?

Attribute packing is key. If you store each attribute as a separate uint256, 10 attributes take 10 storage slots. Packing uint8 at 32 per slot reduces deployment gas by 40%. For a collection of 10,000 tokens, this saves ~0.04 ETH. Generating SVG via string concatenation without libraries saves up to 30,000 gas per tokenURI call. Use Base64-encoding of JSON directly in the contract—it's cheaper than returning a URL.

How does the reveal mechanism work?

Pre-reveal: all tokens show placeholder metadata. Post-reveal: real metadata is revealed. A naive implementation—owner simply changes baseURI—is centralized and trust-based.

Commit-reveal scheme with VRF: before mint, the owner commits a seed hash; after mint is complete, publishes the seed and calls Chainlink VRF to get a random offset. Metadata is shuffles deterministically via (tokenId + offset) % totalSupply. No one can know in advance which traits any token will get.

function fulfillRandomWords(uint256, uint256[] memory randomWords) internal override {
    revealOffset = randomWords[0] % maxSupply;
    revealed = true;
}

function tokenURI(uint256 tokenId) public view override returns (string memory) {
    require(revealed, "Not revealed yet");
    uint256 metadataId = (tokenId + revealOffset) % maxSupply;
    return string(abi.encodePacked(baseURI, metadataId.toString(), ".json"));
}

Comparison of reveal methods

Why is the reveal mechanism important for collection fairness?

Without a reveal mechanism, minters can analyze metadata before purchase—choosing only rare tokens. This destroys the collection's economics and trust. Commit-reveal ensures no one knows traits before purchase, and VRF provides random distribution. Investing 50,000 gas on reveal (less than $0.5 at 50 gwei) protects the collection's market capitalization from manipulation.

JSON metadata structure

The OpenSea ERC-721 metadata standard is described in EIP-721:

{
  "name": "Token #1",
  "description": "Description text",
  "image": "ipfs://CID/1.png",
  "external_url": "https://project.xyz/token/1",
  "attributes": [
    {"trait_type": "Background", "value": "Blue"},
    {"trait_type": "Rarity", "value": "Legendary", "display_type": "boost_percentage", "max_value": 100}
  ]
}

display_type controls display in OpenSea. Numeric attributes: "number" (plain number), "boost_percentage" (progress bar), "boost_number" (modifier), "date" (unix timestamp → date).

For ERC-1155 the structure is similar, but tokenURI takes uint256 id and can use the {id} placeholder in the URI.

"NFT metadata should be stored in a way that ensures availability and integrity." — EIP-721 rationale.

What is included in metadata development

• Architecture selection (on-chain / off-chain / hybrid) with rationale
• Writing the smart contract with optimized tokenURI
• Metadata generation (TypeScript scripts, rarity weights, layers)
• Upload to IPFS with backup pinning
• Implementation of the reveal mechanism with or without Chainlink VRF
• Contract deployment and configuration of public methods
• Documentation for metadata updates (if off-chain)
• 2-week post-launch support

We have implemented 30+ NFT projects with a total market volume of over 500 ETH. Average gas reduction on on-chain metadata is 40% due to attribute packing and SVG optimization. Get a consultation on metadata architecture for your collection—from 2 days for off-chain to 5 days for on-chain with a reveal mechanism.

We use Foundry for testing and Slither for vulnerability detection. We guarantee the contract passes audit without critical errors. Contact us—we will offer the optimal solution for your project.

Why does NFT marketplace development require a comprehensive approach?

We see that at first glance, an NFT contract looks simple: ERC-721, mint(), IPFS for metadata — that's it. In practice, it's this 'simplicity' that hides most problems — from bots buying out the entire mint in the first block to broken royalties on the secondary market. We often hear: Make a collection like others in a week — and a month later it turns out gas has tripled due to an unoptimized for loop, or OpenSea cannot see metadata after reveal. We know each of these pitfalls and build processes to avoid them.

Over 5 years of working with blockchains, we have implemented 40+ NFT projects, including marketplaces with dynamic attributes and cross-chain bridges. We have accumulated a library of proven templates — some of which we break down below.

Which standard to choose: ERC-721 or ERC-1155?

ERC-721 — each token is unique, one owner. Suitable for collections where each NFT has individual attributes and a direct owner → tokenId mapping.
ERC-1155 — multi-token standard: one contract holds both fungible and non-fungible tokens. It uses balanceOf(address, tokenId) instead of ownerOf(tokenId). A single transaction can transfer multiple different tokens via safeBatchTransferFrom. This saves gas on bulk operations — important for game items, tickets, edition collections. ERC-1155 is 2–3× more gas-efficient than ERC-721 for batch transfers.

Specific case: a game project with 50 types of items, each with a supply of 10,000. ERC-721 — 500,000 unique tokens, huge overhead on mappings. ERC-1155 — 50 tokenIds, balanceOf per player. Gas per transfer is 2–3 times lower, contract deployment is cheaper. For such tasks, we use OpenZeppelin ERC-1155 with custom modifications.

Metadata: on-chain vs IPFS vs centralized

The standard route is tokenURI() returning a link to a JSON with fields name, description, image, attributes. Three storage options:

• Centralized server — cheapest and most flexible. Risk: server goes down, company closes — NFT loses metadata. Not suitable for collections claiming long-term value.
• IPFS + Pinning — content-addressed storage, the link is bound to the content hash. Pinata or NFT.Storage provide pinning. Important: IPFS does not guarantee availability by itself — an active pinning service is needed. If it shuts down, data may disappear if no one keeps a copy.
• On-chain metadata — base64-encoded SVG or JSON directly in tokenURI. Maximum reliability, but expensive: for a collection of 10,000 tokens, gas costs may exceed $5,000. Suitable for generative art projects where visuals are generated from on-chain attributes (Nouns, Loot).

For most collections, we choose IPFS with Pinata for images + on-chain attributes for traits — a good balance. We validate files against a JSON Schema before upload; a typical mistake is unescaped quotes, causing marketplaces to display a blank screen.

{
  "name": "Token #1",
  "description": "A unique NFT",
  "image": "ipfs://QmHash/image.png",
  "attributes": [{"trait_type": "Background", "value": "Red"}]
}

Dynamic NFT: metadata that changes

Dynamic NFT updates metadata in response to external events — match results, character levels, real-world data via Chainlink. Architecturally, it's a combination: the smart contract stores state → tokenURI() generates metadata from the state on-chain. Caching problem: OpenSea and other marketplaces aggressively cache. The standard invalidation mechanism is a MetadataUpdate(tokenId) event from ERC-4906. OpenSea listens to this event and clears the cache. Without it, updated metadata may not appear for weeks.

Chainlink Automation (formerly Keepers) for automatically updating state on the contract on a schedule or condition — a standard solution for dynamics.

How to protect mint from bots?

Allowlist via Merkle tree — standard. The list of addresses is hashed into a Merkle root, stored in the contract. During mint, the user provides a Merkle proof — the contract verifies without storing the full list. We use OpenZeppelin MerkleProof library.

Reveal mechanism — on mint, a placeholder is issued; real traits are revealed after the sale ends. Otherwise, bots can scan pending transactions and snipe rare traits via frontrunning. But reveal requires a commitment scheme — the random seed must be fixed before mint or use Chainlink VRF.

Chainlink VRF for fair randomization of traits. VRF request at mint → callback with verifiable random number → assign traits. This adds ~2 transactions and latency but guarantees fairness. Chainlink VRF v2.5.

Rate limiting — require(mintedPerWallet[msg.sender] < maxPerWallet). Does not protect against multi-wallets but raises attack cost. For premium projects, we often add proof-of-work directly in the contract (via EIP-2612 signatures).

Royalties: the real market state

ERC-2981 — on-chain royalty standard. The contract returns (recipient, amount) for any sale price via royaltyInfo(tokenId, salePrice). Marketplaces query this on each sale. Problem: adherence to royalties is voluntary for marketplaces. Blur launched with zero royalties, triggering a wave of other platforms. The situation has partially stabilized: OpenSea supports ERC-2981, Blur added optional ones. Royalty payments can represent 5–10% of secondary sale volume, so getting them right matters.

Attempts to enforce royalties on-chain by restricting transfers only to approved marketplaces (operator filtering) were proposed by OpenSea via OperatorFilterRegistry. This breaks composability — you cannot transfer an NFT through a custom contract. Most serious projects have abandoned this approach. For projects where royalties are critical, we build a custom marketplace within the ecosystem plus an incentive structure for users to trade there.

Lazy minting and gas-free mint

Gas-free mint via signature: the creator signs a voucher (tokenId, tokenURI, price, signature), the buyer provides the voucher in mint() — the contract verifies the signature via ECDSA.recover() and mints. Works on OpenSea via their Seaport protocol. Seaport is an optimized contract with minimal gas usage. Understanding its mechanics is important when integrating custom marketplace logic.

Stack for NFT projects

• Contracts: Solidity 0.8.x, OpenZeppelin ERC721Enumerable or ERC721A (Azuki) for gas-optimized batch mint, ERC1155 from OpenZeppelin
• VRF and automation: Chainlink VRF v2.5, Chainlink Automation
• Storage: Pinata (IPFS pinning), NFT.Storage, Arweave for permanent storage
• Marketplace: OpenSea Seaport protocol, custom integration
• Frontend: wagmi v2 + viem, RainbowKit for wallet connection, React + TypeScript

Development process

1. Mint mechanics design — allowlist, public sale, price curve (Dutch auction or fixed), limits per wallet
2. Contracts — with Foundry fuzz tests on mint limits, Merkle proof verification, royalty calculations
3. IPFS deployment — upload metadata and images before reveal, pin on at least two services
4. Reveal — if using Chainlink VRF, test on testnet mandatory: VRF subscription must be funded with LINK tokens
5. Marketplace integration — verify collection on OpenSea, configure royalties, test MetadataUpdate events
6. Deployment and monitoring — Tenderly for reentrancy detection, Etherscan API for contract verification, set up event alerts

Deliverables

• Source code of smart contracts (Solidity, Rust for Solana) with comments
• Test suite (Foundry/Hardhat) with ≥90% coverage
• Deployment documentation and integration instructions
• Access to pinning services (Pinata/Pinfluence)
• Metadata generation scripts (Python/JS)
• Support during marketplace verification
• 30 days of technical support after deployment

Timeline

Cost is calculated individually after auditing your task. Send a brief with your project description — we will provide a transparent estimate within 3 business days. For regular clients, there is a flexible discount system on batch orders. If you need a gas-optimized contract, order a free gas analysis. Get a consultation on marketplace architecture — leave a request, and we will evaluate your project in three days.