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.
2017-02-07 01:53:39 +01:00
2024-03-14 11:49:03 +01:00
Some features were introduced and became so widespread they are `ASSUMED` to be present by all nodes, and can be safely ignored (and the semantics are only defined in prior revisions of this spec).
2017-12-14 03:08:43 +01:00
Flags are numbered from the least-significant bit, at bit 0 (i.e. 0x1,
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 ).
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.
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:
2022-04-11 18:37:01 +02: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
* `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).
2019-10-30 07:02:10 +01:00
* `9` : presented in [BOLT 11 ](11-payment-encoding.md ) invoices.
2022-04-11 18:37:01 +02:00
* `B` : presented in the `allowed_features` field of a blinded path.
| 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] |
| 18/19 | `option_support_large_channel` | Can create large channels | IN | | [BOLT #2 ](02-peer-protocol.md#the-open_channel-message ) |
| 20/21 | `option_anchor_outputs` | Anchor outputs | IN | `option_static_remotekey` | [BOLT #3 ](03-transactions.md ) |
| 22/23 | `option_anchors_zero_fee_htlc_tx` | Anchor commitment type with zero fee HTLC transactions | IN | `option_static_remotekey` | [BOLT #3 ][bolt03-htlc-tx], [lightning-dev][ml-sighash-single-harmful] |
| 24/25 | `option_route_blinding` | Node supports blinded paths | IN9 | `var_onion_optin` | [BOLT #4 ](bolt04-route-blinding ) |
| 26/27 | `option_shutdown_anysegwit` | Future segwit versions allowed in `shutdown` | IN | | [BOLT #2 ][bolt02-shutdown] |
2021-03-03 04:10:33 +01:00
| 28/29 | `option_dual_fund` | Use v2 of channel open, enables dual funding | IN | | [BOLT #2 ](02-peer-protocol.md ) |
2023-04-03 01:42:56 +02:00
| 38/39 | `option_onion_messages` | Can forward onion messages | IN | | [BOLT #7 ](04-onion-routing.md#onion-messages ) |
2022-04-11 18:37:01 +02:00
| 44/45 | `option_channel_type` | Node supports the `channel_type` field in open/accept | IN | | [BOLT #2 ](02-peer-protocol.md#the-open_channel-message ) |
| 46/47 | `option_scid_alias` | Supply channel aliases for routing | IN | | [BOLT #2 ][bolt02-channel-ready] |
| 48/49 | `option_payment_metadata` | Payment metadata in tlv record | 9 | | [BOLT #11 ](11-payment-encoding.md#tagged-fields ) |
| 50/51 | `option_zeroconf` | Understands zeroconf channel types | IN | `option_scid_alias` | [BOLT #2 ][bolt02-channel-ready] |
2019-05-13 21:57:45 +02:00
2021-08-30 22:50:25 +02:00
## Definitions
We define `option_anchors` as `option_anchor_outputs || option_anchors_zero_fee_htlc_tx` .
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.
2023-07-15 02:51:05 +02:00
* MUST NOT set both the optional and mandatory bits.
2020-01-17 23:53:11 +01:00
* MUST set all transitive feature dependencies.
2023-07-15 02:51:05 +02:00
* MUST support:
* `var_onion_optin`
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
2023-07-15 02:51:05 +02:00
The receiving node:
* if both the optional and the mandatory feature bits in a pair are set,
the feature should be treated as mandatory.
2022-02-22 03:47:47 +01:00
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
2018-01-30 05:26:52 +01:00
above can be found in [BOLT #1: The `init` Message ](01-messaging.md#the-init-message ).
2017-05-25 02:13:31 +02:00
## Rationale
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.
2017-05-25 02:13:31 +02:00
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 ).
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.
2017-05-11 03:46:05 +02:00
< br >
This work is licensed under a [Creative Commons Attribution 4.0 International License ](http://creativecommons.org/licenses/by/4.0/ ).
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
2021-01-04 20:40:57 +01:00
[bolt03-htlc-tx]: 03-transactions.md#htlc-timeout-and-htlc-success-transactions
2019-09-18 02:33:03 +02:00
[bolt02-shutdown]: 02-peer-protocol.md#closing-initiation-shutdown
2022-02-15 01:32:01 +01:00
[bolt02-channel-ready]: 02-peer-protocol.md#the-channel_ready-message
2019-07-17 13:58:35 +02:00
[bolt04]: 04-onion-routing.md
2019-07-31 09:21:38 +02:00
[bolt07-sync]: 07-routing-gossip.md#initial-sync
[bolt07-query]: 07-routing-gossip.md#query-messages
2019-11-26 04:13:48 +01:00
[bolt04-mpp]: 04-onion-routing.md#basic-multi-part-payments
2022-04-11 18:37:01 +02:00
[bolt04-route-blinding]: 04-onion-routing.md#route-blinding
2021-01-04 20:40:57 +01:00
[ml-sighash-single-harmful]: https://lists.linuxfoundation.org/pipermail/lightning-dev/2020-September/002796.html
