From 528805b4827b858b1e9fb1b9bd6ef8ff78780238 Mon Sep 17 00:00:00 2001 From: Rusty Russell Date: Thu, 21 Jan 2021 15:07:38 +1030 Subject: [PATCH] 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 | 14 +++---- 02-peer-protocol.md | 92 ++++++++++++++++++++++++++++---------------- 03-transactions.md | 3 +- 05-onchain.md | 2 +- 07-routing-gossip.md | 53 +++++++++++++++---------- 6 files changed, 115 insertions(+), 63 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 cb95c8822..66232ab3c 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) @@ -279,11 +279,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 @@ -398,7 +398,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. - SHOULD NOT send `ping` messages more often than once every 30 seconds. @@ -408,7 +408,7 @@ A node sending a `pong` message: memory. A node receiving a `ping` message: - - SHOULD fail the channels if it has received significantly in excess of one `ping` per 30 seconds. + - SHOULD close the connection if it has received significantly in excess of one `ping` per 30 seconds. - if `num_pong_bytes` is less than 65532: - MUST respond by sending a `pong` message, with `byteslen` equal to `num_pong_bytes`. - otherwise (`num_pong_bytes` is **not** less than 65532): @@ -416,7 +416,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 842274074..b655b9572 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -321,9 +321,9 @@ The receiver: - if `minimum_depth` is unreasonably large: - MAY reject the channel. - if `channel_reserve_satoshis` is less than `dust_limit_satoshis` within the `open_channel` message: - - MUST reject the channel. + - MUST reject the channel. - if `channel_reserve_satoshis` from the `open_channel` message is less than `dust_limit_satoshis`: - - MUST reject the channel. + - MUST reject the channel. Other fields have the same requirements as their counterparts in `open_channel`. ### The `funding_created` Message @@ -354,7 +354,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 @@ -389,7 +390,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. @@ -427,7 +429,7 @@ A non-funding node (fundee): funding transaction after a reasonable timeout. 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 @@ -482,7 +484,7 @@ A sending node: - MUST NOT send a `shutdown`. - MUST NOT send an `update_add_htlc` after a `shutdown`. - if no HTLCs remain in either commitment transaction: - - MUST NOT send any `update` message after a `shutdown`. + - MUST NOT send any `update` message after a `shutdown`. - SHOULD fail to route any HTLC added after it has sent `shutdown`. - if it sent a non-zero-length `shutdown_scriptpubkey` in `open_channel` or `accept_channel`: - MUST send the same value in `scriptpubkey`. @@ -496,14 +498,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 @@ -565,18 +568,21 @@ 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. - otherwise, if `fee_satoshis` is greater than the base fee of the final commitment transaction as calculated in [BOLT #3](03-transactions.md#fee-calculation): - - MUST fail the connection. + - MUST send a `warning` and close the connection, or send an + `error` and fail the channel. - 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. - if the receiver agrees with the fee: - SHOULD reply with a `closing_signed` with the same `fee_satoshis` value. - otherwise: @@ -776,6 +782,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: @@ -784,6 +791,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` @@ -849,21 +857,27 @@ 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. + - MUST 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. + - MUST send a `warning` and close the connection, or send an + `error` and fail the channel. - for channels with `chain_hash` identifying the Bitcoin blockchain, if the four most significant bytes of `amount_msat` are not 0: - - MUST fail the channel. + - MUST 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. @@ -953,13 +967,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. @@ -1018,12 +1035,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 @@ -1073,9 +1093,10 @@ A sending node: A receiving node: - if `per_commitment_secret` 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, @@ -1117,12 +1138,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 @@ -1248,10 +1272,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`: @@ -1263,10 +1287,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` applies to the commitment transaction: @@ -1277,7 +1301,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 @@ -1288,7 +1312,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 0a51e3bb8..88c65e401 100644 --- a/03-transactions.md +++ b/03-transactions.md @@ -475,7 +475,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. ## Commitment Transaction Construction diff --git a/05-onchain.md b/05-onchain.md index d1d6a757c..1e199b76b 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 a27c2cd60..bf8edad6a 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. @@ -315,12 +319,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. @@ -331,7 +337,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, @@ -496,8 +503,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. @@ -507,7 +514,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. @@ -647,16 +654,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 @@ -776,7 +788,8 @@ 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 @@ -786,12 +799,12 @@ The receiver of `query_channel_range`: - otherwise: - SHOULD set `full_information` to 1. - 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 set `first_blocknum` to the previous `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 `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 set `first_blocknum` to the previous `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`. If the incoming message includes `query_option`, the receiver MAY append additional information to its reply: - if bit 0 in `query_option_flags` is set, the receiver MAY append a `timestamps_tlv` that contains `channel_update` timestamps for all `short_chanel_id`s in `encoded_short_ids`