From 94abc20c5f06e59db93c31598c0731963be38c4f Mon Sep 17 00:00:00 2001 From: pm47 Date: Mon, 5 Dec 2016 12:30:45 +0100 Subject: [PATCH 1/6] moved msg type description from BOLT#2 to BOLT#1 --- 01-messaging.md | 9 ++++++++- 02-peer-protocol.md | 7 ------- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/01-messaging.md b/01-messaging.md index fd50b8625..5392ec724 100644 --- a/01-messaging.md +++ b/01-messaging.md @@ -2,7 +2,7 @@ ## 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) @@ -23,6 +23,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`): comprises setup of the cryptographic transport, communication of 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. 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) From 8ae61d63e85694df344df4a3edae857338ac824b Mon Sep 17 00:00:00 2001 From: pm47 Date: Mon, 5 Dec 2016 12:45:47 +0100 Subject: [PATCH 2/6] added a ToC --- 01-messaging.md | 27 +++++++++++++++++++-------- 1 file changed, 19 insertions(+), 8 deletions(-) diff --git a/01-messaging.md b/01-messaging.md index fd50b8625..40fcd321b 100644 --- a/01-messaging.md +++ b/01-messaging.md @@ -8,6 +8,15 @@ The default TCP port is 9735. This corresponds to hexadecimal `0x2607`, the unic All data fields are big-endian unless otherwise specified. +## Table of Contents + * [Lightning Message Format](#lightning-message-format) + * [Setup Messages](#initialization-message) + * [The `init` message](#the-init-message) + * [The `error` message](#the-error-message) + * [Acknowledgments](#acknowledgments) + * [References](#references) + * [Authors](#authors) + ## Lightning Message Format After decryption, all lightning messages are of the form: @@ -46,7 +55,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 +72,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 +85,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 +98,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 +110,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 +127,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 +142,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 From 844ee6910e4a1aa6d993a711a6697253e9f7d8bb Mon Sep 17 00:00:00 2001 From: pm47 Date: Mon, 5 Dec 2016 12:47:59 +0100 Subject: [PATCH 3/6] fixed ToC links --- 01-messaging.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/01-messaging.md b/01-messaging.md index 40fcd321b..7ac1c6989 100644 --- a/01-messaging.md +++ b/01-messaging.md @@ -10,10 +10,10 @@ All data fields are big-endian unless otherwise specified. ## Table of Contents * [Lightning Message Format](#lightning-message-format) - * [Setup Messages](#initialization-message) + * [Setup Messages](#setup-messages) * [The `init` message](#the-init-message) * [The `error` message](#the-error-message) - * [Acknowledgments](#acknowledgments) + * [Acknowledgments](#acknowledgements) * [References](#references) * [Authors](#authors) From 58d1733d6d7389de40c81a9b0c745c9da1626eaa Mon Sep 17 00:00:00 2001 From: pm47 Date: Mon, 5 Dec 2016 12:51:46 +0100 Subject: [PATCH 4/6] typo --- 01-messaging.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/01-messaging.md b/01-messaging.md index 7ac1c6989..100cb7b42 100644 --- a/01-messaging.md +++ b/01-messaging.md @@ -13,7 +13,7 @@ All data fields are big-endian unless otherwise specified. * [Setup Messages](#setup-messages) * [The `init` message](#the-init-message) * [The `error` message](#the-error-message) - * [Acknowledgments](#acknowledgements) + * [Acknowledgements](#acknowledgements) * [References](#references) * [Authors](#authors) From 156d336ec3672afa5e16b2547a222c34499e267d Mon Sep 17 00:00:00 2001 From: pm47 Date: Mon, 5 Dec 2016 12:30:45 +0100 Subject: [PATCH 5/6] moved msg type description from BOLT#2 to BOLT#1 --- 01-messaging.md | 9 ++++++++- 02-peer-protocol.md | 7 ------- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/01-messaging.md b/01-messaging.md index 100cb7b42..052122fc9 100644 --- a/01-messaging.md +++ b/01-messaging.md @@ -2,7 +2,7 @@ ## 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) @@ -32,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`): comprises setup of the cryptographic transport, communication of 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. 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) From 1cb8217b1b0549fd9b1d69e46560e667e475b971 Mon Sep 17 00:00:00 2001 From: pm47 Date: Tue, 6 Dec 2016 15:49:56 +0100 Subject: [PATCH 6/6] removed 'setup of cryptographic transport' done in BOLT #8 --- 01-messaging.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/01-messaging.md b/01-messaging.md index 052122fc9..c46746ce6 100644 --- a/01-messaging.md +++ b/01-messaging.md @@ -34,7 +34,7 @@ A node MUST fail the channels if it receives a message of unknown type, if that The messages 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 below. + - 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).