Lightning Book of BOLTs

BOLT #9: Assigned Feature Flags

This document tracks the assignment of features flags in the init message (BOLT #1), as well as features fields in the channel_announcement and node_announcement messages (BOLT #7). The flags are tracked separately, since new flags will likely be added over time.

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).

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.

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.

The Context column decodes as follows:

Bits Name Description Context Dependencies Link
0/1 option_data_loss_protect ASSUMED
4/5 option_upfront_shutdown_script Commits to a shutdown scriptpubkey when opening channel IN BOLT #2
6/7 gossip_queries Peer has useful gossip to share
8/9 var_onion_optin ASSUMED
10/11 gossip_queries_ex Gossip queries can include additional information IN BOLT #7
12/13 option_static_remotekey ASSUMED
14/15 payment_secret ASSUMED [Routing Onion Specification][bolt04]
16/17 basic_mpp Node can receive basic multi-part payments IN9 payment_secret BOLT #4
18/19 option_support_large_channel Can create large channels IN BOLT #2
22/23 option_anchors Anchor commitment type with zero fee HTLC transactions INT BOLT #3, lightning-dev
24/25 option_route_blinding Node supports blinded paths IN9 BOLT #4
26/27 option_shutdown_anysegwit Future segwit versions allowed in shutdown IN BOLT #2
28/29 option_dual_fund Use v2 of channel open, enables dual funding IN BOLT #2
34/35 option_quiesce Support for stfu message IN BOLT #2
36/37 option_attribution_data Can generate/relay attribution data and fulfillment_payload IN9 BOLT #4, successful payments
38/39 option_onion_messages Can forward onion messages IN BOLT #4
40/41 zero_fee_commitments Zero-fee commitment and HTLC transactions IN option_channel_type BOLT #3
42/43 option_provide_storage Can store other nodes’ encrypted backup data IN BOLT #1
44/45 option_channel_type ASSUMED
46/47 option_scid_alias Supply channel aliases for routing INT BOLT #2
48/49 option_payment_metadata Payment metadata in tlv record 9 BOLT #11
50/51 option_zeroconf Understands zeroconf channel types INT option_scid_alias BOLT #2
60/61 option_simple_close Simplified closing negotiation IN option_shutdown_anysegwit BOLT #2
62/63 option_splice Allows replacing the funding transaction with a new one IN BOLT #2
66/67 option_onion_messages_only_channels Only accepts onion messages from peers with a channel IN option_onion_messages BOLT #4

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. * MUST NOT set both the optional and mandatory bits. * MUST set all transitive feature dependencies. * MUST support: * var_onion_optin

The receiving node: * if both the optional and the mandatory feature bits in a pair are set, the feature should be treated as mandatory.

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.

Rationale

Note that for feature flags which are available in both the node_announcement and BOLT 11 invoice contexts, the features as set in the BOLT 11 invoice should override those set in the node_announcement. This keeps things consistent with the unknown features behavior as specified in BOLT 7.

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
This work is licensed under a Creative Commons Attribution 4.0 International License.