mirrors/core-lightning
1
0
Fork 0
mirror of https://github.com/ElementsProject/lightning.git synced 2025-03-04 11:08:03 +01:00
Code Issues Projects Releases Wiki Activity

pyln-spec: upgrade to the last bolt version

Browse source 
Changelog-Fixed: pyln-spec: update the bolts implementation

Signed-off-by: Vincenzo Palazzo <vincenzopalazzodev@gmail.com>
This commit is contained in:
Vincenzo Palazzo 2022-04-06 20:32:57 +02:00 • committed by Rusty Russell
parent f078e54e98
commit c77eda6d64
14 changed files with 230 additions and 141 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
contrib/pyln-spec/bolt1/pyln/spec/bolt1/csv.py
View file

@ -13,6 +13,10 @@ csv = [
"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,",

2
contrib/pyln-spec/bolt1/pyln/spec/bolt1/gen_csv_version.py
View file

@ -1 +1 @@
__csv_version__ = "1"
__csv_version__ = "2"

4
contrib/pyln-spec/bolt1/pyln/spec/bolt1/gen_version.py
View file

@ -1,3 +1,3 @@
__base_version__ = "1.0"
__post_version__ = "186"
__gitversion__ = "38abac62065172c00722dca10e7d3fc3049afd72"
__post_version__ = "222"
__gitversion__ = "f1c797df2966237244527c1c6343dbe9bc765342"

76
contrib/pyln-spec/bolt1/pyln/spec/bolt1/text.py
View file

@ -18,7 +18,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)
@ -226,6 +226,12 @@ integers can be omitted:
* `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 @@ The `features` field MUST be padded to bytes with 0s.
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 @@ The sending node:
- 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 @@ 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.
- MAY use the `remote_addr` to update its `node_announcement`
#### Rationale
@ -301,7 +317,7 @@ support a single network, the `networks` fields avoids nodes
erroneously believing they will receive updates about their preferred
network, or that they can open channels.
### The `error` Message
### The `error` and `warning` Messages
For simplicity of diagnosis, it's often useful to tell a peer that something is incorrect.
@ -311,7 +327,11 @@ For simplicity of diagnosis, it's often useful to tell a peer that something is
* [`u16`:`len`]
* [`len*byte`:`data`]
The 2-byte `len` field indicates the number of bytes in the immediately following field.
1. type: 1 (`warning`)
2. data:
* [`channel_id`:`channel_id`]
* [`u16`:`len`]
* [`len*byte`:`data`]
#### Requirements
@ -326,24 +346,31 @@ The fundee node:
- MUST use `temporary_channel_id` in lieu of `channel_id`.
A sending node:
- when sending `error`:
- MUST fail the channel referred to by the error message.
- SHOULD send `error` for protocol violations or internal errors that make channels unusable or that make further communication unusable.
- SHOULD send `error` with the unknown `channel_id` in reply to messages of type `32`-`255` related to unknown channels.
- when sending `error`:
- MUST fail the channel(s) referred to by the error message.
- MAY set `channel_id` to all zero to indicate all channels.
- when sending `warning`:
- MAY set `channel_id` to all zero if the warning is not related to a specific channel.
- MAY close the connection after sending.
- MAY send an empty `data` field.
- when failure was caused by an invalid signature check:
- SHOULD include the raw, hex-encoded transaction in reply to a `funding_created`, `funding_signed`, `closing_signed`, or `commitment_signed` message.
- when `channel_id` is 0:
- MUST fail all channels with the receiving node.
- MUST close the connection.
- MUST set `len` equal to the length of `data`.
The receiving node:
- upon receiving `error`:
- MUST fail the channel referred to by the error message, if that channel is with the sending node.
- if no existing channel is referred to by the message:
- if `channel_id` is all zero:
- MUST fail all channels with the sending node.
- otherwise:
- MUST fail the channel referred to by `channel_id`, if that channel is with the sending node.
- upon receiving `warning`:
- SHOULD log the message for later diagnosis.
- MAY disconnect.
- MAY reconnect after some delay to retry.
- MAY attempt `shutdown` if permitted at this point.
- if no existing channel is referred to by `channel_id`:
- MUST ignore the message.
- MUST truncate `len` to the remainder of the packet (if it's larger).
- if `data` is not composed solely of printable ASCII characters (For reference: the printable character set includes byte values 32 through 126, inclusive):
- SHOULD NOT print out `data` verbatim.
@ -354,6 +381,11 @@ if the connection is simply dropped, then the peer may retry the
connection. It's also useful to describe protocol violations for
diagnosis, as this indicates that one peer has a bug.
On the other hand, overuse of error messages has lead to
implementations ignoring them (to avoid an otherwise expensive channel
break), so the "warning" message was added to allow some degree of
retry or recovery for spurious errors.
It may be wise not to distinguish errors in production settings, lest
it leak information — hence, the optional `data` field.
@ -389,9 +421,8 @@ 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.
A node sending a `pong` message:
- SHOULD set `ignored` to 0s.
@ -399,7 +430,6 @@ 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.
- 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 `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
@ -913,13 +943,13 @@ message. The base `init` message (without extensions) for these examples is
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

4
contrib/pyln-spec/bolt2/pyln/spec/bolt2/gen_version.py
View file

@ -1,3 +1,3 @@
__base_version__ = "1.0"
__post_version__ = "186"
__gitversion__ = "38abac62065172c00722dca10e7d3fc3049afd72"
__post_version__ = "222"
__gitversion__ = "f1c797df2966237244527c1c6343dbe9bc765342"

164
contrib/pyln-spec/bolt2/pyln/spec/bolt2/text.py
View file

@ -234,6 +234,8 @@ The sending node:
- 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 @@ The receiving node MUST:
- 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 @@ The receiving node MUST fail the channel if:
- `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`.
@ -296,6 +300,10 @@ would be eliminated as dust. The similar requirements in
`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 @@ The sender:
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 @@ The receiver:
- 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 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
@ -432,7 +442,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.
@ -450,7 +461,7 @@ use `option_static_remotekey`, `option_anchor_outputs` or
`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 @@ 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
@ -544,25 +555,23 @@ A sending node:
- 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 @@ may immediately begin closing negotiation, so we ban further updates
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 @@ the other node then replies similarly, using a fee it thinks is fair. This
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 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.
@ -652,7 +664,7 @@ The receiving node:
- 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 @@ 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:
- 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 @@ to have a maximum feerate. It may want a minimum feerate, however, to ensure
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 @@ 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:
@ -881,6 +905,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`
@ -944,19 +969,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.
@ -1042,13 +1072,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.
@ -1107,12 +1140,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
@ -1166,9 +1202,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,
@ -1210,12 +1247,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
@ -1315,7 +1355,7 @@ The sending node:
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 @@ 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`:
@ -1357,33 +1397,32 @@ 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
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 @@ Similarly, for the fundee's `funding_signed` message: it's better to
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

2
contrib/pyln-spec/bolt4/pyln/spec/bolt4/csv.py
View file

@ -8,6 +8,8 @@ csv = [
"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",

2
contrib/pyln-spec/bolt4/pyln/spec/bolt4/gen_csv_version.py
View file

@ -1 +1 @@
__csv_version__ = "2"
__csv_version__ = "3"

4
contrib/pyln-spec/bolt4/pyln/spec/bolt4/gen_version.py
View file

@ -1,3 +1,3 @@
__base_version__ = "1.0"
__post_version__ = "186"
__gitversion__ = "38abac62065172c00722dca10e7d3fc3049afd72"
__post_version__ = "222"
__gitversion__ = "f1c797df2966237244527c1c6343dbe9bc765342"

15
contrib/pyln-spec/bolt4/pyln/spec/bolt4/text.py
View file

@ -264,6 +264,9 @@ It is formatted according to the Type-Length-Value format defined in [BOLT #1](0
2. data:
* [`32*byte`:`payment_secret`]
* [`tu64`:`total_msat`]
1. type: 16 (`payment_metadata`)
2. data:
* [`...*byte`:`payment_metadata`]
### Requirements
@ -281,6 +284,9 @@ The writer:
- 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 @@ ultimate sender that the rest of the payment will follow in succeeding
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 @@ compared against the packet's HMAC.
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 @@ handling by the processing node.
* [`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

2
contrib/pyln-spec/bolt7/pyln/spec/bolt7/csv.py
View file

@ -61,7 +61,7 @@ csv = [
"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,",

2
contrib/pyln-spec/bolt7/pyln/spec/bolt7/gen_csv_version.py
View file

@ -1 +1 @@
__csv_version__ = "2"
__csv_version__ = "3"

4
contrib/pyln-spec/bolt7/pyln/spec/bolt7/gen_version.py
View file

@ -1,3 +1,3 @@
__base_version__ = "1.0"
__post_version__ = "186"
__gitversion__ = "38abac62065172c00722dca10e7d3fc3049afd72"
__post_version__ = "222"
__gitversion__ = "f1c797df2966237244527c1c6343dbe9bc765342"

70
contrib/pyln-spec/bolt7/pyln/spec/bolt7/text.py
View file

@ -98,9 +98,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:
@ -202,7 +204,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.
@ -277,10 +281,7 @@ The following `address descriptor` types are defined:
* `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 @@ The origin node:
- 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 @@ 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,
@ -346,6 +351,7 @@ any future fields appended to the end):
- 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 @@ 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.
@ -565,21 +571,17 @@ of extended queries for gossip synchronization. These explicitly
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<sup>[1](#reference-1)</sup>
* `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<sup>[2](#reference-2)</sup>, 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 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
@ -775,7 +782,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
@ -1094,7 +1102,7 @@ per [HTLC Fees](#htlc-fees):
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 @@ A->D's `update_add_htlc` message would be:
And D->C's `update_add_htlc` would again be the same as B->C's direct payment
above.
## References
1. <a id="reference-1">[RFC 1950 "ZLIB Compressed Data Format Specification version 3.3](https://www.ietf.org/rfc/rfc1950.txt)</a>
2. <a id="reference-2">[Maximum Compression Factor](https://zlib.net/zlib_tech.html)</a>
![Creative Commons License](https://i.creativecommons.org/l/by/4.0/88x31.png "License CC-BY")
<br>