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 option_zero_reserve (FEATURE 64/65) #1140

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
+38 −10
Open

Add option_zero_reserve (FEATURE 64/65) #1140

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
45 changes: 35 additions & 10 deletions 02-peer-protocol.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`).
Expand Down Expand Up @@ -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.
Expand All @@ -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
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand All @@ -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:
Expand Down Expand Up @@ -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.

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

Expand Down Expand Up @@ -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.
Expand All @@ -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
Expand Down
2 changes: 2 additions & 0 deletions 07-routing-gossip.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
1 change: 1 addition & 0 deletions 09-features.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down