mirrors/lightning-bolts
1
0
Fork 0
mirror of https://github.com/lightning/bolts.git synced 2025-03-13 11:35:41 +01:00
Code Issues Projects Releases Wiki Activity

BOLT 2, 3, 9: option_simple_close.

Browse source 
Pay your own fees, so the peer will sign without caring.  Even if it doesn't relay.

Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
This commit is contained in:
Rusty Russell 2023-07-18 06:59:29 +09:30 • committed by t-bast
parent 5f31faa0b6
commit f1807081e7
No known key found for this signature in database
GPG key ID: 34F377B0100ED6BB
3 changed files with 137 additions and 2 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

93
02-peer-protocol.md
View file

@ -36,6 +36,7 @@ operation, and closing.
* [Channel Close](#channel-close)
* [Closing Initiation: `shutdown`](#closing-initiation-shutdown)
* [Closing Negotiation: `closing_signed`](#closing-negotiation-closing_signed)
* [Closing Negotiation: `closing_complete` and `closing_sig`](#closing-negotiation-closing_complete-and-closing_sig)
* [Normal Operation](#normal-operation)
* [Forwarding HTLCs](#forwarding-htlcs)
* [`cltv_expiry_delta` Selection](#cltv_expiry_delta-selection)
@ -1521,10 +1522,24 @@ Closing happens in two stages:
| |<-(?)-- closing_signed Fn----| |
+-------+ +-------+
+-------+ +-------+
| |--(1)----- shutdown ------->| |
| |<-(2)----- shutdown --------| |
| | | |
| | <complete all pending HTLCs> | |
| A | ... | B |
| | | |
| |--(3a)- closing_complete Fee->| |
| |<-(3b)- closing_complete Fee--| |
| |<-(4a)- closing_sig ----------| |
| |--(4b)- closing_sig --------->| |
+-------+ +-------+
### Closing Initiation: `shutdown`
Either node (or both) can send a `shutdown` message to initiate closing,
along with the `scriptpubkey` it wants to be paid to.
along with the `scriptpubkey` it wants to be paid to. This can be
sent multiple times.
1. type: 38 (`shutdown`)
2. data:
@ -1713,6 +1728,82 @@ 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 Negotiation: `closing_complete` and `closing_sig`
Once shutdown is complete, the channel is empty of HTLCs, there are no commitments
for which a revocation is owed, and all updates are included on both commitments,
the final current commitment transactions will have no HTLCs.
Each peer says what fee it will pay, and the other side simply signs that transaction. The only complexity comes from allowing each side to omit its own output should it be uneconomic.
This process will be repeated every time a `shutdown` message is received, which allows re-negotiation.
1. type: 40 (`closing_complete`)
2. data:
* [`channel_id`:`channel_id`]
* [`u64`:`fee_satoshis`]
* [`u8`: `has_closer_output`]
* [`signature`:`signature_with_closee_output`]
* [`signature`:`signature_without_closee_output`]
1. type: 41 (`closing_sig`)
2. data:
* [`channel_id`:`channel_id`]
* [`u8`: `has_closee_output`]
* [`signature`:`signature`]
#### Requirements
Note: the details and requirements for the transaction being signed are in [BOLT 3](03-transactions.md#closing-transaction)).
Both nodes:
- After a `shutdown` has been received, AND no HTLCs remain in either commitment transaction:
- SHOULD send a `closing_complete` message.
The sender of `closing_complete` (aka. "the closer"):
- MUST set `fee_satoshis` to a fee less than or equal to its outstanding balance, rounded down to whole satoshis.
- SHOULD set `has_closer_output` to 0 if it considers its own remaining balance to be uneconomic.
- Otherwise MUST set `has_closer_output` to 1.
- If it sets `has_closer_output` to 1:
- MUST set `signature_with_closee_output` to a valid signature of a transaction with both closer and closee outputs.
- MUST set `signature_without_closee_output` to a valid signature of a transaction with only a closer output.
- Otherwise: (`has_closer_output` is 0):
- MUST set `signature_with_closee_output` to a valid signature of a transaction with only the closee output.
- MUST set `signature_without_closee_output` to a valid signature of a transaction with only the null output as described in [BOLT 3](03-transactions.md#closing-transaction).
The receiver of `closing_complete` (aka. "the closee"):
- if either `signature_with_closee_output` or `signature_without_closee_output` is not valid for the closing transactions specified in [BOLT #3](03-transactions.md#closing-transaction) OR non-compliant with LOW-S-standard rule<sup>[LOWS](https://github.com/bitcoin/bitcoin/pull/6769)</sup>:
- MUST either send a `warning` and close the connection, or send an `error` and fail the channel.
- Otherwise:
- MUST select one of the signatures (and thus, transactions) to respond to.
- MUST sign and broadcast that transaction.
- MUST send `closing_sig`.
The sender of `closing_sig`:
- if it selected `signature_with_closee_output` to broadcast:
- MUST set `has_closee_output` to 1.
- MUST set `signature` to a valid signature on that transaction.
- otherwise (it selected `signature_without_closee_output`):
- MUST set `has_closee_output` to 0.
- MUST set `signature` to a valid signature on that transaction.
The receiver of `closing_sig`:
- MUST broadcast the transaction indicated by `has_closee_output`.
### Rationale
The close protocol is designed to avoid any failure scenarios caused by fee disagreement, since each side offers to pay its own desired fee.
Multiple signatures are given, so each side can choose whether it wants to include its own output. In the case of large fees and tiny channels, where neither side wants its output, the use of an OP_RETURN simply cleans up the dangling unspent transaction output. This is expected to be extremely rare.
Note that there is usually no reason to pay a high fee for rapid processing, since an urgent child could pay the fee on the closing transactions' behalf.
If the closer proposes a transaction which will not relay (either its own output is dust, or the fee rate it proposes is too low), it doesn't harm the closee to sign the transaction.
Similarly, if the closer proposes a high fee, it doesn't harm the closee to sign the transaction, as the closer is paying.
There's a slight game where each side would prefer the other side pay the fee, and proposes a minimal fee. If neither side proposes a fee which will relay, the negotiation can occur again, or the final commitment transaction can be spent. In practice, the opener has an incentive to offer a reasonable closing fee, as they would pay the fee for the commitment transaction, which also costs more to spend.
## 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.

44
03-transactions.md
View file

@ -349,7 +349,9 @@ The witness script for the output is:
To spend this via penalty, the remote node uses a witness stack `<revocationsig> 1`, and to collect the output, the local node uses an input with nSequence `to_self_delay` and a witness stack `<local_delayedsig> 0`.
## Closing Transaction
## Classic Closing Transaction
This variant is used for `closing_signed` messages (i.e. where `option_simple_close` is not negotiated).
Note that there are two possible variants for each node.
@ -390,6 +392,46 @@ has been used.
There will be at least one output, if the funding amount is greater
than twice `dust_limit_satoshis`.
## Closing Transaction
This variant is used for `closing_complete` and `closing_sig` messages (i.e. where `option_simple_close` is negotiated).
In this case, the node sending `closing_complete` ("the closer") pays the fees, and the sequence is set to 0xFFFFFFFD to allow RBF. The outputs are ordered as detailed in [Transaction Output Ordering](#transaction-output-ordering).
Two closing transactions are always produced: one `with_closee_output` one `without_closee_output` (the non-closer chooses which to accept). `closing_complete` contains `has_closer_output` to indicate whether the closer's output is in the transactions.
* version: 2
* locktime: 0
* txin count: 1
* `txin[0]` outpoint: `txid` and `output_index` from `funding_created` message
* `txin[0]` sequence: 0xFFFFFFFD
* `txin[0]` script bytes: 0
* `txin[0]` witness: `0 <signature_for_pubkey1> <signature_for_pubkey2>`
* txout count: 1 or 2 of the following
* The closer output:
* `txout` amount: the final balance for the closer, minus `closing_complete` `fee_satoshis`, rounded down to whole satoshis.
* `txout` script: as specified in that closer's `scriptpubkey` in its `shutdown` message
* The closee output:
* `txout` amount: the final balance for the closer, rounded down to whole satoshis.
* `txout` script: as specified in that closee's `scriptpubkey` in its `shutdown` message
* The null output:
* `txout` amount: 0
* `txout` script: `feeeee` `OP_RETURN` (102 101 101 101 101 101 106).
### Requirements
Each node offering a signature:
- MUST round each output down to whole satoshis.
- MUST subtract the fee given by `fee_satoshis` from the closer output.
### Rationale
The case where both sides omit their outputs due to a de-minimus channel is never expected to happen, however it is
documented here for completeness, and serves to avoid an polluting the unspent outputs. Unfortunately, the transaction
has to be at least 65 bytes to propagate, so the `OP_RETURN` includes padding.
## Fees
### Fee Calculation

2
09-features.md
View file

@ -52,6 +52,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_simple_close` | Simplified closing negotiation | IN | `option_shutdown_anysegwit` | [BOLT #2][bolt02-simple-close] |
## Requirements
@ -97,6 +98,7 @@ This work is licensed under a [Creative Commons Attribution 4.0 International Li
[bolt02-retransmit]: 02-peer-protocol.md#message-retransmission
[bolt02-open]: 02-peer-protocol.md#the-open_channel-message
[bolt02-simple-close]: 02-peer-protocol.md#closing-negotiation-closing_complete-and-closing_sig
[bolt03-htlc-tx]: 03-transactions.md#htlc-timeout-and-htlc-success-transactions
[bolt02-shutdown]: 02-peer-protocol.md#closing-initiation-shutdown
[bolt02-quiescence]: 02-peer-protocol.md#channel-quiescence