Filecoin Integration

Filecoin Integration

Filecoin is a decentralized data storage network with cryptographic proofs that data is actually stored (Proof of Replication and Proof of Spacetime). This fundamentally distinguishes it from IPFS: IPFS is a content addressing protocol with no storage guarantees. Filecoin is a storage layer with economic incentives and verifiable guarantees.

In most production scenarios you use both: IPFS for fast access, Filecoin for long-term guaranteed storage.

Integration Methods: Direct vs Aggregators

Direct work with Filecoin via Lotus node is complex: you need to find a storage provider (SP), agree on deal parameters (price, duration, number of replicas), wait for deal publication on-chain (~24 hours). For most applications this is overkill.

Aggregators (Web3.Storage, Lighthouse, Storacha) abstract away complexity: you upload a file via HTTP API, they manage deals with storage providers.

Integration via Web3.Storage (Storacha)

npm install @web3-storage/w3up-client

import { create } from '@web3-storage/w3up-client'
import { filesFromPaths } from 'files-from-path'

async function uploadToFilecoin(filePaths: string[]): Promise<string> {
  const client = await create()

  // Authentication (once)
  // const account = await client.login('[email protected]')
  // await account.plan.wait()
  // const space = await client.createSpace('my-app')
  // await client.setCurrentSpace(space.did())

  const files = await filesFromPaths(filePaths)
  const cid = await client.uploadDirectory(files)

  return `https://${cid}.ipfs.w3s.link` // IPFS gateway URL
}

// Upload single file
async function uploadFile(content: Uint8Array, name: string): Promise<string> {
  const client = await create()
  const file = new File([content], name)
  const cid = await client.uploadFile(file)
  return cid.toString() // CID for access via any IPFS gateway
}

Direct Integration via Lotus API

For cases where you need full control (SP selection, deal parameters):

import { LotusRPC } from '@filecoin-shipyard/lotus-client-rpc'

const client = new LotusRPC(
  'https://api.node.glif.io/rpc/v0',  // public Glif RPC
  { token: process.env.GLIF_TOKEN }
)

// Get list of storage providers
const miners = await client.stateListMiners([])

// Check provider reputation
const minerInfo = await client.stateMinerInfo(minerAddress, [])
const minerPower = await client.stateMinerPower(minerAddress, [])

// Import file to local Lotus (need running daemon)
// const importResult = await client.clientImport({ Path: '/path/to/file', IsCAR: false })

CAR (Content Addressable Archive) Format

Filecoin stores data in CAR format. When working with large files you need to split them into chunks:

import { pack } from 'ipfs-car/pack'
import { CarWriter } from '@ipld/car'
import { CID } from 'multiformats'

async function createCar(files: File[]): Promise<{ car: Blob; rootCid: CID }> {
  const { root, out } = await pack({
    input: files,
    wrapWithDirectory: true,
  })

  const chunks: Uint8Array[] = []
  for await (const chunk of out) {
    chunks.push(chunk)
  }

  return {
    car: new Blob(chunks, { type: 'application/car' }),
    rootCid: root,
  }
}

Maximum deal size for most SPs is 32 GB. For larger files you need to split into parts and make multiple deals.

Filecoin Virtual Machine (FVM)

Since 2023, Filecoin supports EVM-compatible smart contracts via FVM (Filecoin Virtual Machine). This opens possibilities for programmable storage:

// Contract that automatically renews deals
// Uses Filecoin Solidity API (FEVM)

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.19;

import {MarketAPI} from "@zondax/filecoin-solidity/contracts/v0.8/MarketAPI.sol";
import {MarketTypes} from "@zondax/filecoin-solidity/contracts/v0.8/types/MarketTypes.sol";

contract DealRenewal {
    function renewDeal(uint64 dealId) external {
        MarketTypes.GetDealActivationReturn memory activation =
            MarketAPI.getDealActivation(dealId);

        // If deal expires within 30 days — renew
        int64 expiryEpoch = activation.terminated;
        // ... renewal logic
    }
}

FVM address format differs from EVM: f410f... (FEVM address) vs standard 0x.... You can convert:

import { ethAddressFromDelegated } from '@glif/filecoin-address'

const ethAddress = ethAddressFromDelegated('f410fabcdef...')
// → '0xabcdef...'

Retrieving Data: IPFS Gateways

After upload, a file is accessible via any IPFS gateway:

const CID = 'bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi'

// Public gateways
const gateways = [
  `https://${CID}.ipfs.w3s.link`,           // Web3.Storage
  `https://${CID}.ipfs.dweb.link`,           // Protocol Labs
  `https://ipfs.io/ipfs/${CID}`,             // Protocol Labs
  `https://cloudflare-ipfs.com/ipfs/${CID}`, // Cloudflare
]

// For production: use own gateway or Cloudflare IPFS
// to not depend on public gateway availability

Own IPFS gateway via Kubo:

docker run -d \
  --name ipfs-node \
  -p 4001:4001 \
  -p 8080:8080 \
  -v /data/ipfs:/data/ipfs \
  ipfs/kubo:latest \
  daemon --migrate=true

Add to nginx reverse proxy for ipfs.yourdomain.com.

Checking Storage Status

// Check that file is actually stored on Filecoin
async function checkFilecoinDeals(cid: string): Promise<Deal[]> {
  const res = await fetch(
    `https://api.filecoin.energy/deals/cid/${cid}`
  )
  const data = await res.json()
  return data.deals.filter((d: Deal) => d.status === 'Active')
}

// Or via Filscan API
async function getDealsByCid(cid: string) {
  const res = await fetch(`https://api.filscan.io/api/v1/deal/list?cid=${cid}`)
  return res.json()
}

Full integration with upload via Web3.Storage, retrieval via IPFS gateway, CID storage in database, and deal verification: 3–5 days including testing.