mirrors/lightning-blips
1
0
Fork 0
mirror of https://github.com/lightning/blips.git synced 2024-11-19 00:50:02 +01:00
Code Issues Projects Releases Wiki Activity

Merge pull request #4 from t-bast/reserved-values

Browse Source 
Add blip listing reserved values
This commit is contained in:
Ryan Gentry 2021-12-08 12:49:01 -06:00 committed by GitHub
commit 136c93ce54
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 105 additions and 36 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
README.md
View File

@ -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
View File

@ -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
View 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.