orbis1-sdk-rn

Orbis1 SDK for React Native with RGB core, Watch Tower, and Gas-Free transfers.

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

import {
  Wallet,
  generateKeys,
  restoreKeys,
  Interfaces,
} from 'orbis1-sdk-rn';

// Generate new keys
const keys = await generateKeys(Interfaces.BitcoinNetwork.TESTNET);

// Or restore from mnemonic
const restoredKeys = await restoreKeys(
  Interfaces.BitcoinNetwork.TESTNET,
  'your mnemonic phrase here'
);

// Use the Wallet class for RGB operations, transfers, etc.
const wallet = new Wallet(keys, /* ... */);

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, generateKeys, restoreKeys)
│   ├── __tests__/
│   │   └── index.test.tsx
│   └── core/
│       ├── Interfaces.ts      # Types, enums (BitcoinNetwork, Keys, etc.)
│       ├── NativeRgb.ts        # Turbo Module spec / native bridge interface
│       ├── RgbError.ts         # Error types and RgbError class
│       └── Wallet.ts           # Wallet class (RGB ops, transfers, persistence)
│
├── 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             # Example app UI
│   ├── 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, docs], 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

Summary

| Path | Purpose | |------|--------| | src/ | Library TypeScript source and public API; built to lib/ by react-native-builder-bob. | | android/, ios/ | Native SDK implementation (Turbo Modules); linked into apps via the React Native CLI / CocoaPods. | | example/ | Standalone app that depends on the local library; used to run and test the SDK. | | scripts/ | Postinstall and other tooling (e.g. iOS RGB framework download). | | .github/ | CI (lint, typecheck, test, build library, build example on Android and iOS). |

Contributing

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

License

MIT