diff --git a/README.md b/README.md index 6dfa2b6d4..028b43602 100644 --- a/README.md +++ b/README.md @@ -1,31 +1,58 @@ # c-lightning: A specification compliant Lightning Network implementation in C -c-lightning is a [standard compliant](https://github.com/lightningnetwork/lightning-rfc) implementation of the Lightning Network protocol. -The Lightning Network is a scalability solution for Bitcoin, enabling secure and instant transfer of funds between any two parties for any amount. +c-lightning is a [standard compliant][std] implementation of the Lightning +Network protocol. +The Lightning Network is a scalability solution for Bitcoin, enabling +secure and instant transfer of funds between any two parties for any +amount. -For more information about the Lightning Network please refer to http://lightning.network. +[std]: https://github.com/lightningnetwork/lightning-rfc + +For more information about the Lightning Network please refer to +http://lightning.network. ## Project Status -[![Build Status](https://travis-ci.org/ElementsProject/lightning.svg?branch=master)](https://travis-ci.org/ElementsProject/lightning) -[![Pull Requests Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat)](http://makeapullrequest.com) -[![Irc](https://img.shields.io/badge/chat-on%20freenode-brightgreen.svg)](https://webchat.freenode.net/?channels=c-lightning) +[![Build Status][travis-ci]][travis-ci-link] +[![Pull Requests Welcome][prs]][prs-link] +[![Irc][IRC]][IRC-link] -This implementation is still very much a work in progress. It can be used for testing, but __it should not be used for real funds__. -We do our best to identify and fix problems, and implement missing features. +[travis-ci]: https://travis-ci.org/ElementsProject/lightning.svg?branch=master +[travis-ci-link]: https://travis-ci.org/ElementsProject/lightning +[prs]: https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat +[prs-link]: http://makeapullrequest.com +[IRC]: https://img.shields.io/badge/chat-on%20freenode-brightgreen.svg +[IRC-link]: https://webchat.freenode.net/?channels=c-lightning -Any help testing the implementation, reporting bugs, or helping with outstanding issues is very welcome. -Don't hesitate to reach out to us on IRC at [#lightning-dev @ freenode.net](http://webchat.freenode.net/?channels=%23lightning-dev), [#c-lightning @ freenode.net](http://webchat.freenode.net/?channels=%23c-lightning), -or on the implementation-specific mailing list [c-lightning@lists.ozlabs.org](https://lists.ozlabs.org/listinfo/c-lightning), -or on the Lightning Network-wide mailing list [lightning-dev@lists.linuxfoundation.org](https://lists.linuxfoundation.org/mailman/listinfo/lightning-dev). +This implementation is still very much a work in progress. +It can be used for testing, but __it should not be used for real funds__. +We do our best to identify and fix problems, and implement missing +features. + +Any help testing the implementation, reporting bugs, or helping with +outstanding issues is very welcome. +Don't hesitate to reach out to us on IRC at +[#lightning-dev @ freenode.net][irc1], [#c-lightning @ +freenode.net][irc2], or on the implementation-specific mailing list +[c-lightning@lists.ozlabs.org][ml1], or on the Lightning Network-wide +mailing list [lightning-dev@lists.linuxfoundation.org][ml2]. + +[irc1]: http://webchat.freenode.net/?channels=%23lightning-dev +[irc2]: http://webchat.freenode.net/?channels=%23c-lightning +[ml1]: https://lists.ozlabs.org/listinfo/c-lightning +[ml2]: https://lists.linuxfoundation.org/mailman/listinfo/lightning-dev ## Getting Started -c-lightning currently only works on Linux (and possibly Mac OS with some tweaking), and requires a locally running `bitcoind` (version 0.15 or above) that is fully caught up with the network you're testing on. Pruning (prune=n option in bitcoin.conf) is not currently supported. +c-lightning currently only works on Linux (and possibly Mac OS with some +tweaking), and requires a locally running `bitcoind` (version 0.15 or +above) that is fully caught up with the network you're testing on. +Pruning (prune=n option in bitcoin.conf) is not currently supported. ### Installation -Please refer to the [installation documentation](doc/INSTALL.md) for detailed instructions. +Please refer to the [installation documentation](doc/INSTALL.md) for +detailed instructions. For the impatient here's the gist of it for Ubuntu and Debian: ``` @@ -45,19 +72,23 @@ sudo docker run \ -p 9735:9735 \ cdecker/lightningd:latest ``` + ### Starting `lightningd` -In order to start `lightningd` you will need to have a local `bitcoind` node running in either testnet or regtest mode: +In order to start `lightningd` you will need to have a local `bitcoind` +node running in either testnet or regtest mode: ``` bitcoind -daemon -testnet ``` -Wait until `bitcoind` has synchronized with the testnet network. In case you use regtest, make sure you generate at least 432 blocks to activate SegWit. +Wait until `bitcoind` has synchronized with the testnet network. +In case you use regtest, make sure you generate at least 432 blocks to +activate SegWit. Make sure that you do not have `walletbroadcast=0` in your -`~/.bitcoin/bitcoin.conf`, or you may run into trouble. Notice that -currently pruned nodes are not supported and may result in +`~/.bitcoin/bitcoin.conf`, or you may run into trouble. +Notice that currently pruned nodes are not supported and may result in `lightningd` being unable to synchronize with the blockchain. You can start `lightningd` with the following command: @@ -67,11 +98,13 @@ lightningd/lightningd --network=testnet --log-level=debug ``` ### Listing all commands: -`cli/lightning-cli help` will print a table of the API and lists the following commands +`cli/lightning-cli help` will print a table of the API and lists the +following commands ### Opening a channel on the Bitcoin testnet -First you need to transfer some funds to `lightningd` so that it can open a channel: +First you need to transfer some funds to `lightningd` so that it can +open a channel: ``` # Returns an address
@@ -81,14 +114,15 @@ cli/lightning-cli newaddr bitcoin-cli -testnet sendtoaddress
``` -`lightningd` will register the funds once the transaction is -confirmed. +`lightningd` will register the funds once the transaction is confirmed. -If you don't have any testcoins you can get a few from a faucet -such as [TPs' testnet faucet](http://tpfaucet.appspot.com/) or -[Kiwi's testnet faucet](https://testnet.manu.backend.hamburg/faucet). +If you don't have any testcoins you can get a few from a faucet such as +[TPs' testnet faucet][tps] or [Kiwi's testnet faucet][kiw]. You can send it directly to the `lightningd` address. +[tps]: http://tpfaucet.appspot.com/ +[kiw]: https://testnet.manu.backend.hamburg/faucet + Confirm `lightningd` got funds by: ``` @@ -96,36 +130,44 @@ Confirm `lightningd` got funds by: cli/lightning-cli listfunds ``` -Once `lightningd` has funds, we can connect to a node and open a -channel. -Let's assume the **remote** node is accepting connections at -`` (and optional ``, if not 9735) and has the node ID -``: +Once `lightningd` has funds, we can connect to a node and open a channel. +Let's assume the **remote** node is accepting connections at `` +(and optional ``, if not 9735) and has the node ID ``: ``` cli/lightning-cli connect [] cli/lightning-cli fundchannel ``` -This opens a connection and, on top of that connection, then opens a channel. -The funding transaction needs 1 confirmations in order for the channel to be usable, and 6 to be broadcast for others to use. -You can check the status of the channel using `cli/lightning-cli listpeers`, which after 3 confirmations (1 on testnet) should say that `state` is `CHANNELD_NORMAL`; after 6 confirmations you can use `cli/lightning-cli listchannels` to verify that the `public` field is now `true`. - -### Different states +This opens a connection and, on top of that connection, then opens +a channel. +The funding transaction needs 1 confirmations in order for the channel +to be usable, and 6 to be broadcast for others to use. +You can check the status of the channel using `cli/lightning-cli +listpeers`, which after 3 confirmations (1 on testnet) should say +that `state` is `CHANNELD_NORMAL`; after 6 confirmations you can use +`cli/lightning-cli listchannels` to verify that the `public` field is now +`true`. +### Different states * `GOSSIPING` means that you are connected to a peer but there is no payment channel yet. -* `OPENINGD` means that `lightning_openingd` is negotiating channel opening. -* `CHANNELD_AWAITING_LOCKIN` means that `lightning_channeld` is waiting until - the minimum number of confirmation on the channel funding transaction. +* `OPENINGD` means that `lightning_openingd` is negotiating channel + opening. +* `CHANNELD_AWAITING_LOCKIN` means that `lightning_channeld` is waiting + until the minimum number of confirmation on the channel funding + transaction. * `CHANNELD_NORMAL` means your channel is operating normally. -* `CHANNELD_SHUTTING_DOWN` means one or both sides have asked to shut down the - channel, and we're waiting for existing HTLCs to clear. -* `CLOSINGD_SIGEXCHANGE` means we're trying to negotiate the fee for the mutual close transaction. +* `CHANNELD_SHUTTING_DOWN` means one or both sides have asked to shut + down the channel, and we're waiting for existing HTLCs to clear. +* `CLOSINGD_SIGEXCHANGE` means we're trying to negotiate the fee for + the mutual close transaction. * `CLOSINGD_COMPLETE` means we've broadcast our mutual close - transaction (which spends the funding transaction) , but haven't seen it in a block yet. + transaction (which spends the funding transaction) , but haven't seen + it in a block yet. * `FUNDING_SPEND_SEEN` means we've seen the funding transaction spent. -* `ONCHAIN` means that the `lightning_onchaind` is tracking the onchain closing of the channel. +* `ONCHAIN` means that the `lightning_onchaind` is tracking the onchain + closing of the channel. All these states have more information about what's going on in the `status` field in `listpeers`. @@ -133,28 +175,42 @@ All these states have more information about what's going on in the ### Sending and receiving payments Payments in Lightning are invoice based. -The recipient creates an invoice with the expected `` in millisatoshi (or `"any"` for a donation), a unique `