Filecoin

MeshKit Filecoin support is a persistence bridge. It lets an encrypted MeshKit CID request long-term storage evidence from an HTTP bridge service.

It is not a direct Filecoin client inside Core. Wallets, Boost, Lotus, provider allowlists, pricing rules, renewal automation, and retrieval policy belong in the bridge service that receives MeshKit persistence requests.

Configure The Bridge

{
  "version": 1,
  "provider": {
    "type": "ipfs-http",
    "ipfsApiUrl": "https://ipfs-api.internal.example",
    "metadataApiUrl": "https://meshkit-metadata.internal.example",
    "tokenEnv": "MESHKIT_PROVIDER_TOKEN"
  },
  "persistence": {
    "type": "filecoin-http",
    "endpoint": "https://filecoin.internal.example",
    "tokenEnv": "MESHKIT_FILECOIN_TOKEN"
  }
}

Persist A CID

import { createMeshkit, HttpFilecoinPersistenceProvider, HttpIpfsProvider } from "@meshkit/core";

const mesh = await createMeshkit({
  provider: new HttpIpfsProvider({
    ipfsApiUrl: process.env.MESHKIT_IPFS_API!,
    metadataApiUrl: process.env.MESHKIT_METADATA_API!,
    token: process.env.MESHKIT_PROVIDER_TOKEN,
  }),
  persistence: new HttpFilecoinPersistenceProvider({
    endpoint: process.env.MESHKIT_FILECOIN_ENDPOINT!,
    token: process.env.MESHKIT_FILECOIN_TOKEN,
  }),
});

const file = await mesh.files.put("archive.tar", new Uint8Array([1, 2, 3]));

const proof = await file.persist({
  network: "filecoin",
  replicas: 2,
  durationDays: 365,
  storageProvider: "f01234",
  verifiedDeal: true,
});

console.log(proof.dealId, proof.status);

What Filecoin Proofs Mean

Field	Meaning
`dealId`	Bridge-reported deal identifier
`status`	Bridge-reported lifecycle state
`provider`	Filecoin storage provider when known
`payloadCid` / `pieceCid`	Deal payload or piece identifiers when available
`retrievalUrl`	Optional retrieval endpoint reported by the bridge
`expiresAt`	Bridge-reported expiry

An active deal is not a universal availability or retrieval guarantee. Validate retrieval through the bridge, gateway, or provider path you will use.

Retrieval Boundary

mesh.persistence.retrieve(dealId) calls the configured bridge endpoint and verifies returned bytes against the expected proof CID. Use a gateway, app-owned IPFS infrastructure, or dedicated retrieval service when your product needs a different retrieval policy.

Failure Modes

Symptom	Likely cause	Action
`persistence_not_configured`	No persistence provider was configured	Add a Filecoin bridge provider
Deal status remains queued	Bridge or Filecoin provider has not activated the deal	Inspect bridge logs and provider policy
Active deal cannot retrieve	Deal state is not retrieval evidence	Validate retrieval path separately
Retrieval bytes mismatch	Bridge returned bytes that do not match proof CID	Reject and investigate bridge/provider data

Validation

MESHKIT_LIVE_FILECOIN=1 MESHKIT_FILECOIN_ENDPOINT=https://filecoin.example MESHKIT_FILECOIN_STORAGE=ipfs-http MESHKIT_IPFS_API=http://127.0.0.1:5001 npm run providers:filecoin:live