Add fee-bumping reserves recommendation

Author: Antoine Riard

doc/fee-bumping-reserves.md

@@ -0,0 +1,43 @@
+# Fee-Bumping Reserves Recommendations for Anchor Outputs Channels
+
+The Lightning Dev Kit 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, 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 "warm" host. A LDK user can implement management of fee-bumping reserves through the `CoinSelectionSource` and `WalletSource` traits.
+
+The accumulated satoshis value of the collection of the UTXOs must be maintained to cover sufficient transaction weight surface 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 assume Taproot channel type usage, where the weight of the channel transactions weight are modified due to P2TR scriptpubkeys and corresponding
+witness spends.

lightning/src/events/bump_transaction.rs

@@ -438,6 +438,9 @@ pub struct CoinSelection {
 /// sign for them. The coin selection method aims to mimic Bitcoin Core's `fundrawtransaction` RPC,
 /// which most wallets should be able to satisfy. Otherwise, consider implementing [`WalletSource`],
 /// which can provide a default implementation of this trait when used with [`Wallet`].
+///
+/// The set of UTXOs might represent a level of amount reserves according to the recommendations in
+/// `doc/fee-bumping-reserves.md`.
 pub trait CoinSelectionSource {
 	/// Performs coin selection of a set of UTXOs, with at least 1 confirmation each, that are
 	/// available to spend. Implementations are free to pick their coin selection algorithm of

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 `doc/fee-bumping-reserves.md`.
 	///
 	/// Note that if you wish accept inbound channels with anchor outputs, you must enable
 	/// [`UserConfig::manually_accept_inbound_channels`] and manually accept them with