An IPFS blockchain setup stores large files on IPFS and puts only a short content identifier, called a CID, on-chain. This guide explains how CIDs work, how to keep IPFS data available, how smart contracts reference that data, and which mistakes break IPFS-based apps.
What IPFS is and what it is not
Blockchains charge for every byte of storage, so dApps keep files off-chain and store a reference on-chain, and IPFS makes that reference verifiable. The CID is computed from the data itself, so anyone can check that the fetched file matches the CID in the contract.
The InterPlanetary File System (IPFS) is a set of protocols that address, route and transfer data by its content. A normal web request asks one server for a file at a path. An IPFS request asks the network which nodes hold the data with a given hash, and the client then checks the data it receives.
- IPFS provides content addressing, verification, deduplication, and retrieval from any node or gateway that holds the data.
- IPFS does not provide a ledger, payments, a storage guarantee or privacy. Anyone who knows a CID can fetch the data from a node that announces it.
The blockchain records ownership and order, while IPFS stores the large data in a form that shows any change.
How content addressing works
An IPFS implementation splits an added file into chunks, hashes each chunk and links the chunks into a Merkle DAG, a tree of hashes. The hash at the root of the tree becomes the file's CID. A directory is a DAG node that links to its files, and the format for files and directories is called UnixFS.
A CID combines the hash with information about how to read the data:
| Part | Meaning | Example values |
|---|---|---|
| Version | CIDv0 or CIDv1 | CIDv0 strings start with Qm. CIDv1 strings in base32 usually start with bafy or bafk. |
| Multibase | Text encoding of the CID | base58btc for CIDv0, base32 by default for CIDv1 |
| Codec | Structure of the referenced bytes | dag-pb (UnixFS), raw, dag-cbor, dag-json |
| Multihash | Hash function and digest | sha2-256 by default |
Why one file can have two CIDs
The same bytes can produce different CIDs, because the CID depends on the chunk size, CID version, codec, DAG width and the raw-leaves setting. A backend and a user's tool with different settings compute different CIDs for an identical file.
In March 2026 the IPFS project published IPIP-0499 to fix this problem, and the specification defines two named profiles with every parameter set:
| Parameter | unixfs-v1-2025 | unixfs-v0-2015 (legacy) |
|---|---|---|
| CID version | CIDv1 | CIDv0 |
| Chunk size | 1 MiB | 256 KiB |
| Raw leaves | Yes | No |
| Links per DAG node | 1,024 | 174 |
| Hash | sha2-256 | sha2-256 |
The IPFS blog lists support in Kubo 0.40, boxo 0.37 and Helia's UnixFS 7.0.3 package. Choose one profile for new work and write it into your upload pipeline. Use CIDv1, because subdomain gateways need a CID that does not depend on letter case, and the base32 form of a CIDv1 meets that need.
Finding and fetching IPFS data
IPFS nodes announce the CIDs they hold in a distributed hash table based on Kademlia. Nodes exchange blocks with the Bitswap protocol, or over HTTP from trustless gateways.
Most users never run a node, and their apps reach IPFS through an HTTP gateway. A gateway accepts two URL styles:
- Path style:
https://gateway.example/ipfs/<cid>/. Every CID shares one browser origin, and the IPFS documentation says path gateways should not host web apps. - Subdomain style:
https://<cid>.ipfs.gateway.example/. Each CID gets its own browser origin, so use this style to serve HTML or JavaScript.
With a regular gateway, the client trusts the gateway to return the right bytes. A trustless gateway returns raw blocks or CAR files, and the client checks every hash itself, as browser libraries such as Helia's verified fetch do. If your app depends on the integrity of IPFS data, verify the data in the client.
Public gateways change over time. In 2024, Cloudflare moved its public IPFS gateway traffic to two IPFS Foundation gateways, ipfs.io and dweb.link. The cloudflare-ipfs.com hostname was scheduled to stop working on August 14, 2024, and any contract or metadata file that hardcoded that hostname lost its links.
Pinning: how IPFS data stays available
Every IPFS node caches data it fetches, but it deletes unpinned data during garbage collection. If the only node that pinned a file goes offline, the CID still exists, but nobody can retrieve the file, which is how NFTs end up pointing at missing images.
| Option | How it works | Suits |
|---|---|---|
| Self-hosted Kubo nodes | You run the Go implementation and pin your CIDs | Teams with operations staff who want full control |
| IPFS Cluster | Coordinates pins and replication across several of your own nodes | Production copies in more than one region |
| Pinning services | Commercial providers pin data for a fee, many through the standard Pinning Service API | Most dApps that want a quick start |
| Filecoin storage | Storage providers keep data for a set term and post cryptographic proofs on the Filecoin chain | Long-term and archive storage |
| A mix of the above | Two independent providers plus your own node | Data you cannot afford to lose |
Pinning services also change. NFT.Storage Classic stopped accepting new uploads and pins on June 30, 2024, and the project says retrieval of existing data may get worse over time. Projects that relied on that one service had to move their data.
A production dApp should pin with at least two independent parties and keep the original files and CAR exports in your own backup. Test retrieval from outside your own infrastructure, because a "pinned" status does not prove that users can fetch the file.
Filecoin also offers storage for frequently read data. Filecoin Onchain Cloud uses Proof of Data Possession (PDP), under which providers prove at regular intervals that they hold a copy ready for retrieval. According to the Filecoin blog, uploads through Filecoin's Synapse SDK go to two independent storage providers by default.
Using IPFS with smart contracts
NFT metadata and media
For ERC-721 and ERC-1155 tokens, store the metadata JSON and the media files on IPFS, so the tokenURI function returns ipfs://<cid>/<tokenId>.json.
Write the ipfs:// scheme on-chain instead of a gateway URL, which ties the token to one company's domain. Wallets and marketplaces resolve ipfs:// links through their own gateway.
Upload a whole collection as one directory, so a single base CID covers every token. Inside each JSON file, reference the media with ipfs:// links too. NFT token development covers token contracts in more detail.
Reveals and changing metadata
A CID never changes after creation. For a delayed reveal, publish a commitment before minting, either the final directory CID or a hash of it, and switch the base URI once at reveal.
Some metadata must change, for example game items. For such items, use IPNS, which gives a name, signed by a key, that can point to new content. Another option is an on-chain base URI that a multisig controls. Tell holders that the data can change.
Documents and records
Enterprise and DeFi apps often store a CID on-chain as a commitment to a document, such as a loan agreement, an audit report or a governance proposal. The chain proves that the document existed in that exact form at that block, while the document itself can sit on IPFS or in private storage.
Private and regulated data
IPFS has no access control, so encrypt sensitive data before you add it and manage the encryption keys in a separate system, such as your own key service or a threshold key network.
Copies on other nodes may stay forever, even when they are encrypted. Personal data under erasure rules, such as GDPR, therefore does not belong on IPFS; keep it in normal storage and anchor only hashes on-chain. The EMR and EHR guide shows this pattern for health records.
IPFS development tools in 2026
- Kubo: the main Go implementation, formerly go-ipfs, with an HTTP RPC API.
- Helia: the JavaScript implementation for Node.js and browsers and the replacement for js-ipfs. Its verified fetch library checks content in the browser.
- boxo: the Go library set that Kubo and other Go tools build on.
- IPFS Cluster: manages pins across many nodes.
- CAR files: an archive format that moves DAGs between systems and providers.
- DNSLink: maps a domain to a CID with a DNS TXT record, which teams use to host dApp front ends.
The IPFS documentation covers each tool.
Common failures in IPFS blockchain apps
- One pinning provider. The provider changes prices, shuts down or deletes unpaid data, and every token that used it breaks at once.
- Hardcoded gateway URLs. A contract or metadata file points at one gateway domain, and the links fail when that gateway limits traffic or closes.
- Mismatched CIDs. The CID computed at upload differs from the CID committed on-chain, so a reveal or audit fails.
- dApp code on a path gateway. Scripts from different CIDs share one browser origin, so one site can read another site's local storage.
Build checklist
- Decide what goes on-chain (CIDs, hashes, ownership) and what goes on IPFS.
- Choose one CID profile and compute CIDs locally before upload, then compare them with the CIDs the provider reports.
- Choose at least two pinning parties and set up retrieval monitoring.
- Encrypt sensitive data before it reaches IPFS.
- Store
ipfs://links on-chain and let clients choose the gateway. - If users need censorship resistance, host the front end on IPFS with DNSLink, in addition to normal hosting.
Effort and cost
Adding IPFS storage to an existing dApp through a pinning service takes a few days to two weeks of engineering. A self-run cluster with monitoring takes months, and a product built around decentralized storage also takes months and needs ongoing operations staff.
Storage fees depend on data volume and the provider's price list, and for most NFT collections the fee is small compared with the cost of lost data. For general dApp design, see dApp development and Web3 dApp development.
Frequently asked questions
Is IPFS a blockchain?
No. IPFS is a peer-to-peer protocol for content-addressed files, with no ledger, no consensus and no token. Apps pair IPFS with a blockchain, which stores the CID and the ownership record.
Is data on IPFS permanent?
Data stays available only while at least one node pins it. The CID never changes, but retrieval depends on nodes that keep the data. Use several pinning parties or Filecoin storage for long-term data.
What is the difference between IPFS and Filecoin?
IPFS is the protocol that addresses and moves content. Filecoin is a blockchain market that pays storage providers and requires them to prove they still hold the data. Many projects use the two together.
Why do I get a different CID for the same file?
The CID version, chunk size, codec, DAG width and raw-leaves setting all change the result. Use one named profile, such as unixfs-v1-2025, everywhere you compute CIDs.
Can I delete a file from IPFS?
You can unpin a file from your own nodes. You cannot force other nodes or caches to delete their copies, so treat anything added to IPFS as possibly permanent.