Skip to content

Commit 8cfc619

Browse files
t-bastt-bast
committed
Address pending PR comments
- add more detailed protocol flow diagram - rename sigs TLVs as suggested by @morehouse - mention `upfront_shutdown_script` as suggested by @Crypt-iQ - fix typos - reformat
1 parent 47afb0e commit 8cfc619

File tree

1 file changed

+100
-53
lines changed

1 file changed

+100
-53
lines changed

‎02-peer-protocol.md

Lines changed: 100 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -1509,30 +1509,58 @@ Closing happens in two stages:
15091509
2. once all HTLCs are resolved, the final channel close negotiation begins.
15101510

15111511
+-------+ +-------+
1512-
| |--(1)----- shutdown ------->| |
1513-
| |<-(2)----- shutdown --------| |
1512+
| | shutdown(scriptA1) | |
1513+
| |----------------------------->| |
1514+
| | shutdown(scriptB1) | |
1515+
| |<-----------------------------| |
15141516
| | | |
15151517
| | <complete all pending HTLCs> | |
1516-
| A | ... | B |
1518+
| A | .... | B |
15171519
| | | |
1518-
| |--(3)-- closing_signed F1--->| |
1519-
| |<-(4)-- closing_signed F2----| |
1520-
| | ... | |
1521-
| |--(?)-- closing_signed Fn--->| |
1522-
| |<-(?)-- closing_signed Fn----| |
1523-
+-------+ +-------+
1524-
1525-
+-------+ +-------+
1526-
| |--(1)----- shutdown ------->| |
1527-
| |<-(2)----- shutdown --------| |
1520+
| | closing_complete | |
1521+
| |----------------------------->| |
1522+
| | closing_complete | |
1523+
| |<-----------------------------| |
1524+
| | closing_sig | |
1525+
| |<-----------------------------| |
1526+
| | closing_sig | |
1527+
| |----------------------------->| |
15281528
| | | |
1529-
| | <complete all pending HTLCs> | |
1530-
| A | ... | B |
1529+
| | <A updates their script> | |
15311530
| | | |
1532-
| |--(3a)- closing_complete Fee->| |
1533-
| |<-(3b)- closing_complete Fee--| |
1534-
| |<-(4a)- closing_sig ----------| |
1535-
| |--(4b)- closing_sig --------->| |
1531+
| | shutdown(scriptA2) | |
1532+
| |----------------------------->| |
1533+
| | closing_complete | |
1534+
| |----------------------------->| |
1535+
| | closing_sig | |
1536+
| |<-----------------------------| |
1537+
| | | |
1538+
| | <Both update their script> | | (*) This is a concurrent update
1539+
| | | |
1540+
| | shutdown(scriptA3) | |
1541+
| |-------------------> | |
1542+
| | closing_complete | |
1543+
| |-------------------> | |
1544+
| | shutdown(scriptB2) | |
1545+
| | <-------------------| |
1546+
| | closing_complete | |
1547+
| | <-------------------| |
1548+
| | shutdown(scriptA3) | |
1549+
| | ------------------->| |
1550+
| | closing_complete | |
1551+
| | ------------------->| | (*) B doesn't answer with closing_sig because A's sig doesn't use scriptB2
1552+
| | shutdown(scriptB2) | |
1553+
| |<------------------- | |
1554+
| | closing_complete | |
1555+
| |<------------------- | | (*) A doesn't answer with closing_sig because B's sig doesn't use scriptA3
1556+
| | closing_complete | |
1557+
| |----------------------------->| | (*) A now uses scriptB2 and scriptA3 for closing_complete
1558+
| | closing_complete | |
1559+
| |<-----------------------------| | (*) B now uses scriptB2 and scriptA3 for closing_complete
1560+
| | closing_sig | |
1561+
| |----------------------------->| |
1562+
| | closing_sig | |
1563+
| |<-----------------------------| |
15361564
+-------+ +-------+
15371565

15381566
### Closing Initiation: `shutdown`
@@ -1742,7 +1770,8 @@ Once shutdown is complete, the channel is empty of HTLCs, there are no commitmen
17421770
for which a revocation is owed, and all updates are included on both commitments,
17431771
the final current commitment transactions will have no HTLCs.
17441772

1745-
Each peer says what fee it will pay, and the other side simply signs that transaction. The lesser-paid peer (if either is) can opt to omit their own output from the closing tx.
1773+
Each peer says what fee it will pay, and the other side simply signs that transaction.
1774+
The lesser-paid peer (if either is) can opt to omit their own output from the closing tx.
17461775

17471776
This process will be repeated every time a `shutdown` message is received, which allows re-negotiation (and RBF).
17481777

@@ -1755,13 +1784,13 @@ This process will be repeated every time a `shutdown` message is received, which
17551784

17561785
1. `tlv_stream`: `closing_tlvs`
17571786
2. types:
1758-
1. type: 1 (`closer_no_closee`)
1787+
1. type: 1 (`closer_output_only`)
17591788
2. data:
17601789
* [`signature`:`sig`]
1761-
1. type: 2 (`no_closer_closee`)
1790+
1. type: 2 (`closee_output_only`)
17621791
2. data:
17631792
* [`signature`:`sig`]
1764-
1. type: 3 (`closer_and_closee`)
1793+
1. type: 3 (`closer_and_closee_outputs`)
17651794
2. data:
17661795
* [`signature`:`sig`]
17671796

@@ -1772,7 +1801,7 @@ This process will be repeated every time a `shutdown` message is received, which
17721801

17731802
#### Requirements
17741803

1775-
Note: the details and requirements for the transaction being signed are in [BOLT 3](03-transactions.md#closing-transaction)).
1804+
Note: the details and requirements for the transaction being signed are in [BOLT 3](03-transactions.md#closing-transaction).
17761805

17771806
An output is *dust* if the amount is less than the [Bitcoin Core Dust Thresholds](03-transactions.md#dust-limits).
17781807

@@ -1783,36 +1812,35 @@ Both nodes:
17831812
The sender of `closing_complete` (aka. "the closer"):
17841813
- MUST set `fee_satoshis` to a fee less than or equal to its outstanding balance, rounded down to whole satoshis.
17851814
- MUST set `fee_satoshis` so that at least one output is not dust.
1786-
- MUST use the last send and received `shutdown` `scriptpubkey` to generate the closing transaction specified in [BOLT #3](03-transactions.md#closing-transaction).
1787-
- If it sets `signature` fields, MUST set them as valid signature using its `funding_pubkey` of:
1788-
- `closer_no_closee`: closing transaction with only the local ("closer") output.
1789-
- `no_closer_closee`: closing transaction with only the remote ("closee") output.
1790-
- `closer_and_closee`: closing transaction with both the closer and closee outputs.
1815+
- MUST use the last sent and received `shutdown.scriptpubkey` to generate the closing transaction specified in [BOLT #3](03-transactions.md#closing-transaction).
1816+
- MUST set `signature` fields as valid signature using its `funding_pubkey` of:
1817+
- `closer_output_only`: closing transaction with only the local ("closer") output.
1818+
- `closee_output_only`: closing transaction with only the remote ("closee") output.
1819+
- `closer_and_closee_outputs`: closing transaction with both the closer and closee outputs.
17911820
- If the local outstanding balance (in millisatoshi) is less than the remote outstanding balance:
1792-
- MUST NOT set `closer_no_closee`.
1793-
- MUST set exactly one of `no_closer_closee` or `closer_and_closee`.
1794-
- MUST set `no_closer_closee` if the local output amount is dust.
1795-
- MAY set `no_closer_closee` if it considers the local output amount uneconomic AND its `scriptpubkey` is not `OP_RETURN`.
1821+
- MUST NOT set `closer_output_only`.
1822+
- MUST set `closee_output_only` if the local output amount is dust.
1823+
- MAY set `closee_output_only` if it considers the local output amount uneconomical AND its `scriptpubkey` is not `OP_RETURN`.
17961824
- Otherwise (not lesser amount, cannot remove own output):
1797-
- MUST NOT set `no_closer_closee`.
1825+
- MUST NOT set `closee_output_only`.
17981826
- If the closee's output amount is dust:
1799-
- MUST set `closer_no_closee`.
1800-
- SHOULD NOT set `closer_and_closee`.
1827+
- MUST set `closer_output_only`.
1828+
- SHOULD NOT set `closer_and_closee_outputs`.
18011829
- Otherwise:
1802-
- MUST set both `closer_no_closee` and `closer_and_closee`.
1830+
- MUST set both `closer_output_only` and `closer_and_closee_outputs`.
18031831

18041832
The receiver of `closing_complete` (aka. "the closee"):
18051833
- If `fee_satoshis` is greater than the closer's outstanding balance:
18061834
- MUST either send a `warning` and close the connection, or send an `error` and fail the channel.
18071835
- Select a signature for validation:
18081836
- if the local output amount is dust:
1809-
- MUST use `closer_no_closee`.
1810-
- otherwise, if it considers the closee output amount uneconomic AND its `scriptpubkey` is not `OP_RETURN`:
1811-
- MUST use `closer_no_closee`.
1812-
- otherwise, if `closer_and_closee` is present:
1813-
- MUST use `closer_and_closee`.
1837+
- MUST use `closer_output_only`.
1838+
- otherwise, if it considers the local output amount uneconomical AND its `scriptpubkey` is not `OP_RETURN`:
1839+
- MUST use `closer_output_only`.
1840+
- otherwise, if `closer_and_closee_outputs` is present:
1841+
- MUST use `closer_and_closee_outputs`.
18141842
- otherwise:
1815-
- MUST use `no_closer_closee`.
1843+
- MUST use `closee_output_only`.
18161844
- If the selected signature field does not exist:
18171845
- MUST either send a `warning` and close the connection, or send an `error` and fail the channel.
18181846
- If the signature field is not valid for the corresponding closing transaction specified in [BOLT #3](03-transactions.md#closing-transaction):
@@ -1828,29 +1856,48 @@ The receiver of `closing_sig`:
18281856
- if `tlvs` does not contain one of the tlv fields sent in `closing_complete`:
18291857
- MUST ignore `closing_sig`.
18301858
- if the signature field is not valid for the corresponding closing transaction specified in [BOLT #3](03-transactions.md#closing-transaction):
1831-
- MUST ignore `closing_complete`.
1859+
- MUST ignore `closing_sig`.
18321860
- if the signature field is non-compliant with LOW-S-standard rule<sup>[LOWS](https://github.com/bitcoin/bitcoin/pull/6769)</sup>:
18331861
- MUST either send a `warning` and close the connection, or send an `error` and fail the channel.
18341862
- otherwise:
1835-
- MUST sign and broadcast the corrsponding closing transaction.
1863+
- MUST sign and broadcast the corresponding closing transaction.
18361864

18371865
### Rationale
18381866

1839-
The close protocol is designed to avoid any failure scenarios caused by fee disagreement, since each side offers to pay its own desired fee.
1867+
The close protocol is designed to avoid any failure scenarios caused by fee disagreement,
1868+
since each side offers to pay its own desired fee.
18401869

1841-
If one side has less funds than the other, it may choose to omit its own output, and in this case dust MUST be omitted, to ensure the resulting transaction can be broadcast.
1870+
If one side has less funds than the other, it may choose to omit its own output, and in this case
1871+
dust MUST be omitted, to ensure that the resulting transaction can be broadcast.
18421872

1843-
The corner case where fees are so high that both outputs are dust is addressed in two ways: paying a low fee to avoid the problem, or using an OP_RETURN (which is never "dust").
1873+
The corner case where fees are so high that both outputs are dust is addressed in two ways: paying
1874+
a low fee to avoid the problem, or using an OP_RETURN (which is never "dust"). If one side chooses
1875+
to use an `OP_RETURN` output, its amount must be 0 to ensure that the resulting transaction can be
1876+
broadcast.
18441877

1845-
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.
1878+
Note that there is usually no reason to pay a high fee for rapid processing, since an urgent child
1879+
could pay the fee on the closing transactions' behalf. If rapid processing is desired and CPFP is
1880+
not an option, the closer can RBF its previous closing transactions by sending `shutdown` again.
18461881

1847-
However, sending a new `shutdown` message overrides previous ones, so you can negotiate again (even changing the output address) if you want: in this case there's a race where you could receive a `closing_complete` for the previous output address, and the signature won't validate. In this case, ignoring the `closing_complete` is the correct behaviour, as the new `shutdown` will trigger a new `closing_complete` with the correct signature. This assumption that we only remember the last-sent of any message is why so many cases of bad signatures are simply ignored.
1882+
Sending a new `shutdown` message overrides previous ones, so you can negotiate again (even changing
1883+
the output address when `upfront_shutdown_script` was not negotiated) if you want: in this case
1884+
there's a race where you could receive `closing_complete` for the previous output address, and the
1885+
signature won't validate. In this case, ignoring the `closing_complete` is the correct behaviour,
1886+
as the new `shutdown` will trigger a new `closing_complete` with the correct signature. This
1887+
assumption that we only remember the last-sent of any message is why so many cases of bad
1888+
signatures are simply ignored.
18481889

1849-
If the closer proposes a transaction which will not relay (an output is dust, or the fee rate it proposes is too low), it doesn't harm the closee to sign the transaction.
1890+
If the closer proposes a transaction which will not relay (an output is dust, or the fee rate it
1891+
proposes is too low), it doesn't harm the closee to sign the transaction.
18501892

1851-
Similarly, if the closer proposes a high fee, it doesn't harm the closee to sign the transaction, as the closer is paying.
1893+
Similarly, if the closer proposes a high fee, it doesn't harm the closee to sign the transaction,
1894+
as the closer is paying.
18521895

1853-
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.
1896+
There's a slight game where each side would prefer the other side pay the fee, and proposes a
1897+
minimal fee. If neither side proposes a fee which will relay, the negotiation can occur again,
1898+
or the final commitment transaction can be spent. In practice, the opener has an incentive to
1899+
offer a reasonable closing fee, as they would pay the fee for the commitment transaction, which
1900+
also costs more to spend.
18541901

18551902
## Normal Operation
18561903

0 commit comments

Comments
 (0)