colibri_stateless 3.0.3
colibri_stateless: ^3.0.3 copied to clipboard
Dart bindings for Colibri Stateless via FFI (proof generation and verification for Ethereum RPC).
Colibri Stateless — Dart / Flutter #
Dart FFI bindings for Colibri v2 (package line 0.2.x) — proof generation and verification.
Current package versions:
| Package | Version |
|---|---|
colibri_stateless |
3.0.0 (Colibri / npm) |
colibri_flutter |
3.0.0 (same) |
Verify Ethereum RPC data cryptographically — without running a full node.
Colibri Stateless is a highly efficient prover/verifier for Ethereum (with upcoming support for Layer-2s such as OP-Stack). These Dart FFI bindings wrap the C core and verify every RPC response against the beacon chain — no full node, no continuous sync. Use them standalone (colibri_stateless) or via the Flutter plugin (colibri_flutter) with bundled native binaries.
Website · Docs · Whitepaper · Privacy (PAP)
Why Colibri? #
- Stateless — verification needs nothing but the proof and the sync committee it is checked against. The committee is cached locally so it does not have to travel with every request, but it works just as well with an empty cache or none at all. No persistent state, no full node.
- Cryptographically verified RPC — every RPC response is checked against BLS signatures.
- Offline verification — proofs are fully self-contained and verify without any network connection, thanks to zk-proofs for the sync committee and signed checkpoints.
- On-demand, not always-on — work happens only when you make a request; no background sync burning bandwidth, CPU, or battery.
- Verifies historical data (older than ~27h / 8192 blocks) — via
historical_summariesproofs, where other light clients simply fail. eth_getLogscompleteness proofs — proves no matching log was omitted in the requested range.- Fully verified local transaction simulation — simulate a transaction against verified state before signing.
- Privacy-aware — Pragmatic Adaptive Privacy (PAP) mode. Experimental.
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();
}
Dart-specific features #
- Async request handling with
dart:async - Multi-chain configuration with sensible defaults
- Flutter plugin (
colibri_flutter) with bundled Android/iOS/desktop binaries - Local
eth_callproofs –useAccesslist: true(default) useseth_createAccessList; setfalsefor legacydebug_traceCall - Privacy-preserving
eth_call–proverMode: hybrid,privacyMode: basic,obliviousNodes(default empty; e.g.https://rpc.safe-node.com/, API key for testing). SettingobliviousNodesauto-enables PAP. TEE/ORAM: Oblivious Labs.
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.2.1
import 'package:colibri_flutter/colibri_flutter.dart';
final colibri = Colibri(chainId: 1);
See flutter/colibri_flutter/README.md. On Android and iOS, if you omit storage, the client uses in-memory storage by default (see Colibri constructor docs).
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/colibri_flutter/Frameworks/c4_swift.xcframework, or use colibri_flutter from pub.dev (see above). FFI symbols are retained via force_link.c + -force_load (see the Flutter plugin README troubleshooting section).
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/colibri_flutter/Frameworks/c4_swift.xcframework(macOS only) - Windows:
bindings/dart/native/windows/colibri.dll(Windows host only)
Requirements:
- Android:
ANDROID_NDK_HOME(orANDROID_NDK) set - iOS: macOS + Xcode (uses
bindings/swift/build_ios.sh) - Windows: build on a Windows host
The build script uses -DETH_ZKPROOF=ON when building the C core for ZK proof support.
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 callexample/proof_verify.dart— create + verify a proof manuallyexample/custom_storage.dart— custom storage integrationexample/unproofable_rpc.dart— unproofable method routed to direct RPCexample/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
Alternatively: ./run_tests.sh (handles native library path etc.). 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 matches the Colibri release version used for npm (@corpus-core/colibri-stateless): C4_VERSION / COLIBRI_VERSION, or the exact git tag on HEAD (e.g. v3.0.0 → 3.0.0). Same source as the emscripten CI publish step.
Sync checked-in pubspecs (nearest tag if not on an exact tag):
./scripts/sync_version.sh
./scripts/sync_version.sh --exact # require tag or C4_VERSION
Publish colibri_stateless (temp copy excludes the Flutter plugin; version applied in the copy):
# on a release tag, or: export C4_VERSION=3.0.0
./scripts/publish_colibri_stateless.sh --dry-run
./scripts/publish_colibri_stateless.sh
Publish colibri_flutter (builds natives, then publishes at the same Colibri version; depends on colibri_stateless: ^<version>):
cd flutter/colibri_flutter
./scripts/publish_colibri_flutter.sh --dry-run
./scripts/publish_colibri_flutter.sh
This script builds the Android .so files (requires ANDROID_NDK_HOME) and the iOS XCFramework (requires macOS + Xcode), then runs dart pub publish. The binaries are not checked into git; they are built on demand before each publish.
Alternatively, build binaries separately and publish manually:
./scripts/build_native_libs.sh --all # from flutter/colibri_flutter/
dart pub publish
Or use the repo-root script which also copies binaries into the plugin:
# from repo root
./scripts/build_flutter_binaries.sh --android --ios
cd bindings/dart/flutter/colibri_flutter
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.