Guía de IPFS Nivel Medio: Contenido Direccionado, Pinning, IPNS y PubSub por Santiago Soñora

“Hola, mundo” en IPFS

El 'Hola, mundo' en IPFS: iniciar tu nodo local y agregar un archivo, obteniendo su Content Identifier (CID).

📋 Copiar

# Instala IPFS (si no lo has hecho) siguiendo la documentación oficial.
# Inicializa tu repositorio local de IPFS (solo la primera vez)
ipfs init

# Inicia el daemon (el nodo local de IPFS)
ipfs daemon
# (En otra terminal, o después de ver 'Daemon is ready')

# Agrega un archivo
echo "Hola IPFS" > hola.txt
ipfs add hola.txt

Resultado:

Output

initializing IPFS node at /Users/tu_usuario/.ipfs
... (output de inicialización)
Daemon is ready
added Qm... hola.txt

Comandos básicos

Familiarizarse con estos comandos es esencial para interactuar eficientemente con IPFS:

Inicializar el repositorio local de IPFS
📋 Copiar
```
ipfs init
```
Configura el directorio local donde IPFS almacenará sus datos (el repositorio) y genera la clave de identidad de tu nodo. Necesario solo la primera vez que usas IPFS en una máquina.
Iniciar el daemon (nodo local de IPFS)
📋 Copiar
```
ipfs daemon
```
Inicia el proceso en segundo plano que conecta tu máquina a la red IPFS, permitiendo agregar, obtener y compartir archivos. Debe estar corriendo para que la mayoría de los otros comandos funcionen.
Ver estado y ID de tu nodo IPFS
📋 Copiar
```
ipfs id
```
Muestra la ID de tu nodo IPFS (tu Peer ID), las direcciones a las que otros nodos pueden conectarse para encontrarte, y otra información.
Agregar archivo(s) a IPFS
📋 Copiar
```
ipfs add archivo.txt
```
Agrega uno o más archivos al almacenamiento local de tu nodo IPFS y genera su Content Identifier (CID) basado en su contenido.
Agregar un directorio completo a IPFS
📋 Copiar
```
ipfs add -r /ruta/a/tu/carpeta
```
Agrega recursivamente todos los archivos y subdirectorios dentro de una carpeta. Genera un CID único para cada archivo/subdirectorio y un CID raíz para la carpeta completa. El flag `-r` es para recursivo.
Obtener un archivo o directorio por su CID
📋 Copiar
```
ipfs get <CID>
```
Busca el contenido asociado a un CID específico en la red IPFS (si tu nodo no lo tiene) y lo descarga a tu máquina local. Si es un CID de directorio, descarga la carpeta completa.
Hacer 'pin' (pinear) un CID para asegurar su persistencia
📋 Copiar
```
ipfs pin add <CID>
```
Indica a tu nodo local que conserve el contenido asociado a ese CID de forma permanente y que no lo elimine durante la recolección de basura. Essential para que tus archivos permanezcan disponibles.
Ver los CIDs que tu nodo está pineando
📋 Copiar
```
ipfs pin ls
```
Muestra una lista de todos los Content Identifiers que tu nodo IPFS está manteniendo de forma persistente ('pineados').
Eliminar un CID del pineado
📋 Copiar
```
ipfs pin rm <CID>
```
Elimina un CID de la lista de pineado de tu nodo. El contenido aún puede estar en el repositorio local temporalmente hasta la próxima recolección de basura.
Ver la interfaz Web UI de IPFS
📋 Copiar
```
http://127.0.0.1:5001/webui
```
Accede a una interfaz gráfica local en tu navegador para gestionar tu nodo IPFS, ver peers, explorar archivos pineados y agregar nuevos.
Acceder a contenido IPFS a través de un Gateway público
📋 Copiar
```
https://ipfs.io/ipfs/<CID>
https://cloudflare-ipfs.com/ipfs/<CID>
```
Permite a cualquier persona acceder al contenido IPFS desde un navegador web estándar sin necesidad de tener un nodo IPFS local corriendo.
Explorar la estructura interna de un objeto IPFS (blob, tree, commit)
📋 Copiar
```
ipfs object get <CID> # Ve el objeto raw
ipfs ls <CID> # Lista los enlaces para CIDs de directorios/commits
```
Permite investigar cómo IPFS estructura los datos. `ipfs object get` muestra el objeto IPLD subyacente. `ipfs ls` es útil para ver los contenidos de directorios.
Publicar un CID a tu IPNS (para una dirección mutable)
📋 Copiar
```
ipfs name publish <CID>
```
Asocia un CID (el hash de tu contenido actual) a tu clave de IPNS (por defecto, tu Peer ID). Esto crea una dirección `/ipns/<tu_id>` que siempre apuntará a este CID, incluso si el contenido cambia y genera un nuevo CID.
Resolver un nombre IPNS (encontrar el CID actual)
📋 Copiar
```
ipfs name resolve <IPNS_ID>
```
Busca en la red IPFS para encontrar el CID actual al que apunta un nombre IPNS (que puede ser un Peer ID o un nombre IPNS personalizado asociado a una clave).
Suscribirse a un tema de PubSub (mensajería P2P)
📋 Copiar
```
ipfs pubsub sub <nombre_del_tema>
```
Configura tu nodo para escuchar mensajes publicados en un tema específico en la red PubSub de IPFS. Mantén el comando ejecutándose para recibir mensajes.
Publicar un mensaje a un tema de PubSub
📋 Copiar
```
ipfs pubsub pub <nombre_del_tema> "tu mensaje para los suscriptores"
```
Envía un mensaje a todos los nodos IPFS conectados a la red que están suscritos al tema especificado.
Ejecutar Recolección de Basura (Garbage Collection) manual
📋 Copiar
```
ipfs repo gc
```
Instruye a tu nodo local a eliminar cualquier contenido que ya no esté pineado, liberando espacio en el repositorio. Normalmente, el daemon lo hace automáticamente.

Conceptos Clave

Comprender estos conceptos fundamentales te ayudará a dominar IPFS de forma más organizada y eficiente:

Contenido Direccionado (Content Addressing) y CIDs:

La base de IPFS. En lugar de identificar un archivo por su ubicación ('localhost/images/logo.png'), se identifica por un hash criptográfico de su contenido ('Qm...'). Este hash se llama CID (Content Identifier). Si cambias un solo bit del archivo, el CID cambia. Esto garantiza que si pides un CID, obtienes exactamente el contenido correcto y no ha sido alterado. Es la clave para la inmutabilidad y la verificación.
IPLD (InterPlanetary Linked Data):

El modelo de datos sobre el que se construye IPFS. IPLD permite estructurar datos complejos (como archivos grandes divididos en bloques o directorios con subdirectorios y archivos) como un grafo de objetos de datos enlazados. Los CIDs actúan como los punteros ('enlaces') entre estos objetos. Es lo que permite que IPFS maneje estructuras de datos más allá de archivos individuales.
Agregar y Obtener Datos (Archivos, Directorios, Bloques):

El proceso de `ipfs add` toma tu contenido local, lo divide en bloques (si es grande), lo hashea, lo envuelve en objetos IPLD y genera un CID. Tu nodo lo almacena localmente y lo anuncia a la red. `ipfs get <CID>` le pide a tu nodo que encuentre y recupere el contenido asociado a ese CID de cualquier nodo en la red que lo tenga y lo ensamble de nuevo.
Pinning (Pineado) y Garbage Collection (Recolección de Basura):

Por defecto, los datos que agregas a tu nodo son temporales y pueden ser eliminados. 'Pinear' (`ipfs pin add`) un CID es la forma de decirle a tu nodo que ese contenido es importante y debe conservarlo indefinidamente en su almacenamiento local. La 'Garbage Collection' (`ipfs repo gc`) es el proceso mediante el cual tu nodo elimina activamente los bloques de datos que ya no están pineados para liberar espacio.
IPNS (InterPlanetary Naming System):

Un sistema para crear direcciones mutables en el mundo inmutable de IPFS. Te permite asociar un CID (que cambia cada vez que actualizas tu contenido) a un nombre IPNS (generalmente la ID de tu nodo o una clave personalizada) que permanece constante (`/ipns/<nombre>`). Es útil para sitios web que se actualizan o datos que cambian con el tiempo, ya que la URL `/ipns/` siempre apunta a la última versión publicada del contenido pineado.
IPFS Gateways:

Servidores (como `ipfs.io` o `cloudflare-ipfs.com`) que actúan como puentes entre la red HTTP tradicional e IPFS. Permiten a cualquier usuario de Internet acceder al contenido almacenado en IPFS simplemente usando una URL HTTP (`https://gateway.com/ipfs/<CID>` o `https://gateway.com/ipns/<IPNS_ID>`) sin necesidad de tener un nodo IPFS corriendo localmente.
Ejecutando un Nodo IPFS:

Las diferentes formas de conectarse y participar en la red IPFS. La implementación más común es 'Kubo' (el daemon CLI oficial). También existe JS-IPFS (una implementación en JavaScript para navegadores o Node.js), IPFS Desktop (una interfaz gráfica fácil de usar), y IPFS Cluster (para gestionar grupos de nodos que pinean contenido).
PubSub (Publish/Subscribe):

Un protocolo de mensajería peer-to-peer integrado en IPFS. Permite que los nodos se suscriban a 'temas' y publiquen mensajes a esos temas, creando una red de comunicación descentralizada. Es útil para notificaciones en tiempo real, sistemas de chat P2P básicos o coordinación entre dApps.
IPFS Web UI:

Una interfaz gráfica local (accesible en `http://127.0.0.1:5001/webui` cuando el daemon está corriendo) que te permite interactuar visualmente con tu nodo IPFS. Puedes ver el estado de tu nodo, tus peers, explorar los archivos que tienes pineados, agregar nuevos archivos o carpetas, y ver estadísticas.
Interacción con IPFS desde Código (API, RPC, Librerías):

Cómo integrar la funcionalidad de IPFS en tus propias aplicaciones. El daemon IPFS expone una API HTTP y una API RPC que puedes llamar directamente. También existen librerías cliente (como `ipfs-core` o `ipfs-http-client` para JavaScript) que simplifican la interacción programática con un nodo IPFS local o remoto.
Pinning Services y Soluciones de Almacenamiento Web3:

Servicios de terceros (ej: Pinata, Web3.Storage, Infura IPFS Gateway, Gateway3) que ejecutan nodos IPFS potentes y fiables. Ofrecen pinear tu contenido IPFS por ti, asegurando que esté siempre disponible en la red sin que tengas que preocuparte por mantener tu propio nodo corriendo 24/7. Muchos de estos servicios integran con Filecoin para el almacenamiento a largo plazo.
Consideraciones de Seguridad y Privacidad:

IPFS es una red pública. Por defecto, el contenido que agregas y pineas puede ser accedido por cualquiera que conozca su CID. Para datos privados, debes cifrarlos ANTES de agregarlos a IPFS. Aunque el contenido se verifica por hash, la identidad de los peers puede ser rastreada por observadores de la red.

Casos de uso

Algunos ejemplos de aplicaciones prácticas donde se utiliza IPFS:

Alojar sitios web estáticos de forma descentralizada y resistente a la censura:

Publicar el contenido estático (HTML, CSS, JS, imágenes) de un sitio web en IPFS. Se puede acceder a través de gateways públicos o utilizando IPNS para tener una URL mutable (`/ipns/<id>`) que siempre apunte a la última versión del sitio.
Gestionar metadatos y archivos asociados a Tokens No Fungibles (NFTs):

Almacenar las imágenes, videos, audio, descripciones y otros metadatos de los NFTs en IPFS, utilizando el CID como URI (identificador único) en el contrato inteligente del NFT (ej: en el campo `tokenURI`). Esto garantiza que los metadatos del NFT sean inmutables y verificables.
Distribuir grandes conjuntos de datos o archivos multimedia (audio/video) de forma eficiente a través de P2P:

Utilizar IPFS para compartir archivos voluminosos, aprovechando la naturaleza peer-to-peer para que múltiples nodos puedan ayudar a distribuir los datos simultáneamente, reduciendo la carga en un único servidor central.
Construir aplicaciones descentralizadas (dApps) que almacenan y recuperan datos de usuario o datos de la aplicación en IPFS:

Integrar la funcionalidad de IPFS en el frontend o backend de una dApp para permitir que los usuarios (o la dApp misma) almacenen datos de forma descentralizada, como perfiles de usuario, configuraciones, o datos específicos de la aplicación, vinculados a sus identidades en la blockchain.
Crear un sistema de archivos distribuido, versionado y resistente a la censura para colaboración:

Utilizar IPFS para almacenar archivos de proyectos o documentos compartidos. IPFS maneja el versionado implícito (cada cambio de archivo/carpeta crea un nuevo CID) y permite agregar directorios completos, facilitando la colaboración descentralizada.
Construir herramientas de comunicación descentralizada o sistemas de notificación utilizando IPFS PubSub:

Implementar funcionalidades de chat, mensajería en tiempo real, sistemas de notificación o coordinación entre peers utilizando el protocolo Publish/Subscribe integrado en IPFS.
Asegurar la disponibilidad y persistencia confiable de datos importantes utilizando pinning services:

Para contenido que debe estar siempre disponible (ej: frontend de una dApp, metadatos de NFTs populares), usar un servicio de pinning de terceros (como Pinata, Web3.Storage) es crucial. Ellos se aseguran de que copias de tu contenido IPFS estén pineadas en múltiples nodos distribuidos.
Compartir archivos de forma privada o con control de acceso (construyendo capas adicionales):

Aunque IPFS es público por naturaleza, se pueden construir aplicaciones sobre él que cifren los datos antes de agregarlos (usando claves de cifrado) y controlen quién puede obtener esas claves, permitiendo compartir contenido de forma privada sobre la red pública de IPFS.

Consejos para Principiantes

Aquí tienes algunas recomendaciones para facilitar tus inicios en IPFS:

Entiende Profundamente el Contenido Direccionado y los CIDs:

Esta es la idea central. Tu archivo no tiene una URL, tiene un CID. Si cambias el archivo, el CID cambia. Esto es diferente a la web tradicional y es fundamental para la integridad y resistencia a la censura. Acostúmbrate a trabajar con CIDs.
Domina el Concepto de Pinning (Pineado):

¡Este es un error común para principiantes! Por defecto, IPFS no garantiza que tus archivos permanezcan disponibles para siempre. Debes 'pinear' los CIDs que quieres conservar. Si no pineas un CID, tu nodo local puede eliminarlo para liberar espacio (`garbage collection`), y si ningún otro nodo lo tiene pineado, el contenido se vuelve inaccesible.
Utiliza el Daemon de IPFS (`ipfs daemon`) Constantemente:

Para que tu nodo participe activamente en la red (descubrir peers, obtener/proporcionar contenido), el daemon debe estar corriendo. La mayoría de los otros comandos CLI (`ipfs add`, `ipfs get`) interactúan con el daemon.
Acostúmbrate a Usar la CLI de IPFS y el Dashboard Web UI:

La CLI es tu herramienta principal para interactuar con tu nodo de forma programática o con scripts. El Dashboard Web UI (`http://127.0.0.1:5001/webui`) es genial para gestionar visualmente tu nodo, ver pines, peers y explorar archivos.
Considera Usar un Servicio de Pinning para Persistencia Fiable en Producción:

Para asegurar que tu contenido importante (frontend de dApps, metadatos de NFTs) esté siempre disponible para cualquier persona en la red, es muy recomendable usar un servicio de pinning de terceros (como Pinata, Web3.Storage). Ellos se encargan de ejecutar nodos robustos y pinear tu contenido de forma fiable.
Entiende la Diferencia entre Agregar Archivos Individuales y Directorios:

`ipfs add <archivo>` te da un CID para el archivo. `ipfs add -r <carpeta>` te da un CID raíz para la carpeta (que internamente apunta a los CIDs de los archivos y subcarpetas). Usa `-r` para colecciones de archivos o sitios web.
Explora IPNS para Direcciones Mutables si Tu Contenido se Actualiza:

Si necesitas que un nombre (`/ipns/`) apunte a contenido que cambias periódicamente (cuyo CID cambia), IPNS es la solución. Tu ID de nodo IPFS es un nombre IPNS por defecto al que puedes publicar CIDs.
Sé Consciente de la Publicidad de los Datos por Defecto:

Cualquier contenido que agregues a IPFS y pinees es público por defecto. Si necesitas privacidad, DEBES cifrar tus datos ANTES de agregarlos a IPFS.
Prueba el Sistema de Mensajería PubSub para Comunicación P2P:

Si estás interesado en comunicación descentralizada, experimenta con `ipfs pubsub`. Permite a los nodos que conocen un tema comunicarse sin un servidor central.
Revisa la Documentación Oficial para Profundizar:

La documentación de IPFS es extensa y cubre en detalle todos los conceptos (CIDs, IPLD, Pinning, PubSub, IPNS, Gateways) y cómo usar la CLI y las API. Es tu mejor recurso para ir más allá de lo básico.

Herramientas relacionadas

Si te interesa IPFS, también podrías explorar estas herramientas:

Recursos útiles

Amplía tus conocimientos con estos enlaces y materiales: