X-Git-Url: http://git.bitcoin.ninja/index.cgi?a=blobdiff_plain;f=lightning%2Fsrc%2Fchain%2Fchaininterface.rs;h=1f42dc2fe4251a26be3c7b659bae89505893b6e3;hb=refs%2Fheads%2F2024-04-log-in-flights;hp=6073ed61aaf0cc88beea1c899b687fbb407fbc93;hpb=baf9731a21f695baf1e5fe562b9484f5f56f99e6;p=rust-lightning diff --git a/lightning/src/chain/chaininterface.rs b/lightning/src/chain/chaininterface.rs index 6073ed61..1f42dc2f 100644 --- a/lightning/src/chain/chaininterface.rs +++ b/lightning/src/chain/chaininterface.rs @@ -40,7 +40,7 @@ pub trait BroadcasterInterface { /// be sure to manage both cases correctly. /// /// Bitcoin transaction packages are defined in BIP 331 and here: - /// https://github.com/bitcoin/bitcoin/blob/master/doc/policy/packages.md + /// fn broadcast_transactions(&self, txs: &[&Transaction]); } @@ -48,26 +48,91 @@ pub trait BroadcasterInterface { /// estimation. #[derive(Clone, Copy, Debug, Hash, PartialEq, Eq)] pub enum ConfirmationTarget { - /// We'd like a transaction to confirm in the future, but don't want to commit most of the fees - /// required to do so yet. The remaining fees will come via a Child-Pays-For-Parent (CPFP) fee - /// bump of the transaction. - /// - /// The feerate returned should be the absolute minimum feerate required to enter most node - /// mempools across the network. Note that if you are not able to obtain this feerate estimate, - /// you should likely use the furthest-out estimate allowed by your fee estimator. - MempoolMinimum, - /// We are happy with a transaction confirming slowly, at least within a day or so worth of - /// blocks. - Background, - /// We'd like a transaction to confirm without major delayed, i.e., within the next 12-24 blocks. - Normal, - /// We'd like a transaction to confirm in the next few blocks. - HighPriority, + /// We have some funds available on chain which we need to spend prior to some expiry time at + /// which point our counterparty may be able to steal them. Generally we have in the high tens + /// to low hundreds of blocks to get our transaction on-chain, but we shouldn't risk too low a + /// fee - this should be a relatively high priority feerate. + OnChainSweep, + /// This is the lowest feerate we will allow our channel counterparty to have in an anchor + /// channel in order to close the channel if a channel party goes away. + /// + /// This needs to be sufficient to get into the mempool when the channel needs to + /// be force-closed. Setting too high may result in force-closures if our counterparty attempts + /// to use a lower feerate. Because this is for anchor channels, we can always bump the feerate + /// later; the feerate here only needs to be sufficient to enter the mempool. + /// + /// A good estimate is the expected mempool minimum at the time of force-closure. Obviously this + /// is not an estimate which is very easy to calculate because we do not know the future. Using + /// a simple long-term fee estimate or tracking of the mempool minimum is a good approach to + /// ensure you can always close the channel. A future change to Bitcoin's P2P network + /// (package relay) may obviate the need for this entirely. + MinAllowedAnchorChannelRemoteFee, + /// The lowest feerate we will allow our channel counterparty to have in a non-anchor channel. + /// + /// This is the feerate on the transaction which we (or our counterparty) will broadcast in + /// order to close the channel if a channel party goes away. Setting this value too high will + /// cause immediate force-closures in order to avoid having an unbroadcastable state. + /// + /// This feerate represents the fee we pick now, which must be sufficient to enter a block at an + /// arbitrary time in the future. Obviously this is not an estimate which is very easy to + /// calculate. This can leave channels subject to being unable to close if feerates rise, and in + /// general you should prefer anchor channels to ensure you can increase the feerate when the + /// transactions need broadcasting. + /// + /// Do note some fee estimators round up to the next full sat/vbyte (ie 250 sats per kw), + /// causing occasional issues with feerate disagreements between an initiator that wants a + /// feerate of 1.1 sat/vbyte and a receiver that wants 1.1 rounded up to 2. If your fee + /// estimator rounds subtracting 250 to your desired feerate here can help avoid this issue. + /// + /// [`ChannelConfig::max_dust_htlc_exposure`]: crate::util::config::ChannelConfig::max_dust_htlc_exposure + MinAllowedNonAnchorChannelRemoteFee, + /// This is the feerate on the transaction which we (or our counterparty) will broadcast in + /// order to close the channel if a channel party goes away. + /// + /// This needs to be sufficient to get into the mempool when the channel needs to + /// be force-closed. Setting too low may result in force-closures. Because this is for anchor + /// channels, it can be a low value as we can always bump the feerate later. + /// + /// A good estimate is the expected mempool minimum at the time of force-closure. Obviously this + /// is not an estimate which is very easy to calculate because we do not know the future. Using + /// a simple long-term fee estimate or tracking of the mempool minimum is a good approach to + /// ensure you can always close the channel. A future change to Bitcoin's P2P network + /// (package relay) may obviate the need for this entirely. + AnchorChannelFee, + /// Lightning is built around the ability to broadcast a transaction in the future to close our + /// channel and claim all pending funds. In order to do so, non-anchor channels are built with + /// transactions which we need to be able to broadcast at some point in the future. + /// + /// This feerate represents the fee we pick now, which must be sufficient to enter a block at an + /// arbitrary time in the future. Obviously this is not an estimate which is very easy to + /// calculate, so most lightning nodes use some relatively high-priority feerate using the + /// current mempool. This leaves channels subject to being unable to close if feerates rise, and + /// in general you should prefer anchor channels to ensure you can increase the feerate when the + /// transactions need broadcasting. + /// + /// Since this should represent the feerate of a channel close that does not need fee + /// bumping, this is also used as an upper bound for our attempted feerate when doing cooperative + /// closure of any channel. + NonAnchorChannelFee, + /// When cooperatively closing a channel, this is the minimum feerate we will accept. + /// Recommended at least within a day or so worth of blocks. + /// + /// This will also be used when initiating a cooperative close of a channel. When closing a + /// channel you can override this fee by using + /// [`ChannelManager::close_channel_with_feerate_and_script`]. + /// + /// [`ChannelManager::close_channel_with_feerate_and_script`]: crate::ln::channelmanager::ChannelManager::close_channel_with_feerate_and_script + ChannelCloseMinimum, } /// A trait which should be implemented to provide feerate information on a number of time /// horizons. /// +/// If access to a local mempool is not feasible, feerate estimates should be fetched from a set of +/// third-parties hosting them. Note that this enables them to affect the propagation of your +/// pre-signed transactions at any time and therefore endangers the safety of channels funds. It +/// should be considered carefully as a deployment. +/// /// Note that all of the functions implemented here *must* be reentrant-safe (obviously - they're /// called from inside the library in response to chain events, P2P events, or timer events). pub trait FeeEstimator { @@ -130,7 +195,7 @@ mod tests { let test_fee_estimator = &TestFeeEstimator { sat_per_kw }; let fee_estimator = LowerBoundedFeeEstimator::new(test_fee_estimator); - assert_eq!(fee_estimator.bounded_sat_per_1000_weight(ConfirmationTarget::Background), FEERATE_FLOOR_SATS_PER_KW); + assert_eq!(fee_estimator.bounded_sat_per_1000_weight(ConfirmationTarget::AnchorChannelFee), FEERATE_FLOOR_SATS_PER_KW); } #[test] @@ -139,6 +204,6 @@ mod tests { let test_fee_estimator = &TestFeeEstimator { sat_per_kw }; let fee_estimator = LowerBoundedFeeEstimator::new(test_fee_estimator); - assert_eq!(fee_estimator.bounded_sat_per_1000_weight(ConfirmationTarget::Background), sat_per_kw); + assert_eq!(fee_estimator.bounded_sat_per_1000_weight(ConfirmationTarget::AnchorChannelFee), sat_per_kw); } }