doc/lightning-feerates.7.md: Document `feerates` command.

Changelog-None

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 \

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
+

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 < <ZmnSCPxj@protonmail.com> > 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: <https://github.com/ElementsProject/lightning>

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
 ---------

doc/lightning-txprepare.7.md

@@ -76,7 +76,8 @@ Rusty Russell <<rusty@rustcorp.com.au>> 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
 ---------

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
 ---------