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`