Skip to content

Commit 136c93c

Browse files
ryanthegentryryanthegentry
authored
Merge pull request #4 from t-bast/reserved-values
Add blip listing reserved values
2 parents ba5fee2 + 56a76e4 commit 136c93c

File tree

3 files changed

+105
-36
lines changed

3 files changed

+105
-36
lines changed

‎README.md‎

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
# Bitcoin Lightning Improvement Proposal
2+
13
bLIP stands for Bitcoin Lightning Improvement Proposal. A bLIP is a design document
24
providing information to the Lightning community, or describing a new feature for
35
the Lightning Network. The bLIP should provide a concise technical specification of
@@ -12,8 +14,10 @@ list](https://lists.linuxfoundation.org/mailman/listinfo/lightning-dev). After
1214
discussion, please open a PR. After copy-editing and acceptance, it will be
1315
published here.
1416

15-
For more detail on the process, please read <a href="blip-0001.md">bLIP-0001</a>.
17+
For more detail on the process, please read [bLIP-0001](./blip-0001.md) and
18+
[bLIP-0002](./blip-0002.md).
1619

17-
| Number | Title | Author | Status |
18-
|--------|-------|--------|--------|
19-
|1|bLIP Process|Ryan Gentry|Active|
20+
| Number | Title | Author | Status |
21+
|--------|---------------------------|-----------------------------|--------|
22+
| 1 | bLIP Process | Ryan Gentry | Active |
23+
| 2 | reserved values | Bastien Teinturier | Active |

‎blip-0001.md‎

Lines changed: 6 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -31,37 +31,8 @@ application level that isn’t described within the core BOLT documents. This is
3131
But in the spirit of interoperability, documenting features, standards, and protocols
3232
in a single location with a standard format will make it easy on future adopters.
3333

34-
In particular, there are (at least) three scarce sets of identifiers used in Lightning
35-
Network protocol development that benefit from central organization and documentation
36-
to avoid potential clashes:
37-
38-
* **Feature Bits** are used to designate that a given node supports a given feature, and
39-
are publicly broadcasted on the Lightning Network. bLIPs may introduce new Feature Bit
40-
assignments > `100`, as those are set aside for experimental features, with the caveat
41-
that Feature Bit assignments > `1000` are discouraged from mainnet usage. Feature Bits are
42-
assigned and specified in [Bolt
43-
#9](https://github.com/lightningnetwork/lightning-rfc/blob/master/09-features.md).
44-
* **Message Types** are used to indicate how to interpret the `payload` feature of a
45-
Lightning message. Types `32768`-`65535` are set aside for experimental and
46-
application-specific messages, which are best suited to be documented in a bLIP.
47-
Message Types are assigned and specified in [Bolt
48-
#1](https://github.com/lightningnetwork/lightning-rfc/blob/master/01-messaging.md).
49-
* **Type-Length-Values (TLVs)** are used to allow for the backwards-compatible addition
50-
of new fields to existing message types (as described in in [Bolt
51-
#1](https://github.com/lightningnetwork/lightning-rfc/blob/master/01-messaging.md)).
52-
bLIPs may introduce new TLV fields to existing messages, using `type`s greater than `65536`.
53-
54-
Potentially more scarce sets of identifiers exist (e.g. [BOLT
55-
#4](https://github.com/lightningnetwork/lightning-rfc/blob/master/04-onion-routing.md#failure-messages)
56-
onion failure messages, [BOLT
57-
#7](https://github.com/lightningnetwork/lightning-rfc/blob/master/07-routing-gossip.md#the-channel_update-message) `channel_update` `channel_flags` and `message_flags`, and [BOLT
58-
#11](https://github.com/lightningnetwork/lightning-rfc/blob/master/11-payment-encoding.md#tagged-fields)
59-
invoice tagged fields) in the Lightning Network protocol. If/when bLIPs are made that
60-
require these identifiers, further specification of how and where to assign and allocate
61-
them can be accomplished.
62-
6334
bLIPs will serve as the primary mechanism for proposing new features for the Lightning
64-
Network protocol, documenting their design, and avoiding collisions of these scarce
35+
Network protocol, documenting their design, and avoiding collisions of scarce
6536
identifiers (as some proposals may request one or more). Hopefully, they will provide
6637
an avenue for developers to quickly get feedback on their ideas outside of the main BOLT
6738
process. Because the bLIPs are maintained as text files in a versioned repository,
@@ -102,8 +73,11 @@ draft must be written in bLIP style as described below, and its bLIP number will
10273
the PR number automatically assigned by Github (or, if preferred by the author, the
10374
Issue # if there was discussion in the Issues section of this repository about this bLIP).
10475

105-
When the bLIP draft is complete, the editors will check the requested Feature Bit, Message
106-
Type, and/or TLV assignments for collisions. If there are no issues, the bLIPs editors will
76+
If the bLIP needs to reserve values in shared namespaces (such as feature bits, message
77+
types or tlv fields), the author should update [bLIP 0002](./blip-0002.md) accordingly.
78+
79+
When the bLIP draft is complete, the editors will check bLIP 0002 for collisions.
80+
If there are no issues, the bLIPs editors will
10781
merge the pull request into the [bLIPs repository](https://github.com/lightning/blips).
10882
The editors will not unreasonably reject a bLIP. Reasons for rejecting bLIPs include
10983
duplication of effort, disregard for formatting rules, being too unfocused or too

‎blip-0002.md‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
```
2+
bLIP: 2
3+
Title: Reserved values
4+
Status: Active
5+
Author: Bastien Teinturier <bastien@acinq.fr>
6+
Created: 2021-11-05
7+
License: CC0
8+
```
9+
10+
# Abstract
11+
12+
bLIPs may need to define messages and fields that need to be correctly parsed and interpreted
13+
throughout the network to ensure interoperability and guarantee backwards-compatibility.
14+
15+
The [BOLTs](https://github.com/lightning/bolts) already provide several mechanisms for that,
16+
which bLIPs should rely on:
17+
18+
* [feature bits](https://github.com/lightning/bolts/blob/master/09-features.md)
19+
* [message format](https://github.com/lightning/bolts/blob/master/01-messaging.md#lightning-message-format)
20+
* [tlv fields](https://github.com/lightning/bolts/blob/master/01-messaging.md#type-length-value-format)
21+
* an `extension` tlv stream for every message defined in the BOLTs
22+
23+
bLIP authors must edit the tables below to reserve values in these various namespaces to ensure
24+
there will be no conflict between unrelated bLIPs, which would otherwise potentially lead to a
25+
network split.
26+
27+
# Reserved values
28+
29+
## Table of Contents
30+
31+
* [Feature bits](#feature-bits)
32+
* [Messages](#messages)
33+
* [TLV fields in BOLT messages](#tlv-fields-in-bolt-messages)
34+
* [`init`](#init)
35+
* [`ping`](#ping)
36+
37+
## Feature bits
38+
39+
Feature bits are specified in [Bolt 9](https://github.com/lightning/bolts/blob/master/09-features.md).
40+
They let nodes publicly advertise that they support or require a given feature.
41+
Feature bits in the `0`-`255` range are reserved for BOLTs: bLIPs must use feature bits above that range.
42+
43+
bLIPs may reserve feature bits by adding them to the following table:
44+
45+
| Bits | Name | Description | Context | Dependencies | Link |
46+
|---------|----------------------|-------------------------------------------------|----------------|--------------------------------|--------------------------------|
47+
| 256/257 | `feature_name` | Short description | Bolt 9 context | Dependencies on other features | Link to the corresponding bLIP |
48+
49+
## Messages
50+
51+
The BOLTs define a standard [message format](https://github.com/lightning/bolts/blob/master/01-messaging.md#lightning-message-format)
52+
that every lightning implementation understands.
53+
54+
Message types in the `0`-`32767` range are reserved for BOLTs: bLIPs must use message types in the `32768`-`65535` range.
55+
bLIPs may create new messages and reserve their type in the following table:
56+
57+
| Type | Name | Link |
58+
|-------|-----------------------------|--------------------------------|
59+
| 32768 | `message_name` | Link to the corresponding bLIP |
60+
61+
## TLV fields in BOLT messages
62+
63+
Every BOLT message contains a trailing `extension` field, which is a tlv stream with tlv fields
64+
specific to that BOLT message.
65+
66+
bLIPs may add new tlv fields to existing messages.
67+
bLIPs must carefully decide whether these new tlv fields should be even or odd, following the
68+
"it's ok to be odd" rule defined [here](https://github.com/lightning/bolts/blob/master/01-messaging.md#lightning-message-format).
69+
70+
When adding new tlv fields to existing BOLT messages, bLIPS must use types greater than `65536`
71+
and fill the table corresponding to the message they're modifying.
72+
73+
### `init`
74+
75+
The following table contains extension tlv fields for the `init` message:
76+
77+
| Type | Name | Link |
78+
|-------|-----------------------------|--------------------------------|
79+
| 65536 | `tlv_field_name` | Link to the corresponding bLIP |
80+
81+
### `ping`
82+
83+
The following table contains extension tlv fields for the `ping` message:
84+
85+
| Type | Name | Link |
86+
|-------|-----------------------------|--------------------------------|
87+
| 65536 | `tlv_field_name` | Link to the corresponding bLIP |
88+
89+
# Copyright
90+
91+
This bLIP is licensed under the CC0 license.

0 commit comments

Comments
 (0)