Skip to main content

colibri_stateless 3.2.1 copy "colibri_stateless: ^3.2.1" to clipboard
colibri_stateless: ^3.2.1 copied to clipboard

Dart bindings for Colibri Stateless via FFI (proof generation and verification for Ethereum RPC).

Colibri Logo

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.3 (Colibri / npm)
colibri_flutter 3.0.3 (same)

Verify Ethereum RPC data cryptographically — without running a full node.

ETH2.0 Spec Version 1.4.0 License pub

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_summaries proofs, where other light clients simply fail.
  • eth_getLogs completeness 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_call proofs – useAccesslist: true (default) uses eth_createAccessList; set false for legacy debug_traceCall
  • L1 execution RPCs – optional ethRpcsL1 for requests that target the L1 of the configured chain. Empty uses the built-in defaults. Only an EEZ L2 such as RollupX has an L1 that differs from the chain itself (Ethereum mainnet). Requests for the configured chain keep using ethRpcs.
  • Privacy-preserving eth_call – proverMode: hybrid, privacyMode: basic, obliviousNodes (default empty; e.g. https://rpc.safe-node.com/, API key for testing). Setting obliviousNodes auto-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 (or ANDROID_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 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

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.

CI (automated on release tags) #

Pushing a tag vX.Y.Z runs .github/workflows/publish-dart.yml, which builds Flutter natives first, then publishes colibri_stateless and colibri_flutter via OIDC automated publishing (no PUB_TOKEN / long-lived secrets). Only exact vX.Y.Z tags are published (prerelease tags like v1.2.3-rc.1 are not).

One-time setup on pub.dev (Admin → Automated publishing → GitHub Actions) for both packages:

Setting Value
Packages colibri_stateless and colibri_flutter
Repository corpus-core/colibri-stateless
Tag pattern v{{version}} (lockstep versions)
Trigger Enable publishing from push events
Auth OIDC (id-token: write in the workflow)

Automated publishing only works after each package has been published at least once manually. Same-version re-publish is impossible on pub.dev — if Flutter fails after Dart succeeded, publish Flutter manually for that version or cut a new patch tag.

Documentation #

1
likes
160
points
857
downloads

Documentation

Documentation
API reference

Publisher

verified publishercorpuscore.tech

Weekly Downloads

Dart bindings for Colibri Stateless via FFI (proof generation and verification for Ethereum RPC).

Homepage
Repository (GitHub)
View/report issues

License

MIT (license)

Dependencies

ffi, http

More

Packages that depend on colibri_stateless