diff --git a/02-peer-protocol.md b/02-peer-protocol.md index f61bd3cca..4d057e682 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -797,6 +797,52 @@ A fulfilling node: transaction, AND is past this fulfillment deadline: - MUST fail the channel. +### Bounding exposure to trimmed in-flight HTLCs: `max_dust_htlc_exposure_msat` + +When an HTLC in a channel is below the "trimmed" threshold in [BOLT3 #3](03-transactions.md), +the HTLC cannot be claimed on-chain, instead being turned into additional miner +fees if either party unilaterally closes the channel. Because the threshold is +per-HTLC, the total exposure to such HTLCs may be substantial if there are many +dust HTLCs committed when the channel is force-closed. + +This can be exploited in griefing attacks or even in miner-extractable-value attacks, +if the malicious entity wins [mining capabilities](https://lists.linuxfoundation.org/pipermail/lightning-dev/2020-May/002714.html). + +The total exposure is given by the following back-of-the-envelope computation: + + remote `max_accepted_htlcs` * (`HTLC-success-kiloweight` * `feerate_per_kw` + remote `dust_limit_satoshis`) + + local `max_accepted_htlcs` * (`HTLC-timeout-kiloweight` * `feerate_per_kw` + remote `dust_limit_satoshis`) + +To mitigate this scenario, a `max_dust_htlc_exposure_msat` threshold can be +applied when sending, forwarding and receiving HTLCs. + +A node: + - when receiving an HTLC: + - if the HTLC's `amount_msat` is smaller than the remote `dust_limit_satoshis` plus the HTLC-timeout fee at `feerate_per_kw`: + - if the `amount_msat` plus the dust balance of the remote transaction is greater than `max_dust_htlc_exposure_msat`: + - SHOULD fail this HTLC once it's committed + - SHOULD NOT reveal a preimage for this HTLC + - if the HTLC's `amount_msat` is smaller than the local `dust_limit_satoshis` plus the HTLC-success fee at `feerate_per_kw`: + - if the `amount_msat` plus the dust balance of the local transaction is greater than `max_dust_htlc_exposure_msat`: + - SHOULD fail this HTLC once it's committed + - SHOULD NOT reveal a preimage for this HTLC + - when offering an HTLC: + - if the HTLC's `amount_msat` is smaller than the remote `dust_limit_satoshis` plus the HTLC-success fee at `feerate_per_kw`: + - if the `amount_msat` plus the dust balance of the remote transaction is greater than `max_dust_htlc_exposure_msat`: + - SHOULD NOT send this HTLC + - SHOULD fail the corresponding incoming HTLC (if any) + - if the HTLC's `amount_msat` is inferior to the holder's `dust_limit_satoshis` plus the HTLC-timeout fee at the `feerate_per_kw`: + - if the `amount_msat` plus the dust balance of the local transaction is greater than `max_dust_htlc_exposure_msat`: + - SHOULD NOT send this HTLC + - SHOULD fail the corresponding incoming HTLC (if any) + +The `max_dust_htlc_exposure_msat` is an upper bound on the trimmed balance from +dust exposure. The exact value used is a matter of node policy. + +For channels that don't use `option_anchors_zero_fee_htlc_tx`, an increase of +the `feerate_per_kw` may trim multiple htlcs from commitment transactions, +which could create a large increase in dust exposure. + ### Adding an HTLC: `update_add_htlc` Either node can send `update_add_htlc` to offer an HTLC to the other, @@ -1118,6 +1164,16 @@ The node _responsible_ for paying the Bitcoin fee: The node _not responsible_ for paying the Bitcoin fee: - MUST NOT send `update_fee`. +A sending node: + - if `option_anchors_zero_fee_htlc_tx` was not negotiated: + - if the `update_fee` increases `feerate_per_kw`: + - if the dust balance of the remote transaction at the updated `feerate_per_kw` is greater than `max_dust_htlc_exposure_msat`: + - MAY NOT send `update_fee` + - MAY fail the channel + - if the dust balance of the local transaction at the updated `feerate_per_kw` is greater than `max_dust_htlc_exposure_msat`: + - MAY NOT send `update_fee` + - MAY fail the channel + A receiving node: - if the `update_fee` is too low for timely processing, OR is unreasonably large: - SHOULD fail the channel. @@ -1127,6 +1183,12 @@ A receiving node: current commitment transaction: - SHOULD fail the channel, - but MAY delay this check until the `update_fee` is committed. + - if `option_anchors_zero_fee_htlc_tx` was not negotiated: + - if the `update_fee` increases `feerate_per_kw`: + - if the dust balance of the remote transaction at the updated `feerate_per_kw` is greater then `max_dust_htlc_exposure_msat`: + - MAY fail the channel + - if the dust balance of the local transaction at the updated `feerate_per_kw` is greater than `max_dust_htlc_exposure_msat`: + - MAY fail the channel #### Rationale @@ -1150,6 +1212,11 @@ it's simplest to only allow it to set fee levels; however, as the same fee rate applies to HTLC transactions, the receiving node must also care about the reasonableness of the fee. +If on-chain fees increase while commitments contain many HTLCs that will +be trimmed at the updated feerate, this could overflow the configured +`max_dust_htlc_exposure_msat`. Whether to close the channel preemptively +or not is left as a matter of node policy. + ## Message Retransmission Because communication transports are unreliable, and may need to be