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

Clarify init-message description

Browse Source 
This is based on a series of patches from @EmelyanenkoK which makes the treatment of feature bits clearer and adds rationale so that future extensions can be made wisely.

Thanks to all involved!

Closes: #156 
Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
This commit is contained in:
Rusty Russell 2017-05-25 09:43:31 +09:30 committed by GitHub
parent 95e7196560
commit 1e228bcf8f
2 changed files with 50 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

25
01-messaging.md
View File

@ -73,10 +73,11 @@ a buffer with 6 bytes of pre-padding.
## Setup Messages
### The `init` message
Once authentication is complete, the first message reveals the features supported or required by this node, even if this is a reconnection.
Odd features are optional, even features are compulsory (_it's OK to be odd_).
The meaning of these bits will be defined in the future.
[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.
Both fields `globalfeatures` and `localfeatures` MUST be padded to bytes with zeros.
1. type: 16 (`init`)
2. data:
@ -89,22 +90,24 @@ The 2 byte `gflen` and `lflen` fields indicate the number of bytes in the immedi
#### Requirements
The sending node MUST send `init` as the first lightning message for any
Each node MUST send `init` as the first lightning message for any
connection.
The sending node SHOULD use the minimum lengths required to represent
the feature fields. The sending node MUST set feature bits
corresponding to features it requires the peer to support, and SHOULD
set feature bits corresponding to features it optionally supports.
the feature fields.
The receiving node MUST fail the channels if it receives a
`globalfeatures` or `localfeatures` with an even bit set which it does
not understand.
The sender MUST set feature bits as defined in [BOLT #9](09-features.md),
and MUST set to zero any feature bits that are not defined.
The receiver MUST respond to known feature bits as specified in
[BOLT #9](09-features.md). For unknown feature bits which are
non-zero, the receiver MUST ignore the bit if the bit number is odd,
and MUST fail the connection if the bit number is even.
Each node MUST wait to receive `init` before sending any other messages.
#### Rationale
The even/odd semantic allows future incompatible changes, or backward
This semantic allows future incompatible changes, or backward
compatible changes. Bits should generally be assigned in pairs, so
that optional features can later become compulsory.

40
09-features.md
View File

@ -5,20 +5,52 @@ They are tracked separately since new flags will likely be added over time.
The `features` flags in the routing messages are a subset of the `globalfeatures` flags, since the `localfeatures` are by definition only of interest to direct peers.
Flags are numbered from the least-significant bit at bit 0 (ie. 0x1,
an even bit). They are generally assigned in pairs, so that features
can be introduced as optional (odd bits), and later upgraded to refuse
old nodes (even bits). See [BOLT #1: The `init` message](#the-init-message).
## Assigned `localfeatures` flags
These flags may only be used in the `init` message, and are generally assigned in pairs.
Flags begin at bit 0 (ie. 0x1), and odd-numbered flags (eg. 0x2) are optional.
These flags may only be used in the `init` message:
| Bits | Name |Description | Link |
|------|------------------|------------------------------------------------|---------------------------------------------------------------------|
| 0/1 | `channels_public` | The sending node wishes to announce channels | [BOLT #7](07-routing-gossip.md#the-announcement_signatures-message) |
| 2/3 | `initial_routing_sync` | The sending node needs a complete routing information dump | [BOLT #7](07-routing-gossip.md#initial-sync) |
| 3 | `initial_routing_sync` | The sending node needs a complete routing information dump | [BOLT #7](07-routing-gossip.md#initial-sync) |
## Assigned `globalfeatures` flags
## Requirements
(Note that the requirements for feature bits which are not defined
above, can be found in [BOLT #1: The `init` message](#the-init-message)). The requirements when receiving set bits are defined in the linked section in the table above).
Additional requirements:
* `channels_public`: the sender MUST set exactly one of these bits if
it wants to announce the channel publicly, otherwise it MUST set
neither. If it sets one it MUST set the even bit if it will fail the
connection if the other node does not also set one of the
`channels_public` bits, otherwise it MUST set the odd bit. The
receiver MUST terminate the connection if neither `channels_public`
bit is set and it set the even `channels_public` bit on the `init`
message it sent, otherwise the receiver SHOULD treat either bit the
same.
## Rationale
There's little point insisting on an `initial_routing_sync` (you can't
tell if the remote node complies, and it has to know what it means as
it's defined in the initial spec) so there's no even bit for that.
There is a some point in insisting on channels being public: a node
may not want to serve any private channels, and this gives clear
indication, so that uses both bits. You can read these bits as "odd:
I would like the channel to be public" and "even: I require that the
channel be public".
![Creative Commons License](https://i.creativecommons.org/l/by/4.0/88x31.png "License CC-BY")
<br>