mirrors/lightning-bolts
1
0
Fork 0
mirror of https://github.com/lightning/bolts.git synced 2024-11-19 10:00:04 +01:00
Code Issues Projects Releases Wiki Activity
fb7102e034
lightning-bolts/09-features.md

85 lines
5.6 KiB
Markdown
Raw Normal View History

BOLT 2&7: Cleaner separation of concerns wrt announcement signatures (#97) * BOLT 2&7: Cleaner separation of concerns wrt announcement signatures So far we did not have any indication on what to do if a node does not allow announcing the channel and we had a mix of concerns in the `funding_locked` message, which would also transfer the signatures needed for the announcement. This is a proposal about splitting the signatures into their own message, so that simple omission is an opt-out of announcements, and it does not mix announcement/gossip stuff into the peer-protocol. (It also ended up adding a localfeatures flag to opt-into the channel-announcement, and thus creating BOLT 9)
2017-02-07 01:53:39 +01:00
# BOLT #9: Assigned Feature Flags
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 <rusty@rustcorp.com.au> Co-Authored-By: Bastien Teinturier <31281497+t-bast@users.noreply.github.com>
2019-09-17 07:21:17 +02:00
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.
BOLT 2&7: Cleaner separation of concerns wrt announcement signatures (#97) * BOLT 2&7: Cleaner separation of concerns wrt announcement signatures So far we did not have any indication on what to do if a node does not allow announcing the channel and we had a mix of concerns in the `funding_locked` message, which would also transfer the signatures needed for the announcement. This is a proposal about splitting the signatures into their own message, so that simple omission is an opt-out of announcements, and it does not mix announcement/gossip stuff into the peer-protocol. (It also ended up adding a localfeatures flag to opt-into the channel-announcement, and thus creating BOLT 9)
2017-02-07 01:53:39 +01:00
BOLT-09 Edits (#321) I regularized the descriptions in the localfeatures table, so keep a careful eye on the accuracy of those. Otherwise, fairly standard editing in this very short section. Added text for lack of globalfeatures flags.
2017-12-14 03:08:43 +01:00
Flags are numbered from the least-significant bit, at bit 0 (i.e. 0x1,
BOLT09 copy edit for clarity and consistency with stylesheet guidelines
2018-06-08 06:39:17 +02:00
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).
BOLT 2&7: Cleaner separation of concerns wrt announcement signatures (#97) * BOLT 2&7: Cleaner separation of concerns wrt announcement signatures So far we did not have any indication on what to do if a node does not allow announcing the channel and we had a mix of concerns in the `funding_locked` message, which would also transfer the signatures needed for the announcement. This is a proposal about splitting the signatures into their own message, so that simple omission is an opt-out of announcements, and it does not mix announcement/gossip stuff into the peer-protocol. (It also ended up adding a localfeatures flag to opt-into the channel-announcement, and thus creating BOLT 9)
2017-02-07 01:53:39 +01:00
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 <rusty@rustcorp.com.au> Co-Authored-By: Bastien Teinturier <31281497+t-bast@users.noreply.github.com>
2019-09-17 07:21:17 +02:00
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.
BOLT 2&7: Cleaner separation of concerns wrt announcement signatures (#97) * BOLT 2&7: Cleaner separation of concerns wrt announcement signatures So far we did not have any indication on what to do if a node does not allow announcing the channel and we had a mix of concerns in the `funding_locked` message, which would also transfer the signatures needed for the announcement. This is a proposal about splitting the signatures into their own message, so that simple omission is an opt-out of announcements, and it does not mix announcement/gossip stuff into the peer-protocol. (It also ended up adding a localfeatures flag to opt-into the channel-announcement, and thus creating BOLT 9)
2017-02-07 01:53:39 +01:00
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 <rusty@rustcorp.com.au> Co-Authored-By: Bastien Teinturier <31281497+t-bast@users.noreply.github.com>
2019-09-17 07:21:17 +02:00
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).
BOLT 11: use the same features for BOLT11 invoices as for others. A bit less dense, but avoids a separate feature space. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2019-10-30 07:02:10 +01:00
* `9`: presented in [BOLT 11](11-payment-encoding.md) invoices.
BOLT 9: Add CC-BY license tag. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2017-05-11 03:46:05 +02:00
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.
2020-01-17 23:53:11 +01:00
| 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] |
bolt07: Add feature bits for multi-frame support
2019-05-13 21:57:45 +02:00
Clarify init-message description This is based on a series of patches from @EmelyanenkoK which makes the treatment of feature bits clearer and adds rationale so that future extensions can be made wisely. Thanks to all involved! Closes: #156 Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2017-05-25 02:13:31 +02:00
## Requirements
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 <rusty@rustcorp.com.au> Co-Authored-By: Bastien Teinturier <31281497+t-bast@users.noreply.github.com>
2019-09-17 07:21:17 +02:00
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.
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.
2020-01-17 23:53:11 +01:00
* MUST set all transitive feature dependencies.
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 <rusty@rustcorp.com.au> Co-Authored-By: Bastien Teinturier <31281497+t-bast@users.noreply.github.com>
2019-09-17 07:21:17 +02:00
BOLT-09 Edits (#321) I regularized the descriptions in the localfeatures table, so keep a careful eye on the accuracy of those. Otherwise, fairly standard editing in this very short section. Added text for lack of globalfeatures flags.
2017-12-14 03:08:43 +01:00
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
Remove trailing whitespace
2018-01-30 05:26:52 +01:00
above can be found in [BOLT #1: The `init` Message](01-messaging.md#the-init-message).
Clarify init-message description This is based on a series of patches from @EmelyanenkoK which makes the treatment of feature bits clearer and adds rationale so that future extensions can be made wisely. Thanks to all involved! Closes: #156 Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2017-05-25 02:13:31 +02:00
## Rationale
BOLT09 copy edit for clarity and consistency with stylesheet guidelines
2018-06-08 06:39:17 +02:00
There is no _even_ bit for `initial_routing_sync`, as there would be little
point: a local node can't determine if a remote node complies, and it must
interpret the flag, as defined in the initial spec.
Clarify init-message description This is based on a series of patches from @EmelyanenkoK which makes the treatment of feature bits clearer and adds rationale so that future extensions can be made wisely. Thanks to all involved! Closes: #156 Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2017-05-25 02:13:31 +02:00
Do not allow routing to a node with unkown feature bits set. This appears to have been an oversight in the flat features spec, and is somewhat implicitly relied on for several new feature bits - if var_onion_optin is set on a node_announcement (its not allowed on a channel_announcement), then trying to route through that node using the pre-tlv formt is somewhat nonsensical, and should be forbidden.
2019-12-24 19:45:30 +01:00
Note that for feature flags which are available in both the `node_announcement`
and [BOLT 11](11-payment-encoding.md) invoice contexts, the features as set in
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).
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.
2020-01-17 23:53:11 +01:00
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.
BOLT 9: Add CC-BY license tag. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2017-05-11 03:46:05 +02:00
![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/).
Bolt 04: fix a few left-over spelling / clean-up nits (#653) * Fix a few left-over spelling / clean-up nits * Bolt 09: fix spec links
2019-07-31 09:21:38 +02:00
[bolt02-retransmit]: 02-peer-protocol.md#message-retransmission
[bolt02-open]: 02-peer-protocol.md#the-open_channel-message
bolt09: Cleanup the feature bits tables and extract URLs into footer The tables were a bit unreadable in the source view, and the globalfeatures table was not rendering correctly. This is just a minor cleanup pass. Signed-off-by: Christian Decker <decker.christian@gmail.com> Suggested-by: Janus Troelsen <@ysangkok>
2019-07-17 13:58:35 +02:00
[bolt04]: 04-onion-routing.md
Bolt 04: fix a few left-over spelling / clean-up nits (#653) * Fix a few left-over spelling / clean-up nits * Bolt 09: fix spec links
2019-07-31 09:21:38 +02:00
[bolt07-sync]: 07-routing-gossip.md#initial-sync
[bolt07-query]: 07-routing-gossip.md#query-messages
BOLT 9: Add feature bits for payment_secret and basic_mpp. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2019-11-26 04:13:48 +01:00
[bolt04-mpp]: 04-onion-routing.md#basic-multi-part-payments
Reference in New Issue Copy Permalink