09+11: require transitive feature dependencies

This commit: - Adds a new Dependencies column to the BOLT 9 feature table populated with existing feature dependencies. - Requires that all valid feature vectors set transitive dependencies. - Requires checking transitive dependencies when validating init messages and payment request. - Removes transitive feature requiremetns from the BOLT 11 writer, now that they are implicit by needing to comply with the BOLT 9 origin requirements.
lightning · Jan 21, 2020 · 4c638b7 · 4c638b7
1 parent 11f6017
commit 4c638b7
Show file tree

Hide file tree

Showing 3 changed files with 23 additions and 14 deletions.
diff --git a/01-messaging.md b/01-messaging.md
@@ -255,6 +255,8 @@ The receiving node:
     - MUST ignore the bit.
   - upon receiving unknown _even_ feature bits that are non-zero:
     - MUST fail the connection.
+  - if the feature vector does not set all known, transitive dependencies:
+    - MUST fail the connection.
 
 #### Rationale
 

diff --git a/09-features.md b/09-features.md
@@ -26,17 +26,17 @@ The Context column decodes as follows:
 * `C+`: presented in the `channel_announcement` message, but always even (required).
 * `9`: presented in [BOLT 11](11-payment-encoding.md) invoices.
 
-| 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  | IN9      | [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)         |
-| 14/15 | `payment_secret`                 | Node supports `payment_secret` field                      | IN9      | [Routing Onion Specification][bolt04]   |
-| 16/17 | `basic_mpp`                      | Node can receive basic multi-part payments                | IN9      | [BOLT #4][bolt04-mpp]                 |
+| Bits  | Name                             | Description                                               | Context  | Dependencies      | 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  | IN9      |                   | [Routing Onion Specification][bolt04] |
+| 10/11 | `gossip_queries_ex`              | Gossip queries can include additional information         | IN       | `gossip_queries`  | [BOLT #7][bolt07-query]               |
+| 12/13 | `option_static_remotekey`        | Static key for remote output                              | IN       |                   | [BOLT #3](03-transactions.md)         |
+| 14/15 | `payment_secret`                 | Node supports `payment_secret` field                      | IN9      | `var_onion_optin` | [Routing Onion Specification][bolt04] |
+| 16/17 | `basic_mpp`                      | Node can receive basic multi-part payments                | IN9      | `payment_secret`  | [BOLT #4][bolt04-mpp]                 |
 
 ## Requirements
 
@@ -49,6 +49,7 @@ The origin node:
     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.
+  * MUST set all transitive feature dependencies.
 
 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
@@ -66,6 +67,11 @@ the [BOLT 11](11-payment-encoding.md) invoice should override those set in the
 `node_announcement`. This keeps things consistent with the unknown features
 behavior as specified in [BOLT 7](07-routing-gossip.md#the-node_announcement-message).
 
+The origin must set all transitive feature dependencies in order to create a
+well-formed feature vector. By validating all known dependencies up front, this
+simplifies logic gated on a single feature bit; the feature's dependencies are
+known to be set, and do not need to be validated at every feature gate.
+
 ![Creative Commons License](https://i.creativecommons.org/l/by/4.0/88x31.png "License CC-BY")
 <br>
 This work is licensed under a [Creative Commons Attribution 4.0 International License](http://creativecommons.org/licenses/by/4.0/).

diff --git a/11-payment-encoding.md b/11-payment-encoding.md
@@ -292,6 +292,8 @@ on the amount sent.
 ### Requirements
 
 A writer:
+  - MUST set the `9` field to a feature vector compliant with the
+    [BOLT 9 origin node requirements](09-features.md#requirements).
   - if `payment_secret` feature is set:
     - MUST include an `s` field.
   - otherwise:
@@ -300,14 +302,13 @@ A writer:
     - MUST set the even feature `payment_secret`.
   - If the final node supports [Basic multi-part payments](04-onion-routing.md#basic-multi-part-payments):
     - MUST set the `basic_mpp` feature.
-    - MUST set the `payment_secret` feature.
   - Otherwise:
     - MUST NOT set the `basic_mpp` feature.
-  - if it sets the `payment_secret` feature:
-    - MUST set the `var_onion_optin` feature.
   - MUST set `var_onion_optin` if and only if it supports that feature.
 
 A reader:
+  - if the feature vector does not set all known, transitive feature dependencies:
+    - MUST NOT attempt the payment.
   - if the `basic_mpp` feature is offered in the invoice:
     - MAY pay using [Basic multi-part payments](04-onion-routing.md#basic-multi-part-payments).
   - otherwise: