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=e923a94bb6d3e7afb5f37376b6de132225821d21;hpb=c86950d5104666b059c4fbe1248afc04610c45c5;p=rust-lightning diff --git a/lightning/src/chain/chaininterface.rs b/lightning/src/chain/chaininterface.rs index e923a94b..1f42dc2f 100644 --- a/lightning/src/chain/chaininterface.rs +++ b/lightning/src/chain/chaininterface.rs @@ -14,30 +14,125 @@ //! disconnections, transaction broadcasting, and feerate information requests. use core::{cmp, ops::Deref}; +use core::convert::TryInto; use bitcoin::blockdata::transaction::Transaction; +// TODO: Define typed abstraction over feerates to handle their conversions. +pub(crate) fn compute_feerate_sat_per_1000_weight(fee_sat: u64, weight: u64) -> u32 { + (fee_sat * 1000 / weight).try_into().unwrap_or(u32::max_value()) +} +pub(crate) const fn fee_for_weight(feerate_sat_per_1000_weight: u32, weight: u64) -> u64 { + ((feerate_sat_per_1000_weight as u64 * weight) + 1000 - 1) / 1000 +} + /// An interface to send a transaction to the Bitcoin network. pub trait BroadcasterInterface { - /// Sends a transaction out to (hopefully) be mined. - fn broadcast_transaction(&self, tx: &Transaction); + /// Sends a list of transactions out to (hopefully) be mined. + /// This only needs to handle the actual broadcasting of transactions, LDK will automatically + /// rebroadcast transactions that haven't made it into a block. + /// + /// In some cases LDK may attempt to broadcast a transaction which double-spends another + /// and this isn't a bug and can be safely ignored. + /// + /// If more than one transaction is given, these transactions should be considered to be a + /// package and broadcast together. Some of the transactions may or may not depend on each other, + /// be sure to manage both cases correctly. + /// + /// Bitcoin transaction packages are defined in BIP 331 and here: + /// + fn broadcast_transactions(&self, txs: &[&Transaction]); } -/// An enum that represents the speed at which we want a transaction to confirm used for feerate +/// An enum that represents the priority at which we want a transaction to confirm used for feerate /// estimation. #[derive(Clone, Copy, Debug, Hash, PartialEq, Eq)] pub enum ConfirmationTarget { - /// We are happy with this transaction confirming slowly when feerate drops some. - Background, - /// We'd like this transaction to confirm without major delay, but 12-18 blocks is fine. - Normal, - /// We'd like this 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 { @@ -100,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] @@ -109,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); } }