2020-07-12 04:30:35 +01:00
lightning-feerates -- Command for querying recommended onchain feerates
=======================================================================
SYNOPSIS
--------
**feerates** *style*
DESCRIPTION
-----------
2022-05-13 16:54:36 +01:00
The **feerates** command returns the feerates that CLN will use.
2020-07-12 04:30:35 +01:00
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
2022-05-13 16:54:36 +01:00
estimates in the past, CLN will continue to use those for a while.
CLN will also smoothen feerate estimations from the backend.
2020-07-12 04:30:35 +01:00
*style* is either of the two strings:
2023-04-11 05:01:55 +01:00
* *perkw* - provide feerate in units of satoshis per 1000 weight (e.g. the minimum fee is usually `253perkw` )
* *perkb* - provide feerate in units of satoshis per 1000 virtual bytes (eg. the minimum fee is usually `1000perkb` )
Explorers often present fees in "sat/vB": 4 sat/vB is `4000perkb` or
`1000perkw` .
2020-07-12 04:30:35 +01:00
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
------------
doc/schemas: disableoffer, disconnect, feerates, fetchinvoice, fundchannel, fundchannel_cancel, fundchannel_complete, fundchannel_start, fundpsbt, getinfo, getlog, getroute.
We also add a test for getlog, since it was never called by the
testsuite.
Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2021-05-26 08:35:01 +01:00
[comment]: # (GENERATE-FROM-SCHEMA-START)
On success, an object is returned, containing:
2022-09-05 22:33:09 +01:00
doc/schemas: disableoffer, disconnect, feerates, fetchinvoice, fundchannel, fundchannel_cancel, fundchannel_complete, fundchannel_start, fundpsbt, getinfo, getlog, getroute.
We also add a test for getlog, since it was never called by the
testsuite.
Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2021-05-26 08:35:01 +01:00
- **perkb** (object, optional): If *style* parameter was perkb:
2023-04-07 05:39:53 +01:00
- **min\_acceptable** (u32): The smallest feerate that we allow peers to specify: half the 100-block estimate
2022-09-05 22:45:06 +01:00
- **max\_acceptable** (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).
2023-04-07 05:53:49 +01:00
- **floor** (u32): The smallest feerate that our backend tells us it will accept (i.e. minrelayfee or mempoolminfee) *(added v23.05)*
lightningd: clean up feerate handling, deprecate old terms.
Drop try_get_feerate() in favor of explicit feerate_for_deadline() and
smoothed_feerate_for_deadline().
This shows us everywhere we deal with old-style feerates by names.
`delayed_to_us` and `htlc_resolution` will be moving to dynamic fees,
so deprecate those.
Note that "penalty" is still used for generating penalty txs for
watchtowers, and "unilateral_close" still used until we get zero-fee
anchors.
Changelog-Added: JSON-RPC: `feerates` `estimates` array shows fee estimates by blockcount from underlying plugin (usually *bcli*).
Changelog-Changed: JSON-RPC: `close`, `fundchannel`, `fundpsbt`, `multifundchannel`, `multiwithdraw`, `txprepare`, `upgradewallet`, `withdraw` `feerate` (`feerange` for `close`) value *slow* is now 100 block-estimate, not half of 100-block estimate.
Changelog-Deprecated: JSON-RPC: `close`, `fundchannel`, `fundpsbt`, `multifundchannel`, `multiwithdraw`, `txprepare`, `upgradewallet`, `withdraw` `feerate` (`feerange` for `close`) expressed as, "delayed_to_us", "htlc_resolution", "max_acceptable" or "min_acceptable". Use explicit block counts or *slow*/*normal*/*urgent*/*minimum*.
Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2023-04-07 05:43:39 +01:00
- **estimates** (array of objects): Feerate estimates from plugin which we are using (usuallly bcli) *(added v23.05)* :
- **blockcount** (u32): The number of blocks the feerate is expected to get a transaction in *(added v23.05)*
- **feerate** (u32): The feerate for this estimate, in given *style* *(added v23.05)*
- **smoothed\_feerate** (u32): The feerate, smoothed over time (useful for coordinating with other nodes) *(added v23.05)*
doc/schemas: disableoffer, disconnect, feerates, fetchinvoice, fundchannel, fundchannel_cancel, fundchannel_complete, fundchannel_start, fundpsbt, getinfo, getlog, getroute.
We also add a test for getlog, since it was never called by the
testsuite.
Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2021-05-26 08:35:01 +01:00
- **opening** (u32, optional): Default feerate for lightning-fundchannel(7) and lightning-withdraw(7)
2022-09-05 22:45:06 +01:00
- **mutual\_close** (u32, optional): Feerate to aim for in cooperative shutdown. 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.
2022-11-11 02:03:13 +00:00
- **unilateral\_close** (u32, optional): Feerate for commitment\_transaction in a live channel which we originally funded
lightningd: clean up feerate handling, deprecate old terms.
Drop try_get_feerate() in favor of explicit feerate_for_deadline() and
smoothed_feerate_for_deadline().
This shows us everywhere we deal with old-style feerates by names.
`delayed_to_us` and `htlc_resolution` will be moving to dynamic fees,
so deprecate those.
Note that "penalty" is still used for generating penalty txs for
watchtowers, and "unilateral_close" still used until we get zero-fee
anchors.
Changelog-Added: JSON-RPC: `feerates` `estimates` array shows fee estimates by blockcount from underlying plugin (usually *bcli*).
Changelog-Changed: JSON-RPC: `close`, `fundchannel`, `fundpsbt`, `multifundchannel`, `multiwithdraw`, `txprepare`, `upgradewallet`, `withdraw` `feerate` (`feerange` for `close`) value *slow* is now 100 block-estimate, not half of 100-block estimate.
Changelog-Deprecated: JSON-RPC: `close`, `fundchannel`, `fundpsbt`, `multifundchannel`, `multiwithdraw`, `txprepare`, `upgradewallet`, `withdraw` `feerate` (`feerange` for `close`) expressed as, "delayed_to_us", "htlc_resolution", "max_acceptable" or "min_acceptable". Use explicit block counts or *slow*/*normal*/*urgent*/*minimum*.
Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2023-04-07 05:43:39 +01:00
- **delayed\_to\_us** (u32, optional): Feerate for returning unilateral close funds to our wallet **deprecated, removal in v24.02**
- **htlc\_resolution** (u32, optional): Feerate for returning unilateral close HTLC outputs to our wallet **deprecated, removal in v24.02**
- **penalty** (u32, optional): Feerate to use when creating penalty tx for watchtowers
doc/schemas: disableoffer, disconnect, feerates, fetchinvoice, fundchannel, fundchannel_cancel, fundchannel_complete, fundchannel_start, fundpsbt, getinfo, getlog, getroute.
We also add a test for getlog, since it was never called by the
testsuite.
Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2021-05-26 08:35:01 +01:00
- **perkw** (object, optional): If *style* parameter was perkw:
2022-09-05 22:45:06 +01:00
- **min\_acceptable** (u32): The smallest feerate that you can use, usually the minimum relayed feerate of the backend
- **max\_acceptable** (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).
2023-04-07 05:53:49 +01:00
- **floor** (u32): The smallest feerate that our backend tells us it will accept (i.e. minrelayfee or mempoolminfee) *(added v23.05)*
lightningd: clean up feerate handling, deprecate old terms.
Drop try_get_feerate() in favor of explicit feerate_for_deadline() and
smoothed_feerate_for_deadline().
This shows us everywhere we deal with old-style feerates by names.
`delayed_to_us` and `htlc_resolution` will be moving to dynamic fees,
so deprecate those.
Note that "penalty" is still used for generating penalty txs for
watchtowers, and "unilateral_close" still used until we get zero-fee
anchors.
Changelog-Added: JSON-RPC: `feerates` `estimates` array shows fee estimates by blockcount from underlying plugin (usually *bcli*).
Changelog-Changed: JSON-RPC: `close`, `fundchannel`, `fundpsbt`, `multifundchannel`, `multiwithdraw`, `txprepare`, `upgradewallet`, `withdraw` `feerate` (`feerange` for `close`) value *slow* is now 100 block-estimate, not half of 100-block estimate.
Changelog-Deprecated: JSON-RPC: `close`, `fundchannel`, `fundpsbt`, `multifundchannel`, `multiwithdraw`, `txprepare`, `upgradewallet`, `withdraw` `feerate` (`feerange` for `close`) expressed as, "delayed_to_us", "htlc_resolution", "max_acceptable" or "min_acceptable". Use explicit block counts or *slow*/*normal*/*urgent*/*minimum*.
Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2023-04-07 05:43:39 +01:00
- **estimates** (array of objects): Feerate estimates from plugin which we are using (usuallly bcli) *(added v23.05)* :
- **blockcount** (u32): The number of blocks the feerate is expected to get a transaction in *(added v23.05)*
- **feerate** (u32): The feerate for this estimate, in given *style* *(added v23.05)*
- **smoothed\_feerate** (u32): The feerate, smoothed over time (useful for coordinating with other nodes) *(added v23.05)*
doc/schemas: disableoffer, disconnect, feerates, fetchinvoice, fundchannel, fundchannel_cancel, fundchannel_complete, fundchannel_start, fundpsbt, getinfo, getlog, getroute.
We also add a test for getlog, since it was never called by the
testsuite.
Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2021-05-26 08:35:01 +01:00
- **opening** (u32, optional): Default feerate for lightning-fundchannel(7) and lightning-withdraw(7)
2022-09-05 22:45:06 +01:00
- **mutual\_close** (u32, optional): Feerate to aim for in cooperative shutdown. 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.
2022-11-11 02:03:13 +00:00
- **unilateral\_close** (u32, optional): Feerate for commitment\_transaction in a live channel which we originally funded
lightningd: clean up feerate handling, deprecate old terms.
Drop try_get_feerate() in favor of explicit feerate_for_deadline() and
smoothed_feerate_for_deadline().
This shows us everywhere we deal with old-style feerates by names.
`delayed_to_us` and `htlc_resolution` will be moving to dynamic fees,
so deprecate those.
Note that "penalty" is still used for generating penalty txs for
watchtowers, and "unilateral_close" still used until we get zero-fee
anchors.
Changelog-Added: JSON-RPC: `feerates` `estimates` array shows fee estimates by blockcount from underlying plugin (usually *bcli*).
Changelog-Changed: JSON-RPC: `close`, `fundchannel`, `fundpsbt`, `multifundchannel`, `multiwithdraw`, `txprepare`, `upgradewallet`, `withdraw` `feerate` (`feerange` for `close`) value *slow* is now 100 block-estimate, not half of 100-block estimate.
Changelog-Deprecated: JSON-RPC: `close`, `fundchannel`, `fundpsbt`, `multifundchannel`, `multiwithdraw`, `txprepare`, `upgradewallet`, `withdraw` `feerate` (`feerange` for `close`) expressed as, "delayed_to_us", "htlc_resolution", "max_acceptable" or "min_acceptable". Use explicit block counts or *slow*/*normal*/*urgent*/*minimum*.
Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2023-04-07 05:43:39 +01:00
- **delayed\_to\_us** (u32, optional): Feerate for returning unilateral close funds to our wallet **deprecated, removal in v24.02**
- **htlc\_resolution** (u32, optional): Feerate for returning unilateral close HTLC outputs to our wallet **deprecated, removal in v24.02**
- **penalty** (u32, optional): Feerate to use when creating penalty tx for watchtowers
2022-09-05 22:45:06 +01:00
- **onchain\_fee\_estimates** (object, optional):
- **opening\_channel\_satoshis** (u64): Estimated cost of typical channel open
- **mutual\_close\_satoshis** (u64): Estimated cost of typical channel close
lightningd: clean up feerate handling, deprecate old terms.
Drop try_get_feerate() in favor of explicit feerate_for_deadline() and
smoothed_feerate_for_deadline().
This shows us everywhere we deal with old-style feerates by names.
`delayed_to_us` and `htlc_resolution` will be moving to dynamic fees,
so deprecate those.
Note that "penalty" is still used for generating penalty txs for
watchtowers, and "unilateral_close" still used until we get zero-fee
anchors.
Changelog-Added: JSON-RPC: `feerates` `estimates` array shows fee estimates by blockcount from underlying plugin (usually *bcli*).
Changelog-Changed: JSON-RPC: `close`, `fundchannel`, `fundpsbt`, `multifundchannel`, `multiwithdraw`, `txprepare`, `upgradewallet`, `withdraw` `feerate` (`feerange` for `close`) value *slow* is now 100 block-estimate, not half of 100-block estimate.
Changelog-Deprecated: JSON-RPC: `close`, `fundchannel`, `fundpsbt`, `multifundchannel`, `multiwithdraw`, `txprepare`, `upgradewallet`, `withdraw` `feerate` (`feerange` for `close`) expressed as, "delayed_to_us", "htlc_resolution", "max_acceptable" or "min_acceptable". Use explicit block counts or *slow*/*normal*/*urgent*/*minimum*.
Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2023-04-07 05:43:39 +01:00
- **unilateral\_close\_satoshis** (u64): Estimated cost of typical (non-anchor) unilateral close (without HTLCs)
2023-06-26 00:02:21 +01:00
- **htlc\_timeout\_satoshis** (u64): Estimated cost of typical HTLC timeout transaction (non-anchors)
- **htlc\_success\_satoshis** (u64): Estimated cost of typical HTLC fulfillment transaction (non-anchors)
doc/schemas: disableoffer, disconnect, feerates, fetchinvoice, fundchannel, fundchannel_cancel, fundchannel_complete, fundchannel_start, fundpsbt, getinfo, getlog, getroute.
We also add a test for getlog, since it was never called by the
testsuite.
Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2021-05-26 08:35:01 +01:00
The following warnings may also be returned:
2022-09-05 22:33:09 +01:00
2022-09-05 22:45:06 +01:00
- **warning\_missing\_feerates**: Some fee estimates are missing
2021-09-03 11:07:59 +01:00
doc/schemas: disableoffer, disconnect, feerates, fetchinvoice, fundchannel, fundchannel_cancel, fundchannel_complete, fundchannel_start, fundpsbt, getinfo, getlog, getroute.
We also add a test for getlog, since it was never called by the
testsuite.
Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2021-05-26 08:35:01 +01:00
[comment]: # (GENERATE-FROM-SCHEMA-END)
2020-07-12 04:30:35 +01:00
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
-----
2023-04-07 05:43:45 +01:00
Many other commands have a *feerate* parameter. This can be:
* One of the strings to use lightningd's internal estimates:
2023-04-11 05:04:57 +01:00
* *urgent* (next 6 blocks or so)
* *normal* (next 12 blocks or so)
2023-04-07 05:43:45 +01:00
* *slow* (next 100 blocks or so)
* *minimum* for the lowest value bitcoind will currently accept (added in v23.05)
* A number, with an optional suffix:
* *blocks* means aim for confirmation in that many blocks (added in v23.05)
* *perkw* means the number is interpreted as satoshi-per-kilosipa (weight)
* *perkb* means it is interpreted bitcoind-style as satoshi-per-kilobyte.
Omitting the suffix is equivalent to *perkb* .
2020-07-12 04:30:35 +01:00
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
------
2021-06-29 15:34:20 +01:00
ZmnSCPxj < < ZmnSCPxj @ protonmail . com > > wrote the initial version of this
2020-07-12 04:30:35 +01:00
manpage.
SEE ALSO
--------
2021-06-23 20:31:47 +01:00
lightning-parsefeerate(7), lightning-fundchannel(7), lightning-withdraw(7),
2022-11-11 01:44:56 +00:00
lightning-txprepare(7), lightning-fundchannel\_start(7).
2020-07-12 04:30:35 +01:00
RESOURCES
---------
Main web site: < https: / / github . com / ElementsProject / lightning >
2020-08-25 02:33:16 +01:00
2023-06-26 00:02:21 +01:00
[comment]: # ( SHA256STAMP:195f8f4cc16197a62269ca1cda77e9d8788ff0c0c49a9d9d45067f6a578c22fd)
