· Nacho Coll · Guides  · 9 min de leitura

CID do IPFS explicado: o que é e como funciona o endereçamento por conteúdo

Explicação técnica clara dos Content Identifiers (CIDs) do IPFS. Como funciona o endereçamento por conteúdo, versões de CID e como criar seu primeiro CID.

Explicação técnica clara dos Content Identifiers (CIDs) do IPFS. Como funciona o endereçamento por conteúdo, versões de CID e como criar seu primeiro CID.

Se você já trabalhou com IPFS (InterPlanetary File System), provavelmente já se deparou com strings como QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG ou bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi. Isso não é uma sequência aleatória — são Content Identifiers (CIDs), a espinha dorsal do sistema de endereçamento por conteúdo do IPFS.

Entender CIDs é crucial para quem está construindo sobre IPFS, seja fazendo upload de arquivos, construindo aplicações descentralizadas ou implementando sistemas de distribuição de conteúdo. Este guia vai destrinchar tudo o que você precisa saber sobre CIDs do IPFS, como o endereçamento por conteúdo funciona e como começar a usá-los nos seus projetos.

IPFS Ninja

O que é um CID do IPFS?

Um Content Identifier (CID) é uma impressão digital única que representa um pedaço de conteúdo no IPFS. Diferente das URLs web tradicionais que apontam para uma localização (como https://example.com/file.pdf), CIDs apontam para o conteúdo em si, independente de onde ele esteja armazenado.

Pensa assim:

  • Endereçamento por localização: “Vá até a Rua Principal, 123 e peça o livro vermelho”
  • Endereçamento por conteúdo: “Encontre o livro com ISBN 978-0-123456-78-9” (não importa qual biblioteca tenha)

CIDs funcionam de forma similar — eles identificam o conteúdo pelo seu hash criptográfico, tornando o conteúdo imutável e verificável. Se um único byte mudar no arquivo, o CID muda completamente.

Por que endereçamento por conteúdo importa

A arquitetura web tradicional depende de endereçamento por localização. Quando você visita https://example.com/image.jpg, você está confiando que:

  1. O dono do domínio não mudou o conteúdo
  2. O servidor está online e acessível
  3. O conteúdo não foi adulterado

Com endereçamento por conteúdo usando CIDs:

  1. Imutabilidade: O CID garante que o conteúdo não mudou
  2. Descentralização: O conteúdo pode ser obtido de qualquer nó IPFS que o tenha
  3. Verificação: Você pode verificar criptograficamente que recebeu o conteúdo correto
  4. Eficiência: Conteúdo idêntico é deduplicado automaticamente

Anatomia de um CID

Vamos dissecar um CID típico pra entender seus componentes:

bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi
└─┬─┘└─────────────────┬─────────────────────────────────┘
  │                   │
  │                   └─ Hash do Conteúdo (codificado em Base32)
  └─ Prefixo Multibase (indica codificação)

Um CID contém várias informações:

1. Prefixo Multibase

O primeiro caractere indica como o CID está codificado:

  • Q = Codificação Base58 (CIDv0)
  • b = Codificação Base32 (CIDv1)
  • f = Base16/hexadecimal (CIDv1)
  • z = Base58 (CIDv1)

2. Versão do CID

  • CIDv0: Sempre começa com Qm, usa SHA-256, limitado ao codec DAG-PB
  • CIDv1: Mais flexível, suporta múltiplas funções de hash e codecs

3. Multicodec

Especifica como o conteúdo está estruturado (DAG-PB, DAG-CBOR, bytes brutos, etc.)

4. Multihash

O hash criptográfico real do conteúdo, incluindo:

  • Identificador da função de hash (geralmente SHA-256)
  • Comprimento do hash
  • O digest do hash

CIDv0 vs CIDv1: Entendendo as diferenças

O IPFS evoluiu através de duas versões principais de CID, cada uma com características distintas:

CIDv0: O formato original

CIDs CIDv0 sempre começam com Qm e ficam assim:

QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG

Características:

  • Apenas codificação Base58
  • Apenas função de hash SHA-256
  • Apenas codec DAG-PB (Protobuf)
  • 46 caracteres de comprimento
  • Retrocompatível com todas as implementações de IPFS

Quando usar CIDv0:

  • Compatibilidade máxima com nós IPFS mais antigos
  • Trabalhar com sistemas existentes que esperam prefixos Qm
  • Armazenamento de arquivos (caso de uso mais comum)

CIDv1: O padrão moderno

CIDs CIDv1 são mais flexíveis e podem ficar assim:

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

Características:

  • Múltiplos formatos de codificação (Base32, Base58, Base16)
  • Suporte a diferentes funções de hash (SHA-256, SHA-512, BLAKE2, etc.)
  • Múltiplos codecs (Raw, DAG-CBOR, DAG-JSON, etc.)
  • Formato auto-descritivo
  • Não diferencia maiúsculas/minúsculas quando usa Base32

Quando usar CIDv1:

  • Construir novas aplicações
  • Precisar de identificadores que não diferenciem maiúsculas/minúsculas
  • Trabalhar com dados estruturados (JSON, CBOR)
  • Usar funções de hash alternativas

Convertendo entre versões

Você pode converter CIDs entre versões mantendo a mesma referência de conteúdo:

// CIDv0
const cidv0 = "QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG";

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

// Both reference the same content!

Como funciona o endereçamento por conteúdo

O endereçamento por conteúdo no IPFS segue um processo determinístico que garante que o mesmo conteúdo sempre produz o mesmo CID:

1. Preparação do conteúdo

Quando você adiciona conteúdo ao IPFS, ele é primeiro decomposto:

  • Arquivos pequenos: Armazenados como blocos únicos
  • Arquivos grandes: Divididos em chunks e organizados num Merkle DAG (Directed Acyclic Graph)
  • Diretórios: Representados como estruturas DAG ligando para arquivos

2. Processo de hashing

Cada pedaço de conteúdo passa por:

  1. Serialização: Conteúdo é formatado de acordo com seu codec
  2. Hashing: Função de hash criptográfico processa os dados serializados
  3. Criação do Multihash: Hash é envelopado com informações de algoritmo e comprimento
  4. Montagem do CID: Versão, codec e multihash são combinados

3. Estrutura Merkle DAG

O IPFS organiza conteúdo num Merkle DAG onde:

  • Cada nó tem um CID
  • Nós pais referenciam nós filhos por CID
  • Mudanças em qualquer nó propagam pela árvore
  • Estruturas inteiras podem ser verificadas criptograficamente
Root CID: bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi
├── file1.txt (QmHash1...)
├── file2.jpg (QmHash2...)
└── subdirectory/
    ├── file3.pdf (QmHash3...)
    └── file4.mp4 (QmHash4...)

Exemplos práticos: Trabalhando com CIDs

Vamos explorar como trabalhar com CIDs na prática usando a API do IPFS Ninja:

Subindo conteúdo e pegando um 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

Pinando conteúdo existente por CID

Se você já tem um CID, pode pinar pra garantir que ele continua disponível:

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

Acessando conteúdo via CID

Uma vez que você tem um CID, pode acessar o conteúdo por vários 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;
};

Boas práticas de CID pra desenvolvedores

1. Sempre valide CIDs

Antes de usar um CID na sua aplicação, valide seu 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. Lide com ambas versões de CID

Sua aplicação deve funcionar com CIDv0 e 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. Cacheie mapeamentos de CID

Se você gera CIDs com frequência, considere fazer 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. Use descrições significativas

Ao subir conteúdo, inclua metadados descritivos:

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 comuns de CID

1. Deploy de site estático

Faça deploy de sites inteiros pro IPFS e referencie 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;
};

Pra saber mais sobre deploy de sites, dá uma olhada no nosso guia sobre como subir arquivos pro IPFS.

2. Armazenamento de metadados NFT

Armazene metadados NFT de forma imutável 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. Distribuição de conteúdo

Use CIDs pra entrega de conteúdo distribuída:

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

Entendendo IPFS pinning com CIDs

CIDs são temporários por padrão — precisam ser “pinados” pra continuarem disponíveis. Saiba mais sobre esse conceito crucial no nosso guia completo sobre o que é IPFS pinning.

Ao escolher um serviço de pinning IPFS, considere ler nossa comparação IPFS Ninja vs Pinata ou explore nosso resumo dos melhores serviços de pinning IPFS disponíveis hoje.

Crie seu primeiro CID em 30 segundos

Pronto pra gerar seu primeiro CID? Aqui um exemplo rápido usando a API do 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();

Isso vai retornar algo como:

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

Para exemplos de API mais detalhados, veja nosso tutorial da API de upload IPFS.

Conclusão

CIDs são a fundação do sistema de endereçamento por conteúdo do IPFS, fornecendo identificação de conteúdo imutável, verificável e descentralizada. Entender como eles funcionam — dos detalhes técnicos de CIDv0 vs CIDv1 aos padrões práticos de implementação — é essencial pra construir aplicações descentralizadas robustas.

Pontos principais:

  • CIDs identificam conteúdo de forma única, não localizações
  • CIDv0 oferece compatibilidade máxima, CIDv1 oferece flexibilidade
  • Endereçamento por conteúdo permite verificação e deduplicação
  • Manejo adequado de CID é crucial pra aplicações de produção

Seja você armazenando metadados NFT, fazendo deploy de sites descentralizados ou construindo sistemas de distribuição de conteúdo, CIDs fornecem a fundação confiável que você precisa pra aplicações verdadeiramente descentralizadas.

Pronto pra começar a pinar? Crie uma conta grátis — 50 arquivos, 1 GB de armazenamento, 2 GB de banda/mês. Sem cartão de crédito.

Share:
Voltar ao Blog

Artigos Relacionados

Ver Todos os Artigos »