flutter_rgb

A Flutter plugin for the RGB protocol. This library allows you to issue new assets, manage RGB assets, and perform transfers on top of the Bitcoin network.

This library uses rgb-lib-swift for iOS and rgb-lib-kotlin for Android.

Table of Contents

• Features
• Installation
• Project Structure
• Usage Guide
  • Initialization
  • Issuing Assets
  • Receiving Assets
  • Sending Assets
• API Reference
• Troubleshooting

Features

• Complete RGB wallet functionality.
• Support for multiple asset schemas:
  • NIA (Non-Inflatable Asset)
  • CFA (Collectible Fungible Asset)
  • UDA (Unique Digital Asset)
  • IFA (Inflatable Fungible Asset)
• Bitcoin balance and transfer management.
• PSBT signing and management.
• Support for various transport endpoints.

Installation

Add flutter_rgb to your pubspec.yaml:

dependencies:
  flutter_rgb:
    git:
      url: https://github.com/Orbis-1/flutter_rgb.git

iOS Setup

The iOS FFI framework (rgb_libFFI.xcframework) is automatically downloaded during pod install via a prepare command. No manual download is required.

Android Setup

The library consumes the Maven dependency org.rgbtools:rgb-lib-android. Ensure your project has mavenCentral() in the repository list.

Project Structure

flutter_rgb/
├── android/          # Android native implementation (Kotlin)
├── ios/              # iOS native implementation (Swift)
├── lib/              # Dart API
│   ├── flutter_rgb.dart    # Main entry point (FlutterRgb class)
│   ├── types.dart          # Data models and enums
│   └── src/wallet.dart     # High-level Wallet class
├── scripts/          # Utility scripts (e.g., download_ios_lib.sh)
└── example/          # Example usage application

Usage Guide

Initialization

import 'package:flutter_rgb/flutter_rgb.dart';

// 1. Generate keys
final keys = await FlutterRgb.generateKeys(BitcoinNetwork.testnet.name.toUpperCase());

// 2. Initialize a wallet instance
final wallet = Wallet(keys, network: BitcoinNetwork.testnet.name.toUpperCase());

// 3. Go online
await wallet.goOnline("ssl://mempool.space:50002");

Issuing Assets (NIA)

final asset = await wallet.issueAssetNia(
  ticker: "MYASSET",
  name: "My Asset",
  precision: 0,
  amounts: [1000],
);

Receiving Assets

final receiveData = await wallet.blindReceive(
  assignment: Assignment(type: AssignmentType.fungible, amount: 100),
  transportEndpoints: ["rpc://proxyserver.com:3000/json-rpc"],
  minConfirmations: 1,
);

print("Invoice: ${receiveData.invoice}");

Sending Assets

await wallet.send(
  recipientMap: {
    assetId: [
      Recipient(
        recipientId: "rgb:...",
        assignment: Assignment(type: AssignmentType.fungible, amount: 100),
        transportEndpoints: ["rpc://proxyserver.com:3000/json-rpc"],
      ),
    ],
  },
  donation: false,
  feeRate: 1.5,
  minConfirmations: 1,
);

API Reference

Wallet Class (High-Level)

Method	Returns	Description
generateKeys(network)	Future<Keys>	Generates a new mnemonic and derived account xpubs.
restoreKeys(network, mnemonic)	Future<Keys>	Restores keys from an existing mnemonic.
goOnline(indexerUrl, [skipCheck])	Future<void>	Connects the wallet to an Electrum server.
getBtcBalance([skipSync])	Future<BtcBalance>	Gets the current Bitcoin balance.
getAddress()	Future<String>	Generates a new Bitcoin address.
issueAssetNia(...)	Future<AssetNia>	Issues a new NIA asset.
issueAssetCfa(...)	Future<AssetCfa>	Issues a new CFA asset.
issueAssetUda(...)	Future<AssetUda>	Issues a new UDA asset.
issueAssetIfa(...)	Future<AssetIfa>	Issues a new IFA asset.
listAssets(schemas)	Future<Assets>	Lists all assets matching the provided schemas.
listTransfers(assetId)	Future<List<Transfer>>	Lists transfers for a specific asset.
listUnspents(...)	Future<List<Unspent>>	Lists unspent transaction outputs.
send(...)	Future<OperationResult>	Executes an RGB asset transfer.
sync()	Future<void>	Synchronizes the wallet state with the network.

FlutterRgb Class (Low-Level)

Static methods that map directly to the platform channel. Use this if you need to manage multiple wallet IDs manually.

Data Types (types.dart)

• Keys: Contains mnemonic, xpub, accountXpubVanilla, accountXpubColored, masterFingerprint.
• BtcBalance: Contains vanilla and colored balances.
• Assignment: Defines amount and AssignmentType (fungible, nonFungible, etc.).
• ReceiveData: Contains invoice, recipientId, and expirationTimestamp.

Troubleshooting

iOS build fails with "xcframework missing"

The pod install command should automatically download the framework. If it fails, you can run the download script manually:

sh scripts/download_ios_lib.sh

Android minSdkVersion

Ensure your android/app/build.gradle has a minSdkVersion of at least 24.