Add details for post-anchor dust_limit_satoshis

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).
 

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: