mirror of
https://github.com/ElementsProject/lightning.git
synced 2025-01-18 13:25:43 +01:00
doc/lightning-feerates.7.md: Document feerates command.
Changelog-None
This commit is contained in:
ZmnSCPxj jxPCSnmZ
Rusty Russell
parent
869fa082d4
commit
b27f4e1f9a
@ -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 \
|
||||
|
||||
155
doc/lightning-feerates.7
generated
Normal file
155
doc/lightning-feerates.7
generated
Normal file
@ -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
|
||||
|
||||
130
doc/lightning-feerates.7.md
Normal file
130
doc/lightning-feerates.7.md
Normal file
@ -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>
|
||||
@ -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
|
||||
---------
|
||||
|
||||
@ -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
|
||||
---------
|
||||
|
||||
@ -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
|
||||
---------
|
||||
|
||||
Loading…
Reference in New Issue
Block a user