From bb479a83787b3a6cef6a8fefb380e27424f23cf6 Mon Sep 17 00:00:00 2001 From: Rusty Russell Date: Mon, 6 May 2019 16:23:00 +0930 Subject: [PATCH 1/5] BOLT 1, 7, 9: rename feature bits, combine in gossip. Rename `globalfeatures` to `channelfeatures` and `localfeatures` to `nodefeatures`. --- 01-messaging.md | 18 +++++++++--------- 02-peer-protocol.md | 2 +- 07-routing-gossip.md | 2 +- 09-features.md | 10 +++++----- 4 files changed, 16 insertions(+), 16 deletions(-) diff --git a/01-messaging.md b/01-messaging.md index 9ff3d55fd..97a2caccb 100644 --- a/01-messaging.md +++ b/01-messaging.md @@ -88,18 +88,18 @@ a buffer with 6-bytes of pre-padding. Once authentication is complete, the first message reveals the features supported or required by this node, even if this is a reconnection. -[BOLT #9](09-features.md) specifies lists of global and local features. Each feature is generally represented in `globalfeatures` or `localfeatures` by 2 bits. The least-significant bit is numbered 0, which is _even_, and the next most significant bit is numbered 1, which is _odd_. +[BOLT #9](09-features.md) specifies lists of channel and node features. Each feature is generally represented in `channelfeatures` or `nodefeatures` by 2 bits. The least-significant bit is numbered 0, which is _even_, and the next most significant bit is numbered 1, which is _odd_. -Both fields `globalfeatures` and `localfeatures` MUST be padded to bytes with 0s. +Both fields `channelfeatures` and `nodefeatures` MUST be padded to bytes with 0s. 1. type: 16 (`init`) 2. data: - * [`2`:`gflen`] - * [`gflen`:`globalfeatures`] - * [`2`:`lflen`] - * [`lflen`:`localfeatures`] + * [`2`:`cflen`] + * [`cflen`:`channelfeatures`] + * [`2`:`nflen`] + * [`nflen`:`nodefeatures`] -The 2-byte `gflen` and `lflen` fields indicate the number of bytes in the immediately following field. +The 2-byte `cflen` and `nflen` fields indicate the number of bytes in the immediately following field. #### Requirements @@ -124,8 +124,8 @@ This semantic allows both future incompatible changes and future backward compat Nodes wait for receipt of the other's features to simplify error diagnosis when features are incompatible. -The feature masks are split into local features (which only affect the -protocol between these two nodes) and global features (which can affect +The feature masks are split into node features (which only affect the +protocol between these two nodes) and channel features (which can affect HTLCs and are thus also advertised to other nodes). ### The `error` Message diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 85814a28c..42059efc1 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -256,7 +256,7 @@ ids. #### Future -It would be easy to have a local feature bit which indicated that a +It would be easy to have a node feature bit which indicated that a receiving node was prepared to fund a channel, which would reverse this protocol. diff --git a/07-routing-gossip.md b/07-routing-gossip.md index 80116eef2..d332741df 100644 --- a/07-routing-gossip.md +++ b/07-routing-gossip.md @@ -727,7 +727,7 @@ In the case where the `channel_announcement` is nonetheless missed, ## Initial Sync If a node requires an initial sync of gossip messages, it will be flagged -in the `init` message, via a feature flag ([BOLT #9](09-features.md#assigned-localfeatures-flags)). +in the `init` message, via a feature flag ([BOLT #9](09-features.md#assigned-nodefeatures-flags)). Note that the `initial_routing_sync` feature is overridden (and should be considered equal to 0) by the `gossip_queries` feature if the diff --git a/09-features.md b/09-features.md index d06fcffea..710e033e7 100644 --- a/09-features.md +++ b/09-features.md @@ -1,13 +1,13 @@ # BOLT #9: Assigned Feature Flags -This document tracks the assignment of `localfeatures` and `globalfeatures` +This document tracks the assignment of `nodefeatures` and `channelfeatures` flags in the `init` message ([BOLT #1](01-messaging.md)) along with the `features` flag fields in the `channel_announcement` and `node_announcement` messages ([BOLT #7](07-routing-gossip.md)). The flags are tracked separately, since new flags will likely be added over time. The `features` flags in the routing messages are a subset of the -`globalfeatures` flags, as `localfeatures`, by definition, are only of interest +`channelfeatures` flags, as `nodefeatures`, by definition, are only of interest to direct peers. Flags are numbered from the least-significant bit, at bit 0 (i.e. 0x1, @@ -16,7 +16,7 @@ can be introduced as optional (_odd_ bits) and later upgraded to be compulsory (_even_ bits), which will be refused by outdated nodes: see [BOLT #1: The `init` Message](01-messaging.md#the-init-message). -## Assigned `localfeatures` flags +## Assigned `nodefeatures` flags These flags may only be used in the `init` message: @@ -27,9 +27,9 @@ These flags may only be used in the `init` message: | 4/5 | `option_upfront_shutdown_script` | Commits to a shutdown scriptpubkey when opening channel | [BOLT #2](02-peer-protocol.md#the-open_channel-message) | | 6/7 | `gossip_queries` | More sophisticated gossip control | [BOLT #7](07-routing-gossip.md#query-messages) | -## Assigned `globalfeatures` flags +## Assigned `channelfeatures` flags -There are currently no `globalfeatures` flags. +There are currently no `channelfeatures` flags. ## Requirements From 733428e162fffd644c8e28816066c27aaeff2ac7 Mon Sep 17 00:00:00 2001 From: Rusty Russell Date: Mon, 6 May 2019 16:23:46 +0930 Subject: [PATCH 2/5] BOLT 9: Note that features share the same number space. Signed-off-by: Rusty Russell --- 09-features.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/09-features.md b/09-features.md index 710e033e7..ef6fc58ea 100644 --- a/09-features.md +++ b/09-features.md @@ -4,7 +4,9 @@ This document tracks the assignment of `nodefeatures` and `channelfeatures` flags in the `init` message ([BOLT #1](01-messaging.md)) along with the `features` flag fields in the `channel_announcement` and `node_announcement` messages ([BOLT #7](07-routing-gossip.md)). -The flags are tracked separately, since new flags will likely be added over time. +The flags use the same number space, but are semantically separate; directly +connected peers are affected by `nodefeatures`, and anyone trying to route +a payment is affected by `channelfeatures`. The `features` flags in the routing messages are a subset of the `channelfeatures` flags, as `nodefeatures`, by definition, are only of interest From 0f1f7c6b2dbca1b9216e3dcbb6a381390fa94f1e Mon Sep 17 00:00:00 2001 From: Rusty Russell Date: Mon, 6 May 2019 16:24:14 +0930 Subject: [PATCH 3/5] BOLT 1: don't need to disconnect on unknown `channelfeatures`. You can still gossip. Signed-off-by: Rusty Russell --- 01-messaging.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/01-messaging.md b/01-messaging.md index 97a2caccb..79fcf99bd 100644 --- a/01-messaging.md +++ b/01-messaging.md @@ -112,9 +112,9 @@ The sending node: The receiving node: - MUST wait to receive `init` before sending any other messages. - MUST respond to known feature bits as specified in [BOLT #9](09-features.md). - - upon receiving unknown _odd_ feature bits that are non-zero: + - upon receiving unknown _odd_ `nodefeatures` bits that are non-zero: - MUST ignore the bit. - - upon receiving unknown _even_ feature bits that are non-zero: + - upon receiving unknown _even_ `nodefeatures` bits that are non-zero: - MUST fail the connection. #### Rationale @@ -126,7 +126,9 @@ diagnosis when features are incompatible. The feature masks are split into node features (which only affect the protocol between these two nodes) and channel features (which can affect -HTLCs and are thus also advertised to other nodes). +routing and are thus also advertised to other nodes). A node may +connect to a node with unknown channel features, even though it won't be +able to establish a channel. ### The `error` Message From 783790aa2aedb0dad80b55b91a5c931d191eb70a Mon Sep 17 00:00:00 2001 From: Rusty Russell Date: Mon, 6 May 2019 16:24:35 +0930 Subject: [PATCH 4/5] BOLT 7: Explicitly mirror channelfeatures in channel_announcement. If we really want a new gossip message which old nodes will ignore, we'll use a new type, so having it discard unknown features is overzealous. Each feature can itself specify how it's advertized here: an key-exchange-instead-of-hash-preimage feature would need to advertize as even (you need to understand it to use it), for example, but a wumbo feature would advertize as odd. Signed-off-by: Rusty Russell --- 07-routing-gossip.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/07-routing-gossip.md b/07-routing-gossip.md index d332741df..d92f8e0eb 100644 --- a/07-routing-gossip.md +++ b/07-routing-gossip.md @@ -140,7 +140,7 @@ announcement message: this is accomplished by having a signature from each * [`64`:`bitcoin_signature_1`] * [`64`:`bitcoin_signature_2`] * [`2`:`len`] - * [`len`:`features`] + * [`len`:`channelfeatures`] * [`32`:`chain_hash`] * [`8`:`short_channel_id`] * [`33`:`node_id_1`] @@ -173,16 +173,16 @@ The origin node: - MUST set `bitcoin_signature_1` and `bitcoin_signature_2` to valid signatures of the hash `h` (using `bitcoin_key_1` and `bitcoin_key_2`'s respective secrets). - - SHOULD set `len` to the minimum length required to hold the `features` bits + - SHOULD set `len` to the minimum length required to hold the `channelfeatures` bits it sets. + - MUST set a `channelfeatures` bit for each `channelfeature` negotiated for + the channel, according to [BOLT #9](09-features.md). The receiving node: - MUST verify the integrity AND authenticity of the message by verifying the signatures. - - if there is an unknown even bit in the `features` field: - - MUST NOT parse the remainder of the message. + - if there is an unknown even bit in the `channelfeatures` field: - MUST NOT add the channel to its local network view. - - SHOULD NOT forward the announcement. - if the `short_channel_id`'s output does NOT correspond to a P2WSH (using `bitcoin_key_1` and `bitcoin_key_2`, as specified in [BOLT #3](03-transactions.md#funding-transaction-output)) OR the output is From 14ced3b6c33961f1adc3699994c21a4abc4958f8 Mon Sep 17 00:00:00 2001 From: Rusty Russell Date: Mon, 6 May 2019 16:24:54 +0930 Subject: [PATCH 5/5] BOLT 7: advertize both feature sets in node_announcement. This lets you find out what nodes support what node features, rather than connecting and probing. Like channel_announcement, we won't use feature bits for incompatible changes; we'll use a separate type. So don't discard messages with unknown ones. Similarly, you can try to connect to a node with unknown bits; you might fail, but that's OK. Either it was an unknown node feature, and you'll find out from their init msg, or it's a channel feature and you won't be able to open a channel. Signed-off-by: Rusty Russell --- 07-routing-gossip.md | 18 ++++-------------- 1 file changed, 4 insertions(+), 14 deletions(-) diff --git a/07-routing-gossip.md b/07-routing-gossip.md index d92f8e0eb..24fe9825b 100644 --- a/07-routing-gossip.md +++ b/07-routing-gossip.md @@ -248,8 +248,8 @@ nodes not associated with an already known channel are ignored. 1. type: 257 (`node_announcement`) 2. data: * [`64`:`signature`] - * [`2`:`flen`] - * [`flen`:`features`] + * [`2`:`cflen`] + * [`cflen`:`combinedfeatures`] * [`4`:`timestamp`] * [`33`:`node_id`] * [`3`:`rgb_color`] @@ -304,8 +304,9 @@ The origin node: to 0. - SHOULD ensure `ipv4_addr` AND `ipv6_addr` are routable addresses. - MUST NOT include more than one `address descriptor` of the same type. - - SHOULD set `flen` to the minimum length required to hold the `features` + - SHOULD set `cflen` to the minimum length required to hold the `combinedfeatures` bits it sets. + - MUST set `combinedfeatures` to the logical OR of `nodefeatures` and `channelfeatures`. The receiving node: - if `node_id` is NOT a valid compressed public key: @@ -316,12 +317,6 @@ The receiving node: any future fields appended to the end): - SHOULD fail the connection. - MUST NOT process the message further. - - if `features` field contains _unknown even bits_: - - MUST NOT parse the remainder of the message. - - MAY discard the message altogether. - - SHOULD NOT connect to the node. - - MAY forward `node_announcement`s that contain an _unknown_ `features` _bit_, - regardless of if it has parsed the announcement or not. - SHOULD ignore the first `address descriptor` that does NOT match the types defined above. - if `addrlen` is insufficient to hold the address descriptors of the @@ -343,11 +338,6 @@ any future fields appended to the end): ### Rationale -New node features are possible in the future: backwards compatible (or -optional) ones will have _odd_ `feature` _bits_, incompatible ones will have -_even_ `feature` _bits_. These may be propagated by nodes even if they -cannot process the announcements themselves. - New address types may be added in the future; as address descriptors have to be ordered in ascending order, unknown ones can be safely ignored. Additional fields beyond `addresses` may also be added in the future—with