From b27f4e1f9a6694ffab77836f70dbfa23593f7804 Mon Sep 17 00:00:00 2001 From: ZmnSCPxj jxPCSnmZ Date: Sun, 12 Jul 2020 11:30:35 +0800 Subject: [PATCH] doc/lightning-feerates.7.md: Document `feerates` command. Changelog-None --- doc/Makefile | 1 + doc/lightning-feerates.7 | 155 +++++++++++++++++++++++++++++++++ doc/lightning-feerates.7.md | 130 +++++++++++++++++++++++++++ doc/lightning-fundchannel.7.md | 3 +- doc/lightning-txprepare.7.md | 3 +- doc/lightning-withdraw.7.md | 2 +- 6 files changed, 291 insertions(+), 3 deletions(-) create mode 100644 doc/lightning-feerates.7 create mode 100644 doc/lightning-feerates.7.md diff --git a/doc/Makefile b/doc/Makefile index a7611e893..9d1064d90 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -18,6 +18,7 @@ MANPAGES := doc/lightning-cli.1 \ doc/lightning-delinvoice.7 \ doc/lightning-dev-sendcustommsg.7 \ doc/lightning-disconnect.7 \ + doc/lightning-feerates.7 \ doc/lightning-fundchannel.7 \ doc/lightning-fundchannel_start.7 \ doc/lightning-fundchannel_complete.7 \ diff --git a/doc/lightning-feerates.7 b/doc/lightning-feerates.7 new file mode 100644 index 000000000..8c773b5bf --- /dev/null +++ b/doc/lightning-feerates.7 @@ -0,0 +1,155 @@ +.TH "LIGHTNING-FEERATES" "7" "" "" "lightning-feerates" +.SH NAME +lightning-feerates - Command for querying recommended onchain feerates +.SH SYNOPSIS + +\fBfeerates\fR \fIstyle\fR + +.SH DESCRIPTION + +The \fBfeerates\fR command returns the feerates that C-lightning will use\. +The feerates will be based on the recommended feerates from the backend\. +The backend may fail to provide estimates, but if it was able to provide +estimates in the past, C-lightning will continue to use those for a while\. +C-lightning will also smoothen feerate estimations from the backend\. + + +\fIstyle\fR is either of the two strings: + +.RS +.IP \[bu] +\fIperkw\fR - provide feerate in units of satoshis per 1000 weight\. +.IP \[bu] +\fIperkb\fR - provide feerate in units of satoshis per 1000 virtual bytes\. + +.RE + +Bitcoin transactions have non-witness and witness bytes: + +.RS +.IP \[bu] +Non-witness bytes count as 4 weight, 1 virtual byte\. +All bytes other than SegWit witness count as non-witness bytes\. +.IP \[bu] +Witness bytes count as 1 weight, 0\.25 virtual bytes\. + +.RE + +Thus, all \fIperkb\fR feerates will be exactly 4 times \fIperkw\fR feerates\. + + +To compute the fee for a transaction, multiply its weight or virtual bytes +by the appropriate \fIperkw\fR or \fIperkw\fR feerate +returned by this command, +then divide by 1000\. + + +There is currently no way to change these feerates from the RPC\. +If you need custom control over onchain feerates, +you will need to provide your own plugin +that replaces the \fBbcli\fR plugin backend\. +For commands like \fBlightning-withdraw\fR(7) or \fBlightning-fundchannel\fR(7) you +can provide a preferred feerate directly as a parameter, +which will override the recommended feerates returned by \fBfeerates\fR\. + +.SH RETURN VALUE + +The \fBfeerates\fR command returns the feerates in an object named +\fIperkw\fR or \fIperkb\fR, depending on your \fIstyle\fR parameter\. + + +Some of these estimations may be missing, except for \fImin_acceptable\fR +and \fImax_acceptable\fR, which are always present\. + + +The \fIperkw\fR or \fIperkb\fR object may have fields containing the estimates: + +.RS +.IP \[bu] +\fIopening\fR - feerate used for channel opening by \fBlightning-fundchannel\fR(7), +as well as normal onchain-to-onchain spends by \fBlightning-withdraw\fR(7)\. +In general, for all normal onchain-to-onchain spends, this is the feerate +you should also use\. +.IP \[bu] +\fImutual_close\fR - the starting feerate used in mutual close negotiation\. +Note that since mutual close is a \fBnegotiation\fR, +the actual feerate used in mutual close +will be somewhere between this +and the corresponding mutual close feerate of the peer\. +.IP \[bu] +\fIunilateral_close\fR - the feerate we will pay for when a unilateral close +is done on a channel we originally funded\. +When anchor commitments are implemented, +this will be the feerate we will use +for a unilateral close we initiated\. +.IP \[bu] +\fIdelayed_to_us\fR - the feerate we will use when claiming our output from +a unilateral close we initiated\. +.IP \[bu] +\fIhtlc_resolution\fR - the feerate we will use to claim HTLCs +from a unilateral close we initiated\. +.IP \[bu] +\fIpenalty\fR - the feerate we will use to revoke old state, +if the counterparty attempts to cheat us\. + +.RE + +The following fields are always present in the \fIperkw\fR or \fIperkb\fR object: + +.RS +.IP \[bu] +\fImin_acceptable\fR - the smallest feerate that you can use, +usually the minimum relayed feerate of the backend\. +.IP \[bu] +\fImax_acceptable\fR - the largest feerate we will accept +from remote negotiations\. +If a peer attempts to open a channel to us but wants a unilateral close +feerate larger than \fImax_acceptable\fR, we reject the open attempt\. +If the peer attempts to change the unilateral close feerate of a channel it +opened to us, such that the new feerate exceeds \fImax_acceptable\fR, we +unilaterally close the channel +(at the current unilateral close feerate instead of the new one)\. + +.RE +.SH ERRORS + +The \fBfeerates\fR command will never error, +however some fields may be missing in the result +if feerate estimates for that kind of transaction are unavailable\. + +.SH NOTES + +Many other commands have a \fIfeerate\fR parameter, which can be the strings +\fIurgent\fR, \fInormal\fR, or \fIslow\fR\. +These are mapped to the \fBfeerates\fR outputs as: + +.RS +.IP \[bu] +\fIurgent\fR - equal to \fIunilateral_close\fR +.IP \[bu] +\fInormal\fR - equal to \fIopening\fR +.IP \[bu] +\fIslow\fR - equal to \fImin_acceptable\fR\. + +.RE +.SH TRIVIA + +In C-lightning we like to call the weight unit "sipa" +in honor of Pieter Wuille, +who uses the name "sipa" on IRC and elsewhere\. +Internally we call the \fIperkw\fR style as "feerate per kilosipa"\. + +.SH AUTHOR + +ZmnSCPxj < \fIZmnSCPxj@protonmail.com\fR > wrote the initial version of this +manpage\. + +.SH SEE ALSO + +\fBlightning-fundchannel\fR(7), \fBlightning-withdraw\fR(7), \fBlightning-txprepare\fR(7), +\fBlightning-fundchannel_start\fR(7)\. + +.SH RESOURCES + +Main web site: \fIhttps://github.com/ElementsProject/lightning\fR + diff --git a/doc/lightning-feerates.7.md b/doc/lightning-feerates.7.md new file mode 100644 index 000000000..85a6af80e --- /dev/null +++ b/doc/lightning-feerates.7.md @@ -0,0 +1,130 @@ +lightning-feerates -- Command for querying recommended onchain feerates +======================================================================= + +SYNOPSIS +-------- + +**feerates** *style* + +DESCRIPTION +----------- + +The **feerates** command returns the feerates that C-lightning will use. +The feerates will be based on the recommended feerates from the backend. +The backend may fail to provide estimates, but if it was able to provide +estimates in the past, C-lightning will continue to use those for a while. +C-lightning will also smoothen feerate estimations from the backend. + +*style* is either of the two strings: + +* *perkw* - provide feerate in units of satoshis per 1000 weight. +* *perkb* - provide feerate in units of satoshis per 1000 virtual bytes. + +Bitcoin transactions have non-witness and witness bytes: + +* Non-witness bytes count as 4 weight, 1 virtual byte. + All bytes other than SegWit witness count as non-witness bytes. +* Witness bytes count as 1 weight, 0.25 virtual bytes. + +Thus, all *perkb* feerates will be exactly 4 times *perkw* feerates. + +To compute the fee for a transaction, multiply its weight or virtual bytes +by the appropriate *perkw* or *perkw* feerate +returned by this command, +then divide by 1000. + +There is currently no way to change these feerates from the RPC. +If you need custom control over onchain feerates, +you will need to provide your own plugin +that replaces the `bcli` plugin backend. +For commands like lightning-withdraw(7) or lightning-fundchannel(7) you +can provide a preferred feerate directly as a parameter, +which will override the recommended feerates returned by **feerates**. + +RETURN VALUE +------------ + +The **feerates** command returns the feerates in an object named +*perkw* or *perkb*, depending on your *style* parameter. + +Some of these estimations may be missing, except for *min\_acceptable* +and *max\_acceptable*, which are always present. + +The *perkw* or *perkb* object may have fields containing the estimates: + +* *opening* - feerate used for channel opening by lightning-fundchannel(7), + as well as normal onchain-to-onchain spends by lightning-withdraw(7). + In general, for all normal onchain-to-onchain spends, this is the feerate + you should also use. +* *mutual\_close* - the starting feerate used in mutual close negotiation. + Note that since mutual close is a **negotiation**, + the actual feerate used in mutual close + will be somewhere between this + and the corresponding mutual close feerate of the peer. +* *unilateral\_close* - the feerate we will pay for when a unilateral close + is done on a channel we originally funded. + When anchor commitments are implemented, + this will be the feerate we will use + for a unilateral close we initiated. +* *delayed\_to\_us* - the feerate we will use when claiming our output from + a unilateral close we initiated. +* *htlc_resolution* - the feerate we will use to claim HTLCs + from a unilateral close we initiated. +* *penalty* - the feerate we will use to revoke old state, + if the counterparty attempts to cheat us. + +The following fields are always present in the *perkw* or *perkb* object: + +* *min\_acceptable* - the smallest feerate that you can use, + usually the minimum relayed feerate of the backend. +* *max\_acceptable* - the largest feerate we will accept + from remote negotiations. + If a peer attempts to open a channel to us but wants a unilateral close + feerate larger than *max\_acceptable*, we reject the open attempt. + If the peer attempts to change the unilateral close feerate of a channel it + opened to us, such that the new feerate exceeds *max\_acceptable*, we + unilaterally close the channel + (at the current unilateral close feerate instead of the new one). + +ERRORS +------ + +The **feerates** command will never error, +however some fields may be missing in the result +if feerate estimates for that kind of transaction are unavailable. + +NOTES +----- + +Many other commands have a *feerate* parameter, which can be the strings +*urgent*, *normal*, or *slow*. +These are mapped to the **feerates** outputs as: + +* *urgent* - equal to *unilateral\_close* +* *normal* - equal to *opening* +* *slow* - equal to *min\_acceptable*. + +TRIVIA +------ + +In C-lightning we like to call the weight unit "sipa" +in honor of Pieter Wuille, +who uses the name "sipa" on IRC and elsewhere. +Internally we call the *perkw* style as "feerate per kilosipa". + +AUTHOR +------ + +ZmnSCPxj < > wrote the initial version of this +manpage. + +SEE ALSO +-------- + +lightning-fundchannel(7), lightning-withdraw(7), lightning-txprepare(7), +lightning-fundchannel_start(7). + +RESOURCES +--------- + +Main web site: diff --git a/doc/lightning-fundchannel.7.md b/doc/lightning-fundchannel.7.md index 84426bde1..879e58998 100644 --- a/doc/lightning-fundchannel.7.md +++ b/doc/lightning-fundchannel.7.md @@ -80,7 +80,8 @@ channel parameters (funding limits, channel reserves, fees, etc.). SEE ALSO -------- -lightning-connect(7), lightning-listfunds(), lightning-listpeers(7) +lightning-connect(7), lightning-listfunds(), lightning-listpeers(7), +lightning-feerates(7) RESOURCES --------- diff --git a/doc/lightning-txprepare.7.md b/doc/lightning-txprepare.7.md index b3c304793..11d4c29f8 100644 --- a/doc/lightning-txprepare.7.md +++ b/doc/lightning-txprepare.7.md @@ -76,7 +76,8 @@ Rusty Russell <> is mainly responsible. SEE ALSO -------- -lightning-withdraw(7), lightning-txsend(7), lightning-txdiscard(7) +lightning-withdraw(7), lightning-txsend(7), lightning-txdiscard(7), +lightning-feerates(7) RESOURCES --------- diff --git a/doc/lightning-withdraw.7.md b/doc/lightning-withdraw.7.md index 42e389310..7c19f7afd 100644 --- a/doc/lightning-withdraw.7.md +++ b/doc/lightning-withdraw.7.md @@ -63,7 +63,7 @@ SEE ALSO -------- lightning-listfunds(7), lightning-fundchannel(7), lightning-newaddr(7), -lightning-txprepare(7). +lightning-txprepare(7), lightning-feerates(7). RESOURCES ---------