Интеграция с 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 адрес) vs стандартного 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 дней включая тестирование.