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

Amend: Make pull request changes; re-structure requirements; correct grammar

Browse Source 
Implement changes requested by @rustyrussell: wording change, structure requirements according to whether nodes are sending or receiving;
Correct grammar, punctuation, capitalization, and style for correctness, concision, clarity, comprehension, and consistency;
This commit is contained in:
Landon Mutch 2017-11-09 13:30:53 -08:00
parent 2f6a629a03
commit 2d829756e1
1 changed files with 83 additions and 78 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

161
01-messaging.md
View File

@ -4,7 +4,7 @@
This protocol assumes an underlying authenticated and ordered transport mechanism that takes care of framing individual messages. This protocol assumes an underlying authenticated and ordered transport mechanism that takes care of framing individual messages.
[BOLT #8](08-transport.md) specifies the canonical transport layer used in Lightning, though it can be replaced by any transport that fulfills the above guarantees. [BOLT #8](08-transport.md) specifies the canonical transport layer used in Lightning, though it can be replaced by any transport that fulfills the above guarantees.
The default TCP port is 9735. This corresponds to hexadecimal `0x2607`, the Unicode code point for LIGHTNING.<sup>[1](#reference-1)</sup> The default TCP port is 9735. This corresponds to hexadecimal `0x2607`: the Unicode code point for LIGHTNING.<sup>[1](#reference-1)</sup>
All data fields are big-endian unless otherwise specified. All data fields are big-endian unless otherwise specified.
@ -22,12 +22,12 @@ All data fields are big-endian unless otherwise specified.
## Connection Handling and Multiplexing ## Connection Handling and Multiplexing
Implementations MUST use one connection per peer, channel messages (which include a channel id) are multiplexed over this single connection. Implementations MUST use a single connection per peer — channel messages (which include a channel id) are multiplexed over this single connection.
## Lightning Message Format ## Lightning Message Format
After decryption, all lightning messages are of the form: After decryption, all Lightning messages are of the form:
1. `type`: 2 byte big-endian field indicating the type of message. 1. `type`: 2 byte big-endian field indicating the type of message.
2. `payload`: variable length payload which comprises the remainder of 2. `payload`: variable length payload which comprises the remainder of
@ -35,15 +35,16 @@ After decryption, all lightning messages are of the form:
The `type` field indicates how to interpret the `payload` field. The `type` field indicates how to interpret the `payload` field.
The format for each individual type is specified in a specification in this repository. The format for each individual type is specified in a specification in this repository.
The type follows the _it's ok to be odd_ rule, so nodes MAY send odd-numbered types without ascertaining that the recipient understands it. The type follows the _it's ok to be odd_ rule, so nodes MAY send <i>odd</i>-numbered types without ascertaining that the recipient understands it.
A node: A sending node:
- MUST NOT send an evenly-typed message not listed here without prior negotiation. - MUST NOT send an evenly-typed message not listed here, without prior negotiation.
- when receives message of unknown type
- if that type is odd A receiving node:
- MUST ignore the received message. - upon receiving a message of <i>odd</i>, unknown type:
- otherwise type is even - MUST ignore the received message.
- MUST fail the channels. - upon receiving a message of <i>even</i>, unknown type:
- MUST fail the channels.
The messages are grouped logically into 4 groups, ordered by their most significant set bit: The messages are grouped logically into 4 groups, ordered by their most significant set bit:
@ -52,11 +53,11 @@ The messages are grouped logically into 4 groups, ordered by their most signific
- Commitment (types `128`-`255`): messages related to updating the current commitment transaction, which includes adding, revoking, and settling HTLCs, as well as updating fees and exchanging signatures. These are described in [BOLT #2](02-peer-protocol.md). - Commitment (types `128`-`255`): messages related to updating the current commitment transaction, which includes adding, revoking, and settling HTLCs, as well as updating fees and exchanging signatures. These are described in [BOLT #2](02-peer-protocol.md).
- Routing (types `256`-`511`): node and channel announcements, as well as any active route exploration. These are described in [BOLT #7](07-routing-gossip.md). - Routing (types `256`-`511`): node and channel announcements, as well as any active route exploration. These are described in [BOLT #7](07-routing-gossip.md).
The size of the message is required to fit into a 2 byte unsigned int by the transport layer, therefore the maximum possible size is 65535 bytes. The size of the message is required to fit into a 2 byte unsigned int by the transport layer; therefore, the maximum possible size is 65535 bytes.
A node: A receiving node:
- MUST ignore any additional data within a message, beyond the length it expects for that type. - MUST ignore any additional data within a message, beyond the length it expects for that type.
- if it receives a known message with insufficient length for the contents - upon receiving a known message with insufficient length for the contents:
- MUST fail the channels. - MUST fail the channels.
### Rationale ### Rationale
@ -69,12 +70,12 @@ Length is limited to 65535 bytes by the cryptographic wrapping, and
messages in the protocol are never more than that length anyway. messages in the protocol are never more than that length anyway.
The "it's OK to be odd" rule allows for future optional extensions The "it's OK to be odd" rule allows for future optional extensions
without negotiation or special coding in clients. The "ignore without negotiation or special coding in clients. The "ignore
additional data" rule similarly allows for future expansion. additional data" rule similarly allows for future expansion.
Implementations may prefer to have message data aligned on an 8 byte Implementations may prefer to have message data aligned on an 8 byte
boundary (the largest natural alignment requirement of any type here), boundary (the largest natural alignment requirement of any type here);
but adding a 6 byte padding after the type field was considered however, adding a 6 byte padding after the type field was considered
wasteful: alignment may be achieved by decrypting the message into wasteful: alignment may be achieved by decrypting the message into
a buffer with 6 bytes of pre-padding. a buffer with 6 bytes of pre-padding.
@ -83,7 +84,7 @@ a buffer with 6 bytes of pre-padding.
### The `init` Message ### 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. 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 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 <i>even</i>, and the next most significant bit is numbered 1, which is <i>odd</i>.
Both fields `globalfeatures` and `localfeatures` MUST be padded to bytes with zeros. Both fields `globalfeatures` and `localfeatures` MUST be padded to bytes with zeros.
@ -98,40 +99,35 @@ The 2 byte `gflen` and `lflen` fields indicate the number of bytes in the immedi
#### Requirements #### Requirements
Each node:
- MUST send `init` as the first lightning message for any connection.
- MUST wait to receive `init` before sending any other messages.
The sending node: The sending node:
- SHOULD use the minimum lengths required to represent the feature fields. - MUST send `init` as the first Lightning message for any connection.
- MUST set feature bits as defined in [BOLT #9](09-features.md) - SHOULD use the minimum lengths required to represent the feature fields.
- MUST set feature bits as defined in [BOLT #9](09-features.md).
- MUST set to zero any feature bits that are not defined. - MUST set to zero any feature bits that are not defined.
The receiving node: The receiving node:
- MUST wait to receive `init` before sending any other messages.
- 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).
- for unknown feature bits which are non-zero: - upon receiving <i>odd</i> feature bits which are non-zero:
- if the bit number is odd - MUST ignore the bit.
- MUST ignore the bit. - upon receiving <i>even</i> feature bits which are non-zero:
- otherwise the bit number is even - MUST fail the connection.
- MUST fail the connection.
#### Rationale #### Rationale
This semantic allows future incompatible changes and/or backward 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.
compatible changes. Bits should generally be assigned in pairs, so
that optional features can 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, where features are incompatible. diagnosis, where features are incompatible.
The feature masks are split into local features, which only affect the The feature masks are split into local features (which only affect the
protocol between these two nodes, and global features, which can affect protocol between these two nodes) and global features (which can affect
HTLCs and thus are also advertised to other nodes. HTLCs) and are thus also advertised to other nodes.
### The `error` Message ### The `error` Message
For simplicity of diagnosis, it is often useful to tell the peer that something is incorrect. For simplicity of diagnosis, it's often useful to tell a peer that something is incorrect.
1. type: 17 (`error`) 1. type: 17 (`error`)
2. data: 2. data:
@ -143,42 +139,47 @@ The 2-byte `len` field indicates the number of bytes in the immediately followin
#### Requirements #### Requirements
The channel is referred to by `channel_id`, unless `channel_id` is zero (ie. all bytes are zero), in which case it refers to all channels. The channel is referred to by `channel_id`, unless `channel_id` is zero (i.e. all bytes are zero), in which case it refers to all channels.
The funding node: The funding node:
- for all error messages sent before (and including) the `funding_created` message - for all error messages sent before (and including) the `funding_created` message:
- MUST use `temporary_channel_id` in lieu of `channel_id`. - MUST use `temporary_channel_id` in lieu of `channel_id`.
The fundee node: The fundee node:
- for all error messages sent before (and not including) the `funding_signed` message - for all error messages sent before (and not including) the `funding_signed` message:
- MUST use `temporary_channel_id` in lieu of `channel_id`. - MUST use `temporary_channel_id` in lieu of `channel_id`.
A node: A sending node:
- when sending `error`:
- MUST fail the channel referred to by the error message.
- SHOULD send `error` for protocol violations or internal errors which make channels unusable or further communication unusable. - SHOULD send `error` for protocol violations or internal errors which make channels unusable or further communication unusable.
- MAY send an empty `data` field. - MAY send an empty `data` field.
- SHOULD include the raw, hex-encoded transaction in reply to a `funding_created`, `funding_signed`, `closing_signed`, or `commitment_signed` message when failure was caused by an invalid signature check. - when failure was caused by an invalid signature check:
- when sending or receiving `error` - SHOULD include the raw, hex-encoded transaction in reply to a `funding_created`, `funding_signed`, `closing_signed`, or `commitment_signed` message.
- MUST fail the channel referred to by the error message - when `channel_id` is zero:
- when `channel_id` is zero - MUST fail all channels,
- MUST fail all channels
- and MUST close the connection. - and MUST close the connection.
- MUST set `len` equal to the length of `data`. - MUST set `len` equal to the length of `data`.
The receiving node: The receiving node:
- if no existing channel is referred to by the message - upon receiving `error`:
- MUST fail the channel referred to by the error message.
- if no existing channel is referred to by the message:
- MUST ignore the message. - MUST ignore the message.
- MUST truncate `len` to the remainder of the packet if it is larger. - if it's larger:
- SHOULD only print out `data` verbatim if the string is composed solely of printable ASCII characters (For reference: the printable character set includes byte values 32 through 127, inclusive). - MUST truncate `len` to the remainder of the packet.
- if the string is composed solely of printable ASCII characters (For reference: the printable character set includes byte values 32 through 127, inclusive):
- SHOULD only print out `data` verbatim.
#### Rationale #### Rationale
There are unrecoverable errors which require an abort of conversations; There are unrecoverable errors which require an abort of conversations;
if the connection is simply dropped then the peer may retry the if the connection is simply dropped, then the peer may retry the
connection. It's also useful to describe protocol violations for connection. It's also useful to describe protocol violations for
diagnosis, as it indicates that one peer has a bug. diagnosis, as this indicates that one peer has a bug.
It may be wise not to distinguish errors in production settings, lest It may be wise not to distinguish errors in production settings, lest
it leak information, thus the optional `data` field. it leak information — hence, the optional `data` field.
## Control Messages ## Control Messages
@ -195,7 +196,7 @@ application level. Such messages also allow obfuscation of traffic patterns.
* [`byteslen`:`ignored`] * [`byteslen`:`ignored`]
The `pong` message is to be sent whenever a `ping` message is received. It The `pong` message is to be sent whenever a `ping` message is received. It
serves as a reply and also serves to keep the connection alive while serves as a reply and also serves to keep the connection alive, while
explicitly notifying the other end that the receiver is still active. Within explicitly notifying the other end that the receiver is still active. Within
the received `ping` message, the sender will specify the number of bytes to be the received `ping` message, the sender will specify the number of bytes to be
included within the data payload of the `pong` message. included within the data payload of the `pong` message.
@ -207,46 +208,50 @@ included within the data payload of the `pong` message.
#### Requirements #### Requirements
A node: A node sending a `ping` message:
- when sending `pong` or `ping`: - SHOULD set `ignored` to zeros,
- SHOULD set `ignored` to zeroes - but MUST NOT set `ignored` to sensitive data such as secrets or portions of initialized
- but MUST NOT set `ignored` to sensitive data such as secrets or portions of initialized
memory. memory.
- SHOULD NOT send `ping` messages more often than once every 30 seconds - if it doesn't receive a corresponding `pong`:
- MAY terminate the network connection if it does not receive a corresponding - MAY terminate the network connection,
`pong`
- and MUST NOT fail the channels in this case. - and MUST NOT fail the channels in this case.
- SHOULD NOT send `ping` messages more often than once every 30 seconds.
A node sending a `pong` message:
- SHOULD set `ignored` to zeros,
- but MUST NOT set `ignored` to sensitive data such as secrets or portions of initialized
memory.
A node receiving a `ping` message: A node receiving a `ping` message:
- SHOULD fail the channels if it has received significantly in excess of one `ping` per 30 seconds - SHOULD fail the channels if it has received significantly in excess of one `ping` per 30 seconds.
- if `num_pong_bytes` is less than 65532 - if `num_pong_bytes` is less than 65532:
- MUST respond by sending a `pong` message, with `byteslen` equal to `num_pong_bytes` - MUST respond by sending a `pong` message, with `byteslen` equal to `num_pong_bytes`.
- otherwise - otherwise (`num_pong_bytes` is <b>not</b> less than 65532):
- it MUST ignore the `ping`. - it MUST ignore the `ping`.
A node receiving a `pong` message: A node receiving a `pong` message:
- MAY fail the channels, if `byteslen` does not - if `byteslen` does not correspond to any `ping`'s `num_pong_bytes` value it has sent:
correspond to any `ping` `num_pong_bytes` value it has sent. - MAY fail the channels.
### Rationale ### Rationale
The largest possible message is 65535 bytes, thus the maximum sensible `byteslen` The largest possible message is 65535 bytes; thus, the maximum sensible `byteslen`
is 65531 in order to account for the type field (`pong`) and the `byteslen` itself. This allows is 65531 — in order to account for the type field (`pong`) and the `byteslen` itself. This allows
a convenient cutoff for `num_pong_bytes` to indicate that no reply should be sent. a convenient cutoff for `num_pong_bytes` to indicate that no reply should be sent.
Connections between nodes within the network may be very long lived, as payment Connections between nodes within the network may be very long lived, as payment
channels have an indefinite lifetime. However, it's likely that for a channels have an indefinite lifetime. However, it's likely that for a
significant portion of the life-time of a connection, no new data will be significant portion of the lifetime of a connection, no new data will be
exchanged. Additionally, on several platforms it's possible that Lightning exchanged. Also, on several platforms it's possible that Lightning
clients will be put to sleep without prior warning. As a result, we use a clients will be put to sleep without prior warning. Hence, we use a
distinct ping message in order to probe for the liveness of the connection on distinct `ping` message, in order to probe for the liveness of the connection on
the other side as well as to keep the established connection active. the other side, as well as to keep the established connection active.
Additionally, the ability for a sender to request that the receiver send a Additionally, the ability for a sender to request that the receiver send a
response with a particular number of bytes enables nodes on the network to response with a particular number of bytes enables nodes on the network to
create _synthetic_ traffic. Such traffic can be used to partially defend create _synthetic_ traffic. Such traffic can be used to partially defend
against packet and timing analysis, as nodes can fake the traffic patterns of against packet and timing analysis — as nodes can fake the traffic patterns of
typical exchanges without applying any true updates to their respective typical exchanges, without applying any true updates to their respective
channels. channels.
When combined with the onion routing protocol defined in When combined with the onion routing protocol defined in
@ -256,7 +261,7 @@ privacy of participants within the network.
Limited precautions are recommended against `ping` flooding, however some Limited precautions are recommended against `ping` flooding, however some
latitude is given because of network delays. Note that there are other methods latitude is given because of network delays. Note that there are other methods
of incoming traffic flooding (eg. sending odd unknown message types, or padding of incoming traffic flooding (e.g. sending <i>odd</i> unknown message types, or padding
every message maximally). every message maximally).
Finally, the usage of periodic `ping` messages serves to promote frequent key Finally, the usage of periodic `ping` messages serves to promote frequent key
@ -265,7 +270,7 @@ rotations as specified within [BOLT #8](https://github.com/lightningnetwork/ligh
## Acknowledgments ## Acknowledgments
TODO(roasbeef); fin [ TODO: (roasbeef); fin ]
## References ## References
@ -273,7 +278,7 @@ TODO(roasbeef); fin
## Authors ## Authors
FIXME [ FIXME: Insert Author List ]
![Creative Commons License](https://i.creativecommons.org/l/by/4.0/88x31.png "License CC-BY") ![Creative Commons License](https://i.creativecommons.org/l/by/4.0/88x31.png "License CC-BY")
<br> <br>