diff --git a/docker/README.md b/docker/README.md index 38a46545..6c9b87fa 100644 --- a/docker/README.md +++ b/docker/README.md @@ -1,12 +1,26 @@ ### Getting started This document is written for people who are eager to do something with -lightning network daemon (`lnd`). 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. +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. -In current readme we decribe the steps which are needed to recreate -following schema, and send payment from `Alice` to `Bob`. + +This document describes a workflow on `simnet`, a development/test network +that's similar to Bitcoin Core's `regtest` mode. In `simnet` mode blocks can be +generated as will, as the difficulty is very low. This makes it an ideal +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`. ``` + ----- + + --- + | Alice | <--- channel ---> | Bob | <--- Bob and Alice are the lightning network daemons which @@ -29,26 +43,29 @@ following schema, and send payment from `Alice` to `Bob`. docker | 1.13.0 **General workflow is following:** - * Create Bitcoin network - * Create `Alice` node - * Create `Bob` node - * Initialize `Alice` node with some amount of bitcoins - * Open channel between `Alice` and `Bob` - * Send payment from `Alice` to `Bob` -Start the `btcd`, create `Alice` address and mine some bitcoins. + * Create a `btcd` node running on a private `simnet`. + * Create `Alice`, one of the `lnd` nodes in our test network. + * Create `Bob`, the other `lnd` node in our test network. + * Mine some blocks to send `Alice` some bitcoin. + * Open channel between `Alice` and `Bob`. + * Send payment from `Alice` to `Bob`. + * Finally, close the channel between `Alice` and Bob`. + +Start `btcd`, and then create an address for `Alice` that we'll directly mine +bitcoin into. ```bash # Create "btcd" node: $ docker-compose up -d "btcd" -# Run "Alice" container and log into it: +# Run the "Alice" container and log into it: $ docker-compose up -d "alice" $ docker exec -i -t "alice" bash -# Generate new backward compatible "segwit" "alice" address: +# Generate a new backward compatible nested p2sh for from Alice: alice$ lncli newaddress np2wkh -# Recreate "btcd" node and set "alice" address as mining address: +# Recreate "btcd" node and set Alice's address as mining address: $ MINING_ADDRESS= docker-compose up -d "btcd" # Generate 201 block (we need at least "100 >=" blocks because of coinbase @@ -59,9 +76,9 @@ $ docker-compose run btcctl generate 250 $ docker-compose run btcctl getblockchaininfo | grep -A 1 segwit ``` -Now we have `btcd` node turned on and some amount of bitcoins mined on -`Alice` address. But in order `lnd` saw them lets restart the `lnd` -daemon. +Now we have `btcd` running and some amount of bitcoins mined to the `Alice` +address. We'll need to restart `Alice` just once so she properly syncs up with +`btcd`. ```bash # Stop "Alice" container: $ docker-compose stop "alice" @@ -80,67 +97,128 @@ Connect `Bob` node to `Alice` node. $ docker-compose up --no-recreate -d "bob" $ docker exec -i -t "bob" bash -# Get the identity address of "Bob" node: +# Get the identity pubkey of "Bob" node: bob$ lncli getinfo +{ + ----> "identity_pubkey": "0290bf454f4b95baf9227801301b331e35d477c6b6e7f36a599983ae58747b3828", + "block_height": 3949, + "block_hash": "00000000853c9dcccf8879abb0a91f0152aed16efe68015a924156f5845016ee", + "synced_to_chain": true, + "testnet": false, +} + # Get the IP address of "Bob" node: $ docker inspect "bob" | grep IPAddress # Connect "Alice" to the "Bob" node: -alice$ lncli connect @:10011 +alice$ lncli connect @:10011 # Check list of peers on "Alice" side: alice$ lncli listpeers +{ + "peers": [ + { + "pub_key": "0290bf454f4b95baf9227801301b331e35d477c6b6e7f36a599983ae58747b3828", + "peer_id": 1, + "address": "10.0.0.125:10011", + "bytes_sent": 3278, + "bytes_recv": 3278 + } + ] +} # Check list of peers on "Bob" side: bob$ lncli listpeers +{ + "peers": [ + { + "pub_key": "036a0c5ea35df8a528b98edf6f290b28676d51d0fe202b073fe677612a39c0aa09", + "peer_id": 1, + "address": "10.0.0.15:10011", + "bytes_sent": 3278, + "bytes_recv": 3278 + } + ] +} ``` -Create `Alice<->Bob` channel. +Create the `Alice<->Bob` channel. ```bash # Open the channel with "Bob": -alice$ lncli openchannel --node_key= --num_confs=1 --local_amt=1000000 --push_amt=0 +alice$ lncli openchannel --node_key= --num_confs=1 --local_amt=1000000 # 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 +{ + "channels": [ + { + "remote_pubkey": "0290bf454f4b95baf9227801301b331e35d477c6b6e7f36a599983ae58747b3828", + "channel_point": "7a632cde9e9e2ae4e9209591c0587bbb03254814c62e2a7fcef35ced743b0025:0", + "chan_id": 1170330072213225472, + "capacity": 1005000, + "local_balance": 1000000, + } + ] +} + ``` Send the payment form "Alice" to "Bob". ``` # Add invoice on "Bob" side: bob> lncli addinvoice --value=10000 +{ + "r_hash": "", + "pay_req": "", +} # Send payment from "Alice" to "Bob": alice> lncli sendpayment --pay_req= -# Check "Alice" channel balance was descreased on sent amount: +# Check "Alice"'s channel balance was decremented accordingly by the payment +# amount alice> lncli listchannels -# Check "Bob" channel balance was increased on sent amount: +# Check "Bob"'s channel balance was credited with the payment amount bob> lncli listchannels ``` Now we have open channel in which we sent only one payment, lets imagine -that we sent a lots of them and we ok to close channel. Lets do it. +that we sent a lots of them and we'll now like to close the channel. Lets do +it! ``` # List the "Alice" channel and retrieve "channel_point" which represent # the opened channel: alice> lncli listchannels +{ + "channels": [ + { + "remote_pubkey": "0290bf454f4b95baf9227801301b331e35d477c6b6e7f36a599983ae58747b3828", + "channel_point": "7a632cde9e9e2ae4e9209591c0587bbb03254814c62e2a7fcef35ced743b0025:0", + "chan_id": 1170330072213225472, + "capacity": 1005000, + "local_balance": 900000, + "remote_balance": 10000, + } + ] +} -# Channel point consist of two numbers devided by ":" the first on is +# Channel point consist of two numbers separated by colon the first on is # "funding_txid" and the second one is "output_index": alice> lncli closechannel --funding_txid= --output_index= # Include close transaction in block thereby close the channel: $ docker-compose run btcctl generate 1 -# Check "Alice" on-chain balance was descresed on sent amount: +# Check "Alice" on-chain balance was credited by her settled amount in the channel: alice> lncli walletbalance -# Check "Bob" on-chain balance was increased on sent amount: +# Check "Bob" on-chain balance was credited with the funds he received in the +# channel: bob> lncli walletbalance ``` @@ -149,4 +227,4 @@ bob> lncli walletbalance * How to see `alice` | `bob` | `btcd` logs? ``` docker-compose logs -``` \ No newline at end of file +```