orbis1-sdk-rn

Orbis1 SDK for React Native — A modular TypeScript SDK for RGB asset operations with Bitcoin, featuring gas-free transfers and watch tower monitoring.

Features

• 🔐 RGB Wallet Operations — Complete RGB asset lifecycle: issue, send, receive, and manage NIA, UDA, CFA, and IFA assets
• ⚡ Gas-Free Transfers — Transfer RGB assets without holding BTC for mining fees via collaborative transaction signing
• 🗼 Watch Tower — Monitor RGB invoices and receive push notifications for incoming transfers
• 🏗️ Modular Architecture — Enable only the features you need; each feature is independently configurable
• 🔄 New Architecture Ready — Built with React Native's Turbo Modules for optimal performance
• 📱 Cross-Platform — Full support for iOS and Android with native RGB bindings

Prerequisites

• Node.js — Use the version in .nvmrc (e.g. v22.20.0). nvm recommended:

  nvm use

• Yarn — This repo uses Yarn 4 (see packageManager in package.json). Use Yarn for all installs and scripts; npm is not supported for development.
• Android (for running the example on Android):
  • React Native environment setup (Android Studio, JDK 17, Android SDK, etc.)
• iOS (for running the example on iOS):
  • macOS only
  • Xcode and iOS Simulator or device
  • CocoaPods (installed via Bundler in the example app)
  • The iOS native RGB framework (rgb_libFFI.xcframework) is downloaded automatically on yarn (postinstall) when run on macOS.

Installation

To use the SDK in your app:

npm install orbis1-sdk-rn
# or
yarn add orbis1-sdk-rn

Usage

Basic Setup

import {
  Orbis1SDK,
  generateKeys,
  Environment,
  LogLevel,
  BitcoinNetwork,
} from 'orbis1-sdk-rn';

// 1. Generate or restore keys
const keys = await generateKeys(BitcoinNetwork.TESTNET4);

// 2. Configure and create SDK instance
const sdk = new Orbis1SDK({
  apiKey: 'your-api-key',
  environment: Environment.TESTNET4,
  wallet: {
    enabled: true,
    keys,
    supportedSchemas: ['NIA', 'UDA', 'CFA', 'IFA'],
  },
  features: {
    gasFree: { enabled: true },
    watchTower: { enabled: true },
  },
  logging: { level: LogLevel.INFO },
});

// 3. Initialize SDK (registers and boots all enabled features)
await sdk.initialize();

// 4. Get wallet and perform operations
const wallet = sdk.getWallet();
await wallet.goOnline('ssl://electrum.example.com:50053');
await wallet.sync();

const balance = await wallet.getBtcBalance();
const assets = await wallet.listAssets(['NIA', 'CFA']);

Gas-Free Transfers

Transfer RGB assets without holding BTC for mining fees:

// 1. Request fee quote
const quote = await sdk.gasFree().requestFeeQuote({
  assetId: 'rgb:...',
  amount: 1000,
  recipientInvoice: 'rgb:invoice...',
});

console.log(`Service fee: ${quote.serviceFeeAmount} (asset units)`);
console.log(`Quote expires: ${quote.expiresAt}`);

// 2. Confirm transfer (if user accepts quote)
const result = await sdk.gasFree().confirmTransfer(request, quote);

console.log(`Transfer complete! TXID: ${result.txid}`);

Watch Tower Monitoring

Monitor RGB invoices for incoming transfers. Call addToWatchTower with an AddToWatchTowerParams object:

| Field | Required | Description | |-------|----------|-------------| | invoice | Yes | RGB invoice string to monitor | | fcmToken | No | Per-request FCM device token; if omitted, the value from setFcmToken is used when set | | email | No | Email address for notifications | | webPushNotification | No | Web Push subscription (endpoint + keys.p256dh / keys.auth) for browser notifications |

On success, the method resolves to AddToWatchTowerResponse: status, message, and data (including recipient_id, endpoint_url, expiry, and optional echo fields for FCM / email / web push when registered).

// Default FCM for all registrations (optional)
sdk.watchTower().setFcmToken('your-fcm-device-token');

// Register with invoice only, or add email / per-call FCM / web push
await sdk.watchTower().addToWatchTower({
  invoice: 'rgb:invoice...',
  email: '[email protected]',
  // fcmToken: 'override-token',
  // webPushNotification: { endpoint: '...', keys: { p256dh: '...', auth: '...' } },
});

const res = await sdk.watchTower().addToWatchTower({ invoice: 'rgb:...' });
console.log(res.data.recipient_id, res.data.expiry);

Running the repository (development)

This repo is a monorepo with Yarn workspaces: the library lives in the root and an example app in example/.

1. Clone and install

git clone <repo-url>
cd orbis1-sdk-rn

Use the correct Node version:

nvm use
# or: node -v  should match .nvmrc (e.g. v22.20.0)

Install dependencies (required for both library and example):

yarn

• On macOS, yarn runs a postinstall script that downloads the iOS RGB framework (rgb_libFFI.xcframework) into ios/. If it’s already present, the download is skipped.
• Do not use npm install for development; the project relies on Yarn workspaces.

2. Build the library (optional)

The example app uses the library from source. To build the library output (e.g. for publishing or typecheck):

yarn prepare
# or: bob build

3. Run the example app

The example app uses the local library, so JS/TS changes are picked up without rebuilding; native changes require a rebuild.

Start Metro (from repo root):

yarn example start

In another terminal, run the app:

Android:

yarn example android

iOS (first time or after native dependency changes):

From the repo root:

cd example
bundle install
bundle exec pod install --project-directory=ios
cd ..
yarn example ios

Or from example:

cd example
bundle install
cd ios && bundle exec pod install && cd ..
yarn ios

Subsequent runs (if you didn’t change native deps):

yarn example ios

4. Working with native code

• iOS: Open example/ios/Orbis1SdkExample.xcworkspace in Xcode. Library native code is under Pods → Development Pods → orbis1-sdk-rn.
• Android: Open example/android in Android Studio. Library code is under orbis1-sdk-rn.

5. Verify New Architecture

To confirm the example runs with the New Architecture, check the Metro logs for something like:

Running "Orbis1SdkExample" with {"fabric":true,"initialProps":{"concurrentRoot":true},"rootTag":1}

(fabric: true and concurrentRoot: true indicate the New Architecture.)

Scripts (from repo root)

| Command | Description | |--------|-------------| | yarn | Install dependencies (and on macOS, download iOS RGB framework) | | yarn prepare | Build the library (output in lib/) | | yarn typecheck | TypeScript type-check | | yarn lint | Run ESLint | | yarn lint --fix | Fix lint/format issues | | yarn test | Run unit tests (Jest) | | yarn example start | Start Metro for the example app | | yarn example android | Run the example app on Android | | yarn example ios | Run the example app on iOS |

Project structure

orbis1-sdk-rn/
├── .github/                    # CI/CD and GitHub config
│   ├── actions/
│   │   └── setup/               # Reusable workflow: Node, Yarn cache, install
│   │       └── action.yml
│   ├── ISSUE_TEMPLATE/          # Bug report and issue config
│   └── workflows/
│       └── ci.yml              # Lint, typecheck, test, build lib, Android & iOS builds
│
├── android/                    # Native Android module (Kotlin)
│   ├── build.gradle
│   └── src/main/
│       ├── AndroidManifest.xml
│       └── java/com/orbis1sdk/
│           ├── AppConstants.kt      # Build/config constants exposed to JS
│           ├── Orbis1SdkModule.kt  # Turbo Module entry (New Architecture)
│           ├── Orbis1SdkPackage.kt  # Package registration
│           ├── RgbModule.kt        # RGB core native implementation (bridge to rgb lib)
│           ├── RgbPackage.kt       # RGB native package registration
│           └── WalletStore.kt      # Persistent wallet storage
│
├── ios/                        # Native iOS module (Swift + Obj-C)
│   ├── AppConstants.swift      # Build/config constants exposed to JS
│   ├── Orbis1Sdk.h / .mm       # Turbo Module Obj-C bridge
│   ├── Rgb.h / .mm             # RGB module Obj-C bridge
│   ├── Rgb.swift               # RGB Swift API
│   ├── RgbLib.swift            # rgb_libFFI.xcframework bindings
│   ├── WalletStore.swift       # Persistent wallet storage
│   └── (rgb_libFFI.xcframework) # Downloaded by postinstall on macOS
│
├── scripts/
│   └── download-rgb-lib-ios.js # Postinstall: fetches RGB iOS xcframework for macOS
│
├── src/                        # TypeScript/React Native library source
│   ├── index.tsx               # Public API exports
│   ├── Orbis1SDK.ts            # Main SDK class, feature orchestration
│   │
│   ├── core/                   # RGB core functionality
│   │   ├── Interfaces.ts       # Types, enums (BitcoinNetwork, Keys, Assets, etc.)
│   │   ├── KeyManager.ts       # generateKeys, restoreKeys, decodeInvoice
│   │   ├── NativeRgb.ts        # Turbo Module spec / native bridge interface
│   │   ├── RgbError.ts         # RGB-specific error types
│   │   └── Wallet.ts           # Wallet class (RGB operations, transfers, UTXOs)
│   │
│   ├── types/                  # SDK configuration and types
│   │   ├── SDKConfig.ts        # SDKConfig interface, Environment, LogLevel, Zod schemas
│   │   ├── IFeatureModule.ts   # Feature module interface (lifecycle hooks)
│   │   └── Feature.ts          # Feature enum (GAS_FREE, WATCH_TOWER)
│   │
│   ├── errors/                 # Error handling
│   │   ├── OrbisError.ts       # Base SDK error class
│   │   ├── ConfigurationError.ts
│   │   └── FeatureNotEnabledError.ts
│   │
│   ├── features/               # Feature modules
│   │   ├── gas-free/
│   │   │   ├── GasFreeModule.ts # Main gas-free orchestration
│   │   │   ├── client/
│   │   │   │   ├── IServiceClient.ts
│   │   │   │   └── ServiceClient.ts # HTTP client for gas-free service
│   │   │   ├── consignment/
│   │   │   │   ├── IConsignmentReader.ts
│   │   │   │   └── ConsignmentReader.ts # RGB consignment file reader
│   │   │   ├── errors/
│   │   │   │   ├── GasFreeError.ts
│   │   │   │   ├── ConsignmentVerificationError.ts
│   │   │   │   ├── InvalidPSBTError.ts
│   │   │   │   ├── QuoteExpiredError.ts
│   │   │   │   └── ServiceUnavailableError.ts
│   │   │   ├── types/
│   │   │   │   ├── GasFreeConfig.ts
│   │   │   │   ├── GasFreeRequest.ts
│   │   │   │   ├── GasFreeResult.ts
│   │   │   │   └── FeeQuote.ts
│   │   │   └── utils/
│   │   │       ├── retry.ts
│   │   │       └── validation.ts
│   │   │
│   │   └── watch-tower/
│   │       ├── WatchTowerModule.ts # Watch tower feature implementation
│   │       └── types/
│   │           ├── WatchTowerConfig.ts
│   │           ├── WatchTowerRequest.ts
│   │           ├── WatchTowerResponse.ts
│   │           └── index.ts
│   │
│   └── utils/                  # Shared utilities
│       ├── FeatureRegistry.ts  # Feature registration and lifecycle management
│       └── logger.ts           # Logging utilities
│
├── example/                    # Example React Native app (Yarn workspace)
│   ├── android/                # Example app Android project
│   │   ├── app/                # App module (MainActivity, MainApplication, res)
│   │   ├── build.gradle, settings.gradle, gradle.properties
│   │   └── gradlew, gradle/wrapper/
│   ├── ios/                    # Example app iOS project
│   │   ├── Orbis1SdkExample/    # App target (AppDelegate, Info.plist, assets)
│   │   ├── Orbis1SdkExample.xcworkspace  # Open this in Xcode (includes Pods)
│   │   ├── Orbis1SdkExample.xcodeproj/
│   │   ├── Podfile, Podfile.lock
│   │   └── .xcode.env
│   ├── src/
│   │   ├── App.tsx             # Main app with tab navigation
│   │   ├── context/
│   │   │   └── SDKContext.tsx  # SDK provider, initialization lifecycle
│   │   └── screens/
│   │       ├── WalletScreen.tsx     # Wallet operations, balance, assets
│   │       ├── WatchTowerScreen.tsx # Add invoices to watch tower
│   │       └── GasFreeScreen.tsx    # Gas-free transfer demo
│   ├── index.js                # App entry
│   ├── package.json            # Deps: react, react-native; scripts: start, android, ios
│   ├── metro.config.js
│   ├── react-native.config.js  # Links to parent library
│   ├── Gemfile / Gemfile.lock  # CocoaPods via Bundler
│   └── app.json
│
├── lib/                        # Build output (from yarn prepare) — not committed
│   ├── module/                 # Compiled JS (ESM)
│   └── typescript/             # Generated .d.ts
│
├── package.json                # Library manifest, workspaces [example], scripts
├── Orbis1Sdk.podspec           # CocoaPods spec for iOS
├── tsconfig.json / tsconfig.build.json
├── babel.config.js
├── eslint.config.mjs
├── turbo.json                  # Turbo tasks: build:android, build:ios
├── lefthook.yml                # Git hooks (e.g. commitlint)
├── .nvmrc                      # Node version (e.g. v22.20.0)
├── .yarnrc.yml                 # Yarn 4 config, workspace hoisting
├── .yarn/releases/             # Pinned Yarn binary
├── CONTRIBUTING.md
├── CODE_OF_CONDUCT.md
└── LICENSE

Architecture Overview

| Component | Purpose | |-----------|---------| | Orbis1SDK | Main SDK class; orchestrates features, manages lifecycle, provides unified API | | Wallet | RGB wallet operations (issue assets, send/receive, UTXO management, sync) | | GasFreeModule | Coordinates gas-free transfers via external mining inputs and service co-signing | | WatchTowerModule | Monitors RGB invoices and integrates with push notifications | | FeatureRegistry | Manages feature lifecycle (register, initialize, cleanup) | | Native Modules | iOS (Swift/Obj-C) and Android (Kotlin) Turbo Modules bridging rgb-lib |

Key Design Principles

1. Modular Features — Features are optional and independently configurable; enable only what you need

2. Explicit Initialization — Call sdk.initialize() before using any features; lifecycle is clear and predictable

3. Wallet Ownership — Consumers control wallet lifecycle (goOnline, sync, close); SDK never calls these automatically

4. Type Safety — Comprehensive TypeScript types with Zod schema validation for runtime safety

5. Error Handling — Structured error hierarchy (OrbisError → ConfigurationError, FeatureNotEnabledError, GasFreeError, etc.)

6. Ensure the SDK and example app only require 'enabled' for features, with name/environment handled internally.

Example App

The example app (example/) is a fully functional React Native application demonstrating all SDK features. It serves as both a testing ground for SDK development and a reference implementation for integration.

Features Demonstrated

The app has three tabs showcasing different SDK capabilities:

💳 Wallet Tab

• SDK Initialization Lifecycle — Step-by-step visualization of the SDK and wallet initialization process
• Key Generation — Generate new wallet keys or restore from mnemonic
• Balance Display — Real-time BTC balance (vanilla and colored wallets)
• RGB Asset Management — List all assets (NIA, UDA, CFA, IFA) with balances
• Asset Issuance — Issue new RGB assets directly from the app
• Network Operations — Connect to Electrum indexer, sync wallet, refresh balance

🗼 Watch Tower Tab

• Invoice Monitoring — Add RGB invoices to the watch tower service
• Push Notifications — Configure FCM token for transfer notifications
• Status Tracking — View monitored invoices and their status

⚡ Gas-Free Tab

• Two-Stage Transfer Flow:
  1. Request Fee Quote — Get service fee estimate for transfer
  2. Confirm Transfer — Execute gas-free transfer with quote approval
• Progress Tracking — Real-time transfer state visualization (PSBT build → service verification → broadcast → completion)
• Fee Breakdown — Detailed display of who pays mining fees and service fees
• Invoice Parsing — Automatic decoding of RGB invoices with asset/amount validation

Architecture Highlights

• Single SDK Instance — SDKContext.tsx creates one shared SDK instance used by all screens
• Lifecycle Management — Demonstrates proper SDK initialization, wallet lifecycle (goOnline → sync), and cleanup
• Feature Access — Shows how to access features via sdk.gasFree() and sdk.watchTower()
• Error Handling — Comprehensive error display with user-friendly messages
• State Management — Uses React Context for SDK state, demonstrates proper async/await patterns

Running the Example

See Running the repository (development) above for detailed setup instructions.

Quick start:

# From repo root
yarn
cd example
bundle install
cd ios && bundle exec pod install && cd ..
yarn ios  # or: yarn android

The example app connects to testnet4 by default and includes demo API keys for testing. Replace these with your own keys before production use.

Contributing

• Development workflow
• Sending a pull request
• Code of conduct

License

MIT