09-features.md (10038B)
1 # BOLT #9: Assigned Feature Flags 2 3 This document tracks the assignment of `features` flags in the `init` 4 message ([BOLT #1](01-messaging.md)), as well as `features` fields in 5 the `channel_announcement` and `node_announcement` messages ([BOLT 6 #7](07-routing-gossip.md)). The flags are tracked separately, since 7 new flags will likely be added over time. 8 9 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). 10 11 Flags are numbered from the least-significant bit, at bit 0 (i.e. 0x1, 12 an _even_ bit). They are generally assigned in pairs so that features 13 can be introduced as optional (_odd_ bits) and later upgraded to be compulsory 14 (_even_ bits), which will be refused by outdated nodes: 15 see [BOLT #1: The `init` Message](01-messaging.md#the-init-message). 16 17 Some features don't make sense on a per-channels or per-node basis, so 18 each feature defines how it is presented in those contexts. Some 19 features may be required for opening a channel, but not a requirement 20 for use of the channel, so the presentation of those features depends 21 on the feature itself. 22 23 The Context column decodes as follows: 24 25 * `I`: presented in the `init` message. 26 * `N`: presented in the `node_announcement` messages 27 * `C`: presented in the `channel_announcement` message. 28 * `C-`: presented in the `channel_announcement` message, but always odd (optional). 29 * `C+`: presented in the `channel_announcement` message, but always even (required). 30 * `9`: presented in [BOLT 11](11-payment-encoding.md) invoices. 31 * `B`: presented in the `allowed_features` field of a blinded path. 32 * `T`: used in the `channel_type` field [when opening channels](02-peer-protocol.md#the-open_channel-message). 33 34 | Bits | Name | Description | Context | Dependencies | Link | 35 |-------|-----------------------------------|-----------------------------------------------------------|----------|-----------------------------|-----------------------------------------------------------------------| 36 | 0/1 | `option_data_loss_protect` | ASSUMED | | | | 37 | 4/5 | `option_upfront_shutdown_script` | Commits to a shutdown scriptpubkey when opening channel | IN | | [BOLT #2][bolt02-open] | 38 | 6/7 | `gossip_queries` | Peer has useful gossip to share | | | | 39 | 8/9 | `var_onion_optin` | ASSUMED | | | | 40 | 10/11 | `gossip_queries_ex` | Gossip queries can include additional information | IN | | [BOLT #7][bolt07-query] | 41 | 12/13 | `option_static_remotekey` | ASSUMED | | | | 42 | 14/15 | `payment_secret` | ASSUMED | | | [Routing Onion Specification][bolt04] | 43 | 16/17 | `basic_mpp` | Node can receive basic multi-part payments | IN9 | `payment_secret` | [BOLT #4][bolt04-mpp] | 44 | 18/19 | `option_support_large_channel` | Can create large channels | IN | | [BOLT #2](02-peer-protocol.md#the-open_channel-message) | 45 | 22/23 | `option_anchors` | Anchor commitment type with zero fee HTLC transactions | INT | | [BOLT #3][bolt03-htlc-tx], [lightning-dev][ml-sighash-single-harmful] | 46 | 24/25 | `option_route_blinding` | Node supports blinded paths | IN9 | | [BOLT #4][bolt04-route-blinding] | 47 | 26/27 | `option_shutdown_anysegwit` | Future segwit versions allowed in `shutdown` | IN | | [BOLT #2][bolt02-shutdown] | 48 | 28/29 | `option_dual_fund` | Use v2 of channel open, enables dual funding | IN | | [BOLT #2](02-peer-protocol.md) | 49 | 34/35 | `option_quiesce` | Support for `stfu` message | IN | | [BOLT #2][bolt02-quiescence] | 50 | 36/37 | `option_attribution_data` | Can generate/relay attribution data in `update_fail_htlc` and `update_fulfill_htlc` | IN9 | | [BOLT #4][bolt04-attribution-data] | 51 | 38/39 | `option_onion_messages` | Can forward onion messages | IN | | [BOLT #7](04-onion-routing.md#onion-messages) | 52 | 42/43 | `option_provide_storage` | Can store other nodes' encrypted backup data | IN | | [BOLT #1](01-messaging.md#peer-storage) | 53 | 44/45 | `option_channel_type` | ASSUMED | | | | 54 | 46/47 | `option_scid_alias` | Supply channel aliases for routing | INT | | [BOLT #2][bolt02-channel-ready] | 55 | 48/49 | `option_payment_metadata` | Payment metadata in tlv record | 9 | | [BOLT #11](11-payment-encoding.md#tagged-fields) | 56 | 50/51 | `option_zeroconf` | Understands zeroconf channel types | INT | `option_scid_alias` | [BOLT #2][bolt02-channel-ready] | 57 | 60/61 | `option_simple_close` | Simplified closing negotiation | IN | `option_shutdown_anysegwit` | [BOLT #2][bolt02-simple-close] | 58 59 ## Requirements 60 61 The origin node: 62 * If it supports a feature above, SHOULD set the corresponding odd 63 bit in all feature fields indicated by the Context column unless 64 indicated that it must set the even feature bit instead. 65 * If it requires a feature above, MUST set the corresponding even 66 feature bit in all feature fields indicated by the Context column, 67 unless indicated that it must set the odd feature bit instead. 68 * MUST NOT set feature bits it does not support. 69 * MUST NOT set feature bits in fields not specified by the table above. 70 * MUST NOT set both the optional and mandatory bits. 71 * MUST set all transitive feature dependencies. 72 * MUST support: 73 * `var_onion_optin` 74 75 The receiving node: 76 * if both the optional and the mandatory feature bits in a pair are set, 77 the feature should be treated as mandatory. 78 79 The requirements for receiving specific bits are defined in the linked sections in the table above. 80 The requirements for feature bits that are not defined 81 above can be found in [BOLT #1: The `init` Message](01-messaging.md#the-init-message). 82 83 ## Rationale 84 85 Note that for feature flags which are available in both the `node_announcement` 86 and [BOLT 11](11-payment-encoding.md) invoice contexts, the features as set in 87 the [BOLT 11](11-payment-encoding.md) invoice should override those set in the 88 `node_announcement`. This keeps things consistent with the unknown features 89 behavior as specified in [BOLT 7](07-routing-gossip.md#the-node_announcement-message). 90 91 The origin must set all transitive feature dependencies in order to create a 92 well-formed feature vector. By validating all known dependencies up front, this 93 simplifies logic gated on a single feature bit; the feature's dependencies are 94 known to be set, and do not need to be validated at every feature gate. 95 96  97 <br> 98 This work is licensed under a [Creative Commons Attribution 4.0 International License](http://creativecommons.org/licenses/by/4.0/). 99 100 [bolt02-retransmit]: 02-peer-protocol.md#message-retransmission 101 [bolt02-open]: 02-peer-protocol.md#the-open_channel-message 102 [bolt02-simple-close]: 02-peer-protocol.md#closing-negotiation-closing_complete-and-closing_sig 103 [bolt03-htlc-tx]: 03-transactions.md#htlc-timeout-and-htlc-success-transactions 104 [bolt02-shutdown]: 02-peer-protocol.md#closing-initiation-shutdown 105 [bolt02-quiescence]: 02-peer-protocol.md#channel-quiescence 106 [bolt02-channel-ready]: 02-peer-protocol.md#the-channel_ready-message 107 [bolt04-attribution-data]: 04-onion-routing.md#returning-errors 108 [bolt07-sync]: 07-routing-gossip.md#initial-sync 109 [bolt07-query]: 07-routing-gossip.md#query-messages 110 [bolt04-mpp]: 04-onion-routing.md#basic-multi-part-payments 111 [bolt04-route-blinding]: 04-onion-routing.md#route-blinding 112 [bolt04-attributable-errors]: 04-onion-routing.md 113 [ml-sighash-single-harmful]: https://lists.linuxfoundation.org/pipermail/lightning-dev/2020-September/002796.html