Pinning

Come i file persistono sulla rete IPFS e perche' il pinning e' importante.

Il problema della garbage collection

I nodi IPFS hanno spazio di archiviazione limitato. Per gestire lo spazio su disco, eseguono periodicamente la garbage collection — un processo che rimuove i dati nella cache che non sono stati esplicitamente contrassegnati come importanti. Senza intervento, un file che hai caricato potrebbe essere cancellato dalla rete entro poche ore.

Il pinning dice a un nodo IPFS: "mantieni questo file permanentemente — non fare garbage collection su di esso." Un file pinnato rimane nello spazio di archiviazione del nodo a tempo indeterminato, garantendo che rimanga disponibile sulla rete.

Pinning locale vs remoto

Il pinning locale significa eseguire il proprio nodo IPFS e pinnare i file su di esso. Sei responsabile dell'uptime, dello spazio di archiviazione e della connettivita' di rete. Se il tuo nodo va offline, i tuoi file diventano non disponibili.

Il pinning remoto (cio' che IPFS.NINJA fornisce) significa che un servizio gestito pinna i tuoi file su un'infrastruttura sempre online. Ottieni la permanenza del pinning senza eseguire il tuo nodo.

TIP

Ogni file caricato tramite IPFS.NINJA viene automaticamente pinnato al nostro cluster IPFS. Non sono necessari passaggi aggiuntivi — i tuoi file sono persistenti dal momento del caricamento.

Cosa succede quando fai unpin

Se elimini un file dal tuo account IPFS.NINJA, lo depinniamo dai nostri nodi. Il file potrebbe comunque essere accessibile se:

• Altri nodi IPFS hanno nella cache o pinnato lo stesso CID
• Un gateway IPFS ha il file nella sua cache
• Un altro utente ha caricato lo stesso contenuto (stesso CID = stesso file)

Col tempo, senza che nessun nodo pinni il CID, il file verra' eliminato dalla garbage collection dell'intera rete.

Best practice per il pinning

• Pinna presto — Carica e pinna il tuo contenuto prima di fare riferimento al CID in smart contract, metadati NFT o sistemi esterni.
• Non affidarti alla cache — Le cache dei gateway IPFS sono temporanee. Solo il contenuto pinnato e' garantito che persista.
• Mantieni attivo il tuo account — I file rimangono pinnati finche' il tuo account IPFS.NINJA e' attivo, anche nel livello gratuito.

Pinnare contenuto esistente

Non devi caricare un file tramite IPFS.NINJA per pinnarlo. Se il contenuto esiste gia' sulla rete IPFS — caricato da qualcun altro, o da te tramite un altro servizio — puoi pinnarlo al tuo account fornendo il suo CID.

Quando pinni un CID esistente, il nostro cluster:

1. Cerca nella rete IPFS i nodi che hanno il contenuto
2. Scarica il contenuto dal nodo disponibile piu' vicino
3. Lo pinna localmente sulla nostra infrastruttura
4. Lo rende accessibile tramite il tuo account e gateway

Questo e' utile per:

• Preservare asset NFT — pinna metadati e immagini da collezioni esistenti
• Backup del contenuto — assicurati che CID importanti rimangano disponibili anche se il pinner originale va offline
• Migrazione da un altro servizio — pinna i tuoi CID esistenti senza ricaricare i file

Consulta la documentazione dell'API Pinning per i dettagli sugli endpoint.