``` bLIP: 2 Title: Reserved values Status: Active Author: Bastien Teinturier Created: 2021-11-05 License: CC0 ``` ## Abstract bLIPs may need to define messages and fields that need to be correctly parsed and interpreted throughout the network to ensure interoperability and guarantee backwards-compatibility. The [BOLTs](https://github.com/lightning/bolts) already provide several mechanisms for that, which bLIPs should rely on: * [feature bits](https://github.com/lightning/bolts/blob/master/09-features.md) * [message format](https://github.com/lightning/bolts/blob/master/01-messaging.md#lightning-message-format) * [tlv fields](https://github.com/lightning/bolts/blob/master/01-messaging.md#type-length-value-format) * an `extension` tlv stream for every message defined in the BOLTs bLIP authors must edit the tables below to reserve values in these various namespaces to ensure there will be no conflict between unrelated bLIPs, which would otherwise potentially lead to a network split. ## Reserved values ### Table of Contents * [Feature bits](#feature-bits) * [Messages](#messages) * [TLV fields in BOLT messages](#tlv-fields-in-bolt-messages) * [`init`](#init) * [`ping`](#ping) * [`update_add_htlc`](#update_add_htlc) * [Onion Messages](#onion-messages) * [`invoice_request`](#invoice_request) ### Feature bits Feature bits are specified in [Bolt 9](https://github.com/lightning/bolts/blob/master/09-features.md). They let nodes publicly advertise that they support or require a given feature. Feature bits in the `0`-`255` range are reserved for BOLTs: bLIPs must use feature bits above that range. Custom feature bits used in the `I` [Bolt 11](https://github.com/lightning/bolts/blob/master/11-payment-encoding.md) context must be <= 5114 due to the [size limitations on tagged fields](https://github.com/lightning/bolts/blob/master/11-payment-encoding.md#tagged-fields). bLIPs may reserve feature bits by adding them to the following table: | Bits | Name | Description | Context | Dependencies | Link | |---------|------------------------|------------------------------------------------------------|---------|-------------------------|---------------------------| | 54/55 | `keysend` | A form of spontaneous payment | N | `var_onion_optin` | [bLIP 3](./blip-0003.md) | | 256/257 | `hosted_channels` | This node accepts requests for hosted channels | IN | | [bLIP 17](./blip-0017.md) | | 258/259 | `dns_resolver` | This node accepts DNSSEC proof requests | N | | [bLIP 32](./blip-0032.md) | | 260/261 | `htlc_endorsement` | This node forwards experimental htlc endorsement signals | N | | [bLIP 4](./blip-004.md) | | 262/263 | `bolt11_blinded_path` | This invoice may contain a new blinded path tagged field | I | `option_route_blinding` | [bLIP 39](./blip-0039.md) | | 729 | `option_supports_lsps` | This node supports LSPS protocol(s) | IN | | [bLIP 50](./blip-0050.md) | ### Messages The BOLTs define a standard [message format](https://github.com/lightning/bolts/blob/master/01-messaging.md#lightning-message-format) that every lightning implementation understands. Message types in the `0`-`32767` range are reserved for BOLTs: bLIPs must use message types in the `32768`-`65535` range. bLIPs may create new messages and reserve their type in the following table: | Type | Name | Link | | ------- | ------------------------------- | -------------------------- | | 37913 | `lsps0_message_id` | [bLIP 50](./blip-0050.md) | | 65535 | `invoke_hosted_channel` | [bLIP 17](./blip-0017.md) | | 65533 | `init_hosted_channel` | [bLIP 17](./blip-0017.md) | | 65531 | `last_cross_signed_state` | [bLIP 17](./blip-0017.md) | | 65529 | `state_update` | [bLIP 17](./blip-0017.md) | | 65527 | `state_override` | [bLIP 17](./blip-0017.md) | | 65525 | `hosted_channel_branding` | [bLIP 17](./blip-0017.md) | | 65511 | `ask_channel_branding` | [bLIP 17](./blip-0017.md) | | 63505 | `hc_update_add_htlc` | [bLIP 17](./blip-0017.md) | | 63503 | `hc_update_fulfill_htlc` | [bLIP 17](./blip-0017.md) | | 63501 | `hc_updated_fail_htlc` | [bLIP 17](./blip-0017.md) | | 63499 | `hc_update_fail_malformed_htlc` | [bLIP 17](./blip-0017.md) | | 63497 | `hc_error` | [bLIP 17](./blip-0017.md) | ### TLV fields in BOLT messages Every BOLT message contains a trailing `extension` field, which is a tlv stream with tlv fields specific to that BOLT message. bLIPs may add new tlv fields to existing messages. bLIPs must carefully decide whether these new tlv fields should be even or odd, following the "it's ok to be odd" rule defined [here](https://github.com/lightning/bolts/blob/master/01-messaging.md#lightning-message-format). When adding new tlv fields to existing BOLT messages, bLIPS must use types greater than `65536` and fill the table corresponding to the message they're modifying. #### `init` The following table contains extension tlv fields for the `init` message: | Type | Name | Link | |-------|-----------------------------|--------------------------------| | 65536 | `tlv_field_name` | Link to the corresponding bLIP | #### `payment_onion_payload` The following table contains extension tlv fields for the `payment_onion_payload` message: | Type | Name | Link | |-------------|-----------------------------|--------------------------------| | 7629169 | `podcasting_2_0` | [bLIP 10](./blip-0010.md) | | 5482373484 | `keysend_preimage` | [bLIP 3](./blip-0003.md) | #### `update_add_htlc` The following table contains extension tlv fields for the `update_add_htlc` message: | Type | Name | Link | |--------|-----------------------------|--------------------------------| | 106823 | `endorsed` | [bLIP 4](./blip-0004.md) | | 65537 | `extra_fee` | [bLIP 25](./blip-0025.md) | #### `ping` The following table contains extension tlv fields for the `ping` message: | Type | Name | Link | |-------|-----------------------------|--------------------------------| | 65536 | `tlv_field_name` | Link to the corresponding bLIP | ### Onion Messages The following table contains tlv fields for use in onion messages as the payload type: | Type | Name | Link | |-------|-----------------------------|--------------------------------| | 65536 | `dnssec_query` | [bLIP 32](./blip-0032.md) | | 65538 | `dnssec_proof` | [bLIP 32](./blip-0032.md) | | 65550 | `dnssec_error` | [bLIP 32](./blip-0032.md) | #### `invoice_request` The following table contains extension tlv fields for `invoice_request`s sent in onion messages: | Type | Name | Link | |------------|-----------------------------|---------------------------| | 2000001729 | `invreq_contact_secret` | [bLIP 42](./blip-0042.md) | | 2000001731 | `invreq_payer_offer` | [bLIP 42](./blip-0042.md) | | 2000001733 | `invreq_payer_bip_353_name` | [bLIP 42](./blip-0042.md) | ## Copyright This bLIP is licensed under the CC0 license.