Proposal: Integrating Validating Remote Signer (VLS) in RGB Lightning Node

[gofman8]

Proposal: Integrating Validating Remote Signer (VLS) in RGB Lightning Node

At ThunderStack, we aim to provide the best possible service and security for our clients, developers, and users. To achieve this, we propose integrating the Validating Remote Signer (VLS) into the RGB Lightning Node.

Motivation

During the implementation of a cloud solution for the RGB Lightning Node (RLN), one of the primary concerns raised by users was the need for higher standards of security. Users emphasized the importance of separating the signer from the node to minimize attack surfaces and enhance key protection. To address these needs, we propose providing several deployment options for the signer, each offering different trade-offs in terms of security, usability, and control. See the use cases below for details.

Use Cases

1. Secure Remote Signer Deployment

By default, deploy the remote signer to AWS Nitro Enclaves, ensuring:

• Isolation of the signer in a hardware-secured environment.
• Protection against unauthorized access and external threats.

Reference: AWS Nitro Enclaves

2. User-Hosted Non-Custodial Signers

Provide users with:

• Scripts and documentation for hosting signers locally, ensuring full key ownership.
• Optional MPC-based signing for enterprise-grade security in cloud environments, inspired by Fireblocks custody solutions.

Reference: Fireblocks MPC API, AWS Nitro MPC

3. Mobile Wallet Integration

Enable signers to operate on mobile wallets by:

• Supporting a non-custodial architecture suitable for mobile aligning with the Greenlight framework, to keep secret keys on user's device for signing operations.
• Leveraging notification systems to wake the device for signing operations.

Reference: Breez SDK Notifications, Greenlight Key Manager

Reference Implementation

LDK VLS Implementation

The LDK VLS Implementation demonstrates the use of Lightning Development Kit (LDK) with VLS

Design Goals

• Ensure compatibility with Greenlight.
• Enhance security for both cloud-hosted and user-hosted setups.
• Introduce enterprise-level security via MPC mechanisms.

References

1. AWS Nitro Enclaves
2. Fireblocks MPC
3. Breez SDK Notifications
4. Greenlight Key Manager
5. VLS Overview
6. VLS Transaction Diagrams

[nicbus]

Thanks for the proposal, we'll have a deeper look at it and post our updates here. We're currently working on other tasks ATM so it could take some time for us to post a reply.

[gofman8]

Thanks for the proposal, we'll have a deeper look at it and post our updates here. We're currently working on other tasks ATM so it could take some time for us to post a reply.

Thank you for your response! I appreciate you taking the time to consider the proposal, and I’m ready to provide anything you need from me if it helps. Looking forward to your updates!

[sbn20241]

RGB Lightning Node with VLS Integration - Installation Guide

Complete step-by-step guide for setting up and running RGB Lightning Node with VLS (Validating Lightning Signer) integration on regtest network.

Table of Contents

• Installation Steps
  • 1. Clone Repository
  • 2. Build VLS Container
  • 3. Build RGB Lightning Node
  • 4. Start Core Services
  • 5. Start Services and Initialize
  • 6. Fund the Node
  • 7. Create UTXOs
  • 8. Work with RGB Assets
• Troubleshooting

---

Installation Steps

1. Clone Repository

# Clone the RGB Lightning Node repository with submodules
git clone https://github.com/RGB-OS/rgb-lightning-node --recurse-submodules --shallow-submodules

cd rgb-lightning-node

# Checkout the VLS integration branch
git checkout origin/vls-send-btc

# Checkout the RGB integration branch in rust-lightning
cd rust-lightning
git checkout rgb_integration
cd ..

Note: If using a local deployment, skip cargo install and proceed to Docker setup.

---

2. Build VLS Container

The VLS (Validating Lightning Signer) daemon runs as a separate Docker container.

2.1 Clone VLS Container Repository

git clone git@github.com:RGB-OS/vls-container.git

2.2 Build VLS Container Image

cd vls-container/vlsd

docker build \
  --build-arg VLS_GIT_HASH=246a477ae9c3daf3f7c2afa366595f7ae4a99416 \
  --build-arg VLS_REPO=https://github.com/RGB-OS/validating-lightning-signer \
  --build-arg VLS_BRANCH=feature/rgb_lightning_integration \
  --build-arg TXOO_PUBLIC_KEY=027f31ebc5462c1fdce1b737ecff52d37d75dea43ce11c74d25aa297165faa2007 \
  -t vlsd:latest .

cd ../..

Expected output: Image vlsd:latest built successfully.

---

3. Build RGB Lightning Node

Build the RGB Lightning Node Docker image with VLS support enabled:

# From the rgb-lightning-node root directory
docker compose build rgb-lightning-node

Alternatively, build manually:

docker build -f Dockerfile.local -t rgb-lightning-node-rgb-lightning-node:latest .

Expected output: RGB Lightning Node image built with --features vls.

---

4. Start Core Services

Start Bitcoin Core, Electrs, and RGB Proxy:

docker compose up -d bitcoind electrs proxy

Wait for services to initialize (10-30 seconds):

# Check Bitcoind status
docker compose logs bitcoind | tail -10

# Check Electrs status (wait for "waiting for 0 blocks")
docker compose logs electrs | tail -10

# Check all services are running
docker compose ps

Expected services:

• ✅ Bitcoin Core (regtest network) on port 18443
• ✅ Electrs (Electrum server) on port 50001
• ✅ RGB Proxy Server on port 3000

4.1 Create Bitcoin Wallet (if needed)

# Create wallet (run only once, ignore error if wallet exists)
docker compose exec bitcoind bitcoin-cli -rpcwallet=testwallet createwallet testwallet || true

# Mine initial blocks to fund the wallet
docker compose exec bitcoind bitcoin-cli -rpcwallet=testwallet -generate 101

---

5. Start Services and Initialize

5.1 Start RGB Lightning Node

docker compose up -d rgb-lightning-node

Wait for the node to start (check logs):

docker compose logs rgb-lightning-node | tail -20

Look for:

• Listening on 0.0.0.0:3001
• VLS gRPC endpoint with HsmdService initialized successfully

5.2 Start VLS Daemon (Before Unlock)

Start the VLS daemon before unlocking to enable connection during unlock:

# Create VLS data volume (if not exists)
docker volume create vls_data_test || true

# Start VLS daemon with permissive policies (before we have the address)
docker run -d --name vlsd-test \
  --network rgb-lightning-node_default \
  -e VLS_NETWORK=regtest \
  -e TXOO_PUBLIC_KEY=027f31ebc5462c1fdce1b737ecff52d37d75dea43ce11c74d25aa297165faa2007 \
  -e BITCOIND_RPC_URL=http://user:password@bitcoind:18443 \
  -e VLS_ALLOWLIST="" \
  -e VLS_RGB_INDEXER_URL="electrum+tcp://electrs:50001" \
  --mount type=volume,src=vls_data_test,dst=/home/vls/.lightning-signer \
  vlsd:latest \
  --connect=tcp://rgb-lightning-node-rgb-lightning-node-1:7701 \
  --policy-filter='policy-chain-validated:warn' \
  --policy-filter='policy-unapproved-destination:warn'

Verify VLS is connecting:

docker logs vlsd-test | tail -20

Look for:

• frontend started
• Connection attempts (may show errors until RGB node is unlocked)

5.3 Initialize the Node

curl -X POST http://127.0.0.1:3001/init \
  -H 'Content-Type: application/json' \
  -d '{"password": "rgb-lightning-node-password-2024"}'

Expected response:

{"success": true}

5.4 Unlock the Node

curl -X POST http://127.0.0.1:3001/unlock \
  -H 'Content-Type: application/json' \
  -d '{
    "password": "rgb-lightning-node-password-2024",
    "bitcoind_rpc_username": "user",
    "bitcoind_rpc_password": "password",
    "bitcoind_rpc_host": "bitcoind",
    "bitcoind_rpc_port": 18443,
    "indexer_url": "electrs:50001",
    "proxy_endpoint": "rpc://proxy:3000/json-rpc",
    "announce_addresses": [],
    "announce_alias": null
  }'

Expected response:

{"success": true}

Important: Wait for unlock to complete. Check logs if it takes more than 30 seconds.

5.5 Restart VLS with Address in Allowlist

Optional, in case of issues with signing.

After unlock, get the RGB wallet address and restart VLS with it in the allowlist:

# Get the RGB wallet address
ADDRESS=$(curl -s -X POST http://127.0.0.1:3001/address \
  -H 'Content-Type: application/json' \
  -d '{}' | jq -r '.address')

echo "RGB Wallet Address: $ADDRESS"

# Stop and remove the existing VLS container
docker stop vlsd-test && docker rm vlsd-test

# Restart VLS with the address in allowlist
docker run -d --name vlsd-test \
  --network rgb-lightning-node_default \
  -e VLS_NETWORK=regtest \
  -e TXOO_PUBLIC_KEY=027f31ebc5462c1fdce1b737ecff52d37d75dea43ce11c74d25aa297165faa2007 \
  -e BITCOIND_RPC_URL=http://user:password@bitcoind:18443 \
  -e VLS_ALLOWLIST="$ADDRESS" \
  -e VLS_RGB_INDEXER_URL="electrum+tcp://electrs:50001" \
  --mount type=volume,src=vls_data_test,dst=/home/vls/.lightning-signer \
  vlsd:latest \
  --connect=tcp://rgb-lightning-node-rgb-lightning-node-1:7701 \
  --policy-filter='policy-chain-validated:warn' \
  --policy-filter='policy-unapproved-destination:warn'

Verify VLS is connected:

docker logs vlsd-test | tail -20

Look for:

• frontend started
• tracker ... synced at height ...
• No connection errors

---

6. Fund the Node

6.1 Get Bitcoin Address

curl -X POST http://127.0.0.1:3001/address \
  -H 'Content-Type: application/json' \
  -d '{}' | jq .

Response example:

{
  "address": "bcrt1pnal75epq4t5ya5d4qrrwl6k4stx3qkn9uu0uwlaxcg826jungxfqsfv0qg"
}

6.2 Send Bitcoin to Address

# Replace <ADDRESS> with the address from step 6.1
ADDRESS="<YOUR_ADDRESS_HERE>"

# Send Bitcoin to the address
docker compose exec bitcoind bitcoin-cli -rpcwallet=testwallet sendtoaddress $ADDRESS 0.001

# Mine blocks to confirm the transaction
docker compose exec bitcoind bitcoin-cli -rpcwallet=testwallet -generate 6

6.3 Check Balance

curl -X POST http://127.0.0.1:3001/btcbalance \
  -H 'Content-Type: application/json' \
  -d '{"skip_sync": false}' | jq .

Response example:

{
  "vanilla": {
    "future": 0,
    "spendable": 100000,
    "trusted_pending": 0,
    "untrusted_pending": 0
  },
  "colored": {
    "future": 0,
    "spendable": 0,
    "trusted_pending": 0,
    "untrusted_pending": 0
  }
}

---

7. Create UTXOs

UTXOs (Unspent Transaction Outputs) are required for RGB asset operations. Create UTXOs with sufficient funds:

curl -X POST http://127.0.0.1:3001/createutxos \
  -H 'Content-Type: application/json' \
  -d '{
    "up_to": false,
    "num": 5,
    "size": 1000,
    "fee_rate": 1,
    "skip_sync": false
  }' | jq .

Parameters:

• up_to: false = create exactly num UTXOs
• num: Number of UTXOs to create (e.g., 5)
• size: Size of each UTXO in satoshis (e.g., 1000)
• fee_rate: Fee rate in sat/vbyte (e.g., 1)
• skip_sync: false = sync after creation

Mine blocks to confirm UTXOs:

docker compose exec bitcoind bitcoin-cli -rpcwallet=testwallet -generate 6

Check balance again to see UTXOs reflected:

curl -X POST http://127.0.0.1:3001/btcbalance \
  -H 'Content-Type: application/json' \
  -d '{"skip_sync": false}' | jq .

---

8. Work with RGB Assets

8.1 Issue RGB Asset

Create a new RGB asset (NIA - Non-Inflatable Asset):

curl -X POST http://127.0.0.1:3001/issueassetnia \
  -H 'Content-Type: application/json' \
  -d '{
    "ticker": "TESTRGB",
    "name": "Test RGB Asset",
    "precision": 0,
    "amounts": [1000],
    "description": "A test RGB asset for demonstration"
  }' | jq .

Response example:

{
  "asset_id": "rgb1...",
  "invoice": "..."
}

Save the asset_id for later use.

8.2 List Assets

curl -X POST http://127.0.0.1:3001/listassets \
  -H 'Content-Type: application/json' \
  -d '{"filter_asset_schemas": []}' | jq .

8.3 Send Bitcoin

# Replace <RECIPIENT_ADDRESS> with the destination Bitcoin address
curl -X POST http://127.0.0.1:3001/sendbtc \
  -H 'Content-Type: application/json' \
  -d '{
    "address": "<RECIPIENT_ADDRESS>",
    "amount": 50000,
    "fee_rate": 1,
    "skip_sync": false
  }' | jq .

Mine blocks to confirm:

docker compose exec bitcoind bitcoin-cli -rpcwallet=testwallet -generate 6

8.4 Send RGB Asset

To send RGB assets, you need a blinded receive invoice from the recipient. For testing with another node:

Step 1: Generate a blinded receive invoice (from recipient node):

# On recipient node
curl -X POST http://127.0.0.1:3002/rgb_blind_receive \
  -H 'Content-Type: application/json' \
  -d '{
    "asset_id": "<ASSET_ID>",
    "duration_seconds": 3600,
    "transport_endpoints": ["rpc://127.0.0.1:3000/json-rpc"],
    "min_confirmations": 1
  }' | jq .

Step 2: Send the asset using the recipient_id from the invoice:

curl -X POST http://127.0.0.1:3001/sendasset \
  -H 'Content-Type: application/json' \
  -d '{
    "asset_id": "<ASSET_ID>",
    "recipient_id": "bcrt:utxob:...",
    "amount": 100,
    "fee_rate": 1,
    "invoice": null
  }' | jq .

Step 3: Mine blocks to confirm:

docker compose exec bitcoind bitcoin-cli -rpcwallet=testwallet -generate 6

8.5 List Transfers

Check asset transfer history:

curl -X POST http://127.0.0.1:3001/listtransfers \
  -H 'Content-Type: application/json' \
  -d '{
    "asset_id": "<ASSET_ID>"
  }' | jq .

---

Troubleshooting

Node Unlock Stuck

Symptom: Unlock request hangs or times out.

Solutions:

1. Check if Electrs is ready:

   docker compose logs electrs | grep "waiting for 0 blocks"

2. Wait for Electrs to finish initial block download (IBD)
3. Restart services:

   docker compose restart electrs rgb-lightning-node

VLS Connection Errors

Symptom: error connecting to node in VLS logs.

Solutions:

1. Verify RGB Lightning Node is listening on port 7701:

   docker compose logs rgb-lightning-node | grep "7701"

2. Check network connectivity:

   docker network inspect rgb-lightning-node_default

3. Restart VLS container:

   docker restart vlsd-test

"InvalidValue" or "RecvError" Panics

Symptom: Server crashes with InvalidValue or RecvError during unlock.

Cause: Corrupted LDK data directory.

Solution:

# Stop services
docker compose down

# Clear LDK data
rm -rf dataldk0/.ldk

# Restart services
docker compose up -d

"No uncolored UTXOs are available"

Symptom: Cannot create or send assets.

Solutions:

1. Create UTXOs:

   curl -X POST http://127.0.0.1:3001/createutxos \
     -H 'Content-Type: application/json' \
     -d '{"up_to": false, "num": 5, "size": 1000, "fee_rate": 1, "skip_sync": false}'

2. Mine blocks to confirm:

   docker compose exec bitcoind bitcoin-cli -rpcwallet=testwallet -generate 6

3. Check balance to ensure funds are "spendable", not "future"

Address Mismatch Errors

Symptom: wallet address does not match output address in VLS.

Solution:

1. Get current RGB wallet address:

   curl -X POST http://127.0.0.1:3001/address -H 'Content-Type: application/json' -d '{}'

2. Restart VLS with updated allowlist:

   docker stop vlsd-test && docker rm vlsd-test
   # Restart with new address in VLS_ALLOWLIST (step 6.2)

Quick Reference

Service Ports

• RGB Lightning Node API: 3001
• LDK Peer Port: 9735
• VLS gRPC Port: 7701
• Bitcoin Core RPC: 18443
• Electrs: 50001
• RGB Proxy: 3000

Common Commands

# Check service status
docker compose ps

# View logs
docker compose logs -f rgb-lightning-node
docker logs -f vlsd-test

# Stop all services
docker compose down

# Restart a service
docker compose restart rgb-lightning-node

# Clean up everything
docker compose down -v
rm -rf dataldk0 datacore dataindex
docker volume rm vls_data_test

---