· Nacho Coll · Guides  · 8 min leestijd

IPFS CID uitgelegd: wat het is en hoe content-adressering werkt

Heldere technische uitleg van IPFS Content Identifiers (CIDs). Hoe content-adressering werkt, CID-versies en hoe je je eerste CID maakt.

Heldere technische uitleg van IPFS Content Identifiers (CIDs). Hoe content-adressering werkt, CID-versies en hoe je je eerste CID maakt.

Als je ooit met IPFS (InterPlanetary File System) hebt gewerkt, ben je waarschijnlijk strings tegengekomen zoals QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG of bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi. Dit zijn geen willekeurige reeksen — het zijn Content Identifiers (CIDs), de ruggengraat van het content-adresseringssysteem van IPFS.

CIDs begrijpen is cruciaal voor iedereen die op IPFS bouwt — of je nu bestanden uploadt, gedecentraliseerde applicaties bouwt of content-distributiesystemen implementeert. Deze gids legt alles uit wat je moet weten over IPFS CIDs, hoe content-adressering werkt en hoe je ermee aan de slag gaat in je projecten.

IPFS Ninja

Wat is een IPFS CID?

Een Content Identifier (CID) is een unieke vingerafdruk die een stuk content op IPFS vertegenwoordigt. In tegenstelling tot traditionele web-URL’s die naar een locatie wijzen (zoals https://example.com/file.pdf), wijzen CIDs naar de content zelf, ongeacht waar deze is opgeslagen.

Zie het zo:

  • Locatie-gebaseerde adressering: “Ga naar Hoofdstraat 123 en vraag om het rode boek”
  • Content-gebaseerde adressering: “Vind het boek met ISBN 978-0-123456-78-9” (welke bibliotheek het heeft maakt niet uit)

CIDs werken vergelijkbaar — ze identificeren content op basis van zijn cryptografische hash, waardoor de content onveranderlijk en verifieerbaar wordt. Als één enkele byte in het bestand verandert, verandert de CID volledig.

Waarom content-adressering belangrijk is

De traditionele webarchitectuur vertrouwt op locatie-gebaseerde adressering. Wanneer je https://example.com/image.jpg bezoekt, vertrouw je erop dat:

  1. De domeineigenaar de content niet heeft gewijzigd
  2. De server online en toegankelijk is
  3. De content niet is gemanipuleerd

Met content-adressering via CIDs:

  1. Onveranderlijkheid: De CID garandeert dat de content niet is gewijzigd
  2. Decentralisatie: Content kan opgehaald worden van elke IPFS-node die het heeft
  3. Verificatie: Je kunt cryptografisch verifiëren dat je de juiste content hebt ontvangen
  4. Efficiëntie: Identieke content wordt automatisch gededupliceerd

Anatomie van een CID

Laten we een typische CID ontleden om de componenten te begrijpen:

bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi
└─┬─┘└─────────────────┬─────────────────────────────────┘
  │                   │
  │                   └─ Content Hash (Base32 gecodeerd)
  └─ Multibase prefix (geeft codering aan)

Een CID bevat verschillende stukjes informatie:

1. Multibase prefix

Het eerste teken geeft aan hoe de CID is gecodeerd:

  • Q = Base58-codering (CIDv0)
  • b = Base32-codering (CIDv1)
  • f = Base16/hexadecimaal (CIDv1)
  • z = Base58 (CIDv1)

2. CID-versie

  • CIDv0: Begint altijd met Qm, gebruikt SHA-256, beperkt tot DAG-PB codec
  • CIDv1: Flexibeler, ondersteunt meerdere hashfuncties en codecs

3. Multicodec

Specificeert hoe de content is gestructureerd (DAG-PB, DAG-CBOR, ruwe bytes, enz.)

4. Multihash

De daadwerkelijke cryptografische hash van de content, inclusief:

  • Hashfunctie-identifier (gewoonlijk SHA-256)
  • Hashlengte
  • De hash-digest

CIDv0 vs CIDv1: De verschillen begrijpen

IPFS heeft twee hoofdversies van CIDs doorlopen, elk met onderscheidende kenmerken:

CIDv0: Het oorspronkelijke formaat

CIDv0 CIDs beginnen altijd met Qm en zien er zo uit:

QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG

Kenmerken:

  • Alleen Base58-codering
  • Alleen SHA-256 hashfunctie
  • Alleen DAG-PB (Protobuf) codec
  • 46 tekens lang
  • Backwards compatibel met alle IPFS-implementaties

Wanneer CIDv0 te gebruiken:

  • Maximale compatibiliteit met oudere IPFS-nodes
  • Werken met bestaande systemen die Qm-prefixes verwachten
  • Bestandsopslag (meest voorkomende gebruikssituatie)

CIDv1: De moderne standaard

CIDv1 CIDs zijn flexibeler en kunnen er zo uitzien:

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

Kenmerken:

  • Meerdere codeerformaten (Base32, Base58, Base16)
  • Ondersteuning voor verschillende hashfuncties (SHA-256, SHA-512, BLAKE2, enz.)
  • Meerdere codecs (Raw, DAG-CBOR, DAG-JSON, enz.)
  • Zelfbeschrijvend formaat
  • Niet hoofdlettergevoelig bij Base32

Wanneer CIDv1 te gebruiken:

  • Nieuwe applicaties bouwen
  • Hoofdletter-ongevoelige identifiers nodig hebben
  • Werken met gestructureerde data (JSON, CBOR)
  • Alternatieve hashfuncties gebruiken

Converteren tussen versies

Je kunt CIDs converteren tussen versies terwijl dezelfde contentreferentie behouden blijft:

// CIDv0
const cidv0 = "QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG";

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

// Both reference the same content!

Hoe content-adressering werkt

Content-adressering in IPFS volgt een deterministisch proces dat ervoor zorgt dat dezelfde content altijd dezelfde CID oplevert:

1. Content-voorbereiding

Wanneer je content aan IPFS toevoegt, wordt deze eerst opgebroken:

  • Kleine bestanden: Opgeslagen als enkele blokken
  • Grote bestanden: Verdeeld in chunks en georganiseerd in een Merkle DAG (Directed Acyclic Graph)
  • Directories: Weergegeven als DAG-structuren die naar bestanden linken

2. Hashing-proces

Elk stuk content doorloopt:

  1. Serialisatie: Content wordt geformatteerd volgens zijn codec
  2. Hashing: Cryptografische hashfunctie verwerkt de geserialiseerde data
  3. Multihash-creatie: Hash wordt verpakt met algoritme- en lengtinformatie
  4. CID-assemblage: Versie, codec en multihash worden gecombineerd

3. Merkle DAG-structuur

IPFS organiseert content in een Merkle DAG waar:

  • Elke node een CID heeft
  • Bovenliggende nodes verwijzen naar onderliggende nodes via CID
  • Wijzigingen in elke node door de boom propageren
  • Hele structuren cryptografisch verifieerbaar zijn
Root CID: bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi
├── file1.txt (QmHash1...)
├── file2.jpg (QmHash2...)
└── subdirectory/
    ├── file3.pdf (QmHash3...)
    └── file4.mp4 (QmHash4...)

Praktische voorbeelden: Werken met CIDs

Laten we verkennen hoe je in de praktijk met CIDs werkt met de IPFS Ninja API:

Content uploaden en een CID krijgen

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

Bestaande content pinnen op CID

Als je al een CID hebt, kun je deze pinnen om beschikbaarheid te garanderen:

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

Content benaderen via CID

Zodra je een CID hebt, kun je de content op verschillende manieren benaderen:

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

CID-best practices voor ontwikkelaars

1. Valideer CIDs altijd

Voordat je een CID in je applicatie gebruikt, valideer het formaat:

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. Ondersteun beide CID-versies

Je applicatie moet zowel met CIDv0 als CIDv1 werken:

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. Cache CID-mappings

Als je vaak CIDs genereert, overweeg 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. Gebruik betekenisvolle beschrijvingen

Bij het uploaden van content, voeg beschrijvende metadata toe:

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

Veelvoorkomende CID-gebruiksgevallen

1. Statische website-deployment

Deploy hele websites naar IPFS en verwijs er via CID naar:

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

Lees meer over website-deployment in onze gids over hoe je bestanden uploadt naar IPFS.

2. NFT-metadata-opslag

Sla NFT-metadata onveranderlijk op met 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. Contentdistributie

Gebruik CIDs voor gedistribueerde contentlevering:

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

IPFS-pinning begrijpen met CIDs

CIDs zijn standaard tijdelijk — ze moeten “gepind” worden om beschikbaar te blijven. Leer meer over dit cruciale concept in onze uitgebreide gids over wat IPFS-pinning is.

Bij het kiezen van een IPFS-pinningservice, overweeg om onze IPFS Ninja vs Pinata vergelijking te lezen of verken ons overzicht van de beste IPFS-pinningservices die vandaag beschikbaar zijn.

Maak je eerste CID in 30 seconden

Klaar om je eerste CID te genereren? Hier is een snel voorbeeld met de IPFS Ninja API:

# 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();

Dit zal iets als dit teruggeven:

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

Voor meer gedetailleerde API-voorbeelden, zie onze IPFS-upload API-tutorial.

Conclusie

CIDs vormen het fundament van het content-adresseringssysteem van IPFS en bieden onveranderlijke, verifieerbare en gedecentraliseerde content-identificatie. Begrijpen hoe ze werken — van de technische details van CIDv0 vs CIDv1 tot praktische implementatiepatronen — is essentieel voor het bouwen van robuuste gedecentraliseerde applicaties.

Belangrijkste leerpunten:

  • CIDs identificeren content uniek, niet locaties
  • CIDv0 biedt maximale compatibiliteit, CIDv1 biedt flexibiliteit
  • Content-adressering maakt verificatie mogelijk en deduplicatie
  • Goede CID-afhandeling is cruciaal voor productie-applicaties

Of je nu NFT-metadata opslaat, gedecentraliseerde websites deployt of content-distributiesystemen bouwt, CIDs bieden de betrouwbare basis die je nodig hebt voor echt gedecentraliseerde applicaties.

Klaar om te beginnen met pinnen? Maak een gratis account aan — 50 bestanden, 1 GB opslag, 2 GB bandbreedte/maand. Geen creditcard vereist.

Share:
Terug naar Blog

Gerelateerde Artikelen

Alle Artikelen Bekijken »