# rgb-lightning-node (RLN) — Developer Reference

> **Source:** https://github.com/RGB-Tools/rgb-lightning-node
> **OpenAPI / Swagger UI:** https://rgb-tools.github.io/rgb-lightning-node
> **Part of:** github.com/RGB-Tools — official higher-level projects for RGB Protocol on Bitcoin v0.11.1

RLN is an RGB-enabled Lightning node based on LDK (Lightning Development Kit). It allows opening Lightning channels that carry both satoshis and RGB assets. Each Lightning commitment transaction includes an additional output anchoring the RGB state transition, so asset state changes follow the same security model as standard Lightning payments.

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

---

## How RGB works on Lightning

- Channels are funded with both satoshis and RGB assets
- Each channel update (HTLC) includes a new RGB state transition committed in the output
- HTLCs carry both satoshi and RGB asset allocations
- Every RGB Lightning payment also transfers satoshis (required to keep outputs above the dust limit)
- If an output falls below the dust limit, the UTXO cannot be spent and the RGB allocation becomes inaccessible — always keep allocations above dust

For technical details: https://docs.rgb.info/lightning-network-compatibility

---

## Requirements

Each RLN node requires:
1. A bitcoind node
2. An indexer (Electrum or Esplora)
3. 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 (with Docker services)

```sh
# Start bitcoind + electrs + rgb-proxy-server in Docker
./regtest.sh start

# Start three nodes (each in a separate terminal)
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

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

Regtest services for `/unlock`:
```json
{
  "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"
}
```

### Regtest (Docker container)

```sh
docker run --rm -it \
    -p 3001:3001 \
    -v RLNdata1:/RLNdata \
    --network rgb-lightning-node_default \
    rgb-lightning-node \
        --daemon-listening-port 3001 \
        --ldk-peer-listening-port 9735 \
        --network regtest \
        --disable-authentication \
        RLNdata
# remove data: docker volume rm RLNdata1
```

### Testnet3

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

Testnet3 public services for `/unlock`:
```json
{
  "bitcoind_rpc_username": "user",
  "bitcoind_rpc_password": "password",
  "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"
}
```

### Testnet4

Same as testnet3 except:
- CLI flag: `--network testnet4`
- `bitcoind_rpc_port`: 18443
- `indexer_url`: `ssl://electrum.iriswallet.com:50053`

---

## Authentication (Biscuit tokens)

By default authentication is enabled. For regtest/dev use `--disable-authentication`.

For production:

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

# Generate root keypair (save private key securely)
biscuit keypair
# or: biscuit keypair --only-private-key > private-key-file

# Mint tokens
echo 'role("admin");' \
  | biscuit generate --private-key-file private-key-file -   # full access

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

# Token with expiry
echo 'role("admin");
      check if time($t), $t <= 2025-12-31T00:00:00Z;' \
  | biscuit generate --private-key-file private-key-file -

# Custom permissions
echo 'role("custom");
      right("api", "/nodeinfo");
      right("api", "/networkinfo");' \
  | biscuit generate --private-key-file private-key-file -
```

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

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

---

## REST API reference

All endpoints are POST unless noted otherwise. Base URL: `http://localhost:<daemon-port>`.

Full OpenAPI spec: https://rgb-tools.github.io/rgb-lightning-node

### Node lifecycle

| Endpoint | Method | Description |
|---|---|---|
| `/init` | POST | Initialize node: set passwords, connect indexer, proxy |
| `/unlock` | POST | Unlock node (provide bitcoind/indexer/proxy credentials) |
| `/lock` | POST | Lock node |
| `/shutdown` | POST | Stop the node daemon |
| `/nodeinfo` | GET | Node public key, alias, peers, channels |
| `/networkinfo` | GET | Bitcoin network info |
| `/sync` | POST | Sync wallet state with the indexer |

### Bitcoin wallet

| Endpoint | Method | Description |
|---|---|---|
| `/address` | POST | Get a Bitcoin address |
| `/btcbalance` | POST | Bitcoin balance (settled + pending) |
| `/createutxos` | POST | Create UTXOs for RGB allocations |
| `/sendbtc` | POST | Send Bitcoin to an address |
| `/estimatefee` | POST | Estimate fee for a transaction |
| `/listtransactions` | POST | List Bitcoin transactions |
| `/listunspents` | POST | List UTXOs with RGB allocations |
| `/backup` | POST | Backup wallet |
| `/restore` | POST | Restore wallet from backup |
| `/changepassword` | POST | Change unlock password |
| `/checkindexerurl` | POST | Validate indexer URL |
| `/checkproxyendpoint` | POST | Validate proxy endpoint URL |

### RGB asset issuance

| Endpoint | Method | Description |
|---|---|---|
| `/issueassetnia` | POST | Issue NIA (fixed-supply fungible) |
| `/issueassetifa` | POST | Issue IFA (inflatable fungible) |
| `/issueassetcfa` | POST | Issue CFA (collectible fungible) |
| `/issueassetuda` | POST | Issue UDA (non-fungible / NFT) |
| `/inflate` | POST | Inflate supply (IFA only) |

### RGB asset management

| Endpoint | Method | Description |
|---|---|---|
| `/listassets` | POST | List all known RGB assets |
| `/assetbalance` | POST | Balance for a specific asset |
| `/assetmetadata` | POST | Metadata for a specific asset |
| `/getassetmedia` | POST | Retrieve media file for a UDA |
| `/postassetmedia` | POST | Upload media file for a UDA |
| `/listtransfers` | POST | List RGB transfer history |
| `/refreshtransfers` | POST | Refresh transfer statuses |
| `/failtransfers` | POST | Mark stale transfers as failed |

### Lightning channels

| Endpoint | Method | Description |
|---|---|---|
| `/openchannel` | POST | Open a Lightning channel (with optional RGB asset funding) |
| `/closechannel` | POST | Close a channel |
| `/listchannels` | GET | List open channels |
| `/getchannelid` | POST | Get channel ID for a peer/channel pair |

### Lightning payments

| Endpoint | Method | Description |
|---|---|---|
| `/lninvoice` | POST | Create a standard Lightning invoice |
| `/decodelninvoice` | POST | Decode a Lightning invoice |
| `/rgbinvoice` | POST | Create an RGB Lightning invoice |
| `/decodergbinvoice` | POST | Decode an RGB Lightning invoice |
| `/sendpayment` | POST | Send a Lightning payment |
| `/sendrgb` | POST | Send RGB assets via Lightning |
| `/keysend` | POST | Keysend payment (no invoice needed) |
| `/getpayment` | POST | Get details for a specific payment |
| `/listpayments` | GET | List all payments |
| `/invoicestatus` | POST | Check status of an invoice |

### Peers

| Endpoint | Method | Description |
|---|---|---|
| `/connectpeer` | POST | Connect to a Lightning peer |
| `/disconnectpeer` | POST | Disconnect a peer |
| `/listpeers` | GET | List connected peers |
| `/sendonionmessage` | POST | Send an onion message |

### Atomic swaps (RGB asset exchange)

| Endpoint | Method | Description |
|---|---|---|
| `/makerinit` | POST | Maker: initialize atomic swap offer |
| `/makerexecute` | POST | Maker: execute atomic swap |
| `/taker` | POST | Taker: accept atomic swap |
| `/getswap` | POST | Get details for a specific swap |
| `/listswaps` | GET | List all swaps |

### Other

| Endpoint | Method | Description |
|---|---|---|
| `/signmessage` | POST | Sign a message with node key |
| `/revoketoken` | POST | Revoke an authentication token |

---

## Example workflow

```sh
BASE=http://localhost:3001

# 1. Initialize and unlock
curl -X POST -H "Content-type: application/json" \
    -d '{"password":"secret","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"}' \
    $BASE/init

# 2. Get a Bitcoin address and fund the wallet
curl -X POST $BASE/address

# 3. Create UTXOs for RGB
curl -X POST -H "Content-type: application/json" \
    -d '{"fee_rate":1.5}' $BASE/createutxos

# 4. Issue a NIA asset
curl -X POST -H "Content-type: application/json" \
    -d '{"ticker":"DEMO","name":"Demo Token","amounts":[1000000],"precision":0}' \
    $BASE/issueassetnia

# 5. Open a channel to node 2 (with RGB asset)
curl -X POST -H "Content-type: application/json" \
    -d '{"peer_pubkey_and_opt_addr":"<node2_pubkey>@localhost:9736","capacity_sat":100000,"push_msat":50000,"asset_amount":500000,"asset_id":"<asset_id>","fee_rate":1.5,"public":true}' \
    $BASE/openchannel

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

# 7. 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}' \
    $BASE/sendrgb
```

---

## Canonical sources

- https://github.com/RGB-Tools/rgb-lightning-node — repository
- https://rgb-tools.github.io/rgb-lightning-node — OpenAPI spec / Swagger UI
- https://docs.rgb.info/lightning-network-compatibility — RGB on Lightning technical docs
- https://github.com/RGB-Tools/rgb-proxy-server — required proxy server
- https://github.com/RGB-Tools/rgb-lib — wallet library used by applications