# rgb-lib — Developer Reference

> **Source:** https://github.com/RGB-Tools/rgb-lib
> **Crate:** https://crates.io/crates/rgb-lib
> **PyPI:** https://pypi.org/project/rgb-lib/
> **Part of:** github.com/RGB-Tools — official higher-level projects for RGB Protocol on Bitcoin v0.11.1

`rgb-lib` is the primary library for building RGB-compatible wallets. It abstracts Bitcoin and RGB internals, uses BDK for UTXO management, and the rgb-protocol core libraries for RGB operations.

---

## Critical warning

> **Never use the same wallet mnemonic on more than one device.**  
> rgb-lib has exclusive control over all UTXOs in the wallet. Using the same mnemonic elsewhere — even with another rgb-lib instance — can cause RGB asset loss due to UTXO conflicts. A consistency check runs every time the wallet goes online and raises an error if discrepancies are detected.

---

## Language bindings

| Language | Repository | Package |
|---|---|---|
| Rust (native) | https://github.com/RGB-Tools/rgb-lib | crates.io/crates/rgb-lib |
| Python | https://github.com/RGB-Tools/rgb-lib-python | pypi.org/project/rgb-lib |
| Kotlin (Android) | https://github.com/RGB-Tools/rgb-lib-kotlin | — |
| Swift (iOS/macOS) | https://github.com/RGB-Tools/rgb-lib-swift | — |
| Node.js | https://github.com/RGB-Tools/rgb-lib-nodejs | — |

---

## Setup

### Rust

```rust
use rgb_lib::keys::{WitnessVersion, generate_keys};
use rgb_lib::wallet::{DatabaseType, SinglesigKeys, Wallet, WalletData};
use rgb_lib::{AssetSchema, BitcoinNetwork};

// Generate keys
let keys = generate_keys(BitcoinNetwork::Regtest, WitnessVersion::Taproot);
let single_sig_keys = SinglesigKeys::from_keys(&keys, None);

// Configure wallet
let wallet_data = WalletData {
    data_dir: "/path/to/data".to_string(),
    bitcoin_network: BitcoinNetwork::Regtest,
    database_type: DatabaseType::Sqlite,
    max_allocations_per_utxo: 5,
    supported_schemas: vec![AssetSchema::Nia],  // or vec![] for all schemas
};

// Create wallet
let wallet = Wallet::new(wallet_data, single_sig_keys)?;
```

### Python

```sh
pip install rgb-lib
```

```python
import rgb_lib

# Generate keys
keys = rgb_lib.generate_keys(rgb_lib.BitcoinNetwork.REGTEST)
print(keys.account_xpub)

# Configure wallet
wallet_data = rgb_lib.WalletData(
    data_dir="/path/to/data",
    bitcoin_network=rgb_lib.BitcoinNetwork.REGTEST,
    database_type=rgb_lib.DatabaseType.SQLITE,
    max_allocations_per_utxo=5,
    supported_schemas=[rgb_lib.AssetSchema.NIA],  # or [] for all
)
keys = rgb_lib.SinglesigKeys.from_keys(keys, None)
wallet = rgb_lib.Wallet(wallet_data, keys)
```

### Python demo (Docker + Jupyter)

```sh
git clone https://github.com/RGB-Tools/rgb-lib-python
cd rgb-lib-python/demo
./services.sh build
./services.sh start
# open http://localhost:8888/... in browser
# fund a wallet:
./services.sh fund <bitcoin_address>
# mine a block:
./services.sh mine
# stop:
./services.sh stop
```

---

## WalletData fields

| Field | Type | Description |
|---|---|---|
| `data_dir` | String | Directory where wallet data is stored |
| `bitcoin_network` | BitcoinNetwork | Regtest / Testnet / Mainnet |
| `database_type` | DatabaseType | Currently only Sqlite supported |
| `max_allocations_per_utxo` | u32 | Max RGB allocations per UTXO |
| `supported_schemas` | Vec\<AssetSchema\> | Schemas to support; empty = all schemas |

---

## Supported schemas

| Schema | AssetSchema variant | Description |
|---|---|---|
| NIA | `AssetSchema::Nia` | Non Inflatable Asset — fixed supply fungible |
| IFA | `AssetSchema::Ifa` | Inflatable Fungible Asset — issuer can inflate supply |
| CFA | `AssetSchema::Cfa` | Collectible Fungible Asset — NIA with optional Article |
| UDA | `AssetSchema::Uda` | Unique Digital Asset — non-fungible (NFT) |

---

## Schema IDs (v0.11.1, as embedded in rgb-lib)

| Schema | ID |
|---|---|
| NIA | `rgb:sch:RWhwUfTMpuP2Zfx1~j4nswCANGeJrYOqDcKelaMV4zU#remote-digital-pegasus` |
| UDA | `rgb:sch:~6rjymf3GTE840lb5JoXm2aFwE8eWCk3mCjOf_mUztE#spider-montana-fantasy` |
| CFA | `rgb:sch:JgqK5hJX9YBT4osCV7VcW_iLTcA5csUCnLzvaKTTrNY#mars-house-friend` |
| IFA | `rgb:sch:p6H_wtDgei9HHUVLjKW0tNdHHFLhfHxrn9QX_QQUE78#scale-year-shave` |

---

## Key API methods

### Offline methods (no indexer required)

| Method | Description |
|---|---|
| `get_address` | Get a Bitcoin receive address |
| `issue_asset_nia` | Issue a Non Inflatable Asset |
| `issue_asset_ifa` | Issue an Inflatable Fungible Asset |
| `issue_asset_cfa` | Issue a Collectible Fungible Asset |
| `issue_asset_uda` | Issue a Unique Digital Asset (NFT) |
| `blind_receive` | Generate a blinded UTXO invoice for receiving |
| `witness_receive` | Generate a witness-based receive invoice |
| `list_assets` | List all known RGB assets |
| `list_transfers` | List transfer history |
| `list_unspents` | List UTXOs with their RGB allocations |
| `backup` | Create an encrypted wallet backup |
| `restore_backup` | Restore wallet from backup |

### Online methods (require `go_online` first)

| Method | Description |
|---|---|
| `go_online` | Connect to indexer and proxy server; returns Online handle |
| `sync` | Sync wallet state with the Bitcoin network |
| `create_utxos` | Create new UTXOs for RGB allocations |
| `send` | Transfer RGB assets (single-call) |
| `send_begin` / `send_end` | Two-phase RGB asset transfer |
| `refresh` | Refresh transfer statuses, auto-accept valid incoming transfers |
| `get_btc_balance` | Get Bitcoin balance |
| `get_asset_balance` | Get balance for a specific RGB asset |
| `drain_to` | Drain all Bitcoin to an address |
| `fail_transfers` | Mark stale/expired transfers as failed |
| `delete_transfers` | Delete failed transfers from local DB |

---

## External services

The library requires an indexer and (for transfers) a proxy server:

```rust
// Go online: connect to indexer and proxy
let online = wallet.go_online(
    false,  // skip consistency check
    "ssl://electrum.iriswallet.com:50013".to_string(),  // indexer URL (Electrum)
)?;
```

For production, use `rgb-proxy-server` (see rgb-proxy-server-reference.md):
```
proxy_url: "rpcs://proxy.iriswallet.com/0.2/json-rpc"
```

For regtest testing, use the services from rgb-sandbox or rgb-lib-python demo:
```
indexer_url: "127.0.0.1:50001"
proxy_url: "rpc://127.0.0.1:3000/json-rpc"
```

---

## Docs and diagrams

The `docs/` directory in the repo contains UML diagrams for:
- Asset issuance flow
- Asset send flow
- Asset receive flow
- Transfer state machine
- Multisig coordination

Full docs: https://docs.rgb.info