The Story of David Kaspar

Well done, you have participated in a lightning liquidity swap and all channels are open (future post about how to actually do the swap and common problems).

Now you should see a new incoming channel and a new outgoing channel. The incoming channel will have all the liquidity remotely and your outgoing channel will have all the liquidity locally.

This means that no lightning payments can be routed via you. You have to balance those channels to have 50% local and 50% remote liquidity.

In summary your will pay yourself half of the channel capacity and route the payment through all the swap participants. This will result in all channels in the swap to become 50/50 balanced.

Case 1: Now for a simple triangle swap, where there are only two other participants, you can use the plugin Thunderhub or Ride The Lightning (RTL) to perform this payment.

Select the node you connected to as Outgoing. You should see 100% blue bar, this means the balance is all on your side (local).

Select the node that connected to you as Incoming. You should see a 100% green bar, this means that the balance is all on the other side (remote).

Set the fees to something you are comfortable with, perhaps 100 for each field.

 If your swap participants have done their job they have lowered all fees to 0 and the rebalance should be free.

Set the amount to Fixed and half the channel size (or slightly less if you get liquidity problems).

Hit rebalance!

Case 2: For any more complicated swaps like a square (4 participants) or a pentagram (5 participants) you will have to build an exact payment route through all the participants to do the balancing correctly (and cheaply).

You still want to pay yourself half the channel size but it has to go out to the node you connected to, then via each participant in the correct order, and then back in via the node that connected to you.

You will have to use the lncli command after you SSH to your node to perform this more complicated payment.

Some swap sites like lightningnetwork.plus will prepare the correct route for you already. Please start by running the provided command to test whether the route works correctly:

lncli buildroute --amt [AMOUNT] --hops 1a613234234116def5de68...,7243578234df738...,87827ea233...,014aea43432244...,0a34324445...

Replace the example hops with the actual public keys of the nodes in your swap.

If all is well you will get a json output with a prebuilt route and the cost for this transfer:

{
"route": {
"total_time_lock": 715773,
"total_fees": "4",
"total_amt": "1250004",
"hops": [
{…

If the fees seem too high then you should start a dialog with the other swap participants to lower their channel fees. Skill levels of the participants varies widely and you may need to assist them.

You can now prepare an invoice which will be the payment to yourself since the routing appears to be successful:

lncli addinvoice --amt [AMOUNT]

This command will return you a PAYMENT_ADDR and a R_HASH that you have to use in the below step.

You can now run the command provided by your service that will in a single line build the route using lncli buildroute, add a multi-payment record (mpp) using the jq utility and then send the payment using lncli sendtoroute:

lncli buildroute --amt [AMOUNT] --hops 1a613234234116def5de68…,7243578234df738…,87827ea233…,014aea43432244…,0a34324445… | jq -r '(.route.hops[-1] | .mpp_record) |= {payment_addr:"[PAYMENT_ADDR]", total_amt_msat: "[AMOUNT]"}' | lncli sendtoroute --payment_hash=[R_HASH] -

You can also construct the hops manually by hand by starting with the node you connected to, traverse the participants one by one and finishing with the public key of your own node.

If all goes well, you should get a SUCCESS result code and also information about the total fees paid.

Congratulations, you are now balanced!

Common problems with liquidity rebalancing

Not all channels have been set up.

The swap participants are reporting that they all have opened channels but how can you be sure? The lncli buildroute command is a quick way to test that the route is correctly set up.

Private channels

If a swap participant accidentally created a private channel instead of a public one then the liquidity swap will not work.

Not enough liquidity in existing channels

A participant can accidentally crate a smaller channel than specified.

I have also seen cases where participants already had existing channels with the other participants so they didn’t feel like creating additional ones.

This will however break the swap as the liquidity in the swap is less than was specified. Rebalancing will not work for example.

Remote node is down

You are unable to open the channel and you see errors like 503, 'FailedToSuccessfullyConnectToRemotePeer'.

This is likely due to the remote node being down, having TOR configuration issues or other resource problems. A restart of the remote node often helps.

Divide the channel opening process into two steps: 1) connect to the peer first and 2) open the channel with the existing peer

Node not accepting the specified channel size in the swap

A node can be misconfigured to only allow chanel size above a certain size… a size that is larger than the swap. Often this is due to am extra zero in the required channel size.

Blockchain reorg

Luckily this hasn’t happened to me but there is a theoretical scenario where the open channel has only one confirmation and due to blockchain reorg that transaction becomes void. Wait for a few confirmations before using a newly open channel!

You are using Umbrel and thus LND in a Docker container. You get the error “The input device is not a TTY”

Umbrel is popular Lightning node operating system. If uses docker container for many of the require services, such as lncli. This means you don’t have direct access to lcnli and linux “piping” between processes doesn’t work.

Split the routing command into two steps:

lncli buildroute --amt [AMOUNT] --hops 1a613234234116def5de68…,7243578234df738…,87827ea233…,014aea43432244…,0a34324445… | jq -r '(.route.hops[-1] | .mpp_record) |= {payment_addr:"[PAYMENT_ADDRESS]", total_amt_msat: "[AMOUNT]"}' > path.txt

lncli sendtoroute --payment_hash=[R_HASH] --routes="$(cat path.txt)"

“not enough witness outputs to create funding transaction”

You are opening a channel and you have enough funds in your on-chain wallet but you still get this error.

Some of your utxo are probably unconfirmed and you cannot spend them even though they are showing in your total balance.

You probably have some chennels pending. There are unconfirmed payments to yourself as part of it.

Wait until all channels are confirmed and all funds should be available again for new channel opening!