· Nacho Coll · Guides  · 9 min di lettura

IPFS CID spiegato: cos'è e come funziona l'indirizzamento per contenuto

Spiegazione tecnica chiara dei Content Identifier (CID) di IPFS. Come funziona l'indirizzamento per contenuto, le versioni di CID e come creare il tuo primo CID.

Spiegazione tecnica chiara dei Content Identifier (CID) di IPFS. Come funziona l'indirizzamento per contenuto, le versioni di CID e come creare il tuo primo CID.

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

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.

Share:
Torna al Blog

Articoli Correlati

Vedi Tutti gli Articoli »