Define anchor channel reserve requirements #3487

wvanlint · 2024-12-17T00:09:36Z

This change defines anchor reserve requirements by calculating weights and fees for the transactions that need to be confirmed on-chain in the event of a unilateral closure. The calculation is given a set of parameters as input, including the expected fee rate and number of in-flight HTLCs.

wpaulino

Great work getting this started, this has been a major pain point when enabling anchor outputs.

wpaulino · 2025-01-14T01:00:36Z

lightning/src/util/anchor_channel_reserves.rs

+//   - 72 bytes for the signature
+//   - 1 byte for the public key length
+//   - 33 bytes for the public key
+const P2WPKH_INPUT_WEIGHT: u64 = (36 + 4 + 1) * WITNESS_SCALE_FACTOR as u64 + (1 + 1 + 72 + 1 + 33);


We have this and some of the other estimates around the codebase, it'd be nice to just have one copy of each and reuse them.

Definitely agree, it would be great to unify these across the codebase. They are currently a bit spread out, and some seem to estimate a lower bound, even though they use a 73 byte signature length. Perhaps I can take a look at refactoring this as a separate PR?

wpaulino · 2025-01-14T01:05:58Z

lightning/src/util/anchor_channel_reserves.rs

+	pub expected_accepted_htlcs: u16,
+	/// Whether the wallet providing the anchor channel reserve uses Taproot P2TR outputs for its
+	/// funds, or Segwit P2WPKH outputs otherwise.
+	pub taproot_wallet: bool,


What about wallets that have both output types while they're still migrating to P2TR only?

I modified it so the satisfaction_weights of the Utxos are always taken into account, replacing the weight of one input in the multi-stage transactions. This parameter can then be considered the output type of newly created (change) outputs only.

wpaulino · 2025-01-14T01:35:55Z

lightning/src/util/anchor_channel_reserves.rs

+pub fn get_reserve_per_channel(context: &AnchorChannelReserveContext) -> Amount {
+	let weight = Weight::from_wu(
+		COMMITMENT_TRANSACTION_BASE_WEIGHT +
+		// Reserves are calculated assuming each accepted HTLC is forwarded as the upper bound.


IIUC, the forwarded HTLC will be in a different channel though, so isn't this overestimating by 2x when looking at all channels in aggregate? Perhaps it's better to describe this as accounting for N outbound and N inbound HTLCs per channel?

The math throughout seems correct but the comments are a bit confusing.

Yeah, I think we're describing the same situation: there will be N inbound/accepted HTLCs per channel which will be forwarded to other channels. This will result in N outbound/offered HTLCs per channel in aggregate.

I cleaned up the comments a bit but let me know if there is a better phrasing. I mainly wanted to emphasize the relationship of the parameter with ChannelHandshakeConfig::our_max_accepted_htlcs.

wpaulino · 2025-01-14T01:50:25Z

lightning/src/util/anchor_channel_reserves.rs

+			anchor_channels_with_balance.insert(channel_id);
+		}
+	}
+	// Count channels that are in the middle of negotiation as well.


What about those that have been negotiated but don't have a monitor yet?

Ah you're right. Added accounting for channels in between negotiation and signing as well.

wpaulino · 2025-01-14T01:52:54Z

lightning/src/util/anchor_channel_reserves.rs

+		if channel_monitor.channel_type_features().supports_anchors_zero_fee_htlc_tx()
+			&& !channel_monitor.get_claimable_balances().is_empty()
+		{
+			anchor_channels_with_balance.insert(channel_id);


We should only have one monitor per channel so the hash set seems redundant?

I assumed that with splicing, there would be multiple monitors per channel as the monitors seemed to be stored per OutPoint. Let me know if I'm wrong there though. It might still be useful to resolve channels between ChannelManager and ChannelMonitors now.

morehouse

Concept ACK.

I was just discussing with @TheBlueMatt the need to document best practices for UTXO reserves, and here is a PR that actually calculates some reasonable values. Amazing!

morehouse · 2025-01-15T22:15:08Z

lightning/src/util/anchor_channel_reserves.rs

+	// We require disjoint sets of UTXOs for the reserve of each channel,
+	// as claims are only aggregated per channel currently.
+	//
+	// UTXOs larger than the required reserve are a singleton disjoint set.
+	// A disjoint set of fractional UTXOs could overcontribute by any amount less than the
+	// required reserve, approaching double the reserve.
+	//
+	// Note that for the fractional UTXOs, this is an approximation as we can't efficiently calculate
+	// a worst-case coin selection as an NP-complete problem.
+	num_whole_utxos + total_fractional_amount.to_sat() / reserve_per_channel.to_sat() / 2


This calculation assumes that all HTLCs for each channel are claimed in a single transaction, which is probably reasonable most of the time.

But do note that differing CLTVs currently prevent HTLC claim aggregation and can cause significantly more UTXOs to be needed in the worst case. A malicious counterparty can certainly force this worst case in an effort to exhaust UTXOs and steal funds.

If we assume each HTLC claim takes X blocks to confirm, we would need at least X UTXOs per channel to handle the worst case. Perhaps we should add an expected_tx_confirmation_delay parameter to the context, which indicates how long we expect transactions to be in the mempool before they confirm.

Definitely agree! The CLTV expiries limit the aggregation of HTLC transactions, and the number of UTXOs constrains the concurrency of the claim transactions. Combined with a confirmation time of more than 1 block, this can result in delays in getting everything on-chain.

I actually had this as a parameter during initial calculations, but ended up not including it for a number of reasons:

Probabilistically/hopefully, not all counterparties will be malicious. UTXOs for channels that are not in the process of unilaterally closing can be used.

The ConfirmationTarget::UrgentOnchainSweep fee rate estimate should be set relatively high, although we don't document an expected confirmation time outside of CLTV_CLAIM_BUFFER as an upper bound.

Requiring multiple UTXOs per channel is more expensive for the user as they have to pay a fragmentation cost up-front. I did debate dynamically splitting UTXOs in the anchor output spend transaction when required at some point.

I also wanted to provide a recommendation that was as simple as possible for any users.

What do you think?

Perhaps we can include the parameter in the future when claim transactions can be aggregated across channels. At that point, we only would need X UTXOs in total.

I actually had this as a parameter during initial calculations, but ended up not including it for a number of reasons:

* Probabilistically/hopefully, not all counterparties will be malicious. UTXOs for channels that are not in the process of unilaterally closing can be used. * The `ConfirmationTarget::UrgentOnchainSweep` fee rate estimate should be set relatively high, although we don't document an expected confirmation time outside of [CLTV_CLAIM_BUFFER](https://github.com/lightningdevkit/rust-lightning/blob/86308e19e0f4160d95a3a40767cc8a570765d317/lightning/src/chain/channelmonitor.rs#L233) as an upper bound.

Yeah, UrgentOnchainSweep needs better documentation. Or better yet, we should do #3527.

* Requiring multiple UTXOs per channel is more expensive for the user as they have to pay a fragmentation cost up-front. I did debate dynamically splitting UTXOs in the anchor output spend transaction when required at some point.

If we do that then I think we can end up violating the CPFP carve out, which increases the pinning attack surface.

I also wanted to provide a recommendation that was as simple as possible for any users.

What do you think?

Perhaps we can include the parameter in the future when claim transactions can be aggregated across channels. At that point, we only would need X UTXOs in total.

This seems reasonable, but I think we should at least document these decisions so the user is fully aware.

If we do that then I think we can end up violating the CPFP carve out, which increases the pinning attack surface.

In what way? I believe the only unconfirmed input to the anchor output spend transaction would be the anchor output, as LDK will only select confirmed UTXOs to provide funds for the relevant transactions. We would split larger confirmed UTXOs in the anchor output spend transaction depending on the number of in-flight HTLCs. The split UTXOs can then be used once confirmed, every non-anchor output on the commitment transaction should have a CSV lock anyway.

This seems reasonable, but I think we should at least document these decisions so the user is fully aware.

Added these assumptions in the documentation for get_reserve_per_channel.

at least X UTXOs per channel

I was thinking a bit more about the verification of the UTXO shape here for the future. The algorithm to find the value that can be provided with the required concurrency guarantees is interesting.

If there is a reserve R to get 20 transactions confirmed, and the confirmation time is 5 blocks, there is a variety of ways to provide sufficient UTXOs e.g.:

5 UTXOs of value R / 5

20 UTXOs of value R / 20

Anything in between

But not:

1 UTXO of value R and 5 UTXOs of value R / 20. This can only provide concurrency to get ~6 transactions confirmed without waiting.

It won't be too difficult to verify, but it might be complicated to explain to the users. Or we would just require uniform UTXOs.

codecov · 2025-01-20T23:24:54Z

Codecov Report

Attention: Patch coverage is 73.75566% with 58 lines in your changes missing coverage. Please review.

Project coverage is 88.50%. Comparing base (a91196b) to head (278b847).

Files with missing lines	Patch %	Lines
lightning/src/util/anchor_channel_reserves.rs	75.81%	49 Missing and 3 partials ⚠️
lightning/src/chain/channelmonitor.rs	0.00%	6 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3487      +/-   ##
==========================================
- Coverage   88.55%   88.50%   -0.06%     
==========================================
  Files         149      150       +1     
  Lines      114944   115171     +227     
  Branches   114944   115171     +227     
==========================================
+ Hits       101794   101932     +138     
- Misses      10663    10746      +83     
- Partials     2487     2493       +6

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

morehouse · 2025-01-24T17:49:57Z

lightning/src/util/anchor_channel_reserves.rs

+impl Default for AnchorChannelReserveContext {
+	fn default() -> Self {
+		AnchorChannelReserveContext {
+			upper_bound_fee_rate: FeeRate::from_sat_per_kwu(50 * 250),


Can avoid the manual conversion to sat/kw.

Suggested change

upper_bound_fee_rate: FeeRate::from_sat_per_kwu(50 * 250),

upper_bound_fee_rate: FeeRate::from_sat_per_vb(50).unwrap(),

I mainly wanted to avoid runtime unwrapping in favor of compilation-time verification here.

morehouse · 2025-01-24T18:21:55Z

lightning/src/util/anchor_channel_reserves.rs

+		htlc_success_transaction_weight(context) * (context.expected_accepted_htlcs as u64) +
+		htlc_timeout_transaction_weight(context) * (context.expected_accepted_htlcs as u64),
+	);
+	context.upper_bound_fee_rate.fee_wu(weight).unwrap_or(Amount::MAX)


If overflow actually happens something's not right, and it's going to mess up most of the calculations anyway.

Maybe we should be returning errors throughout instead of silently swallowing them.

Exposed the overflow errors.

morehouse · 2025-01-24T18:44:51Z

lightning/src/util/anchor_channel_reserves.rs

+	let default_satisfaction_fee = context
+		.upper_bound_fee_rate
+		.fee_wu(Weight::from_wu(if context.taproot_wallet {
+			P2TR_INPUT_WEIGHT
+		} else {
+			P2WPKH_INPUT_WEIGHT
+		}))
+		.unwrap_or(Amount::MAX);
+	let reserve_per_channel = get_reserve_per_channel(context) - default_satisfaction_fee;


Maybe we should just remove the default wallet input weight from anchor_output_spend_transaction_weight, so we don't have to subtract it here.

Refactored this to take the weight of the initial inputs as an argument, and made a note that get_reserve_per_channel only includes fees to spend a single UTXO of the default type.

This change defines anchor reserve requirements by calculating weights and fees for the transactions that need to be confirmed on-chain in the event of a unilateral closure. The calculation is given a set of parameters as input, including the expected fee rate and number of in-flight HTLCs.

wvanlint force-pushed the anchor_channel_reserves branch 2 times, most recently from a74fcb8 to 6e59174 Compare December 17, 2024 00:21

wvanlint marked this pull request as ready for review January 6, 2025 19:03

wpaulino self-requested a review January 6, 2025 20:02

wpaulino reviewed Jan 14, 2025

View reviewed changes

morehouse reviewed Jan 15, 2025

View reviewed changes

wvanlint force-pushed the anchor_channel_reserves branch from 6e59174 to da80c28 Compare January 20, 2025 23:16

wvanlint force-pushed the anchor_channel_reserves branch from da80c28 to 21dc5e7 Compare January 21, 2025 01:33

morehouse reviewed Jan 24, 2025

View reviewed changes

wvanlint force-pushed the anchor_channel_reserves branch from 21dc5e7 to a2604f7 Compare February 4, 2025 00:37

wvanlint added 7 commits February 3, 2025 16:52

f Adjust initial spend with actual satisfaction fee

23d6fc3

f Adjust documentation

1f27913

f Account for channels in between negotiating and signing

35c2283

f Expose overflow errors

a658b91

f Extract initial input weight

f31c37c

f Document assumptions to require 1 UTXO per channel

278b847

wvanlint force-pushed the anchor_channel_reserves branch from a2604f7 to 278b847 Compare February 4, 2025 00:55

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Define anchor channel reserve requirements #3487

Define anchor channel reserve requirements #3487

wvanlint commented Dec 17, 2024

wpaulino left a comment

wpaulino Jan 14, 2025

wvanlint Jan 20, 2025

wpaulino Jan 14, 2025

wvanlint Jan 20, 2025 •

edited

Loading

wpaulino Jan 14, 2025

wpaulino Jan 14, 2025

wvanlint Jan 20, 2025 •

edited

Loading

wpaulino Jan 14, 2025

wvanlint Jan 20, 2025

wpaulino Jan 14, 2025

wvanlint Jan 21, 2025 •

edited

Loading

morehouse left a comment

morehouse Jan 15, 2025

wvanlint Jan 21, 2025

morehouse Jan 24, 2025

wvanlint Feb 4, 2025 •

edited

Loading

codecov bot commented Jan 20, 2025 •

edited

Loading

morehouse Jan 24, 2025

wvanlint Feb 4, 2025 •

edited

Loading

morehouse Jan 24, 2025

wvanlint Feb 4, 2025

morehouse Jan 24, 2025

wvanlint Feb 4, 2025 •

edited

Loading

	upper_bound_fee_rate: FeeRate::from_sat_per_kwu(50 * 250),
	upper_bound_fee_rate: FeeRate::from_sat_per_vb(50).unwrap(),

Define anchor channel reserve requirements #3487

Are you sure you want to change the base?

Define anchor channel reserve requirements #3487

Conversation

wvanlint commented Dec 17, 2024

wpaulino left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

wvanlint Jan 20, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

wvanlint Jan 20, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

wvanlint Jan 21, 2025 • edited Loading

Choose a reason for hiding this comment

morehouse left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

wvanlint Feb 4, 2025 • edited Loading

Choose a reason for hiding this comment

codecov bot commented Jan 20, 2025 • edited Loading

Codecov Report

Choose a reason for hiding this comment

wvanlint Feb 4, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

wvanlint Feb 4, 2025 • edited Loading

Choose a reason for hiding this comment

wvanlint Jan 20, 2025 •

edited

Loading

wvanlint Jan 20, 2025 •

edited

Loading

wvanlint Jan 21, 2025 •

edited

Loading

wvanlint Feb 4, 2025 •

edited

Loading

codecov bot commented Jan 20, 2025 •

edited

Loading

wvanlint Feb 4, 2025 •

edited

Loading

wvanlint Feb 4, 2025 •

edited

Loading