BOLT 9: flatten feature fields.

We simply specify, in each case, where they will appear ("Context"). Because `globalfeatures` is already in use, we fold that into the renamed `localfeatures` field to unify them (now called `features`), but dissuade further use. Note also: we REQUIRE minimal `features` field in channel_announcement, since otherwise both sides of channel will not agree and not be able to create their signatures! Consider these theoretical future features: `opt_dlog_chan`: a new channel type which uses a new discrete log HTLC type, but can't support traditional HTLC: * `init`: presents as odd (optional) or even (if traditional channels not supported) * `node_announcement`: the same as above, so you can seek suitable peers. * `channel_announcement`: presents as even (compulsory), since users need to use the new HTLCs. `opt_wumbochan`: a node which allows channels > 2^24 satoshis: * `init`: presents as odd (optional), or maybe even (if you only want giant channels) * `node_announcement`: the same as above, so you can seek suitable peers. * `channel_announcement`: not present, since size of channel indicates capacity. `opt_wumbohtlc`: a channel which allows HTLCs > 2^32 millisatoshis: * `init`: presents as odd (optional), or even (compulsory) * `node_announcement`: the same as above, so you can seek suitable peers. * `channel_announcement`: odd (optional) since you can use the channel without understanding what this option means. Signed-off-by: Rusty Russell <[email protected]> Co-Authored-By: Bastien Teinturier <[email protected]>
lightning · Nov 25, 2019 · 206084c · 206084c
1 parent 5f57ee3
commit 206084c
Show file tree

Hide file tree

Showing 5 changed files with 49 additions and 46 deletions.
diff --git a/.aspell.en.pws b/.aspell.en.pws
@@ -371,3 +371,4 @@ tlvs
 snprintf
 GitHub
 IRC
+bitmasks
diff --git a/01-messaging.md b/01-messaging.md
@@ -226,29 +226,30 @@ The following convenience types are also defined:
 
 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 features. Each feature is generally represented 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_.  For historical reasons, features are divided into global and local feature bitmasks.
 
-Both fields `globalfeatures` and `localfeatures` MUST be padded to bytes with 0s.
+The `features` field MUST be padded to bytes with 0s.
 
 1. type: 16 (`init`)
 2. data:
    * [`u16`:`gflen`]
    * [`gflen*byte`:`globalfeatures`]
-   * [`u16`:`lflen`]
-   * [`lflen*byte`:`localfeatures`]
+   * [`u16`:`flen`]
+   * [`flen*byte`:`features`]
 
-The 2-byte `gflen` and `lflen` fields indicate the number of bytes in the immediately following field.
 
 #### Requirements
 
 The sending node:
   - MUST send `init` as the first Lightning message for any connection.
   - MUST set feature bits as defined in [BOLT #9](09-features.md).
   - MUST set any undefined feature bits to 0.
-  - SHOULD use the minimum lengths required to represent the feature fields.
+  - SHOULD NOT set features greater than 13 in `globalfeatures`.
+  - SHOULD use the minimum length required to represent the `features` field.
 
 The receiving node:
   - MUST wait to receive `init` before sending any other messages.
+  - MUST combine (logical OR) the two feature bitmaps into one logical `features` map.
   - MUST respond to known feature bits as specified in [BOLT #9](09-features.md).
   - upon receiving unknown _odd_ feature bits that are non-zero:
     - MUST ignore the bit.
@@ -257,15 +258,14 @@ The receiving node:
 
 #### Rationale
 
+There used to be two feature bitfields here, but for backwards compatibility they're now
+combined into one.
+
 This semantic allows both future incompatible changes and future backward compatible changes. Bits should generally be assigned in pairs, in order that optional features may later become compulsory.
 
 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
-HTLCs and are thus also advertised to other nodes).
-
 ### The `error` Message
 
 For simplicity of diagnosis, it's often useful to tell a peer that something is incorrect.

diff --git a/02-peer-protocol.md b/02-peer-protocol.md
@@ -187,8 +187,6 @@ The `shutdown_scriptpubkey` allows the sending node to commit to where
 funds will go on mutual close, which the remote node should enforce
 even if a node is compromised later.
 
-[ FIXME: Describe dangerous feature bit for larger channel amounts. ]
-
 #### Requirements
 
 The sending node:
@@ -264,12 +262,6 @@ are above both `dust_limit_satoshis`.
 
 Details for how to handle a channel failure can be found in [BOLT 5:Failing a Channel](05-onchain.md#failing-a-channel).
 
-#### Future
-
-It would be easy to have a local feature bit which indicated that a
-receiving node was prepared to fund a channel, which would reverse this
-protocol.
-
 ### The `accept_channel` Message
 
 This message contains information about a node and indicates its

diff --git a/07-routing-gossip.md b/07-routing-gossip.md
@@ -180,7 +180,8 @@ 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
+  - MUST set `features` based on what features were negotiated for this channel, according to [BOLT #9](09-features.md#assigned-features-flags)
+  - MUST set `len` to the minimum length required to hold the `features` bits
   it sets.
 
 The receiving node:
@@ -311,6 +312,7 @@ 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.
+  - 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.
 

diff --git a/09-features.md b/09-features.md
@@ -1,44 +1,52 @@
 # BOLT #9: Assigned Feature Flags
 
-This document tracks the assignment of `localfeatures` and `globalfeatures`
-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
-to direct peers.
+This document tracks the assignment of `features` flags in the `init`
+message ([BOLT #1](01-messaging.md)), as well as `features` 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.
 
 Flags are numbered from the least-significant bit, at bit 0 (i.e. 0x1,
 an _even_ bit). They are generally assigned in pairs so that features
 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
-
-These flags may only be used in the `init` message:
-
-| Bits  | Name                             | Description                                                               | Link                         |
-|-------|----------------------------------|---------------------------------------------------------------------------|------------------------------|
-| 0/1   | `option_data_loss_protect`       | Requires or supports extra `channel_reestablish` fields                   | [BOLT #2][bolt02-retransmit] |
-| 3     | `initial_routing_sync`           | Indicates that the sending node needs a complete routing information dump | [BOLT #7][bolt07-sync]       |
-| 4/5   | `option_upfront_shutdown_script` | Commits to a shutdown scriptpubkey when opening channel                   | [BOLT #2][bolt02-open]       |
-| 6/7   | `gossip_queries`                 | More sophisticated gossip control                                         | [BOLT #7][bolt07-query]      |
-| 10/11 | `gossip_queries_ex`              | Gossip queries can include additional information                         | [BOLT #7][bolt07-query]      |
-| 12/13| `option_static_remotekey`     | Static key for remote output                                              | [BOLT #3](03-transactions.md)    |
+Some features don't make sense on a per-channels or per-node basis, so
+each feature defines how it is presented in those contexts.  Some
+features may be required for opening a channel, but not a requirement
+for use of the channel, so the presentation of those features depends
+on the feature itself.
 
-## Assigned `globalfeatures` flags
+The Context column decodes as follows:
+* `I`: presented in the `init` message.
+* `N`: presented in the `node_announcement` messages
+* `C`: presented in the `channel_announcement` message.
+* `C-`: presented in the `channel_announcement` message, but always odd (optional).
+* `C+`: presented in the `channel_announcement` message, but always even (required).
 
-The following `globalfeatures` bits are currently assigned by this specification:
-
-| Bits | Name              | Description                                                        | Link                                  |
-|------|-------------------|--------------------------------------------------------------------|---------------------------------------|
-| 8/9  | `var_onion_optin` | This node requires/supports variable-length routing onion payloads | [Routing Onion Specification][bolt04] |
+| Bits  | Name                             | Description                                               | Context  | Link                                  |
+|-------|----------------------------------|-----------------------------------------------------------|----------|---------------------------------------|
+| 0/1   | `option_data_loss_protect`       | Requires or supports extra `channel_reestablish` fields   | IN       | [BOLT #2][bolt02-retransmit]          |
+| 3     | `initial_routing_sync`           | Sending node needs a complete routing information dump    | I        | [BOLT #7][bolt07-sync]                |
+| 4/5   | `option_upfront_shutdown_script` | Commits to a shutdown scriptpubkey when opening channel   | IN       | [BOLT #2][bolt02-open]                |
+| 6/7   | `gossip_queries`                 | More sophisticated gossip control                         | IN       | [BOLT #7][bolt07-query]               |
+| 8/9   | `var_onion_optin`                | Requires/supports variable-length routing onion payloads  | IN       | [Routing Onion Specification][bolt04] |
+| 10/11 | `gossip_queries_ex`              | Gossip queries can include additional information         | IN       | [BOLT #7][bolt07-query]               |
+| 12/13| `option_static_remotekey`         | Static key for remote output                              | IN       | [BOLT #3](03-transactions.md)         |
 
 ## Requirements
 
+The origin node:
+  * If it supports a feature above, SHOULD set the corresponding odd
+    bit in all feature fields indicated by the Context column unless
+	indicated that it must set the even feature bit instead.
+  * If it requires a feature above, MUST set the corresponding even
+    feature bit in all feature fields indicated by the Context column,
+    unless indicated that it must set the odd feature bit instead.
+  * MUST NOT set feature bits it does not support.
+  * MUST NOT set feature bits in fields not specified by the table above.
+
 The requirements for receiving specific bits are defined in the linked sections in the table above.
 The requirements for feature bits that are not defined
 above can be found in [BOLT #1: The `init` Message](01-messaging.md#the-init-message).
-Original file line number
+Diff line change
@@ Expand Up / @@ -371,3 +371,4 @@ tlvs @@
     snprintf
     GitHub
     IRC
+    bitmasks