From c77eda6d64b6092cc1fd26ae93798acc40d6414e Mon Sep 17 00:00:00 2001 From: Vincenzo Palazzo Date: Wed, 6 Apr 2022 20:32:57 +0200 Subject: [PATCH] pyln-spec: upgrade to the last bolt version Changelog-Fixed: pyln-spec: update the bolts implementation Signed-off-by: Vincenzo Palazzo --- .../pyln-spec/bolt1/pyln/spec/bolt1/csv.py | 4 + .../bolt1/pyln/spec/bolt1/gen_csv_version.py | 2 +- .../bolt1/pyln/spec/bolt1/gen_version.py | 4 +- .../pyln-spec/bolt1/pyln/spec/bolt1/text.py | 76 +++++--- .../bolt2/pyln/spec/bolt2/gen_version.py | 4 +- .../pyln-spec/bolt2/pyln/spec/bolt2/text.py | 166 +++++++++++------- .../pyln-spec/bolt4/pyln/spec/bolt4/csv.py | 2 + .../bolt4/pyln/spec/bolt4/gen_csv_version.py | 2 +- .../bolt4/pyln/spec/bolt4/gen_version.py | 4 +- .../pyln-spec/bolt4/pyln/spec/bolt4/text.py | 15 +- .../pyln-spec/bolt7/pyln/spec/bolt7/csv.py | 2 +- .../bolt7/pyln/spec/bolt7/gen_csv_version.py | 2 +- .../bolt7/pyln/spec/bolt7/gen_version.py | 4 +- .../pyln-spec/bolt7/pyln/spec/bolt7/text.py | 84 ++++----- 14 files changed, 230 insertions(+), 141 deletions(-) diff --git a/contrib/pyln-spec/bolt1/pyln/spec/bolt1/csv.py b/contrib/pyln-spec/bolt1/pyln/spec/bolt1/csv.py index eda2a5862644..cecb380b6afe 100644 --- a/contrib/pyln-spec/bolt1/pyln/spec/bolt1/csv.py +++ b/contrib/pyln-spec/bolt1/pyln/spec/bolt1/csv.py @@ -13,6 +13,10 @@ "msgdata,error,channel_id,channel_id,", "msgdata,error,len,u16,", "msgdata,error,data,byte,len", + "msgtype,warning,1", + "msgdata,warning,channel_id,channel_id,", + "msgdata,warning,len,u16,", + "msgdata,warning,data,byte,len", "msgtype,ping,18", "msgdata,ping,num_pong_bytes,u16,", "msgdata,ping,byteslen,u16,", diff --git a/contrib/pyln-spec/bolt1/pyln/spec/bolt1/gen_csv_version.py b/contrib/pyln-spec/bolt1/pyln/spec/bolt1/gen_csv_version.py index 0741f08250cc..2140fc8212ff 100644 --- a/contrib/pyln-spec/bolt1/pyln/spec/bolt1/gen_csv_version.py +++ b/contrib/pyln-spec/bolt1/pyln/spec/bolt1/gen_csv_version.py @@ -1 +1 @@ -__csv_version__ = "1" +__csv_version__ = "2" diff --git a/contrib/pyln-spec/bolt1/pyln/spec/bolt1/gen_version.py b/contrib/pyln-spec/bolt1/pyln/spec/bolt1/gen_version.py index cb11f894225b..3377756caf44 100644 --- a/contrib/pyln-spec/bolt1/pyln/spec/bolt1/gen_version.py +++ b/contrib/pyln-spec/bolt1/pyln/spec/bolt1/gen_version.py @@ -1,3 +1,3 @@ __base_version__ = "1.0" -__post_version__ = "186" -__gitversion__ = "38abac62065172c00722dca10e7d3fc3049afd72" +__post_version__ = "222" +__gitversion__ = "f1c797df2966237244527c1c6343dbe9bc765342" diff --git a/contrib/pyln-spec/bolt1/pyln/spec/bolt1/text.py b/contrib/pyln-spec/bolt1/pyln/spec/bolt1/text.py index d5a2e99efae2..721c6ac76a35 100644 --- a/contrib/pyln-spec/bolt1/pyln/spec/bolt1/text.py +++ b/contrib/pyln-spec/bolt1/pyln/spec/bolt1/text.py @@ -18,7 +18,7 @@ * [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) @@ -226,6 +226,12 @@ * `tu32`: a 0 to 4 byte unsigned integer * `tu64`: a 0 to 8 byte unsigned integer +When used to encode amounts, the previous fields MUST comply with the upper +bound of 21 million BTC: + +* satoshi amounts MUST be at most `0x000775f05a074000` +* milli-satoshi amounts MUST be at most `0x1d24b2dfac520000` + The following convenience types are also defined: * `chain_hash`: a 32-byte chain identifier (see [BOLT #0](00-introduction.md#glossary-and-terminology-guide)) @@ -259,9 +265,12 @@ 1. type: 1 (`networks`) 2. data: * [`...*chain_hash`:`chains`] - + 1. type: 3 (`remote_addr`) + 2. data: + * [`...*byte`:`data`] The optional `networks` indicates the chains the node is interested in. +The optional `remote_addr` can be used to circumvent NAT issues. #### Requirements @@ -272,6 +281,12 @@ - SHOULD NOT set features greater than 13 in `globalfeatures`. - SHOULD use the minimum length required to represent the `features` field. - SHOULD set `networks` to all chains it will gossip or open channels for. + - SHOULD set `remote_addr` to reflect the remote IP address (and port) of an + incoming connection, if the node is the receiver and the connection was done + via IP. + - if it sets `remote_addr`: + - MUST set it to a valid `address descriptor` (1 byte type and data) as described in [BOLT 7](07-routing-gossip.md#the-node_announcement-message). + - SHOULD NOT set private addresses as `remote_addr`. The receiving node: - MUST wait to receive `init` before sending any other messages. @@ -280,11 +295,12 @@ - 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. + - MAY use the `remote_addr` to update its `node_announcement` #### Rationale @@ -301,7 +317,7 @@ 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. @@ -311,7 +327,11 @@ * [`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 @@ -326,24 +346,31 @@ - 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. @@ -354,6 +381,11 @@ 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. @@ -389,9 +421,8 @@ - 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. A node sending a `pong` message: - SHOULD set `ignored` to 0s. @@ -399,7 +430,6 @@ memory. A node receiving a `ping` message: - - SHOULD fail the channels 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): @@ -407,7 +437,7 @@ 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 @@ -913,13 +943,13 @@ The following `init` messages are valid: - `0x001000000000`: no extension provided -- `0x00100000000001012a030104`: the extension contains two _odd_ TLV records (with types `0x01` and `0x03`) +- `0x001000000000c9012acb0104`: the extension contains two unknown _odd_ TLV records (with types `0xc9` and `0xcb`) The following `init` messages are invalid: - `0x00100000000001`: the extension is present but truncated -- `0x00100000000002012a`: the extension contains unknown _even_ TLV records (assuming that TLV type `0x02` is unknown) -- `0x001000000000010101010102`: the extension TLV stream is invalid (duplicate TLV record type `0x01`) +- `0x001000000000ca012a`: the extension contains unknown _even_ TLV records (assuming that TLV type `0xca` is unknown) +- `0x001000000000c90101c90102`: the extension TLV stream is invalid (duplicate TLV record type `0xc9`) Note that when messages are signed, the _extension_ is part of the signed bytes. Nodes should store the _extension_ bytes even if they don't understand them to diff --git a/contrib/pyln-spec/bolt2/pyln/spec/bolt2/gen_version.py b/contrib/pyln-spec/bolt2/pyln/spec/bolt2/gen_version.py index cb11f894225b..3377756caf44 100644 --- a/contrib/pyln-spec/bolt2/pyln/spec/bolt2/gen_version.py +++ b/contrib/pyln-spec/bolt2/pyln/spec/bolt2/gen_version.py @@ -1,3 +1,3 @@ __base_version__ = "1.0" -__post_version__ = "186" -__gitversion__ = "38abac62065172c00722dca10e7d3fc3049afd72" +__post_version__ = "222" +__gitversion__ = "f1c797df2966237244527c1c6343dbe9bc765342" diff --git a/contrib/pyln-spec/bolt2/pyln/spec/bolt2/text.py b/contrib/pyln-spec/bolt2/pyln/spec/bolt2/text.py index b6a9305891eb..66ba1fbb4e22 100644 --- a/contrib/pyln-spec/bolt2/pyln/spec/bolt2/text.py +++ b/contrib/pyln-spec/bolt2/pyln/spec/bolt2/text.py @@ -234,6 +234,8 @@ - MAY include `upfront_shutdown_script`. - if it includes `open_channel_tlvs`: - MUST include `upfront_shutdown_script`. + - if `option_channel_type` is negotiated: + - MUST set `channel_type` - if it includes `channel_type`: - MUST set it to a defined type representing the type it wants. - MUST use the smallest bitmap possible to represent the channel type. @@ -253,13 +255,14 @@ - discard the previous `open_channel` message. The receiving node MAY fail the channel if: + - `option_channel_type` was negotiated but the message doesn't include a `channel_type` - `announce_channel` is `false` (`0`), yet it wishes to publicly announce the channel. - `funding_satoshis` is too small. - it considers `htlc_minimum_msat` too large. - it considers `max_htlc_value_in_flight_msat` too small. - it considers `channel_reserve_satoshis` too large. - it considers `max_accepted_htlcs` too small. - - it considers `dust_limit_satoshis` too small and plans to rely on the sending node publishing its commitment transaction in the event of a data loss (see [message-retransmission](02-peer-protocol.md#message-retransmission)). + - it considers `dust_limit_satoshis` too large. The receiving node MUST fail the channel if: - the `chain_hash` value is set to a hash of a chain that is unknown to the receiver. @@ -270,6 +273,7 @@ - `funding_pubkey`, `revocation_basepoint`, `htlc_basepoint`, `payment_basepoint`, or `delayed_payment_basepoint` are not valid secp256k1 pubkeys in compressed format. - `dust_limit_satoshis` is greater than `channel_reserve_satoshis`. + - `dust_limit_satoshis` is smaller than `354 satoshis` (see [BOLT 3](03-transactions.md#dust-limits)). - the funder's amount for the initial commitment transaction is not sufficient for full [fee payment](03-transactions.md#fee-payment). - both `to_local` and `to_remote` amounts for the initial commitment transaction are less than or equal to `channel_reserve_satoshis` (see [BOLT 3](03-transactions.md#commitment-transaction-outputs)). - `funding_satoshis` is greater than or equal to 2^24 and the receiver does not support `option_support_large_channel`. @@ -280,7 +284,7 @@ #### Rationale -The requirement for `funding_satoshis` to be less than 2^24 satoshi was a temporary self-imposed limit while implementations were not yet considered stable, it can be lifted by advertising `option_support_large_channel`. +The requirement for `funding_satoshis` to be less than 2^24 satoshi was a temporary self-imposed limit while implementations were not yet considered stable, it can be lifted by advertising `option_support_large_channel`. The *channel reserve* is specified by the peer's `channel_reserve_satoshis`: 1% of the channel total is suggested. Each side of a channel maintains this reserve so it always has something to lose if it were to try to broadcast an old, revoked commitment transaction. Initially, this reserve may not be met, as only one side has funds; but the protocol ensures that there is always progress toward meeting this reserve, and once met, it is maintained. @@ -296,6 +300,10 @@ `accept_channel` ensure that both sides' `channel_reserve_satoshis` are above both `dust_limit_satoshis`. +The receiver should not accept large `dust_limit_satoshis`, as this could be +used in griefing attacks, where the peer publishes its commitment with a lot +of dust htlcs, which effectively become miner fees. + Details for how to handle a channel failure can be found in [BOLT 5:Failing a Channel](05-onchain.md#failing-a-channel). ### The `accept_channel` Message @@ -341,8 +349,8 @@ avoid double-spending of the funding transaction. - MUST set `channel_reserve_satoshis` greater than or equal to `dust_limit_satoshis` from the `open_channel` message. - MUST set `dust_limit_satoshis` less than or equal to `channel_reserve_satoshis` from the `open_channel` message. - - if it sets `channel_type`: - - MUST set it to the `channel_type` from `open_channel` + - if `option_channel_type` was negotiated: + - MUST set `channel_type` to the `channel_type` from `open_channel` The receiver: - if `minimum_depth` is unreasonably large: @@ -353,7 +361,8 @@ - MUST reject the channel. - if `channel_type` is set, and `channel_type` was set in `open_channel`, and they are not equal types: - MUST reject the channel. - + - if `option_channel_type` was negotiated but the message doesn't include a `channel_type`: + - MAY reject the channel. Other fields have the same requirements as their counterparts in `open_channel`. @@ -386,7 +395,8 @@ 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 @@ -432,7 +442,8 @@ 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. @@ -450,7 +461,7 @@ `option_anchors_zero_fee_htlc_tx` is considered superior to `option_anchor_outputs`, which again is considered superior to -`option_static_remotekey`, and the superior one is is favored if more than one +`option_static_remotekey`, and the superior one is favored if more than one is negotiated. ### The `funding_locked` Message @@ -478,7 +489,7 @@ 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 @@ -544,25 +555,23 @@ - MUST send the same value in `scriptpubkey`. - MUST set `scriptpubkey` in one of the following forms: - 1. `OP_DUP` `OP_HASH160` `20` 20-bytes `OP_EQUALVERIFY` `OP_CHECKSIG` - (pay to pubkey hash), OR - 2. `OP_HASH160` `20` 20-bytes `OP_EQUAL` (pay to script hash), OR - 3. `OP_0` `20` 20-bytes (version 0 pay to witness pubkey hash), OR - 4. `OP_0` `32` 32-bytes (version 0 pay to witness script hash), OR - 5. if (and only if) `option_shutdown_anysegwit` is negotiated: + 1. `OP_0` `20` 20-bytes (version 0 pay to witness pubkey hash), OR + 2. `OP_0` `32` 32-bytes (version 0 pay to witness script hash), OR + 3. if (and only if) `option_shutdown_anysegwit` is negotiated: * `OP_1` through `OP_16` inclusive, followed by a single push of 2 to 40 bytes (witness program versions 1 through 16) 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 @@ -577,9 +586,11 @@ to the commitment transaction (in particular, `update_fee` would be possible otherwise). -The `scriptpubkey` forms include only standard forms accepted by the -Bitcoin network, which ensures the resulting transaction will -propagate to miners. +The `scriptpubkey` forms include only standard segwit forms accepted by +the Bitcoin network, which ensures the resulting transaction will +propagate to miners. However old nodes may send non-segwit scripts, which +may be accepted for backwards-compatibility (with a caveat to force-close +if this output doesn't meet dust relay requirements). The `option_upfront_shutdown_script` feature means that the node wanted to pre-commit to `shutdown_scriptpubkey` in case it was @@ -601,7 +612,7 @@ exchange continues until both agree on the same fee or when one side fails the channel. -In the modern method, the funder sends its permissable fee range, and the +In the modern method, the funder sends its permissible fee range, and the non-funder has to pick a fee in this range. If the non-funder chooses the same value, negotiation is complete after two messages, otherwise the funder will reply with the same value (completing after three messages). @@ -642,7 +653,8 @@ 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. @@ -652,7 +664,7 @@ - MAY close the connection. - if the message contains a `fee_range`: - if there is no overlap between that and its own `fee_range`: - - SHOULD fail the connection + - SHOULD send a warning - MUST fail the channel if it doesn't receive a satisfying `fee_range` after a reasonable amount of time - otherwise: - if it is the funder: @@ -668,13 +680,18 @@ - 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: - MUST propose a value "strictly between" the received `fee_satoshis` and its previously-sent `fee_satoshis`. +The receiving node: + - if one of the outputs in the closing transaction is below the dust limit for its `scriptpubkey` (see [BOLT 3](03-transactions.md#dust-limits)): + - MUST fail the channel + #### Rationale When `fee_range` is not provided, the "strictly between" requirement ensures @@ -691,6 +708,12 @@ that the transaction propagates. It can always use CPFP later to speed up confirmation if necessary, so that minimum should be low. +It may happen that the closing transaction doesn't meet bitcoin's default relay +policies (e.g. when using a non-segwit shutdown script for an output below 546 +satoshis, which is possible if `dust_limit_satoshis` is below 546 satoshis). +No funds are at risk when that happens, but the channel must be force-closed as +the closing transaction will likely never reach miners. + ## Normal Operation Once both nodes have exchanged `funding_locked` (and optionally [`announcement_signatures`](07-routing-gossip.md#the-announcement_signatures-message)), the channel can be used to make payments via Hashed Time Locked Contracts. @@ -873,6 +896,7 @@ - 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: @@ -881,6 +905,7 @@ - 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` @@ -944,19 +969,24 @@ 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. @@ -1042,13 +1072,16 @@ 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. @@ -1107,12 +1140,15 @@ 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 @@ -1166,9 +1202,10 @@ 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, @@ -1210,12 +1247,15 @@ 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 @@ -1315,7 +1355,7 @@ next `commitment_signed` it expects to receive. - MUST set `next_revocation_number` to the commitment number of the next `revoke_and_ack` message it expects to receive. - - if `option_static_remotekey` or `option_anchors` applies to the commitment + - if `option_static_remotekey` applies to the commitment transaction: - MUST set `my_current_per_commitment_point` to a valid point. - otherwise: @@ -1342,10 +1382,10 @@ - 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`: @@ -1357,33 +1397,32 @@ - 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 - transaction: + - if `option_static_remotekey` applies to the commitment transaction: - if `next_revocation_number` is greater than expected above, AND `your_last_per_commitment_secret` is correct for that `next_revocation_number` minus 1: - MUST NOT broadcast its commitment transaction. - - SHOULD fail the channel. + - SHOULD send an `error` to request the peer to 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 `next_revocation_number` minus 1: - MUST NOT broadcast its commitment transaction. - - SHOULD fail the channel. + - SHOULD send an `error` to request the peer to fail the channel. - SHOULD store `my_current_per_commitment_point` to retrieve funds 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, @@ -1454,18 +1493,19 @@ remember a channel that never opens (and times out) than to let the funder open it while the fundee has forgotten it. -`option_data_loss_protect` was added to allow a node, which has somehow fallen behind -(e.g. has been restored from old backup), to detect that it's fallen-behind. A fallen-behind -node must know it cannot broadcast its current commitment transaction — which would lead to -total loss of funds — as the remote node can prove it knows the -revocation preimage. The error returned by the fallen-behind node -(or simply the invalid numbers in the `channel_reestablish` it has -sent) should make the other node drop its current commitment -transaction to the chain. This will, at least, allow the fallen-behind node to recover -non-HTLC funds, if the `my_current_per_commitment_point` -is valid. However, this also means the fallen-behind node has revealed this -fact (though not provably: it could be lying), and the other node could use this to -broadcast a previous state. +`option_data_loss_protect` was added to allow a node, which has somehow fallen +behind (e.g. has been restored from old backup), to detect that it has fallen +behind. A fallen-behind node must know it cannot broadcast its current +commitment transaction — which would lead to total loss of funds — as the +remote node can prove it knows the revocation preimage. The `error` returned by +the fallen-behind node should make the other node drop its current commitment +transaction to the chain. The other node should wait for that `error` to give +the fallen-behind node an opportunity to fix its state first (e.g by restarting +with a different backup). If the fallen-behind node doesn't have the latest +backup, this will, at least, allow it to recover non-HTLC funds, if the +`my_current_per_commitment_point` is valid. However, this also means the +fallen-behind node has revealed this fact (though not provably: it could be lying), +and the other node could use this to broadcast a previous state. `option_static_remotekey` removes the changing `to_remote` key, so the `my_current_per_commitment_point` is unnecessary and thus diff --git a/contrib/pyln-spec/bolt4/pyln/spec/bolt4/csv.py b/contrib/pyln-spec/bolt4/pyln/spec/bolt4/csv.py index fbc4f6f7e04b..b6458142ab21 100644 --- a/contrib/pyln-spec/bolt4/pyln/spec/bolt4/csv.py +++ b/contrib/pyln-spec/bolt4/pyln/spec/bolt4/csv.py @@ -8,6 +8,8 @@ "tlvtype,tlv_payload,payment_data,8", "tlvdata,tlv_payload,payment_data,payment_secret,byte,32", "tlvdata,tlv_payload,payment_data,total_msat,tu64,", + "tlvtype,tlv_payload,payment_metadata,16", + "tlvdata,tlv_payload,payment_metadata,payment_metadata,byte,...", "msgtype,invalid_realm,PERM|1", "msgtype,temporary_node_failure,NODE|2", "msgtype,permanent_node_failure,PERM|NODE|2", diff --git a/contrib/pyln-spec/bolt4/pyln/spec/bolt4/gen_csv_version.py b/contrib/pyln-spec/bolt4/pyln/spec/bolt4/gen_csv_version.py index 2140fc8212ff..fec7e9616295 100644 --- a/contrib/pyln-spec/bolt4/pyln/spec/bolt4/gen_csv_version.py +++ b/contrib/pyln-spec/bolt4/pyln/spec/bolt4/gen_csv_version.py @@ -1 +1 @@ -__csv_version__ = "2" +__csv_version__ = "3" diff --git a/contrib/pyln-spec/bolt4/pyln/spec/bolt4/gen_version.py b/contrib/pyln-spec/bolt4/pyln/spec/bolt4/gen_version.py index cb11f894225b..3377756caf44 100644 --- a/contrib/pyln-spec/bolt4/pyln/spec/bolt4/gen_version.py +++ b/contrib/pyln-spec/bolt4/pyln/spec/bolt4/gen_version.py @@ -1,3 +1,3 @@ __base_version__ = "1.0" -__post_version__ = "186" -__gitversion__ = "38abac62065172c00722dca10e7d3fc3049afd72" +__post_version__ = "222" +__gitversion__ = "f1c797df2966237244527c1c6343dbe9bc765342" diff --git a/contrib/pyln-spec/bolt4/pyln/spec/bolt4/text.py b/contrib/pyln-spec/bolt4/pyln/spec/bolt4/text.py index bfbde39c9e07..398e908a8659 100644 --- a/contrib/pyln-spec/bolt4/pyln/spec/bolt4/text.py +++ b/contrib/pyln-spec/bolt4/pyln/spec/bolt4/text.py @@ -264,6 +264,9 @@ 2. data: * [`32*byte`:`payment_secret`] * [`tu64`:`total_msat`] + 1. type: 16 (`payment_metadata`) + 2. data: + * [`...*byte`:`payment_metadata`] ### Requirements @@ -281,6 +284,9 @@ - MUST include `payment_data` - MUST set `payment_secret` to the one provided - MUST set `total_msat` to the total amount it will send + - if the recipient provided `payment_metadata`: + - MUST include `payment_metadata` with every HTLC + - MUST not apply any limits to the size of payment_metadata except the limits implied by the fixed onion size The reader: - MUST return an error if `amt_to_forward` or `outgoing_cltv_value` are not present. @@ -303,6 +309,9 @@ HTLCs; we call these outstanding HTLCs which have the same preimage, an "HTLC set". +`payment_metadata` is to be included in every payment part, so that +invalid payment details can be detected as early as possible. + #### Requirements The writer: @@ -658,7 +667,7 @@ Comparison of the computed HMAC and the packet's HMAC MUST be time-constant to avoid information leaks. -At this point, the processing node can generate a _rho_-key and a _gamma_-key. +At this point, the processing node can generate a _rho_-key. The routing information is then deobfuscated, and the information about the next hop is extracted. @@ -949,9 +958,9 @@ * [`u32`:`height`] The `payment_hash` is unknown to the final node, the `payment_secret` doesn't -match the `payment_hash`, the amount for that `payment_hash` is incorrect or +match the `payment_hash`, the amount for that `payment_hash` is incorrect, the CLTV expiry of the htlc is too close to the current block height for safe -handling. +handling or `payment_metadata` isn't present while it should be. The `htlc_msat` parameter is superfluous, but left in for backwards compatibility. The value of `htlc_msat` always matches the amount specified in diff --git a/contrib/pyln-spec/bolt7/pyln/spec/bolt7/csv.py b/contrib/pyln-spec/bolt7/pyln/spec/bolt7/csv.py index a27d109ec42e..d94248c545a7 100644 --- a/contrib/pyln-spec/bolt7/pyln/spec/bolt7/csv.py +++ b/contrib/pyln-spec/bolt7/pyln/spec/bolt7/csv.py @@ -61,7 +61,7 @@ "msgdata,reply_channel_range,chain_hash,chain_hash,", "msgdata,reply_channel_range,first_blocknum,u32,", "msgdata,reply_channel_range,number_of_blocks,u32,", - "msgdata,reply_channel_range,full_information,byte,", + "msgdata,reply_channel_range,sync_complete,byte,", "msgdata,reply_channel_range,len,u16,", "msgdata,reply_channel_range,encoded_short_ids,byte,len", "msgdata,reply_channel_range,tlvs,reply_channel_range_tlvs,", diff --git a/contrib/pyln-spec/bolt7/pyln/spec/bolt7/gen_csv_version.py b/contrib/pyln-spec/bolt7/pyln/spec/bolt7/gen_csv_version.py index 2140fc8212ff..fec7e9616295 100644 --- a/contrib/pyln-spec/bolt7/pyln/spec/bolt7/gen_csv_version.py +++ b/contrib/pyln-spec/bolt7/pyln/spec/bolt7/gen_csv_version.py @@ -1 +1 @@ -__csv_version__ = "2" +__csv_version__ = "3" diff --git a/contrib/pyln-spec/bolt7/pyln/spec/bolt7/gen_version.py b/contrib/pyln-spec/bolt7/pyln/spec/bolt7/gen_version.py index cb11f894225b..3377756caf44 100644 --- a/contrib/pyln-spec/bolt7/pyln/spec/bolt7/gen_version.py +++ b/contrib/pyln-spec/bolt7/pyln/spec/bolt7/gen_version.py @@ -1,3 +1,3 @@ __base_version__ = "1.0" -__post_version__ = "186" -__gitversion__ = "38abac62065172c00722dca10e7d3fc3049afd72" +__post_version__ = "222" +__gitversion__ = "f1c797df2966237244527c1c6343dbe9bc765342" diff --git a/contrib/pyln-spec/bolt7/pyln/spec/bolt7/text.py b/contrib/pyln-spec/bolt7/pyln/spec/bolt7/text.py index 96cbb4979ba8..84c430ec8a2b 100644 --- a/contrib/pyln-spec/bolt7/pyln/spec/bolt7/text.py +++ b/contrib/pyln-spec/bolt7/pyln/spec/bolt7/text.py @@ -98,9 +98,11 @@ 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: @@ -202,7 +204,9 @@ - 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. @@ -277,10 +281,7 @@ * `1`: ipv4; data = `[4:ipv4_addr][2:port]` (length 6) * `2`: ipv6; data = `[16:ipv6_addr][2:port]` (length 18) - * `3`: Tor v2 onion service; data = `[10:onion_addr][2:port]` (length 12) - * version 2 onion service addresses; Encodes an 80-bit, truncated `SHA-1` - hash of a 1024-bit `RSA` public key for the onion service (a.k.a. Tor - hidden service). + * `3`: Deprecated (length 12). Used to contain Tor v2 onion services. * `4`: Tor v3 onion service; data = `[35:onion_addr][2:port]` (length 37) * version 3 ([prop224](https://gitweb.torproject.org/torspec.git/tree/proposals/224-rend-spec-ng.txt)) onion service addresses; Encodes: @@ -313,15 +314,18 @@ - MUST set `features` according to [BOLT #9](09-features.md#assigned-features-flags) - SHOULD set `flen` to the minimum length required to hold the `features` bits it sets. + - SHOULD not announce a Tor v2 onion service. 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. @@ -332,7 +336,8 @@ 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, @@ -346,6 +351,7 @@ - MAY choose NOT to queue messages longer than the minimum expected length. - MAY use `rgb_color` AND `alias` to reference nodes in interfaces. - SHOULD insinuate their self-signed origins. + - SHOULD ignore Tor v2 onion services. ### Rationale @@ -495,8 +501,8 @@ - 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. @@ -506,7 +512,7 @@ - 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. @@ -565,21 +571,17 @@ request what gossip should be received. There are several messages which contain a long array of -`short_channel_id`s (called `encoded_short_ids`) so we utilize a -simple compression scheme: the first byte indicates the encoding, the -rest contains the data. +`short_channel_id`s (called `encoded_short_ids`) so we include an encoding byte +which allows for different encoding schemes to be defined in the future, if they +provide benefit. Encoding types: * `0`: uncompressed array of `short_channel_id` types, in ascending order. -* `1`: array of `short_channel_id` types, in ascending order, compressed with zlib deflate[1](#reference-1) +* `1`: Previously used for zlib compression, this encoding MUST NOT be used. -This encoding is also used for arrays of other types (timestamps, flags, ...), and specified with an `encoded_` prefix. For example, `encoded_timestamps` is an array of timestamps than can be either compressed (with a `1` prefix) or uncompressed (with a `0` prefix). - -Note that a 65535-byte zlib message can decompress into 67632120 -bytes[2](#reference-2), but since the only valid contents -are unique 8-byte values, no more than 14 bytes can be duplicated -across the stream: as each duplicate takes at least 2 bits, no valid -contents could decompress to more than 3669960 bytes. +This encoding is also used for arrays of other types (timestamps, flags, ...), +and specified with an `encoded_` prefix. For example, `encoded_timestamps` is +an array of timestamps with a `0` prefix. Query messages can be extended with optional fields that can help reduce the number of messages needed to synchronize routing tables by enabling: @@ -646,16 +648,21 @@ 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 @@ -775,20 +782,21 @@ 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: @@ -1094,7 +1102,7 @@ 200 + ( 4999999 * 2000 / 1000000 ) = 10199 -Similarly, it would need to add B->C's `channel_update` `cltv_expiry` (20), C's +Similarly, it would need to add B->C's `channel_update` `cltv_expiry_delta` (20), C's requested `min_final_cltv_expiry` (9), and the cost for the _shadow route_ (42). Thus, A->B's `update_add_htlc` message would be: @@ -1118,10 +1126,6 @@ And D->C's `update_add_htlc` would again be the same as B->C's direct payment above. -## References - -1. [RFC 1950 "ZLIB Compressed Data Format Specification version 3.3](https://www.ietf.org/rfc/rfc1950.txt) -2. [Maximum Compression Factor](https://zlib.net/zlib_tech.html) ![Creative Commons License](https://i.creativecommons.org/l/by/4.0/88x31.png "License CC-BY")