· Nacho Coll · Guides  · 9 min de lectura

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

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

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

Si alguna vez 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 de contenido de IPFS.

Comprender los CIDs es crucial para cualquiera que construya sobre IPFS, ya sea que subas archivos, construyas aplicaciones descentralizadas o implementes 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 de contenido y cómo empezar a usarlos en tus proyectos.

IPFS Ninja

¿Qué es un IPFS CID?

Un Content Identifier (CID) es una huella digital única que representa un fragmento 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 mismo, independientemente de dónde esté almacenado.

Piénsalo así:

  • Direccionamiento basado en ubicación: «Ve a la calle Mayor 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 forma similar — identifican el contenido basándose en su hash criptográfico, haciendo que el contenido sea inmutable y verificable. Si un solo byte cambia en el archivo, el CID cambia completamente.

Por qué importa el direccionamiento de contenido

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

  1. El propietario del dominio no ha cambiado el contenido
  2. El servidor está en línea y accesible
  3. El contenido no ha sido manipulado

Con el direccionamiento de 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

Desglosemos un CID típico para entender sus componentes:

bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi
└─┬─┘└─────────────────┬─────────────────────────────────┘
  │                   │
  │                   └─ Hash del contenido (Base32 codificado)
  └─ 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 CID

  • CIDv0: Siempre empieza con Qm, usa SHA-256, limitado al códec DAG-PB
  • CIDv1: Más flexible, soporta múltiples funciones hash y códecs

3. Multicodec

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

4. Multihash

El hash criptográfico real del contenido, incluyendo:

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

CIDv0 vs CIDv1: Comprendiendo las diferencias

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

CIDv0: El formato original

Los CIDs CIDv0 siempre empiezan con Qm y tienen este aspecto:

QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG

Características:

  • Solo codificación Base58
  • Solo función hash SHA-256
  • Solo códec DAG-PB (Protobuf)
  • 46 caracteres de longitud
  • Compatible con todas las implementaciones de IPFS

Cuándo usar CIDv0:

  • Máxima compatibilidad con nodos IPFS más 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 tener este aspecto:

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 códecs (Raw, DAG-CBOR, DAG-JSON, etc.)
  • Formato autodescriptivo
  • Insensible a mayúsculas al usar 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 de contenido

El direccionamiento de contenido en IPFS sigue un proceso determinista 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: Almacenados como bloques únicos
  • Archivos grandes: Divididos en trozos y organizados en un Merkle DAG (grafo acíclico dirigido)
  • Directorios: Representados como estructuras DAG que enlazan con archivos

2. Proceso de hashing

Cada fragmento de contenido pasa por:

  1. Serialización: El contenido se formatea según su códec
  2. Hashing: Una función hash criptográfica procesa los datos serializados
  3. Creación de Multihash: El hash se envuelve con información de algoritmo y longitud
  4. Ensamblaje del CID: La versión, el códec y el multihash se combinan

3. Estructura Merkle DAG

IPFS organiza el contenido en un Merkle DAG donde:

  • Cada nodo tiene un CID
  • Los nodos padre referencian los nodos hijos vía CID
  • Los cambios en cualquier nodo se propagan hacia arriba en el árbol
  • Estructuras enteras se pueden verificar criptográficamente
Root CID: bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi
├── file1.txt (QmHash1...)
├── file2.jpg (QmHash2...)
└── subdirectory/
    ├── file3.pdf (QmHash3...)
    └── file4.mp4 (QmHash4...)

Ejemplos prácticos: Trabajando con CIDs

Exploremos cómo trabajar con CIDs en la práctica utilizando 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

Fijar contenido existente por CID

Si ya tienes un CID, puedes fijarlo para garantizar la disponibilidad:

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 mediante diferentes 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;
};

Mejores prácticas de CID para desarrolladores

1. Valida siempre 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 tanto con CIDv0 como 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. Cachea los mapeos de CID

Si generas CIDs frecuentemente, considera la caché:

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 completos en IPFS y referénciales 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 saber más sobre el despliegue de sitios web, mira nuestra guía sobre cómo subir archivos a IPFS.

2. Almacenamiento de metadatos NFT

Almacena metadatos NFT de forma inmutable 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 };
};

Comprendiendo el pinning de IPFS con CIDs

Los CIDs son temporales por defecto — deben ser «fijados» para permanecer 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 de IPFS, considera leer nuestra comparación IPFS Ninja vs Pinata o explora nuestro resumen de los mejores servicios de pinning de IPFS disponibles hoy.

Crea tu primer CID en 30 segundos

¿Listo para generar tu primer CID? Aquí tienes 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, mira nuestro tutorial de API de subida IPFS.

Conclusión

Los CIDs son la base del sistema de direccionamiento de contenido de IPFS, proporcionando identificación de contenido inmutable, verificable y descentralizada. Comprender 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 el contenido de forma única, no ubicaciones
  • CIDv0 proporciona compatibilidad máxima, CIDv1 ofrece flexibilidad
  • El direccionamiento de contenido permite la verificación y la deduplicación
  • El manejo adecuado de CID es crucial para aplicaciones de producción

Ya sea que estés almacenando metadatos NFT, desplegando sitios web descentralizados o construyendo sistemas de distribución de contenido, los CIDs proporcionan la base fiable que necesitas para aplicaciones verdaderamente descentralizadas.

¿Listo para empezar a hacer pinning? Crea una cuenta gratuita — 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 »