Skip to content

Add fee-bumping reserves recommendations for anchor channels #2450

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from
Closed

Add fee-bumping reserves recommendations for anchor channels #2450

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 52 additions & 0 deletions lightning/src/events/bump_transaction.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,58 @@
//!
//! [`Event`]: crate::events::Event

//! LDK offers the ability to its users to open Lightning [anchor-output](https://bitcoinops.org/en/topics/anchor-outputs/)
//! channels (`option_anchors_zero_fee_htlc_tx`) with its counterparties.
//!
//! Anchor output channels are requiring from the user the provisioning and maintenance of fee-bumping reserves to accommodate
//! fee rate increase to the commitment (via a Child-Pay-For-Parent) or the second-stage HTLC transactions (via Replace-by-Fee).
//! 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 as a pending HTLC is detected. A LDK user can implement management of fee-bumping reserves through the
//! [`CoinSelectionSource`] and [`WalletSource`] traits.
//!
//! The total value of the fee-bumping reserve must be high enough to ensure channel transactions are confirmed
//! in a timely fashion, even in the face of full mempool and high fee rates. Transactions might have a dynamic
//! weight due to carrying HTLCs.
//!
//! A _predictive_ worst-case `feerate_per_kw` based on historically observed network mempools congestion must be selected.
//! I.e the prediction has to include an additional safety margin. A factor of 2 is a conservative estimation.
//!
//! The user is always involved in any decision to open an anchor channel and in the context of fee-bumping reserves
//! management the user should track them as `current_opened_channels` (the outcome of `ChannelManager::list_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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Similarly here, I'm not sure I understand how the user should act on this advise.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The aim of this documentation is to give the heuristics to the user to understand the amount in satoshis of fee-bumping reserves one should keep, assuming conservative risk exposure (e.g the “A factor of 2 is a conservative estimation”).

This section explains the details of the factors entering in the computation of the max number of pending HTLCs (inbound / outbound) that a channel can have, under default LDK settings.

Note, high-level helpers could be built from the level ones we have currently (get_inbound_pending_htlcs_stats() / get_outbound_pending_htlc_stats()).

//! `max_htlc_allsides`. As of 0.0.116 release, LDK has a BOLT3's `max_accepted_htlcs` of 50 (`DEFAULT_MAX_HTLCS`)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

max_htlc_allsides does not exist in this repo, what is it referring to?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See comment just above. In this context, this is used a convenience to yield the level of fee-bumping reserve that a LDK user is recommended to maintain. Specific helpers to compute it could be introduced.

//! 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).
Comment on lines +37 to +39
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The counterparty can also limit us so the 483 is actually dynamic per channel as well.

//!
//! 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. Those recommendations
//! should be also revised in function of interactions with transaction standardness policy and its evolutions (e.g number
//! of transactions allowed to be relayed as a package and as such how many LN commitment one CPFP can cover).

use alloc::collections::BTreeMap;
use core::ops::Deref;

Expand Down
1 change: 1 addition & 0 deletions lightning/src/util/config.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`].
///
/// Note that if you wish accept inbound channels with anchor outputs, you must enable
/// [`UserConfig::manually_accept_inbound_channels`] and manually accept them with
Expand Down