Add fee-bumping reserves recommendation

Author: Antoine Riard

lightning/src/events/bump_transaction.rs

@@ -11,6 +11,66 @@
 //!
 //! [`Event`]: crate::events::Event
 
+//! LDK offers the ability to its users to open Lightning [anchor outputs](https://bitcoinops.org/en/topics/anchor-outputs/)
+//! channels (`option_anchors_zero_fee_htlc_tx`) with its counterparties.
+//!
+//! Under the Lightning security model, confirmation of commitment and second-stage HTLC transactions
+//! (BOLT3's `HTLC-timeout` and `HTLC-preimage` and the corresponding spends on counterparty commitment
+//! transaction) must be realized in a time-sensitive manner if there are pending HTLCs. Lack of chain
+//! confirmation before HTLC expiration timelocks can constitute a loss of funds, as the counterparty can
+//! claim the HTLC output with a [competing transaction](https://bitcoinops.org/en/blog/waiting-for-confirmation/#policy-as-an-interface).
+//!
+//! Failure of confirmation might be provoked by blockspace demand spikes provoked by unrelated Bitcoin on-chain
+//! transaction issuers. Anchor output enables to remedy to this issue by allowing a Lightning node to dynamically
+//! adjust the feerate of its commitment and second-stage HTLC transactions in an unilateral way.
+//!
+//! However, anchor output channels are requiring from the user the provision and maintenance of fee-bumping
+//! reserves to attach feerate increase to the commitment (via a Child-Pay-For-Parent) or the second-stage HTLC
+//! transactions (via `SIGHASH_SINGLE | SIGHASH_ANYONECANPAY`). Those fee-bumping reserves should be a collection
+//! of UTXOs, of which the state and signing capabilites should be maintained on a "hot" host. A "hot" host is a
+//! computing machine with 24/7 Internet connectivity as fee-bumping UTXOs might need to be signed as soon there is
+//! a pending HTLC. A LDK user can implement management of fee-bumping reserves through the `CoinSelectionSource`
+//! and `WalletSource` traits.
+//!
+//! The total value of the collection of the UTXOs maintained must be high enough to pay for channel transactions
+//! weight at high-level of network mempools feerates.
+//!
+//! A _predictive_ worst-case `feerate_per_kw` based on historical network mempools traffic must be selected.
+//! Predictive worst-case must be understood as the worst-historical network mempools feerate with an additional
+//! safety margin. A factor of 2 is a conservative estimation.
+//!
+//! The number of opened anchor outputs channels must be selected, i.e `current_opened_channels`. As of 0.0.116
+//! release, LDK does not have a max number of opened channels enforced by default.
+//!
+//! The maximum number of HTLC outputs per-commitment transaction on both directions must be selected, i.e
+//! `max_htlc_allsides`.  As of 0.0.116 release, LDK has a BOLT3's `max_accepted_htlcs` of 50 (`DEFAULT_MAX_HTLCS`)
+//! and the value can be adjusted with the config setting `our_max_accepted_htlcs`. There is no LDK mechanism to
+//! limit the number of forward HTLCs (i.e offered HTLC outputs on a commitment transaction). As such `max_htlc_allsides`
+//! is `our_max_accepted_htlcs` + `483` (BOLT3 maximum for outgoing HTLCs).
+//!
+//! Each channel included in the `current_opened_channels` set has a combined transaction weight surface computed in
+//! the following (according to [BOLT3 annex](https://github.com/lightning/bolts/blob/master/03-transactions.md#appendix-a-expected-weights):
+//! - `a`: 900 WU for the base commitment fields with the 4 outputs (`output_paying_to_remote`, `output_paying_to_local`, `output_anchor`, `output_anchor`) present
+//! - `b`: 172 WU * `max_htlc_allsides`
+//! - `c`: 666 WU * `our_max_accepted_htlcs` 
+//! - `d`: 706 WU * 483
+//!
+//! If the Lightning node does not accept HTLC routing (i.e incoming HTLCs), the compomnent `c` can be assigned a 0 value.
+//!
+//! The sum of `a` + `b` + `c` + `d` is called `max_channel_weight_surface`, a worst-case estimation of the transaction
+//! weight surface to fee-bump.
+//!
+//! To obtain the amount in satoshis that must be maintained as fee-bumping reserves, the following equation can be resolved:
+//!
+//!	`current_opened_channel` * `max_channel_weight_surface` * `worst_case_feerate_per_kw` / 1000
+//!
+//! The `worst_case_feerate_per_kw` is a conservative estimation of the level of fee-bumping reserves that must be
+//! maintained. A Lightning node operator may ponder this level of reserves with its subjective timevalue cost of the
+//! immobilized satoshis capital.
+//!
+//! Those fee-bumping reserves recommendations do not assume Taproot channel type usage, where the weight of the channel
+//! transactions weight are modified due to P2TR scriptpubkeys and corresponding witness spends.
+
 use alloc::collections::BTreeMap;
 use core::ops::Deref;
 

lightning/src/util/config.rs

@@ -152,6 +152,7 @@ pub struct ChannelHandshakeConfig {
 	/// If set, we attempt to negotiate the `anchors_zero_fee_htlc_tx`option for all future
 	/// channels. This feature requires having a reserve of onchain funds readily available to bump
 	/// transactions in the event of a channel force close to avoid the possibility of losing funds.
+	/// The level of reserve maintained might follow the recommendations in `bump_transaction.rs`.
 	///
 	/// Note that if you wish accept inbound channels with anchor outputs, you must enable
 	/// [`UserConfig::manually_accept_inbound_channels`] and manually accept them with