· Nacho Coll · Guides  · 9 min de lecture

CID IPFS expliqué : ce que c'est et comment fonctionne l'adressage par contenu

Explication technique claire des Content Identifiers (CIDs) IPFS. Comment fonctionne l'adressage par contenu, les versions de CID et la création de votre premier CID.

Explication technique claire des Content Identifiers (CIDs) IPFS. Comment fonctionne l'adressage par contenu, les versions de CID et la création de votre premier CID.

Si vous avez travaillé avec IPFS (InterPlanetary File System), vous avez probablement rencontré des chaînes comme QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG ou bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi. Ce ne sont pas des chaînes aléatoires : ce sont des Content Identifiers (CIDs), l’épine dorsale du système d’adressage par contenu d’IPFS.

Comprendre les CIDs est crucial pour quiconque construit sur IPFS, que vous téléversiez des fichiers, bâtissiez des applications décentralisées ou implémentiez des systèmes de distribution de contenu. Ce guide décompose tout ce que vous devez savoir sur les CIDs IPFS, comment fonctionne l’adressage par contenu et comment commencer à les utiliser dans vos projets.

IPFS Ninja

Qu’est-ce qu’un CID IPFS ?

Un Content Identifier (CID) est une empreinte unique qui représente un contenu sur IPFS. Contrairement aux URLs web traditionnelles qui pointent vers un emplacement (comme https://example.com/file.pdf), les CIDs pointent vers le contenu lui-même, peu importe où il est stocké.

Pensez-y de la sorte :

  • Adressage par emplacement : « Va au 123 rue Principale et demande le livre rouge »
  • Adressage par contenu : « Trouve le livre avec ISBN 978-0-123456-78-9 » (peu importe quelle bibliothèque l’a)

Les CIDs fonctionnent de façon similaire — ils identifient le contenu par son hash cryptographique, rendant le contenu immuable et vérifiable. Si un seul octet change dans le fichier, le CID change complètement.

Pourquoi l’adressage par contenu compte

L’architecture web traditionnelle repose sur l’adressage par emplacement. Quand vous visitez https://example.com/image.jpg, vous faites confiance au fait que :

  1. Le propriétaire du domaine n’a pas changé le contenu
  2. Le serveur est en ligne et accessible
  3. Le contenu n’a pas été altéré

Avec l’adressage par contenu via CIDs :

  1. Immutabilité : Le CID garantit que le contenu n’a pas changé
  2. Décentralisation : Le contenu peut être récupéré depuis n’importe quel nœud IPFS qui l’a
  3. Vérification : Vous pouvez vérifier cryptographiquement avoir reçu le bon contenu
  4. Efficacité : Le contenu identique est dédupliqué automatiquement

Anatomie d’un CID

Disséquons un CID typique pour comprendre ses composants :

bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi
└─┬─┘└─────────────────┬─────────────────────────────────┘
  │                   │
  │                   └─ Hash du contenu (encodé en Base32)
  └─ Préfixe Multibase (indique l'encodage)

Un CID contient plusieurs informations :

1. Préfixe Multibase

Le premier caractère indique comment le CID est encodé :

  • Q = Encodage Base58 (CIDv0)
  • b = Encodage Base32 (CIDv1)
  • f = Base16/hexadécimal (CIDv1)
  • z = Base58 (CIDv1)

2. Version du CID

  • CIDv0 : Commence toujours par Qm, utilise SHA-256, limité au codec DAG-PB
  • CIDv1 : Plus flexible, prend en charge plusieurs fonctions de hachage et codecs

3. Multicodec

Spécifie comment le contenu est structuré (DAG-PB, DAG-CBOR, octets bruts, etc.)

4. Multihash

Le hash cryptographique réel du contenu, incluant :

  • Identifiant de la fonction de hachage (généralement SHA-256)
  • Longueur du hash
  • Le digest du hash

CIDv0 vs CIDv1 : comprendre les différences

IPFS a évolué à travers deux versions majeures de CID, chacune avec des caractéristiques distinctes :

CIDv0 : le format original

Les CIDs CIDv0 commencent toujours par Qm et ressemblent à ceci :

QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG

Caractéristiques :

  • Encodage Base58 uniquement
  • Fonction de hachage SHA-256 uniquement
  • Codec DAG-PB (Protobuf) uniquement
  • 46 caractères de long
  • Rétro-compatible avec toutes les implémentations IPFS

Quand utiliser CIDv0 :

  • Compatibilité maximale avec les anciens nœuds IPFS
  • Travailler avec des systèmes existants qui attendent des préfixes Qm
  • Stockage de fichiers (cas d’usage le plus courant)

CIDv1 : le standard moderne

Les CIDs CIDv1 sont plus flexibles et peuvent ressembler à :

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

Caractéristiques :

  • Plusieurs formats d’encodage (Base32, Base58, Base16)
  • Support de différentes fonctions de hachage (SHA-256, SHA-512, BLAKE2, etc.)
  • Plusieurs codecs (Raw, DAG-CBOR, DAG-JSON, etc.)
  • Format auto-descriptif
  • Insensible à la casse en Base32

Quand utiliser CIDv1 :

  • Construire de nouvelles applications
  • Besoin d’identifiants insensibles à la casse
  • Travailler avec des données structurées (JSON, CBOR)
  • Utiliser des fonctions de hachage alternatives

Conversion entre versions

Vous pouvez convertir les CIDs entre versions tout en conservant la même référence de contenu :

// CIDv0
const cidv0 = "QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG";

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

// Both reference the same content!

Comment fonctionne l’adressage par contenu

L’adressage par contenu dans IPFS suit un processus déterministe qui assure que le même contenu produit toujours le même CID :

1. Préparation du contenu

Quand vous ajoutez du contenu à IPFS, il est d’abord décomposé :

  • Petits fichiers : Stockés comme blocs uniques
  • Gros fichiers : Découpés en morceaux et organisés dans un Merkle DAG (Directed Acyclic Graph)
  • Répertoires : Représentés comme structures DAG liant aux fichiers

2. Processus de hachage

Chaque morceau de contenu passe par :

  1. Sérialisation : Le contenu est formaté selon son codec
  2. Hachage : La fonction de hachage cryptographique traite les données sérialisées
  3. Création du multihash : Le hash est enveloppé avec des informations d’algorithme et de longueur
  4. Assemblage du CID : Version, codec et multihash sont combinés

3. Structure Merkle DAG

IPFS organise le contenu dans un Merkle DAG où :

  • Chaque nœud a un CID
  • Les nœuds parents référencent les nœuds enfants par CID
  • Les changements sur un nœud se propagent en haut de l’arbre
  • Des structures entières peuvent être vérifiées cryptographiquement
Root CID: bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi
├── file1.txt (QmHash1...)
├── file2.jpg (QmHash2...)
└── subdirectory/
    ├── file3.pdf (QmHash3...)
    └── file4.mp4 (QmHash4...)

Exemples pratiques : travailler avec les CIDs

Voyons comment travailler avec les CIDs en pratique avec l’API d’IPFS Ninja :

Téléverser du contenu et obtenir un 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

Pinner du contenu existant par CID

Si vous avez déjà un CID, vous pouvez le pinner pour vous assurer qu’il reste disponible :

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

Accéder au contenu via CID

Une fois que vous avez un CID, vous pouvez accéder au contenu de plusieurs façons :

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

Bonnes pratiques CID pour développeurs

1. Toujours valider les CIDs

Avant d’utiliser un CID dans votre application, validez son 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. Gérer les deux versions de CID

Votre application devrait fonctionner avec CIDv0 et 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. Mettre en cache les correspondances de CID

Si vous générez des CIDs fréquemment, envisagez le cache :

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. Utiliser des descriptions significatives

Lors du téléversement de contenu, incluez des métadonnées descriptives :

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

Cas d’usage courants des CIDs

1. Déploiement de sites web statiques

Déployez des sites web entiers sur IPFS et référencez-les par 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;
};

Pour en savoir plus sur le déploiement de sites web, consultez notre guide sur comment téléverser des fichiers sur IPFS.

2. Stockage de métadonnées NFT

Stockez les métadonnées NFT de façon immuable avec des 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. Distribution de contenu

Utilisez les CIDs pour la distribution de contenu distribuée :

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

Comprendre le pinning IPFS avec les CIDs

Les CIDs sont temporaires par défaut — ils doivent être « pinés » pour rester disponibles. Apprenez-en plus sur ce concept crucial dans notre guide complet sur qu’est-ce que le pinning IPFS.

Lors du choix d’un service de pinning IPFS, lisez notre comparaison IPFS Ninja vs Pinata ou explorez notre tour d’horizon des meilleurs services de pinning IPFS disponibles aujourd’hui.

Créez votre premier CID en 30 secondes

Prêt à générer votre premier CID ? Voici un exemple rapide avec l’API d’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();

Cela renverra quelque chose comme :

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

Pour des exemples d’API plus détaillés, consultez notre tutoriel API d’upload IPFS.

Conclusion

Les CIDs sont la fondation du système d’adressage par contenu d’IPFS, fournissant une identification de contenu immuable, vérifiable et décentralisée. Comprendre comment ils fonctionnent — des détails techniques de CIDv0 vs CIDv1 aux patterns d’implémentation pratiques — est essentiel pour construire des applications décentralisées robustes.

Points clés à retenir :

  • Les CIDs identifient le contenu de façon unique, pas les emplacements
  • CIDv0 offre une compatibilité maximale, CIDv1 fournit la flexibilité
  • L’adressage par contenu permet la vérification et la déduplication
  • Une bonne gestion des CIDs est cruciale pour les applications de production

Que vous stockiez des métadonnées NFT, déployiez des sites web décentralisés ou construisiez des systèmes de distribution de contenu, les CIDs fournissent la fondation fiable dont vous avez besoin pour des applications véritablement décentralisées.

Prêt à commencer à piner ? Créer un compte gratuit — 50 fichiers, 1 Go de stockage, 2 Go de bande passante/mois. Pas de carte de crédit requise.

Share:
Retour au Blog

Articles Connexes

Voir Tous les Articles »