SDK v5.0.0 Migration Guide

Migrate from v4.x to v5.0.0 — full on-device processing, images never leave the device.

Breaking Changes Summary

• • New peer dependency: blockfact-core — handles Poseidon hash, watermark, .facti build, and MobileCLIP embedding on-device
• • Return type: registerContent() returns factiLocalPath instead of factiUrl
• • Removed props: skipZkp and wsUrl on BlockFactProvider
• • New props: modelUrl and onModelDownloadProgress on BlockFactProvider
• • Setup CLI: npx @blockfact/setup now downloads the MobileCLIP ONNX model (82MB)
• • No image upload: Images are no longer uploaded to S3 — all processing is on-device

Step 1: Update Dependencies

Install the new blockfact-core peer dependency alongside the existing mopro-ffi:

# Remove old install
npm uninstall @blockfact/react-native-facti-pro

# Install v5 with both peer dependencies
npm install @blockfact/react-native-facti-pro@5.0.0 blockfact-core mopro-ffi

Re-run the setup script — it now also downloads the MobileCLIP-S1 ONNX model (82MB) for on-device image embeddings:

Then rebuild native modules:

# iOS
cd ios && pod install && cd ..

# Android — rebuild automatically on next build

Step 2: Update BlockFactProvider Props

Remove skipZkp and wsUrl props. Optionally add modelUrl and onModelDownloadProgress:

// ❌ v4.x
<BlockFactProvider
  apiBase="https://api.blockfact.io"
  skipZkp={false}
  wsUrl="wss://ws.blockfact.io"
>

// ✅ v5.0.0
<BlockFactProvider
  apiBase="https://api.blockfact.io"
  modelUrl="https://cdn.blockfact.io/models/mobileclip-s1.onnx"  // Optional
  onModelDownloadProgress={(p) => console.log(p + '%')}           // Optional
>

Step 3: Update registerContent() Usage

The return type has changed. factiUrl is replaced by factiLocalPath — the .facti file is now built on-device and saved locally:

// ❌ v4.x
const { jobId, status } = await registerContent({ filePath, ... });
// factiUrl was available after job completed (IPFS URL)

// ✅ v5.0.0
const { jobId, status, factiLocalPath } = await registerContent({ filePath, ... });
// factiLocalPath: local file path to the .facti file built on-device

// Optional: pin to IPFS if you need a public URL
const { cid, url } = await uploadToIPFS(factiLocalPath);

Step 4: New Exports

uploadToIPFS(factiPath)

In v4.x, .facti files were automatically uploaded to IPFS via Pinata. In v5, IPFS pinning is optional and explicit:

import { useBlockFact } from '@blockfact/react-native-facti-pro';

const { uploadToIPFS } = useBlockFact();

// After registration completes:
const { cid, url } = await uploadToIPFS(factiLocalPath);
// cid: 'QmXyz...'
// url: 'https://gateway.pinata.cloud/ipfs/QmXyz...'

ensureEmbeddingModel()

Pre-download the MobileCLIP model before the user captures content. Useful for onboarding flows to avoid a download delay on first registration:

import { useBlockFact } from '@blockfact/react-native-facti-pro';

const { ensureEmbeddingModel } = useBlockFact();

// Call during onboarding or app startup
await ensureEmbeddingModel();
// Model is now cached — processContent() won't need to download it

What Changed Under the Hood

Peer Dependencies Reference

Setup CLI Changes

npx @blockfact/setup now performs additional steps in v5:

• • ✅ Verifies mopro-ffi native module (same as v4)
• • ✅ Installs ZKP circuit files — .zkey for iOS + Android (same as v4)
• • ✅ Verifies blockfact-core native module (new)
• • ✅ Downloads MobileCLIP-S1 ONNX model (82MB) from CDN (new)
• • ✅ Verifies DeviceCheck (iOS) / Play Integrity (Android) modules
• • ✅ Verifies starknet.js v9+

FAQ

Do I still need mopro-ffi?

Yes. mopro-ffi handles ZKP proof generation. blockfact-core handles everything else (hash, watermark, embedding, .facti build). Both are required.

What happens to existing .facti files on IPFS?

Existing .facti files on IPFS remain accessible. v5 just changes the default — .facti files are built locally and you choose whether to pin them to IPFS via uploadToIPFS().

When does the MobileCLIP model download?

On first registerContent() call if not already cached. Pre-download with ensureEmbeddingModel() or at build time with npx @blockfact/setup. The model is cached permanently in the app's Documents directory.

Support

• 📧 Email: support@blockfact.io
• 💬 Discord: Join our community
• 🐛 GitHub: Report issues