· Nacho Coll · Guides  · 8 min čitanja

IPFS CID objašnjen: što je to i kako funkcionira sadržajno adresiranje

Jasno tehničko objašnjenje IPFS Content Identifiera (CIDs). Kako funkcionira sadržajno adresiranje, CID verzije i kako stvoriti svoj prvi CID.

Jasno tehničko objašnjenje IPFS Content Identifiera (CIDs). Kako funkcionira sadržajno adresiranje, CID verzije i kako stvoriti svoj prvi CID.

Ako ste ikada radili s IPFS-om (InterPlanetary File System), vjerojatno ste naišli na nizove poput QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG ili bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi. Ovo nisu nasumične besmislice — to su Content Identifieri (CIDs), okosnica sustava sadržajnog adresiranja IPFS-a.

Razumijevanje CIDs-a ključno je za svakoga tko gradi na IPFS-u, bilo da prenosite datoteke, gradite decentralizirane aplikacije ili implementirate sustave distribucije sadržaja. Ovaj vodič razložit će sve što trebate znati o IPFS CIDs-ima, kako funkcionira sadržajno adresiranje i kako početi koristiti ih u svojim projektima.

IPFS Ninja

Što je IPFS CID?

Content Identifier (CID) je jedinstveni otisak prsta koji predstavlja komad sadržaja na IPFS-u. Za razliku od tradicionalnih web URL-ova koji pokazuju na lokaciju (poput https://example.com/file.pdf), CIDs pokazuju na sam sadržaj, bez obzira gdje je pohranjen.

Razmislite o tome ovako:

  • Adresiranje temeljeno na lokaciji: „Idite na Glavnu ulicu 123 i tražite crvenu knjigu”
  • Adresiranje temeljeno na sadržaju: „Pronađite knjigu s ISBN-om 978-0-123456-78-9” (nije važno koja knjižnica je ima)

CIDs rade slično — identificiraju sadržaj na temelju njegove kriptografske hash vrijednosti, čineći sadržaj nepromjenjivim i provjerljivim. Ako se promijeni samo jedan bajt u datoteci, CID se potpuno mijenja.

Zašto je sadržajno adresiranje važno

Tradicionalna web arhitektura oslanja se na adresiranje temeljeno na lokaciji. Kada posjetite https://example.com/image.jpg, vjerujete da:

  1. Vlasnik domene nije promijenio sadržaj
  2. Poslužitelj je online i dostupan
  3. Sadržaj nije bio manipuliran

Sa sadržajnim adresiranjem koristeći CIDs:

  1. Nepromjenjivost: CID jamči da se sadržaj nije promijenio
  2. Decentralizacija: Sadržaj se može dohvatiti s bilo kojeg IPFS čvora koji ga ima
  3. Provjera: Možete kriptografski provjeriti da ste primili točan sadržaj
  4. Učinkovitost: Identičan sadržaj se automatski deduplicira

Anatomija CID-a

Razložimo tipični CID kako bismo razumjeli njegove komponente:

bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi
└─┬─┘└─────────────────┬─────────────────────────────────┘
  │                   │
  │                   └─ Hash sadržaja (Base32 kodiran)
  └─ Multibase prefiks (označava kodiranje)

CID sadrži nekoliko informacija:

1. Multibase prefiks

Prvi znak označava kako je CID kodiran:

  • Q = Base58 kodiranje (CIDv0)
  • b = Base32 kodiranje (CIDv1)
  • f = Base16/heksadecimalno (CIDv1)
  • z = Base58 (CIDv1)

2. CID verzija

  • CIDv0: Uvijek počinje s Qm, koristi SHA-256, ograničen na DAG-PB codec
  • CIDv1: Fleksibilniji, podržava više hash funkcija i codeca

3. Multicodec

Određuje kako je sadržaj strukturiran (DAG-PB, DAG-CBOR, sirovi bajtovi itd.)

4. Multihash

Stvarna kriptografska hash vrijednost sadržaja, uključujući:

  • Identifikator hash funkcije (obično SHA-256)
  • Duljinu hash-a
  • Hash digest

CIDv0 vs CIDv1: Razumijevanje razlika

IPFS je evoluirao kroz dvije glavne verzije CID-a, svaka s različitim karakteristikama:

CIDv0: Izvorni format

CIDv0 CIDs uvijek počinju s Qm i izgledaju ovako:

QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG

Karakteristike:

  • Samo Base58 kodiranje
  • Samo SHA-256 hash funkcija
  • Samo DAG-PB (Protobuf) codec
  • 46 znakova duljine
  • Unatrag kompatibilan sa svim IPFS implementacijama

Kada koristiti CIDv0:

  • Maksimalna kompatibilnost sa starijim IPFS čvorovima
  • Rad s postojećim sustavima koji očekuju Qm prefikse
  • Pohrana datoteka (najčešći slučaj uporabe)

CIDv1: Moderni standard

CIDv1 CIDs su fleksibilniji i mogu izgledati ovako:

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

Karakteristike:

  • Više formata kodiranja (Base32, Base58, Base16)
  • Podrška za različite hash funkcije (SHA-256, SHA-512, BLAKE2 itd.)
  • Više codeca (Raw, DAG-CBOR, DAG-JSON itd.)
  • Samoopisni format
  • Neosjetljiv na velika/mala slova pri Base32 uporabi

Kada koristiti CIDv1:

  • Izgradnja novih aplikacija
  • Potreba za identifikatorima neosjetljivim na velika slova
  • Rad sa strukturiranim podacima (JSON, CBOR)
  • Korištenje alternativnih hash funkcija

Konverzija između verzija

Možete konvertirati CIDs između verzija dok održavate istu referencu sadržaja:

// CIDv0
const cidv0 = "QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG";

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

// Both reference the same content!

Kako funkcionira sadržajno adresiranje

Sadržajno adresiranje u IPFS-u slijedi deterministički proces koji osigurava da isti sadržaj uvijek proizvodi isti CID:

1. Priprema sadržaja

Kada dodate sadržaj u IPFS, prvo se razlaže:

  • Male datoteke: Pohranjene kao pojedinačni blokovi
  • Velike datoteke: Podijeljene u dijelove i organizirane u Merkle DAG (usmjereni aciklički graf)
  • Direktoriji: Predstavljeni kao DAG strukture koje povezuju s datotekama

2. Proces hashinga

Svaki dio sadržaja prolazi kroz:

  1. Serijalizaciju: Sadržaj se formatira prema svojem codecu
  2. Hashing: Kriptografska hash funkcija obrađuje serijalizirane podatke
  3. Multihash stvaranje: Hash se omata informacijama o algoritmu i duljini
  4. CID sklapanje: Verzija, codec i multihash se kombiniraju

3. Merkle DAG struktura

IPFS organizira sadržaj u Merkle DAG gdje:

  • Svaki čvor ima CID
  • Roditeljski čvorovi referenciraju dječje čvorove putem CID-a
  • Promjene u bilo kojem čvoru se propagiraju kroz stablo
  • Cijele strukture se mogu kriptografski provjeriti
Root CID: bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi
├── file1.txt (QmHash1...)
├── file2.jpg (QmHash2...)
└── subdirectory/
    ├── file3.pdf (QmHash3...)
    └── file4.mp4 (QmHash4...)

Praktični primjeri: Rad s CIDs-ima

Istražimo kako raditi s CIDs-ima u praksi koristeći IPFS Ninja API:

Učitavanje sadržaja i dobivanje CID-a

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

Pinanje postojećeg sadržaja po CID-u

Ako već imate CID, možete ga pinati kako biste osigurali dostupnost:

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

Pristup sadržaju putem CID-a

Jednom kada imate CID, možete pristupiti sadržaju putem različitih metoda:

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

Najbolje prakse CID-a za razvijatelje

1. Uvijek validirajte CIDs

Prije korištenja CID-a u vašoj aplikaciji, validirajte njegov format:

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. Rukujte obje verzije CID-a

Vaša aplikacija trebala bi raditi s CIDv0 i 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. Spremajte CID mapiranja u predmemoriju

Ako često generirate CIDs, razmotrite 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. Koristite smislene opise

Pri učitavanju sadržaja, uključite opisne metapodatke:

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

Uobičajeni slučajevi uporabe CID-a

1. Implementacija statičkih web stranica

Implementirajte cijele web stranice na IPFS i referencirajte ih putem CID-a:

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

Za više informacija o implementaciji web stranica, pogledajte naš vodič o tome kako učitati datoteke na IPFS.

2. Pohrana NFT metapodataka

Pohranjujte NFT metapodatke nepromjenjivo koristeći 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. Distribucija sadržaja

Koristite CIDs za distribuiranu isporuku sadržaja:

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

Razumijevanje IPFS pinninga s CIDs-ima

CIDs su prema zadanim postavkama privremeni — moraju se „pinati” kako bi ostali dostupni. Saznajte više o ovom ključnom konceptu u našem sveobuhvatnom vodiču o tome što je IPFS pinning.

Pri odabiru IPFS pinning usluge, razmotrite čitanje naše usporedbe IPFS Ninja vs Pinata ili istražite naš pregled najboljih IPFS pinning usluga dostupnih danas.

Stvorite svoj prvi CID za 30 sekundi

Spremni stvoriti svoj prvi CID? Evo brzog primjera koristeći 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();

Ovo će vratiti nešto poput:

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

Za detaljnije primjere API-ja, pogledajte naš tutorial IPFS upload API.

Zaključak

CIDs su temelj sustava sadržajnog adresiranja IPFS-a, pružajući nepromjenjivu, provjerljivu i decentraliziranu identifikaciju sadržaja. Razumijevanje kako funkcioniraju — od tehničkih detalja CIDv0 vs CIDv1 do praktičnih obrazaca implementacije — je ključno za izgradnju robusnih decentraliziranih aplikacija.

Ključni zaključci:

  • CIDs jedinstveno identificiraju sadržaj, ne lokacije
  • CIDv0 pruža maksimalnu kompatibilnost, CIDv1 nudi fleksibilnost
  • Sadržajno adresiranje omogućuje provjeru i deduplikaciju
  • Pravilno rukovanje CID-om je ključno za produkcijske aplikacije

Bilo da pohranjujete NFT metapodatke, implementirate decentralizirane web stranice ili gradite sustave distribucije sadržaja, CIDs pružaju pouzdanu osnovu koja vam je potrebna za istinski decentralizirane aplikacije.

Spremni započeti pinanje? Stvorite besplatni račun — 50 datoteka, 1 GB pohrane, 2 GB propusnosti/mjesec. Bez kreditne kartice.

Share:
Natrag na Blog

Povezani članci

Pogledaj sve članke »