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`