ERC-721 e ERC-1155 con Metadati IPFS — Smart Contract NFT che Funzionano Davvero

Perché un NFT non è solo un'immagine costosa

Quando un cliente ci chiede di sviluppare un marketplace o una collezione NFT, il primo problema che vediamo è sempre lo stesso: si parte dall'immagine, dal design, dal marketing. Pochi si fermano a pensare a cosa rende un NFT tecnicamente solido, trasferibile, persistente. Un token che punta a un'immagine su un server centralizzato? Non è un NFT, è un segnalibro fragile. Se il server cade, il token vale zero. Noi, di Meteora Web, affrontiamo questi progetti partendo dalla blockchain — ERC-721 o ERC-1155? E dove mettiamo i metadati? IPFS, non altrove. In questa guida vediamo esattamente come scrivere smart contract per NFT che reggano al tempo, al mercato e alle verifiche on-chain.

Cosa differenzia ERC-721 da ERC-1155 nella pratica?

ERC-721: un token per ogni identità

ERC-721 è lo standard originale per token non fungibili. Ogni token ha un ID unico. Lo usi quando ogni asset è distinto: arte digitale, oggetti da collezione, certificati. Lo smart contract assegna un ID e lo lega a un proprietario tramite mapping. La funzione ownerOf(tokenId) restituisce l'indirizzo. Semplice, lineare. Ma se hai 10.000 token, devi deployare 10.000 entry nello storage. Il costo di minting è fisso per token.

ERC-1155: il multi-token che risparmia gas

ERC-1155 è stato progettato per gestire sia token fungibili che non fungibili in un unico contratto. Ogni ID può rappresentare una classe di token con una quantità. Esempio: un gioco ha 5 spade rare (ID 1) e 100 pozioni (ID 2). Con ERC-1155 un singolo contratto basta. Inoltre, le transfer batch riducono il gas: una transazione sposta più token. Noi lo consigliamo per progetti con volumi elevati o economie multiple (item, valute, skin).

Nella nostra esperienza, se devi vendere 100 edizioni limitate di un'opera, ERC-721 va bene. Se hai un ecosistema complesso, ERC-1155 è la scelta giusta.

Come implementare uno smart contract ERC-721 con OpenZeppelin?

Partiamo dal codice che usiamo nei progetti reali. Installi le dipendenze Hardhat e OpenZeppelin, poi scrivi il contratto.

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

import "@openzeppelin/contracts/token/ERC721/extensions/ERC721URIStorage.sol";

contract MyNFT is ERC721URIStorage {
    uint256 private _nextTokenId;

    constructor() ERC721("MyNFT", "MNFT") {}

    function safeMint(address to, string memory uri) public returns (uint256) {
        uint256 tokenId = _nextTokenId++;
        _safeMint(to, tokenId);
        _setTokenURI(tokenId, uri);
        return tokenId;
    }
}

Il punto critico: _setTokenURI memorizza l'URI dei metadati. Se usi un server centralizzato, il token è vulnerabile. Ecco perché noi puntiamo sempre a IPFS.

Come gestire i metadati su IPFS in modo sicuro?

IPFS (InterPlanetary File System) garantisce persistenza tramite content-addressing. L'URI è un hash del contenuto: se modifichi il file, l'hash cambia. Nessuno può alterare l'immagine senza cambiare l'URI. Il problema? I file su IPFS non sono garantiti permanenti se nessuno li pinna. Servizi come Pinata o Infura offrono pinning, ma noi spesso consigliamo ai clienti di mantenere un nodo IPFS proprio o usare Filecoin per archiviazione a lungo termine.

Il formato dei metadati secondo lo standard OpenSea (de facto) è un JSON:

{
  "name": "Opera #1",
  "description": "Prima opera della collezione",
  "image": "ipfs://Qm...hash.../immagine.png",
  "attributes": [
    {"trait_type": "Rarità", "value": "Leggendario"}
  ]
}

L'URI passato a safeMint sarà ipfs://Qm...hash.../token1.json. MAI usare link HTTP. Perdere il controllo significa perdere il valore del token.

Come si usa ERC-1155 per collezioni multiple e batch transfer?

Lo standard ERC-1155 include funzioni balanceOf, safeTransferFrom e safeBatchTransferFrom. Ecco un esempio base:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

import "@openzeppelin/contracts/token/ERC1155/ERC1155.sol";

contract MyCollection is ERC1155 {
    uint256 public constant ART_1 = 0;
    uint256 public constant ART_2 = 1;

    constructor() ERC1155("ipfs://Qm.../{id}.json") {
        _mint(msg.sender, ART_1, 100, "");
        _mint(msg.sender, ART_2, 50, "");
    }
}

Attenzione: l'URI base contiene {id} che viene sostituito automaticamente con l'ID del token. I metadati su IPFS devono avere file con nome corrispondente all'ID (es. 0.json, 1.json). Questo semplifica la gestione di centinaia di token.

Quali errori evitare nella gestione di metadati off-chain?

Il primo errore: URL centralizzati. Abbiamo visto progetti con link a Google Drive o server AWS. Se il server cade, il tuo NFT è una stringa vuota. Il secondo errore: URI mutabili. Se usi un contratto proxy o un URI updatable, perdi la fiducia degli acquirenti. Il terzo errore: dimenticare lo storage dei metadati su IPFS dopo il deploy. Pinnare i file prima di mintare è essenziale.

Noi, di Meteora Web, usiamo uno script di deploy che carica automaticamente i metadati su IPFS e li pinna via API. Poi genera il contratto con l'URI corretto. Nessun passaggio manuale, nessun errore.

Cosa fare adesso

1. Scegli lo standard: ERC-721 per collezioni semplici, ERC-1155 per progetti multi-asset.
2. Usa IPFS per i metadati: carica file JSON e immagini, ottieni hash, pinna.
3. Implanta con OpenZeppelin: usa librerie auditate per sicurezza e risparmio gas.
4. Testa su testnet: Goerli o Sepolia con Hardhat. Verifica che tokenId e URI corrispondano.
5. Blocca l'URI: non prevedere funzioni per cambiare metadati dopo il mint.

Per approfondire l'intero ecosistema blockchain per sviluppatori, leggi il nostro pillar Blockchain e Web3 per Sviluppatori.