From d49aea376c28a3139e7c690d14729c0263420ba2 Mon Sep 17 00:00:00 2001 From: Simon Vrouwe Date: Sun, 11 Dec 2022 12:56:03 +0200 Subject: [PATCH] doc: "--enable-experimental-features" hard-codes experimental-offers + experimental-onion-messages as enabled, ignoring their command line flags. Also add some references to BOLT drafts (PR #), plus a few cosmetic changes. --- doc/lightningd-config.5.md | 37 +++++++++++++++++++++++-------------- 1 file changed, 23 insertions(+), 14 deletions(-) diff --git a/doc/lightningd-config.5.md b/doc/lightningd-config.5.md index 8f0dcc7f0..116b06313 100644 --- a/doc/lightningd-config.5.md +++ b/doc/lightningd-config.5.md @@ -174,7 +174,7 @@ Subsystems include: * *jsonrpc#FD*: Each JSONRPC connection, FD = file descriptor number - + The following subsystems exist for each channel, where N is an incrementing internal integer id assigned for the lifetime of the channel: * *openingd-chan#N*: Each opening / idling daemon @@ -185,10 +185,10 @@ Subsystems include: * *onchaind-chan#N*: Each onchain close handling daemon - + So, **log-level=debug:plugin** would set debug level logging on all plugins and the plugin manager. **log-level=io:chan#55** would set -IO logging on channel number 55 (or 550, for that matter). +IO logging on channel number 55 (or 550, for that matter). **log-level=debug:024b9a1fa8** would set debug logging for that channel (or any node id containing that string). @@ -662,21 +662,26 @@ Experimental options are subject to breakage between releases: they are made available for advanced users who want to test proposed features. When the build is configured _without_ `--enable-experimental-features`, below options are available but disabled by default. -A build _with_ `--enable-experimental-features` enables some of below options -by default and also adds support for even more features. Supported features can -be listed with `lightningd --list-features-only`. +Supported features can be listed with `lightningd --list-features-only` + +A build _with_ `--enable-experimental-features` flag hard-codes some of below +options as enabled, ignoring their command line flag. It may also add support for +even more features. The safest way to determine the active configuration is by +checking `listconfigs` or by looking at `our_features` (bits) in `getinfo`. * **experimental-onion-messages** Specifying this enables sending, forwarding and receiving onion messages, -which are in draft status in the BOLT specifications. +which are in draft status in the [bolt][bolt] specifications (PR #759). +A build with `--enable-experimental-features` usually enables this via +experimental-offers, see below. * **experimental-offers** Specifying this enables the `offers` and `fetchinvoice` plugins and -corresponding functionality, which are in draft status as BOLT12. -This usually requires **experimental-onion-messages** as well. See -lightning-offer(7) and lightning-fetchinvoice(7). +corresponding functionality, which are in draft status ([bolt][bolt] #798) as [bolt12][bolt12]. +A build with `--enable-experimental-features` enables this permanently and usually +enables experimental-onion-messages as well. * **fetchinvoice-noconnect** @@ -685,14 +690,14 @@ trying to connect directly to the offering node as a last resort. * **experimental-shutdown-wrong-funding** - Specifying this allows the `wrong_funding` field in shutdown: if a + Specifying this allows the `wrong_funding` field in _shutdown: if a remote node has opened a channel but claims it used the incorrect txid (and the channel hasn't been used yet at all) this allows them to -negotiate a clean shutdown with the txid they offer. +negotiate a clean shutdown with the txid they offer ([#4421][pr4421]). * **experimental-dual-fund** - Specifying this enables support for the dual funding protocol, + Specifying this enables support for the dual funding protocol ([bolt][bolt] #851), allowing both parties to contribute funds to a channel. The decision about whether to add funds or not to a proposed channel is handled automatically by a plugin that implements the appropriate logic for @@ -702,7 +707,7 @@ your needs. The default behavior is to not contribute funds. Specifying this enables support for accepting incoming WebSocket connections on that port, on any IPv4 and IPv6 addresses you listen -to. The normal protocol is expected to be sent over WebSocket binary +to ([bolt][bolt] #891). The normal protocol is expected to be sent over WebSocket binary frames once the connection is upgraded. BUGS @@ -734,3 +739,7 @@ COPYING Note: the modules in the ccan/ directory have their own licenses, but the rest of the code is covered by the BSD-style MIT license. + +[bolt]: https://github.com/lightning/bolts +[bolt12]: https://github.com/rustyrussell/lightning-rfc/blob/guilt/offers/12-offer-encoding.md +[pr4421]: https://github.com/ElementsProject/lightning/pull/4421