# Flutter

Flutter plugin for Colibri Stateless with **bundled native binaries** for Android, iOS, macOS, Linux (and Windows when built on Windows). No manual build or `libraryPath` required on mobile; on desktop you pass the plugin’s bundled library path.

## Overview

**colibri\_flutter** is the same Colibri Dart API as **colibri\_stateless**, packaged as a Flutter plugin with pre-built native libraries. Use it in Flutter apps when you want verified RPC without managing the native build yourself. Flutter web is not supported (no FFI).

### When to use

* **Mobile (Android / iOS)** – Use **colibri\_flutter** from pub.dev; binaries are included.
* **Desktop (macOS / Linux / Windows)** – Use **colibri\_flutter** and pass `libraryPath: colibriFlutterLibraryPath` after building desktop binaries (or use a published package that ships them).

## Installation

### pub.dev (recommended for mobile)

```yaml
dependencies:
  colibri_flutter: ^0.1.5
```

```bash
flutter pub get
```

### Path dependency (development)

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

## Usage

```dart
import 'package:colibri_flutter/colibri_flutter.dart';

// Android/iOS: libraryPath not needed (plugin loads the lib).
// macOS/Linux: use bundled lib path.
final colibri = Colibri(chainId: 1, libraryPath: colibriFlutterLibraryPath);

final blockNumber = await colibri.rpc('eth_blockNumber', []);
colibri.close();
```

* On **Android** and **iOS**, the plugin loads the native library automatically; **colibriFlutterLibraryPath** is `null` and can be omitted.
* On **macOS** and **Linux**, pass **libraryPath: colibriFlutterLibraryPath** so the app uses the plugin’s bundled library (you must have built desktop binaries for it to be present).

## Platform notes

* **Android** – `libcolibri.so` is loaded from the plugin’s `jniLibs` when the engine attaches.
* **iOS** – The XCFramework is linked; no path needed. When building yourself, place it under `ios/Frameworks/` or use the published package.
* **Desktop** – Build binaries from the repo root with `./scripts/build_flutter_binaries.sh --macos` (or `--linux`, `--windows` as appropriate). Requires Android NDK for Android, Xcode on macOS for iOS.
* **Storage** – On Android and iOS, if you omit **storage**, the client uses in-memory storage by default (native file storage is not used on mobile).

## Building native binaries (maintainers)

From the **repository root**:

```bash
./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
./scripts/build_flutter_binaries.sh --linux
./scripts/build_flutter_binaries.sh --windows
```

Output: Android `jniLibs`, iOS XCFramework, and desktop libraries as documented in the main Dart README.

## Further information

* **Plugin README**: [flutter/colibri\_flutter/README.md](https://github.com/corpus-core/colibri-stateless/blob/dev/bindings/dart/flutter/colibri_flutter/README.md)
* **Specification**: [GitBook – Bindings](https://corpus-core.gitbook.io/specification-colibri-stateless/developer-guide/bindings)
* **Pub package**: [colibri\_flutter](https://pub.dev/packages/colibri_flutter)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://corpus-core.gitbook.io/specification-colibri-stateless/developer-guide/bindings/flutter.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.