IPFS
STORAGE
IPFS connects machines with content-addressed files. Instead of fragile location URLs, everything is retrieved by its hash—perfect for keeping heavy assets off-chain while maintaining verifiable links from smart contracts.
The Blockchain Storage Problem
Blockchains are optimized for consensus over small, critical data—not for streaming megabytes of media. Trying to store files directly leads to massive gas costs and node bloat.
Storage Costs
Every byte on-chain costs gas. A 1MB image can be ruinous on L1.
Chain Bloat
Full nodes must store history forever; large files make running nodes painful.
Inefficiency
Consensus systems aren’t file systems. Use the right tool for the job.
💡 Keep only the file hash (CID) on-chain. Store the bytes in IPFS for verifiable, distributed retrieval.
InterPlanetary File System
IPFS is a P2P network for content-addressed files. Peers fetch data by CID; any node holding the content can serve it, and cryptographic hashes guarantee integrity.
Key Principles
- •Content-addressed (hashes, not locations)
- •Peer-to-peer distribution with no central server
- •Cryptographic verification of every block
- •Deduplication—same content, same CID
FIG IPFS-NET-01: IPFS Network Topology
HTTP (Traditional Web)
- • Location-based: https://example.com/cat.jpg
- • Centralized servers
- • Single point of failure
- • Link rot when hosts disappear
IPFS (Distributed Web)
- • Content-based: ipfs://QmX7Kd...
- • Distributed across peers
- • No single point of failure
- • Content stays reachable when pinned
Content Addressing
Adding a file to IPFS turns it into a content-addressed object through chunking, hashing, DAG assembly, and CID generation.
Chunking
Split into 256KB blocks
Hashing
Hash every block (SHA-256)
DAG
Blocks linked in a Merkle DAG
CID
Root hash → unique identifier
cat.jpg uploaded to IPFS
Deduplication: same content → same CID. Storage is saved across the network automatically.
Content Identifiers (CIDs)
A CID is a self-describing identifier for any IPFS object. It carries the hash, codec, and version info needed to verify data.
Immutable
Same bytes, same CID. Change a byte and the CID changes.
Verifiable
Anyone can hash the content to confirm authenticity.
Self-Describing
CID encodes hash function and version metadata.
Universal
Works across IPFS implementations and versions.
Pinning & Persistence
Garbage collection will remove unpinned data. Pinning keeps content alive by persisting it on nodes you control or via pinning services.
Without Pinning
- ✗ Files may disappear
- ✗ Unreachable when last peer goes offline
- ✗ No durability guarantees
With Pinning
- ✓ Content persists as long as pinned
- ✓ Pinning services add reliability
- ✓ Multiple pins = redundancy
Pinata
Managed pinning + APIs
Web3.Storage
Protocol Labs managed pinning
Infura IPFS
Enterprise-grade gateway
Self-Hosted
Run your own node
Using IPFS
import { create } from 'ipfs-http-client'
// Connect to IPFS node
const ipfs = create({
host: 'ipfs.infura.io',
port: 5001,
protocol: 'https'
})
// Upload file
async function uploadFile(file) {
const added = await ipfs.add(file)
console.log('CID:', added.path)
return added.path
}HTTP Gateway
https://ipfs.io/ipfs/QmX7Kd...Fetch via public gateways
IPFS Desktop
ipfs://QmX7Kd...Use local node + native protocol
Programmatic
ipfs.cat(CID)Fetch content via SDKs