Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add a max_dust_htlc_exposure_msat #919

Merged
merged 4 commits into from
Aug 14, 2023
Merged

Add a max_dust_htlc_exposure_msat #919

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
ca94c53
Bound exposure to trimmed in-flight HTLCs
ariard Aug 22, 2021
261a2a0
Reject update_fee beyond max_dust_htlc_exposure_msat
ariard Aug 22, 2021
5fb0b5c
Updates to dust exposure spec
t-bast Oct 10, 2022
7705356
Add context for option_anchors_zero_fee_htlc_tx
ariard Dec 9, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
67 changes: 67 additions & 0 deletions 02-peer-protocol.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 <sup>[mining capabilities](https://lists.linuxfoundation.org/pipermail/lightning-dev/2020-May/002714.html)</sup>.

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:
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

imo this whole section should be moved into the update_add_htlc requirements, as they're actions that are triggered by the receipt of this message.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Noted, I'll update this PR in that sense.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Well, in fact it's not exactly clear that it should be in the update_add_htlc requirements as it's a relay requirement, to me in the same category of cltv_expiry_delta selection. At least was my thinking when I wrote those lines.

Though it can be a source of confusion and maybe we should even add a new BOLT4 message. Due to lack of that, I remember it was hard to assess that max_dust_htlc_exposure_msat was well in-place when I verified fixes against Eclair in a black-box way.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yes but you don't enact these spec requirements until a update_add_htlc message is received.

- 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,
Expand Down Expand Up @@ -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.
Expand All @@ -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

Expand All @@ -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
Expand Down