mirror of
https://github.com/lightning/bolts.git
synced 2024-11-19 10:00:04 +01:00
Organize 01-messaging requirements into unordered lists
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
parent
34878c0d96
commit
5450ec193a
@ -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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user