mirror of
https://github.com/ElementsProject/lightning.git
synced 2024-11-20 02:27:51 +01:00
43ae30df21
Useful for parsing a passed in feerate before calling lightningd with it, e.g. when you need to know what the feerate is for a fundpsbt before calling fundpsbt Changelog-Added: JSON-RPC: new command `parsefeerate` which takes a feerate string and returns the calculated perkw/perkb
173 lines
6.1 KiB
Groff
Generated
173 lines
6.1 KiB
Groff
Generated
.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
|
|
|
|
On success, an object is returned, containing:
|
|
|
|
.RS
|
|
.IP \[bu]
|
|
\fBperkb\fR (object, optional): If \fIstyle\fR parameter was perkb:
|
|
.RS
|
|
.IP \[bu]
|
|
\fBmin_acceptable\fR (u32): The smallest feerate that you can use, usually the minimum relayed feerate of the backend
|
|
.IP \[bu]
|
|
\fBmax_acceptable\fR (u32): The largest feerate we will accept from remote negotiations\. If a peer attempts to set the feerate higher than this we will unilaterally close the channel (or simply forget it if it's not open yet)\.
|
|
.IP \[bu]
|
|
\fBopening\fR (u32, optional): Default feerate for \fBlightning-fundchannel\fR(7) and \fBlightning-withdraw\fR(7)
|
|
.IP \[bu]
|
|
\fBmutual_close\fR (u32, optional): Feerate to aim for in cooperative shutdown\. 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]
|
|
\fBunilateral_close\fR (u32, optional): Feerate for commitment_transaction in a live channel which we originally funded
|
|
.IP \[bu]
|
|
\fBdelayed_to_us\fR (u32, optional): Feerate for returning unilateral close funds to our wallet
|
|
.IP \[bu]
|
|
\fBhtlc_resolution\fR (u32, optional): Feerate for returning unilateral close HTLC outputs to our wallet
|
|
.IP \[bu]
|
|
\fBpenalty\fR (u32, optional): Feerate to start at when penalizing a cheat attempt
|
|
|
|
.RE
|
|
|
|
.IP \[bu]
|
|
\fBperkw\fR (object, optional): If \fIstyle\fR parameter was perkw:
|
|
.RS
|
|
.IP \[bu]
|
|
\fBmin_acceptable\fR (u32): The smallest feerate that you can use, usually the minimum relayed feerate of the backend
|
|
.IP \[bu]
|
|
\fBmax_acceptable\fR (u32): The largest feerate we will accept from remote negotiations\. If a peer attempts to set the feerate higher than this we will unilaterally close the channel (or simply forget it if it's not open yet)\.
|
|
.IP \[bu]
|
|
\fBopening\fR (u32, optional): Default feerate for \fBlightning-fundchannel\fR(7) and \fBlightning-withdraw\fR(7)
|
|
.IP \[bu]
|
|
\fBmutual_close\fR (u32, optional): Feerate to aim for in cooperative shutdown\. 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]
|
|
\fBunilateral_close\fR (u32, optional): Feerate for commitment_transaction in a live channel which we originally funded
|
|
.IP \[bu]
|
|
\fBdelayed_to_us\fR (u32, optional): Feerate for returning unilateral close funds to our wallet
|
|
.IP \[bu]
|
|
\fBhtlc_resolution\fR (u32, optional): Feerate for returning unilateral close HTLC outputs to our wallet
|
|
.IP \[bu]
|
|
\fBpenalty\fR (u32, optional): Feerate to start at when penalizing a cheat attempt
|
|
|
|
.RE
|
|
|
|
.IP \[bu]
|
|
\fBonchain_fee_estimates\fR (object, optional):
|
|
.RS
|
|
.IP \[bu]
|
|
\fBopening_channel_satoshis\fR (u64): Estimated cost of typical channel open
|
|
.IP \[bu]
|
|
\fBmutual_close_satoshis\fR (u64): Estimated cost of typical channel close
|
|
.IP \[bu]
|
|
\fBunilateral_close_satoshis\fR (u64): Estimated cost of typical unilateral close (without HTLCs)
|
|
.IP \[bu]
|
|
\fBhtlc_timeout_satoshis\fR (u64): Estimated cost of typical HTLC timeout transaction
|
|
.IP \[bu]
|
|
\fBhtlc_success_satoshis\fR (u64): Estimated cost of typical HTLC fulfillment transaction
|
|
|
|
.RE
|
|
|
|
|
|
.RE
|
|
|
|
The following warnings may also be returned:
|
|
|
|
.RS
|
|
.IP \[bu]
|
|
\fBwarning_missing_feerates\fR: Some fee estimates are missing
|
|
|
|
.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 \fI<ZmnSCPxj@protonmail.com\fR> wrote the initial version of this
|
|
manpage\.
|
|
|
|
.SH SEE ALSO
|
|
|
|
\fBlightning-parsefeerate\fR(7), \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
|
|
|
|
\" SHA256STAMP:3c68e2e2b47bc4107d71e263372b3ec3ac77434d7319c670f293d3be88703fe7
|