lightning-blips/blip-0002.md

bLIP: 2
Title: Reserved values
Status: Active
Author: Bastien Teinturier <bastien@acinq.fr>
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 already provide several mechanisms for that, which bLIPs should rely on:

• feature bits
• message format
• tlv fields
• 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
• Messages
• TLV fields in BOLT messages
  • init
  • ping
  • update_add_htlc
• Onion Messages

Feature bits

Feature bits are specified in Bolt 9. 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 context must be <= 5114 due to the size limitations on 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
256/257	hosted_channels	This node accepts requests for hosted channels	IN		bLIP 17
258/259	dns_resolver	This node accepts DNSSEC proof requests	N		bLIP 32
260/261	htlc_endorsement	This node forwards experimental htlc endorsement signals	N		bLIP 4
262/263	bolt11_blinded_path	This invoice may contain a new blinded path tagged field	I	option_route_blinding	bLIP 39

Messages

The BOLTs define a standard 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
65535	invoke_hosted_channel	bLIP 17
65533	init_hosted_channel	bLIP 17
65531	last_cross_signed_state	bLIP 17
65529	state_update	bLIP 17
65527	state_override	bLIP 17
65525	hosted_channel_branding	bLIP 17
65511	ask_channel_branding	bLIP 17
63505	hc_update_add_htlc	bLIP 17
63503	hc_update_fulfill_htlc	bLIP 17
63501	hc_updated_fail_htlc	bLIP 17
63499	hc_update_fail_malformed_htlc	bLIP 17
63497	hc_error	bLIP 17

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.

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
5482373484	keysend_preimage	bLIP 3

update_add_htlc

The following table contains extension tlv fields for the update_add_htlc message:

Type	Name	Link
106823	endorsed	bLIP 4
65537	extra_fee	bLIP 25

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
65538	dnssec_proof	bLIP 32

Copyright

This bLIP is licensed under the CC0 license.