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

@@ -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:

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
+c-lightning is a [standard compliant](https://github.com/lightningnetwork/lightning-rfc) implementation of the Lightning Network protocol.
-bitcoin lightning (see:
+The Lightning Network is a scalability solution for Bitcoin, enabling secure and instant transfer of funds between any two party for any amount. 
-[http://lightning.network](http://lightning.network) which proposed
-the original "lightning network").
 
-This implementation is being developed in parallel with the protocol
+For more information about the Lightning Network please refer to http://lightning.network.
-definition, which you can find [on my fork of the protocol description repository](https://github.com/rustyrussell/lightning).
+
+## 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 <address>
+daemon/lightgning-cli newaddr 
+
+# Returns a transaction id <txid>
+bitcoin-cli -testnet sendtoaddress <address> <amount>
+
+# Retrieves the raw transaction <rawtx>
+bitcoin-cli -testnet getrawtransaction <txid>
+
+# Notifies `lightningd` that there are now funds available:
+daemon/lightning-cli addfunds <rawtx>
+```
+
+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 `<ip>:<port>` and has the node ID `<node_id>`:
+
+```
+daemon/lightning-cli connect <ip> <port> <node_id>
+daemon/lightning-cli fundchannel <node_id> <amount>
+```
+
+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 `<amount>` in millisatoshi and a `<label>`:
+
+```
+daemon/lightning-cli invoice <amount> <label>
+```
+
+This returns a random value called `rhash` that is part of the invoice.
+The recipient needs to communicate its ID `<recipient_id>`, `<rhash>` and the desired `<amount>` to the sender.
+
+The sender needs to compute a route to the recipient, and use that route to actually send the payment:
+
+```
+route=$(daemon/lightning-cli getroute <recipient_id> <amount> 1 | jq --raw-output .route -)
+daemon/lightning-cli sendpay $route <amount>
+```
+
+Notice that in the first step we stored the route in a variable and reused it in the second step.
+`lightning-cli` should return a preimage that serves as a receipt, confirming that the payment was successful.
+
+This low-level interface is still experimental and will eventually be complemented with a higher level interface that is easier to use.
+
+## Further information
 
-If you're interested in using the daemon to test payments, the
 JSON-RPC interface is documented in the following manual pages:
+
 * [invoice](doc/lightning-invoice.7.txt)
 * [listinvoice](doc/lightning-listinvoice.7.txt)
 * [waitinvoice](doc/lightning-waitinvoice.7.txt)
@@ -17,32 +120,4 @@ JSON-RPC interface is documented in the following manual pages:
 * [getroute](doc/lightning-getroute.7.txt)
 * [sendpay](doc/lightning-sendpay.7.txt)
 
-Steps:
+For simple access to the JSON-RPC interface you can use the `daemon/lightning-cli` tool, or the [python API client](contrib/pylightning).
-
-0.  If you're running a previous version, you'll need to shut it down
-    (maybe close channels first) and delete the $HOME/.lightning directory.
-1.  [Install and compile](INSTALL.md) the requirements.
-2.  Make sure bitcoind is running in testnet mode, and has the latest
-    blocks.
-3.  Get some test bitcoins, such as from [TPs' testnet faucet](http://tpfaucet.appspot.com/) or [Kiwi's testnet faucet](https://testnet.manu.backend.hamburg/faucet).
-3.  If you want others to connect to your lightningd, create $HOME/.lightning/config and put `port=8334` in it (or any other port).
-4.  Run `daemon/lightningd`.
-6.  Run `daemon/lightning-cli getinfo` to check it's working.
-7.  Find a node using `daemon/lightning-cli getnodes` (this will populate
-    over time).
-8.  Create a new connection to the node using `contrib/lightning-open-channel
-    ADDRESS PORT AMOUNT` where AMOUNT is in BTC (.04294967 is the maximum
-    possible).  If successful, this will return only once a block has been
-    mined with the funding transaction in it.
-9.  You can create more channels if you wish.
-10.  You can accept payment using `daemon/lightning-cli invoice
-    MILLISATOSHI LABEL`; it will give you a payment hash to give to the
-    payer.
-11. You can send payments using `contrib/lightning-pay DEST-ID MILLISATOSHI PAYMENT-HASH`.
-
-Final note: This is very much a testbed and work in progress; expect
-All The Things to change, all the time.
-
-Welcome aboard!
-
-Rusty.