CID IPFS 2026: Guida al content addressing

Guida pratica ai CID IPFS: CIDv0 vs CIDv1, come funziona il content addressing, generare CID in Node.js e Python, verificare l'integrità. Aggiornato al 2026.

Nacho Colldi Aggiornato: 10 min di lettura
Guida pratica ai CID IPFS: CIDv0 vs CIDv1, come funziona il content addressing, generare CID in Node.js e Python, verificare l'integrità. Aggiornato al 2026.
TL;DR
  • Genera un CID riproducibile dai byte di qualsiasi file: lo stesso contenuto produce sempre lo stesso hash.
  • Usa CIDv1 per i nuovi upload: è in Base32, minuscolo, e funziona con i gateway a sottodominio; CIDv0 no.
  • Un singolo byte modificato in un file cambia completamente il suo CID, rendendo qualsiasi manomissione immediatamente rilevabile.
  • Il content addressing significa che i file vengono identificati da ciò che sono, non da dove sono ospitati.

Se hai mai lavorato con IPFS (InterPlanetary File System), probabilmente ti sei imbattuto in stringhe come QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG o bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi. Non si tratta di stringhe casuali — sono Content Identifier (CID), la spina dorsale del sistema di indirizzamento per contenuto di IPFS.

Capire i CID è fondamentale per chiunque costruisca su IPFS, che si tratti di caricare file, costruire applicazioni decentralizzate o implementare sistemi di distribuzione dei contenuti. Questa guida ti spiegherà tutto ciò che devi sapere sui CID di IPFS, come funziona l’indirizzamento per contenuto e come iniziare a usarli nei tuoi progetti.

IPFS Ninja

Genera un CID in 5 righe (Python)#

import hashlib, base58

def cidv0(content: bytes) -> str:
    sha256 = hashlib.sha256(content).digest()
    return base58.b58encode(b"\x12\x20" + sha256).decode()

print(cidv0(b"hello world"))
# QmaozNR7DZHQK1ZcU9p7QdrshMvXqWK6gpvBw3cWE69N3T

Quel CID è riproducibile da chiunque — esegui di nuovo lo stesso codice con gli stessi byte in qualsiasi parte del mondo e otterrai la stessa stringa. Questo è l’indirizzamento per contenuto.

Cos’è un CID di IPFS?#

Un Content Identifier (CID) è un’impronta digitale unica che rappresenta un contenuto su IPFS. A differenza degli URL web tradizionali che puntano a una posizione (come https://example.com/file.pdf), i CID puntano al contenuto stesso, indipendentemente da dove sia memorizzato.

Immaginala così:

  • Indirizzamento per posizione: «Vai in Via Principale 123 e chiedi il libro rosso»
  • Indirizzamento per contenuto: «Trova il libro con ISBN 978-0-123456-78-9» (non importa quale biblioteca lo abbia)

I CID funzionano in modo simile — identificano i contenuti tramite il loro hash crittografico, rendendoli immutabili e verificabili. Se cambia anche un solo byte del file, il CID cambia completamente.

Perché l’indirizzamento per contenuto è importante#

L’architettura web tradizionale si basa sull’indirizzamento per posizione. Quando visiti https://example.com/image.jpg, ti fidi che:

  1. Il proprietario del dominio non abbia cambiato il contenuto
  2. Il server sia online e accessibile
  3. Il contenuto non sia stato manomesso

Con l’indirizzamento per contenuto tramite CID:

  1. Immutabilità: Il CID garantisce che il contenuto non sia cambiato
  2. Decentralizzazione: Il contenuto può essere recuperato da qualsiasi nodo IPFS che lo possiede
  3. Verifica: Puoi verificare crittograficamente di aver ricevuto il contenuto corretto
  4. Efficienza: Contenuti identici vengono deduplicati automaticamente

Anatomia di un CID#

Analizziamo un CID tipico per capirne i componenti:

bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi
└─┬─┘└─────────────────┬─────────────────────────────────┘
  │                   │
  │                   └─ Hash del contenuto (codificato in Base32)
  └─ Prefisso Multibase (indica la codifica)

Un CID contiene diverse informazioni:

1. Prefisso Multibase#

Il primo carattere indica come è codificato il CID:

  • Q = Codifica Base58 (CIDv0)
  • b = Codifica Base32 (CIDv1)
  • f = Base16/esadecimale (CIDv1)
  • z = Base58 (CIDv1)

2. Versione del CID#

  • CIDv0: Inizia sempre con Qm, usa SHA-256, limitato al codec DAG-PB
  • CIDv1: Più flessibile, supporta più funzioni hash e codec

3. Multicodec#

Specifica come è strutturato il contenuto (DAG-PB, DAG-CBOR, byte grezzi, ecc.)

4. Multihash#

L’hash crittografico effettivo del contenuto, che include:

  • Identificatore della funzione hash (di solito SHA-256)
  • Lunghezza dell’hash
  • Il digest dell’hash

CIDv0 vs CIDv1: Capire le differenze#

IPFS si è evoluto attraverso due versioni principali di CID, ognuna con caratteristiche distinte:

CIDv0: Il formato originale#

I CID CIDv0 iniziano sempre con Qm e sono fatti così:

QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG

Caratteristiche:

  • Solo codifica Base58
  • Solo funzione hash SHA-256
  • Solo codec DAG-PB (Protobuf)
  • 46 caratteri di lunghezza
  • Retrocompatibili con tutte le implementazioni IPFS

Quando usare CIDv0:

  • Massima compatibilità con nodi IPFS più vecchi
  • Lavorare con sistemi esistenti che si aspettano prefissi Qm
  • Storage di file (caso d’uso più comune)

CIDv1: Lo standard moderno#

I CID CIDv1 sono più flessibili e possono apparire così:

bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi  # Base32
zb2rhj7crUKTQYRGCRATFaQ6YFLTde2YzdqbbhAASkL9uRDXn      # Base58
f01551220d1e2c35...                                      # Base16

Caratteristiche:

  • Formati di codifica multipli (Base32, Base58, Base16)
  • Supporto per diverse funzioni hash (SHA-256, SHA-512, BLAKE2, ecc.)
  • Codec multipli (Raw, DAG-CBOR, DAG-JSON, ecc.)
  • Formato auto-descrittivo
  • Insensibile al maiuscolo/minuscolo quando si usa Base32

Quando usare CIDv1:

  • Costruire nuove applicazioni
  • Avere bisogno di identificatori insensibili al case
  • Lavorare con dati strutturati (JSON, CBOR)
  • Usare funzioni hash alternative

Conversione tra versioni#

Puoi convertire i CID tra versioni mantenendo lo stesso riferimento al contenuto:

// CIDv0
const cidv0 = "QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG";

// Convert to CIDv1 Base32
const cidv1 = "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi";

// Both reference the same content!

Come funziona l’indirizzamento per contenuto#

L’indirizzamento per contenuto in IPFS segue un processo deterministico che garantisce che lo stesso contenuto produca sempre lo stesso CID:

1. Preparazione del contenuto#

Quando aggiungi contenuto a IPFS, viene prima scomposto:

  • File piccoli: Memorizzati come blocchi singoli
  • File grandi: Suddivisi in chunk e organizzati in un Merkle DAG (Directed Acyclic Graph)
  • Directory: Rappresentate come strutture DAG che collegano i file

2. Processo di hashing#

Ogni pezzo di contenuto attraversa:

  1. Serializzazione: Il contenuto viene formattato secondo il suo codec
  2. Hashing: Una funzione hash crittografica elabora i dati serializzati
  3. Creazione del Multihash: L’hash viene incapsulato con informazioni su algoritmo e lunghezza
  4. Assemblaggio del CID: Versione, codec e multihash vengono combinati

3. Struttura Merkle DAG#

IPFS organizza i contenuti in un Merkle DAG dove:

  • Ogni nodo ha un CID
  • I nodi padre fanno riferimento ai nodi figlio tramite CID
  • I cambiamenti in qualsiasi nodo si propagano nell’albero
  • Intere strutture possono essere verificate crittograficamente
Root CID: bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi
├── file1.txt (QmHash1...)
├── file2.jpg (QmHash2...)
└── subdirectory/
    ├── file3.pdf (QmHash3...)
    └── file4.mp4 (QmHash4...)

Esempi pratici: Lavorare con i CID#

Esploriamo come lavorare con i CID nella pratica usando l’API di IPFS Ninja:

Caricare contenuto e ottenere un CID#

// Upload a file and get its CID
const uploadFile = async (content, filename) => {
  const response = await fetch('https://api.ipfs.ninja/upload/new', {
    method: 'POST',
    headers: {
      'X-Api-Key': 'bws_1234567890abcdef1234567890abcdef12345678',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      content: btoa(content), // Base64 encode binary content
      description: `Upload of ${filename}`
    })
  });
  
  const result = await response.json();
  console.log('CID:', result.cid);
  console.log('IPFS URL:', result.uris.ipfs);
  console.log('HTTP URL:', result.uris.url);
  
  return result.cid;
};

// Example usage
uploadFile('Hello, IPFS!', 'greeting.txt');
// Returns: bafkreifjxz6zwqh27k5xnr5qfbx4w6n5vuwwwdcngguwjewzj2e3xxfgvi

Pinnare contenuto esistente tramite CID#

Se hai già un CID, puoi pinnarlo per garantire che rimanga disponibile:

const pinByCID = async (cid) => {
  const response = await fetch('https://api.ipfs.ninja/pin', {
    method: 'POST',
    headers: {
      'X-Api-Key': 'bws_1234567890abcdef1234567890abcdef12345678',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      cid: cid,
      description: 'Pinned via API'
    })
  });
  
  const result = await response.json();
  console.log('Pinned CID:', result.cid);
  
  return result;
};

// Pin the "Hello World" of IPFS
pinByCID('QmWATWQ7fVPP2EFGu71UkfnqhYXDYH566qy47CnJDgvs8u');

Accedere ai contenuti tramite CID#

Una volta che hai un CID, puoi accedere al contenuto con diversi metodi:

// Direct IPFS gateway access
const ipfsUrl = `https://ipfs.ninja/ipfs/${cid}`;

// Custom gateway (if configured)
const customGatewayUrl = `https://my-app.gw.ipfs.ninja/ipfs/${cid}`;

// Fetch content programmatically
const fetchContent = async (cid) => {
  const response = await fetch(`https://ipfs.ninja/ipfs/${cid}`);
  const content = await response.text();
  return content;
};

Best practice per CID per sviluppatori#

1. Valida sempre i CID#

Prima di usare un CID nella tua applicazione, validane il formato:

const isValidCID = (cid) => {
  // Basic validation patterns
  const cidv0Pattern = /^Qm[1-9A-HJ-NP-Za-km-z]{44}$/;
  const cidv1Pattern = /^[bf][a-z2-7]{58}$/;
  
  return cidv0Pattern.test(cid) || cidv1Pattern.test(cid);
};

2. Gestisci entrambe le versioni di CID#

La tua applicazione dovrebbe funzionare sia con CIDv0 che con CIDv1:

const normalizeCID = (cid) => {
  if (cid.startsWith('Qm')) {
    // CIDv0 - can convert to CIDv1 if needed
    return cid;
  } else if (cid.startsWith('b') || cid.startsWith('f') || cid.startsWith('z')) {
    // CIDv1
    return cid;
  } else {
    throw new Error('Invalid CID format');
  }
};

3. Memorizza le mappature CID nella cache#

Se generi CID frequentemente, considera di mettere in cache:

const cidCache = new Map();

const getCachedCID = (content) => {
  const contentHash = btoa(content);
  
  if (cidCache.has(contentHash)) {
    return cidCache.get(contentHash);
  }
  
  // Upload and cache result
  return uploadFile(content).then(cid => {
    cidCache.set(contentHash, cid);
    return cid;
  });
};

4. Usa descrizioni significative#

Quando carichi contenuti, includi metadata descrittivi:

const uploadWithMetadata = async (content, metadata) => {
  return fetch('https://api.ipfs.ninja/upload/new', {
    method: 'POST',
    headers: {
      'X-Api-Key': 'bws_1234567890abcdef1234567890abcdef12345678',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      content: btoa(content),
      description: metadata.name || 'Uploaded file',
      metadata: {
        filename: metadata.filename,
        contentType: metadata.contentType,
        uploadedAt: new Date().toISOString(),
        version: metadata.version || '1.0'
      }
    })
  });
};

Casi d’uso comuni dei CID#

1. Deploy di siti statici#

Distribuisci interi siti web su IPFS e fai riferimento ad essi tramite CID:

// Upload website directory structure
const deployWebsite = async (files) => {
  const uploads = await Promise.all(
    files.map(file => uploadFile(file.content, file.path))
  );
  
  // Root CID references entire site
  const rootCID = uploads.find(u => u.path === 'index.html').cid;
  console.log(`Website deployed: https://ipfs.ninja/ipfs/${rootCID}`);
  
  return rootCID;
};

Per saperne di più sul deploy di siti web, dai un’occhiata alla nostra guida su come caricare file su IPFS.

2. Storage di metadata NFT#

Memorizza i metadata NFT in modo immutabile usando i CID:

const nftMetadata = {
  name: "My Awesome NFT",
  description: "A unique digital collectible",
  image: "ipfs://bafkreibc5sgo2plmjkq2tzmhrn54bk3crhnqekiy7u66fqvqm37pu2e5gw",
  attributes: [
    { trait_type: "Color", value: "Blue" },
    { trait_type: "Rarity", value: "Epic" }
  ]
};

const metadataCID = await uploadFile(
  JSON.stringify(nftMetadata, null, 2), 
  'metadata.json'
);

// Use in smart contract
console.log(`Token URI: ipfs://${metadataCID}`);

3. Distribuzione di contenuti#

Usa i CID per la distribuzione di contenuti decentralizzata:

// Upload once, access everywhere
const distributeContent = async (content) => {
  const cid = await uploadFile(content, 'content.txt');
  
  // Content available via multiple gateways
  const gateways = [
    `https://ipfs.ninja/ipfs/${cid}`,
    `https://ipfs.io/ipfs/${cid}`,
    `https://cloudflare-ipfs.com/ipfs/${cid}`
  ];
  
  return { cid, gateways };
};

Capire il pinning IPFS con i CID#

I CID sono temporanei per default — devono essere «pinnati» per rimanere disponibili. Scopri di più su questo concetto cruciale nella nostra guida completa su cos’è il pinning IPFS.

Quando scegli un servizio di pinning IPFS, considera di leggere il nostro confronto IPFS Ninja vs Pinata o esplora il nostro riepilogo dei migliori servizi di pinning IPFS disponibili oggi.

Crea il tuo primo CID in 30 secondi#

Pronto a generare il tuo primo CID? Ecco un esempio rapido usando l’API di IPFS Ninja:

# Using curl (replace with your actual API key)
curl -X POST https://api.ipfs.ninja/upload/new \
  -H "X-Api-Key: bws_YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "SGVsbG8sIElQRlMgV29ybGQh",
    "description": "My first IPFS upload"
  }'
// Using JavaScript
const createFirstCID = async () => {
  const response = await fetch('https://api.ipfs.ninja/upload/new', {
    method: 'POST',
    headers: {
      'X-Api-Key': 'bws_YOUR_API_KEY_HERE',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      content: btoa('Hello, IPFS World!'), // Base64: "SGVsbG8sIElQRlMgV29ybGQh"
      description: 'My first IPFS upload'
    })
  });
  
  const result = await response.json();
  console.log('🎉 Your first CID:', result.cid);
  console.log('🌐 Access it at:', result.uris.url);
  
  return result;
};

createFirstCID();

Questo restituirà qualcosa di simile:

{
  "cid": "bafkreif2pall7dybz7vecqka3zo24irdwabf7rbiiweuhau7a2hjlqvfjw",
  "sizeMB": 0.000017,
  "uris": {
    "ipfs": "ipfs://bafkreif2pall7dybz7vecqka3zo24irdwabf7rbiiweuhau7a2hjlqvfjw",
    "url": "https://ipfs.ninja/ipfs/bafkreif2pall7dybz7vecqka3zo24irdwabf7rbiiweuhau7a2hjlqvfjw"
  }
}

Per esempi API più dettagliati, vedi il nostro tutorial dell’API di upload IPFS.

Conclusione#

I CID sono il fondamento del sistema di indirizzamento per contenuto di IPFS, fornendo identificazione del contenuto immutabile, verificabile e decentralizzata. Capire come funzionano — dai dettagli tecnici di CIDv0 vs CIDv1 ai pattern pratici di implementazione — è essenziale per costruire applicazioni decentralizzate robuste.

Punti chiave:

  • I CID identificano univocamente i contenuti, non le posizioni
  • CIDv0 offre massima compatibilità, CIDv1 offre flessibilità
  • L’indirizzamento per contenuto consente la verifica e la deduplicazione
  • Una gestione corretta dei CID è cruciale per le applicazioni di produzione

Sia che tu stia memorizzando metadata NFT, distribuendo siti web decentralizzati o costruendo sistemi di distribuzione dei contenuti, i CID forniscono la base affidabile necessaria per applicazioni veramente decentralizzate.

Pronto a iniziare a pinnare? Crea un account gratuito — 50 file, 1 GB di storage, 2 GB di banda/mese. Senza carta di credito.

Nacho Coll

Sull'autore

Founder & Engineer at IPFS.NINJA

Nacho founded IPFS.NINJA to make content-addressed storage feel as simple as an S3 PUT — a single API call, a permanent CID, no wallets or peer discovery to reason about. Writes about IPFS internals, decentralized storage patterns, and the pinning-service landscape from the operator side of the wire.

Torna al Blog

Articoli Correlati

Prestazioni IPFS: accelera il recupero con gateway dedicato
Guides

Prestazioni IPFS: accelera il recupero con gateway dedicato

29 giu 20267min di lettura
Token di Upload IPFS: Upload Sicuri Lato Client senza Esporre le Chiavi API
Guides

Token di Upload IPFS: Upload Sicuri Lato Client senza Esporre le Chiavi API

6 apr 202610min di lettura
Archiviazione metadati NFT: guida IPFS per creatori
Guides

Archiviazione metadati NFT: guida IPFS per creatori

30 mar 20269min di lettura