mirrors/lightning-bolts
1
0
Fork 0
mirror of https://github.com/lightning/bolts.git synced 2025-01-18 13:22:35 +01:00
Code Issues Projects Releases Wiki Activity

Make it explicit when to send warnings, errors, fail channel and close connection.

Browse Source 
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 <rusty@rustcorp.com.au>
This commit is contained in:
Rusty Russell 2021-12-14 10:32:22 +10:30
parent 474b68caea
commit eb6f3084c5
6 changed files with 107 additions and 57 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
00-introduction.md
View File

@ -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)_

12
01-messaging.md
View File

@ -17,7 +17,7 @@ All data fields are unsigned big-endian unless otherwise specified.
* [Fundamental Types](#fundamental-types)
* [Setup Messages](#setup-messages)
* [The `init` Message](#the-init-message)
* [The `error` Message](#the-error-message)
* [The `error` and `warning` Messages](#the-error-and-warning-messages)
* [Control Messages](#control-messages)
* [The `ping` and `pong` Messages](#the-ping-and-pong-messages)
* [Appendix A: BigSize Test Vectors](#appendix-a-bigsize-test-vectors)
@ -285,11 +285,11 @@ The receiving node:
- upon receiving unknown _odd_ feature bits that are non-zero:
- MUST ignore the bit.
- upon receiving unknown _even_ feature bits that are non-zero:
- MUST fail the connection.
- MUST close the connection.
- upon receiving `networks` containing no common chains
- MAY fail the connection.
- MAY close the connection.
- if the feature vector does not set all known, transitive dependencies:
- MUST fail the connection.
- MUST close the connection.
#### Rationale
@ -404,7 +404,7 @@ A node sending a `ping` message:
- MUST NOT set `ignored` to sensitive data such as secrets or portions of initialized
memory.
- if it doesn't receive a corresponding `pong`:
- MAY terminate the network connection,
- MAY close the network connection,
- and MUST NOT fail the channels in this case.
A node sending a `pong` message:
@ -420,7 +420,7 @@ A node receiving a `ping` message:
A node receiving a `pong` message:
- if `byteslen` does not correspond to any `ping`'s `num_pong_bytes` value it has sent:
- MAY fail the channels.
- MAY close the connection.
### Rationale

80
02-peer-protocol.md
View File

@ -392,7 +392,8 @@ The sender:
The recipient:
- if `signature` is incorrect OR non-compliant with LOW-S-standard rule<sup>[LOWS](https://github.com/bitcoin/bitcoin/pull/6769)</sup>:
- 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<sup>[LOWS](https://github.com/bitcoin/bitcoin/pull/6769)</sup>:
- MUST fail the channel.
- MUST send a `warning` and close the connection, or send an
`error` and fail the channel.
- MUST NOT broadcast the funding transaction before receipt of a valid `funding_signed`.
- on receipt of a valid `funding_signed`:
- SHOULD broadcast the funding transaction.
@ -484,7 +486,7 @@ A non-funding node (fundee):
transaction after a timeout of 2016 blocks.
From the point of waiting for `funding_locked` onward, either node MAY
fail the channel if it does not receive a required response from the
send an `error` and fail the channel if it does not receive a required response from the
other node after a reasonable timeout.
#### Rationale
@ -558,14 +560,15 @@ A sending node:
A receiving node:
- if it hasn't received a `funding_signed` (if it is a funder) or a `funding_created` (if it is a fundee):
- SHOULD fail the connection
- SHOULD send a `warning`.
- if the `scriptpubkey` is not in one of the above forms:
- SHOULD fail the connection.
- SHOULD send a `warning`.
- if it hasn't sent a `funding_locked` yet:
- MAY reply to a `shutdown` message with a `shutdown`
- once there are no outstanding updates on the peer, UNLESS it has already sent a `shutdown`:
- MUST reply to a `shutdown` message with a `shutdown`
- if both nodes advertised the `option_upfront_shutdown_script` feature, and the receiving node received a non-zero-length `shutdown_scriptpubkey` in `open_channel` or `accept_channel`, and that `shutdown_scriptpubkey` is not equal to `scriptpubkey`:
- MAY send a `warning`.
- MUST fail the connection.
#### Rationale
@ -647,7 +650,8 @@ The sending node:
The receiving node:
- if the `signature` is not valid for either variant of closing transaction
specified in [BOLT #3](03-transactions.md#closing-transaction) OR non-compliant with LOW-S-standard rule<sup>[LOWS](https://github.com/bitcoin/bitcoin/pull/6769)</sup>:
- 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 <sup>[LOWS](https://github.com/bitcoin/bitcoin/pull/6769)</sup>:
- 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 <sup>[LOWS](https://github.com/bitcoin/bitcoin/pull/6769)</sup>:
- 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,

3
03-transactions.md
View File

@ -484,7 +484,8 @@ contribute to fees.
A node:
- if the resulting fee rate is too low:
- MAY fail the channel.
- MAY send a `warning` warn and close the connection, or send an
`error` and fail the channel.
## Dust Limits

2
05-onchain.md
View File

@ -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

53
07-routing-gossip.md
View File

@ -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: