mirrors/lightning-bolts
1
0
Fork 0
mirror of https://github.com/lightning/bolts.git synced 2025-03-10 17:18:44 +01:00
Code Issues Projects Releases Wiki Activity

BOLT 9: flatten feature fields.

Browse source 
We simply specify, in each case, where they will appear ("Context").

Because `globalfeatures` is already in use, we fold that into the
renamed `localfeatures` field to unify them (now called `features`),
but dissuade further use.

Note also: we REQUIRE minimal `features` field in
channel_announcement, since otherwise both sides of channel will not
agree and not be able to create their signatures!

Consider these theoretical future features:

`opt_dlog_chan`: a new channel type which uses a new discrete log HTLC
type, but can't support traditional HTLC:

* `init`: presents as odd (optional) or even (if traditional channels
  not supported)
* `node_announcement`: the same as above, so you can seek suitable peers.
* `channel_announcement`: presents as even (compulsory), since users need
  to use the new HTLCs.

`opt_wumbochan`: a node which allows channels > 2^24 satoshis:

* `init`: presents as odd (optional), or maybe even (if you only want
  giant channels)
* `node_announcement`: the same as above, so you can seek suitable peers.
* `channel_announcement`: not present, since size of channel indicates
  capacity.

`opt_wumbohtlc`: a channel which allows HTLCs > 2^32 millisatoshis:

* `init`: presents as odd (optional), or even (compulsory)
* `node_announcement`: the same as above, so you can seek suitable peers.
* `channel_announcement`: odd (optional) since you can use the channel
  without understanding what this option means.

Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
Co-Authored-By: Bastien Teinturier <31281497+t-bast@users.noreply.github.com>
This commit is contained in:
Rusty Russell 2019-09-17 14:51:17 +09:30
parent 5f57ee3689
commit 206084c939
5 changed files with 49 additions and 46 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
.aspell.en.pws
View file

@ -371,3 +371,4 @@ tlvs
snprintf snprintf
GitHub GitHub
IRC IRC
bitmasks

20
01-messaging.md
View file

@ -226,18 +226,17 @@ The following convenience types are also defined:
Once authentication is complete, the first message reveals the features supported or required by this node, even if this is a reconnection. Once authentication is complete, the first message reveals the features supported or required by this node, even if this is a reconnection.
[BOLT #9](09-features.md) specifies lists of global and local features. Each feature is generally represented in `globalfeatures` or `localfeatures` by 2 bits. The least-significant bit is numbered 0, which is _even_, and the next most significant bit is numbered 1, which is _odd_. [BOLT #9](09-features.md) specifies lists of features. Each feature is generally represented by 2 bits. The least-significant bit is numbered 0, which is _even_, and the next most significant bit is numbered 1, which is _odd_. For historical reasons, features are divided into global and local feature bitmasks.
Both fields `globalfeatures` and `localfeatures` MUST be padded to bytes with 0s. The `features` field MUST be padded to bytes with 0s.
1. type: 16 (`init`) 1. type: 16 (`init`)
2. data: 2. data:
* [`u16`:`gflen`] * [`u16`:`gflen`]
* [`gflen*byte`:`globalfeatures`] * [`gflen*byte`:`globalfeatures`]
* [`u16`:`lflen`] * [`u16`:`flen`]
* [`lflen*byte`:`localfeatures`] * [`flen*byte`:`features`]
The 2-byte `gflen` and `lflen` fields indicate the number of bytes in the immediately following field.
#### Requirements #### Requirements
@ -245,10 +244,12 @@ The sending node:
- MUST send `init` as the first Lightning message for any connection. - MUST send `init` as the first Lightning message for any connection.
- MUST set feature bits as defined in [BOLT #9](09-features.md). - MUST set feature bits as defined in [BOLT #9](09-features.md).
- MUST set any undefined feature bits to 0. - MUST set any undefined feature bits to 0.
- SHOULD use the minimum lengths required to represent the feature fields. - SHOULD NOT set features greater than 13 in `globalfeatures`.
- SHOULD use the minimum length required to represent the `features` field.
The receiving node: The receiving node:
- MUST wait to receive `init` before sending any other messages. - MUST wait to receive `init` before sending any other messages.
- MUST combine (logical OR) the two feature bitmaps into one logical `features` map.
- MUST respond to known feature bits as specified in [BOLT #9](09-features.md). - MUST respond to known feature bits as specified in [BOLT #9](09-features.md).
- upon receiving unknown _odd_ feature bits that are non-zero: - upon receiving unknown _odd_ feature bits that are non-zero:
- MUST ignore the bit. - MUST ignore the bit.
@ -257,15 +258,14 @@ The receiving node:
#### Rationale #### Rationale
There used to be two feature bitfields here, but for backwards compatibility they're now
combined into one.
This semantic allows both future incompatible changes and future backward compatible changes. Bits should generally be assigned in pairs, in order that optional features may later become compulsory. This semantic allows both future incompatible changes and future backward compatible changes. Bits should generally be assigned in pairs, in order that optional features may later become compulsory.
Nodes wait for receipt of the other's features to simplify error Nodes wait for receipt of the other's features to simplify error
diagnosis when features are incompatible. diagnosis when features are incompatible.
The feature masks are split into local features (which only affect the
protocol between these two nodes) and global features (which can affect
HTLCs and are thus also advertised to other nodes).
### The `error` Message ### The `error` Message
For simplicity of diagnosis, it's often useful to tell a peer that something is incorrect. For simplicity of diagnosis, it's often useful to tell a peer that something is incorrect.

8
02-peer-protocol.md
View file

@ -187,8 +187,6 @@ The `shutdown_scriptpubkey` allows the sending node to commit to where
funds will go on mutual close, which the remote node should enforce funds will go on mutual close, which the remote node should enforce
even if a node is compromised later. even if a node is compromised later.
[ FIXME: Describe dangerous feature bit for larger channel amounts. ]
#### Requirements #### Requirements
The sending node: The sending node:
@ -264,12 +262,6 @@ are above both `dust_limit_satoshis`.
Details for how to handle a channel failure can be found in [BOLT 5:Failing a Channel](05-onchain.md#failing-a-channel). Details for how to handle a channel failure can be found in [BOLT 5:Failing a Channel](05-onchain.md#failing-a-channel).
#### Future
It would be easy to have a local feature bit which indicated that a
receiving node was prepared to fund a channel, which would reverse this
protocol.
### The `accept_channel` Message ### The `accept_channel` Message
This message contains information about a node and indicates its This message contains information about a node and indicates its

4
07-routing-gossip.md
View file

@ -180,7 +180,8 @@ The origin node:
- MUST set `bitcoin_signature_1` and `bitcoin_signature_2` to valid - MUST set `bitcoin_signature_1` and `bitcoin_signature_2` to valid
signatures of the hash `h` (using `bitcoin_key_1` and `bitcoin_key_2`'s signatures of the hash `h` (using `bitcoin_key_1` and `bitcoin_key_2`'s
respective secrets). respective secrets).
- SHOULD set `len` to the minimum length required to hold the `features` bits - MUST set `features` based on what features were negotiated for this channel, according to [BOLT #9](09-features.md#assigned-features-flags)
- MUST set `len` to the minimum length required to hold the `features` bits
it sets. it sets.
The receiving node: The receiving node:
@ -311,6 +312,7 @@ The origin node:
to 0. to 0.
- SHOULD ensure `ipv4_addr` AND `ipv6_addr` are routable addresses. - SHOULD ensure `ipv4_addr` AND `ipv6_addr` are routable addresses.
- MUST NOT include more than one `address descriptor` of the same type. - MUST NOT include more than one `address descriptor` of the same type.
- MUST set `features` according to [BOLT #9](09-features.md#assigned-features-flags)
- SHOULD set `flen` to the minimum length required to hold the `features` - SHOULD set `flen` to the minimum length required to hold the `features`
bits it sets. bits it sets.

62
09-features.md
View file

@ -1,14 +1,10 @@
# BOLT #9: Assigned Feature Flags # BOLT #9: Assigned Feature Flags
This document tracks the assignment of `localfeatures` and `globalfeatures` This document tracks the assignment of `features` flags in the `init`
flags in the `init` message ([BOLT #1](01-messaging.md)) along with the message ([BOLT #1](01-messaging.md)), as well as `features` fields in
`features` flag fields in the `channel_announcement` and `node_announcement` the `channel_announcement` and `node_announcement` messages ([BOLT
messages ([BOLT #7](07-routing-gossip.md)). #7](07-routing-gossip.md)). The flags are tracked separately, since
The flags are tracked separately, since new flags will likely be added over time. new flags will likely be added over time.
The `features` flags in the routing messages are a subset of the
`globalfeatures` flags, as `localfeatures`, by definition, are only of interest
to direct peers.
Flags are numbered from the least-significant bit, at bit 0 (i.e. 0x1, Flags are numbered from the least-significant bit, at bit 0 (i.e. 0x1,
an _even_ bit). They are generally assigned in pairs so that features an _even_ bit). They are generally assigned in pairs so that features
@ -16,29 +12,41 @@ can be introduced as optional (_odd_ bits) and later upgraded to be compulsory
(_even_ bits), which will be refused by outdated nodes: (_even_ bits), which will be refused by outdated nodes:
see [BOLT #1: The `init` Message](01-messaging.md#the-init-message). see [BOLT #1: The `init` Message](01-messaging.md#the-init-message).
## Assigned `localfeatures` flags Some features don't make sense on a per-channels or per-node basis, so
each feature defines how it is presented in those contexts. Some
features may be required for opening a channel, but not a requirement
for use of the channel, so the presentation of those features depends
on the feature itself.
These flags may only be used in the `init` message: The Context column decodes as follows:
* `I`: presented in the `init` message.
* `N`: presented in the `node_announcement` messages
* `C`: presented in the `channel_announcement` message.
* `C-`: presented in the `channel_announcement` message, but always odd (optional).
* `C+`: presented in the `channel_announcement` message, but always even (required).
| Bits | Name | Description | Link | | Bits | Name | Description | Context | Link |
|-------|----------------------------------|---------------------------------------------------------------------------|------------------------------| |-------|----------------------------------|-----------------------------------------------------------|----------|---------------------------------------|
| 0/1 | `option_data_loss_protect` | Requires or supports extra `channel_reestablish` fields | [BOLT #2][bolt02-retransmit] | | 0/1 | `option_data_loss_protect` | Requires or supports extra `channel_reestablish` fields | IN | [BOLT #2][bolt02-retransmit] |
| 3 | `initial_routing_sync` | Indicates that the sending node needs a complete routing information dump | [BOLT #7][bolt07-sync] | | 3 | `initial_routing_sync` | Sending node needs a complete routing information dump | I | [BOLT #7][bolt07-sync] |
| 4/5 | `option_upfront_shutdown_script` | Commits to a shutdown scriptpubkey when opening channel | [BOLT #2][bolt02-open] | | 4/5 | `option_upfront_shutdown_script` | Commits to a shutdown scriptpubkey when opening channel | IN | [BOLT #2][bolt02-open] |
| 6/7 | `gossip_queries` | More sophisticated gossip control | [BOLT #7][bolt07-query] | | 6/7 | `gossip_queries` | More sophisticated gossip control | IN | [BOLT #7][bolt07-query] |
| 10/11 | `gossip_queries_ex` | Gossip queries can include additional information | [BOLT #7][bolt07-query] | | 8/9 | `var_onion_optin` | Requires/supports variable-length routing onion payloads | IN | [Routing Onion Specification][bolt04] |
| 12/13| `option_static_remotekey` | Static key for remote output | [BOLT #3](03-transactions.md) | | 10/11 | `gossip_queries_ex` | Gossip queries can include additional information | IN | [BOLT #7][bolt07-query] |
| 12/13| `option_static_remotekey` | Static key for remote output | IN | [BOLT #3](03-transactions.md) |
## Assigned `globalfeatures` flags
The following `globalfeatures` bits are currently assigned by this specification:
| Bits | Name | Description | Link |
|------|-------------------|--------------------------------------------------------------------|---------------------------------------|
| 8/9 | `var_onion_optin` | This node requires/supports variable-length routing onion payloads | [Routing Onion Specification][bolt04] |
## Requirements ## Requirements
The origin node:
* If it supports a feature above, SHOULD set the corresponding odd
bit in all feature fields indicated by the Context column unless
indicated that it must set the even feature bit instead.
* If it requires a feature above, MUST set the corresponding even
feature bit in all feature fields indicated by the Context column,
unless indicated that it must set the odd feature bit instead.
* MUST NOT set feature bits it does not support.
* MUST NOT set feature bits in fields not specified by the table above.
The requirements for receiving specific bits are defined in the linked sections in the table above. The requirements for receiving specific bits are defined in the linked sections in the table above.
The requirements for feature bits that are not defined The requirements for feature bits that are not defined
above can be found in [BOLT #1: The `init` Message](01-messaging.md#the-init-message). above can be found in [BOLT #1: The `init` Message](01-messaging.md#the-init-message).