Інтеграція з Filecoin

Інтеграція з Filecoin

Filecoin — децентралізована мережа зберігання даних з криптографічними доказами того, що дані дійсно зберігаються (Proof of Replication та Proof of Spacetime). Це принципово відрізняє його від IPFS: IPFS — це протокол адресації контенту без гарантій зберігання. Filecoin — це шар зберігання з економічними стимулами та верифіковуваними гарантіями.

У більшості production сценаріїв використовуються обидва: IPFS для швидкого доступу, Filecoin для довгострокового гарантованого зберігання.

Способи інтеграції: прямий vs через агрегатори

Пряма робота з Filecoin через Lotus node складна: потрібно знайти storage provider (SP), узгодити параметри deal (ціна, строк, кількість реплік), дочекатися публікації deal на чейні (~24 години). Для більшості додатків це избыток.

Агрегатори (Web3.Storage, Lighthouse, Storacha) абстрагують складність: ви завантажуєте файл через HTTP API, вони самі керують deals зі storage providers.

Інтеграція через 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()

  // Аутентифікація (один раз)
  // 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
}

// Загрузка одного файлу
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 для доступу через будь-який IPFS gateway
}

Пряма інтеграція через Lotus API

Для випадків, коли вам потрібен повний контроль (вибір SP, параметри deal):

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

const client = new LotusRPC(
  'https://api.node.glif.io/rpc/v0',  // публічний Glif RPC
  { token: process.env.GLIF_TOKEN }
)

// Отримати список storage providers
const miners = await client.stateListMiners([])

// Перевірити репутацію провайдера
const minerInfo = await client.stateMinerInfo(minerAddress, [])
const minerPower = await client.stateMinerPower(minerAddress, [])

// Імпортувати файл у локальний Lotus (потребує запущеного daemon)
// const importResult = await client.clientImport({ Path: '/path/to/file', IsCAR: false })

CAR (Content Addressable Archive) формат

Filecoin зберігає дані у CAR форматі. При роботі з великими файлами потрібно розділити їх на куски:

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,
  }
}

Максимальний розмір одного deal у більшості SP — 32 GB. Для більших файлів потрібно розділяти на частини та робити кілька deals.

Filecoin Virtual Machine (FVM)

З 2023 року Filecoin підтримує EVM-сумісні смарт-контракти через FVM (Filecoin Virtual Machine). Це відкриває можливості для програмованого зберігання:

// Контракт, який автоматично продовжує deals
// Використовує 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);

        // Якщо deal закінчується в течение 30 днів — продовжуємо
        int64 expiryEpoch = activation.terminated;
        // ... логіка продовження
    }
}

FVM адреса відрізняється від EVM: формат f410f... (FEVM адреса) проти стандартного 0x.... Можна конвертувати:

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

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

Отримання даних: IPFS gateways

Після завантаження файл доступен через будь-який IPFS gateway:

const CID = 'bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi'

// Публічні гейтвеї
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
]

// Для production: використовувати власний gateway або Cloudflare IPFS
// щоб не залежати від доступності публічних

Власний IPFS gateway через Kubo:

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

Додайте до nginx reverse proxy для ipfs.yourdomain.com.

Перевірка статусу зберігання

// Перевірити, що файл дійсно зберігається на 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')
}

// Або через Filscan API
async function getDealsByCid(cid: string) {
  const res = await fetch(`https://api.filscan.io/api/v1/deal/list?cid=${cid}`)
  return res.json()
}

Повна інтеграція з завантаженням через Web3.Storage, читанням через IPFS gateway, зберіганням CID у базі та верифікацією deals: 3–5 днів включаючи тестування.