From a1ed156b19facc1738767db41e67e5f8cd02217d Mon Sep 17 00:00:00 2001 From: t-bast Date: Wed, 19 Nov 2025 13:49:38 +0100 Subject: [PATCH 1/2] Add details for post-anchor `dust_limit_satoshis` Since the introduction of `option_anchors`, pre-signed HTLC transactions don't include any fees, and thus don't contribute to trimming. This results in HTLC outputs in the commitment transactions that may be forever uneconomical to spend, and will pollute the utxo set. We should use a `dust_limit_satoshis` that is higher than Bitcoin Core's standard values to take into account the cost of these second-stage txs at a reasonable (TM) feerate. --- 02-peer-protocol.md | 8 ++++++-- 03-transactions.md | 24 +++++++++++++++++++----- 2 files changed, 25 insertions(+), 7 deletions(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 7feb2146c..b15a079f0 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -781,6 +781,7 @@ The sending node SHOULD: - set `to_self_delay` sufficient to ensure the sender can irreversibly spend a commitment transaction output, in case of misbehavior by the receiver. - set `feerate_per_kw` to at least the rate it estimates would cause the transaction to be immediately included in a block. - set `dust_limit_satoshis` to a sufficient value to allow commitment transactions to propagate through the Bitcoin network. + - set `dust_limit_satoshis` to a sufficient value to allow HTLC transactions to propagate through the Bitcoin network. - set `htlc_minimum_msat` to the minimum value HTLC it's willing to accept from this peer. The receiving node MUST: @@ -801,7 +802,7 @@ The receiving node MAY fail the channel if: - it considers `max_htlc_value_in_flight_msat` too small. - it considers `channel_reserve_satoshis` too large. - it considers `max_accepted_htlcs` too small. - - it considers `dust_limit_satoshis` too large. + - it considers `dust_limit_satoshis` too large (see [BOLT 3](03-transactions.md#dust-limits)). The receiving node MUST fail the channel if: - the `chain_hash` value is set to a hash of a chain that is unknown to the receiver. @@ -842,7 +843,10 @@ are above both `dust_limit_satoshis`. The receiver should not accept large `dust_limit_satoshis`, as this could be used in griefing attacks, where the peer publishes its commitment with a lot -of dust htlcs, which effectively become miner fees. +of dust htlcs, which effectively become miner fees. But it must allow values +higher than the standard Bitcoin Core dust limits, since HTLC outputs need to +be spent by a second-stage transaction at a feerate matching the current +on-chain feerate. Details for how to handle a channel failure can be found in [BOLT 5:Failing a Channel](05-onchain.md#failing-a-channel). diff --git a/03-transactions.md b/03-transactions.md index bda4830f8..760ab51e4 100644 --- a/03-transactions.md +++ b/03-transactions.md @@ -281,11 +281,15 @@ To redeem the HTLC, the HTLC-success transaction is used as detailed below. This ### Trimmed Outputs Each peer specifies a `dust_limit_satoshis` below which outputs should -not be produced; these outputs that are not produced are termed "trimmed". A trimmed output is -considered too small to be worth creating and is instead added -to the commitment transaction fee. For HTLCs, it needs to be taken into -account that the second-stage HTLC transaction may also be below the -limit. +not be produced; these outputs that are not produced are termed "trimmed". +A trimmed output is considered too small to be worth creating: it is instead +either added to the commitment transaction fee. + +For HTLCs, it needs to be taken into account that the second-stage HTLC +transaction may also be below the limit. Note that when using `option_anchors`, +HTLC transactions don't include a fee and thus don't contribute to trimming: +setting a higher `dust_limit_satoshis` makes sense for those channels to ensure +that outputs are economical to spend. #### Requirements @@ -551,6 +555,7 @@ Bitcoin Core defines the following dust thresholds: - pay to script hash (p2sh): 540 satoshis - pay to witness pubkey hash (p2wpkh): 294 satoshis - pay to witness script hash (p2wsh): 330 satoshis +- pay to anchor (p2a): 240 satoshis - unknown segwit versions: 354 satoshis - `OP_RETURN` outputs: these are never dust @@ -560,6 +565,15 @@ is explained in the following sections. In all these sections, the calculations are done with a feerate of 3000 sat/kB as per Bitcoin Core's implementation. +Note that since the introduction of `option_anchors`, the second-stage HTLC +transaction's weight is not taken into account when deciding whether outputs +should be included in the commitment transaction or not. It thus makes sense +to use a `dust_limit_satoshis` that takes into account the cost of those +second-stage HTLC transactions, to ensure that outputs added to the commitment +transaction can actually be claimed on-chain, otherwise they may pollute the +utxo set indefinitely. At a minimum, nodes should allow their peer to use a +`dust_limit_satoshis` that is higher than the values defined by Bitcoin Core. + ### Pay to pubkey hash (p2pkh) A p2pkh output is 34 bytes: From 68c6544f38bd32d7ea56c4b3634294232b7a72d9 Mon Sep 17 00:00:00 2001 From: t-bast Date: Tue, 16 Dec 2025 09:46:24 +0100 Subject: [PATCH 2/2] Explain that this isn't a perfect solution As requested by @ziggie1984 --- 03-transactions.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/03-transactions.md b/03-transactions.md index 760ab51e4..bbaafbb63 100644 --- a/03-transactions.md +++ b/03-transactions.md @@ -573,6 +573,11 @@ second-stage HTLC transactions, to ensure that outputs added to the commitment transaction can actually be claimed on-chain, otherwise they may pollute the utxo set indefinitely. At a minimum, nodes should allow their peer to use a `dust_limit_satoshis` that is higher than the values defined by Bitcoin Core. +We cannot predict future feerates, so this will not always work and can still +result in HTLC outputs that are unspendable if the on-chain fees are too high. +We cannot use very large `dust_limit_satoshis` values either since it would +create too much dust exposure in the commitment transaction (more details +[here](/02-peer-protocol.md#bounding-exposure-to-trimmed-in-flight-htlcs-max_dust_htlc_exposure_msat)). ### Pay to pubkey hash (p2pkh)