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

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.

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

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
32768	message_name	Link to the corresponding bLIP

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

ping

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

Type	Name	Link
65536	tlv_field_name	Link to the corresponding bLIP

update_add_htlc

The following table contains extension tlv fields for the update_add_htlc message's onion payload:

Type	Name	Link
5482373484	keysend_preimage	bLIP 3

Copyright

This bLIP is licensed under the CC0 license.