CIDs IPFS 2026: Guia de Endereçamento por Conteúdo

Guia prático dos CIDs IPFS: CIDv0 vs CIDv1, endereçamento de conteúdo, geração de CIDs em Node.js e Python, verificação de integridade. Atualizado para 2026.

Nacho Collpor Atualizado: 11 min de leitura
Guia prático dos CIDs IPFS: CIDv0 vs CIDv1, endereçamento de conteúdo, geração de CIDs em Node.js e Python, verificação de integridade. Atualizado para 2026.
TL;DR
  • Gere um CID reprodutível a partir dos bytes de qualquer ficheiro — o mesmo conteúdo produz sempre o mesmo hash.
  • Utilize CIDv1 para novos uploads: é Base32, em minúsculas, e funciona com gateways de subdomínio; o CIDv0 não funciona.
  • Um único byte alterado num ficheiro muda completamente o seu CID, tornando a adulteração imediatamente detetável.
  • O endereçamento por conteúdo significa que os ficheiros são identificados pelo que são, não por onde estão alojados.

Se alguma vez trabalhou com IPFS (InterPlanetary File System), provavelmente encontrou cadeias de caracteres como QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG ou bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi. Não são disparates aleatórios — são Content Identifiers (CIDs), a espinha dorsal do sistema de endereçamento de conteúdo do IPFS.

Compreender os CIDs é crucial para qualquer pessoa que construa em IPFS, quer esteja a carregar ficheiros, a construir aplicações descentralizadas ou a implementar sistemas de distribuição de conteúdo. Este guia irá explicar tudo o que precisa de saber sobre os CIDs do IPFS, como funciona o endereçamento de conteúdo e como começar a utilizá-los nos seus projetos.

Gere um CID em 5 Linhas (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

Esse CID é reprodutível por qualquer pessoa — execute novamente com os mesmos bytes em qualquer lugar do planeta e obtenha a mesma cadeia de caracteres. Isto é o endereçamento de conteúdo.

Equivalente em 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...
IPFS Ninja

O que é um IPFS CID?#

Um Content Identifier (CID) é uma impressão digital única que representa um pedaço de conteúdo no IPFS. Ao contrário dos URLs web tradicionais que apontam para uma localização (como https://example.com/file.pdf), os CIDs apontam para o próprio conteúdo, independentemente de onde esteja armazenado.

Pense nisto assim:

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

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

Por que o endereçamento de conteúdo importa#

A arquitetura web tradicional depende do endereçamento baseado em localização. Quando visita https://example.com/image.jpg, confia que:

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

Com endereçamento de conteúdo usando CIDs:

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

Anatomia de um CID#

Vamos analisar um CID típico para compreender os seus componentes:

bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi
└─┬─┘└─────────────────┬─────────────────────────────────┘
  │                   │
  │                   └─ Hash de Conteúdo (codificado 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 CID#

  • CIDv0: Começa sempre com Qm, usa SHA-256, limitado ao codec DAG-PB
  • CIDv1: Mais flexível, suporta múltiplas funções 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 hash (geralmente SHA-256)
  • Comprimento do hash
  • O digest do hash

CIDv0 vs CIDv1: Compreendendo 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 começam sempre com Qm e têm este aspeto:

QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG

Características:

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

Quando usar CIDv0:

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

CIDv1: O padrão moderno#

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

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

Características:

  • Múltiplos formatos de codificação (Base32, Base58, Base16)
  • Suporte para diferentes funções hash (SHA-256, SHA-512, BLAKE2, etc.)
  • Múltiplos codecs (Raw, DAG-CBOR, DAG-JSON, etc.)
  • Formato auto-descritivo
  • Insensível a maiúsculas ao usar Base32

Quando usar CIDv1:

  • Construir novas aplicações
  • Necessitar de identificadores insensíveis a maiúsculas
  • Trabalhar com dados estruturados (JSON, CBOR)
  • Usar funções hash alternativas

Conversão entre versões#

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 de conteúdo#

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

1. Preparação do conteúdo#

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

  • Ficheiros pequenos: Armazenados como blocos únicos
  • Ficheiros grandes: Divididos em pedaços e organizados num Merkle DAG (grafo acíclico direcionado)
  • Diretórios: Representados como estruturas DAG que ligam a ficheiros

2. Processo de hashing#

Cada peça de conteúdo passa por:

  1. Serialização: O conteúdo é formatado de acordo com o seu codec
  2. Hashing: A função hash criptográfica processa os dados serializados
  3. Criação do Multihash: O hash é embrulhado com informações de algoritmo e comprimento
  4. Montagem do CID: A versão, o codec e o 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 via CID
  • As alterações em qualquer nó propagam-se para cima na á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: Trabalhar com CIDs#

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

Carregar conteúdo e obter 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

Fixar conteúdo existente por CID#

Se já tem um CID, pode fixá-lo para garantir disponibilidade:

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

Aceder ao conteúdo via CID#

Assim que tem um CID, pode aceder ao conteúdo através de 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;
};

Melhores práticas de CID para programadores#

1. Valide sempre os CIDs#

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

A 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. Coloque em cache os mapeamentos CID#

Se gera CIDs frequentemente, considere caching:

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 carregar 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. Implementação de website estático#

Implemente websites inteiros no IPFS e referencie-os 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 mais sobre implementação de websites, veja o nosso guia sobre como carregar ficheiros para o 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 para 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 };
};

Compreender o pinning de IPFS com CIDs#

Os CIDs são temporários por defeito — devem ser “fixados” para permanecerem disponíveis. Saiba mais sobre este conceito crucial no nosso guia abrangente sobre o que é o pinning de IPFS.

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

Crie o seu primeiro CID em 30 segundos#

Pronto para gerar o seu primeiro CID? Aqui está 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();

Isto irá 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 o nosso tutorial da API de upload IPFS.

Conclusão#

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

Pontos-chave:

  • Os CIDs identificam conteúdo de forma única, não localizações
  • CIDv0 fornece compatibilidade máxima, CIDv1 oferece flexibilidade
  • O endereçamento de conteúdo permite verificação e deduplicação
  • Manuseamento adequado de CID é crucial para aplicações de produção

Quer esteja a armazenar metadados NFT, a implementar websites descentralizados, ou a construir sistemas de distribuição de conteúdo, os CIDs fornecem a base fiável que precisa para aplicações verdadeiramente descentralizadas.

Pronto para começar a fazer pinning? Crie uma conta gratuita — 50 ficheiros, 1 GB de armazenamento, 2 GB de largura de banda/mês. Sem cartão de crédito.

Nacho Coll

Sobre o autor

Founder & Engineer at IPFS.NINJA

Nacho founded IPFS.NINJA to make content-addressed storage feel as simple as an S3 PUT — a single API call, a permanent CID, no wallets or peer discovery to reason about. Writes about IPFS internals, decentralized storage patterns, and the pinning-service landscape from the operator side of the wire.

Voltar ao Blog

Artigos Relacionados

Desempenho IPFS: Acelere a Recuperação com Gateway Dedicado
Guides

Desempenho IPFS: Acelere a Recuperação com Gateway Dedicado

29/06/20267min de leitura
Tokens de Upload IPFS: Uploads Seguros do Cliente
Guides

Tokens de Upload IPFS: Uploads Seguros do Cliente

6/04/202616min de leitura
Armazenamento de Metadados NFT: Guia IPFS para Criadores
Guides

Armazenamento de Metadados NFT: Guia IPFS para Criadores

30/03/202610min de leitura