Colibri Dart Bindings

Dart FFI bindings for Colibri Stateless (proof generation + verification).

Quick Start

Build the native library

./build.sh

This produces a shared library in native/:

macOS: native/libcolibri.dylib
Linux: native/libcolibri.so
Windows: native/colibri.dll

Use in Dart

import 'package:colibri_stateless/colibri.dart';

Future<void> main() async {
final colibri = Colibri(
  chainId: 1,
  libraryPath: 'native/libcolibri.dylib', // adjust for your OS
);

  final blockNumber = await colibri.rpc('eth_blockNumber', []);
  print('Block number: $blockNumber');

  colibri.close();
}

Features

Proof generation + verification through the C core
Async request handling with dart:async
Multi-chain configuration with sensible defaults

You can also set the library path via COLIBRI_DART_LIBRARY.

Flutter (with bundled binaries)

For Flutter apps, use the colibri_flutter package on pub.dev — it includes Android and iOS binaries, so no separate build is required:

dependencies:
  colibri_flutter: ^0.1.0

import 'package:colibri_flutter/colibri_flutter.dart';
final colibri = Colibri(chainId: 1);

See flutter/colibri_flutter/README.md.

iOS (building yourself)

iOS does not allow dynamic dlopen of external libraries. When building yourself, place the XCFramework at bindings/dart/flutter/colibri_flutter/ios/Frameworks/c4_swift.xcframework, or use colibri_flutter from pub.dev (see above).

Build (Debug)

./build_debug.sh

Flutter / Mobile Binaries

From the repository root, one command builds platform-specific binaries for Flutter:

./scripts/build_flutter_binaries.sh

This produces:

Android: bindings/dart/flutter/colibri_flutter/android/src/main/jniLibs/<abi>/libcolibri.so
iOS: bindings/dart/flutter/colibri_flutter/ios/Frameworks/c4_swift.xcframework (macOS only)
Windows: bindings/dart/native/windows/colibri.dll (Windows host only)

Requirements:

Android: ANDROID_NDK_HOME (or ANDROID_NDK) set
iOS: macOS + Xcode (uses bindings/swift/build_ios.sh)
Windows: build on a Windows host

Per-platform:

./scripts/build_flutter_binaries.sh --android
./scripts/build_flutter_binaries.sh --ios
./scripts/build_flutter_binaries.sh --macos    # macOS host; universal dylib
./scripts/build_flutter_binaries.sh --linux    # Linux host
./scripts/build_flutter_binaries.sh --windows

Examples

example/basic_usage.dart — minimal verified RPC call
example/proof_verify.dart — create + verify a proof manually
example/custom_storage.dart — custom storage integration
example/unproofable_rpc.dart — unproofable method routed to direct RPC
example/read_block.dart, example/read_logs.dart, example/contract_call.dart, example/transaction_receipt.dart — more RPC examples

See example/README.md for run commands and optional .env configuration.

Testing

dart test

If the native library lives elsewhere, set COLIBRI_DART_LIBRARY.

Coverage

./test/run_coverage.sh

Coverage output is written to test/coverage/ (LCOV file: test/coverage/lcov.info).

Compare C vs Dart results

From the repository root (requires C build):

export C4_BUILD_DIR=/path/to/cmake/build
./scripts/compare_c_dart_tests.sh

Publishing (pub.dev)

Package version is synced with the repository root. The canonical version is in the repo root file VERSION (same as used for releases). To update the Dart/Flutter package versions from it:

./scripts/sync_version.sh

Then publish colibri_stateless (from a copy that excludes the Flutter plugin, so the package stays small):

./scripts/publish_colibri_stateless.sh --dry-run   # check
./scripts/publish_colibri_stateless.sh             # publish

To publish colibri_flutter (from its own directory; includes Android/iOS binaries):

cd flutter/colibri_flutter
dart pub publish --dry-run
dart pub publish

You will be prompted to log in with a Google account (first time: create publisher or link account at pub.dev).

Recommended: publish from a clean git state and after running dart test.

Documentation

Core docs: https://corpus-core.gitbook.io/specification-colibri-stateless
Bindings overview: https://corpus-core.gitbook.io/specification-colibri-stateless/developer-guide/bindings