From 474b68caea0d7b4302f3117716ae90cde3597e5a Mon Sep 17 00:00:00 2001 From: Rusty Russell Date: Fri, 10 Dec 2021 04:48:20 +1030 Subject: [PATCH 1/5] BOLT 1: Add warning message, remove "close all" error. Under this spec, an error with an all-zero channel id is ignored. Warnings, being odd, will be ignored by older nodes too. Signed-off-by: Rusty Russell --- 01-messaging.md | 36 +++++++++++++++++++++++------------- 1 file changed, 23 insertions(+), 13 deletions(-) diff --git a/01-messaging.md b/01-messaging.md index 867fe002d..946946dd3 100644 --- a/01-messaging.md +++ b/01-messaging.md @@ -306,7 +306,7 @@ support a single network, the `networks` fields avoids nodes erroneously believing they will receive updates about their preferred network, or that they can open channels. -### The `error` Message +### The `error` and `warning` Messages For simplicity of diagnosis, it's often useful to tell a peer that something is incorrect. @@ -316,12 +316,14 @@ For simplicity of diagnosis, it's often useful to tell a peer that something is * [`u16`:`len`] * [`len*byte`:`data`] -The 2-byte `len` field indicates the number of bytes in the immediately following field. +1. type: 1 (`warning`) +2. data: + * [`channel_id`:`channel_id`] + * [`u16`:`len`] + * [`len*byte`:`data`] #### Requirements -The channel is referred to by `channel_id`, unless `channel_id` is 0 (i.e. all bytes are 0), in which case it refers to all channels. - The funding node: - for all error messages sent before (and including) the `funding_created` message: - MUST use `temporary_channel_id` in lieu of `channel_id`. @@ -331,24 +333,27 @@ The fundee node: - MUST use `temporary_channel_id` in lieu of `channel_id`. A sending node: - - when sending `error`: - - MUST fail the channel referred to by the error message. - SHOULD send `error` for protocol violations or internal errors that make channels unusable or that make further communication unusable. - SHOULD send `error` with the unknown `channel_id` in reply to messages of type `32`-`255` related to unknown channels. + - when sending `error`: + - MUST fail the channel referred to by the error message. + - when sending `warning`: + - MAY set `channel_id` to all zero if the warning is not related to a specific channel. + - MAY close the connection after sending. - MAY send an empty `data` field. - when failure was caused by an invalid signature check: - SHOULD include the raw, hex-encoded transaction in reply to a `funding_created`, `funding_signed`, `closing_signed`, or `commitment_signed` message. - - when `channel_id` is 0: - - MUST fail all channels with the receiving node. - - MUST close the connection. - - MUST set `len` equal to the length of `data`. The receiving node: - upon receiving `error`: - - MUST fail the channel referred to by the error message, if that channel is with the sending node. - - if no existing channel is referred to by the message: + - MUST fail the channel referred to by `channel_id`, if that channel is with the sending node. + - upon receiving `warning`: + - SHOULD log the message for later diagnosis. + - MAY disconnect. + - MAY reconnect after some delay to retry. + - MAY attempt `shutdown` if permitted at this point. + - if no existing channel is referred to by `channel_id`: - MUST ignore the message. - - MUST truncate `len` to the remainder of the packet (if it's larger). - if `data` is not composed solely of printable ASCII characters (For reference: the printable character set includes byte values 32 through 126, inclusive): - SHOULD NOT print out `data` verbatim. @@ -359,6 +364,11 @@ if the connection is simply dropped, then the peer may retry the connection. It's also useful to describe protocol violations for diagnosis, as this indicates that one peer has a bug. +On the other hand, overuse of error messages has lead to +implementations ignoring them (to avoid an otherwise expensive channel +break), so the "warning" message was added to allow some degree of +retry or recovery for spurious errors. + It may be wise not to distinguish errors in production settings, lest it leak information — hence, the optional `data` field. From eb6f3084c5d0c020f750a987298aa9b596a12f5f Mon Sep 17 00:00:00 2001 From: Rusty Russell Date: Tue, 14 Dec 2021 10:32:22 +1030 Subject: [PATCH 2/5] Make it explicit when to send warnings, errors, fail channel and close connection. And make most places warn or error. Places where we're operating on a channel tend to be "warn and close connection" since we want to forget the mistake they just sent, and closing the connection does that. We now use the same words everywhere: 1. "fail channel" means to go onchain (if necessary). 2. "send `error`" means to send an error message. 3. "send `warning`" means to send a warning message. 4. "close connection" means close the connection. These are all spelled out explicitly, rather than having "fail channel" imply sending an error packet, for example. Signed-off-by: Rusty Russell --- 00-introduction.md | 14 ++++++++ 01-messaging.md | 12 +++---- 02-peer-protocol.md | 80 ++++++++++++++++++++++++++++---------------- 03-transactions.md | 3 +- 05-onchain.md | 2 +- 07-routing-gossip.md | 53 ++++++++++++++++++----------- 6 files changed, 107 insertions(+), 57 deletions(-) diff --git a/00-introduction.md b/00-introduction.md index 6807f3b11..cdb0d656b 100644 --- a/00-introduction.md +++ b/00-introduction.md @@ -132,6 +132,20 @@ See [BOLT #11: Invoice Protocol for Lightning Payments](11-payment-encoding.md) * _See related: [closing transaction](#closing-transaction), [funding transaction](#funding-transaction), [penalty transaction](#penalty-transaction)_ * _See types: [revoked commitment transaction](#revoked-commitment-transaction)_ +* #### *Fail the channel*: + * This is a forced close of the channel. Very early on (before + opening), this may not require any action but forgetting the + existence of the channel. Usually it requires signing and + broadcasting the latest commitment transaction, although during + mutual close it can also be performed by signing and broadcasting a + mutual close transaction. See [BOLT #5](05-onchain.md#failing-a-channel). + +* #### *Close the connection*: + * This means closing communication with the peer (such as closing + the TCP socket). It does not imply closing any channels with the + peer, but does cause the discarding of uncommitted state for + connections with channels: see [BOLT #2](02-peer-protocol.md#message-retransmission). + * #### *Final node*: * The final recipient of a packet that is routing a payment from an *[origin node](#origin-node)* through some number of *[hops](#hop)*. It is also the final *[receiving peer](#receiving-peer)* in a chain. * _See category: [node](#node)_ diff --git a/01-messaging.md b/01-messaging.md index 946946dd3..59aa3dc57 100644 --- a/01-messaging.md +++ b/01-messaging.md @@ -17,7 +17,7 @@ All data fields are unsigned big-endian unless otherwise specified. * [Fundamental Types](#fundamental-types) * [Setup Messages](#setup-messages) * [The `init` Message](#the-init-message) - * [The `error` Message](#the-error-message) + * [The `error` and `warning` Messages](#the-error-and-warning-messages) * [Control Messages](#control-messages) * [The `ping` and `pong` Messages](#the-ping-and-pong-messages) * [Appendix A: BigSize Test Vectors](#appendix-a-bigsize-test-vectors) @@ -285,11 +285,11 @@ The receiving node: - upon receiving unknown _odd_ feature bits that are non-zero: - MUST ignore the bit. - upon receiving unknown _even_ feature bits that are non-zero: - - MUST fail the connection. + - MUST close the connection. - upon receiving `networks` containing no common chains - - MAY fail the connection. + - MAY close the connection. - if the feature vector does not set all known, transitive dependencies: - - MUST fail the connection. + - MUST close the connection. #### Rationale @@ -404,7 +404,7 @@ A node sending a `ping` message: - MUST NOT set `ignored` to sensitive data such as secrets or portions of initialized memory. - if it doesn't receive a corresponding `pong`: - - MAY terminate the network connection, + - MAY close the network connection, - and MUST NOT fail the channels in this case. A node sending a `pong` message: @@ -420,7 +420,7 @@ A node receiving a `ping` message: A node receiving a `pong` message: - if `byteslen` does not correspond to any `ping`'s `num_pong_bytes` value it has sent: - - MAY fail the channels. + - MAY close the connection. ### Rationale diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 36ece00a6..4206d311f 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -392,7 +392,8 @@ The sender: The recipient: - if `signature` is incorrect OR non-compliant with LOW-S-standard rule[LOWS](https://github.com/bitcoin/bitcoin/pull/6769): - - MUST fail the channel. + - MUST send a `warning` and close the connection, or send an + `error` and fail the channel. #### Rationale @@ -438,7 +439,8 @@ The sender MUST set: The recipient: - if `signature` is incorrect OR non-compliant with LOW-S-standard rule[LOWS](https://github.com/bitcoin/bitcoin/pull/6769): - - MUST fail the channel. + - MUST send a `warning` and close the connection, or send an + `error` and fail the channel. - MUST NOT broadcast the funding transaction before receipt of a valid `funding_signed`. - on receipt of a valid `funding_signed`: - SHOULD broadcast the funding transaction. @@ -484,7 +486,7 @@ A non-funding node (fundee): transaction after a timeout of 2016 blocks. From the point of waiting for `funding_locked` onward, either node MAY -fail the channel if it does not receive a required response from the +send an `error` and fail the channel if it does not receive a required response from the other node after a reasonable timeout. #### Rationale @@ -558,14 +560,15 @@ A sending node: A receiving node: - if it hasn't received a `funding_signed` (if it is a funder) or a `funding_created` (if it is a fundee): - - SHOULD fail the connection + - SHOULD send a `warning`. - if the `scriptpubkey` is not in one of the above forms: - - SHOULD fail the connection. + - SHOULD send a `warning`. - if it hasn't sent a `funding_locked` yet: - MAY reply to a `shutdown` message with a `shutdown` - once there are no outstanding updates on the peer, UNLESS it has already sent a `shutdown`: - MUST reply to a `shutdown` message with a `shutdown` - if both nodes advertised the `option_upfront_shutdown_script` feature, and the receiving node received a non-zero-length `shutdown_scriptpubkey` in `open_channel` or `accept_channel`, and that `shutdown_scriptpubkey` is not equal to `scriptpubkey`: + - MAY send a `warning`. - MUST fail the connection. #### Rationale @@ -647,7 +650,8 @@ The sending node: The receiving node: - if the `signature` is not valid for either variant of closing transaction specified in [BOLT #3](03-transactions.md#closing-transaction) OR non-compliant with LOW-S-standard rule[LOWS](https://github.com/bitcoin/bitcoin/pull/6769): - - MUST fail the connection. + - MUST send a `warning` and close the connection, or send an + `error` and fail the channel. - if `fee_satoshis` is equal to its previously sent `fee_satoshis`: - SHOULD sign and broadcast the final closing transaction. - MAY close the connection. @@ -673,7 +677,8 @@ The receiving node: - MUST propose a `fee_satoshis` in the overlap between received and (about-to-be) sent `fee_range`. - otherwise, if `fee_satoshis` is not strictly between its last-sent `fee_satoshis` and its previously-received `fee_satoshis`, UNLESS it has since reconnected: - - SHOULD fail the connection. + - SHOULD send a `warning` and close the connection, or send an + `error` and fail the channel. - otherwise, if the receiver agrees with the fee: - SHOULD reply with a `closing_signed` with the same `fee_satoshis` value. - otherwise: @@ -888,6 +893,7 @@ An offering node: - MUST NOT offer an HTLC with a timeout deadline before its `cltv_expiry`. - if an HTLC which it offered is in either node's current commitment transaction, AND is past this timeout deadline: + - SHOULD send an `error` to the receiving peer (if connected). - MUST fail the channel. A fulfilling node: @@ -896,6 +902,7 @@ A fulfilling node: - MUST fail (and not forward) an HTLC whose fulfillment deadline is already past. - if an HTLC it has fulfilled is in either node's current commitment transaction, AND is past this fulfillment deadline: + - SHOULD send an `error` to the offering peer (if connected). - MUST fail the channel. ### Adding an HTLC: `update_add_htlc` @@ -959,19 +966,24 @@ been received). It MUST continue incrementing instead. A receiving node: - receiving an `amount_msat` equal to 0, OR less than its own `htlc_minimum_msat`: - - SHOULD fail the channel. + - SHOULD send a `warning` and close the connection, or send an + `error` and fail the channel. - 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 fail the channel. + - 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 fail the channel. + - SHOULD send a `warning` and close the connection, or send an + `error` and fail the channel. - if sending node sets `cltv_expiry` to greater or equal to 500000000: - - SHOULD fail the channel. + - SHOULD send a `warning` and close the connection, or send an + `error` and fail the channel. - MUST allow multiple HTLCs with the same `payment_hash`. - if the sender did not previously acknowledge the commitment of that HTLC: - MUST ignore a repeated `id` value after a reconnection. - if other `id` violations occur: - - MAY fail the channel. + - MAY send a `warning` and close the connection, or send an + `error` and fail the channel. The `onion_routing_packet` contains an obfuscated list of hops and instructions for each hop along the path. It commits to the HTLC by setting the `payment_hash` as associated data, i.e. includes the `payment_hash` in the computation of HMACs. @@ -1057,13 +1069,16 @@ A node: A receiving node: - if the `id` does not correspond to an HTLC in its current commitment transaction: - - MUST fail the channel. + - MUST send a `warning` and close the connection, or send an + `error` and fail the channel. - if the `payment_preimage` value in `update_fulfill_htlc` doesn't SHA256 hash to the corresponding HTLC `payment_hash`: - - MUST fail the channel. + - MUST send a `warning` and close the connection, or send an + `error` and fail the channel. - if the `BADONION` bit in `failure_code` is not set for `update_fail_malformed_htlc`: - - MUST fail the channel. + - MUST send a `warning` and close the connection, or send an + `error` and fail the channel. - if the `sha256_of_onion` in `update_fail_malformed_htlc` doesn't match the onion it sent: - MAY retry or choose an alternate error response. @@ -1122,12 +1137,15 @@ fee changes). A receiving node: - once all pending updates are applied: - if `signature` is not valid for its local commitment transaction OR non-compliant with LOW-S-standard rule [LOWS](https://github.com/bitcoin/bitcoin/pull/6769): - - MUST fail the channel. + - MUST send a `warning` and close the connection, or send an + `error` and fail the channel. - if `num_htlcs` is not equal to the number of HTLC outputs in the local commitment transaction: - - MUST fail the channel. + - MUST send a `warning` and close the connection, or send an + `error` and fail the channel. - if any `htlc_signature` is not valid for the corresponding HTLC transaction OR non-compliant with LOW-S-standard rule [LOWS](https://github.com/bitcoin/bitcoin/pull/6769): - - MUST fail the channel. + - MUST send a `warning` and close the connection, or send an + `error` and fail the channel. - MUST respond with a `revoke_and_ack` message. #### Rationale @@ -1181,9 +1199,10 @@ A sending node: A receiving node: - if `per_commitment_secret` is not a valid secret key or does not generate the previous `per_commitment_point`: - - MUST fail the channel. + - MUST send an `error` and fail the channel. - if the `per_commitment_secret` was not generated by the protocol in [BOLT #3](03-transactions.md#per-commitment-secret-requirements): - - MAY fail the channel. + - MAY send a `warning` and close the connection, or send an + `error` and fail the channel. A node: - MUST NOT broadcast old (revoked) commitment transactions, @@ -1225,12 +1244,15 @@ The node _not responsible_ for paying the Bitcoin fee: A receiving node: - if the `update_fee` is too low for timely processing, OR is unreasonably large: - - SHOULD fail the channel. + - MUST send a `warning` and close the connection, or send an + `error` and fail the channel. - if the sender is not responsible for paying the Bitcoin fee: - - MUST fail the channel. + - MUST send a `warning` and close the connection, or send an + `error` and fail the channel. - if the sender cannot afford the new fee rate on the receiving node's current commitment transaction: - - SHOULD fail the channel, + - SHOULD send a `warning` and close the connection, or send an + `error` and fail the channel. - but MAY delay this check until the `update_fee` is committed. #### Rationale @@ -1357,10 +1379,10 @@ A node: - if `next_commitment_number` is not 1 greater than the commitment number of the last `commitment_signed` message the receiving node has sent: - - SHOULD fail the channel. + - SHOULD send an `error` and fail the channel. - if it has not sent `commitment_signed`, AND `next_commitment_number` is not equal to 1: - - SHOULD fail the channel. + - SHOULD send an `error` and fail the channel. - if `next_revocation_number` is equal to the commitment number of the last `revoke_and_ack` the receiving node sent, AND the receiving node hasn't already received a `closing_signed`: @@ -1372,10 +1394,10 @@ A node: - otherwise: - if `next_revocation_number` is not equal to 1 greater than the commitment number of the last `revoke_and_ack` the receiving node has sent: - - SHOULD fail the channel. + - SHOULD send an `error` and fail the channel. - if it has not sent `revoke_and_ack`, AND `next_revocation_number` is not equal to 0: - - SHOULD fail the channel. + - SHOULD send an `error` and fail the channel. A receiving node: - if `option_static_remotekey` or `option_anchors` applies to the commitment @@ -1387,7 +1409,7 @@ A node: - SHOULD fail the channel. - otherwise: - if `your_last_per_commitment_secret` does not match the expected values: - - SHOULD fail the channel. + - SHOULD send an `error` and fail the channel. - otherwise, if it supports `option_data_loss_protect`: - if `next_revocation_number` is greater than expected above, AND `your_last_per_commitment_secret` is correct for that @@ -1398,7 +1420,7 @@ A node: should the sending node broadcast its commitment transaction on-chain. - otherwise (`your_last_per_commitment_secret` or `my_current_per_commitment_point` do not match the expected values): - - SHOULD fail the channel. + - SHOULD send an `error` and fail the channel. A node: - MUST NOT assume that previously-transmitted messages were lost, diff --git a/03-transactions.md b/03-transactions.md index af6590fd3..014888279 100644 --- a/03-transactions.md +++ b/03-transactions.md @@ -484,7 +484,8 @@ contribute to fees. A node: - if the resulting fee rate is too low: - - MAY fail the channel. + - MAY send a `warning` warn and close the connection, or send an + `error` and fail the channel. ## Dust Limits diff --git a/05-onchain.md b/05-onchain.md index 98c737926..08cd27efa 100644 --- a/05-onchain.md +++ b/05-onchain.md @@ -74,8 +74,8 @@ A node: reorganizations. - upon the funding transaction being spent, if the channel is NOT already closed: + - MAY send a descriptive `error`. - SHOULD fail the channel. - - MAY send a descriptive error packet. - SHOULD ignore invalid transactions. ## Rationale diff --git a/07-routing-gossip.md b/07-routing-gossip.md index 13919bd4e..d89287e8e 100644 --- a/07-routing-gossip.md +++ b/07-routing-gossip.md @@ -97,9 +97,11 @@ A node: A recipient node: - if the `short_channel_id` is NOT correct: - - SHOULD fail the channel. + - SHOULD send a `warning` and close the connection, or send an + `error` and fail the channel. - if the `node_signature` OR the `bitcoin_signature` is NOT correct: - - MAY fail the channel. + - MAY send a `warning` and close the connection, or send an + `error` and fail the channel. - if it has sent AND received a valid `announcement_signatures` message: - SHOULD queue the `channel_announcement` message for its peers. - if it has not sent funding_locked: @@ -201,7 +203,9 @@ The receiving node: - otherwise: - if `bitcoin_signature_1`, `bitcoin_signature_2`, `node_signature_1` OR `node_signature_2` are invalid OR NOT correct: - - SHOULD fail the connection. + - SHOULD send a `warning`. + - MAY close the connection. + - MUST ignore the message. - otherwise: - if `node_id_1` OR `node_id_2` are blacklisted: - SHOULD ignore the message. @@ -313,12 +317,14 @@ The origin node: The receiving node: - if `node_id` is NOT a valid compressed public key: - - SHOULD fail the connection. + - SHOULD send a `warning`. + - MAY close the connection. - MUST NOT process the message further. - if `signature` is NOT a valid signature (using `node_id` of the double-SHA256 of the entire message following the `signature` field, including any future fields appended to the end): - - SHOULD fail the connection. + - SHOULD send a `warning`. + - MAY close the connection. - MUST NOT process the message further. - if `features` field contains _unknown even bits_: - SHOULD NOT connect to the node. @@ -329,7 +335,8 @@ any future fields appended to the end): defined above. - if `addrlen` is insufficient to hold the address descriptors of the known types: - - SHOULD fail the connection. + - SHOULD send a `warning`. + - MAY close the connection. - if `port` is equal to 0: - SHOULD ignore `ipv6_addr` OR `ipv4_addr`. - if `node_id` is NOT previously known from a `channel_announcement` message, @@ -493,8 +500,8 @@ The receiving node: - if `signature` is not a valid signature, using `node_id` of the double-SHA256 of the entire message following the `signature` field (including unknown fields following `fee_proportional_millionths`): + - SHOULD send a `warning` and close the connection. - MUST NOT process the message further. - - SHOULD fail the connection. - if the specified `chain_hash` value is unknown (meaning it isn't active on the specified chain): - MUST ignore the channel update. @@ -504,7 +511,7 @@ The receiving node: - MAY blacklist this `node_id`. - MAY forget all channels associated with it. - if the fields below `timestamp` are equal: - - SHOULD ignore this message + - SHOULD ignore this message - if `timestamp` is lower than that of the last-received `channel_update` for this `short_channel_id` AND for `node_id`: - SHOULD ignore the message. @@ -644,16 +651,21 @@ The sender: The receiver: - if the first byte of `encoded_short_ids` is not a known encoding type: - - MAY fail the connection + - MAY send a `warning`. + - MAY close the connection. - if `encoded_short_ids` does not decode into a whole number of `short_channel_id`: - - MAY fail the connection. + - MAY send a `warning`. + - MAY close the connection. - if it has not sent `reply_short_channel_ids_end` to a previously received `query_short_channel_ids` from this sender: - - MAY fail the connection. + - MAY send a `warning`. + - MAY close the connection. - if the incoming message includes `query_short_channel_ids_tlvs`: - if `encoding_type` is not a known encoding type: - - MAY fail the connection + - MAY send a `warning`. + - MAY close the connection. - if `encoded_query_flags` does not decode to exactly one flag per `short_channel_id`: - - MAY fail the connection. + - MAY send a `warning`. + - MAY close the connection. - MUST respond to each known `short_channel_id`: - if the incoming message does not include `encoded_query_flags`: - with a `channel_announcement` and the latest `channel_update` for each end @@ -773,20 +785,21 @@ The sender of `query_channel_range`: The receiver of `query_channel_range`: - if it has not sent all `reply_channel_range` to a previously received `query_channel_range` from this sender: - - MAY fail the connection. + - MAY send a `warning`. + - MAY close the connection. - MUST respond with one or more `reply_channel_range`: - MUST set with `chain_hash` equal to that of `query_channel_range`, - MUST limit `number_of_blocks` to the maximum number of blocks whose results could fit in `encoded_short_ids` - MAY split block contents across multiple `reply_channel_range`. - the first `reply_channel_range` message: - - MUST set `first_blocknum` less than or equal to the `first_blocknum` in `query_channel_range` - - MUST set `first_blocknum` plus `number_of_blocks` greater than `first_blocknum` in `query_channel_range`. - - successive `reply_channel_range` message: - - MUST have `first_blocknum` equal or greater than the previous `first_blocknum`. + - MUST set `first_blocknum` less than or equal to the `first_blocknum` in `query_channel_range` + - MUST set `first_blocknum` plus `number_of_blocks` greater than `first_blocknum` in `query_channel_range`. + - successive `reply_channel_range` message: + - MUST have `first_blocknum` equal or greater than the previous `first_blocknum`. - MUST set `sync_complete` to `false` if this is not the final `reply_channel_range`. - - the final `reply_channel_range` message: - - MUST have `first_blocknum` plus `number_of_blocks` equal or greater than the `query_channel_range` `first_blocknum` plus `number_of_blocks`. + - the final `reply_channel_range` message: + - MUST have `first_blocknum` plus `number_of_blocks` equal or greater than the `query_channel_range` `first_blocknum` plus `number_of_blocks`. - MUST set `sync_complete` to `true`. If the incoming message includes `query_option`, the receiver MAY append additional information to its reply: From 4fc9f51889f36b53244f53b3b95e77171abd6308 Mon Sep 17 00:00:00 2001 From: Rusty Russell Date: Tue, 14 Dec 2021 10:32:24 +1030 Subject: [PATCH 3/5] Update 03-transactions.md Co-authored-by: Bastien Teinturier <31281497+t-bast@users.noreply.github.com> --- 03-transactions.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/03-transactions.md b/03-transactions.md index 014888279..282533236 100644 --- a/03-transactions.md +++ b/03-transactions.md @@ -484,7 +484,7 @@ contribute to fees. A node: - if the resulting fee rate is too low: - - MAY send a `warning` warn and close the connection, or send an + - MAY send a `warning` and close the connection, or send an `error` and fail the channel. ## Dust Limits @@ -2508,4 +2508,3 @@ before subtraction of: ![Creative Commons License](https://i.creativecommons.org/l/by/4.0/88x31.png "License CC-BY")
This work is licensed under a [Creative Commons Attribution 4.0 International License](http://creativecommons.org/licenses/by/4.0/). - From c36c14d6dae742944af743a971dcbcb7cef06d14 Mon Sep 17 00:00:00 2001 From: Rusty Russell Date: Tue, 14 Dec 2021 10:32:24 +1030 Subject: [PATCH 4/5] BOLT 2: Error instead of warning on shutdown on unopened channel. Abandoning channel is kinda what they want here. Reported-by: Matt Corallo Signed-off-by: Rusty Russell --- 02-peer-protocol.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 4206d311f..db5881c90 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -560,7 +560,7 @@ A sending node: A receiving node: - if it hasn't received a `funding_signed` (if it is a funder) or a `funding_created` (if it is a fundee): - - SHOULD send a `warning`. + - SHOULD send an `error` and fail the channel. - if the `scriptpubkey` is not in one of the above forms: - SHOULD send a `warning`. - if it hasn't sent a `funding_locked` yet: From 8032f70f571166368c4af7c024a7a75a8d6a03f4 Mon Sep 17 00:00:00 2001 From: Rusty Russell Date: Tue, 4 Jan 2022 05:55:42 +1030 Subject: [PATCH 5/5] BOLT 1: Restore all-zero error semantics There were valid uses for "I don't want to talk to you anymore" apparently! Also fixed some tabs -> spaces. Signed-off-by: Rusty Russell --- 01-messaging.md | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/01-messaging.md b/01-messaging.md index 59aa3dc57..84e402d70 100644 --- a/01-messaging.md +++ b/01-messaging.md @@ -324,6 +324,8 @@ For simplicity of diagnosis, it's often useful to tell a peer that something is #### Requirements +The channel is referred to by `channel_id`, unless `channel_id` is 0 (i.e. all bytes are 0), in which case it refers to all channels. + The funding node: - for all error messages sent before (and including) the `funding_created` message: - MUST use `temporary_channel_id` in lieu of `channel_id`. @@ -336,9 +338,10 @@ A sending node: - SHOULD send `error` for protocol violations or internal errors that make channels unusable or that make further communication unusable. - SHOULD send `error` with the unknown `channel_id` in reply to messages of type `32`-`255` related to unknown channels. - when sending `error`: - - MUST fail the channel referred to by the error message. + - MUST fail the channel(s) referred to by the error message. + - MAY set `channel_id` to all zero to indicate all channels. - when sending `warning`: - - MAY set `channel_id` to all zero if the warning is not related to a specific channel. + - MAY set `channel_id` to all zero if the warning is not related to a specific channel. - MAY close the connection after sending. - MAY send an empty `data` field. - when failure was caused by an invalid signature check: @@ -346,12 +349,15 @@ A sending node: The receiving node: - upon receiving `error`: - - MUST fail the channel referred to by `channel_id`, if that channel is with the sending node. + - if `channel_id` is all zero: + - MUST fail all channels with the sending node. + - otherwise: + - MUST fail the channel referred to by `channel_id`, if that channel is with the sending node. - upon receiving `warning`: - SHOULD log the message for later diagnosis. - - MAY disconnect. - - MAY reconnect after some delay to retry. - - MAY attempt `shutdown` if permitted at this point. + - MAY disconnect. + - MAY reconnect after some delay to retry. + - MAY attempt `shutdown` if permitted at this point. - if no existing channel is referred to by `channel_id`: - MUST ignore the message. - if `data` is not composed solely of printable ASCII characters (For reference: the printable character set includes byte values 32 through 126, inclusive):