ElementsProject / lightning

Core Lightning (CLN): A specification compliant Lightning Network implementation in C Core Lightning (previously c-lightning) is a lightweight, highly customizable and [standard compliant][std] implementation of the Lightning Network protocol. • Getting Started • Installation • Starting lightningd • Using the JSON-RPC Interface • Care And Feeding Of Your New Lightning Node • Opening A Channel • Sending and Receiving Payments • Configuration File • Further Information • FAQ • Pruning • HD wallet encryption • Developers • Documentation Project Status [![Continuous Integration][actions-badge]][actions] [![Pull Requests Welcome][prs-badge]][prs] [![Documentation Status][docs-badge]][docs] [![Telegram][telegram-badge]][telegram] [![Discord][discord-badge]][discord] [![Irc][IRC-badge]][IRC] 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 ( or ), but the implementation is considered stable and can be safely used on mainnet. Reach Out to Us Any help testing the implementation, reporting bugs, or helping with outstanding issues is very welcome. Don't hesitate to reach out to us on the implementation-specific [mailing list][ml1], or on [CLN Discord][discord], or on [CLN Telegram][telegram], or on IRC at [dev][irc1]/[gen][irc2] channel. Getting Started Core Lightning only works on Linux and macOS, and requires a locally (or remotely) running (version 25.0 or above) that is fully caught up with the network you're running on, and relays transactions (ie with ). Pruning ( option in ) is partially supported, see here for more details. Installation There are 3 supported installation options: • 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 as described in the installation documentation. Starting Regtest (local, fast-start) Option If you want to experiment with , there's a script to set up a regtest test network of two local lightning nodes, which provides a convenient helper. See the notes at the top of the file for details on how to use it. Mainnet Option To test with real bitcoin, you will need to have a local node running: Wait until has synchronized with the network. Make sure that you do not have in your , or you may run into trouble. Notice that running against a pruned node may cause some issues if not managed carefully, see below for more information. You can start with the following command: This creates a subdirectory in your home directory: see (or https://docs.corelightning.org/docs) for more runtime options. Using The JSON-RPC Interface Core Lightning exposes a [JSON-RPC 2.0][jsonrpcspec] interface over a Unix Domain socket; the tool can be used to access it, or there is a python client library. You can use to print a table of RPC methods; will offer specific information on that command. Useful commands: • newaddr: get a bitcoin address to deposit funds into your lightning node. • listfunds: see where your funds are. • connect: connect to another lightning node. • fundchannel: create a channel to another connected node. • invoice: create an invoice to get paid by another node. • pay: pay someone else's invoice. • plugin: commands to control extensions. Care And Feeding Of Your New Lightning Node Once you've started for the first time, there's a script called which will connect you to other nodes on the lightning network. There are also numerous plugins available for Core Lightning which add capabilities: in particular there's a collection at: https://github.com/lightningd/plugins For a less reckless experience, you can encrypt the HD wallet seed: see HD wallet encryption. You can also chat to other users at Discord [core-lightning][discord]; we are always happy to help you get started! Opening A Channel First you need to transfer some funds to so that it can open a channel: will register the funds once the transaction is confirmed. Alternatively you can generate a taproot address should your source of funds support it: Confirm got funds by: Once 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 : This opens a connection and, on top of that connection, then opens a channel. The funding transaction needs 3 confirmation in order for the channel to be usable, and 6 to be announced for others to use. You can check the status of the channel using , which after 3 confirmations (1 on testnet) should say that is ; after 6 confirmations you can use to verify that the field is now . Sending and Receiving Payments Payments in Lightning are invoice based. The recipient creates an invoice with the expected in millisatoshi (or for a donation), a unique and a the payer will see: This returns some internal details, and a standard invoice string called (named after the [BOLT #11 lightning spec][BOLT11]). [BOLT11]: https://github.com/lightning/bolts/blob/master/11-payment-encoding.md The sender can feed this string to the command to see what it is, and pay it simply using the command: Note that there are lower-level interfaces (and more options to these interfaces) for more sophisticated use. Configuration File can be configured either by passing options via the command line, or via a configuration file. Command line options will always override the values in the configuration file. To use a configuration file, create a file named within your top-level lightning directory or network subdirectory (eg. or ). See . A sample configuration file is available at . Further information Pruning Core Lightning requires JSON-RPC access to a fully synchronized in order to synchronize with the Bitcoin network. Access to ZeroMQ is not required and does not need…