Rln

Docker environment is bundled at agent/docker-compose.yml.

Node Registry

Subcommand Reference

Query (Green — execute freely)

node_id <name>                  Get node's public key
balance <name>                  Get wallet + channel balances
channels <name>                 List channels
peers <name>                    List connected peers
status <name>                   Node status
network_status                  All nodes + bitcoin height
rgb_balance <name> [contract]   RGB asset balances

Operations (Yellow — execute then report result)

connect <from> <to>             Connect two peers (rgb-ldk/cln/lnd)
open_channel <from> <to> <sats> Open a BTC channel (rgb-ldk/cln/lnd)
open_rgb_channel <from> <to> <sats> <asset_id> <asset_amount>
                                Open an RGB channel (rgb-ldk only)
send_btc <from> <to> <sats>    Send BTC via Lightning (cross-impl OK)
send_rgb <from> <to> <asset> <amount>  Send RGB asset (rgb-ldk only)
import_issuer <name> [issuer]   Import RGB issuer (rgb-ldk only)
issue_rgb <name> <ticker> <supply>     Issue new RGB asset (rgb-ldk only)
fund <name> [btc_amount]        Fund node from bitcoind (all types)
mine [blocks]                   Mine regtest blocks (default: 6)
sync <name>                     Sync node wallet (no-op for cln/lnd)

Destructive (Red — ask user for confirmation before executing)

close_channel <name> <chan_id>  Close a channel (all types)

Playbooks (composite — one command runs full workflow)

btc_e2e_test [from] [to] [sats] [pay_sats]
                                BTC: connect → open → mine → pay
rgb_e2e_test [from] [to] [ticker] [supply] [chan_sats] [asset_amt] [pay_amt]
                                RGB: issue → connect → open → mine → pay
full_e2e_test [from] [to]       Run both BTC and RGB E2E tests
cross_e2e_test [from] [to] [sats] [pay_sats]
                                Cross-impl: fund → connect → open → mine → pay

Setup

network_setup                   Start docker (default: alice + bob)
network_setup --full            Start docker (+ CLN + LND)

Playbooks

First-time Setup

1. network_setup — starts Docker (alice + bob), waits for readiness, funds nodes

Quick BTC Test (one command)

btc_e2e_test alice bob 500000 1000

Quick RGB Test (one command)

rgb_e2e_test alice bob USDT 500000 500000 100000 1000

Full Test (BTC + RGB, one command)

full_e2e_test alice bob

Manual: Open Channel Between Two RGB-LDK Nodes

1. connect alice bob
2. open_channel alice bob 500000
3. mine 6 then sync alice
4. Verify: channels alice

Manual: Issue and Send RGB Asset

1. issue_rgb alice USDT 500000
2. open_rgb_channel alice bob 500000 <asset_id> 100000
3. mine 6 then sync alice then sync bob
4. send_rgb alice bob <asset_id> 1000

Safety Rules

• Green (query): Execute without asking. Show results directly.
• Yellow (operations): Execute, then report what happened.
• Red (destructive): Always confirm with user before executing.
• Playbooks: Execute freely — they are composite operations with built-in verification.

Conventions

• Amounts default to sats (satoshis) unless user specifies otherwise.
• Network is always regtest.
• Output is JSON. Parse and present in human-readable form.
• If a command fails, show the error JSON and suggest next steps.
• When user says "alice's balance", run balance alice.
• When user says "alice send bob 1000", run send_btc alice bob 1000.
• When user says "run the full test", run full_e2e_test alice bob.