IPNS — Nombres Mutables para IPFS

IPNS (InterPlanetary Name System) te ofrece direcciones estables y compartibles que pueden actualizarse para apuntar a contenido diferente a lo largo del tiempo. Mientras que los CIDs de IPFS cambian cada vez que el contenido cambia, un nombre IPNS permanece igual — solo actualizas a donde apunta.

Disponible en los planes Bodhi (3 nombres, 100 publicaciones/mes) y Nirvana (10 nombres, 1,000 publicaciones/mes).

Aprende más sobre IPNS

Para una inmersion profunda en como funciona IPNS a nivel de protocolo, consulta la documentación oficial de IPFS sobre IPNS.

¿Por qué usar IPNS?

El problema: Cada vez que subes una nueva version de un archivo a IPFS, obtienes un CID diferente. Si compartiste el CID antiguo con los usuarios, ellos siguen viendo el contenido antiguo. Tendrias que compartir un nuevo enlace cada vez.

La solución: Crea un nombre IPNS una vez, compartelo y actualiza a que apunta cuando tu contenido cambie. Cualquier persona con la dirección IPNS siempre obtiene la version más reciente.

Casos de uso comunes

• Sitios web en IPFS — Despliega tu sitio, obtén un CID, publicalo en tu nombre IPNS. Redesplegar -> nuevo CID -> actualizar el nombre IPNS. La URL nunca cambia.
• Metadatos NFT que evolucionan — Apunta el tokenURI de tu NFT a una dirección IPNS. Actualiza los metadatos (ej. un item de juego sube de nivel) sin cambiar el contrato inteligente.
• Archivos de configuración — Tu aplicación lee la configuración desde una dirección IPNS. Actualiza la configuración sin redesplegar la aplicación.
• Feeds de datos — Pública conjuntos de datos diarios o feeds de precios bajo una dirección IPNS estable.
• DNSLink — Conecta tu dominio a IPNS para que https://tudominio.com siempre sirva el contenido IPFS más reciente.

Usando el Panel de Control

1. Crear un nombre IPNS

1. Ve a IPNS en la barra lateral bajo Hosting.
2. Haz clic en Crear nombre.
3. Ingresa una etiqueta (ej. "mi-sitio-web") y haz clic en Crear.
4. Copia la dirección IPNS (comienza con k51...) — está es tu dirección permanente y compartible.

2. Publicar un CID en tu nombre IPNS

1. Encuentra el nombre IPNS en la lista y haz clic en Publicar.
2. Ingresa el CID al que quieres que apunte (ej. QmXk7VRz... o bafybei...).
3. Haz clic en Publicar. Esto se propaga a la red IPFS y puede tomar hasta 60 segundos.
4. Una vez publicado, el contenido es accesible en:
   • Gateway IPFS: https://ipfs.ninja/ipns/{tu-nombre-ipns}
   • Cualquier gateway público: https://dweb.link/ipns/{tu-nombre-ipns}
   • IPFS nativo: ipns://{tu-nombre-ipns}

3. Actualizar tu contenido

Cuando tu contenido cambia:

1. Sube la nueva version a IPFS (vía panel de control o API) -> obtén un nuevo CID.
2. Vuelve a IPNS, haz clic en Publicar en el mismo nombre, ingresa el nuevo CID.
3. La dirección IPNS permanece igual — cualquier persona que la use automáticamente obtiene el nuevo contenido.

4. Resolver un nombre IPNS

Usa la sección Resolver en la parte inferior de la página para buscar el CID actual de cualquier nombre IPNS — el tuyo o de cualquier otra persona.

5. Eliminar un nombre IPNS

Haz clic en el botón de eliminar junto a cualquier nombre. El registro IPNS expirará de la red dentro de 48 horas.

Conectar un Dominio con DNSLink

Puedes apuntar tu propio nombre de dominio a una dirección IPNS usando DNSLink. Esto permite que los usuarios accedan a tu contenido IPFS a través de una URL regular como https://tudominio.com.

¿Cómo configurar DNSLink

1. Crea un nombre IPNS y pública el CID de tu contenido en el (pasos anteriores).

2. Agrega un registro DNS TXT en el proveedor DNS de tu dominio:

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

   Ejemplo: Si tu nombre IPNS es k51qzi5uqu5djcpbukxs...:

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

3. Verifica el registro usando dig o nslookup:

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

4. Accede a través de cualquier gateway IPFS que soporte DNSLink:

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

   O a través de un navegador con soporte IPFS (como Brave):

   ipns://myapp.com

Propagación DNS

Los cambios de DNS pueden tardar hasta 24 horas en propagarse globalmente. Después de agregar el registro TXT, espera algunas horas antes de probar.

TIP

Solo necesitas configurar DNSLink una vez. Cuando publicas un nuevo CID en tu nombre IPNS, el dominio automáticamente resuelve al nuevo contenido — no se necesitan cambios DNS.

DNSLink con Cloudflare

Si usas Cloudflare:

1. Ve a DNS -> Records.
2. Agrega un nuevo registro: Tipo: TXT, Nombre: _dnslink, Contenido: dnslink=/ipns/k51...
3. Configura el estado del proxy en Solo DNS (nube gris).

DNSLink con Route 53

1. Ve a tu zona alojada en Route 53.
2. Crea un registro: Nombre: _dnslink.yourdomain.com, Tipo: TXT, Valor: "dnslink=/ipns/k51..."

Ejemplos de Uso

Ejemplo 1: Despliegue de sitio web estático

# 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

Ejemplo 2: Metadatos 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 })
});

Ejemplo 3: Integración 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"'"}'

Referencia de la API

Todos los ejemplos de la API usan el encabezado X-Api-Key. Obtén tu clave API desde la página de Claves API.

Listar Claves IPNS

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

Respuesta:

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

Crear Clave 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"}'

Respuesta 201:

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

Publicar en IPNS

Publicar actualiza el nombre IPNS para apuntar a un nuevo CID. Esto se propaga al DHT de IPFS y puede tomar hasta 60 segundos.

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"}'

Respuesta:

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

Resolver Nombre IPNS

Busca el CID actual de cualquier nombre IPNS.

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

Respuesta:

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

Eliminar Clave IPNS

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

Respuesta:

{ "success": true }

¿Cómo Funciona IPNS

1. Generación de claves: Cuando creas un nombre IPNS, se genera un par de claves criptográficas (Ed25519). El hash de la clave pública se convierte en tu dirección IPNS (k51...).
2. Publicación: Cuando publicas, firmas un registro diciendo "este nombre apunta al CID X" y lo transmites al DHT de IPFS (Tabla Hash Distribuida).
3. Resolución: Cuando alguien busca tu nombre IPNS, los nodos IPFS consultan el DHT para obtener el registro firmado más reciente y siguen el enlace al CID.
4. Republicación: Los registros IPNS expiran después de 48 horas. IPFS Ninja republica automáticamente tus registros cada 12 horas para mantenerlos activos.
5. Seguridad: Solo el poseedor de la clave privada (tu) puede actualizar a que apunta un nombre IPNS. Nadie más puede secuestrar tu nombre.

Límites del Plan

Plan	Nombres IPNS	Publicaciones / Mes
Dharma (Gratuito)	No disponible	—
Bodhi ($5/mes)	3	100
Nirvana ($29/mes)	10	1,000

• Los registros se republican automáticamente cada 12 horas para mantenerlos activos en la red IPFS.
• Los nombres que no se publican durante 90 días se marcan como inactivos y dejan de ser republicados.
• Los nombres inactivos pueden reactivarse publicando un nuevo CID en ellos.

Lectura Adicional

• Conceptos IPNS — Documentación IPFS — Documentación oficial sobre como funciona IPNS a nivel de protocolo
• DNSLink — Documentación IPFS — Conectar nombres de dominio a contenido IPFS/IPNS
• Direccionamiento por Contenido — Entendiendo los CIDs y por que IPNS resuelve el problema de la mutabilidad