diff --git a/README.md b/README.md index 5c98f5cb0..b07b627f1 100644 --- a/README.md +++ b/README.md @@ -1,279 +1,74 @@ # c-lightning: A specification compliant Lightning Network implementation in C -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. +c-lightning is a lighweight, highly customizable and [standard compliant][std] implementation of the Lightning Network protocol. -[std]: https://github.com/lightningnetwork/lightning-rfc - -For more information about the Lightning Network please refer to -http://lightning.network. ## Project Status [![Build Status][travis-ci]][travis-ci-link] [![Pull Requests Welcome][prs]][prs-link] [![Irc][IRC]][IRC-link] -[![Documentation Status](https://readthedocs.org/projects/lightning/badge/?version=docs)](https://lightning.readthedocs.io/) +[![Documentation Status](https://readthedocs.org/projects/lightning/badge/?version=docs)][docs] -[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 +This implementation has been in production use on the Bitcoin mainnet since early 2018, with the launch of the [Blockstream Store][blockstream-store-blog]. +We recommend getting started by experimenting on `testnet`, but the implementation is considered stable and can be safely used on mainnet. -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 +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]. ## Getting Started -c-lightning currently only works on Linux (and possibly Mac OS with some -tweaking), and requires a locally (or remotely) 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 only works on Linux and Mac OS, and requires a locally (or remotely) running `bitcoind` (version 0.16 or above) that is fully caught up with the network you're testing on. +Pruning (`prune=n` option in `bitcoin.conf`) is partially supported, see [here](#pruning) for more details. ### Installation -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: +There are 4 supported installation options: - sudo apt-get update - sudo apt-get install -y \ - autoconf automake build-essential git libtool libgmp-dev \ - libsqlite3-dev python python3 net-tools zlib1g-dev libsodium-dev \ - python3-mako git - git clone https://github.com/ElementsProject/lightning.git - cd lightning - ./configure - make + - Installation from the [Ubuntu PPA][ppa] + - Installation of a pre-compiled binary from the [release page][releases] on Github + - Using one of the [provided docker images][dockerhub] on the Docker Hub + - Compiling the source code yourself (suggested mainly for developers or if you need one of the still [unreleased features][changelog-unreleased]) -Or if you like to throw `docker` into the mix, you can use the official docker image either directly or as a base layer for more complex images. -The docker image is [elementsproject/lightningd](https://hub.docker.com/r/elementsproject/lightningd/) (from this [Dockerfile](Dockerfile)). -Image tags with `-dev` at the end are images built with `DEVELOPER=1`. -If you build the image yourself, you can use the build arg `DEVELOPER=1` to build c-lightning in developer mode. +Please refer to the [PPA release page][ppa] and the [installation documentation](doc/INSTALL.md) for detailed instructions. -It has the following environment variable: +For the impatient here's the gist of it for Ubuntu: -* `EXPOSE_TCP` default to false, if true, use expose c-lightning RPC on port 9835. (Use this only for testing) - -Here is an example of a docker-compose file with bitcoind and c-lightning on `testnet` which expose bitcoind's RPC interface on default ports `18332` and c-lightning API on port `9735`: - -``` -version: "3" -services: - bitcoind: - image: nicolasdorier/docker-bitcoin:0.16.3 - container_name: bitcoind - environment: - BITCOIN_EXTRA_ARGS: | - testnet=1 - whitelist=0.0.0.0/0 - server=1 - rpcuser=rpcuser - rpcpassword=rpcpass - expose: - - "18332" - ports: - - "0.0.0.0:18333:18333" - volumes: - - "bitcoin_datadir:/data" - - clightning_bitcoin: - image: elementsproject/lightningd - container_name: lightningd - command: - - --bitcoin-rpcconnect=bitcoind - - --bitcoin-rpcuser=rpcuser - - --bitcoin-rpcpassword=rpcpass - - --network=testnet - - --alias=myawesomenode - - --log-level=debug - environment: - EXPOSE_TCP: "true" - expose: - - "9735" - ports: - - "0.0.0.0:9735:9735" - volumes: - - "clightning_bitcoin_datadir:/root/.lightning" - - "bitcoin_datadir:/etc/bitcoin" - links: - - bitcoind - -volumes: - bitcoin_datadir: - clightning_bitcoin_datadir: +```bash +sudo apt-get install -y software-properties-common +sudo add-apt-repository -u ppa:bitcoin/bitcoin +sudo add-apt-repository -u ppa:lightningnetwork/ppa +sudo apt-get install bitcoind lightningd ``` ### 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 this case we start `testnet`): - bitcoind -daemon -testnet +```bash +bitcoind -daemon -testnet +``` Wait until `bitcoind` has synchronized with the testnet network. -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 -`lightningd` being unable to synchronize with the blockchain. +Make sure that you do not have `walletbroadcast=0` in your `~/.bitcoin/bitcoin.conf`, or you may run into trouble. +Notice that running `lightningd` against a pruned node may cause some issues if not managed carefully, see [below](#pruning) for more information. You can start `lightningd` with the following command: - 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 - -### 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
- cli/lightning-cli newaddr - - # Returns a transaction id - bitcoin-cli -testnet sendtoaddress
- -`lightningd` will register the funds once the transaction is confirmed. - -You can obtain testcoins from a faucet such as [coinfaucet.eu][cfeu]. -You can send them directly to the `lightningd` address. - -You may need to generate a p2sh-segwit address if the faucet does not support -bech32: - - # Return a p2sh-segwit address - cli/lightning-cli newaddr p2sh-segwit - -[cfeu]: https://coinfaucet.eu/en/btc-testnet - -Confirm `lightningd` got funds by: - - # Returns an array of on-chain funds. - 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 ``: - -``` -cli/lightning-cli connect [] -cli/lightning-cli fundchannel +```bash +lightningd --network=testnet --log-level=debug ``` -This opens a connection and, on top of that connection, then opens -a channel. -The funding transaction needs 1 confirmation 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`. +Please refer to `lightningd --help` for all other command line options. -### Different states -* `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. -* `CLOSINGD_COMPLETE` means we've broadcast our mutual close - 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. -* `AWAITING_UNILATERAL` means that we're waiting for a unilateral close to hit the blockchain. +### JSON-RPC Interface -All these states have more information about what's going on in the -`status` field in `listpeers`. +c-lightning exposes a [JSON-RPC 2.0][jsonrpcspec] interface over a Unix Domain socket located in its home directory (default: `$HOME/.lightning`). +The Unix Domain Socket has the advantage of not being exposed over the network by default, allowing users to add their own authentication and authorization mechanism, while still providing a fully functional RPC interface out of the box. -### 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 `