mirrors/core-lightning
1
0
Fork 0
mirror of https://github.com/ElementsProject/lightning.git synced 2025-01-17 19:03:42 +01:00
Code Issues Projects Releases Wiki Activity

doc: Updating README and related documentation

Browse Source 
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 :-)
This commit is contained in:
Christian Decker 2017-05-09 15:33:42 +02:00 committed by Rusty Russell
parent 05e951d748
commit 744d657860
2 changed files with 113 additions and 38 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
INSTALL.md
View File

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

149
README.md
View File

@ -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 <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:
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.
For simple access to the JSON-RPC interface you can use the `daemon/lightning-cli` tool, or the [python API client](contrib/pylightning).