# RGB-Tools — Developer Reference

> **Source:** https://github.com/RGB-Tools
> **What this is:** github.com/RGB-Tools is the official GitHub organization for higher-level projects built on top of the core rgb-protocol libraries. Confirmed official by the RGB Protocol development team.
>
> **Not to confuse with:**
> - `github.com/rgb-protocol` — core protocol layer (consensus, schemas, VM, encoding)
> - `github.com/RGB-WG` — a separate organization (Maxim Orlovsky / rgb.tech). Do not use.

---

## rgb-lib — Primary Wallet Library

**Repository:** https://github.com/RGB-Tools/rgb-lib  
**Crate:** https://crates.io/crates/rgb-lib  
**PyPI:** https://pypi.org/project/rgb-lib/

A Rust library that provides tools for building cross-platform RGB-compatible wallets without dealing with Bitcoin and RGB internals directly. It uses BDK for Bitcoin walleting and the rgb-protocol libraries for RGB-specific operations.

### Language bindings

| Language | Repository |
|---|---|
| Python | https://github.com/RGB-Tools/rgb-lib-python |
| 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 |

### Key facts

- Handles UTXO management internally — **never use the same wallet mnemonic on more than one device**, or you risk RGB asset loss
- Supports offline usage (some APIs do not require internet access)
- Supports watch-only wallets (no private keys required; signing is done externally)
- Multisig wallets are supported via the RGB multisig hub
- Uses SQLite for on-disk persistence
- Supports Electrum and Esplora as indexers

### Setup (Rust)

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

let keys = generate_keys(BitcoinNetwork::Regtest, WitnessVersion::Taproot);
let single_sig_keys = SinglesigKeys::from_keys(&keys, None);
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],
};
let wallet = Wallet::new(wallet_data, single_sig_keys)?;
```

### Setup (Python)

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

```python
import rgb_lib

keys = rgb_lib.generate_keys(rgb_lib.BitcoinNetwork.REGTEST)
print(keys.account_xpub)
```

### Main API surface

**Offline methods** (no indexer required):

| Method | Description |
|---|---|
| `issue_asset_nia` | Issue a Non Inflatable Asset (fixed supply fungible) |
| `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) |
| `witness_receive` | Generate a witness-based receive address |
| `blind_receive` | Generate a blinded UTXO invoice |
| `get_address` | Get a Bitcoin address from the wallet |
| `list_assets` | List known RGB assets |
| `list_transfers` | List transfer history |
| `list_unspents` | List UTXOs with RGB allocations |
| `backup` | Create a wallet backup |
| `restore_backup` | Restore from backup |

**Online methods** (require indexer):

| Method | Description |
|---|---|
| `go_online` | Connect to indexer and proxy, returns Online handle |
| `sync` | Sync wallet state with the Bitcoin network |
| `create_utxos` | Create new UTXOs for RGB allocations |
| `send_begin` / `send_end` | Two-phase RGB asset transfer (send) |
| `send` | Single-call RGB asset transfer |
| `refresh` | Refresh transfers, accept pending incoming |
| `drain_to` / `drain_to_begin` / `drain_to_end` | Drain Bitcoin from the wallet |
| `get_btc_balance` | Get Bitcoin balance |
| `get_asset_balance` | Get balance for a specific RGB asset |

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

These are the canonical schema IDs 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` |

---

## rgb-proxy-server — Consignment Transport

**Repository:** https://github.com/RGB-Tools/rgb-proxy-server  
**Docker:** `ghcr.io/rgb-tools/rgb-proxy-server`  
**Protocol:** Implements the [RGB HTTP JSON-RPC protocol](https://github.com/RGB-Tools/rgb-http-json-rpc)

The proxy server facilitates relay of client-side RGB data (consignments) between wallets. It is **not trusted** — it only passes data; it never sees or validates asset state. Anyone can self-host an instance.

### Workflow

1. Payer posts the consignment file to the server (using the blinded UTXO as identifier)
2. Payee fetches the consignment file by blinded UTXO
3. Payee validates the consignment locally
4. Payee posts ACK (valid) or NACK (invalid) to the server
5. Payer checks ACK/NACK; if ACK, broadcasts the Bitcoin transaction

### Run

```sh
# npm (local)
npm install
npm run dev        # dev mode, port 3000
npm run build
npm run start      # production build, port 3000

# Docker
docker run -d ghcr.io/rgb-tools/rgb-proxy-server

# Docker with persistent data
docker run -d \
  -v /host/path:/home/node/.rgb-proxy-server \
  ghcr.io/rgb-tools/rgb-proxy-server
```

Data is stored in `$HOME/.rgb-proxy-server` by default. Override with `APP_DATA` env var.

### API (JSON-RPC over HTTP)

**Post consignment** (payer):
```sh
curl -X POST -H 'Content-Type: multipart/form-data' \
  -F 'jsonrpc=2.0' -F 'id="1"' -F 'method=consignment.post' \
  -F 'params[recipient_id]=<blinded_utxo>' \
  -F 'params[txid]=<txid>' \
  -F 'file=@consignment.rgb' \
  localhost:3000/json-rpc
```

**Get consignment** (payee):
```sh
curl -X POST -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":"2","method":"consignment.get","params":{"recipient_id":"<blinded_utxo>"}}' \
  localhost:3000/json-rpc
# returns consignment as base64-encoded string
```

**Post ACK** (payee, if valid):
```sh
curl -X POST -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":"3","method":"ack.post","params":{"recipient_id":"<blinded_utxo>","ack":true}}' \
  localhost:3000/json-rpc
```

**Post NACK** (payee, if invalid):
```sh
curl -X POST -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":"4","method":"ack.post","params":{"recipient_id":"<blinded_utxo>","ack":false}}' \
  localhost:3000/json-rpc
```

**Get ACK status** (payer):
```sh
curl -X POST -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":"5","method":"ack.get","params":{"recipient_id":"<blinded_utxo>"}}' \
  localhost:3000/json-rpc
# returns true (ACK), false (NACK), or null (not yet posted)
```

---

## rgb-lightning-node (RLN) — RGB-Enabled Lightning Node

**Repository:** https://github.com/RGB-Tools/rgb-lightning-node  
**OpenAPI / Swagger UI:** https://rgb-tools.github.io/rgb-lightning-node  
**Based on:** LDK (Lightning Development Kit), forked from ldk-sample

RLN enables Lightning channels that carry RGB assets in addition to satoshis. Each Lightning commitment transaction includes an additional output anchoring the RGB state transition. HTLCs work the same way as in standard Lightning, with both satoshi and RGB asset allocations.

**Projects using RLN:** KaleidoSwap, ThunderStack, LNFI, Iris Wallet desktop, Spectrum, Tiramisu Wallet

### Requirements

Each node requires:
- A bitcoind node
- An indexer (Electrum or Esplora)
- An rgb-proxy-server instance

### Install

```sh
git clone https://github.com/RGB-Tools/rgb-lightning-node --recurse-submodules --shallow-submodules
cargo install --locked --path .

# or build Docker image
docker build -t rgb-lightning-node .
```

### Run (regtest)

```sh
# Start regtest services (bitcoind + electrs + proxy)
./regtest.sh start

# Start nodes (one per shell)
rgb-lightning-node dataldk0/ --daemon-listening-port 3001 \
    --ldk-peer-listening-port 9735 --network regtest \
    --disable-authentication

rgb-lightning-node dataldk1/ --daemon-listening-port 3002 \
    --ldk-peer-listening-port 9736 --network regtest \
    --disable-authentication

rgb-lightning-node dataldk2/ --daemon-listening-port 3003 \
    --ldk-peer-listening-port 9737 --network regtest \
    --disable-authentication
```

Regtest services config for unlock:
- `bitcoind_rpc_username`: user
- `bitcoind_rpc_password`: password
- `bitcoind_rpc_host`: localhost
- `bitcoind_rpc_port`: 18433
- `indexer_url`: 127.0.0.1:50001
- `proxy_endpoint`: rpc://127.0.0.1:3000/json-rpc

```sh
# Regtest utility commands
./regtest.sh sendtoaddress <address> <amount>
./regtest.sh mine <blocks>
./regtest.sh stop
```

### Run (testnet3)

```sh
rgb-lightning-node dataldk0/ --daemon-listening-port 3001 \
    --ldk-peer-listening-port 9735 --network testnet \
    --disable-authentication
```

Testnet3 public services:
- `bitcoind_rpc_host`: electrum.iriswallet.com
- `bitcoind_rpc_port`: 18332
- `indexer_url`: ssl://electrum.iriswallet.com:50013
- `proxy_endpoint`: rpcs://proxy.iriswallet.com/0.2/json-rpc

### REST API (all POST unless noted)

**Node / wallet:**
- `/init` — initialize node (set passwords, connect to services)
- `/unlock` — unlock node
- `/lock` — lock node
- `/nodeinfo` — node info (GET)
- `/networkinfo` — network info (GET)
- `/shutdown` — stop the daemon
- `/address` — get a Bitcoin address
- `/btcbalance` — Bitcoin balance
- `/backup` — backup wallet
- `/restore` — restore wallet
- `/changepassword` — change unlock password
- `/sync` — sync wallet with indexer
- `/createutxos` — create UTXOs for RGB allocations

**RGB assets:**
- `/issueassetnia` — issue NIA (fixed-supply fungible)
- `/issueassetifa` — issue IFA (inflatable fungible)
- `/issueassetcfa` — issue CFA (collectible fungible)
- `/issueassetuda` — issue UDA (non-fungible)
- `/listassets` — list known assets
- `/assetbalance` — balance for a specific asset
- `/assetmetadata` — metadata for a specific asset
- `/getassetmedia` — retrieve asset media
- `/postassetmedia` — upload asset media
- `/inflate` — inflate supply (IFA only)
- `/rgbinvoice` — generate an RGB Lightning invoice
- `/decodergbinvoice` — decode an RGB invoice
- `/sendrgb` — send RGB assets via Lightning

**Lightning channels:**
- `/openchannel` — open a Lightning channel (with optional RGB asset funding)
- `/closechannel` — close a channel
- `/listchannels` — list channels (GET)
- `/getchannelid` — get channel ID

**Lightning payments:**
- `/lninvoice` — create a standard Lightning invoice
- `/decodelninvoice` — decode a Lightning invoice
- `/sendpayment` — send a Lightning payment
- `/keysend` — keysend payment
- `/getpayment` — get payment details
- `/listpayments` — list payments (GET)
- `/invoicestatus` — check invoice status

**Peers:**
- `/connectpeer` — connect to a peer
- `/disconnectpeer` — disconnect from a peer
- `/listpeers` — list peers (GET)

**Transfers / transactions:**
- `/listtransfers` — list RGB transfers
- `/listtransactions` — list Bitcoin transactions
- `/listunspents` — list unspent outputs
- `/failtransfers` — mark stale transfers as failed
- `/refreshtransfers` — refresh transfer statuses

**Swaps (atomic):**
- `/makerinit` — maker initiates atomic swap
- `/makerexecute` — maker executes atomic swap
- `/taker` — taker accepts atomic swap
- `/getswap` — get swap details
- `/listswaps` — list swaps (GET)

**Other:**
- `/estimatefee` — estimate fee for a transaction
- `/checkindexerurl` — validate indexer URL
- `/checkproxyendpoint` — validate proxy endpoint
- `/sendbtc` — send Bitcoin
- `/sendonionmessage` — send an onion message
- `/signmessage` — sign a message

### Authentication (Biscuit tokens)

By default, authentication is enabled. Use `--disable-authentication` for dev/regtest.

```sh
# Install biscuit CLI
cargo install biscuit-cli

# Generate root keypair
biscuit keypair

# Mint an admin token
echo 'role("admin");' | biscuit generate --private-key-file private-key-file -

# Mint a read-only token
echo 'role("read-only");' | biscuit generate --private-key-file private-key-file -

# Use token in requests
curl -H "Authorization: Bearer <token>" http://localhost:3001/nodeinfo
```

Start node with public key:
```sh
rgb-lightning-node dataldk0/ --daemon-listening-port 3001 \
    --ldk-peer-listening-port 9735 --network regtest \
    --root-public-key <public_key>
```

### Example: issue and send an RGB asset

```sh
# Issue a NIA asset on node 1
curl -X POST -H "Content-type: application/json" \
    -d '{"ticker":"USDT","name":"Tether","amounts":[1000000],"precision":0}' \
    http://localhost:3001/issueassetnia

# Get an RGB invoice from node 2
curl -X POST -H "Content-type: application/json" \
    -d '{"asset_id":"<asset_id>","amount":100,"expiry_sec":3600}' \
    http://localhost:3002/rgbinvoice

# Send RGB assets from node 1
curl -X POST -H "Content-type: application/json" \
    -d '{"invoice":"<rgb_invoice>","amount":100,"asset_id":"<asset_id>","fee_msat":1000}' \
    http://localhost:3001/sendrgb
```

---

## Other RGB-Tools repositories

| Repository | Description |
|---|---|
| [iris-wallet-android](https://github.com/RGB-Tools/iris-wallet-android) | Reference Android wallet (full RGB + Lightning) |
| [iris-wallet-desktop](https://github.com/RGB-Tools/iris-wallet-desktop) | Reference desktop wallet |
| [rgb-multisig-hub](https://github.com/RGB-Tools/rgb-multisig-hub) | Coordination server for rgb-lib multisig wallets |
| [rgb-lightning-sample](https://github.com/RGB-Tools/rgb-lightning-sample) | Minimal LDK-based RLN demo |
| [faucet-rgb](https://github.com/RGB-Tools/faucet-rgb) | Faucet for RGB assets (testnet/regtest) |
| [rgb-http-json-rpc](https://github.com/RGB-Tools/rgb-http-json-rpc) | RGB HTTP JSON-RPC protocol specification |

---

## Canonical sources

- https://github.com/RGB-Tools — all higher-level RGB tools
- https://github.com/rgb-protocol — core protocol (consensus, schemas, VM, encoding)
- https://docs.rgb.info — full technical documentation
- https://rgb.info — official homepage