Storage·Filecoin · Multi-chain
Filecoin
Decentralized storage L1 with cryptographic proofs (PoRep / PoSt) of physical storage by independent storage providers (SPs). Modern apps use the Filecoin Synapse SDK or hot-storage networks like Storacha / Lighthouse instead of negotiating raw storage deals with SPs.
- 01verifiable cold archival storage
- 02datasets needing provable persistence
- 03NFT and metadata long-tail backup
- 04AI / model weight archival
- 05regulated data with auditable proofs
- pnpm add @filoz/synapse-sdk
| Variable | Scope | Description |
|---|---|---|
| FILECOIN_PRIVATE_KEY | Server | Private key (hex) of an FEVM-compatible wallet funded with FIL/USDFC used by the Synapse SDK to pay for storage. Server-side only. |
| NEXT_PUBLIC_FILECOIN_RPC_URL | Client | Filecoin (FEVM) RPC endpoint, e.g. `https://api.calibration.node.glif.io/rpc/v1` for testnet or a Glif/Ankr mainnet URL. |
Use the Filecoin Synapse SDK (`@filoz/synapse-sdk`) — it abstracts away raw deal-making and gives you a high-level upload/retrieve API on top of Filecoin Onchain Cloud (PDP, FilCDN, payments). Initialize on the server with `const synapse = await Synapse.create({ privateKey: process.env.FILECOIN_PRIVATE_KEY, rpcURL: process.env.NEXT_PUBLIC_FILECOIN_RPC_URL })`, then upload via `const { commp } = await synapse.storage.upload(bytes)` and retrieve with `synapse.storage.download(commp)`. Approve a USDFC deposit once with `synapse.payments.deposit(amount)` so subsequent uploads charge automatically. For pure pinning UX (CID in / file out) prefer Storacha or Lighthouse, which sit on top of Filecoin and hide deal mechanics. Only drop down to raw Lotus / `lotus client deal` flows when you specifically need to pick SPs or verify deal IDs onchain.
- ⚑Filecoin storage prices are quoted in FIL per GiB-epoch but you actually pay storage providers via deals — without a wrapper SDK (Synapse / Storacha / Lighthouse) you must run a Lotus node, fund a wallet, and manage deal proposals yourself.
- ⚑Retrieval is not free or instant — cold deals can take seconds to minutes to fetch. Use FilCDN / IPFS hot-cache layers for user-facing reads, and treat raw Filecoin as the cold tier behind a hot CID.
- ⚑SP availability is not guaranteed by the protocol — a single deal with a single SP can fail. Always pick multiple SPs (or use a wrapper that does replication for you) and verify PoSt status before treating data as 'persistent'.
- ⚑Payments need USDFC (a stablecoin on FEVM) for the new Onchain Cloud flow — funding only with FIL will not work on Synapse-based pipelines.
- ⚑Filecoin and IPFS are not the same — pinning to IPFS does not create a Filecoin deal, and a Filecoin deal does not automatically expose data over IPFS gateways. Use Storacha / Lighthouse if you want both.
- ⚑Calibration testnet and mainnet are completely separate — testnet FIL has no value and SPs there are flaky; do not benchmark production reliability against calibration.