From 668c0f8c4c201c6369599f55a343a980b7ff3996 Mon Sep 17 00:00:00 2001 From: t-bast Date: Fri, 16 Feb 2024 12:29:48 +0100 Subject: [PATCH] Add `option_zero_reserve` Lightning channels require nodes to lock some of their channel funds into a channel reserve, which cannot be used for payments made on that channel. This guarantees that both nodes always have an output in the commitment transaction, which they will lose if they publish a revoked commitment. While this requirement is generally useful, it creates inefficiencies since that liquidity can't be used to relay payments, and provides a bad user experience. In some settings, we may want to remove that channel reserve and allow nodes to use all of their channel funds. The `option_zero_reserve` feature lets nodes advertise that they allow their peers to disable the channel reserve on their side, and may lift the same requirement in response. --- 02-peer-protocol.md | 57 ++++++++++++++++++++++++++++++++++----------- 09-features.md | 1 + 2 files changed, 45 insertions(+), 13 deletions(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 59570122b..c43acf0d8 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -797,7 +797,10 @@ The sending node: - MUST set `push_msat` to equal or less than 1000 * `funding_satoshis`. - MUST set `funding_pubkey`, `revocation_basepoint`, `htlc_basepoint`, `payment_basepoint`, and `delayed_payment_basepoint` to valid secp256k1 pubkeys in compressed format. - MUST set `first_per_commitment_point` to the per-commitment point to be used for the initial commitment transaction, derived as specified in [BOLT #3](03-transactions.md#per-commitment-secret-requirements). - - MUST set `channel_reserve_satoshis` greater than or equal to `dust_limit_satoshis`. + - If the receiver supports `option_zero_reserve`: + - MAY set `channel_reserve_satoshis` to `0`. + - Otherwise (`option_zero_reserve` cannot be used): + - MUST set `channel_reserve_satoshis` greater than or equal to `dust_limit_satoshis`. - MUST set undefined bits in `channel_flags` to 0. - if both nodes advertised the `option_upfront_shutdown_script` feature: - MUST include `upfront_shutdown_script` with either a valid `shutdown_scriptpubkey` as required by `shutdown` `scriptpubkey`, or a zero-length `shutdown_scriptpubkey` (ie. `0x0000`). @@ -847,10 +850,10 @@ The receiving node MUST fail the channel if: - it considers `feerate_per_kw` too small for timely processing or unreasonably large. - `funding_pubkey`, `revocation_basepoint`, `htlc_basepoint`, `payment_basepoint`, or `delayed_payment_basepoint` are not valid secp256k1 pubkeys in compressed format. - - `dust_limit_satoshis` is greater than `channel_reserve_satoshis`. + - it doesn't support `option_zero_reserve` and `dust_limit_satoshis` is greater than `channel_reserve_satoshis`. - `dust_limit_satoshis` is smaller than `354 satoshis` (see [BOLT 3](03-transactions.md#dust-limits)). - the funder's amount for the initial commitment transaction is not sufficient for full [fee payment](03-transactions.md#fee-payment). - - both `to_local` and `to_remote` amounts for the initial commitment transaction are less than or equal to `channel_reserve_satoshis` (see [BOLT 3](03-transactions.md#commitment-transaction-outputs)). + - it doesn't support `option_zero_reserve` and both `to_local` and `to_remote` amounts for the initial commitment transaction are less than or equal to `channel_reserve_satoshis` (see [BOLT 3](03-transactions.md#commitment-transaction-outputs)). - `funding_satoshis` is greater than or equal to 2^24 and the receiver does not support `option_support_large_channel`. - the `channel_type` is not suitable. - the `channel_type` includes `option_zeroconf` and it does not trust the sender to open an unconfirmed channel. @@ -874,7 +877,7 @@ The requirement that `channel_reserve_satoshis` is not considered dust according to `dust_limit_satoshis` eliminates cases where all outputs would be eliminated as dust. The similar requirements in `accept_channel` ensure that both sides' `channel_reserve_satoshis` -are above both `dust_limit_satoshis`. +are above both `dust_limit_satoshis`, unless `option_zero_reserve` is used. 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 @@ -928,16 +931,21 @@ The sender: - MUST set `minimum_depth` to zero. - otherwise: - SHOULD set `minimum_depth` to a number of blocks it considers reasonable to avoid double-spending of the funding transaction. - - MUST set `channel_reserve_satoshis` greater than or equal to `dust_limit_satoshis` from the `open_channel` message. - - MUST set `dust_limit_satoshis` less than or equal to `channel_reserve_satoshis` from the `open_channel` message. - - MUST set `channel_type` to the `channel_type` from `open_channel`. + - If the receiver supports `option_zero_reserve` and `channel_reserve_satoshis` from the `open_channel` message is `0`: + - MAY set `channel_reserve_satoshis` to `0`. + - If the receiver supports `option_zero_reserve`: + - MAY set `channel_reserve_satoshis` to `0`. + - Otherwise (`option_zero_reserve` cannot be used): + - MUST set `channel_reserve_satoshis` greater than or equal to `dust_limit_satoshis` from the `open_channel` message. + - MUST set `dust_limit_satoshis` less than or equal to `channel_reserve_satoshis` from the `open_channel` message. + - MUST set `channel_type` to the `channel_type` from `open_channel`. The receiver: - if `minimum_depth` is unreasonably large: - MAY fail the channel. - - if `channel_reserve_satoshis` is less than `dust_limit_satoshis` within the `open_channel` message: + - if `channel_reserve_satoshis` is less than `dust_limit_satoshis` within the `open_channel` message and `option_zero_reserve` is not set: - MUST fail the channel. - - if `channel_reserve_satoshis` from the `open_channel` message is less than `dust_limit_satoshis`: + - if `channel_reserve_satoshis` from the `open_channel` message is less than `dust_limit_satoshis` and `option_zero_reserve` is not set: - MUST fail the channel. - if the message doesn't include a `channel_type`: - MUST fail the channel. @@ -1187,6 +1195,7 @@ This message initiates the v2 channel establishment workflow. 2. data: * [`...*byte`:`type`] 1. type: 2 (`require_confirmed_inputs`) + 1. type: 4 (`disable_channel_reserve`) Rationale and Requirements are the same as for [`open_channel`](#the-open_channel-message), with the following additions. @@ -1202,6 +1211,8 @@ The sending node: - MUST set `funding_feerate_perkw` to the feerate for this transaction - If it requires the receiving node to only use confirmed inputs: - MUST set `require_confirmed_inputs` + - If the receiving node supports `option_zero_reserve`: + - MAY set `disable_channel_reserve`. The receiving node: - MAY fail the negotiation if: @@ -1232,7 +1243,8 @@ Note that `open_channel`'s `channel_reserve_satoshi` has been omitted. Instead, the channel reserve is fixed at 1% of the total channel balance (`open_channel2`.`funding_satoshis` + `accept_channel2`.`funding_satoshis`) rounded down to the nearest whole satoshi or the `dust_limit_satoshis`, -whichever is greater. +whichever is greater, unless `disable_channel_reserve` is set, in which +case there will be no channel reserve on the receiver side. Note that `push_msat` has been omitted. @@ -1276,6 +1288,7 @@ acceptance of the new channel. 2. data: * [`...*byte`:`type`] 1. type: 2 (`require_confirmed_inputs`) + 1. type: 4 (`disable_channel_reserve`) Rationale and Requirements are the same as listed above, for [`accept_channel`](#the-accept_channel-message) with the following @@ -1288,7 +1301,15 @@ The accepting node: - MUST set `channel_type` to the `channel_type` from `open_channel2`. - MAY respond with a `funding_satoshis` value of zero. - If it requires the opening node to only use confirmed inputs: - - MUST set `require_confirmed_inputs`. + - MUST set `require_confirmed_inputs` + - If the receiving node supports `option_zero_reserve` and the `open_channel2` + message contains `disable_channel_reserve`: + - If the opening node is purchasing liquidity: + - SHOULD set `disable_channel_reserve`. + - Otherwise: + - MAY set `disable_channel_reserve`. + - If the receiving node supports `option_zero_reserve`: + - MAY set `disable_channel_reserve`. The receiving node: - MUST fail the negotiation if: @@ -1304,7 +1325,8 @@ Note that `accept_channel`'s `channel_reserve_satoshi` has been omitted. Instead, the channel reserve is fixed at 1% of the total channel balance (`open_channel2`.`funding_satoshis` + `accept_channel2`.`funding_satoshis`) rounded down to the nearest whole satoshi or the `dust_limit_satoshis`, -whichever is greater. +whichever is greater, unless `disable_channel_reserve` is set, in which +case there will be no channel reserve on the receiver side. ### Funding Composition @@ -1796,6 +1818,8 @@ The receiving node: - Either side has added an output other than the channel funding output and the balance for that side is less than the channel reserve that matches the new channel capacity. + - Either side has added an output other than the channel funding output + and any resulting commitment transactions would have no outputs. ##### Rationale @@ -2787,7 +2811,8 @@ A sending node: - SHOULD NOT offer `amount_msat` if, after adding that HTLC to its commitment transaction, its remaining balance doesn't allow it to pay the commitment transaction fee when receiving or sending a future additional non-dust HTLC - while maintaining its channel reserve. It is recommended that this "fee spike + while maintaining its channel reserve, or if the resulting commitment + transaction would have no outputs. It is recommended that this "fee spike buffer" can handle twice the current `feerate_per_kw` to ensure predictability between implementations. - if it is _not responsible_ for paying the Bitcoin fee: @@ -2795,6 +2820,9 @@ A sending node: its commitment transaction, it cannot pay the fee for the updated local or remote transaction at the current `feerate_per_kw` while maintaining its channel reserve. + - if, after adding that HTLC to its commitment transaction, that transaction + doesn't have any output: + - MUST NOT offer `amount_msat`. - MUST offer `amount_msat` greater than 0. - MUST NOT offer `amount_msat` below the receiving node's `htlc_minimum_msat` - MUST set `cltv_expiry` less than 500000000. @@ -2822,6 +2850,9 @@ A receiving node: - receiving an `amount_msat` that the sending node cannot afford at the current `feerate_per_kw` (while maintaining its channel reserve and any `to_local_anchor` and `to_remote_anchor` costs): - SHOULD send a `warning` and close the connection, or send an `error` and fail the channel. + - receiving an `amount_msat` that results in a commitment transaction without any output: + - SHOULD send a `warning` and close the connection, or send an + `error` and fail the channel. - if a sending node adds more than receiver `max_accepted_htlcs` HTLCs to its local commitment transaction, OR adds more than receiver `max_htlc_value_in_flight_msat` worth of offered HTLCs to its local commitment transaction: - SHOULD send a `warning` and close the connection, or send an diff --git a/09-features.md b/09-features.md index b0b9cb642..611899938 100644 --- a/09-features.md +++ b/09-features.md @@ -56,6 +56,7 @@ The Context column decodes as follows: | 50/51 | `option_zeroconf` | Understands zeroconf channel types | INT | `option_scid_alias` | [BOLT #2][bolt02-channel-ready] | | 60/61 | `option_simple_close` | Simplified closing negotiation | IN | `option_shutdown_anysegwit` | [BOLT #2][bolt02-simple-close] | | 62/63 | `option_splice` | Allows replacing the funding transaction with a new one | IN | | [BOLT #2](02-peer-protocol.md#channel-splicing) | +| 64/65 | `option_zero_reserve` | This node may accept zero-reserve channels | IN | | [BOLT #2][bolt02-open] | ## Requirements