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..bbaafbb63 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,20 @@ 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. +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) A p2pkh output is 34 bytes: