SDK v4.0 Migration Guide

v3.x → v4.0 — Breaking changes and setup instructions

⚠️ All v3.x SDKs are blocked

The minimum required version is now 4.0.0. Existing v3.x integrations will show a version-blocked error until upgraded.

Breaking Changes

1. Native ZKP Required

snarkjs and circomlibjs have been removed. ZKP proofs are now generated natively via mopro-ffi. Processing will throw ZKP_GENERATION_FAILED if mopro-ffi is not installed.

2. FACT Token Approval Required

Users pay 0.01 FACT per registration. The SDK checks balance before queueing (INSUFFICIENT_FACT_BALANCE) and signs an ERC20 approve transaction before each registration. Wallets receive 50 FACT on creation.

3. Device Attestation Required

iOS: App Attest (iOS 14+) or DeviceCheck fallback. Android: Play Integrity. Processing blocks without attestation. Native modules must be linked.

4. starknet.js v9

Upgraded from ^5.24.0 to ^9.4.2. The SDK handles this internally — no changes needed in your code unless you use starknet.js directly.

Setup

# 1. Update the SDK
npm install @blockfact/react-native-facti-pro@latest

# 2. Run the setup CLI — verifies all native dependencies
npx @blockfact/setup

The setup CLI checks and installs:

  • ✓ mopro-ffi native module
  • ✓ poseidon-lite
  • ✓ poseidon_check_final.zkey circuit asset (iOS + Android)
  • ✓ DeviceCheckModule.swift + .m (iOS)
  • ✓ Play Integrity dependency (Android)
  • ✓ starknet.js v9+

iOS Setup (Manual Steps)

After running npx @blockfact/setup, you still need to:

  1. 1. Add DeviceCheckModule.swift and DeviceCheckModule.m to your Xcode target
  2. 2. Add DeviceCheck.framework to Linked Frameworks
  3. 3. Add poseidon_check_final.zkey to your app bundle (Copy Bundle Resources)
  4. 4. For mopro-ffi: add -force_load flag for libblockfact_zkp.a and set DEAD_CODE_STRIPPING = NO

⚠️ Expo Users

Expo Go is not supported. You must use a development build (npx expo prebuild) or EAS Build to include native modules.

Account / Signer Modes

Standalone Mode

Private key is stored in Keychain via createWallet(). The SDK signs FACT approve transactions automatically. No additional setup needed.

Web3Auth Mode

The SDK does not have access to the Web3Auth private key. Pass your Account instance via the signer parameter:

const { registerContent } = useBlockFact();

// Create Account from Web3Auth provider
const account = new Account({
  provider, address, signer: web3authPrivateKey, cairoVersion: '1'
});

await registerContent({
  filePath: photo.uri,
  latitude, longitude,
  signer: account,  // SDK uses this to sign approve tx
});

New Exports

import {
  BlockFactProvider,
  useBlockFact,
  getFactBalance,       // { balance: bigint, formatted: string }
  ensureFactApproval,   // { approved: boolean, txHash?: string }
  verifyContent,
  checkLocationPermission,
  startLocationWatch,
  stopLocationWatch,
  getCachedLocation,
} from '@blockfact/react-native-facti-pro';

API Changes

POST /api/preprocess

New fields in request body:

  • • device_attestation — App Attest / DeviceCheck / Play Integrity token
  • • owner_address — user's wallet address (triggers V2 user-paid path)

POST /api/deploy-starknet-account

New optional field:

  • • public_key — explicit StarkNet public key (for wallet migration when Web3Auth JWT key ≠ StarkNet key)

GET /api/config

New endpoint. Returns contract configuration consumed by the SDK internally. Developers do not need to call this directly.