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:
parent
5450ec193a
commit
531317b3b4
@ -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
|
||||||
|
Loading…
Reference in New Issue
Block a user