diff --git a/tutorial/01-lncli.md b/tutorial/01-lncli.md index 0a26865..f85a7dc 100644 --- a/tutorial/01-lncli.md +++ b/tutorial/01-lncli.md @@ -257,6 +257,7 @@ To see all the commands available for `lncli`, simply type `lncli --help` or `lncli -h`. ### Setting up Bitcoin addresses + Let's create a new Bitcoin address for Alice. This will be the address that stores Alice's on-chain balance. @@ -324,8 +325,9 @@ Generate 400 blocks, so that Alice gets the reward. We need at least 100 blocks because coinbase funds can't be spent until after 100 confirmations, and we need about 300 to activate segwit. window with `$GOPATH` and `$PATH` set. + ```bash -alice$ btcctl --simnet --rpcuser=kek --rpcpass=kek generate 400 +btcctl --simnet --rpcuser=kek --rpcpass=kek generate 400 ``` Check that segwit is active: @@ -335,11 +337,13 @@ btcctl --simnet --rpcuser=kek --rpcpass=kek getblockchaininfo | grep -A 1 segwit Check Alice's wallet balance. `--witness_only=true` specifies that we only want to consider witness outputs when calculating the wallet balance. + ```bash alice$ lncli-alice walletbalance --witness_only=true ``` It's no fun if only Alice any money. Let's give some to Charlie as well: + ```bash # Quit btcd btcd --txindex --simnet --rpcuser=kek --rpcpass=kek --miningaddr= @@ -423,20 +427,33 @@ bob$ lncli-bob listpeers ``` Finish up the P2P network by connecting Bob to Charlie: + ```bash charlie$ lncli-charlie connect @localhost:10012 ``` +and testing their connections: + +```bash +# Check that Charlie has added Bob as a peer: +charlie$ lncli-charlie listpeers + +# Check that Bob has added Charlie as a peer +bob$ lncli-bob listpeers +``` + ### Setting up Lightning Network Before we can send payment, we will need to set up payment channels from Alice to Bob, and Bob to Charlie. First, let's open the Alice<-->Bob channel. + ```bash alice$ lncli-alice openchannel --node_key= --local_amt=1000000 ``` -- `--local_amt` specifies the amount of money that Alice will commit to the + +- `--local_amt` specifies the amount of Satoshi that Alice will commit to the channel. To see the full list of options, you can try `lncli openchannel --help`. @@ -446,6 +463,7 @@ btcctl --simnet --rpcuser=kek --rpcpass=kek generate 6 ``` Check that Alice<-->Bob channel was created: + ```bash alice$ lncli-alice listchannels { @@ -476,8 +494,9 @@ Finally, to the exciting part - sending payments! Let's send a payment from Alice to Bob. First, Bob will need to generate an invoice: + ```bash -bob$ lncli-bob addinvoice --value=10000 +bob$ lncli-bob addinvoice --value=100000 { "r_hash": "", "pay_req": "", @@ -485,18 +504,19 @@ bob$ lncli-bob addinvoice --value=10000 ``` Send the payment from Alice to Bob: + ```bash alice$ lncli-alice sendpayment --pay_req= { "payment_preimage": "baf6929fc95b3824fb774a4b75f6c8a1ad3aaef04efbf26cc064904729a21e28", "payment_route": { "total_time_lock": 1, - "total_amt": 10000, + "total_amt": 100000, "hops": [ { "chan_id": 495879744192512, "chan_capacity": 1000000, - "amt_to_forward": 10000 + "amt_to_forward": 100000 } ] } @@ -513,6 +533,7 @@ bob$ lncli-bob listchannels Now that we know how to send single-hop payments, sending multi hop payments is not that much more difficult. Let's set up a channel from Bob<-->Charlie: + ```bash charlie$ lncli-charlie openchannel --node_key= --local_amt=800000 --push_amt=200000 @@ -524,6 +545,7 @@ Note that this time, we supplied the `--push_amt` argument, which specifies the amount of money we want to other party to have at the first channel state. Let's make a payment from Alice to Charlie by routing through Bob: + ```bash charlie$ lncli-charlie addinvoice --value=10000 alice$ lncli-alice sendpayment --pay_req= @@ -562,6 +584,7 @@ alice$ lncli-alice listchannels The Channel point consists of two numbers separated by a colon, which uniquely identifies the channel. The first number is `funding_txid` and the second number is `output_index`. + ```bash # Close the Alice<-->Bob channel from Alice's side. alice$ lncli-alice closechannel --funding_txid= --output_index= @@ -573,7 +596,7 @@ btcctl --simnet --rpcuser=kek --rpcpass=kek generate 1 # channel. Recall that Bob previously had no on-chain Bitcoin: alice$ lncli-bob walletbalance { - "balance": "20001" + "balance": "110001" } ``` diff --git a/tutorial/02-web-client.md b/tutorial/02-web-client.md index 2f249eb..c1c7a45 100644 --- a/tutorial/02-web-client.md +++ b/tutorial/02-web-client.md @@ -21,24 +21,531 @@ npm install # Setup default configuration files "./node_modules/.bin/gulp" bundle +``` -# Start the server to point to our Alice node: -node server --lndhost=localhost:10001 +### Setting up LND and BTCD + +`lnd` should be started with the wallet encryption and macaroons options disabled, but in the previous [Stage 1 Tutorial](/tutorial/01-lncli) we only disabled macaroons. This means that we have to edit the `lnd.conf` we previously configured in Stage 1 tutorial. Considering we're using the local `simnet` blockchain, the suggestion is to start over from the beginning. Be patient, because the setting up procedure is going to be long and a little bit boring. Take it as a way to review most of what you learnt in Stage 1 tutorial. + +You'll need a total of 6 terminal windows: + +1. one terminal to launch `btcd` node; +2. three terminals to launch a `lnd` node for each peer (i.e. Alice, Bob and Charlie); +3. one terminal to submit commands to the `btcd` node and to the three `lnd` nodes via `btcctl` and `lncli`; +5. one terminal to launch the `lncli-web` app (you already used during the above installation). + +First, use a new terminal window to delete any content from Alice, Bob and Charlie directories: + +```bash +# in a new terminal window +# delete alice's directory content +cd $GOPATH/dev/alice +rm -rf test_* + +# delete bob's directory content +cd $GOPATH/dev/bob +rm -rf test_* + +# delete charlie's directory content +cd $GOPATH/dev/charlie +rm -rf test_* +``` + +Then edit the `lnd.conf` file to add the `noencryptwallet` option: + +```bash +[Application Options] +datadir=test_data +logdir=test_log +debuglevel=info +debughtlc=true +no-macaroons=true +noencryptwallet=true + +[Bitcoin] +bitcoin.simnet=1 +bitcoin.active=1 +bitcoin.rpcuser=kek +bitcoin.rpcpass=kek +``` + +> NOTE: Mac OS X: ~/Library/Application Support/Lnd/lnd.conf; POSIX OSes: ~/.lnd/lnd.conf; Windows: $LOCALAPPDATA/Lnd/data + +By taking into account that the current NodeJS gRPC module implementation does not support P-521 kind of certificates, which are the ones auto-generated by lnd, you need to manually regenerate a compatible version of them (i.e. P-256) as follows: + +```bash +# Enter the Lnd home directory, located by default at ~/.lnd on Linux or +# /Users/[username]/Library/Application Support/Lnd on Mac OSX +cd ~/.lnd +openssl ecparam -genkey -name prime256v1 -out tls.key +openssl req -new -sha256 -key tls.key -out csr.csr -subj '/CN=localhost/O=lnd' +openssl req -x509 -sha256 -days 3650 -key tls.key -in csr.csr -out tls.cert +rm csr.csr +``` + +Finally copy the generated certificate file into `lncli-web` directory: + +```bash +cp tls.cert /lnd.cert +``` + +#### Configure btcd.conf and btcctl.conf + +Let's now configure `btcd` and `btcctl` to make things simpler to be run. First delete any generated content during the Stage 1 from the `~/.btcd` directory (or `~/Library/Application Support/Btcd` on Mac OS X): + +```bash +# delete the .btcd directory +rm -rf ~/.btcd +``` + +Recreate the above directory and create a `btcd.conf` inside it: + +```bash +mkdir ~/.btcd +touch ~/.btcd/btcd.conf +``` + +> NOTE: mutatis mutandis, make the same thing in Mac OS X or Windows OSes + +Edit the `btcd.conf` file as follows: + +```bash +[Application Options] +simnet=1 +rpcuser=kek +rpcpass=kek +txindex=1 +``` + +Proceed by configuring `btcctl` + +```bash +mkdir ~/.btcctl +touch ~/.btcctl/btcctl.conf +``` + +> NOTE: mutatis mutandis, make the same thing in Mac OS X or Windows OSes + +Edit `btcctl.conf` as follows: + +```bash +[Application Options] +simnet=1 +rpcuser=kek +rpcpass=kek +``` + +We are done and ready to launch `btcd` and a cluster of `lnd`s on top of it, as we already did in Stage 1 tutorial. + +### Run btcd + +Run `btcd`: + +```bash +cd $HOME # you can run btcd from any directory +btcd +2017-12-28 12:27:42.558 [INF] BTCD: Version 0.12.0-beta +2017-12-28 12:27:42.558 [INF] BTCD: Loading block database from '/home/mimmo/.btcd/data/simnet/blocks_ffldb' +2017-12-28 12:27:42.563 [INF] BTCD: Block database loaded +2017-12-28 12:27:42.566 [INF] INDX: Transaction index is enabled +2017-12-28 12:27:42.566 [INF] INDX: cf index is enabled +2017-12-28 12:27:42.566 [INF] INDX: Catching up indexes from height -1 to 0 +2017-12-28 12:27:42.566 [INF] INDX: Indexes caught up to height 0 +2017-12-28 12:27:42.566 [INF] CHAN: Chain state (height 0, hash 683e86bd5c6d110d91b94b97137ba6bfe02dbbdb8e3dff722a669b5d69d77af6, totaltx 1, work 2) +2017-12-28 12:27:42.566 [INF] RPCS: Generating TLS certificates... +2017-12-28 12:27:42.591 [INF] RPCS: Done generating TLS certificates +2017-12-28 12:27:42.601 [INF] AMGR: Loaded 0 addresses from file '/home/mimmo/.btcd/data/simnet/peers.json' +2017-12-28 12:27:42.601 [INF] RPCS: RPC server listening on 127.0.0.1:18556 +2017-12-28 12:27:42.601 [INF] CMGR: Server listening on [::]:18555 +2017-12-28 12:27:42.601 [INF] CMGR: Server listening on 0.0.0.0:18555 +``` + +### Run Alice, Bob and Charlie lnd + +As we did in Stage 1 tutorial, we can now lunch the cluster of `lnd`s nodes for Alice, Bob and Charlie: + +```bash +# from a new terminal window +cd $HOME # could be any directory +lnd --rpcport=10001 --peerport=10011 --restport=8001 +2017-12-28 12:42:21.305 [INF] LTND: Version 0.3.0-alpha +... +2017-12-28 12:42:23.795 [INF] CMGR: Server listening on [::]:10011 + +# from a new terminal window +cd $GOPATH/dev/bob +lnd --rpcport=10002 --peerport=10012 --restport=8002 +2017-12-28 12:44:30.704 [INF] LTND: Version 0.3.0-alpha +... +2017-12-28 12:44:33.295 [INF] CMGR: Server listening on [::]:10012 + +# from a new terminal window +cd $GOPATH/dev/charlie +lnd --rpcport=10003 --peerport=10013 --restport=8003 +2017-12-28 12:46:14.287 [INF] LTND: Version 0.3.0-alpha +... +2017-12-28 12:46:16.799 [INF] CMGR: Server listening on [::]:10013 +``` + +### Create addresses + +As you should remember from Stage 1 tutorial, before funding the peers we need to create new addresses for them by using the `lncli` command line tool. Let's do it here as well: + +> NOTE: copy down the generated addresses, because you'll need them later when funding peers + +```bash +# from a new terminal window +cd $HOME # could be any directory +lncli-alice newaddress np2wkh +{ + "address": "rX4mANQmUzoTADdQ4htinMJoTQPaexYvGe" +} +# check Alice's balance +lncli-alice walletbalance +{ + "total_balance": "0", + "confirmed_balance": "0", + "unconfirmed_balance": "0" +} + +lncli-bob newaddress np2wkh +{ + "address": "rtpCLSQqEdNPwNoj9zFvXzy5Ej1qqPuv9e" +} +# check Bob's balance +lncli-bob walletbalance +{ + "total_balance": "0", + "confirmed_balance": "0", + "unconfirmed_balance": "0" +} + +lncli-charlie newaddress np2wkh +{ + "address": "rWaEQ1yTGMyfeeVVE9RrLCPoHnuFchzBKr" +} +# check Charlie's balance +lncli-charlie walletbalance +{ + "total_balance": "0", + "confirmed_balance": "0", + "unconfirmed_balance": "0" +} +``` + +### Fund Alice and Charlie + +As we did in Stage 1 tutorial, to fund peers we need to stop the running `btcd` and to rerun it with the `--miningaddr` option set to the address of each peer we want to fund. If you're not quick in re-running the `btcd` node after having stopped it, the running lnd nodes for Alice, Bob and Charlie will timeout. We strongly suggest to stop them all before stopping the `btcd` node. + +```bash +# stop alice's lnd node +lncli-alice stop + +# stop bob's lnd node +lncli-bob stop + +# stop charlie's lnd node +lncli-charlie stop + +# stop btcd node +btcctl stop +``` + +Let's start by funding Alice's address + +```bash +# rerun btcd node from the same terminal where you launched btcd the first time +btcd --miningaddr= +``` + +Go back to the terminal where you stopped `btcd` and generate 400 blocks + +```bash +# from the terminal where you stopped btcd +btcctl generate 400 +[ + "7d62d49522595b7cd05853efb5c7b88ef9b0cd0c33adc147bb2fec7187403e56", + ... + "126dfa3c1e38d7467baebecea0a08a0e2a49f474cf585c2445df4b022d7785af" +] +``` -# Check out the available command line arguments +Repeat the above procedure for Charlie's address. As we did in the Stage 1 tutorial, we're not going to fund Bob's address. + +```bash +btcctl stop + +# rerun btcd node from the same terminal where you launched btcd the first time +btcd --miningaddr= +``` + +Go back to the terminal where you stopped `btcd` and generate 100 blocks to fund Charlie + +```bash +# from the terminal where you stopped btcd +btcctl generate 100 +[ + "52b54c972ae0b97b06cfc21b13c3fcf385d750c14fc32f29f9c80dcda23bb222", + ... + "1176c0c51d3e87e0fb0fb82f460035128144ef86a3c3bbccc539103e7d8a230f" +] +``` + +You can now restart the three LND nodes using the terminal windows you have previously started them from + +```bash +# from alice's terminal window +lnd --rpcport=10001 --peerport=10011 --restport=8001 +# from bob's terminal window +lnd --rpcport=10002 --peerport=10012 --restport=8002 +# from charlie's terminal window +lnd --rpcport=10003 --peerport=10013 --restport=8003 +``` + +If you're curious about the new balance of each peers you can check them out as you did in Stage 1 tutorial: + +```bash +# alice's balance +lncli-alice walletbalance +{ + "total_balance": "2000000000000", + "confirmed_balance": "2000000000000", + "unconfirmed_balance": "0" +} + +# bob's balace (0 BTC) +lncli-bob walletbalance +{ + "total_balance": "0", + "confirmed_balance": "0", + "unconfirmed_balance": "0" +} + +# charlie's balance +lncli-charlie walletbalance +{ + "total_balance": "5000000000", + "confirmed_balance": "5000000000", + "unconfirmed_balance": "0" +} +``` + +### Running the LND web client + +After a lot of set up, we're ready to play with the `lncli-web` app we already installed and set up at the very beginning of this Stage 2 tutorial. You can attach the web app to whichever `lnd` node you want. To be consistent with the workflow described in Stage 1 tutorial, we're going to attach it to the Alice's lnd node. + +```bash +# from the terminal where you installed lncli-web +cd + +# If you're curious, check out the available command line arguments node server --help + +# run the server +node server --lndhost=localhost:10001 +... +info: App listening on localhost port 8280 ``` -Open up [`http://localhost:8280/`](http://localhost:8280/) in your browser to see the web dashboard. +As you see, the server inform you that the web app is listening on port 8280 of the localhost. Open up [`http://localhost:8280/`](http://localhost:8280/) in your browser to see the web dashboard. ### Poking around -Now would be a good time to reopen that channel we had between Alice and Bob. -Except this time, we're going to do it through the web dashboard. Feel free to -try this on your own - the web dashboard is intuitive enough that we don't need -step by step instructions for it. +Now it would be a good time to repeat the Stage 1 workflow, except this time we're going to do it through the web dashboard. In the `Node Info` panel of the `Node and Network Information` section, you should see that block height is 500, the number of blocks we previously generated to fund Alice and Charlie. You should also see that there are no current active o pending channels. The `Network Info` panel inform you there is just one connected node (i.e. Alice ). The total network capacity is 0, because there are no active channels at the moment. In the `Wallet and Channel Balances` section you can see current Alice's balances, i.e. the wallet balance and the channel one. + +#### Connect Alice with Bob + +In the `Peers` section you see there are no connected peers. Let's connect Alice with Bob. As you remember from Stage 1, to connect to a peer you need to know the public-key and the address and the port of the lnd node you want to connect to. Go back to the terminal window to get the public-key: + +```bash +lncli-bob getinfo +{ + "identity_pubkey": , + "alias": "", + "num_pending_channels": 0, + "num_active_channels": 0, + "num_peers": 0, + "block_height": 500, + "block_hash": "1176c0c51d3e87e0fb0fb82f460035128144ef86a3c3bbccc539103e7d8a230f", + "synced_to_chain": false, + "testnet": false, + "chains": [ + "bitcoin" + ] +} +``` + +Now click the `+` icon in the `Connected peers` panel of the dashboard and paste the above public-key and the `localhost:10012` in the corresponding fields. `10012` is the peer port we assigned to Bob when we started his lnd node. As soon as you click the `Connect Peer` button, you'll see the `Connected peers` panel being updated. + +#### Open a channel between Alice and Bob + +We can now open a payment channel from Alice to Bob. Click the `+` icon in the 'Active Channels' panel and select Bob's public-key from the drop-down menu of the `Node Pubkey` field. Type `1000000` in the `Local amount` field and `0` in the `Push amount` field. Then click the `Open Channel` button. You'll receive a notification about not being able to create the channel. Go to the the terminal where you previously run the block generation and generate 6 new blocks. + +```bash +btcctl generate 6 +``` +> NOTE: The last time we run btcd we set Charlie's address as the miningaddr. So, Charlie is going to earn all the mined BTC from now on + +This step is needed to create the funding transaction in the simnet blockchain, as you can verify by yourself by refreshing the `Active channels` panel. Note that the local balance is `991312`, because it has been payed a fee of `8688` Satoshi to the miner of the block recording the payment funding transaction generated by opening the channel. + +#### Sending single hop payments + +As from the Stage 1 tutorial, let Bob create a payment request from the terminal + +```bash +lncli-bob addinvoice --value=100000 +{ + "r_hash": "9761a5336f8d5d4cd6f59a5581bc7f0f0316c114532f4f1970b85f4e1cf8b2f0", + "pay_req": +} +``` + +Copy the payment request code from the terminal, click the `+` icon from the `Payment` panel of the `Payments/Invoices` section of the dashboard and paste it into the `Payment request` field. You should immediately see the details of the payment request. Click the `Send Payment` button. The off-chain payment from Alice to Bob is almost instantaneous as you can verify by refreshing the `Active channels` panel. + +#### Multi-hop payments + +Considering that the running `lncli-web` app is attached to Alice's LND node, to setup a multi-hop off-chain payment we need to use again the terminals. + +##### Connect Charlie to Bob + +First we need to create a connection between Charlie and Bob, as we did in the Stage 1 tutorial. + +```bash +lncli-charlie connect @localhost:10012 +{ + "peer_id": 0 +} + +# check charlie's peers +lncli-charlie listpeers +{ + "peers": [ + { + "pub_key": , + "peer_id": 1, + "address": "127.0.0.1:10012", + "bytes_sent": "149", + "bytes_recv": "149", + "sat_sent": "0", + "sat_recv": "0", + "inbound": true, + "ping_time": "0" + } + ] +} + +# check bob's peers. He now has a connection with both Alice and Charlie +lncli-bob listpeers +{ + "peers": [ + { + "pub_key": , + "peer_id": 1, + "address": "127.0.0.1:47512", + "bytes_sent": "3057", + "bytes_recv": "4802", + "sat_sent": "0", + "sat_recv": "100000", + "inbound": false, + "ping_time": "644" + }, + { + "pub_key": , + "peer_id": 2, + "address": "127.0.0.1:48902", + "bytes_sent": "149", + "bytes_recv": "149", + "sat_sent": "0", + "sat_recv": "0", + "inbound": false, + "ping_time": "0" + } + ] +} +``` + +##### Open a channel from Charlie to Bob + +Now open a payment channel from Charlie to Bob. + +```bash +lncli-charlie openchannel --node_key= --local_amt=800000 --push_amt=200000 +{ + "funding_txid": "f9bb66231aca688698a1429cb2be7326ce0161f6f0ca681e6b669cb0769f32a9" +} +``` + +As usual, this transaction has to be recorded into the blockchain, so let's generate the next 6 required blocks. + +```bash +btcctl generate 6 +[ + "064ba46271cc3e8d2229dd986813796754c4a7b1a319a4394783a413983cda20", + ... + "67e2a02f23c66254435915b6346cd10fbfa3021c3583403274c176ae4e97bf9b" +] +``` + +If you visit the dashboard, you should see the updated information in the `Network info` panel: there are now 3 nodes, 2 channels and the total capacity of the channel network is `1800000` (i.e. the sum of the capacity of the two established channels). + +##### Create the invoice by Charlie + +Let's create an invoice by Charlie in such a way that Alice will be able to pay the generated payment request without being directly connected with Charlie. + +```bash +lncli-charlie addinvoice --value=10000 +{ + "r_hash": "c9d8acce1d5b939b1b97536d1c23e0c8216f49cc2376de7d89a32608bc4bb1c2", + "pay_req": +} +``` + +Copy the payment request identifier. + +#### Alice pays Charlie + +Go back to the dashboard and click the `+` from the `Payment` panel. Paste the copied payment request in the corresponding field. You should immediately see the payment detail, including Charlie's public-key as the destination of the payment. Click the `Send payment` button. You should now see an almost instant update of the `Active channels` and `Payments` panels: + +* the value of the local balance is know `881310` (remote balance is `110001`). +* there is a new payment in the `Payment` panel. + +### Other peers's view + +As said, when we started the `lncli-web` app we attached it to Alice's LND node. But we could also attach it to Bob or Charlie's nodes. + +Close the browser window, stop the running node server (CTRL-C/CMD-C) and rerun it by passing the LND address of Bob's node. + +```bash +node server --lndhost=localhost:10001 +... +info: App listening on localhost port 8280 +^C +# connect the node server to Bob's LND node +node server --lndhost=localhost:10002 +... +info: App listening on localhost port 8280 +``` + +You now see the Bob's view of the network. Do the same with Charlie's view. + +```bash +node server --lndhost=localhost:10002 +... +info: App listening on localhost port 8280 +^C + +# connect the node server to Charlie's LND node +node server --lndhost=localhost:10003 +... +info: App listening on localhost port 8280 +``` + +### Conclusion + +Feel free to try the dashboard on your own - the web dashboard is intuitive enough that we don't need step by step instructions for it. -Note: The LND wallet is coming soon! Sign up for our newsletter at the bottom +When done, stop the node server, all the LND's nodes and finally the `btcd` daemon. +> NOTE: The LND wallet is coming soon! Sign up for our newsletter at the bottom of our [community page](//lightning.community#mc-embedded-subscribe-form) ### Moving on to Step 3