2017-01-12 03:12:32 +03:00
|
|
|
This document is written for people who are eager to do something with
|
2017-01-13 04:11:46 +03:00
|
|
|
the Lightning Network Daemon (`lnd`). This folder uses `docker-compose` to
|
|
|
|
package `lnd` and `btcd` together to make deploying the two daemons as easy as
|
|
|
|
typing a few commands. All configuration between `lnd` and `btcd` are handled
|
|
|
|
automatically by their `docker-compose` config file.
|
|
|
|
|
2017-01-18 02:32:12 +03:00
|
|
|
### Prerequisites
|
|
|
|
Name | Version
|
2017-03-28 02:20:31 +03:00
|
|
|
--------|---------
|
|
|
|
docker-compose | 1.9.0
|
|
|
|
docker | 1.13.0
|
2017-01-18 02:32:12 +03:00
|
|
|
|
|
|
|
### Table of content
|
|
|
|
* [Create lightning network cluster](#create-lightning-network-cluster)
|
|
|
|
* [Connect to faucet lightning node](#connect-to-faucet-lightning-node)
|
|
|
|
* [Questions](#questions)
|
|
|
|
|
|
|
|
### Create lightning network cluster
|
|
|
|
This section describes a workflow on `simnet`, a development/test network
|
2017-01-13 04:11:46 +03:00
|
|
|
that's similar to Bitcoin Core's `regtest` mode. In `simnet` mode blocks can be
|
2017-03-01 04:33:59 +03:00
|
|
|
generated at will, as the difficulty is very low. This makes it an ideal
|
2017-01-13 04:11:46 +03:00
|
|
|
environment for testing as one doesn't need to wait tens of minutes for blocks
|
|
|
|
to arrive in order to test channel related functionality. Additionally, it's
|
|
|
|
possible to spin up an arbitrary number of `lnd` instances within containers to
|
|
|
|
create a mini development cluster. All state is saved between instances using a
|
|
|
|
shared value.
|
|
|
|
|
|
|
|
Current workflow is big because we recreate the whole network by ourselves,
|
|
|
|
next versions will use the started `btcd` bitcoin node in `testnet` and
|
|
|
|
`faucet` wallet from which you will get the bitcoins.
|
|
|
|
|
|
|
|
In the workflow below, we describe the steps required to recreate following
|
|
|
|
topology, and send a payment from `Alice` to `Bob`.
|
2017-01-12 03:12:32 +03:00
|
|
|
```
|
|
|
|
+ ----- + + --- +
|
|
|
|
| Alice | <--- channel ---> | Bob | <--- Bob and Alice are the lightning network daemons which
|
|
|
|
+ ----- + + --- + creates the channel and interact with each other using
|
|
|
|
| | Bitcoin network as source of truth.
|
|
|
|
| |
|
|
|
|
+ - - - - - + - - - - - - +
|
|
|
|
|
|
2017-01-18 02:32:12 +03:00
|
|
|
+ --------------- +
|
|
|
|
| Bitcoin network | <--- In current scenario for simplicity we create only one
|
|
|
|
+ --------------- + "btcd" node which represents the Bitcoin network, in
|
2017-01-12 03:12:32 +03:00
|
|
|
real situation Alice and Bob will likely be
|
|
|
|
connected to different Bitcoin nodes.
|
|
|
|
```
|
|
|
|
|
2017-03-28 02:20:31 +03:00
|
|
|
**General workflow is the following:**
|
2017-01-13 04:11:46 +03:00
|
|
|
|
|
|
|
* Create a `btcd` node running on a private `simnet`.
|
2017-03-21 16:17:24 +03:00
|
|
|
* Create `Alice`, one of the `lnd` nodes in our simulation network.
|
|
|
|
* Create `Bob`, the other `lnd` node in our simulation network.
|
|
|
|
* Mine some blocks to send `Alice` some bitcoins.
|
2017-01-13 04:11:46 +03:00
|
|
|
* Open channel between `Alice` and `Bob`.
|
|
|
|
* Send payment from `Alice` to `Bob`.
|
2017-03-28 02:20:31 +03:00
|
|
|
* Close the channel between `Alice` and `Bob`.
|
|
|
|
* Check that on-chain `Bob` balance was changed.
|
2017-01-13 04:11:46 +03:00
|
|
|
|
|
|
|
Start `btcd`, and then create an address for `Alice` that we'll directly mine
|
|
|
|
bitcoin into.
|
2017-01-12 03:12:32 +03:00
|
|
|
```bash
|
2017-01-18 02:32:12 +03:00
|
|
|
# Init bitcoin network env variable:
|
2017-05-13 23:21:14 +03:00
|
|
|
$ export NETWORK="simnet"
|
2017-01-18 02:32:12 +03:00
|
|
|
|
2017-01-13 04:11:46 +03:00
|
|
|
# Run the "Alice" container and log into it:
|
2017-07-04 23:25:24 +03:00
|
|
|
$ docker-compose run -d --name alice lnd_btc
|
|
|
|
$ docker exec -i -t alice bash
|
2017-01-12 03:12:32 +03:00
|
|
|
|
2017-01-18 02:32:12 +03:00
|
|
|
# Generate a new backward compatible nested p2sh address for Alice:
|
2017-01-12 03:12:32 +03:00
|
|
|
alice$ lncli newaddress np2wkh
|
|
|
|
|
2017-01-13 04:11:46 +03:00
|
|
|
# Recreate "btcd" node and set Alice's address as mining address:
|
2017-07-04 23:25:24 +03:00
|
|
|
$ MINING_ADDRESS=<alice_address> docker-compose up -d btcd
|
2017-01-12 03:12:32 +03:00
|
|
|
|
2017-01-18 02:32:12 +03:00
|
|
|
# Generate 400 block (we need at least "100 >=" blocks because of coinbase
|
|
|
|
# block maturity and "300 ~=" in order to activate segwit):
|
|
|
|
$ docker-compose run btcctl generate 400
|
2017-01-12 03:12:32 +03:00
|
|
|
|
|
|
|
# Check that segwit is active:
|
|
|
|
$ docker-compose run btcctl getblockchaininfo | grep -A 1 segwit
|
|
|
|
```
|
|
|
|
|
2017-03-28 02:20:31 +03:00
|
|
|
Check `Alice` balance:
|
|
|
|
```
|
2017-01-12 03:12:32 +03:00
|
|
|
alice$ lncli walletbalance --witness_only=true
|
|
|
|
```
|
|
|
|
|
|
|
|
Connect `Bob` node to `Alice` node.
|
2017-03-28 02:20:31 +03:00
|
|
|
|
2017-01-12 03:12:32 +03:00
|
|
|
```bash
|
|
|
|
# Run "Bob" node and log into it:
|
2017-08-29 13:35:16 +03:00
|
|
|
$ docker-compose run -d --name bob lnd_btc
|
2017-07-04 23:25:24 +03:00
|
|
|
$ docker exec -i -t bob bash
|
2017-01-12 03:12:32 +03:00
|
|
|
|
2017-01-13 04:11:46 +03:00
|
|
|
# Get the identity pubkey of "Bob" node:
|
2017-01-12 03:12:32 +03:00
|
|
|
bob$ lncli getinfo
|
|
|
|
|
2017-01-13 04:11:46 +03:00
|
|
|
{
|
2017-03-21 16:17:24 +03:00
|
|
|
----->"identity_pubkey": "0343bc80b914aebf8e50eb0b8e445fc79b9e6e8e5e018fa8c5f85c7d429c117b38",
|
|
|
|
"alias": "",
|
|
|
|
"num_pending_channels": 0,
|
|
|
|
"num_active_channels": 0,
|
|
|
|
"num_peers": 0,
|
|
|
|
"block_height": 1215,
|
|
|
|
"block_hash": "7d0bc86ea4151ed3b5be908ea883d2ac3073263537bcf8ca2dca4bec22e79d50",
|
|
|
|
"synced_to_chain": true,
|
|
|
|
"testnet": false
|
2017-05-03 06:49:40 +03:00
|
|
|
"chains": [
|
|
|
|
"bitcoin"
|
|
|
|
]
|
2017-01-13 04:11:46 +03:00
|
|
|
}
|
|
|
|
|
2017-01-12 03:12:32 +03:00
|
|
|
# Get the IP address of "Bob" node:
|
2017-07-04 23:25:24 +03:00
|
|
|
$ docker inspect bob | grep IPAddress
|
2017-01-12 03:12:32 +03:00
|
|
|
|
|
|
|
# Connect "Alice" to the "Bob" node:
|
2017-04-04 15:28:05 +03:00
|
|
|
alice$ lncli connect <bob_pubkey>@<bob_host>
|
2017-01-12 03:12:32 +03:00
|
|
|
|
|
|
|
# Check list of peers on "Alice" side:
|
|
|
|
alice$ lncli listpeers
|
2017-01-13 04:11:46 +03:00
|
|
|
{
|
2017-03-21 16:17:24 +03:00
|
|
|
"peers": [
|
|
|
|
{
|
|
|
|
"pub_key": "0343bc80b914aebf8e50eb0b8e445fc79b9e6e8e5e018fa8c5f85c7d429c117b38",
|
|
|
|
"peer_id": 1,
|
2017-08-22 10:40:51 +03:00
|
|
|
"address": "172.19.0.4:9735",
|
2017-03-21 16:17:24 +03:00
|
|
|
"bytes_sent": "357",
|
|
|
|
"bytes_recv": "357",
|
|
|
|
"sat_sent": "0",
|
|
|
|
"sat_recv": "0",
|
|
|
|
"inbound": true,
|
|
|
|
"ping_time": "0"
|
|
|
|
}
|
|
|
|
]
|
2017-01-13 04:11:46 +03:00
|
|
|
}
|
2017-01-12 03:12:32 +03:00
|
|
|
|
|
|
|
# Check list of peers on "Bob" side:
|
|
|
|
bob$ lncli listpeers
|
2017-01-13 04:11:46 +03:00
|
|
|
{
|
2017-03-21 16:17:24 +03:00
|
|
|
"peers": [
|
|
|
|
{
|
|
|
|
"pub_key": "03d0cd35b761f789983f3cfe82c68170cd1c3266b39220c24f7dd72ef4be0883eb",
|
|
|
|
"peer_id": 1,
|
|
|
|
"address": "172.19.0.3:51932",
|
|
|
|
"bytes_sent": "357",
|
|
|
|
"bytes_recv": "357",
|
|
|
|
"sat_sent": "0",
|
|
|
|
"sat_recv": "0",
|
|
|
|
"inbound": false,
|
|
|
|
"ping_time": "0"
|
|
|
|
}
|
|
|
|
]
|
2017-01-13 04:11:46 +03:00
|
|
|
}
|
2017-01-12 03:12:32 +03:00
|
|
|
```
|
|
|
|
|
2017-01-13 04:11:46 +03:00
|
|
|
Create the `Alice<->Bob` channel.
|
2017-01-12 03:12:32 +03:00
|
|
|
```bash
|
|
|
|
# Open the channel with "Bob":
|
2017-08-29 13:35:16 +03:00
|
|
|
alice$ lncli openchannel --node_key=<bob_identity_pubkey> --local_amt=1000000
|
2017-01-12 03:12:32 +03:00
|
|
|
|
|
|
|
# Include funding transaction in block thereby open the channel:
|
|
|
|
$ docker-compose run btcctl generate 1
|
|
|
|
|
|
|
|
# Check that channel with "Bob" was created:
|
|
|
|
alice$ lncli listchannels
|
2017-01-13 04:11:46 +03:00
|
|
|
{
|
2017-03-21 16:17:24 +03:00
|
|
|
"channels": [
|
|
|
|
{
|
|
|
|
"active": true,
|
|
|
|
"remote_pubkey": "0343bc80b914aebf8e50eb0b8e445fc79b9e6e8e5e018fa8c5f85c7d429c117b38",
|
|
|
|
"channel_point": "3511ae8a52c97d957eaf65f828504e68d0991f0276adff94c6ba91c7f6cd4275:0",
|
|
|
|
"chan_id": "1337006139441152",
|
|
|
|
"capacity": "1005000",
|
|
|
|
"local_balance": "1000000",
|
|
|
|
"remote_balance": "0",
|
|
|
|
"unsettled_balance": "0",
|
|
|
|
"total_satoshis_sent": "0",
|
|
|
|
"total_satoshis_received": "0",
|
|
|
|
"num_updates": "0"
|
|
|
|
}
|
|
|
|
]
|
2017-01-13 04:11:46 +03:00
|
|
|
}
|
2017-01-12 03:12:32 +03:00
|
|
|
```
|
|
|
|
|
2017-01-18 02:32:12 +03:00
|
|
|
Send the payment form `Alice` to `Bob`.
|
|
|
|
```bash
|
2017-01-12 03:12:32 +03:00
|
|
|
# Add invoice on "Bob" side:
|
2017-01-18 02:32:12 +03:00
|
|
|
bob$ lncli addinvoice --value=10000
|
2017-01-13 04:11:46 +03:00
|
|
|
{
|
|
|
|
"r_hash": "<your_random_rhash_here>",
|
|
|
|
"pay_req": "<encoded_invoice>",
|
|
|
|
}
|
2017-01-12 03:12:32 +03:00
|
|
|
|
|
|
|
# Send payment from "Alice" to "Bob":
|
2017-01-18 02:32:12 +03:00
|
|
|
alice$ lncli sendpayment --pay_req=<encoded_invoice>
|
2017-01-12 03:12:32 +03:00
|
|
|
|
2017-07-04 23:25:24 +03:00
|
|
|
# Check "Alice"'s channel balance
|
|
|
|
alice$ lncli channelbalance
|
2017-01-12 03:12:32 +03:00
|
|
|
|
2017-07-04 23:25:24 +03:00
|
|
|
# Check "Bob"'s channel balance
|
|
|
|
bob$ lncli channelbalance
|
2017-01-12 03:12:32 +03:00
|
|
|
```
|
|
|
|
|
2017-03-01 04:33:59 +03:00
|
|
|
Now we have open channel in which we sent only one payment, let's imagine
|
|
|
|
that we sent lots of them and we'll now like to close the channel. Let's do
|
2017-01-13 04:11:46 +03:00
|
|
|
it!
|
2017-01-18 02:32:12 +03:00
|
|
|
```bash
|
2017-01-12 03:12:32 +03:00
|
|
|
# List the "Alice" channel and retrieve "channel_point" which represent
|
|
|
|
# the opened channel:
|
2017-01-18 02:32:12 +03:00
|
|
|
alice$ lncli listchannels
|
2017-01-13 04:11:46 +03:00
|
|
|
{
|
2017-03-21 16:17:24 +03:00
|
|
|
"channels": [
|
|
|
|
{
|
|
|
|
"active": true,
|
|
|
|
"remote_pubkey": "0343bc80b914aebf8e50eb0b8e445fc79b9e6e8e5e018fa8c5f85c7d429c117b38",
|
|
|
|
---->"channel_point": "3511ae8a52c97d957eaf65f828504e68d0991f0276adff94c6ba91c7f6cd4275:0",
|
|
|
|
"chan_id": "1337006139441152",
|
|
|
|
"capacity": "1005000",
|
|
|
|
"local_balance": "990000",
|
|
|
|
"remote_balance": "10000",
|
|
|
|
"unsettled_balance": "0",
|
|
|
|
"total_satoshis_sent": "10000",
|
|
|
|
"total_satoshis_received": "0",
|
|
|
|
"num_updates": "2"
|
|
|
|
}
|
|
|
|
]
|
2017-01-13 04:11:46 +03:00
|
|
|
}
|
|
|
|
|
2017-01-18 02:32:12 +03:00
|
|
|
# Channel point consist of two numbers separated by colon the first one
|
|
|
|
# is "funding_txid" and the second one is "output_index":
|
|
|
|
alice$ lncli closechannel --funding_txid=<funding_txid> --output_index=<output_index>
|
2017-01-12 03:12:32 +03:00
|
|
|
|
|
|
|
# Include close transaction in block thereby close the channel:
|
|
|
|
$ docker-compose run btcctl generate 1
|
|
|
|
|
2017-01-13 04:11:46 +03:00
|
|
|
# Check "Alice" on-chain balance was credited by her settled amount in the channel:
|
2017-01-18 02:32:12 +03:00
|
|
|
alice$ lncli walletbalance
|
2017-01-12 03:12:32 +03:00
|
|
|
|
2017-01-13 04:11:46 +03:00
|
|
|
# Check "Bob" on-chain balance was credited with the funds he received in the
|
|
|
|
# channel:
|
2017-01-18 02:32:12 +03:00
|
|
|
bob$ lncli walletbalance
|
2017-03-21 16:17:24 +03:00
|
|
|
{
|
2017-11-26 16:33:32 +03:00
|
|
|
"total_balance": "0.0001",
|
|
|
|
"confirmed_balance": "0.0001",
|
|
|
|
"unconfirmed_balance": "0"
|
2017-03-21 16:17:24 +03:00
|
|
|
}
|
2017-01-12 03:12:32 +03:00
|
|
|
```
|
|
|
|
|
2017-01-18 02:32:12 +03:00
|
|
|
### Connect to faucet lightning node
|
|
|
|
In order to be more confident with `lnd` commands I suggest you to try
|
2017-03-01 04:33:59 +03:00
|
|
|
to create a mini lightning network cluster ([Create lightning network cluster](#create-lightning-network-cluster)).
|
2017-01-18 02:32:12 +03:00
|
|
|
|
2017-04-04 15:28:05 +03:00
|
|
|
In this section we will try to connect our node to the faucet/hub node
|
2017-01-18 02:32:12 +03:00
|
|
|
which will create with as the channel and send as some amount of
|
|
|
|
bitcoins. The schema will be following:
|
|
|
|
|
|
|
|
```
|
|
|
|
+ ----- + + ------ + (1) + --- +
|
|
|
|
| Alice | <--- channel ---> | Faucet | <--- channel ---> | Bob |
|
|
|
|
+ ----- + + ------ + + --- +
|
|
|
|
| | |
|
|
|
|
| | | <--- (2)
|
|
|
|
+ - - - - - - - - - - - - - + - - - - - - - - - - - - - +
|
|
|
|
|
|
|
|
|
+ --------------- +
|
|
|
|
| Bitcoin network | <--- (3)
|
|
|
|
+ --------------- +
|
|
|
|
|
|
|
|
|
2017-10-14 22:11:33 +03:00
|
|
|
(1) You may connect an additinal node "Bob" and make the multihop
|
2017-01-18 02:32:12 +03:00
|
|
|
payment Alice->Faucet->Bob
|
|
|
|
|
|
|
|
(2) "Faucet", "Alice" and "Bob" are the lightning network daemons which
|
|
|
|
creates the channel and interact with each other using Bitcoin network
|
|
|
|
as source of truth.
|
|
|
|
|
|
|
|
(3) In current scenario "Alice" and "Faucet" lightning network nodes
|
|
|
|
connected to different Bitcoin nodes. If you decide to connect "Bob"
|
|
|
|
to "Faucet" than already created "btcd" node would be sufficient.
|
|
|
|
```
|
|
|
|
|
2017-11-28 02:18:30 +03:00
|
|
|
First of all you need to run `btcd` node in `testnet` and wait for it to be
|
2017-08-04 02:33:54 +03:00
|
|
|
synced with test network (`May the Force and Patience be with you`).
|
2017-01-18 02:32:12 +03:00
|
|
|
```bash
|
|
|
|
# Init bitcoin network env variable:
|
2017-05-13 23:21:14 +03:00
|
|
|
$ export NETWORK="testnet"
|
2017-01-18 02:32:12 +03:00
|
|
|
|
|
|
|
# Run "btcd" node:
|
|
|
|
$ docker-compose up -d "btcd"
|
|
|
|
```
|
|
|
|
|
|
|
|
After `btcd` synced, connect `Alice` to the `Faucet` node.
|
|
|
|
```bash
|
|
|
|
# Run "Alice" container and log into it:
|
|
|
|
$ docker-compose up -d "alice"; docker exec -i -t "alice" bash
|
|
|
|
|
|
|
|
# Connect "Alice" to the "Faucet" node:
|
2017-04-04 15:28:05 +03:00
|
|
|
alice$ lncli connect <faucet_identity_address>@<faucet_host>
|
2017-01-18 02:32:12 +03:00
|
|
|
```
|
|
|
|
|
|
|
|
After connection was achieved the `Faucet` node should create the channel
|
|
|
|
and send some amount of bitcoins to `Alice`.
|
|
|
|
|
|
|
|
**What you may do next?:**
|
|
|
|
- Send some amount to `Faucet` node back.
|
|
|
|
- Connect `Bob` node to the `Faucet` and make multihop payment (`Alice->Faucet->Bob`)
|
|
|
|
- Close channel with `Faucet` and check the onchain balance.
|
2017-01-12 03:12:32 +03:00
|
|
|
|
|
|
|
### Questions
|
2017-01-18 02:32:12 +03:00
|
|
|
[![Irc](https://img.shields.io/badge/chat-on%20freenode-brightgreen.svg)]
|
|
|
|
(https://webchat.freenode.net/?channels=lnd)
|
|
|
|
|
2017-01-12 03:12:32 +03:00
|
|
|
* How to see `alice` | `bob` | `btcd` logs?
|
2017-01-18 02:32:12 +03:00
|
|
|
```bash
|
2017-03-21 16:17:24 +03:00
|
|
|
docker-compose logs <alice|bob|btcd>
|
2017-03-01 04:33:59 +03:00
|
|
|
```
|