mirror of
https://github.com/lightning/blips.git
synced 2024-11-19 00:50:02 +01:00
Add blip listing reserved values
This is a meta blip that other blips need to update whenever they want to reserve a value in a scarce namespace. The tables in that blip must be kept up to date to avoid clashes in the network, which would lead to p2p network split.
This commit is contained in:
t-bast
parent
ba5fee2906
commit
56a76e4530
12
README.md
12
README.md
@ -1,3 +1,5 @@
|
||||
# Bitcoin Lightning Improvement Proposal
|
||||
|
||||
bLIP stands for Bitcoin Lightning Improvement Proposal. A bLIP is a design document
|
||||
providing information to the Lightning community, or describing a new feature for
|
||||
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
|
||||
discussion, please open a PR. After copy-editing and acceptance, it will be
|
||||
published here.
|
||||
|
||||
For more detail on the process, please read <a href="blip-0001.md">bLIP-0001</a>.
|
||||
For more detail on the process, please read [bLIP-0001](./blip-0001.md) and
|
||||
[bLIP-0002](./blip-0002.md).
|
||||
|
||||
| Number | Title | Author | Status |
|
||||
|--------|-------|--------|--------|
|
||||
|1|bLIP Process|Ryan Gentry|Active|
|
||||
| Number | Title | Author | Status |
|
||||
|--------|---------------------------|-----------------------------|--------|
|
||||
| 1 | bLIP Process | Ryan Gentry | Active |
|
||||
| 2 | reserved values | Bastien Teinturier | Active |
|
||||
|
||||
38
blip-0001.md
38
blip-0001.md
@ -31,37 +31,8 @@ application level that isn’t described within the core BOLT documents. This is
|
||||
But in the spirit of interoperability, documenting features, standards, and protocols
|
||||
in a single location with a standard format will make it easy on future adopters.
|
||||
|
||||
In particular, there are (at least) three scarce sets of identifiers used in Lightning
|
||||
Network protocol development that benefit from central organization and documentation
|
||||
to avoid potential clashes:
|
||||
|
||||
* **Feature Bits** are used to designate that a given node supports a given feature, and
|
||||
are publicly broadcasted on the Lightning Network. bLIPs may introduce new Feature Bit
|
||||
assignments > `100`, as those are set aside for experimental features, with the caveat
|
||||
that Feature Bit assignments > `1000` are discouraged from mainnet usage. Feature Bits are
|
||||
assigned and specified in [Bolt
|
||||
#9](https://github.com/lightningnetwork/lightning-rfc/blob/master/09-features.md).
|
||||
* **Message Types** are used to indicate how to interpret the `payload` feature of a
|
||||
Lightning message. Types `32768`-`65535` are set aside for experimental and
|
||||
application-specific messages, which are best suited to be documented in a bLIP.
|
||||
Message Types are assigned and specified in [Bolt
|
||||
#1](https://github.com/lightningnetwork/lightning-rfc/blob/master/01-messaging.md).
|
||||
* **Type-Length-Values (TLVs)** are used to allow for the backwards-compatible addition
|
||||
of new fields to existing message types (as described in in [Bolt
|
||||
#1](https://github.com/lightningnetwork/lightning-rfc/blob/master/01-messaging.md)).
|
||||
bLIPs may introduce new TLV fields to existing messages, using `type`s greater than `65536`.
|
||||
|
||||
Potentially more scarce sets of identifiers exist (e.g. [BOLT
|
||||
#4](https://github.com/lightningnetwork/lightning-rfc/blob/master/04-onion-routing.md#failure-messages)
|
||||
onion failure messages, [BOLT
|
||||
#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
|
||||
#11](https://github.com/lightningnetwork/lightning-rfc/blob/master/11-payment-encoding.md#tagged-fields)
|
||||
invoice tagged fields) in the Lightning Network protocol. If/when bLIPs are made that
|
||||
require these identifiers, further specification of how and where to assign and allocate
|
||||
them can be accomplished.
|
||||
|
||||
bLIPs will serve as the primary mechanism for proposing new features for the Lightning
|
||||
Network protocol, documenting their design, and avoiding collisions of these scarce
|
||||
Network protocol, documenting their design, and avoiding collisions of scarce
|
||||
identifiers (as some proposals may request one or more). Hopefully, they will provide
|
||||
an avenue for developers to quickly get feedback on their ideas outside of the main BOLT
|
||||
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
|
||||
the PR number automatically assigned by Github (or, if preferred by the author, the
|
||||
Issue # if there was discussion in the Issues section of this repository about this bLIP).
|
||||
|
||||
When the bLIP draft is complete, the editors will check the requested Feature Bit, Message
|
||||
Type, and/or TLV assignments for collisions. If there are no issues, the bLIPs editors will
|
||||
If the bLIP needs to reserve values in shared namespaces (such as feature bits, message
|
||||
types or tlv fields), the author should update [bLIP 0002](./blip-0002.md) accordingly.
|
||||
|
||||
When the bLIP draft is complete, the editors will check bLIP 0002 for collisions.
|
||||
If there are no issues, the bLIPs editors will
|
||||
merge the pull request into the [bLIPs repository](https://github.com/lightning/blips).
|
||||
The editors will not unreasonably reject a bLIP. Reasons for rejecting bLIPs include
|
||||
duplication of effort, disregard for formatting rules, being too unfocused or too
|
||||
|
||||
91
blip-0002.md
Normal file
91
blip-0002.md
Normal file
@ -0,0 +1,91 @@
|
||||
```
|
||||
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](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)
|
||||
|
||||
## 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.
|
||||
|
||||
bLIPs may reserve feature bits by adding them to the following table:
|
||||
|
||||
| Bits | Name | Description | Context | Dependencies | Link |
|
||||
|---------|----------------------|-------------------------------------------------|----------------|--------------------------------|--------------------------------|
|
||||
| 256/257 | `feature_name` | Short description | Bolt 9 context | Dependencies on other features | Link to the corresponding bLIP |
|
||||
|
||||
## 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 |
|
||||
|-------|-----------------------------|--------------------------------|
|
||||
| 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](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 |
|
||||
|
||||
### `ping`
|
||||
|
||||
The following table contains extension tlv fields for the `ping` message:
|
||||
|
||||
| Type | Name | Link |
|
||||
|-------|-----------------------------|--------------------------------|
|
||||
| 65536 | `tlv_field_name` | Link to the corresponding bLIP |
|
||||
|
||||
# Copyright
|
||||
|
||||
This bLIP is licensed under the CC0 license.
|
||||
Loading…
Reference in New Issue
Block a user