From 7533ba4ed3bb8e52ef273f0204e204fa8c8c02b6 Mon Sep 17 00:00:00 2001 From: ShahanaFarooqui Date: Wed, 25 Jun 2025 17:57:58 -0700 Subject: [PATCH 1/3] doc: Move deprecated features page from API reference list to Developer's guide --- .../{deprecations.md => deprecated-features.md} | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) rename doc/developers-guide/{deprecations.md => deprecated-features.md} (98%) diff --git a/doc/developers-guide/deprecations.md b/doc/developers-guide/deprecated-features.md similarity index 98% rename from doc/developers-guide/deprecations.md rename to doc/developers-guide/deprecated-features.md index 54a5f8e819be..2ed1fb06e924 100644 --- a/doc/developers-guide/deprecations.md +++ b/doc/developers-guide/deprecated-features.md @@ -1,6 +1,6 @@ --- -title: "Deprecated Feature" -slug: "deprecations" +title: "Deprecated Features" +slug: "deprecated-features" excerpt: "Deprecated features and timeline for old feature removals." hidden: false --- From 4732e80b0c8b0dc54a049dc9b6bbe0e2108e4a52 Mon Sep 17 00:00:00 2001 From: ShahanaFarooqui Date: Wed, 25 Jun 2025 18:52:28 -0700 Subject: [PATCH 2/3] doc: Update Commando plugin details and link --- doc/developers-guide/app-development.md | 2 +- .../{commando.md => commando-plugin.md} | 10 ++++------ 2 files changed, 5 insertions(+), 7 deletions(-) rename doc/developers-guide/app-development/{commando.md => commando-plugin.md} (62%) diff --git a/doc/developers-guide/app-development.md b/doc/developers-guide/app-development.md index 43a1b809f951..b236b7d1c394 100644 --- a/doc/developers-guide/app-development.md +++ b/doc/developers-guide/app-development.md @@ -9,7 +9,7 @@ There are several ways to connect and interact with a Core Lightning node in ord - Using **[JSON-RPC commands](doc:json-rpc)** if you're building an application in the same system as the CLN node. - Using **[REST APIs](doc:rest)** if you're building an application in a remote client and want to connect to the CLN node over a secure network using REST interface. - Using **[gRPC APIs](doc:grpc)** if you're building an application in a remote client and want to connect to the CLN node over a secure network using gRPC interface. -- Using **[Commando](doc:commando)** to connect to a CLN node over the lightning network and issue commands. +- Using **[Commando Plugin](doc:commando-plugin)** to connect to a CLN node over the lightning network and issue commands. - Using **[WSS Proxy](doc:wss-proxy)** to connect to a CLN node over web secure socket proxy. - Third-party libraries that offer **[JSON over HTTPS](doc:third-party-libraries#json-over-https)** or **[GraphQL](doc:third-party-libraries#graphql)** (deprecated) frameworks to connect to a CLN node remotely. diff --git a/doc/developers-guide/app-development/commando.md b/doc/developers-guide/app-development/commando-plugin.md similarity index 62% rename from doc/developers-guide/app-development/commando.md rename to doc/developers-guide/app-development/commando-plugin.md index 75fc99fca8ca..e119abd2dd58 100644 --- a/doc/developers-guide/app-development/commando.md +++ b/doc/developers-guide/app-development/commando-plugin.md @@ -1,6 +1,6 @@ --- title: "Commando" -slug: "commando" +slug: "commando-plugin" hidden: false createdAt: "2023-02-08T09:54:01.784Z" updatedAt: "2023-09-05T13:55:16.224Z" @@ -9,13 +9,11 @@ updatedAt: "2023-09-05T13:55:16.224Z" > > Used for applications that want to connect to a CLN node over the lightning network in a secure manner. -Commando is a direct-to-node plugin that ships natively with Core Lightning. It lets you set _runes_ to create fine-grained access controls to a CLN node's RPC , and provides access to those same RPCs via Lightning-native network connections. +Commando is a direct-to-node plugin that ships natively with Core Lightning. It lets you set _runes_ to create fine-grained access controls to a CLN node's RPC and provides access to those same RPCs via Lightning-native network connections. -The commando plugin adds some cool RPC methods like: `commando`, `commando-rune`, `commando-blacklist` and `commando-listrunes`. +The commando plugin uses RPC method `commando` which allows you to send a directly connected peer an RPC request. In turn, it will run and send the result to you. This uses the secure connections that Lightning nodes establish with each other on connect. As arbitrary RPC executions by any connected node can be dangerous, generally, the peer will only allow you to execute the command if you've also provided a `rune`. -`commando` RPC allows you to send a directly connected peer an RPC request, who, in turn, will run and send the result to you. This uses the secure connections that Lightning nodes establish with each other on connect. As arbitrary RPC executions by any connected node can be dangerous, generally, the peer will only allow you to execute the command if you've also provided a `rune`. - -For more details on using runes, read through the docs for [commando](ref:lightning-commando). +For more details on using runes, read through the docs for [commando](ref:commando). Check out [this](https://www.youtube.com/watch?v=LZLRCPNn7vA) video of William Casarin (@jb55) walking through how to create runes and connect to a Lightning node via [lnsocket](https://github.com/jb55/lnsocket). From b9c5cf241988b72fd110bfac7fd90ad564256b9f Mon Sep 17 00:00:00 2001 From: ShahanaFarooqui Date: Wed, 25 Jun 2025 19:18:02 -0700 Subject: [PATCH 3/3] doc: Fix links to avoid 404 error --- doc/beginners-guide/beginners-guide.md | 20 +++++++++---------- .../app-development/json-rpc.md | 14 +------------ .../a-day-in-the-life-of-a-plugin.md | 6 +++--- .../plugin-development/hooks.md | 2 +- .../advanced-setup/bitcoin-core.md | 2 +- .../getting-started/configuration.md | 16 +++++++-------- doc/node-operators-guide/analytics.md | 2 +- doc/node-operators-guide/faq.md | 8 ++++---- 8 files changed, 29 insertions(+), 41 deletions(-) diff --git a/doc/beginners-guide/beginners-guide.md b/doc/beginners-guide/beginners-guide.md index 2e8e94001c4b..cae17de7d1df 100644 --- a/doc/beginners-guide/beginners-guide.md +++ b/doc/beginners-guide/beginners-guide.md @@ -35,23 +35,23 @@ You can start `lightningd` with the following command: lightningd --network=bitcoin --log-level=debug ``` -This creates a `.lightning/` subdirectory in your home directory: see `man -l doc/lightningd.8` (or [???](???)) for more runtime options. +This creates a `.lightning/` subdirectory in your home directory: see `man -l doc/lightningd.8` (or [lightningd-config](ref:lightningd-config)) for more runtime options. ## Using The JSON-RPC Interface -Core Lightning exposes a [JSON-RPC 2.0](https://www.jsonrpc.org/specification) interface over a Unix Domain socket; the [`lightning-cli`](ref:lightning-cli) tool can be used to access it, or there is a [python client library](???). +Core Lightning exposes a [JSON-RPC 2.0](https://www.jsonrpc.org/specification) interface over a Unix Domain socket; the [`lightning-cli`](ref:lightning-cli) tool can be used to access it, or there is a [python client library](doc:json-rpc#using-python). -You can use `[lightning-cli](ref:lightning-cli) help` to print a table of RPC methods; `[lightning-cli](lightning-cli) help ` will offer specific information on that command. +You can use `lightning-cli help` to print a table of RPC methods; `lightning-cli help ` will offer specific information on that command. Useful commands: -- [lightning-newaddr](ref:lightning-newaddr): get a bitcoin address to deposit funds into your lightning node. -- [lightning-listfunds](ref:lightning-listfunds): see where your funds are. -- [lightning-connect](ref:lightning-connect): connect to another lightning node. -- [lightning-fundchannel](ref:lightning-fundchannel): create a channel to another connected node. -- [lightning-invoice](ref:lightning-invoice): create an invoice to get paid by another node. -- [lightning-pay](ref:lightning-pay): pay someone else's invoice. -- [lightning-plugin](ref:lightning-plugin): commands to control extensions. +- [newaddr](ref:newaddr): get a bitcoin address to deposit funds into your lightning node. +- [listfunds](ref:listfunds): see where your funds are. +- [connect](ref:connect): connect to another lightning node. +- [fundchannel](ref:fundchannel): create a channel to another connected node. +- [invoice](ref:invoice): create an invoice to get paid by another node. +- [pay](ref:pay): pay someone else's invoice. +- [plugin](ref:plugin): commands to control extensions. ## Care And Feeding Of Your New Lightning Node diff --git a/doc/developers-guide/app-development/json-rpc.md b/doc/developers-guide/app-development/json-rpc.md index 3c4be13dc434..ecf1641d68ee 100644 --- a/doc/developers-guide/app-development/json-rpc.md +++ b/doc/developers-guide/app-development/json-rpc.md @@ -13,19 +13,7 @@ updatedAt: "2023-02-21T13:50:10.086Z" Core Lightning exposes a [JSON-RPC 2.0](https://www.jsonrpc.org/specification) interface over a Unix Domain socket; the [`lightning-cli`](ref:lightning-cli) tool can be used to access it, or there is a [python client library](doc:json-rpc#using-python). -You can use `[lightning-cli](ref:lightning-cli) help` to print a table of RPC methods; `[lightning-cli](lightning-cli) help ` will offer specific information on that command. - -Useful commands: - -- [lightning-newaddr](ref:lightning-newaddr): get a bitcoin address to deposit funds into your lightning node. -- [lightning-listfunds](ref:lightning-listfunds): see where your funds are. -- [lightning-connect](ref:lightning-connect): connect to another lightning node. -- [lightning-fundchannel](ref:lightning-fundchannel): create a channel to another connected node. -- [lightning-invoice](ref:lightning-invoice): create an invoice to get paid by another node. -- [lightning-pay](ref:lightning-pay): pay someone else's invoice. -- [lightning-plugin](ref:lightning-plugin): commands to control extensions. - -A complete list of all JSON-RPC commands is available at [API Reference](ref:lightning-addgossip). +You can use `lightning-cli help` to print a table of RPC methods; `lightning-cli help ` will offer specific information on that command. A complete list of all JSON-RPC commands is available at [API Reference](ref:get_list_methods_resource). ## Using Python diff --git a/doc/developers-guide/plugin-development/a-day-in-the-life-of-a-plugin.md b/doc/developers-guide/plugin-development/a-day-in-the-life-of-a-plugin.md index e6e971a19ca6..41c817c9ede0 100644 --- a/doc/developers-guide/plugin-development/a-day-in-the-life-of-a-plugin.md +++ b/doc/developers-guide/plugin-development/a-day-in-the-life-of-a-plugin.md @@ -28,7 +28,7 @@ lightningd --plugin=/path/to/plugin1 --plugin=path/to/plugin2 Once those two methods were called `lightningd` will start passing through incoming JSON-RPC commands that were registered and the plugin may interact with `lightningd` using the JSON-RPC over Unix-Socket interface. -Above is generally valid for plugins that start when `lightningd` starts. For dynamic plugins that start via the [lightning-plugin](ref:lightning-plugin) JSON-RPC command there is some difference, mainly in options passthrough (see note in [Types of Options](doc:a-day-in-the-life-of-a-plugin#types-of-options)). +Above is generally valid for plugins that start when `lightningd` starts. For dynamic plugins that start via the [lightning-plugin](ref:plugin) JSON-RPC command there is some difference, mainly in options passthrough (see note in [Types of Options](doc:a-day-in-the-life-of-a-plugin#types-of-options)). - `shutdown` (optional): if subscribed to "shutdown" notification, a plugin can exit cleanly when `lightningd` is shutting down or when stopped via `plugin stop`. @@ -106,7 +106,7 @@ The `subscriptions` array indicates what [Event Notifications](doc:event-notific The `nonnumericids` indicates that the plugin can handle string JSON request `id` fields: prior to v22.11 lightningd used numbers for these, and the change to strings broke some plugins. If present, this must be `true` (since v23.05). See the [lightningd-rpc](ref:lightningd-rpc) documentation for how to handle JSON `id` fields! -The `dynamic` indicates if the plugin can be managed after `lightningd` has been started using the [lightning-plugin](ref:lightning-plugin) JSON-RPC command. Critical plugins that should not be stopped should set it to false. Plugin `options` can be passed to dynamic plugins as argument to the `plugin` command . +The `dynamic` indicates if the plugin can be managed after `lightningd` has been started using the [lightning-plugin](ref:plugin) JSON-RPC command. Critical plugins that should not be stopped should set it to false. Plugin `options` can be passed to dynamic plugins as argument to the `plugin` command . If you can handle the `check` command on your commands, you should set `cancheck` to `true` and expect `lightningd` to pass through any user-requested `check` commands to you directly (without this, `check` currently always passes, which is not very useful!). @@ -251,4 +251,4 @@ The `startup` field allows a plugin to detect if it was started at `lightningd` ### Timeouts During startup ("startup" is true), the plugin has 60 seconds to return `getmanifest` and another 60 seconds to return `init`, or gets killed. -When started dynamically via the [lightning-plugin](ref:lightning-plugin) JSON-RPC command, both `getmanifest` and `init` should be completed within 60 seconds. +When started dynamically via the [lightning-plugin](ref:plugin) JSON-RPC command, both `getmanifest` and `init` should be completed within 60 seconds. diff --git a/doc/developers-guide/plugin-development/hooks.md b/doc/developers-guide/plugin-development/hooks.md index 95e6f1b1bb76..1e1cfdbdf41d 100644 --- a/doc/developers-guide/plugin-development/hooks.md +++ b/doc/developers-guide/plugin-development/hooks.md @@ -576,7 +576,7 @@ Note: The `rpc_command` hook is chainable. If two or more plugins try to replace ### `custommsg` -The `custommsg` plugin hook is the receiving counterpart to the [`sendcustommsg`](ref:lightning-sendcustommsg) RPC method and allows plugins to handle messages that are not handled internally. The goal of these two components is to allow the implementation of custom protocols or prototypes on top of a Core Lightning node, without having to change the node's implementation itself. +The `custommsg` plugin hook is the receiving counterpart to the [`sendcustommsg`](ref:sendcustommsg) RPC method and allows plugins to handle messages that are not handled internally. The goal of these two components is to allow the implementation of custom protocols or prototypes on top of a Core Lightning node, without having to change the node's implementation itself. The payload for a call follows this format: diff --git a/doc/getting-started/advanced-setup/bitcoin-core.md b/doc/getting-started/advanced-setup/bitcoin-core.md index 5661de53d296..657c4a27bdd7 100644 --- a/doc/getting-started/advanced-setup/bitcoin-core.md +++ b/doc/getting-started/advanced-setup/bitcoin-core.md @@ -15,7 +15,7 @@ The lightning daemon will poll `bitcoind` for new blocks that it hasn't processe If `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. -In order to avoid this situation you should be monitoring the gap between Core Lightning's blockheight using `[lightning-cli](ref:lightning-cli) getinfo` and `bitcoind`'s blockheight using `bitcoin-cli getblockchaininfo`. If the two blockheights drift apart it might be necessary to intervene. +In 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`. If the two blockheights drift apart it might be necessary to intervene. # Connecting to Bitcoin Core remotely diff --git a/doc/getting-started/getting-started/configuration.md b/doc/getting-started/getting-started/configuration.md index 19b8742796e7..d527d9adbe2c 100644 --- a/doc/getting-started/getting-started/configuration.md +++ b/doc/getting-started/getting-started/configuration.md @@ -28,7 +28,7 @@ Blank lines and lines beginning with `#` are ignored. `--help` will show you the defaults for many options; they vary with network settings so you can specify `--network` before `--help` to see the defaults for that network. -The [`lightning-listconfigs`](ref:lightning-listconfigs) command will output a valid configuration file using the current settings. +The [`listconfigs`](ref:listconfigs) command will output a valid configuration file using the current settings. ## Options @@ -255,11 +255,11 @@ The [`lightning-listconfigs`](ref:lightning-listconfigs) command will output a v - **fee-base**=_MILLISATOSHI_ - Default: 1000. The base fee to charge for every payment which passes through. Note that millisatoshis are a very, very small unit! Changing this value will only affect new channels and not existing ones. If you want to change fees for existing channels, use the RPC call [`lightning-setchannel`](ref:lightning-setchannel). + Default: 1000. The base fee to charge for every payment which passes through. Note that millisatoshis are a very, very small unit! Changing this value will only affect new channels and not existing ones. If you want to change fees for existing channels, use the RPC call [`setchannel`](ref:setchannel). - **fee-per-satoshi**=_MILLIONTHS_ - Default: 10 (0.001%). This is the proportional fee to charge for every payment which passes through. As percentages are too coarse, it's in millionths, so 10000 is 1%, 1000 is 0.1%. Changing this value will only affect new channels and not existing ones. If you want to change fees for existing channels, use the RPC call [`lightning-setchannel`](ref:lightning-setchannel). + Default: 10 (0.001%). This is the proportional fee to charge for every payment which passes through. As percentages are too coarse, it's in millionths, so 10000 is 1%, 1000 is 0.1%. Changing this value will only affect new channels and not existing ones. If you want to change fees for existing channels, use the RPC call [`setchannel`](ref:setchannel). - **min-capacity-sat**=_SATOSHI_ @@ -277,18 +277,18 @@ The [`lightning-listconfigs`](ref:lightning-listconfigs) command will output a v - **force-feerates**==_VALUES_ Networks like regtest and testnet have unreliable fee estimates: we usually treat them as the minimum (253 sats/kw) if we can't get them. - This allows override of one or more of our standard feerates (see [`lightning-feerates`](ref:lightning-feerates)). Up to 5 values, separated by '/' can be provided: if fewer are provided, then the final value is used for the remainder. The values are in per-kw (roughly 1/4 of bitcoind's per-kb values), and the order is "opening", "mutual_close", "unilateral_close", "delayed_to_us", "htlc_resolution", and "penalty". + This allows override of one or more of our standard feerates (see [`feerates`](ref:feerates)). Up to 5 values, separated by '/' can be provided: if fewer are provided, then the final value is used for the remainder. The values are in per-kw (roughly 1/4 of bitcoind's per-kb values), and the order is "opening", "mutual_close", "unilateral_close", "delayed_to_us", "htlc_resolution", and "penalty". You would usually put this option in the per-chain config file, to avoid setting it on Bitcoin mainnet! e.g. `~rusty/.lightning/regtest/config`. - **htlc-minimum-msat**=_MILLISATOSHI_ Default: 0. Sets the minimal allowed HTLC value for newly created channels. - If you want to change the `htlc_minimum_msat` for existing channels, use the RPC call [`lightning-setchannel`](ref:lightning-setchannel). + If you want to change the `htlc_minimum_msat` for existing channels, use the RPC call [`setchannel`](ref:setchannel). - **htlc-maximum-msat**=_MILLISATOSHI_ - Default: unset (no limit). Sets the maximum allowed HTLC value for newly created channels. If you want to change the `htlc_maximum_msat` for existing channels, use the RPC call [`lightning-setchannel`](ref:lightning-setchannel). + Default: unset (no limit). Sets the maximum allowed HTLC value for newly created channels. If you want to change the `htlc_maximum_msat` for existing channels, use the RPC call [`setchannel`](ref:setchannel). ### Lightning channel and HTLC options @@ -477,13 +477,13 @@ plugins along with any immediate subdirectories). You can specify additional pat - **disable-plugin**=_PLUGIN_ - If _PLUGIN_ contains a /, plugins with the same path as _PLUGIN_ will not be loaded at startup. Otherwise, no plugin with that base name will be loaded at startup, whatever directory it is in. This option is useful for disabling a single plugin inside a directory. You can still explicitly load plugins which have been disabled, using [lightning-plugin](ref:lightning-plugin) `start`. + If _PLUGIN_ contains a /, plugins with the same path as _PLUGIN_ will not be loaded at startup. Otherwise, no plugin with that base name will be loaded at startup, whatever directory it is in. This option is useful for disabling a single plugin inside a directory. You can still explicitly load plugins which have been disabled, using [plugin](ref:plugin) `start`. - **important-plugin**=_PLUGIN_ Specify a plugin to run as part of Core Lightning. This can be specified multiple times to add multiple plugins. - Plugins specified via this option are considered so important, that if the plugin stops for any reason (including via [lightning-plugin](ref:lightning-plugin) `stop`), Core Lightning will also stop running. + Plugins specified via this option are considered so important, that if the plugin stops for any reason (including via [plugin](ref:plugin) `stop`), Core Lightning will also stop running. This way, you can monitor crashes of important plugins by simply monitoring if Core Lightning terminates. Built-in plugins, which are installed with lightningd, are automatically considered important. diff --git a/doc/node-operators-guide/analytics.md b/doc/node-operators-guide/analytics.md index af74c296b115..d269de421363 100644 --- a/doc/node-operators-guide/analytics.md +++ b/doc/node-operators-guide/analytics.md @@ -10,7 +10,7 @@ updatedAt: "2023-02-21T13:39:32.669Z" Since version 23.02, Core Lightning ships with a powerful SQL plugin that allows you to query your node and analyse data for channel / liquidity management, accounting and audit. -See [lightning-sql](ref:lightning-sql) for a full primer on its usage. +See [sql](ref:sql) for a full primer on its usage. ## Using third-party software diff --git a/doc/node-operators-guide/faq.md b/doc/node-operators-guide/faq.md index 62826c9399e6..de7c479a03bc 100644 --- a/doc/node-operators-guide/faq.md +++ b/doc/node-operators-guide/faq.md @@ -17,14 +17,14 @@ A better option is to use the [`summary` plugin](https://github.com/lightningd/p ### My channel is in state `STATE`, what does that mean ? -See the [listpeers](ref:lightning-listpeers) command. +See the [listpeers](ref:listpeers) command. ### My payment is failing / all my payments are failing, why ? There are many reasons for a payment failure. The most common one is a [failure](https://github.com/lightning/bolts/blob/master/04-onion-routing.md#failure-messages) along the route from you to the payee. The best (and most common) solution to a route failure problem is to open more channels, which should increase the available routes to the recipient and lower the probability of a failure. -**Hint:** use the [`pay`](ref:lightning-pay) command which is will iterate through trying all possible routes, +**Hint:** use the [`pay`](ref:pay) command which is will iterate through trying all possible routes, instead of the low-level `sendpay` command which only tries the passed in route. ### How can I receive payments ? @@ -162,7 +162,7 @@ There are 3 types of 'rescans' you can make: If you lose data (likely corrupted `lightningd.sqlite3`) about a channel **with `option_static_remotekey` enabled**, you can wait for your peer to unilateraly close the channel, then use `tools/hsmtool` with the `guesstoremote` command to attempt to recover your funds from the peer's published unilateral close transaction. If `option_static_remotekey` was not enabled, you're probably out of luck. The keys for your funds in your peer's unilateral close transaction are derived from information you lost. Fortunately, since version `0.7.3` channels are created with `option_static_remotekey` by default if your peer supports it. Which is to say that channels created after block [598000](https://blockstream.info/block/0000000000000000000dd93b8fb5c622b9c903bf6f921ef48e266f0ead7faedb) -(short channel id starting with > 598000) have a high chance of supporting `option_static_remotekey`. You can verify it using the `features` field from the [`listpeers` command](ref:lightning-listpeers)'s result. +(short channel id starting with > 598000) have a high chance of supporting `option_static_remotekey`. You can verify it using the `features` field from the [`listpeers` command](ref:listpeers)'s result. Here is an example in Python checking if [one of the `option_static_remotekey` bits](https://github.com/lightning/bolts/blob/master/09-features.md) is set in the negotiated features corresponding to `0x02aaa2`: @@ -179,4 +179,4 @@ If `option_static_remotekey` is enabled you can attempt to recover the funds in ### How do I get the `psbt` for RPC calls that need it? -A `psbt` is created and returned by a call to [`utxopsbt` with `reservedok=true`](ref:lightning-utxopsbt). +A `psbt` is created and returned by a call to [`utxopsbt` with `reservedok=true`](ref:utxopsbt).