react-native-fula

React Native bridge for the Fula protocols, providing blockchain operations, blox device management, plugin management, and AI interactions via go-fula/mobile.

Architecture

┌─────────────────────────────────────────────────┐
│ React Native App │
├─────────────────────────────────────────────────┤
│ TypeScript API (fula, blockchain, fxblox, fxAi)│
├───────────────────┬─────────────────────────────┤
│ Android (Java) │ iOS (Swift) │
│ FulaModule.java │ FulaModule.swift │
├───────────────────┼─────────────────────────────┤
│ go-fula/mobile │ go-fula/mobile │
│ (JNI via .aar) │ (Fula framework) │
└───────────────────┴─────────────────────────────┘

The library uses React Native's NativeModules bridge. All heavy operations run on background threads (single-threaded executor on Android, DispatchQueue.global on iOS) to avoid blocking the JS thread. Responses are returned as JSON strings from the native layer and parsed into typed objects in TypeScript.

Installation

npm install @functionland/react-native-fula

iOS

cd ios && pod install

Requires iOS 15.0+.

Android

The Android AAR is fetched automatically from JitPack. Make sure your project-level build.gradle (or the library's own repositories block) includes:

maven { url 'https://jitpack.io' }

Requires minSdkVersion 26+, Java 17.

Usage

The library exports four namespaced modules:

import{fula,blockchain,fxblox,fxAi}from'@functionland/react-native-fula';

fula -- Client Lifecycle

Manages the Fula client: initialization, connectivity, and shutdown.

// Register lifecycle listeners for proper cleanup on app background/terminationawaitfula.registerLifecycleListener();// Create a new client and connect to the blox nodeconstpeerId=awaitfula.newClient(identity,// string -- base64 private key of DID identitystorePath,// string -- local store path (empty string for default)bloxAddr,// string -- blox multiaddr (empty string for testing without backend)exchange,// string -- 'noop' for testing, '' for productionautoFlush,// boolean (default: false) -- flush writes to disk after each operationuseRelay,// boolean (default: true) -- force connection through relayrefresh// boolean (default: false) -- force recreate the fula object);// init() is a backward-compatible alias for newClient.// Returns { peerId, rootCid } where rootCid is always "".const{ peerId, rootCid }=awaitfula.init(identity,storePath,bloxAddr,exchange,autoFlush,rootCid,useRelay,refresh);

// Check if fula is initialized (optionally check filesystem too)constready=awaitfula.isReady(filesystemCheck);// default: true// Check if client can reach the bloxconstconnected=awaitfula.checkConnection(timeout);// timeout in seconds, default 20// Ping blox peer (tries direct -> relay -> DHT fallback)constresult=awaitfula.ping(timeout);// default 60s// result: { success: boolean, successes: number, avg_rtt_ms: number, errors: string[] }// Shut down libp2p and datastore (client must be discarded after this)awaitfula.shutdown();// Shut down and clear all local dataconstsuccess=awaitfula.logout(identity,storePath);

blockchain -- On-Chain Operations

All blockchain operations are relayed through the connected blox node. The client must be initialized first via fula.newClient() or fula.init().

Account Management

// Check if account exists on-chainconst{ account, exists }=awaitblockchain.checkAccountExists(account);// Fund an accountconst{ from, to, amount }=awaitblockchain.accountFund(account);// Get current account infoconst{ account }=awaitblockchain.getAccount();// Query asset balanceconst{ amount }=awaitblockchain.assetsBalance(account,assetId,classId);// Transfer tokens to Fula networkconst{ msg, description }=awaitblockchain.transferToFula(amount,wallet,chain);

Pool Management

// List all poolsconst{ pools }=awaitblockchain.listPools();// pools: [{ poolID, creator, poolName, parent, participants, region }]// Join / leave a poolconstjoined=awaitblockchain.joinPool(poolID);constleft=awaitblockchain.leavePool(poolID);// Join / leave with a specific blockchainconstjoined=awaitblockchain.joinPoolWithChain(poolID,chainName);constleft=awaitblockchain.leavePoolWithChain(poolID,chainName);// Cancel a pending join requestconstcancelled=awaitblockchain.cancelPoolJoin(poolID);// List pending join requests for a poolconst{ poolRequests }=awaitblockchain.listPoolJoinRequests(poolID);// poolRequests: [{ poolID, account, voted, positiveVotes, peerID }]

Storage and Replication

// Upload manifest for multiple CIDsconst{ storer, cid, pool_id }=awaitblockchain.batchUploadManifest(cids,poolId,replicationFactor);// Replicate content in poolconstreplicatedCids=awaitblockchain.replicateInPool(cids,account,poolId);// List available replication requestsconstavailable=awaitblockchain.listAvailableReplicationRequests(poolID);

Blox Info

// Get free space on blox deviceconst{ size, avail, used, used_percentage }=awaitblockchain.bloxFreeSpace();

fxblox -- Device and Plugin Management

Hardware commands, diagnostics, and plugin management for blox devices. Commands are sent over libp2p to the connected blox.

Hardware Commands

const{ status, msg }=awaitfxblox.wifiRemoveall();// Remove all saved WiFi connectionsconst{ status, msg }=awaitfxblox.reboot();// Reboot deviceconst{ status, msg }=awaitfxblox.partition();// Partition device storageconst{ status, msg }=awaitfxblox.eraseBlData();// Erase all blox local data

Diagnostics

// Fetch Docker container logsconst{ status, msg }=awaitfxblox.fetchContainerLogs(containerName,tailCount);// Analyze logs for best/target peersconst{ best, target, err }=awaitfxblox.findBestAndTargetInLogs(containerName,tailCount);// Storage informationconst{ folder_path, size }=awaitfxblox.getFolderSize(folderPath);const{ size, storage_max, count, folder_path, version }=awaitfxblox.getDatastoreSize();// Docker image infoconst{ images }=awaitfxblox.getDockerImageBuildDates();// images: [{ container_name, image_name, image_created, image_digest }]// IPFS cluster infoconst{ cluster_peer_id, cluster_peer_name }=awaitfxblox.getClusterInfo();

Plugin Management

// List all available pluginsconst{ plugins }=awaitfxblox.listPlugins();// plugins: [{ name, description, version, usage, rewards, socials, requiredInputs, approved, installed }]// List currently active pluginsconst{ msg, status }=awaitfxblox.listActivePlugins();// Install / uninstall / update a pluginconstinstalled=awaitfxblox.installPlugin(pluginName,params);constuninstalled=awaitfxblox.uninstallPlugin(pluginName);constupdated=awaitfxblox.updatePlugin(pluginName);// Check plugin statusconst{ status }=awaitfxblox.showPluginStatus(pluginName,lines);const{ status, msg }=awaitfxblox.getInstallStatus(pluginName);const{ status, msg }=awaitfxblox.getInstallOutput(pluginName,params);

fxAi -- AI Chat

Interact with AI models running on the blox device. Responses are streamed over libp2p.

// Start a chat session -- returns a stream IDconststreamID=awaitfxAi.chatWithAI(aiModel,userMessage);// Option 1: Collect all chunks into a single responseconstfullResponse=awaitfxAi.fetchChunksUsingIterator(streamID);// Option 2: Stream chunks with callbacksconstcancel=fxAi.streamChunks(streamID,{onChunk: (chunk)=>console.log(chunk),onComplete: ()=>console.log('done'),onError: (err)=>console.error(err),});// Call cancel() to stop listening// Option 3: Get chunks manually one at a timeconstchunk=awaitfxAi.getChatChunk(streamID);

Deprecated / Dead Code

The following methods still exist in the TypeScript layer (src/protocols/blockchain.ts and src/interfaces/fulaNativeModule.ts) but have no native implementation on either Android or iOS. They were removed from native modules when direct chain/polkadot APIs were dropped. Calling them will result in a runtime error:

• blockchain.createAccount(seed) -- use blox-side account creation instead
• blockchain.createPool(seed, poolName) -- use blox-side pool creation instead
• blockchain.votePoolJoinRequest(seed, poolID, account, accept)
• blockchain.newStoreRequest(seed, poolID, uploader, cid)
• blockchain.removeReplicationRequest(seed, poolID, cid)
• blockchain.removeStorer(seed, storer, poolID, cid)
• blockchain.removeStoredReplication(seed, uploader, poolID, cid)

TODO: Clean up the TypeScript layer to remove these dead methods and their associated types (SeededResponse, PoolCreateResponse, PoolVoteResponse).

Native Dependency Versions

Platform	Dependency	Version	Source
Android	com.github.functionland:fula-build-aar	v1.58.2	JitPack
iOS	Fula (go-fula/mobile)	~> 1.58.2	CocoaPods

Development

Prerequisites

• Node >= 16
• Yarn 1.22+
• For Android: JDK 17, Android SDK with NDK 27.1.12297006
• For iOS: Xcode with iOS 15.0+ SDK

Setup

# Enable corepack (run as admin/sudo)
corepack enable# Install dependencies
yarn install
# Install iOS pods (macOS only)
yarn example pods

Running the Example App

# Android
yarn example android
# iOS
yarn example ios

Scripts

Command	Description
yarn install	Install dependencies
yarn example android	Run example app on Android
yarn example ios	Run example app on iOS
yarn test	Run Jest tests
yarn typecheck	TypeScript type checking
yarn lint	ESLint + Prettier
yarn build:android	Build Android debug APK
yarn build:ios	Build iOS for simulator

Project Structure

src/
index.tsx # Entry point -- re-exports all modules
interfaces/
fulaNativeModule.ts # NativeModules bridge interface
protocols/
fula.ts # Client lifecycle (init, connect, shutdown)
blockchain.ts # On-chain operations (accounts, pools, storage)
fxblox.ts # Device and plugin management
fx-ai.ts # AI chat streaming
types/
blockchain.ts # Blockchain response types
fxblox.ts # Fxblox response types
android/
src/main/java/land/fx/fula/
FulaModule.java # Android native module
FulaPackage.java # React Native package registration
ThreadUtils.java # Single-threaded executor for background work
ios/
Fula.swift # iOS native module (Swift)
Fula.mm # Objective-C++ bridge declarations
Extensions.swift # String/Data/UInt8 utility extensions
example/ # Example React Native app

Related Libraries

Name	Description
go-fula	Core Fula protocol implementation in Go
fula-build-aar	Android .aar build of go-fula/mobile
Fx Fotos	Photo dApp built with react-native-fula

Contributing

See the contributing guide to learn how to contribute to the repository and the development workflow.

License

MIT