· Nacho Coll · Guides  · 9 min de lectura

CID de IPFS explicado: qué es y cómo funciona el direccionamiento por contenido

Explicación técnica clara de los Content Identifiers (CIDs) de IPFS. Cómo funciona el direccionamiento por contenido, versiones de CID y cómo crear tu primer CID.

Explicación técnica clara de los Content Identifiers (CIDs) de IPFS. Cómo funciona el direccionamiento por contenido, versiones de CID y cómo crear tu primer CID.

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.

IPFS Ninja

¿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:

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

Con direccionamiento por contenido usando CIDs:

  1. Inmutabilidad: El CID garantiza que el contenido no ha cambiado
  2. Descentralización: El contenido puede recuperarse desde cualquier nodo IPFS que lo tenga
  3. Verificación: Puedes verificar criptográficamente que recibiste el contenido correcto
  4. 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:

  1. Serialización: El contenido se formatea según su codec
  2. Hashing: La función hash criptográfica procesa los datos serializados
  3. Creación del multihash: El hash se envuelve con información de algoritmo y longitud
  4. 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.

Share:
Volver al Blog

Artículos Relacionados

Ver Todos los Artículos »