· Nacho Coll · Guides  · 9 min basahin

IPFS CID ipinaliwanag: ano ito at paano gumagana ang content addressing

Malinaw na teknikal na paliwanag ng IPFS Content Identifiers (CIDs). Paano gumagana ang content addressing, mga bersyon ng CID at kung paano gumawa ng iyong unang CID.

Malinaw na teknikal na paliwanag ng IPFS Content Identifiers (CIDs). Paano gumagana ang content addressing, mga bersyon ng CID at kung paano gumawa ng iyong unang CID.

Kung nakapagtrabaho ka na sa IPFS (InterPlanetary File System), malamang nakatagpo ka na ng mga string tulad ng QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG o bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi. Hindi ito random na walang kabuluhan — sila ay Content Identifiers (CIDs), ang gulugod ng content addressing system ng IPFS.

Ang pag-unawa sa CIDs ay mahalaga para sa kahit sino na nagtatayo sa IPFS, ikaw man ay nag-uupload ng mga file, nagtatayo ng decentralized applications, o nag-iimplementa ng content distribution systems. Itong gabay ay magpapaliwanag ng lahat ng kailangan mong malaman tungkol sa IPFS CIDs, paano gumagana ang content addressing, at kung paano magsimulang gamitin ang mga ito sa iyong mga proyekto.

IPFS Ninja

Ano ang IPFS CID?

Ang Content Identifier (CID) ay isang natatanging fingerprint na kumakatawan sa isang piraso ng content sa IPFS. Hindi tulad ng tradisyonal na web URLs na nagtuturo sa isang lokasyon (tulad ng https://example.com/file.pdf), ang CIDs ay nagtuturo sa mismong content, hindi alintana kung saan ito naka-store.

Isipin ito ng ganito:

  • Location-based addressing: “Pumunta sa Main Street 123 at hingin ang pulang libro”
  • Content-based addressing: “Hanapin ang libro na may ISBN 978-0-123456-78-9” (hindi mahalaga kung aling library ang may hawak nito)

Ang CIDs ay gumagana sa parehong paraan — kinikilala nila ang content batay sa cryptographic hash nito, ginagawang hindi nababago at mapapatunayan ang content. Kung magbabago ang isang byte sa file, ang CID ay magbabago nang buo.

Bakit mahalaga ang content addressing

Ang tradisyonal na web architecture ay umaasa sa location-based addressing. Kapag bumisita ka sa https://example.com/image.jpg, nagtitiwala ka na:

  1. Hindi binago ng may-ari ng domain ang content
  2. Ang server ay online at maaaring i-access
  3. Hindi nagalaw ang content

Sa content addressing gamit ang CIDs:

  1. Immutability: Ginagarantiyahan ng CID na hindi nabago ang content
  2. Decentralization: Maaaring makuha ang content mula sa anumang IPFS node na mayroon nito
  3. Verification: Maaari mong i-verify cryptographically na natanggap mo ang tamang content
  4. Efficiency: Ang magkakatulad na content ay awtomatikong na-deduplicate

Anatomya ng CID

I-breakdown natin ang isang tipikal na CID upang maunawaan ang mga bahagi nito:

bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi
└─┬─┘└─────────────────┬─────────────────────────────────┘
  │                   │
  │                   └─ Content Hash (Base32 encoded)
  └─ Multibase prefix (nagpapahiwatig ng encoding)

Ang CID ay naglalaman ng ilang piraso ng impormasyon:

1. Multibase prefix

Ang unang character ay nagpapahiwatig kung paano naka-encode ang CID:

  • Q = Base58 encoding (CIDv0)
  • b = Base32 encoding (CIDv1)
  • f = Base16/hexadecimal (CIDv1)
  • z = Base58 (CIDv1)

2. CID Version

  • CIDv0: Palaging nagsisimula sa Qm, gumagamit ng SHA-256, limitado sa DAG-PB codec
  • CIDv1: Mas flexible, sumusuporta sa maraming hash functions at codecs

3. Multicodec

Tinutukoy kung paano nakabalangkas ang content (DAG-PB, DAG-CBOR, raw bytes, atbp.)

4. Multihash

Ang aktwal na cryptographic hash ng content, kasama ang:

  • Hash function identifier (kadalasan ay SHA-256)
  • Hash length
  • Hash digest

CIDv0 vs CIDv1: Pag-unawa sa pagkakaiba

Ang IPFS ay umunlad sa pamamagitan ng dalawang pangunahing bersyon ng CID, bawat isa ay may natatanging katangian:

CIDv0: Ang orihinal na format

Ang CIDv0 CIDs ay palaging nagsisimula sa Qm at mukhang ganito:

QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG

Mga katangian:

  • Base58 encoding lamang
  • SHA-256 hash function lamang
  • DAG-PB (Protobuf) codec lamang
  • 46 character ang haba
  • Backward compatible sa lahat ng IPFS implementations

Kailan gamitin ang CIDv0:

  • Maximum compatibility sa mga mas lumang IPFS nodes
  • Pagtatrabaho sa mga umiiral na sistema na umaasa sa Qm prefixes
  • File storage (pinakakaraniwang use case)

CIDv1: Ang modernong standard

Ang CIDv1 CIDs ay mas flexible at maaaring mukhang ganito:

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

Mga katangian:

  • Maraming encoding formats (Base32, Base58, Base16)
  • Suporta sa iba’t ibang hash functions (SHA-256, SHA-512, BLAKE2, atbp.)
  • Maraming codecs (Raw, DAG-CBOR, DAG-JSON, atbp.)
  • Self-describing format
  • Hindi case-sensitive kapag gumagamit ng Base32

Kailan gamitin ang CIDv1:

  • Pagbuo ng mga bagong application
  • Kailangan ng case-insensitive identifiers
  • Pagtatrabaho sa structured data (JSON, CBOR)
  • Paggamit ng alternative hash functions

Conversion sa pagitan ng mga bersyon

Maaari mong i-convert ang CIDs sa pagitan ng mga bersyon habang pinanatili ang parehong content reference:

// CIDv0
const cidv0 = "QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG";

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

// Both reference the same content!

Paano gumagana ang content addressing

Ang content addressing sa IPFS ay sumusunod sa isang deterministic na proseso na nagsisiguro na ang parehong content ay laging nagbubuo ng parehong CID:

1. Paghahanda ng content

Kapag nag-add ka ng content sa IPFS, una itong binubreak down:

  • Maliit na mga file: Iniimbak bilang single blocks
  • Malaking mga file: Hinati sa mga chunk at inayos sa Merkle DAG (directed acyclic graph)
  • Mga directory: Kinakatawan bilang DAG structures na nagli-link sa mga file

2. Hashing process

Ang bawat piraso ng content ay dumadaan sa:

  1. Serialization: Ang content ay naka-format ayon sa codec nito
  2. Hashing: Pinoproseso ng cryptographic hash function ang serialized data
  3. Multihash creation: Ang hash ay binabalot ng algorithm at length information
  4. CID assembly: Pinagsama ang version, codec, at multihash

3. Merkle DAG structure

Ang IPFS ay nag-aayos ng content sa isang Merkle DAG kung saan:

  • Ang bawat node ay may CID
  • Ang parent nodes ay tumutukoy sa child nodes sa pamamagitan ng CID
  • Ang mga pagbabago sa anumang node ay kumakalat pataas sa puno
  • Ang buong istruktura ay maaaring i-verify cryptographically
Root CID: bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi
├── file1.txt (QmHash1...)
├── file2.jpg (QmHash2...)
└── subdirectory/
    ├── file3.pdf (QmHash3...)
    └── file4.mp4 (QmHash4...)

Praktikal na mga halimbawa: Pakikipagtulungan sa CIDs

Pag-aralan natin kung paano makipagtulungan sa CIDs sa pagsasanay gamit ang IPFS Ninja API:

Pag-upload ng content at pagkuha ng 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

Pag-pin ng umiiral na content sa pamamagitan ng CID

Kung mayroon ka nang CID, maaari mong i-pin ito upang masiguro ang availability:

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

Pag-access sa content sa pamamagitan ng CID

Kapag mayroon ka nang CID, maaari mong ma-access ang content sa pamamagitan ng iba’t ibang methods:

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

Mga best practice ng CID para sa mga developer

1. Palaging i-validate ang CIDs

Bago gamitin ang isang CID sa iyong application, i-validate ang format nito:

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. Pangasiwaan ang parehong bersyon ng CID

Ang iyong application ay dapat gumana sa parehong CIDv0 at 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. I-cache ang mga CID mapping

Kung madalas kang gumagawa ng CIDs, isaalang-alang ang 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. Gumamit ng makabuluhang mga deskripsyon

Kapag nag-upload ng content, isama ang descriptive metadata:

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

Mga karaniwang use case ng CID

1. Static website deployment

I-deploy ang buong website sa IPFS at i-reference sila sa pamamagitan ng 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;
};

Upang malaman ang higit pa tungkol sa website deployment, tingnan ang aming gabay tungkol sa kung paano mag-upload ng mga file sa IPFS.

2. NFT metadata storage

Mag-imbak ng NFT metadata nang hindi nababago gamit ang 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. Content distribution

Gamitin ang CIDs para sa distributed content delivery:

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

Pag-unawa sa IPFS pinning gamit ang CIDs

Ang CIDs ay pansamantala bilang default — dapat silang “i-pin” upang manatiling available. Matuto pa tungkol sa mahalagang konseptong ito sa aming komprehensibong gabay tungkol sa ano ang IPFS pinning.

Kapag pumipili ng IPFS pinning service, isaalang-alang ang pagbabasa ng aming paghahambing na IPFS Ninja vs Pinata o tuklasin ang aming roundup ng mga pinakamahusay na IPFS pinning services na available ngayon.

Gumawa ng iyong unang CID sa 30 segundo

Handa nang mag-generate ng iyong unang CID? Narito ang isang mabilis na halimbawa gamit ang 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();

Magreturn ito ng kahawig ng:

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

Para sa mas detalyadong mga halimbawa ng API, tingnan ang aming IPFS upload API tutorial.

Konklusyon

Ang CIDs ay ang pundasyon ng content addressing system ng IPFS, nagbibigay ng immutable, verifiable, at decentralized na pagkakakilanlan ng content. Ang pag-unawa kung paano sila gumagana — mula sa teknikal na detalye ng CIDv0 vs CIDv1 hanggang sa praktikal na implementation patterns — ay mahalaga para sa pagbuo ng matatag na decentralized applications.

Mga pangunahing punto:

  • Ang CIDs ay natatanging tinutukoy ang content, hindi lokasyon
  • Ang CIDv0 ay nagbibigay ng maximum compatibility, ang CIDv1 ay nag-aalok ng flexibility
  • Ang content addressing ay nagbibigay-daan sa verification at deduplication
  • Ang wastong pamamahala ng CID ay mahalaga para sa production applications

Mag-store ka man ng NFT metadata, mag-deploy ng decentralized websites, o magbuo ng content distribution systems, ang CIDs ay nagbibigay ng maaasahang pundasyon na kailangan mo para sa tunay na decentralized applications.

Handa nang magsimulang mag-pin? Gumawa ng libreng account — 50 file, 1 GB storage, 2 GB bandwidth/buwan. Walang credit card.

Share:
Bumalik sa Blog

Kaugnay na Artikulo

Tingnan Lahat ng Artikulo »