SDK Overview

This is the React Native SDK for RGB client applications. It provides a complete set of TypeScript/React Native bindings for interacting with the RGB Node and managing RGB-based transfers.

Note: This is the React Native version of the original RGB SDK for Node.js. If you're building a Node.js application, use the original SDK instead.

RGB Node: This SDK requires an RGB Node instance to function. For more information about RGB Node, including setup instructions, public endpoints and API documentation, see the RGB Node repository.

🧰 What You Can Do with This Library

With this SDK, developers can:

• Generate RGB invoices
• Create and manage UTXOs
• Sign PSBTs using local private keys or hardware signing flows
• Fetch asset balances, transfer status, and other RGB-related state

⚙️ Capabilities of rgb-sdk-rn (via WalletManager)

| Method | Description | |--------|-------------| | registerWallet() | Register wallet with the RGB Node | | getBtcBalance() | Get on-chain BTC balance | | getAddress() | Get a derived deposit address | | getXpub() | Get wallet's extended public keys (xpub_van, xpub_col) | | getNetwork() | Get wallet's network | | listUnspents() | List unspent UTXOs | | listAssets() | List RGB assets held | | getAssetBalance(asset_id) | Get balance for a specific asset | | createUtxosBegin({ up_to, num, size, fee_rate }) | Start creating new UTXOs | | createUtxosEnd({ signed_psbt }) | Finalize UTXO creation with a signed PSBT | | createUtxos({ up_to, num, size, fee_rate }) | Complete UTXO creation: begin → sign → end | | blindReceive({ asset_id, amount }) | Generate blinded UTXO for receiving | | witnessReceive({ asset_id, amount }) | Generate witness UTXO for receiving | | issueAssetNia({...}) | Issue a new Non-Inflationary Asset | | signPsbt(psbt, mnemonic?) | Sign PSBT using mnemonic/seed (async) | | signMessage(message) | Produce a Schnorr signature for an arbitrary message (requires seed) | | verifyMessage(message, signature, accountXpub?) | Verify Schnorr message signatures | | refreshWallet() | Sync and refresh wallet state | | syncWallet() | Trigger wallet sync without additional refresh logic | | listTransactions() | List BTC-level transactions | | listTransfers(asset_id) | List RGB transfer history for asset | | failTransfers(...) | Mark expired transfers as failed | | sendBegin(...) | Prepare an RGB asset transfer (build unsigned PSBT) | | sendEnd(...) | Submit signed PSBT to complete RGB asset transfer | | send(...) | Complete RGB asset send operation: begin → sign → end | | sendBtcBegin(...) | Prepare a BTC send (build unsigned PSBT) | | sendBtcEnd({ signed_psbt }) | Submit signed PSBT to complete BTC send | | sendBtc(...) | Complete BTC send operation: begin → sign → end | | estimateFeeRate(blocks) | Get fee estimation for target block confirmation | | estimateFee(psbtBase64) | Estimate fee for a PSBT | | decodeRGBInvoice({ invoice }) | Decode RGB invoice to transfer parameters | | createBackup(password) | Create an encrypted wallet backup on the RGB node | | downloadBackup(backupId?) | Download the generated backup binary | | restoreFromBackup({ backup, password, ... }) | Restore wallet state from a backup file |

Standalone Functions (not WalletManager methods)

| Function | Description | |----------|-------------| | createWallet(network) | Generate new wallet keypair with mnemonic/xpub/xpriv/master fingerprint | | createWalletManager(params) | Factory function to create WalletManager instance | | generateKeys(network) | Generate new wallet keypair (same as createWallet) | | deriveKeysFromMnemonic(network, mnemonic) | Derive wallet keys (xpub/xpriv) from existing mnemonic | | deriveKeysFromSeed(network, seed) | Derive wallet keys (xpub/xpriv) directly from a BIP39 seed |

🧩 Notes for Custom Integration

• All communication with the RGB Node is handled via HTTP API calls encapsulated in the RGBClient class.
• The signPsbt method is async and demonstrates how to integrate a signing flow using bdk-rn. This can be replaced with your own HSM or hardware wallet integration if needed.
• By using this SDK, developers have full control over:
  • Transfer orchestration
  • UTXO selection
  • Invoice lifecycle
  • Signing policy

This pattern enables advanced use cases, such as:

• Integrating with third-party identity/auth layers
• Applying custom fee logic or batching
• Implementing compliance and audit tracking

Getting Started

Prerequisites

Before using this SDK, you'll need an RGB Node instance running. You can:

• Use the public RGB Node endpoints (testnet/mainnet) - see RGB Node repository for details
• Self-host your own RGB Node instance - see RGB Node repository for setup instructions

Installation

npm install rgb-sdk-rn

React Native Setup

This SDK is designed for React Native applications and uses native modules (via bdk-rn). For setup instructions with Expo, see EXPO_SETUP.md.

Important Notes:

• This is the React Native version of the RGB SDK. For Node.js applications, use the original SDK.
• This library is not compatible with browser environments. It requires React Native's native module system.

Basic Usage

const { WalletManager, createWallet } = require('rgb-sdk-rn');

// 1. Generate wallet keys
const keys = await createWallet('regtest');
console.log('Master Fingerprint:', keys.master_fingerprint);
console.log('Master XPriv:', keys.xpriv); // Store securely!

// 2. Initialize wallet (constructor-based)
const wallet = new WalletManager({
    xpub_van: keys.account_xpub_vanilla,
    xpub_col: keys.account_xpub_colored,
    master_fingerprint: keys.master_fingerprint,
    mnemonic: keys.mnemonic,
    network: 'regtest',
    rgb_node_endpoint: 'http://127.0.0.1:8000' // RGB Node endpoint
});

// 3. Get wallet address
const address = await wallet.getAddress();
console.log('Wallet address:', address);

// 4. Check balance
const balance = await wallet.getBtcBalance();
console.log('BTC Balance:', balance);

Core Workflows

Wallet Initialization

const { WalletManager, createWallet } = require('rgb-sdk-rn');

// Generate new wallet keys
const keys = await createWallet('regtest');

// Initialize wallet with keys (constructor-based - recommended)
const wallet = new WalletManager({
    xpub_van: keys.account_xpub_vanilla,
    xpub_col: keys.account_xpub_colored,
    master_fingerprint: keys.master_fingerprint,
    mnemonic: keys.mnemonic,
    network: 'regtest', // 'mainnet', 'testnet', 'signet', or 'regtest'
    rgb_node_endpoint: 'http://127.0.0.1:8000' // RGB Node endpoint
});

// Register wallet with RGB Node
await wallet.registerWallet();

// Alternative: Derive keys from existing mnemonic
const { deriveKeysFromMnemonic } = require('rgb-sdk-rn');
const restoredKeys = await deriveKeysFromMnemonic('testnet', 'abandon abandon abandon...');
const restoredWallet = new WalletManager({
    xpub_van: restoredKeys.account_xpub_vanilla,
    xpub_col: restoredKeys.account_xpub_colored,
    master_fingerprint: restoredKeys.master_fingerprint,
    mnemonic: restoredKeys.mnemonic,
    network: 'testnet',
    rgb_node_endpoint: 'http://127.0.0.1:8000'
});

// Alternative: Using factory function
const { createWalletManager } = require('rgb-sdk-rn');
const wallet2 = createWalletManager({
    xpub_van: keys.account_xpub_vanilla,
    xpub_col: keys.account_xpub_colored,
    master_fingerprint: keys.master_fingerprint,
    mnemonic: keys.mnemonic,
    network: 'regtest',
    rgb_node_endpoint: 'http://127.0.0.1:8000'
});

UTXO Management

// Step 1: Begin UTXO creation
const psbt = await wallet.createUtxosBegin({
    up_to: true,
    num: 5,
    size: 1000,
    fee_rate: 1
});

// Step 2: Sign the PSBT (async operation)
const signed_psbt = await wallet.signPsbt(psbt);

// Step 3: Finalize UTXO creation
const utxosCreated = await wallet.createUtxosEnd({ signed_psbt });
console.log(`Created ${utxosCreated} UTXOs`);

Asset Issuance

// Issue a new NIA
const asset = await wallet.issueAssetNia({
    ticker: "USDT",
    name: "Tether USD",
    amounts: [1000, 500],
    precision: 6
});

console.log('Asset issued:', asset.asset?.assetId);

Asset Transfers

// Create blind receive for receiving wallet
const receiveData = await receiverWallet.blindReceive({
    asset_id: asset_id,
    amount: 100
});

// Step 1: Begin asset transfer
const sendPsbt = await senderWallet.sendBegin({
    invoice: receiveData.invoice,
    fee_rate: 1,
    min_confirmations: 1
});

// Step 2: Sign the PSBT (async operation)
const signed_send_psbt = await senderWallet.signPsbt(sendPsbt);

// Step 3: Finalize transfer
const sendResult = await senderWallet.sendEnd({ 
    signed_psbt: signed_send_psbt 
});

// Alternative: Complete send in one call
const sendResult2 = await senderWallet.send({
    invoice: receiveData.invoice,
    fee_rate: 1,
    min_confirmations: 1
});

// Refresh both wallets to sync the transfer
await senderWallet.refreshWallet();
await receiverWallet.refreshWallet();

BTC Transfers

// Send BTC using the complete flow
const txid = await wallet.sendBtc({
    recipient: 'bc1q...',
    amount: 10000, // satoshis
    fee_rate: 1,
    min_confirmations: 1
});

// Or use the step-by-step approach
const btcPsbt = await wallet.sendBtcBegin({
    recipient: 'bc1q...',
    amount: 10000,
    fee_rate: 1,
    min_confirmations: 1
});
const signedBtcPsbt = await wallet.signPsbt(btcPsbt);
const btcTxid = await wallet.sendBtcEnd({ signed_psbt: signedBtcPsbt });

Fee Estimation

// Get fee rate estimation for target block confirmation
const feeEstimate = await wallet.estimateFeeRate(6); // 6 blocks
console.log('Fee rate:', feeEstimate.fee_rate);

// Estimate fee for a specific PSBT
const psbtFee = await wallet.estimateFee(psbtBase64);
console.log('Estimated fee:', psbtFee.fee, 'satoshis');

Invoice Decoding

// Decode an RGB invoice to see transfer parameters
const decoded = await wallet.decodeRGBInvoice({
    invoice: 'rgb1:...'
});
console.log('Transfer details:', decoded);

Wallet Information

// Get wallet's extended public keys
const xpubs = wallet.getXpub();
console.log('Vanilla xpub:', xpubs.xpub_van);
console.log('Colored xpub:', xpubs.xpub_col);

// Get wallet's network
const network = wallet.getNetwork();
console.log('Network:', network);

Simplified UTXO Creation

// Create UTXOs in one call (begin → sign → end)
const utxosCreated = await wallet.createUtxos({
    up_to: true,
    num: 5,
    size: 1000,
    fee_rate: 1
});
console.log(`Created ${utxosCreated} UTXOs`);

Balance and Asset Management

// Get BTC balance
const btcBalance = await wallet.getBtcBalance();

// List all assets
const assets = await wallet.listAssets();

// Get specific asset balance
const assetBalance = await wallet.getAssetBalance(assetId);

// List unspent UTXOs
const unspents = await wallet.listUnspents();

// List transactions
const transactions = await wallet.listTransactions();

// List transfers for specific asset
const transfers = await wallet.listTransfers(asset_id);

Setup wallet and issue asset

const { WalletManager, createWallet } = require('rgb-sdk-rn');

async function demo() {
    // 1. Generate and initialize wallet
    const keys = await createWallet('regtest');
    const wallet = new WalletManager({
        xpub_van: keys.account_xpub_vanilla,
        xpub_col: keys.account_xpub_colored,
        master_fingerprint: keys.master_fingerprint,
        mnemonic: keys.mnemonic,
        network: 'regtest',
        rgb_node_endpoint: 'http://127.0.0.1:8000'
    });

    // 2. Register wallet
    await wallet.registerWallet();

    // 3. Get address and balance
    const address = await wallet.getAddress();

    // TODO: Send some BTC to this address for fees and UTXO creation
    const balance = await wallet.getBtcBalance();

    // 4. Create UTXOs 
    const psbt = await wallet.createUtxosBegin({
        up_to: true,
        num: 5,
        size: 1000,
        fee_rate: 1
    });
    const signed_psbt = await wallet.signPsbt(psbt); // Async operation
    const utxosCreated = await wallet.createUtxosEnd({ signed_psbt });

    // 5. Issue asset
    const asset = await wallet.issueAssetNia({
        ticker: "DEMO",
        name: "Demo Token",
        amounts: [1000],
        precision: 2
    });

    // 6. List assets and balances
    const assets = await wallet.listAssets();
    const assetBalance = await wallet.getAssetBalance(asset.asset?.asset_id);

    // Wallet is ready to send/receive RGB assets
}

Security

Key Management

const { createWallet, deriveKeysFromMnemonic } = require('rgb-sdk-rn');

// Generate new wallet keys
const keys = await createWallet('testnet');
const mnemonic = keys.mnemonic;
const xpriv = keys.xpriv; // Sensitive - protect at rest

// Store mnemonic securely for later restoration
// Use environment variables for production
const storedMnemonic = process.env.WALLET_MNEMONIC;

// Restore keys from mnemonic
const restoredKeys = await deriveKeysFromMnemonic('testnet', storedMnemonic);
// Optionally, persist restoredKeys.xpriv if your flow requires explicit xpriv access

// Sign and verify arbitrary messages (Schnorr signatures)
// Option 1: Using WalletManager (requires wallet initialized with seed)
const wallet = new WalletManager({
  xpub_van: keys.account_xpub_vanilla,
  xpub_col: keys.account_xpub_colored,
  master_fingerprint: keys.master_fingerprint,
  seed: seedBytes, // Uint8Array seed
  network: 'testnet',
  rgb_node_endpoint: 'http://127.0.0.1:8000'
});
const signature = await wallet.signMessage('Hello RGB!');
const isValid = await wallet.verifyMessage('Hello RGB!', signature);

// Option 2: Using standalone functions
const { signMessage, verifyMessage } = require('rgb-sdk-rn');
const seedHex = process.env.WALLET_SEED_HEX; // 64-byte hex string
const { signature, accountXpub } = await signMessage({
  message: 'Hello RGB!',
  seed: seedHex,
  network: 'testnet',
});
const isValid = await verifyMessage({
  message: 'Hello RGB!',
  signature,
  accountXpub,
  network: 'testnet',
});