· Nacho Coll · Guides  · 9 min de leitura

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

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

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

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.

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.

Share:
Voltar ao Blog

Artigos Relacionados

Ver Todos os Artigos »