RGB Lightning Node Hosting

​

Overview

• Create payment channels containing RGB assets
• Route RGB asset-denominated payments across multiple channels
• Transfer RGB assets with the same user experience and security as regular Bitcoin Lightning payments

​

Hosting Methods Comparison

• Docker-based installation: Best for most users - provides an easy setup with the option to run full infrastructure or just the node.
• Direct installation on a VPS: Best for advanced users who need complete control over the system configuration.
• Hosted solution (ThunderStack): Best for users who want a professionally managed solution with minimal technical overhead.

​

Network Options

​

Trust Considerations

• Zero-Trust Setup: Run your own Bitcoin Core, Electrs, RGB Proxy, and RGB Lightning Node
• Minimal Trust Setup: Run only the RGB Lightning Node and connect to hosted instances for other services

​

Option 1: Docker-Based Installation

​

Prerequisites

• Docker and Docker Compose installed
• At least 4GB RAM and 50GB storage
• Basic knowledge of terminal commands

​

Quick Start with Makefile

1. Clone the repository:

git clone https://github.com/kaleidoswap/docker-images.git
cd docker-images

2. Choose how you want to run the stack:

# To see all available commands
make help

# To run only the RGB Lightning Node (connect then to external services)
make node-only

# To run the full stack (all components on signet)
make full

# To view logs from all services
make logs

​

Option 2: Direct Installation on a VPS

​

Prerequisites

• A VPS or server running Linux (Ubuntu/Debian recommended)
• Rust development environment
• Properly configured firewall (opening ports 3001 for API and 9735 for Lightning)
• Sufficient storage for blockchain data

​

Installation

1. Clone the repository:

git clone https://github.com/RGB-Tools/rgb-lightning-node --recurse-submodules --shallow-submodules
cd rgb-lightning-node

2. Install the binary:

cargo install --locked --debug --path .

3. Start the node:

rgb-lightning-node <data-dir>/ --daemon-listening-port 3001 \
--disable-authentication \
--ldk-peer-listening-port 9735 \
--network <network>

• <data-dir> with your chosen data directory
• <network> with regtest, testnet, or signet (for Mutinynet)

4. When unlocking the node, you’ll need to provide:

• Bitcoin RPC connection details
• Indexer URL
• RGB proxy endpoint

​

VPS Firewall Configuration

# Allow SSH
ufw allow ssh

# Allow RGB Lightning Node API
ufw allow 3001/tcp

# Allow Lightning Network P2P connections
ufw allow 9735/tcp

# Enable the firewall
ufw enable

​

Running as a System Service

sudo nano /etc/systemd/system/rgb-lightning-node.service

[Unit]
Description=RGB Lightning Node
After=network.target

[Service]
User=YOUR_USERNAME
WorkingDirectory=/home/YOUR_USERNAME
ExecStart=/home/YOUR_USERNAME/.cargo/bin/rgb-lightning-node /home/YOUR_USERNAME/rgbln-data/ --daemon-listening-port 3001 --ldk-peer-listening-port 9735 --network signet
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

sudo systemctl enable rgb-lightning-node
sudo systemctl start rgb-lightning-node

​

Option 3: Hosted Provider (ThunderStack)

​

What is ThunderStack?

​

Key Features

• 24/7 Availability: Always-on infrastructure ensures uninterrupted operations
• No Maintenance: Leave the operational complexities of node management to ThunderStack
• Scalability: Add or remove nodes on demand as your needs evolve
• Security: Advanced security protocols like mTLS and Cognito for access control
• Integration Ready: Supports APIs, webhooks, and SDKs for easy integration

​

ThunderStack vs. Self-Hosting

​

Network Environments

​

Connection Details for Different Networks

​

Regtest Environment

{
  "password": "<YOUR_NODE_PASSWORD>",
  "bitcoind_rpc_username": "user",
  "bitcoind_rpc_password": "password",
  "bitcoind_rpc_host": "regtest-bitcoind.rgbtools.org",
  "bitcoind_rpc_port": 80,
  "indexer_url": "electrum.rgbtools.org:50041",
  "proxy_endpoint": "rpcs://proxy.iriswallet.com/0.2/json-rpc"
}

​

Testnet Environment

{
  "password": "<YOUR_NODE_PASSWORD>",
  "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"
}

​

Signet (Mutinynet) Environment

{
  "password": "<YOUR_NODE_PASSWORD>",
  "bitcoind_rpc_username": "user",
  "bitcoind_rpc_password": "default_password",
  "bitcoind_rpc_host": "bitcoind.signet.kaleidoswap.com",
  "bitcoind_rpc_port": 38332,
  "indexer_url": "ssl://electrum.signet.kaleidoswap.com:60601",
  "proxy_endpoint": "rpcs://proxy.signet.kaleidoswap.com/json-rpc"
}

​

Mutinynet: A Custom Bitcoin Signet for Testing

• Extremely fast block times (30 seconds per block vs. 10 minutes on mainnet)
• Stable testnet environment without competition for block space
• Pre-configured for compatibility with RGB Lightning Nodes
• Ideal for testing RGB assets on Lightning

• Mutinynet Explorer & Mempool - View blocks, transactions, and mempool
• Mutinynet Faucet - Get free test coins for development
• Mutinynet GitHub Repository - Technical documentation and source code

​

Node Operation

​

API Overview

• Channel management: open/close channels, connect/disconnect peers
• Asset operations: issue, send, and manage RGB assets
• Payment handling: create/pay invoices, keysend, etc.
• Node information and control

​

Basic Operations

​

Get a Bitcoin Address

curl -X POST http://localhost:3001/address

​

Get Node Information

curl http://localhost:3001/nodeinfo

​

Check Bitcoin Balance

curl -X POST -H "Content-type: application/json" \
    -d '{}' http://localhost:3001/btcbalance

​

Hardware Requirements

​

Security Considerations

1. Firewall Configuration: Only expose necessary ports (3001 for API, 9735 for LN peers)
2. Authentication: Use strong passwords and consider adding API authentication
3. Backups: Regularly backup your node’s data directory
4. Updates: Keep all components updated to patch security vulnerabilities

​

Troubleshooting

​

Common Issues

• Check if Bitcoin Core is running and accessible
• Verify the indexer connection is working
• Ensure the RGB proxy server is running

• Check firewall settings
• Verify the node URL is correct
• Ensure the node is running and unencrypted

• Bitcoin Core might still be syncing
• The indexer might be behind the blockchain
• For Mutinynet, make sure you’re using the correct signet seed nodes

• Ensure you’re using the custom Bitcoin build with Mutinynet support
• Check that your electrs instance is configured for Signet
• Verify the NETWORK=signet environment variable is set
• For connection issues, verify Mutinynet seeds are correctly configured
• If transactions aren’t confirming, check the Mutinynet Explorer for network status

​

Getting Help

1. Check the GitHub repository for known issues
2. Visit the KaleidoSwap Telegram for community support
3. Open an issue on the GitHub repository with detailed information about your problem

​

Additional Resources

• RGB Protocol Documentation
• RGB Lightning Node Repository
• Mutinynet Explorer
• Mutinynet Faucet
• Mutinynet Documentation
• KaleidoSwap Documentation