CIDs de IPFS 2026: Guía de direccionamiento por contenido

Si has trabajado con IPFS (InterPlanetary File System), probablemente te has encontrado con cadenas como QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG o bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi. No son galimatías aleatorios: son Content Identifiers (CIDs), la columna vertebral del sistema de direccionamiento por contenido de IPFS.

Entender los CIDs es crucial para cualquiera que construya sobre IPFS, ya sea subiendo archivos, construyendo aplicaciones descentralizadas o implementando sistemas de distribución de contenido. Esta guía desglosará todo lo que necesitas saber sobre los CIDs de IPFS, cómo funciona el direccionamiento por contenido y cómo empezar a usarlos en tus proyectos.

Genera un CID en 5 líneas (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

Cualquiera puede reproducir este CID — vuelve a ejecutar el mismo código con los mismos bytes en cualquier parte del mundo y obtendrás la misma cadena. Eso es el direccionamiento por contenido.

Equivalente en Node.js:

import { sha256 } from 'multiformats/hashes/sha2';
import { CID } from 'multiformats/cid';

const bytes = new TextEncoder().encode('hello world');
const hash = await sha256.digest(bytes);
const cid = CID.create(1, 0x55, hash); // version 1, raw codec
console.log(cid.toString());
// bafkreif7l7mvyofhyo6fgs6mjf5gguvm5jcahzgvfb3o7t5lmhz3...

¿Qué es un CID de IPFS?#

Un Content Identifier (CID) es una huella única que representa una pieza de contenido en IPFS. A diferencia de las URLs web tradicionales que apuntan a una ubicación (como https://example.com/file.pdf), los CIDs apuntan al contenido en sí, sin importar dónde esté almacenado.

Piénsalo así:

Direccionamiento basado en ubicación: “Ve a la Calle Principal 123 y pide el libro rojo”
Direccionamiento basado en contenido: “Encuentra el libro con ISBN 978-0-123456-78-9” (no importa qué biblioteca lo tenga)

Los CIDs funcionan de manera similar: identifican contenido por su hash criptográfico, lo que hace al contenido inmutable y verificable. Si cambia incluso un solo byte del archivo, el CID cambia por completo.

Por qué importa el direccionamiento por contenido#

La arquitectura web tradicional se apoya en el direccionamiento basado en ubicación. Cuando visitas https://example.com/image.jpg, confías en que:

El dueño del dominio no ha cambiado el contenido
El servidor está online y accesible
El contenido no ha sido manipulado

Con direccionamiento por contenido usando CIDs:

Inmutabilidad: El CID garantiza que el contenido no ha cambiado
Descentralización: El contenido puede recuperarse desde cualquier nodo IPFS que lo tenga
Verificación: Puedes verificar criptográficamente que recibiste el contenido correcto
Eficiencia: El contenido idéntico se deduplica automáticamente

Anatomía de un CID#

Disectemos un CID típico para entender sus componentes:

bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi
└─┬─┘└─────────────────┬─────────────────────────────────┘
  │                   │
  │                   └─ Hash del contenido (codificado en Base32)
  └─ Prefijo Multibase (indica codificación)

Un CID contiene varias piezas de información:

1. Prefijo Multibase#

El primer carácter indica cómo está codificado el CID:

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

2. Versión del CID#

CIDv0: Siempre empieza con Qm, usa SHA-256, limitado al codec DAG-PB
CIDv1: Más flexible, soporta múltiples funciones hash y codecs

3. Multicodec#

Especifica cómo está estructurado el contenido (DAG-PB, DAG-CBOR, bytes en bruto, etc.)

4. Multihash#

El hash criptográfico real del contenido, incluyendo:

Identificador de la función hash (normalmente SHA-256)
Longitud del hash
El digest del hash

CIDv0 vs CIDv1: entendiendo las diferencias#

IPFS ha evolucionado a través de dos versiones principales de CID, cada una con características distintas:

CIDv0: el formato original#

Los CIDs CIDv0 siempre empiezan con Qm y se ven así:

QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG

Características:

Solo codificación Base58
Solo función hash SHA-256
Solo codec DAG-PB (Protobuf)
46 caracteres de largo
Compatible hacia atrás con todas las implementaciones de IPFS

Cuándo usar CIDv0:

Compatibilidad máxima con nodos IPFS antiguos
Trabajar con sistemas existentes que esperan prefijos Qm
Almacenamiento de archivos (caso de uso más común)

CIDv1: el estándar moderno#

Los CIDs CIDv1 son más flexibles y pueden verse así:

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

Características:

Múltiples formatos de codificación (Base32, Base58, Base16)
Soporte para diferentes funciones hash (SHA-256, SHA-512, BLAKE2, etc.)
Múltiples codecs (Raw, DAG-CBOR, DAG-JSON, etc.)
Formato auto-descriptivo
Insensible a mayúsculas cuando se usa Base32

Cuándo usar CIDv1:

Construir nuevas aplicaciones
Necesitar identificadores insensibles a mayúsculas
Trabajar con datos estructurados (JSON, CBOR)
Usar funciones hash alternativas

Convertir entre versiones#

Puedes convertir CIDs entre versiones manteniendo la misma referencia de contenido:

// CIDv0
const cidv0 = "QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG";

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

// Both reference the same content!

Cómo funciona el direccionamiento por contenido#

El direccionamiento por contenido en IPFS sigue un proceso determinístico que asegura que el mismo contenido siempre produce el mismo CID:

1. Preparación del contenido#

Cuando añades contenido a IPFS, primero se descompone:

Archivos pequeños: Se almacenan como bloques únicos
Archivos grandes: Se dividen en trozos y se organizan en un Merkle DAG (Directed Acyclic Graph)
Directorios: Se representan como estructuras DAG que enlazan a archivos

2. Proceso de hashing#

Cada pieza de contenido pasa por:

Serialización: El contenido se formatea según su codec
Hashing: La función hash criptográfica procesa los datos serializados
Creación del multihash: El hash se envuelve con información de algoritmo y longitud
Ensamblaje del CID: Versión, codec y multihash se combinan

3. Estructura Merkle DAG#

IPFS organiza el contenido en un Merkle DAG donde:

Cada nodo tiene un CID
Los nodos padres referencian a los nodos hijos por CID
Los cambios en cualquier nodo se propagan árbol arriba
Estructuras completas pueden verificarse criptográficamente

Root CID: bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi
├── file1.txt (QmHash1...)
├── file2.jpg (QmHash2...)
└── subdirectory/
    ├── file3.pdf (QmHash3...)
    └── file4.mp4 (QmHash4...)

Ejemplos prácticos: trabajar con CIDs#

Veamos cómo trabajar con CIDs en la práctica usando la API de IPFS Ninja:

Subir contenido y obtener 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

Pinear contenido existente por CID#

Si ya tienes un CID, puedes pinearlo para asegurar que siga disponible:

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

Acceder al contenido vía CID#

Una vez que tienes un CID, puedes acceder al contenido por varios métodos:

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

Buenas prácticas con CIDs para desarrolladores#

1. Siempre valida los CIDs#

Antes de usar un CID en tu aplicación, valida su 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. Maneja ambas versiones de CID#

Tu aplicación debería funcionar con CIDv0 y 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. Cachea los mapeos de CID#

Si generas CIDs con frecuencia, considera cachear:

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 descripciones significativas#

Al subir contenido, incluye metadatos descriptivos:

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 de uso comunes de CID#

1. Despliegue de sitios web estáticos#

Despliega sitios web enteros en IPFS y refiérelos por 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;
};

Para aprender más sobre despliegue de sitios web, consulta nuestra guía sobre cómo subir archivos a IPFS.

2. Almacenamiento de metadatos NFT#

Almacena metadatos NFT inmutablemente usando 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ón de contenido#

Usa CIDs para entrega de contenido distribuida:

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

Entendiendo el pinning de IPFS con CIDs#

Los CIDs son temporales por defecto: necesitan ser “pineados” para mantenerse disponibles. Aprende más sobre este concepto crucial en nuestra guía completa sobre qué es el pinning de IPFS.

Al elegir un servicio de pinning IPFS, considera leer nuestra comparativa de IPFS Ninja vs Pinata o explora nuestro resumen de los mejores servicios de pinning IPFS disponibles hoy.

Crea tu primer CID en 30 segundos#

¿Listo para generar tu primer CID? Aquí un ejemplo rápido usando la API de 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();

Esto devolverá algo como:

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

Para ejemplos de API más detallados, consulta nuestro tutorial de API de subida IPFS.

Conclusión#

Los CIDs son la base del sistema de direccionamiento por contenido de IPFS, proporcionando identificación de contenido inmutable, verificable y descentralizada. Entender cómo funcionan —desde los detalles técnicos de CIDv0 vs CIDv1 hasta los patrones prácticos de implementación— es esencial para construir aplicaciones descentralizadas robustas.

Puntos clave:

Los CIDs identifican contenido de forma única, no ubicaciones
CIDv0 ofrece compatibilidad máxima, CIDv1 proporciona flexibilidad
El direccionamiento por contenido permite verificación y deduplicación
El manejo adecuado de CIDs es crucial para aplicaciones en producción

Tanto si almacenas metadatos NFT, despliegas sitios web descentralizados o construyes sistemas de distribución de contenido, los CIDs proporcionan la base fiable que necesitas para aplicaciones verdaderamente descentralizadas.

¿Listo para empezar a pinear? Crea una cuenta gratis — 50 archivos, 1 GB de almacenamiento, 2 GB de ancho de banda/mes. Sin tarjeta de crédito.