mirrors/lightning-bolts
1
0
Fork 0
mirror of https://github.com/lightning/bolts.git synced 2024-11-19 01:50:03 +01:00
Code Issues Projects Releases Wiki Activity
58287e2f5b
lightning-bolts/09-features.md
Olaoluwa Osuntokun 630bf989db
BOLT-02+09: introduce feature bit to gate new channel_type feature (#906) 
In this commit, we add a new feature bit to gate the new explicit
channel type funding via the new `channel_type` TLV. The addition of
this new bit allows peers to seek out other peers that understand the
new explicit channel negotiation. This is useful in practice, as it
allows peers to avoid needing to "downgrade" the feature bits advertised
at the connection level due to one peer not understanding a new
required feature bit while it has a channel with a connecting peer.

Such a workaround is already deployed on the network between lnd peers
and certain eclair peers, as the `lnd` peers require static key, but the
feature bit is unknown to eclair peers. This situation (forced
downgrade) is undesirable, as until the connected peer updates (or the
channel is closed) and "worst" feature bit set must always be advertised
in order to maintain connectivity.

The other benefit of adding this feature bit is that it allows
implementations to simplify their code by ensuring that the new feature
will be used before sending any messages that include or reference that
feature. Without a feature bit, peers are instead forced to essentially
guess if a peer understands that feature, with logic to be able to "bail
out" of an invalid state.

The addition of this feature bit matches the prior precedent of adding
feature bits when new fields in the channel negotiation message (last
one was upfront shutdown) are added.
2021-12-05 16:35:35 -08:00

6.8 KiB
Raw Blame History

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.

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:

  • 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).
  • 9: presented in BOLT 11 invoices.
Bits Name Description Context Dependencies Link
0/1 option_data_loss_protect Requires or supports extra channel_reestablish fields IN BOLT #2
3 initial_routing_sync Sending node needs a complete routing information dump I BOLT #7
4/5 option_upfront_shutdown_script Commits to a shutdown scriptpubkey when opening channel IN BOLT #2
6/7 gossip_queries More sophisticated gossip control IN BOLT #7
8/9 var_onion_optin Requires/supports variable-length routing onion payloads IN9 Routing Onion Specification
10/11 gossip_queries_ex Gossip queries can include additional information IN gossip_queries BOLT #7
12/13 option_static_remotekey Static key for remote output IN BOLT #3
14/15 payment_secret Node supports payment_secret field IN9 var_onion_optin Routing Onion Specification
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
20/21 option_anchor_outputs Anchor outputs IN option_static_remotekey BOLT #3
22/23 option_anchors_zero_fee_htlc_tx Anchor commitment type with zero fee HTLC transactions IN BOLT #3, lightning-dev
26/27 option_shutdown_anysegwit Future segwit versions allowed in shutdown IN BOLT #2
44/45 option_channel_type Node supports the channel_type field in open/accept IN BOLT #2

Definitions

We define option_anchors as option_anchor_outputs || option_anchors_zero_fee_htlc_tx.

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 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 above can be found in BOLT #1: The init Message.

Rationale

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.

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.