IPNS — Noms Mutables pour IPFS

IPNS (InterPlanetary Name System) vous offre des adresses stables et partageables qui peuvent etre mises à jour pour pointer vers du contenu different au fil du temps. Alors que les CIDs IPFS changent à chaque modification du contenu, un nom IPNS reste le même — vous mettez simplement à jour vers ou il pointe.

Disponible sur les plans Bodhi (3 noms, 100 publications/mois) et Nirvana (10 noms, 1 000 publications/mois).

En savoir plus sûr IPNS

Pour une plongee approfondie dans le fonctionnement d'IPNS au niveau du protocole, consultez la documentation officielle IPFS sûr IPNS.

Pourquoi utiliser IPNS ?

Le problème : Chaque fois que vous téléchargez une nouvelle version d'un fichier sur IPFS, vous obtenez un CID different. Si vous avez partage l'ancien CID avec des utilisateurs, ils voient toujours l'ancien contenu. Vous devriez partager un nouveau lien à chaque fois.

La solution : Créez un nom IPNS une fois, partagez-le et mettez à jour vers ou il pointe lorsque votre contenu change. Toute personne ayant l'adresse IPNS obtient toujours la dernière version.

Cas d'utilisation courants

• Sites web sur IPFS — Déployez votre site, obtenez un CID, publiez-le sur votre nom IPNS. Redéployez -> nouveau CID -> mettez à jour le nom IPNS. L'URL ne change jamais.
• Métadonnées NFT qui evoluent — Pointez le tokenURI de votre NFT vers une adresse IPNS. Mettez à jour les métadonnées (ex. un objet de jeu monte de niveau) sans changer le contrat intelligent.
• Fichiers de configuration — Votre application lit la configuration depuis une adresse IPNS. Mettez à jour la configuration sans redéployer l'application.
• Flux de données — Publiez des jeux de données quotidiens ou des flux de prix sous une adresse IPNS stable.
• DNSLink — Connectez votre domaine a IPNS pour que https://votredomaine.com serve toujours le dernier contenu IPFS.

Utilisation du Tableau de Bord

1. Créer un nom IPNS

1. Allez dans IPNS dans la barre latérale sous Hosting.
2. Cliquez sur Créer un nom.
3. Entrez un libellé (ex. "mon-site-web") et cliquez sur Créer.
4. Copiez l'adresse IPNS (commence par k51...) — c'est votre adresse permanente et partageable.

2. Publier un CID sur votre nom IPNS

1. Trouvez le nom IPNS dans la liste et cliquez sur Publier.
2. Entrez le CID vers lequel vous voulez qu'il pointe (ex. QmXk7VRz... ou bafybei...).
3. Cliquez sur Publier. Cela se propage sur le réseau IPFS et peut prendre jusqu'à 60 secondes.
4. Une fois publie, le contenu est accessible a :
   • Gateway IPFS : https://ipfs.ninja/ipns/{votre-nom-ipns}
   • N'importe quel gateway public : https://dweb.link/ipns/{votre-nom-ipns}
   • IPFS natif : ipns://{votre-nom-ipns}

3. Mettre à jour votre contenu

Lorsque votre contenu change :

1. Téléchargez la nouvelle version sur IPFS (via le tableau de bord ou l'API) -> obtenez un nouveau CID.
2. Retournez dans IPNS, cliquez sur Publier sur le même nom, entrez le nouveau CID.
3. L'adresse IPNS reste la même — toute personne l'utilisant obtient automatiquement le nouveau contenu.

4. Résoudre un nom IPNS

Utilisez la section Résoudre en bas de la page pour rechercher le CID actuel de n'importe quel nom IPNS — le votre ou celui de quelqu'un d'autre.

5. Supprimer un nom IPNS

Cliquez sur le bouton supprimer a côté de n'importe quel nom. L'enregistrement IPNS expirera du réseau dans les 48 heures.

Connecter un Domaine avec DNSLink

Vous pouvez pointer votre propre nom de domaine vers une adresse IPNS en utilisant DNSLink. Cela permet aux utilisateurs d'accéder à votre contenu IPFS via une URL régulière comme https://votredomaine.com.

Comment configurer DNSLink

1. Créez un nom IPNS et publiez le CID de votre contenu dessus (étapes ci-dessus).

2. Ajoutez un enregistrement DNS TXT chez votre fournisseur DNS de domaine :

   _dnslink.yourdomain.com  TXT  "dnslink=/ipns/{your-ipns-name}"

   Exemple : Si votre nom IPNS est k51qzi5uqu5djcpbukxs... :

   _dnslink.myapp.com  TXT  "dnslink=/ipns/k51qzi5uqu5djcpbukxs..."

3. Vérifiez l'enregistrement avec dig ou nslookup :

   dig +short TXT _dnslink.myapp.com
   # Devrait retourner : "dnslink=/ipns/k51qzi5uqu5djcpbukxs..."

4. Accédez via n'importe quel gateway IPFS supportant DNSLink :

   https://ipfs.ninja/ipns/myapp.com

   Ou via un navigateur avec support IPFS (comme Brave) :

   ipns://myapp.com

Propagation DNS

Les modifications DNS peuvent prendre jusqu'à 24 heures pour se propager globalement. Apres avoir ajoute l'enregistrement TXT, attendez quelques heures avant de tester.

TIP

Vous n'avez besoin de configurer DNSLink qu'une seule fois. Lorsque vous publiez un nouveau CID sur votre nom IPNS, le domaine résout automatiquement vers le nouveau contenu — aucun changement DNS nécessaire.

DNSLink avec Cloudflare

Si vous utilisez Cloudflare :

1. Allez dans DNS -> Records.
2. Ajoutez un nouvel enregistrement : Type : TXT, Nom : _dnslink, Contenu : dnslink=/ipns/k51...
3. Définissez le statut du proxy sur DNS uniquement (nuage gris).

DNSLink avec Route 53

1. Allez dans votre zone hébergée dans Route 53.
2. Créez un enregistrement : Nom : _dnslink.yourdomain.com, Type : TXT, Valeur : "dnslink=/ipns/k51..."

Exemples d'Utilisation

Exemple 1 : Déploiement de site web statique

# 1. Build your site
npm run build

# 2. Upload the build output to IPFS
CID=$(curl -s -X POST https://api.ipfs.ninja/upload/new \
  -H "X-Api-Key: bws_your_api_key" \
  -H "Content-Type: application/json" \
  -d "{\"content\": $(cat dist/index.html | base64 -w0 | jq -Rs .), \"description\": \"Website v2.1\"}" \
  | jq -r '.cid')

echo "Uploaded: $CID"

# 3. Update your IPNS name to point to the new build
curl -X POST https://api.ipfs.ninja/ipns/publish \
  -H "X-Api-Key: bws_your_api_key" \
  -H "Content-Type: application/json" \
  -d "{\"ipnsName\": \"k51qzi5uqu5dlvj2bv6...\", \"cid\": \"$CID\"}"

# Your site at ipns://k51... now serves the new version

Exemple 2 : Métadonnées NFT mutables

// Smart contract points tokenURI to IPNS address:
// tokenURI = "ipns://k51qzi5uqu5dlvj2bv6..."

// When the NFT evolves (e.g., game item levels up):
const newMetadata = {
  name: "Dragon Sword",
  description: "A legendary weapon — Level 5",
  image: "ipfs://QmNewImageCID...",
  attributes: [
    { trait_type: "Level", value: 5 },
    { trait_type: "Damage", value: 150 }
  ]
};

// Upload new metadata
const uploadRes = await fetch("https://api.ipfs.ninja/upload/new", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Api-Key": "bws_your_api_key"
  },
  body: JSON.stringify({ content: newMetadata, description: "Dragon Sword v5" })
});
const { cid } = await uploadRes.json();

// Update the IPNS pointer — tokenURI stays the same!
await fetch("https://api.ipfs.ninja/ipns/publish", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Api-Key": "bws_your_api_key"
  },
  body: JSON.stringify({ ipnsName: "k51qzi5uqu5dlvj2bv6...", cid })
});

Exemple 3 : Integration CI/CD

# GitHub Actions: auto-publish to IPNS on every push
- name: Upload to IPFS and publish IPNS
  run: |
    CID=$(curl -s -X POST https://api.ipfs.ninja/upload/new \
      -H "X-Api-Key: ${{ secrets.IPFS_NINJA_API_KEY }}" \
      -H "Content-Type: application/json" \
      -d '{"content": '"$(cat build/output.json)"', "description": "Deploy ${{ github.sha }}"}' \
      | jq -r '.cid')

    curl -X POST https://api.ipfs.ninja/ipns/publish \
      -H "X-Api-Key: ${{ secrets.IPFS_NINJA_API_KEY }}" \
      -H "Content-Type: application/json" \
      -d '{"ipnsName": "${{ vars.IPNS_NAME }}", "cid": "'"$CID"'"}'

Référence de l'API

Tous les exemples de l'API utilisent l'en-tête X-Api-Key. Obtenez votre clé API depuis la page Clés API.

Lister les Clés IPNS

curl https://api.ipfs.ninja/ipns/keys \
  -H "X-Api-Key: bws_your_api_key_here"

Réponse :

[
  {
    "ipnsName": "k51qzi5uqu5dlvj2bv6...",
    "keyName": "my-website",
    "currentCid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
    "lastPublishedAt": 1711123200000,
    "publishCountMonth": 12,
    "status": "active",
    "createdAt": 1711036800000
  }
]

Créer une Clé IPNS

curl -X POST https://api.ipfs.ninja/ipns/keys \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-website"}'

Réponse 201 :

{
  "ipnsName": "k51qzi5uqu5dlvj2bv6...",
  "keyName": "my-website",
  "createdAt": 1711036800000
}

Publier sûr IPNS

Publier met à jour le nom IPNS pour pointer vers un nouveau CID. Cela se propage dans le DHT d'IPFS et peut prendre jusqu'à 60 secondes.

curl -X POST https://api.ipfs.ninja/ipns/publish \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"ipnsName": "k51qzi5uqu5dlvj2bv6...", "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi"}'

Réponse :

{
  "ipnsName": "k51qzi5uqu5dlvj2bv6...",
  "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
  "published": true
}

Résoudre un Nom IPNS

Recherchez le CID actuel de n'importe quel nom IPNS.

curl https://api.ipfs.ninja/ipns/resolve/k51qzi5uqu5dlvj2bv6... \
  -H "X-Api-Key: bws_your_api_key_here"

Réponse :

{
  "ipnsName": "k51qzi5uqu5dlvj2bv6...",
  "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi"
}

Supprimer une Clé IPNS

curl -X DELETE https://api.ipfs.ninja/ipns/keys/k51qzi5uqu5dlvj2bv6... \
  -H "X-Api-Key: bws_your_api_key_here"

Réponse :

{ "success": true }

Comment Fonctionne IPNS

1. Generation de clés : Lorsque vous créez un nom IPNS, une paire de clés cryptographiques (Ed25519) est générée. Le hash de la clé publique devient votre adresse IPNS (k51...).
2. Publication : Lorsque vous publiez, vous signez un enregistrement disant "ce nom pointe vers le CID X" et le diffusez dans le DHT d'IPFS (Table de Hachage Distribuee).
3. Resolution : Lorsque quelqu'un recherche votre nom IPNS, les nœuds IPFS interrogent le DHT pour obtenir le dernier enregistrement signe et suivent le lien vers le CID.
4. Republication : Les enregistrements IPNS expirent apres 48 heures. IPFS Ninja républié automatiquement vos enregistrements toutes les 12 heures pour les maintenir actifs.
5. Sécurité : Seul le détenteur de la clé privée (vous) peut mettre à jour vers ou un nom IPNS pointe. Personne d'autre ne peut détourner votre nom.

Limites du Plan

Plan	Noms IPNS	Publications / Mois
Dharma (Gratuit)	Non disponible	—
Bodhi (5 $/mois)	3	100
Nirvana (29 $/mois)	10	1 000

• Les enregistrements sont automatiquement républiés toutes les 12 heures pour les maintenir actifs sur le réseau IPFS.
• Les noms non publies pendant 90 jours sont marqués comme inactifs et cessent d'etre républiés.
• Les noms inactifs peuvent etre réactivés en publiant un nouveau CID dessus.

Lectures Complémentaires

• Concepts IPNS — Documentation IPFS — Documentation officielle sur le fonctionnement d'IPNS au niveau du protocole
• DNSLink — Documentation IPFS — Connecter des noms de domaine au contenu IPFS/IPNS
• Adressage par Contenu — Comprendre les CIDs et pourquoi IPNS résout le problème de la mutabilité