diff --git a/01-messaging.md b/01-messaging.md index fd50b8625..c46746ce6 100644 --- a/01-messaging.md +++ b/01-messaging.md @@ -2,12 +2,21 @@ ## Overview This protocol assumes an underlying authenticated and ordered transport mechanism that takes care of framing individual messages. -[BOLT 08](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.[2](#reference-2) All data fields are big-endian unless otherwise specified. +## Table of Contents + * [Lightning Message Format](#lightning-message-format) + * [Setup Messages](#setup-messages) + * [The `init` message](#the-init-message) + * [The `error` message](#the-error-message) + * [Acknowledgements](#acknowledgements) + * [References](#references) + * [Authors](#authors) + ## Lightning Message Format After decryption, all lightning messages are of the form: @@ -23,6 +32,13 @@ A node MUST NOT send an evenly-typed message not listed here without prior negot 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. +The messages are grouped logically into 4 groups by their most significant set bit: + + - Setup & signalling (types `0`-`31`): messages related to supported features and error reporting. These are described below. + - Channel (types `32`-`127`): comprises messages used to setup, update and tear down micropayment channels. These are described in [BOLT #2](02-peer-protocol.md). + - HTLC (types `128`-`255`: comprises messages related to adding, revoking and settling HTLCs on a micropayment channel. 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). + 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. @@ -46,7 +62,9 @@ but adding a 6 byte padding after the type field was considered wasteful: alignment may be achieved by decrypting the message into a buffer with 6 bytes of pre-padding. -## Initialization Message +## Setup Messages + +### The `init` message Once authentication is complete, the first message reveals the features supported or required by this node. Odd features are optional, even features are compulsory (_it's OK to be odd_). @@ -61,7 +79,7 @@ The meaning of these bits will be defined in the future. The 2 byte `gflen` and `lflen` fields indicate the number of bytes in the immediately following field. -### Requirements +#### Requirements The sending node SHOULD use the minimum lengths required to represent the feature fields. The sending node MUST set feature bits @@ -74,7 +92,7 @@ not understand. Each node MUST wait to receive `init` before sending any other messages. -### Rationale +#### Rationale The even/odd semantic allows future incompatible changes, or backward compatible changes. Bits should generally be assigned in pairs, so @@ -87,7 +105,7 @@ The feature masks are split into local features which only affect the protocol between these two nodes, and global features which can affect HTLCs and thus are also advertised to other nodes. -## Error Message +### The `error` message For simplicity of diagnosis, it is often useful to tell the peer that something is incorrect. @@ -99,7 +117,7 @@ For simplicity of diagnosis, it is often useful to tell the peer that something The 2-byte `len` field indicates the number of bytes in the immediately following field. -### Requirements +#### Requirements A node SHOULD send `error` for protocol violations or internal errors which make channels unusable or further communication unusable. @@ -116,7 +134,7 @@ all channels and MUST close the connection. A receiving node MUST truncate A receiving node SHOULD only print out `data` verbatim if it is a valid string. -### Rationale +#### Rationale There are unrecoverable errors which require an abort of conversations; if the connection is simply dropped then the peer may retry the @@ -131,11 +149,11 @@ it leak information, thus the optional data field. TODO(roasbeef); fin -# References +## References 1. https://en.bitcoin.it/wiki/Secp256k1 2. http://www.unicode.org/charts/PDF/U2600.pdf -# Authors +## Authors FIXME diff --git a/02-peer-protocol.md b/02-peer-protocol.md index c2dd6a9f3..99b201825 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -3,13 +3,6 @@ The peer channel protocol has three phases: establishment, normal operation, and closing. -The messages described in this document are grouped logically into 4 groups by their most significant set bit: - - - Setup & signalling (types `0`-`31`): comprises setup of the cryptographic transport, communication of supported features and error reporting. These are described in BOLT #1. - - Channel (types `32`-`127`): comprises messages used to setup, update and tear down micropayment channels - - HTLC (types `128`-`255`: comprises messages related to adding, revoking and settling HTLCs on a micropayment channel - - Routing (types `256`-`511`): node and channel announcements, as well as any active route exploration. - # Table of Contents * [Channel](#channel) * [Channel Establishment](#channel-establishment)