lndmanage 0.7.1

Channel management tool for lightning network daemon (LND) operators.

lndmanage

lndmanage is a command line tool for advanced channel management of an LND node.

Current feature list (use the --help flag for subcommands):

• Display the node summary status
• Advanced channel listings listchannels
  • listchannels rebalance: list channels for rebalancing
  • listchannels inactive: list inactive channels for channel hygiene
  • listchannels forwardings: list forwarding statistics for each channel
• Rebalancing command rebalance
  • different rebalancing strategies can be chosen
  • a target 'balancedness' can be specified (e.g. to empty the channel)
• Circular self-payments circle
• Recommendation of good nodes recommend-nodes
  • recommend-nodes good-old: based on historic forwardings of closed channels: find nodes already interacted with
  • recommend-nodes flow-analysis: based on forwarding flow analysis: find nodes payments are likely forwarded to
  • recommend-nodes external-source: based on an external source: parses a url/file for node public keys and suggests nodes to connect to (defaults to the list of lightning networkstores)
  • recommend-nodes channel-openings: based on recent channel openings in the network: find nodes which show increased recent channel opening activity

DISCLAIMER: This is BETA software, so please be careful (All actions are executed as a dry run unless you call lndmanage with the --reckless flag though). No warranty is given.

Command line options

usage: lndmanage.py [-h] [--loglevel {INFO,DEBUG}]
                    {status,listchannels,rebalance,circle} ...

Lightning network daemon channel management tool.

positional arguments:
  {status,listchannels,rebalance,circle}
    status              display node status
    listchannels        lists channels with extended information [see also
                        subcommands with -h]
    rebalance           rebalance a channel
    circle              circular self-payment
    recommend-nodes     recommends nodes [see also subcommands with -h]

Rebalancing a channel

The workflow for rebalancing a channel goes as follows:

• take a look at all your unbalanced channels with:

  $ lndmanage listchannels rebalance

  The output will look like:

  -------- Description --------
  ub         unbalancedness (see --help)
  cap        channel capacity [sat]
  lb         local balance [sat]
  rb         remote balance [sat]
  bf         peer base fee [msat]
  fr         peer fee rate
  cid        channel id
  a          alias
  
  -------- Channels --------
         cid            ub       cap        lb        rb     bf        fr  a       
  xxxxxxxxxxxxxxxxxx -0.78   1000000    888861     99480     10  0.000200 abc                
  xxxxxxxxxxxxxxxxxx -0.63   1000000    814537    173768    300  0.000010 def
  xxxxxxxxxxxxxxxxxx  0.55   2000000    450792   1540038     35  0.000002 ghi
  xxxxxxxxxxxxxxxxxx  0.59    400000     81971    306335    400  0.000101 jkl
  ...
  

• the ub field tells you how unbalanced your channel is and in which direction

• take a channel_id from the list you wish to rebalance (target is a 50:50 balance)

• do a dry run to see what's waiting for you

  $ lndmanage rebalance --max-fee-sat 20 --max-fee-rate 0.00001 channel_id

• read the output and if everything looks well, then run with the --reckless flag

• in order to increase the success probability of your rebalancing you can try to do it in smaller chunks, which can be set by the flag --chunksize 0.5 (in this example only half the amounts are used)

Channel hygiene

Inactive channels lock up capital, which can be used elsewhere. In order to close those channels it is useful to take a look at the inactive channels with $ lndmanage listchannels inactive.

You will get an output like:

-------- Description --------
p          true if private channel
ini        true if we opened channel
lup        last update time [days ago]
age        channel age [days]
cap        capacity [sat]
lb         local balance [sat]
sr/w       satoshis sent + received per week of lifespan
cid        channel id
a          alias

-------- Channels --------
       cid         p ini   lup   age       cap        lb     sr/w  a       
xxxxxxxxxxxxxxxxxx F   F    66    71   2000000     10000      100 abc
xxxxxxxxxxxxxxxxxx T   F    20   113     40000         0        0 def
xxxxxxxxxxxxxxxxxx F   T    19    21   1200000      1000        0 ghi
...

Channels, which were updated a long time ago (lup) are likely to be inactive in the future and may be closed.

Another way to see if funds have to be reallocated is to have a look at the forwarding statistics of, e.g., the last two months of the individual channels with $lndmanage listchannels forwardings --from-days-ago 60 --sort-by='fees' (here sorted by total fees, but it can be sorted by any column field).

The output will look like:

-------- Description --------
cid        channel id
nfwd       number of forwardings
age        channel age [days]
fees       fees total [sat]
f/w        fees per week [sat]
ub         unbalancedness
flow       flow direction (positive is outwards)
bwd        bandwidth demand: capacity / max(mean_in, mean_out)
r          rebalance required if marked with X
cap        channel capacity [sat]
in         total forwardings inwards [sat]
imean      mean forwarding inwards [sat]
imax       largest forwarding inwards [sat]
out        total forwardings outwards [sat]
omean      mean forwarding outwards [sat]
omax       largest forwarding outwards [sat]
a          alias

-------- Channels --------
       cid         nfwd   age  fees     f/w    ub  flow  bwd r      cap       in   imean    imax      out   omean    omax  a
xxxxxxxxxxxxxxxxxx    6   103   907 106.950  0.30  1.00 0.00 X  6000000        0     nan     nan  1935309   20000 1800902 abc
xxxxxxxxxxxxxxxxxx    3    82   300  35.374  0.74 -0.08 0.70    1000000   700008  700008  700008   600000  600000  600000 def
xxxxxxxxxxxxxxxxxx    4    32   216  25.461  0.38  0.42 0.17 X  6000000   993591  993591  993591  2450000  750000 1000000 ghi
...

Channel opening strategies

Lndmanage supports a channel annotation functionality. This serves for remembering why a certain channel was opened. By adding the funding transaction id or channel id to the config file ~/.lndmanage/config.ini under the annotations section (as specified in config_sample.ini), annotations can be saved. These annotations will then appear in the listchannels views.

Setup

Lndmanage will be developed in lockstep with lnd and tagged accordingly. If you are running an older version of lnd checkout the according tag.

Requirements: python3.6, lnd v0.7.0-beta

If you run this tool from a different host than the lnd host, make sure to copy /path/to/.lnd/data/chain/bitcoin/mainnet/admin.macaroon and /path/to/.lnd/tls.cert to your local machine, which you need for later configuration.

Linux:

You can install lndmanage via two methods:

1. Install with pip (recommended):

$ python3 -m venv venv
$ source venv/bin/activate
$ python3 -m pip install lndmanage

2. Install from source:

$ git clone https://github.com/bitromortac/lndmanage
$ cd lndmanage
$ python3 -m venv venv
$ source venv/bin/activate
$ python3 setup.py install

Windows (powershell): Install python3, git, and visual studio build tools.

You need to set the environment variable PYTHONIOENCODING for proper encoding to: $env:PYTHONIOENCODING="UTF-8"

1. Install with pip (recommended):

$ py -m venv venv
$ .\venv\Scripts\activate
$ python -m pip install lndmanage

2. Install from source:

$ git clone https://github.com/bitromortac/lndmanage
$ cd lndmanage
$ py -m venv venv
$ .\venv\Scripts\activate
$ python setup.py install

Configuration:

When starting lndmanage for the first time, it will create a runtime folder /home/user/.lndmanage, where the configuration config.ini and log files reside. This folder location can be overwritten by setting an environment variable LNDMANAGE_HOME. If you run this tool from a remote host to the lnd host, you need to configure config.ini.

Running lndmanage

The installation process created an executable lndmanage, which will only be available if the created python environment is active (your prompt should have an (venv) in front):

$ source venv/bin/activate

then run

(venv) $ lndmanage status

If it works, you should see the node status.

Testing

Requirements are an installation of lnregtest and links to bitcoind, bitcoin-cli, lnd, and lncli in the test/bin folder.

Tests can be run with python3 -m unittest discover test from the root folder.

Docker

Due to restructuring of the project, this option is currently defunct.

If you prefer to run lndmanage from a docker container, cd docker and follow README there.

Compiling grpc in python [development]

$ cd grpc_compiled
$ pip install grpcio grpcio-tools googleapis-common-protos
$ git clone https://github.com/googleapis/googleapis.git
$ curl -o rpc.proto -s https://raw.githubusercontent.com/lightningnetwork/lnd/master/lnrpc/rpc.proto
$ python -m grpc_tools.protoc --proto_path=googleapis:. --python_out=. --grpc_python_out=. rpc.proto