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

Organize 01-messaging requirements into unordered lists

Browse Source 
Requirements were difficult to follow in existing sentence form, so I reordered them into hopefully more intuitive groups of unordered lists.
This commit is contained in:
Landon Mutch 2017-11-04 14:43:56 -07:00
parent 34878c0d96
commit 5450ec193a
1 changed files with 50 additions and 38 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

88
01-messaging.md
View File

@ -36,9 +36,13 @@ After decryption, all lightning messages are of the form:
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 type follows the _it's ok to be odd_ rule, so nodes MAY send odd-numbered types without ascertaining that the recipient understands it.
A node MUST NOT send an evenly-typed message not listed here without prior negotiation.
A node MUST ignore a received message of unknown type, if that type is odd.
A node MUST fail the channels if it receives a message of unknown type, if that type is even.
A node MUST NOT:
- send an evenly-typed message not listed here without prior negotiation.
A node MUST:
- ignore a received message of unknown type, if that type is odd.
- fail the channels if it receives a message of unknown type, if that type is even.
The messages are grouped logically into 4 groups, ordered by their most significant set bit:
@ -48,8 +52,10 @@ The messages are grouped logically into 4 groups, ordered by their most signific
- 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.
A node MUST ignore any additional data within a message, beyond the length it expects for that type.
A node MUST fail the channels if it receives a known message with insufficient length for the contents.
A node MUST:
- ignore any additional data within a message, beyond the length it expects for that type.
- fail the channels if it receives a known message with insufficient length for the contents.
### Rationale
@ -90,20 +96,21 @@ The 2 byte `gflen` and `lflen` fields indicate the number of bytes in the immedi
#### Requirements
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.
Each node MUST:
- send `init` as the first lightning message for any connection.
- wait to receive `init` before sending any other messages.
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 sending node:
- 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.
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.
The receiving node MUST:
- respond to known feature bits as specified in [BOLT #9](09-features.md).
- for unknown feature bits which are non-zero:
- ignore the bit if the bit number is odd
- fail the connection if the bit number is even.
Each node MUST wait to receive `init` before sending any other messages.
#### Rationale
@ -134,21 +141,24 @@ The 2-byte `len` field indicates the number of bytes in the immediately followin
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 funding node MUST use `temporary_channel_id` in lieu of `channel_id` for all error messages sent before (and including) the `funding_created` message. The fundee node MUST use `temporary_channel_id` in lieu of `channel_id` for all error messages sent before (and not including) the `funding_signed` message.
The funding node MUST use `temporary_channel_id` in lieu of `channel_id` for all error messages sent before (and including) the `funding_created` message.
The fundee node MUST use `temporary_channel_id` in lieu of `channel_id` for all error messages sent before (and not including) the `funding_signed` message.
A node SHOULD send `error` for protocol violations or internal
errors which make channels unusable or further communication unusable.
A node MAY send an empty `data` field. A node sending `error` MUST
fail the channel referred to by the error message; or if `channel_id` is zero, it MUST
fail all channels and MUST close the connection.
A node MUST set `len` equal to the length of `data`. A node 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.
A node:
- SHOULD send `error` for protocol violations or internal errors which make channels unusable or further communication unusable.
- 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.
A node receiving `error` MUST fail the channel referred to by the message,
or if `channel_id` is zero, it MUST fail all channels and MUST close the connection. If no existing channel is referred to by the message, the receiver MUST ignore the message. A receiving node MUST truncate
`len` to the remainder of the packet if it is larger.
A node MUST:
- when sending or receiving `error`, fail the channel referred to by the error message;
- when `channel_id` is zero, fail all channels and MUST close the connection.
- set `len` equal to the length of `data`.
A receiving node 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.
The receiving node:
- if no existing channel is referred to by the message
- MUST ignore the message.
- MUST truncate `len` to the remainder of the packet if it is 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).
#### Rationale
@ -187,20 +197,22 @@ included within the data payload of the `pong` message.
#### Requirements
A node sending `pong` or `ping` SHOULD set `ignored` to zeroes, but MUST NOT
set `ignored` to sensitive data such as secrets or portions of initialized
A node sending `pong` or `ping`:
- SHOULD set `ignored` to zeroes
- but MUST NOT set `ignored` to sensitive data such as secrets or portions of initialized
memory.
A node SHOULD NOT send `ping` messages more often than once every 30 seconds
and MAY terminate the network connection if it does not receive a corresponding
`pong`: it MUST NOT fail the channels in this case.
A node:
- SHOULD NOT send `ping` messages more often than once every 30 seconds
- MAY terminate the network connection if it does not receive a corresponding
`pong` and MUST NOT fail the channels in this case.
A node receiving a `ping` message 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, it MUST respond by sending a `pong` message
with `byteslen` equal to `num_pong_bytes`; otherwise it MUST ignore the `ping`.
A node receiving a `ping` message:
- SHOULD fail the channels if it has received significantly in excess of one `ping` per 30 seconds
- MUST respond by sending a `pong` message if `num_pong_bytes` is less than 65532, with `byteslen` equal to `num_pong_bytes`; otherwise it MUST ignore the `ping`.
A node receiving a `pong` message MAY fail the channels, if `byteslen` does not
A node receiving a `pong` message:
- MAY fail the channels, if `byteslen` does not
correspond to any `ping` `num_pong_bytes` value it has sent.
### Rationale