IPFS & Decentralized Storage
Store and retrieve content on IPFS using Pinata, Fleek, or web3.storage. Understand content addressing, pinning, and NFT metadata storage.
IPFS (InterPlanetary File System) is a content-addressed, peer-to-peer storage network. Content is identified by its hash (CID) rather than location. It's essential for Web3 because it provides censorship-resistant storage for NFT metadata, dApp frontends, and on-chain data references.
Always pin content through a pinning service (Pinata, web3.storage) - content without pinners gets garbage collected. Use `ipfs://` URIs in contracts, resolve via public gateways for UX. Understand that IPFS is not encryption - don't store secrets.
Workflow
- Upload and pin files with PinataIPFS nodes don't guarantee persistence; pinning services commit to hosting your CIDs.
- Structure NFT metadata correctlyMarketplaces (OpenSea, Blur) parse metadata to display NFT properties; non-standard formats break display.
- Retrieve content via gatewaysBrowsers can't resolve `ipfs://` natively; gateways translate to HTTPS.
- Handle CID versions and encodingCIDv0 (Qm...) and CIDv1 (bafy...) have different formats; modern tooling uses v1.
- Set up IPFS for dApp frontend hostingHosting your dApp frontend on IPFS makes it censorship-resistant; users can access it via any gateway.
Output Format
Files pinned on Pinata with CIDs, NFT metadata JSON following ERC-721 standard, gateway resolver utility, CID stored on-chain.
Examples
Upload image + metadata: `const img = await pinata.pinFileToIPFS(fs.createReadStream("nft.png")); const meta = await pinata.pinJSONToIPFS({ name: "NFT #1", image: `ipfs://${img.IpfsHash}`, attributes: [] }); tokenURI = `ipfs://${meta.IpfsHash}`;`Gateway util: `const toHTTPS = (uri) => uri?.startsWith("ipfs://") ? uri.replace("ipfs://", "https://ipfs.io/ipfs/") : uri`Contract tokenURI: `function tokenURI(uint256 id) public view returns (string memory) { return string.concat("ipfs://", _cids[id]); }`Edge Cases & Gotchas
- Gateway reliability: public gateways go down; always offer fallback gateway URLs in your frontend
- Large collections (10k NFTs): use a base URI with sequential token IDs rather than individual CIDs to simplify management
- Metadata mutability: IPFS is immutable by design; use IPNS or a proxy contract for updatable metadata, but document that it's centralized
When to Break These Rules
- For internal enterprise applications without public decentralization requirements, traditional S3-compatible storage is simpler, faster, and cheaper.
Reference Files
IPFS docs: https://docs.ipfs.tech/Pinata SDK: https://docs.pinata.cloud/ERC-721 Metadata Standard: https://eips.ethereum.org/EIPS/eip-721Fleek: https://fleek.co/