From c6ef1e99e58314a657863b2a7d4c0028cc497725 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 | 45 ++++++++++++++++++++++++++++++++++---------- 07-routing-gossip.md | 2 ++ 09-features.md | 1 + 3 files changed, 38 insertions(+), 10 deletions(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 38e2b72..36683e1 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -762,7 +762,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`). @@ -812,10 +815,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`. - It supports `channel_type` and `channel_type` was set: - if `type` is not suitable. @@ -840,7 +843,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 @@ -891,17 +894,22 @@ 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. + - If the receiver supports `option_zero_reserve` and `channel_reserve_satoshis` from the `open_channel` message is `0`: + - SHOULD 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. - if `option_channel_type` was negotiated: - 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_conf` 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_conf` is not set: - MUST fail the channel. - if `channel_type` is set, and `channel_type` was set in `open_channel`, and they are not equal types: - MUST fail the channel. @@ -1171,6 +1179,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. @@ -1185,6 +1194,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_conf`: + - MAY set `disable_channel_reserve`. The receiving node: - MAY fail the negotiation if: @@ -1214,7 +1225,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. @@ -1258,6 +1270,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 @@ -1270,6 +1283,11 @@ The accepting node: - 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` + - If the receiving node supports `option_zero_conf` and the `open_channel2` + message contains `disable_channel_reserve`: + - SHOULD set `disable_channel_reserve`. + - If the receiving node supports `option_zero_conf`: + - MAY set `disable_channel_reserve`. The receiving node: - MUST fail the negotiation if: @@ -1284,7 +1302,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 @@ -1942,6 +1961,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. @@ -1967,6 +1989,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/07-routing-gossip.md b/07-routing-gossip.md index 4b67a38..4907ebb 100644 --- a/07-routing-gossip.md +++ b/07-routing-gossip.md @@ -462,6 +462,8 @@ The origin node: reasons. - Note: such a `channel_update`, one not preceded by a `channel_announcement`, is invalid to any other peer and would be discarded. + - If the channel will not be announced (i.e. the `announce_channel` bit was not set) and `option_zero_conf` is used: + - MUST send a `channel_update` using the real channel `short_channel_id` once the channel is confirmed. - MUST set `signature` to the signature of the double-SHA256 of the entire remaining packet after `signature`, using its own `node_id`. - MUST set `chain_hash` AND `short_channel_id` to match the 32-byte hash AND diff --git a/09-features.md b/09-features.md index 95c59e9..2ed3ff2 100644 --- a/09-features.md +++ b/09-features.md @@ -50,6 +50,7 @@ The Context column decodes as follows: | 46/47 | `option_scid_alias` | Supply channel aliases for routing | IN | | [BOLT #2][bolt02-channel-ready] | | 48/49 | `option_payment_metadata` | Payment metadata in tlv record | 9 | | [BOLT #11](11-payment-encoding.md#tagged-fields) | | 50/51 | `option_zeroconf` | Understands zeroconf channel types | IN | `option_scid_alias` | [BOLT #2][bolt02-channel-ready] | +| 64/65 | `option_zero_reserve` | This node may accept zero-reserve channels | IN | | [BOLT #2][bolt02-open] | ## Definitions