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

option_closing_rejected: turn-based fee_range coop close (feature 60/61) #1016

Closed
wants to merge 1 commit into from
Closed

option_closing_rejected: turn-based fee_range coop close (feature 60/61) #1016

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
38 changes: 37 additions & 1 deletion 02-peer-protocol.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -679,6 +679,10 @@ non-funder has to pick a fee in this range. If the non-funder chooses the same
value, negotiation is complete after two messages, otherwise the funder will
reply with the same value (completing after three messages).

If `option_closing_rejected` is negotiated, then the fee_range flow is similar to
the case where it isn't negotiated, except that `closing_rejected` messages are
sent by the fundee in case of mismatch.

1. type: 39 (`closing_signed`)
2. data:
* [`channel_id`:`channel_id`]
Expand Down Expand Up @@ -706,7 +710,12 @@ The sending node:
prepared to pay for a close transaction.
- if it doesn't receive a `closing_signed` response after a reasonable amount of time:
- MUST fail the channel
- if it is not the funder:
- if it is the funder:
- if `option_closing_rejected` has been negotiated:
- if a `closing_signed` has already been sent:
- MUST wait until receipt of either a corresponding `closing_signed` or
`closing_rejected` before sending this `closing_signed`.
- otherwise (it is not the funder):
- SHOULD set `max_fee_satoshis` to at least the `max_fee_satoshis` received
- SHOULD set `min_fee_satoshis` to a fairly low value
- MUST set `signature` to the Bitcoin signature of the close transaction,
Expand All @@ -728,6 +737,8 @@ The receiving node:
- if there is no overlap between that and its own `fee_range`:
- SHOULD send a warning
- MUST fail the channel if it doesn't receive a satisfying `fee_range` after a reasonable amount of time
- if `option_closing_rejected` has been negotiated:
- MUST send a `closing_rejected` message.
- otherwise:
- if it is the funder:
- if `fee_satoshis` is not in the overlap between the sent and received `fee_range`:
Expand Down Expand Up @@ -776,6 +787,31 @@ satoshis, which is possible if `dust_limit_satoshis` is below 546 satoshis).
No funds are at risk when that happens, but the channel must be force-closed as
the closing transaction will likely never reach miners.

### Closing Rejected: `closing_rejected`

If the fundee disagrees on the `fee_range` the funder proposed, they may send a
`closing_rejected` to tell them to try again.

1. type: 40 (`closing_rejected`)
2. data:
* [`channel_id`:`channel_id`]
Copy link
Collaborator

Choose a reason for hiding this comment

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

Comment from spec meeting: should this also include a fee range in 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.

I thought we were going with the whole warnings approach for telling what parameters you didn't like about any message?


#### Requirements

The sending node (the fundee):
- if `option_closing_rejected` has not been negotiated:
- MUST NOT send this message.

The receiving node (the funder):
- if `option_closing_rejected` has not been negotiated:
- MUST fail the channel.

#### Rationale

Without `option_closing_rejected`, it is possible that fee_range-based coop close
results in a force close due to a [timing issue](https://github.com/lightning/bolts/issues/1013).
Requiring that the negotiation is turn-based fixes the issue.

## Normal Operation

Once both nodes have exchanged `channel_ready` (and optionally [`announcement_signatures`](07-routing-gossip.md#the-announcement_signatures-message)), the channel can be used to make payments via Hashed Time Locked Contracts.
Expand Down
2 changes: 2 additions & 0 deletions 09-features.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,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] |
| 60/61 | `option_closing_rejected` | Turn-based fee_range coop closing | IN | | [BOLT #2][bolt02-closing-signed]

## Definitions

Expand Down Expand Up @@ -92,6 +93,7 @@ This work is licensed under a [Creative Commons Attribution 4.0 International Li
[bolt02-open]: 02-peer-protocol.md#the-open_channel-message
[bolt03-htlc-tx]: 03-transactions.md#htlc-timeout-and-htlc-success-transactions
[bolt02-shutdown]: 02-peer-protocol.md#closing-initiation-shutdown
[bolt02-closing-signed]: 02-peer-protocol.md#closing-negotiation-closingsigned
[bolt02-channel-ready]: 02-peer-protocol.md#the-channel_ready-message
[bolt04]: 04-onion-routing.md
[bolt07-sync]: 07-routing-gossip.md#initial-sync
Expand Down