CID-uri IPFS 2026: Ghid de adresare pe conținut

Dacă ai lucrat vreodată cu IPFS (InterPlanetary File System), probabil ai întâlnit șiruri precum QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG sau bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi. Acestea nu sunt aiureli aleatorii — sunt Content Identifiers (CIDs), coloana vertebrală a sistemului de adresare a conținutului IPFS.

Înțelegerea CIDs este crucială pentru oricine construiește pe IPFS, indiferent dacă încarci fișiere, construiești aplicații descentralizate sau implementezi sisteme de distribuție a conținutului. Acest ghid va descompune tot ce trebuie să știi despre IPFS CIDs, cum funcționează adresarea conținutului și cum să începi să le folosești în proiectele tale.

Generați un CID în 5 linii (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

Acest CID este reproductibil de oricine — rulează din nou cu aceiași octeți oriunde pe Pământ și obții același șir de caractere. Aceasta este adresarea pe conținut.

Echivalentul în 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...

Ce este un IPFS CID?#

Un Content Identifier (CID) este o amprentă unică care reprezintă o bucată de conținut pe IPFS. Spre deosebire de URL-urile web tradiționale care indică o locație (cum ar fi https://example.com/file.pdf), CIDs indică conținutul în sine, indiferent unde este stocat.

Gândește-te așa:

Adresare bazată pe locație: „Mergi la Strada Principală 123 și cere cartea roșie”
Adresare bazată pe conținut: „Găsește cartea cu ISBN 978-0-123456-78-9” (nu contează ce bibliotecă o are)

CIDs funcționează similar — identifică conținutul pe baza hash-ului său criptografic, făcând conținutul imuabil și verificabil. Dacă un singur byte se schimbă în fișier, CID-ul se schimbă complet.

De ce contează adresarea conținutului#

Arhitectura web tradițională se bazează pe adresarea bazată pe locație. Când vizitezi https://example.com/image.jpg, te bazezi pe faptul că:

Proprietarul domeniului nu a schimbat conținutul
Serverul este online și accesibil
Conținutul nu a fost manipulat

Cu adresarea conținutului folosind CIDs:

Imutabilitate: CID-ul garantează că conținutul nu s-a schimbat
Descentralizare: Conținutul poate fi obținut de la orice nod IPFS care îl are
Verificare: Poți verifica criptografic că ai primit conținutul corect
Eficiență: Conținutul identic este deduplicat automat

Anatomia unui CID#

Să descompunem un CID tipic pentru a-i înțelege componentele:

bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi
└─┬─┘└─────────────────┬─────────────────────────────────┘
  │                   │
  │                   └─ Hash de conținut (codificat Base32)
  └─ Prefix Multibase (indică codificarea)

Un CID conține mai multe informații:

1. Prefix Multibase#

Primul caracter indică modul în care CID-ul este codificat:

Q = Codificare Base58 (CIDv0)
b = Codificare Base32 (CIDv1)
f = Base16/hexazecimal (CIDv1)
z = Base58 (CIDv1)

2. Versiunea CID#

CIDv0: Începe întotdeauna cu Qm, folosește SHA-256, limitat la codec-ul DAG-PB
CIDv1: Mai flexibil, suportă mai multe funcții hash și codecuri

3. Multicodec#

Specifică modul în care conținutul este structurat (DAG-PB, DAG-CBOR, octeți bruți etc.)

4. Multihash#

Hash-ul criptografic real al conținutului, inclusiv:

Identificatorul funcției hash (de obicei SHA-256)
Lungimea hash-ului
Digest-ul hash-ului

CIDv0 vs CIDv1: Înțelegerea diferențelor#

IPFS a evoluat prin două versiuni majore de CID, fiecare cu caracteristici distincte:

CIDv0: Formatul original#

CIDs CIDv0 încep întotdeauna cu Qm și arată astfel:

QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG

Caracteristici:

Doar codificare Base58
Doar funcție hash SHA-256
Doar codec DAG-PB (Protobuf)
46 de caractere lungime
Compatibil cu toate implementările IPFS

Când să folosești CIDv0:

Compatibilitate maximă cu noduri IPFS mai vechi
Lucrul cu sisteme existente care așteaptă prefixe Qm
Stocarea fișierelor (cel mai comun caz de utilizare)

CIDv1: Standardul modern#

CIDs CIDv1 sunt mai flexibile și pot arăta astfel:

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

Caracteristici:

Mai multe formate de codificare (Base32, Base58, Base16)
Suport pentru diferite funcții hash (SHA-256, SHA-512, BLAKE2 etc.)
Mai multe codecuri (Raw, DAG-CBOR, DAG-JSON etc.)
Format auto-descriptiv
Insensibil la majuscule și minuscule la utilizarea Base32

Când să folosești CIDv1:

Construirea de noi aplicații
Necesitatea de identificatori insensibili la majuscule
Lucrul cu date structurate (JSON, CBOR)
Folosirea funcțiilor hash alternative

Conversia între versiuni#

Poți converti CIDs între versiuni menținând aceeași referință de conținut:

// CIDv0
const cidv0 = "QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG";

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

// Both reference the same content!

Cum funcționează adresarea conținutului#

Adresarea conținutului în IPFS urmează un proces determinist care asigură că același conținut produce întotdeauna același CID:

1. Pregătirea conținutului#

Când adaugi conținut în IPFS, este mai întâi descompus:

Fișiere mici: Stocate ca blocuri unice
Fișiere mari: Împărțite în bucăți și organizate într-un Merkle DAG (graf aciclic direcționat)
Directoare: Reprezentate ca structuri DAG care leagă către fișiere

2. Procesul de hashing#

Fiecare bucată de conținut trece prin:

Serializare: Conținutul este formatat conform codec-ului său
Hashing: Funcția hash criptografică procesează datele serializate
Creare Multihash: Hash-ul este împachetat cu informații despre algoritm și lungime
Asamblare CID: Versiunea, codec-ul și multihash-ul sunt combinate

3. Structura Merkle DAG#

IPFS organizează conținutul într-un Merkle DAG unde:

Fiecare nod are un CID
Nodurile părinte referențiază nodurile copil prin CID
Schimbările în orice nod se propagă în sus în arbore
Structuri întregi pot fi verificate criptografic

Root CID: bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi
├── file1.txt (QmHash1...)
├── file2.jpg (QmHash2...)
└── subdirectory/
    ├── file3.pdf (QmHash3...)
    └── file4.mp4 (QmHash4...)

Exemple practice: Lucrul cu CIDs#

Să explorăm cum să lucrăm cu CIDs în practică folosind API-ul IPFS Ninja:

Încărcarea conținutului și obținerea unui 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

Fixarea conținutului existent prin CID#

Dacă ai deja un CID, îl poți fixa pentru a asigura disponibilitatea:

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

Accesarea conținutului prin CID#

Odată ce ai un CID, poți accesa conținutul prin diferite metode:

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

Cele mai bune practici CID pentru dezvoltatori#

1. Validează întotdeauna CIDs#

Înainte de a folosi un CID în aplicația ta, validează formatul:

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. Gestionează ambele versiuni de CID#

Aplicația ta ar trebui să funcționeze atât cu CIDv0, cât și cu 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. Cache-uiește mapările CID#

Dacă generezi CIDs frecvent, ia în considerare cache-ul:

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. Folosește descrieri semnificative#

Când încarci conținut, include metadate descriptive:

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

Cazuri comune de utilizare CID#

1. Implementarea site-urilor statice#

Implementează site-uri întregi pe IPFS și referențiază-le prin 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;
};

Pentru a afla mai multe despre implementarea site-urilor, vezi ghidul nostru despre cum să încarci fișiere pe IPFS.

2. Stocarea metadatelor NFT#

Stochează metadate NFT în mod imuabil folosind 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. Distribuția conținutului#

Folosește CIDs pentru livrarea distribuită a conținutului:

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

Înțelegerea pinning-ului IPFS cu CIDs#

CIDs sunt temporare implicit — trebuie „fixate” pentru a rămâne disponibile. Află mai multe despre acest concept crucial în ghidul nostru cuprinzător despre ce este pinning-ul IPFS.

Când alegi un serviciu de pinning IPFS, ia în considerare să citești comparația noastră IPFS Ninja vs Pinata sau explorează prezentarea noastră a celor mai bune servicii de pinning IPFS disponibile astăzi.

Creează primul tău CID în 30 de secunde#

Ești gata să-ți generezi primul CID? Iată un exemplu rapid folosind API-ul 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();

Aceasta va returna ceva de genul:

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

Pentru exemple API mai detaliate, vezi tutorialul nostru API de încărcare IPFS.

Concluzie#

CIDs sunt fundamentul sistemului de adresare a conținutului IPFS, oferind identificare imuabilă, verificabilă și descentralizată a conținutului. Înțelegerea modului în care funcționează — de la detaliile tehnice ale CIDv0 vs CIDv1 la modelele practice de implementare — este esențială pentru construirea aplicațiilor descentralizate robuste.

Concluzii cheie:

CIDs identifică conținutul în mod unic, nu locațiile
CIDv0 oferă compatibilitate maximă, CIDv1 oferă flexibilitate
Adresarea conținutului permite verificarea și deduplicarea
Manipularea corectă a CID este crucială pentru aplicațiile de producție

Indiferent dacă stochezi metadate NFT, implementezi site-uri descentralizate sau construiești sisteme de distribuție a conținutului, CIDs oferă fundația de încredere de care ai nevoie pentru aplicații cu adevărat descentralizate.

Ești gata să începi să fixezi? Creează un cont gratuit — 50 de fișiere, 1 GB stocare, 2 GB lățime de bandă/lună. Fără card de credit.