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 867fe002d..84e402d70 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 @@ -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,7 +316,11 @@ 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 @@ -331,24 +335,31 @@ 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(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 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: + - 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. + - 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 +370,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. @@ -394,7 +410,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: @@ -410,7 +426,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..db5881c90 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 an `error` and fail the channel. - 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..282533236 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` and close the connection, or send an + `error` and fail the channel. ## Dust Limits @@ -2507,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/). - 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: