Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

Architecture Overview

magical-nft uses a modular three-contract architecture designed for flexibility, gas efficiency, and upgradeability.

Contract Structure

┌─────────────────┐     ┌───────────────────────┐     ┌──────────────────────┐
│  NFT Contract   │────►│     NFT Renderer      │────►│     NFT Storage      │
│    (ERC721)     │     │      (generates       │     │      (EthDrive)      │
│                 │     │       HTML/JSON)      │     │                      │
│ • tokenURI()    │     │ • metadata            │     │ • Files (AVIF)       │
│                 │     │                       │     │ • HTML/CSS/JS        │
└─────────────────┘     └───────────────────────┘     └──────────────────────┘
   (redeployable)            (redeployable)                (redeployable)

Main Contract

The main contract ({{ProjectName}}.sol) handles:

  • ERC721 Implementation - Token ownership and transfers
  • Minting Logic - Mint functions with any custom logic
  • Access Control - Owner-only functions
  • Contract References - Links to renderer and storage

Renderer Contract

The renderer contract ({{ProjectName}}Renderer.sol) is responsible for:

  • Metadata Generation - Building the JSON metadata
  • Image Generation - Creating SVG or HTML-based images
  • Dynamic Content - Rendering based on token state

This separation allows you to upgrade the rendering logic without touching the main contract.

Storage Contract

The storage contract ({{ProjectName}}Storage.sol) manages:

  • SSTORE2 Storage - Efficient onchain data storage
  • File Registry - Mapping of file names to storage addresses
  • Data Retrieval - Functions to read stored data

Using SSTORE2 reduces gas costs significantly compared to regular storage.

Data Flow

  1. User calls tokenURI(tokenId) on the NFT contract
  2. NFT contract delegates to the Renderer
  3. Renderer fetches required assets from Storage (via EthDrive)
  4. Renderer builds and returns the complete metadata JSON with embedded HTML
  5. JSON contains base64-encoded HTML/CSS/JS animation

Benefits

  • Upgradeability - Update renderer without migrating tokens
  • Gas Efficiency - SSTORE2 reduces storage costs
  • Separation of Concerns - Each contract has a single responsibility
  • Composability - Other contracts can interact with individual components