1
0
mirror of https://github.com/lightning/bolts.git synced 2024-11-19 01:50:03 +01:00

Further clarify 01-messaging requirement structures by deepening branches.

This commit is contained in:
Landon Mutch 2017-11-04 18:53:46 -07:00
parent 5450ec193a
commit 531317b3b4

View File

@ -37,12 +37,13 @@ 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 odd-numbered types without ascertaining that the recipient understands it.
A node MUST NOT: A node:
- 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
A node MUST: - if that type is odd
- ignore a received message of unknown type, if that type is odd. - MUST ignore the received message.
- fail the channels if it receives a message of unknown type, if that type is even. - otherwise type is even
- 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:
@ -53,9 +54,10 @@ The messages are grouped logically into 4 groups, ordered by their most signific
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 MUST: A node:
- 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.
- fail the channels if it receives a known message with insufficient length for the contents. - if it receives a known message with insufficient length for the contents
- MUST fail the channels.
### Rationale ### Rationale
@ -96,20 +98,22 @@ The 2 byte `gflen` and `lflen` fields indicate the number of bytes in the immedi
#### Requirements #### Requirements
Each node MUST: Each node:
- send `init` as the first lightning message for any connection. - MUST send `init` as the first lightning message for any connection.
- wait to receive `init` before sending any other messages. - 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. - 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 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 MUST: The receiving node:
- 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: - for unknown feature bits which are non-zero:
- ignore the bit if the bit number is odd - if the bit number is odd
- fail the connection if the bit number is even. - MUST ignore the bit.
- otherwise the bit number is even
- MUST fail the connection.
#### Rationale #### Rationale
@ -141,18 +145,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 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 funding node:
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. - for all error messages sent before (and including) the `funding_created` message
- MUST use `temporary_channel_id` in lieu of `channel_id`.
The fundee node:
- for all error messages sent before (and not including) the `funding_signed` message
- MUST use `temporary_channel_id` in lieu of `channel_id`.
A node: A node:
- 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. - 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 sending or receiving `error`
A node MUST: - MUST fail the channel referred to by the error message
- when sending or receiving `error`, fail the channel referred to by the error message; - when `channel_id` is zero
- when `channel_id` is zero, fail all channels and MUST close the connection. - MUST fail all channels
- set `len` equal to the length of `data`. - and MUST close the connection.
- 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 - if no existing channel is referred to by the message
@ -197,19 +207,22 @@ included within the data payload of the `pong` message.
#### Requirements #### 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
memory.
A node: A node:
- when 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.
- SHOULD NOT send `ping` messages more often than once every 30 seconds - SHOULD NOT send `ping` messages more often than once every 30 seconds
- MAY terminate the network connection if it does not receive a corresponding - MAY terminate the network connection if it does not receive a corresponding
`pong` and MUST NOT fail the channels in this case. `pong`
- and MUST NOT fail the channels in this case.
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
- 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`. - if `num_pong_bytes` is less than 65532
- MUST respond by sending a `pong` message, with `byteslen` equal to `num_pong_bytes`
- otherwise
- 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 - MAY fail the channels, if `byteslen` does not