From 744d657860bc818a288eae099fd640097d07d70d Mon Sep 17 00:00:00 2001 From: Christian Decker Date: Tue, 9 May 2017 15:33:42 +0200 Subject: [PATCH] doc: Updating README and related documentation Like many I don't read any documentation besides the readme in the repo, so I thought I could just pull some simple getting started info into the readme to make it easy for people to get started :-) --- INSTALL.md | 2 +- README.md | 149 ++++++++++++++++++++++++++++++++++++++++------------- 2 files changed, 113 insertions(+), 38 deletions(-) diff --git a/INSTALL.md b/INSTALL.md index 95f1bc098..6931ac067 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -20,7 +20,7 @@ To Build on Ubuntu 16.04 Get dependencies: ``` -sudo apt-get install -y autoconf libtool libprotobuf-c-dev libgmp-dev libsqlite3-dev +sudo apt-get install -y autoconf build-essential git libtool libprotobuf-c-dev libgmp-dev libsqlite3-dev python3 ``` For development or running tests, get additional dependencies: diff --git a/README.md b/README.md index 0b340b39b..fb61b0986 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,118 @@ -# Lightning Protocol Reference Implementation +# c-lightning: A specification compliant Lightning Network implementation in C -In this repository we're developing a reference implementation of -bitcoin lightning (see: -[http://lightning.network](http://lightning.network) which proposed -the original "lightning network"). +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 party for any amount. -This implementation is being developed in parallel with the protocol -definition, which you can find [on my fork of the protocol description repository](https://github.com/rustyrussell/lightning). +For more information about the Lightning Network please refer to http://lightning.network. + +## Project Status + +This implementation is still very much work in progress, and, although it can be used for testing, __it should not be used for real funds__. +We do our best to identify and fix problems, and implement missing feature. + +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) or on the mailing list [lightning-dev@lists.linuxfoundation.org](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` that is fully caught up with the network you're testing on. + +### Installation + +Please refer to the [installation documentation](INSTALL.md) for detailed instructions. +For the impatient here's the gist of it for Ubuntu and Debian: + +``` +sudo apt-get install -y autoconf git build-essential libtool libprotobuf-c-dev libgmp-dev libsqlite3-dev python python3 +git clone https://github.com/ElementsProject/lightning.git +cd lightning +make +``` + +Or if you like to throw `docker` into the mix: + +``` +sudo docker run \ + -v $HOME/.lightning:/root/.lightning \ + -v $HOME/.bitcoin:/root/.bitcoin \ + -p 9735:9735 \ + /cdecker/lightningd:master +``` +### Starting `lightningd` + +In order to start `lightningd` you will need to have a local `bitcoind` node running in either testnet or regtest mode: + +``` +bitcoind -daemon -testnet +``` + +Once `bitcoind` has synchronized with the testnet/regtest network, you can start `lightningd` with the following command: + +``` +lightningd/lightningd --log-level=debug +``` + +### Opening a channel on the Bitcoin testnet + +First you need to transfer some funds to `lightningd` so that it can open a channel: + +``` +# Returns an address
+daemon/lightgning-cli newaddr + +# Returns a transaction id +bitcoin-cli -testnet sendtoaddress
+ +# Retrieves the raw transaction +bitcoin-cli -testnet getrawtransaction + +# Notifies `lightningd` that there are now funds available: +daemon/lightning-cli addfunds +``` + +Eventually `lightningd` will include its own wallet making this transfer easier, but for now this is how it gets its funds. +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). + +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 has the node ID ``: + +``` +daemon/lightning-cli connect +daemon/lightning-cli fundchannel +``` + +This opens a connection and, on top of that connection, then opens a channel. +You can check the status of the channel using `daemon/lightning-cli getpeers`. +The funding transaction needs to confirm in order for the channel to be usable, so wait a few minutes, and once that is complete it `getpeers` should say that the status is in _Normal operation_. + +### Receiving and receiving payments + +Payments in Lightning are invoice based. +The recipient creates an invoice with the expected `` in millisatoshi and a `