colibri_flutter 0.1.8

Flutter plugin for Colibri Stateless with bundled native binaries (Android, iOS, macOS, Linux). Proof generation and verification for Ethereum RPC.

Colibri Flutter

Flutter plugin for Colibri Stateless with bundled native binaries (Android, iOS, macOS, Linux). No manual build or libraryPath needed on mobile; on desktop use colibriFlutterLibraryPath.

Install (pub.dev)

dependencies:
  colibri_flutter: ^0.1.7

Then:

flutter pub get

Usage

import 'package:colibri_flutter/colibri_flutter.dart';

// On Android/iOS: no libraryPath. On macOS/Linux: use bundled lib path.
final colibri = Colibri(chainId: 1, libraryPath: colibriFlutterLibraryPath);
final block = await colibri.rpc('eth_blockNumber', []);
colibri.close();

On Android and iOS the native library is loaded automatically; colibriFlutterLibraryPath is null there. On macOS and Linux, pass colibriFlutterLibraryPath so the plugin's bundled library is used.

Flutter web is not supported (no native FFI). Use Android, iOS, macOS, Linux, or Windows.

If you use assets/.env for configuration: do not commit real secrets; use other configuration (e.g. environment or secure storage) for production.

Testing the plugin

1. Run the example app (from this repo):

cd bindings/dart/flutter/colibri_flutter/example
flutter pub get
flutter run
# Pick a device (e.g. Android emulator or iOS simulator), then tap "Fetch block number".

2. In your own app

• Add dependency: colibri_flutter: ^0.1.7 (and run flutter pub get).
• Use the same constructor so the plugin's library is used on all platforms:

final colibri = Colibri(chainId: 1, libraryPath: colibriFlutterLibraryPath);

• Android: The plugin loads libcolibri.so from jniLibs when the engine attaches. No path needed; colibriFlutterLibraryPath is null.
• iOS: The XCFramework is linked into the app; no path needed.
• macOS / Linux: You must pass colibriFlutterLibraryPath and have built the desktop binaries (see "Building native binaries" below).

3. If the app crashes on the first Colibri call

• Android: Ensure the plugin's jniLibs contain libcolibri.so for your ABI (arm64-v8a, armeabi-v7a, x86_64). If you depend on the published package, they are included. If you use a path dependency, run ./scripts/build_native_libs.sh --android from the plugin directory or ./scripts/build_flutter_binaries.sh --android from the repo root.
• iOS: Ensure the XCFramework is present under ios/Frameworks/ in the plugin (run ./scripts/build_native_libs.sh --ios from the plugin directory, or ./scripts/build_flutter_binaries.sh --ios from the repo root).
• Desktop: Pass libraryPath: colibriFlutterLibraryPath and ensure you have run the build script for macOS/Linux so the bundled lib exists.

Local / path dependency

For development against a local colibri_stateless:

dependencies:
  colibri_flutter:
    path: /path/to/colibri-stateless/bindings/dart/flutter/colibri_flutter
  colibri_stateless:
    path: /path/to/colibri-stateless/bindings/dart

Building native binaries (for maintainers)

Native binaries (.so, .xcframework) are not checked into git. They must be built before publishing or when using a path dependency from a local checkout.

From this directory (recommended):

./scripts/build_native_libs.sh --all
# Or per platform:
./scripts/build_native_libs.sh --android   # requires ANDROID_NDK_HOME
./scripts/build_native_libs.sh --ios       # macOS + Xcode only

Or from the repo root (also builds macOS/Linux/Windows desktop binaries):

./scripts/build_flutter_binaries.sh
# Or per platform:
./scripts/build_flutter_binaries.sh --android
./scripts/build_flutter_binaries.sh --ios
./scripts/build_flutter_binaries.sh --macos   # macOS only (universal arm64 + x86_64)
./scripts/build_flutter_binaries.sh --linux   # Linux host only
./scripts/build_flutter_binaries.sh --windows

Output locations:

• android/src/main/jniLibs/<abi>/libcolibri.so
• ios/Frameworks/c4_swift.xcframework
• macos/Frameworks/libcolibri.dylib (universal; repo-root script only)
• linux/lib/libcolibri.so (repo-root script only)

Publishing (pub.dev)

1. Publish colibri_stateless first from bindings/dart.
2. Build binaries and publish in one step:

./scripts/publish_colibri_flutter.sh --dry-run   # build + check
./scripts/publish_colibri_flutter.sh             # build + publish

The publish script calls build_native_libs.sh --all, verifies the binaries exist, then runs dart pub publish.

3. Repository verification: pub.dev expects the repository URL to clone to a repo that contains a pubspec.yaml with name: colibri_flutter at root. This package lives in a monorepo subdirectory, so to pass that check either:
   • Option A: Create a mirror repo (e.g. corpus-core/colibri-flutter) with this directory's contents at root. Push the mirror, set repository: https://github.com/corpus-core/colibri-flutter in pubspec.yaml, then publish.
   • Option B: Run ./scripts/prepare_pub_mirror.sh from this directory to copy the package into a sibling folder; push that folder as the mirror repo, then set repository in pubspec to the mirror URL and publish.
4. Manual alternative: dart pub publish --dry-run, then dart pub publish (after building binaries separately).

iOS note

iOS does not allow dynamic dlopen of external libraries. The XCFramework is linked into the app; the Dart FFI loader uses DynamicLibrary.process().