{"id":14980005,"url":"https://github.com/elementsproject/lightning","last_synced_at":"2026-01-17T01:17:07.045Z","repository":{"id":33697405,"uuid":"37350472","full_name":"ElementsProject/lightning","owner":"ElementsProject","description":"Core Lightning — Lightning Network implementation focusing on spec compliance and performance","archived":false,"fork":false,"pushed_at":"2025-05-05T19:44:46.000Z","size":119070,"stargazers_count":2951,"open_issues_count":699,"forks_count":942,"subscribers_count":164,"default_branch":"master","last_synced_at":"2025-05-06T01:57:57.685Z","etag":null,"topics":["bitcoin","lightning","lightning-network","p2p"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ElementsProject.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2015-06-13T00:04:22.000Z","updated_at":"2025-05-05T19:44:52.000Z","dependencies_parsed_at":"2025-04-22T13:14:19.460Z","dependency_job_id":"b7bf4f2a-1193-4fc7-b072-bd2a39741562","html_url":"https://github.com/ElementsProject/lightning","commit_stats":{"total_commits":15224,"total_committers":307,"mean_commits":49.58957654723127,"dds":0.4836442459274829,"last_synced_commit":"02176f7004af098581cddf13da86976685c3f31a"},"previous_names":[],"tags_count":204,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ElementsProject%2Flightning","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ElementsProject%2Flightning/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ElementsProject%2Flightning/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ElementsProject%2Flightning/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ElementsProject","download_url":"https://codeload.github.com/ElementsProject/lightning/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252606930,"owners_count":21775413,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bitcoin","lightning","lightning-network","p2p"],"created_at":"2024-09-24T14:01:07.373Z","updated_at":"2026-01-17T01:17:07.001Z","avatar_url":"https://github.com/ElementsProject.png","language":"C","readme":"# Core Lightning (CLN): A specification compliant Lightning Network implementation in C\n\nCore Lightning (previously c-lightning) is a lightweight, highly customizable and [standard compliant][std] implementation of the Lightning Network protocol.\n\n* [Getting Started](#getting-started)\n    * [Installation](#installation)\n    * [Starting lightningd](#starting-lightningd)\n    * [Using the JSON-RPC Interface](#using-the-json-rpc-interface)\n    * [Care And Feeding Of Your New Lightning Node](#care-and-feeding-of-your-new-lightning-node)\n    * [Opening A Channel](#opening-a-channel)\n\t* [Sending and Receiving Payments](#sending-and-receiving-payments)\n\t* [Configuration File](#configuration-file)\n* [Further Information](#further-information)\n    * [FAQ](doc/FAQ.md)\n    * [Pruning](#pruning)\n    * [HD wallet encryption](#hd-wallet-encryption)\n\t* [Developers](#developers)\n* [Documentation](https://docs.corelightning.org/docs)\n\n## Project Status\n\n[![Continuous Integration][actions-badge]][actions]\n[![Pull Requests Welcome][prs-badge]][prs]\n[![Documentation Status][docs-badge]][docs]\n[![BoL2][bol2-badge]][bol2]\n[![Telegram][telegram-badge]][telegram]\n[![Discord][discord-badge]][discord]\n[![Irc][IRC-badge]][IRC]\n\nThis implementation has been in production use on the Bitcoin mainnet since early 2018, with the launch of the [Blockstream Store][blockstream-store-blog].\nWe recommend getting started by experimenting on `testnet` (`testnet4` or `regtest`), but the implementation is considered stable and can be safely used on mainnet.\n\n## Reach Out to Us\n\nAny help testing the implementation, reporting bugs, or helping with outstanding issues is very welcome.\nDon't hesitate to reach out to us on [Build-on-L2][bol2], or 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.\n\n## Getting Started\n\nCore Lightning only works on Linux and macOS, and requires a locally (or remotely) running `bitcoind` (version 25.0 or above) that is fully caught up with the network you're running on, and relays transactions (ie with `blocksonly=0`).\nPruning (`prune=n` option in `bitcoin.conf`) is partially supported, see [here](#pruning) for more details.\n\n### Installation\n\nThere are 3 supported installation options:\n\n - Installation of a pre-compiled binary from the [release page][releases] on GitHub.\n - Using one of the [provided docker images][dockerhub] on the Docker Hub.\n - Compiling the source code yourself as described in the [installation documentation](doc/getting-started/getting-started/installation.md).\n\n### Starting `lightningd`\n\n#### Regtest (local, fast-start) Option\nIf you want to experiment with `lightningd`, there's a script to set\nup a `bitcoind` regtest test network of two local lightning nodes,\nwhich provides a convenient `start_ln` helper. See the notes at the top\nof the `startup_regtest.sh` file for details on how to use it.\n\n```bash\n. contrib/startup_regtest.sh\n```\n\n#### Mainnet Option\nTo test with real bitcoin,  you will need to have a local `bitcoind` node running:\n\n```bash\nbitcoind -daemon\n```\n\nWait until `bitcoind` has synchronized with the network.\n\nMake sure that you do not have `walletbroadcast=0` in your `~/.bitcoin/bitcoin.conf`, or you may run into trouble.\nNotice that running `lightningd` against a pruned node may cause some issues if not managed carefully, see [below](#pruning) for more information.\n\nYou can start `lightningd` with the following command:\n\n```bash\nlightningd --network=bitcoin --log-level=debug\n```\n\nThis creates a `.lightning/` subdirectory in your home directory: see `man -l doc/lightningd.8` (or https://docs.corelightning.org/docs) for more runtime options.\n\n### Using The JSON-RPC Interface\n\nCore Lightning exposes a [JSON-RPC 2.0][jsonrpcspec] interface over a Unix Domain socket; the `lightning-cli` tool can be used to access it, or there is a [python client library](contrib/pyln-client).\n\nYou can use `lightning-cli help` to print a table of RPC methods; `lightning-cli help \u003ccommand\u003e`\nwill offer specific information on that command.\n\nUseful commands:\n\n* [newaddr](doc/lightning-newaddr.7.md): get a bitcoin address to deposit funds into your lightning node.\n* [listfunds](doc/lightning-listfunds.7.md): see where your funds are.\n* [connect](doc/lightning-connect.7.md): connect to another lightning node.\n* [fundchannel](doc/lightning-fundchannel.7.md): create a channel to another connected node.\n* [invoice](doc/lightning-invoice.7.md): create an invoice to get paid by another node.\n* [pay](doc/lightning-pay.7.md): pay someone else's invoice.\n* [plugin](doc/lightning-plugin.7.md): commands to control extensions.\n\n### Care And Feeding Of Your New Lightning Node\n\nOnce you've started for the first time, there's a script called\n`contrib/bootstrap-node.sh` which will connect you to other nodes on\nthe lightning network.\n\nThere are also numerous plugins available for Core Lightning which add\ncapabilities: in particular there's a collection at: https://github.com/lightningd/plugins\n\nIncluding [helpme][helpme-github] which guides you through setting up\nyour first channels and customizing your node.\n\nFor a less reckless experience, you can encrypt the HD wallet seed:\n see [HD wallet encryption](#hd-wallet-encryption).\n\nYou can also chat to other users at Discord [core-lightning][discord];\nwe are always happy to help you get started!\n\n\n### Opening A Channel\n\nFirst you need to transfer some funds to `lightningd` so that it can\nopen a channel:\n\n```bash\n# Returns an address \u003caddress\u003e\nlightning-cli newaddr\n```\n\n`lightningd` will register the funds once the transaction is confirmed.\n\nAlternatively you can generate a taproot address should your source of funds support it:\n\n```bash\n# Return a taproot address\nlightning-cli newaddr p2tr\n```\n\nConfirm `lightningd` got funds by:\n\n```bash\n# Returns an array of on-chain funds.\nlightning-cli listfunds\n```\n\nOnce `lightningd` has funds, we can connect to a node and open a channel.\nLet's assume the **remote** node is accepting connections at `\u003cip\u003e`\n(and optional `\u003cport\u003e`, if not 9735) and has the node ID `\u003cnode_id\u003e`:\n\n```bash\nlightning-cli connect \u003cnode_id\u003e \u003cip\u003e [\u003cport\u003e]\nlightning-cli fundchannel \u003cnode_id\u003e \u003camount_in_satoshis\u003e\n```\n\nThis opens a connection and, on top of that connection, then opens a channel.\nThe funding transaction needs 3 confirmation in order for the channel to be usable, and 6 to be announced for others to use.\nYou can check the status of the channel using `lightning-cli listpeers`, which after 3 confirmations (1 on testnet) should say that `state` is `CHANNELD_NORMAL`; after 6 confirmations you can use `lightning-cli listchannels` to verify that the `public` field is now `true`.\n\n### Sending and Receiving Payments\n\nPayments in Lightning are invoice based.\nThe recipient creates an invoice with the expected `\u003camount\u003e` in\nmillisatoshi (or `\"any\"` for a donation), a unique `\u003clabel\u003e` and a\n`\u003cdescription\u003e` the payer will see:\n\n```bash\nlightning-cli invoice \u003camount\u003e \u003clabel\u003e \u003cdescription\u003e\n```\n\nThis returns some internal details, and a standard invoice string called `bolt11` (named after the [BOLT #11 lightning spec][BOLT11]).\n\n[BOLT11]: https://github.com/lightning/bolts/blob/master/11-payment-encoding.md\n\nThe sender can feed this `bolt11` string to the `decodepay` command to see what it is, and pay it simply using the `pay` command:\n\n```bash\nlightning-cli pay \u003cbolt11\u003e\n```\n\nNote that there are lower-level interfaces (and more options to these\ninterfaces) for more sophisticated use.\n\n## Configuration File\n\n`lightningd` can be configured either by passing options via the command line, or via a configuration file.\nCommand line options will always override the values in the configuration file.\n\nTo use a configuration file, create a file named `config` within your top-level lightning directory or network subdirectory\n(eg. `~/.lightning/config` or `~/.lightning/bitcoin/config`).  See `man -l doc/lightningd-config.5`.\n\nA sample configuration file is available at `contrib/config-example`.\n\n## Further information\n\n### Pruning\n\nCore Lightning requires JSON-RPC access to a fully synchronized `bitcoind` in order to synchronize with the Bitcoin network.\nAccess to ZeroMQ is not required and `bitcoind` does not need to be run with `txindex` like other implementations.\nThe lightning daemon will poll `bitcoind` for new blocks that it hasn't processed yet, thus synchronizing itself with `bitcoind`.\nIf `bitcoind` prunes a block that Core Lightning has not processed yet, e.g., Core Lightning was not running for a prolonged period, then `bitcoind` will not be able to serve the missing blocks, hence Core Lightning will not be able to synchronize anymore and will be stuck.\nIn order to avoid this situation you should be monitoring the gap between Core Lightning's blockheight using `lightning-cli getinfo` and `bitcoind`'s blockheight using `bitcoin-cli getblockchaininfo`.\nIf the two blockheights drift apart it might be necessary to intervene.\n\n### HD wallet encryption\n\nYou can encrypt the `hsm_secret` content (which is used to derive the HD wallet's master key) by passing the `--encrypted-hsm` startup argument, or by using the `hsmtool` (which you can find in the `tool/` directory at the root of this repo) with the `encrypt` method. You can unencrypt an encrypted `hsm_secret` using the `hsmtool` with the `decrypt` method.\n\nIf you encrypt your `hsm_secret`, you will have to pass the `--encrypted-hsm` startup option to `lightningd`. Once your `hsm_secret` is encrypted, you __will not__ be able to access your funds without your password, so please beware with your password management. Also, beware of not feeling too safe with an encrypted `hsm_secret`: unlike for `bitcoind` where the wallet encryption can restrict the usage of some RPC command, `lightningd` always needs to access keys from the wallet which is thus __not locked__ (yet), even with an encrypted BIP32 master seed.\n\n### Developers\n\nDevelopers wishing to contribute should start with the developer guide [here](doc/contribute-to-core-lightning/coding-style-guidelines.md).\n\n[blockstream-store-blog]: https://blockstream.com/2018/01/16/en-lightning-charge/\n[std]: https://github.com/lightning/bolts\n[prs-badge]: https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat\n[prs]: http://makeapullrequest.com\n[bol2-badge]: https://badgen.net/badge/BoL2/chat/blue\n[bol2]: https://community.corelightning.org\n[ml1]: https://lists.ozlabs.org/listinfo/c-lightning\n[discord-badge]: https://badgen.net/badge/Discord/chat/blue\n[discord]: https://discord.gg/mE9s4rc5un\n[telegram-badge]: https://badgen.net/badge/Telegram/chat/blue\n[telegram]: https://t.me/lightningd\n[IRC-badge]: https://img.shields.io/badge/IRC-chat-blue.svg\n[IRC]: https://web.libera.chat/#c-lightning\n[irc1]: https://web.libera.chat/#lightning-dev\n[irc2]: https://web.libera.chat/#c-lightning\n[docs-badge]: https://readthedocs.org/projects/lightning/badge/?version=docs\n[docs]: https://docs.corelightning.org/docs\n[releases]: https://github.com/ElementsProject/lightning/releases\n[dockerhub]: https://hub.docker.com/r/elementsproject/lightningd/\n[jsonrpcspec]: https://www.jsonrpc.org/specification\n[helpme-github]: https://github.com/lightningd/plugins/tree/master/helpme\n[actions-badge]: https://github.com/ElementsProject/lightning/workflows/Continuous%20Integration/badge.svg\n[actions]: https://github.com/ElementsProject/lightning/actions\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felementsproject%2Flightning","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Felementsproject%2Flightning","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felementsproject%2Flightning/lists"}