React Native Pro SDK

Complete SDK for blockchain-verified content registration with StarkNet wallet management, on-device zero-knowledge proofs, offline queue, and enterprise telemetry.

Installation

Native Setup

Run the setup script to install native ZKP libraries, circuit files, and the MobileCLIP embedding model (82MB, downloaded from CDN):

See the Native Module Setup Guide for platform-specific details.

Peer Dependencies

npm install react-native-get-random-values
npm install react-native-keychain
npm install react-native-encrypted-storage
npm install react-native-blob-util
npm install @react-native-community/netinfo
npm install react-native-device-info

iOS Setup

cd ios && pod install && cd ..

Quick Start

1. Wrap Your App

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

export default function App() {
  return (
    <BlockFactProvider apiBase="https://api.blockfact.io">
      <YourApp />
    </BlockFactProvider>
  );
}

2. Create a Wallet

Two modes — standalone (no Web3Auth needed) or Web3Auth:

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

function WalletScreen() {
  const { wallet, createWallet, hasWallet } = useBlockFact();

  // Standalone — generates keypair, deploys on-chain
  const handleStandalone = () => createWallet();

  // Or with Web3Auth
  const handleWeb3Auth = () => createWallet({ idToken: web3authToken });

  if (!hasWallet) {
    return <Button title="Create Wallet" onPress={handleStandalone} />;
  }

  return <Text>Wallet: {wallet.address}</Text>;
}

3. Register Content

function CameraScreen() {
  const { registerContent } = useBlockFact();

  const handleCapture = async (photo) => {
    const { jobId, status } = await registerContent({
      filePath: photo.uri,
      filename: photo.fileName || 'photo.jpg',  // from camera response
      mime: photo.type || 'image/jpeg',          // defaults to image/jpeg
      latitude: position.coords.latitude,
      longitude: position.coords.longitude,
    });

    // Job is queued — processes automatically
    // Survives app kills, resumes on relaunch
    // Auto-retries when network returns
    console.log('Queued:', jobId);
  };
}

API Reference

BlockFactProvider

<BlockFactProvider
  apiBase="https://api.blockfact.io"  // Required
  modelUrl="https://cdn.blockfact.io/models/mobileclip-s1.onnx"  // Optional — custom model CDN
  onModelDownloadProgress={(progress) => {           // Optional — 0-100
    console.log('Model download:', progress + '%');
  }}
  telemetry={{                              // Optional — enterprise only
    enabled: true,
    apiKey: 'ent_live_abc123',
    tags: { organizationId: 'acme-corp', sourceId: 'tablet-001' }
  }}
>
  {children}
</BlockFactProvider>

useBlockFact()

const {
  // State
  wallet,           // { address, mode, userId, publicKey? }
  loading,          // boolean
  error,            // string | null
  blocked,          // boolean — true if SDK version is too old
  sdkVersion,       // string — e.g. "5.0.0"
  hasWallet,        // boolean
  queue,            // UploadQueue instance

  // Functions
  createWallet,     // (params?) => Promise<Wallet>
  registerContent,  // (params) => Promise<{ jobId, status }>
  deleteWallet,     // () => Promise<void>
  uploadToIPFS,     // (factiPath: string) => Promise<{ cid, url }>
  ensureEmbeddingModel, // () => Promise<void> — pre-downloads MobileCLIP model
} = useBlockFact();

createWallet(params?)

// Standalone mode — no Web3Auth dependency
const wallet = await createWallet();
// or with custom user ID
const wallet = await createWallet({ userId: 'user-123' });

// Web3Auth mode
const wallet = await createWallet({ idToken: web3authJWT });

// Returns:
{
  address: string,      // StarkNet address (0x...)
  mode: 'standalone' | 'web3auth',
  userId: string,
  publicKey?: string,   // Only in standalone mode
}

registerContent(params)

const { jobId, status, factiLocalPath } = await registerContent({
  filePath: string,       // Required — local file path
  filename?: string,      // Default: 'photo.jpg'
  mime?: string,          // Default: 'image/jpeg'
  latitude?: number,      // GPS latitude
  longitude?: number,     // GPS longitude
  metadata?: object,      // Custom metadata
});

// Returns immediately — job processes in background
// {
//   jobId: 'abc123',
//   status: 'queued',
//   factiLocalPath: '/path/to/Documents/facti/abc123.facti'  // NEW in v5
// }

// To optionally pin to IPFS:
const { cid, url } = await uploadToIPFS(factiLocalPath);

Upload Queue

const { queue } = useBlockFact();

// Monitor jobs
queue.jobs          // All jobs
queue.pending       // Jobs not yet completed

// Subscribe to changes
const unsub = queue.subscribe(() => {
  console.log('Queue updated:', queue.jobs);
});

// Remove a job
await queue.removeJob(jobId);

// Job statuses:
// 'queued' → 'processing' → 'completed'
//                          → 'failed'
//                          → 'waiting_network' (auto-resumes)

Processing Pipeline

Enterprise Telemetry

Enterprise customers can enable telemetry for fleet monitoring, anomaly detection, and audit trails. Free users are completely unaffected — no API key means no telemetry.

<BlockFactProvider
  apiBase="https://api.blockfact.io"
  telemetry={{
    enabled: true,
    apiKey: 'ent_live_abc123',  // From enterprise dashboard
    tags: {
      organizationId: 'acme-corp',
      projectId: 'field-ops',
      sourceId: 'tablet-001',   // For fleet tracking
    }
  }}
>

Events tracked automatically:

• • source.sdk_initialized — SDK startup with device info
• • source.health_check — Every 5 minutes (queue depth, network status)
• • source.sdk_outdated — When newer version available
• • content.captured — When registerContent() is called
• • content.registered — Successful blockchain registration
• • content.registration_failed — Failed registration

Version Gate

The SDK checks the minimum required version on startup. If your version is too old, blocked will be true and all operations will throw with an upgrade message.

const { blocked, error, sdkVersion } = useBlockFact();

if (blocked) {
  return <Text>{error}</Text>;
  // "SDK v2.5.1 is blocked. Minimum required: v3.0.0. Please upgrade to v3.2.0."
}

Standalone Verification

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

const result = await verifyContent('https://ipfs.io/ipfs/Qm.../file.facti');
// { valid: true, metadata: { ... } }

Error Handling

try {
  const { jobId } = await registerContent({...});
} catch (error) {
  if (error.message.includes('blocked')) {
    // SDK version too old — must upgrade
  } else if (error.message.includes('No wallet')) {
    await createWallet();
  } else if (error.message.includes('filePath')) {
    // Missing required param
  }
}

Security Features

• ✅ On-Device Processing: Images never leave the device — hash, watermark, embedding, .facti all built locally
• ✅ Native ZKP: Groth16 proofs generated on-device via Mopro/Arkworks in <1s
• ✅ Biometric Protection: Face ID, Touch ID, Fingerprint for key access
• ✅ Encrypted Storage: Queue and wallet data encrypted at rest
• ✅ Device Attestation: iOS DeviceCheck / Android Play Integrity (when available)
• ✅ Idempotency: Duplicate registrations prevented via content-derived keys
• ✅ Version Gate: Server-controlled minimum SDK version enforcement
• ✅ Blockchain Verification: Immutable StarkNet registration
• ✅ IPFS Storage: Decentralized .facti file hosting via Pinata

Migration from v4.x

Migration from v3.x

Migration from v2.x

Support

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