· Nacho Coll · Guides  · 9 min de lectura

IPFS CID explicat: què és i com funciona l'adreçament de contingut

Explicació tècnica clara dels IPFS Content Identifiers (CIDs). Com funciona l'adreçament de contingut, versions de CID i com crear el teu primer CID.

Explicació tècnica clara dels IPFS Content Identifiers (CIDs). Com funciona l'adreçament de contingut, versions de CID i com crear el teu primer CID.

Si alguna vegada has treballat amb IPFS (InterPlanetary File System), probablement t’has trobat amb cadenes com QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG o bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi. No són galimatieso aleatori — són Content Identifiers (CIDs), la columna vertebral del sistema d’adreçament de contingut d’IPFS.

Entendre els CIDs és crucial per a qualsevol que construeixi sobre IPFS, tant si pugues fitxers, com si construeixes aplicacions descentralitzades o implementes sistemes de distribució de contingut. Aquesta guia desglossarà tot el que necessites saber sobre els CIDs d’IPFS, com funciona l’adreçament de contingut i com començar a utilitzar-los en els teus projectes.

IPFS Ninja

Què és un IPFS CID?

Un Content Identifier (CID) és una empremta digital única que representa un fragment de contingut a IPFS. A diferència de les URL web tradicionals que apunten a una ubicació (com https://example.com/file.pdf), els CIDs apunten al contingut mateix, independentment d’on estigui emmagatzemat.

Pensa-ho així:

  • Adreçament basat en la ubicació: «Vés al carrer Major 123 i demana el llibre vermell»
  • Adreçament basat en el contingut: «Troba el llibre amb ISBN 978-0-123456-78-9» (no importa quina biblioteca el tingui)

Els CIDs funcionen de manera similar — identifiquen contingut basat en el seu hash criptogràfic, fent el contingut immutable i verificable. Si canvia un sol byte al fitxer, el CID canvia completament.

Per què importa l’adreçament de contingut

L’arquitectura web tradicional es basa en l’adreçament basat en la ubicació. Quan visites https://example.com/image.jpg, confies en que:

  1. El propietari del domini no ha canviat el contingut
  2. El servidor està en línia i accessible
  3. El contingut no ha estat manipulat

Amb l’adreçament de contingut utilitzant CIDs:

  1. Immutabilitat: El CID garanteix que el contingut no ha canviat
  2. Descentralització: El contingut es pot recuperar des de qualsevol node IPFS que el tingui
  3. Verificació: Pots verificar criptogràficament que has rebut el contingut correcte
  4. Eficiència: El contingut idèntic es deduplica automàticament

Anatomia d’un CID

Desglossem un CID típic per entendre els seus components:

bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi
└─┬─┘└─────────────────┬─────────────────────────────────┘
  │                   │
  │                   └─ Hash del contingut (Base32 codificat)
  └─ Prefix Multibase (indica codificació)

Un CID conté diverses peces d’informació:

1. Prefix Multibase

El primer caràcter indica com està codificat el CID:

  • Q = Codificació Base58 (CIDv0)
  • b = Codificació Base32 (CIDv1)
  • f = Base16/hexadecimal (CIDv1)
  • z = Base58 (CIDv1)

2. Versió CID

  • CIDv0: Sempre comença amb Qm, utilitza SHA-256, limitat al codec DAG-PB
  • CIDv1: Més flexible, suporta múltiples funcions de hash i codecs

3. Multicodec

Especifica com s’estructura el contingut (DAG-PB, DAG-CBOR, bytes en cru, etc.)

4. Multihash

El hash criptogràfic real del contingut, inclòs:

  • Identificador de la funció de hash (generalment SHA-256)
  • Longitud del hash
  • El digest del hash

CIDv0 vs CIDv1: Entenent les diferències

IPFS ha evolucionat a través de dues versions principals de CID, cadascuna amb característiques distintives:

CIDv0: El format original

Els CIDs CIDv0 sempre comencen amb Qm i tenen aquest aspecte:

QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG

Característiques:

  • Només codificació Base58
  • Només funció de hash SHA-256
  • Només codec DAG-PB (Protobuf)
  • 46 caràcters de longitud
  • Compatible amb totes les implementacions IPFS

Quan utilitzar CIDv0:

  • Màxima compatibilitat amb nodes IPFS més antics
  • Treballar amb sistemes existents que esperen prefixos Qm
  • Emmagatzematge de fitxers (cas d’ús més comú)

CIDv1: L’estàndard modern

Els CIDs CIDv1 són més flexibles i poden semblar així:

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

Característiques:

  • Múltiples formats de codificació (Base32, Base58, Base16)
  • Suport per a diferents funcions de hash (SHA-256, SHA-512, BLAKE2, etc.)
  • Múltiples codecs (Raw, DAG-CBOR, DAG-JSON, etc.)
  • Format autodescriptiu
  • Insensible a majúscules en utilitzar Base32

Quan utilitzar CIDv1:

  • Construir noves aplicacions
  • Necessitar identificadors insensibles a majúscules
  • Treballar amb dades estructurades (JSON, CBOR)
  • Utilitzar funcions de hash alternatives

Convertir entre versions

Pots convertir CIDs entre versions mantenint la mateixa referència de contingut:

// CIDv0
const cidv0 = "QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG";

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

// Both reference the same content!

Com funciona l’adreçament de contingut

L’adreçament de contingut a IPFS segueix un procés determinista que assegura que el mateix contingut sempre produeix el mateix CID:

1. Preparació del contingut

Quan afegeixes contingut a IPFS, primer es descompon:

  • Fitxers petits: Emmagatzemats com a blocs únics
  • Fitxers grans: Dividits en trossos i organitzats en un Merkle DAG (graf acíclic dirigit)
  • Directoris: Representats com a estructures DAG que enllacen amb fitxers

2. Procés de hashing

Cada fragment de contingut passa per:

  1. Serialització: El contingut es formata segons el seu codec
  2. Hashing: Una funció de hash criptogràfica processa les dades serialitzades
  3. Creació de Multihash: El hash s’envolca amb informació d’algoritme i longitud
  4. Acoblament del CID: La versió, el codec i el multihash es combinen

3. Estructura Merkle DAG

IPFS organitza el contingut en un Merkle DAG on:

  • Cada node té un CID
  • Els nodes pares fan referència als nodes fills via CID
  • Els canvis en qualsevol node es propaguen per l’arbre
  • Estructures senceres es poden verificar criptogràficament
Root CID: bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi
├── file1.txt (QmHash1...)
├── file2.jpg (QmHash2...)
└── subdirectory/
    ├── file3.pdf (QmHash3...)
    └── file4.mp4 (QmHash4...)

Exemples pràctics: Treballant amb CIDs

Explorem com treballar amb CIDs a la pràctica utilitzant l’API d’IPFS Ninja:

Pujar contingut i obtenir 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

Fixar contingut existent per CID

Si ja tens un CID, pots fixar-lo per garantir la disponibilitat:

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');

Accedir al contingut via CID

Un cop tens un CID, pots accedir al contingut mitjançant diferents mètodes:

// 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;
};

Bones pràctiques de CID per a desenvolupadors

1. Valida sempre els CIDs

Abans d’utilitzar un CID a la teva aplicació, valida el seu format:

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. Gestiona ambdues versions de CID

La teva aplicació hauria de funcionar tant amb CIDv0 com amb 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. Memoritza els mapatges de CID

Si generes CIDs freqüentment, considera la memòria cau:

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. Utilitza descripcions significatives

En pujar contingut, inclou metadades descriptives:

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'
      }
    })
  });
};

Casos d’ús comuns de CID

1. Desplegament de llocs web estàtics

Desplega llocs web sencers a IPFS i referencia-los per 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 saber més sobre el desplegament de llocs web, mira la nostra guia sobre com pujar fitxers a IPFS.

2. Emmagatzematge de metadades NFT

Emmagatzema metadades NFT de manera immutable utilitzant CIDs:

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. Distribució de contingut

Utilitza CIDs per a la lliurament distribuït de contingut:

// 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 };
};

Entenent el pinning d’IPFS amb CIDs

Els CIDs són temporals per defecte — han de ser «fixats» per romandre disponibles. Aprèn més sobre aquest concepte crucial a la nostra guia completa sobre què és el pinning d’IPFS.

En triar un servei de pinning d’IPFS, considera llegir la nostra comparació IPFS Ninja vs Pinata o explora el nostre recull dels millors serveis de pinning d’IPFS disponibles avui.

Crea el teu primer CID en 30 segons

Preparat per generar el teu primer CID? Aquí tens un exemple ràpid utilitzant l’API d’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();

Això retornarà alguna cosa com:

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

Per a exemples d’API més detallats, mira el nostre tutorial d’API d’upload IPFS.

Conclusió

Els CIDs són el fonament del sistema d’adreçament de contingut d’IPFS, proporcionant identificació de contingut immutable, verificable i descentralitzada. Entendre com funcionen — des dels detalls tècnics de CIDv0 vs CIDv1 fins als patrons pràctics d’implementació — és essencial per construir aplicacions descentralitzades robustes.

Punts clau:

  • Els CIDs identifiquen el contingut de manera única, no ubicacions
  • CIDv0 proporciona compatibilitat màxima, CIDv1 ofereix flexibilitat
  • L’adreçament de contingut permet la verificació i la deduplicació
  • La gestió adequada de CID és crucial per a aplicacions de producció

Tant si estàs emmagatzemant metadades NFT, desplegant llocs web descentralitzats, o construint sistemes de distribució de contingut, els CIDs proporcionen la base fiable que necessites per a aplicacions realment descentralitzades.

Preparat per començar a fer pinning? Crea un compte gratuït — 50 fitxers, 1 GB d’emmagatzematge, 2 GB d’ample de banda/mes. Sense targeta de crèdit.

Share:
Tornar al Blog

Articles Relacionats

Veure Tots els Articles »