From 7e4611af2b1a491c5bf577841123b258998d08ce Mon Sep 17 00:00:00 2001 From: Landon Mutch Date: Sat, 4 Nov 2017 08:53:23 -0700 Subject: [PATCH 01/23] copy-edit 00-introduction for appropriate grammer, punctuation, and style Edit 00-introduction copy for clarity (minor rephrasing, punctuation), correctness (grammar, capitalization, punctuation), consision (minimizing wordiness, redundancy), and consistency (document style, e.g. 1 space between sentences, capitalization of headers, etc.) --- 00-introduction.md | 52 +++++++++++++++++++++++----------------------- 1 file changed, 26 insertions(+), 26 deletions(-) diff --git a/00-introduction.md b/00-introduction.md index 1126a51c4..e0403a040 100644 --- a/00-introduction.md +++ b/00-introduction.md @@ -1,12 +1,12 @@ # BOLT #0: Introduction and Index -Welcome, friend! These Basis of Lightning Technology (BOLT) documents +Welcome, friend! These Basis of Lightning Technology (BOLT) documents describe a layer-2 protocol for off-chain bitcoin transfer by mutual cooperation, relying on on-chain transactions for enforcement if necessary. Some requirements are subtle; we have tried to highlight motivations -and reasoning behind the results you see here. I'm sure we've fallen +and reasoning behind the results you see here. I'm sure we've fallen short: if you find any part confusing, or wrong, please contact us and help us improve. @@ -25,21 +25,21 @@ This is version 0. ## Glossary and Terminology Guide -* *Funding Transaction*: - * The on-chain, irreversible transaction which pays to both peers - on a channel. Thus it can only be spent by mutual consent. +* *Funding transaction*: + * The on-chain, irreversible transaction that pays to both peers + on a channel. It can only be spent by mutual consent. * *Channel*: * A fast, off-chain method of mutual exchange between two *peers*. - To move funds, they exchange signatures for an updated *commitment + To move funds, peers exchange signatures for an updated *commitment transaction*. -* *Commitment Transaction*: - * A transaction which spends the funding transaction; each peer - holds a signature from the other peer for this transaction, so it - always has a commitment transaction it can spend. After a new +* *Commitment transaction*: + * A transaction which spends the funding transaction. Each peer + holds the other peer's signature for this transaction, so that it + always has a commitment transaction it can spend. After a new commitment transaction is negotiated, the old one is *revoked*. @@ -47,22 +47,22 @@ This is version 0. * A conditional payment between two peers: the recipient can spend the payment by presenting its signature and a *payment preimage*, otherwise the payer can cancel the contract by spending it after - a given time. These are implemented as outputs from the + a given time. These are implemented as outputs from the *commitment transaction*. * *Payment hash, payment preimage*: * The HTLC contains the payment hash, which is the hash of the - payment preimage. Only the final recipient knows the payment - preimage; thus when it reveals the preimage to collect funds is - considered proof that it received the payment. + payment preimage. Only the final recipient knows the payment + preimage. In order to release funds, the final recipient releases + the preimage as proof it has received payment. * *Commitment revocation key*: * Every *commitment transaction* has a unique *commitment revocation key* value which allows the other peer to spend all outputs immediately: revealing this key is how old commitment - transactions are revoked. To do this, each output refers to the + transactions are revoked. To do this, each output refers to the commitment revocation pubkey. @@ -72,36 +72,36 @@ This is version 0. for all previous commitments can be stored compactly. -* *Mutual Close*: +* *Mutual close*: * A cooperative close of a channel, by broadcasting an unconditional spend of the *funding transaction* with an output to each peer (unless one output is too small, and thus is not included). -* *Unilateral Close*: +* *Unilateral close*: * An uncooperative close of a channel, by broadcasting a - *commitment transaction*. This transaction is larger (ie. less + *commitment transaction*. This transaction is larger (ie. less efficient) than a mutual close transaction, and the peer whose commitment is broadcast cannot access its own outputs for some previously-negotiated duration. -* *Revoked Transaction Close*: +* *Revoked transaction close*: * An invalid close of the channel, by broadcasting a revoked - *commitment transaction*. Since the other peer knows the + *commitment transaction*. Since the other peer knows the *commitment revocation secret key*, it can create a *penalty transaction*. -* *Penalty Transaction*: +* *Penalty transaction*: * A transaction which spends all outputs of a revoked commitment - transaction, using the *commitment revocation secret key*. A peer uses this + transaction, using the *commitment revocation secret key*. A peer uses this if the other peer tries to "cheat" by broadcasting a revoked *commitment transaction*. -* *Commitment Number*: +* *Commitment number*: * A 48-bit incrementing counter for each *commitment transaction*; they - are independent for each peer in the channel, and start at 0. + are independent for each peer in the channel and start at 0. * *It's ok to be odd*: @@ -112,11 +112,11 @@ This is version 0. * `chain_hash`: - * Used in several of the BOLT documents, and denotes the genesis hash of a + * Used in several of the BOLT documents to denote the genesis hash of a target blockchain. This allows nodes to create and reference channels on several blockchains. Nodes are to ignore any messages which reference a `chain_hash` that are unknown to them. Unlike `bitcoin-cli` the hash is - not being reversed, and the hash is used directly. + not reversed but is used directly. For the main chain Bitcoin blockchain, the `chain_hash` value MUST be (encoded in hex): From 34878c0d96f540cd89eadd1fc5c001900bfa535c Mon Sep 17 00:00:00 2001 From: Landon Mutch Date: Sat, 4 Nov 2017 09:09:24 -0700 Subject: [PATCH 02/23] copy-edit 01-messaging for appropriate grammer, punctuation, and style Edit 01-messaging copy for clarity (minor rephrasing, punctuation), correctness (grammar, capitalization, punctuation), consision (minimizing wordiness, redundancy), and consistency (document style, e.g. 1 space between sentences, capitalization of headers, etc.) --- 01-messaging.md | 103 ++++++++++++++++++++++++------------------------ 1 file changed, 51 insertions(+), 52 deletions(-) diff --git a/01-messaging.md b/01-messaging.md index c19576bab..21dfdbbb3 100644 --- a/01-messaging.md +++ b/01-messaging.md @@ -9,42 +9,42 @@ 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 - * [Connection handling and multiplexing](#connection-handling-and-multiplexing) + * [Connection Handling and Multiplexing](#connection-handling-and-multiplexing) * [Lightning Message Format](#lightning-message-format) * [Setup Messages](#setup-messages) - * [The `init` message](#the-init-message) - * [The `error` message](#the-error-message) + * [The `init` Message](#the-init-message) + * [The `error` Message](#the-error-message) * [Control Messages](#control-messages) - * [The `ping` and `pong` messages](#the-ping-and-pong-messages) + * [The `ping` and `pong` Messages](#the-ping-and-pong-messages) * [Acknowledgments](#acknowledgments) * [References](#references) * [Authors](#authors) -## Connection handling and multiplexing +## Connection Handling and Multiplexing -Implementations MUST use one connection per peer, channel messages (which include a channel id) being multiplexed over this single connection. +Implementations MUST use one connection per peer, channel messages (which include a channel id) are multiplexed over this single connection. ## Lightning Message Format After decryption, all lightning messages are of the form: -1. `type`: 2 byte big-endian field indicating the type of the message. -2. `payload`: variable length payload. It comprises the remainder of +1. `type`: 2 byte big-endian field indicating the type of message. +2. `payload`: variable length payload which comprises the remainder of the message and conforms to the format matching the `type`. 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. +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. -The messages are grouped logically into 4 groups by their most significant set bit: +The messages are grouped logically into 4 groups, ordered by their most significant set bit: - Setup & Control (types `0`-`31`): messages related to connection setup, control, supported features, and error reporting. These are described below. - - Channel (types `32`-`127`): comprises messages used to setup and tear down micropayment channels. These are described in [BOLT #2](02-peer-protocol.md). - - Commitment (types `128`-`255`): comprises messages related to updating the current commitment transaction, which includes adding, revoking, and settling HTLCs, as well as updating fees and exchanging signatures. These are described in [BOLT #2](02-peer-protocol.md). + - Channel (types `32`-`127`): messages used to setup and tear down micropayment channels. These are described in [BOLT #2](02-peer-protocol.md). + - Commitment (types `128`-`255`): messages related to updating the current commitment transaction, which includes adding, revoking, and settling HTLCs, as well as updating fees and exchanging signatures. 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. @@ -72,10 +72,10 @@ a buffer with 6 bytes of pre-padding. ## Setup Messages -### The `init` message +### The `init` Message Once authentication is complete, the first message reveals the features supported or required by this node, even if this is a reconnection. -[BOLT #9](09-features.md) specifies lists of global and local features. Each feature is generally represented in `globalfeatures` or `localfeatures` by 2 bits. The least-significant bit is numbered 0, which is even, and the next most significant bit is numbered 1, which is odd. +[BOLT #9](09-features.md) specifies lists of global and local features. Each feature is generally represented in `globalfeatures` or `localfeatures` by 2 bits. The least-significant bit is numbered 0, which is even, and the next most significant bit is numbered 1, which is odd. Both fields `globalfeatures` and `localfeatures` MUST be padded to bytes with zeros. @@ -95,30 +95,30 @@ connection. The sending node SHOULD use the minimum lengths required to represent the feature fields. -The sender MUST set feature bits as defined in [BOLT #9](09-features.md), +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 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, +[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. Each node MUST wait to receive `init` before sending any other messages. #### Rationale -This semantic allows future incompatible changes, or backward -compatible changes. Bits should generally be assigned in pairs, so +This semantic allows future incompatible changes and/or backward +compatible changes. Bits should generally be assigned in pairs, so that optional features can later become compulsory. Nodes wait for receipt of the other's features to simplify error -diagnosis where features are incompatible. +diagnosis, where features are incompatible. -The feature masks are split into local features which only affect the -protocol between these two nodes, and global features which can affect +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. -### The `error` message +### The `error` Message For simplicity of diagnosis, it is often useful to tell the peer that something is incorrect. @@ -132,29 +132,29 @@ The 2-byte `len` field indicates the number of bytes in the immediately followin #### Requirements -The channel is referred to by `channel_id` unless `channel_id` is zero (ie. all bytes 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 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 +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 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 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 +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 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. +For reference, the printable character set includes byte values 32 through 127, inclusive. #### Rationale There are unrecoverable errors which require an abort of conversations; if the connection is simply dropped then the peer may retry the -connection. It's also useful to describe protocol violations for +connection. It's also useful to describe protocol violations for diagnosis, as it indicates that one peer has a bug. It may be wise not to distinguish errors in production settings, lest @@ -162,23 +162,23 @@ it leak information, thus the optional `data` field. ## Control Messages -### The `ping` and `pong` messages +### The `ping` and `pong` Messages In order to allow for the existence of very long-lived TCP connections, at times it may be required that both ends keep alive the TCP connection at the -application level. Such messages also allow obfuscation of traffic patterns. +application level. Such messages also allow obfuscation of traffic patterns. 1. type: 18 (`ping`) -2. data: +2. data: * [`2`:`num_pong_bytes`] * [`2`:`byteslen`] * [`byteslen`:`ignored`] The `pong` message is to be sent whenever a `ping` message is received. It -serves as a reply, and also serves to keep the connection alive while +serves as a reply and also serves to keep the connection alive while explicitly notifying the other end that the receiver is still active. Within the received `ping` message, the sender will specify the number of bytes to be -included within the data payload of the `pong` message +included within the data payload of the `pong` message. 1. type: 19 (`pong`) 2. data: @@ -188,42 +188,41 @@ 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 +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, +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 receiving a `ping` message SHOULD fail the channels if it has received -significantly in excess of one `ping` per 30 seconds, otherwise 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`. +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 `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 -The largest possible message is 65535 bytes, thus maximum sensible `byteslen` -is 65531 to account for the type field (`pong`) and `byteslen` itself. This -gives us a convenient cutoff for `num_pong_bytes` to indicate that no reply -should be sent. +The largest possible message is 65535 bytes, thus the maximum sensible `byteslen` +is 65531 in order to account for the type field (`pong`) and the `byteslen` itself. This allows +a convenient cutoff for `num_pong_bytes` to indicate that no reply should be sent. -Connections between nodes within the network may be very long lived as payment +Connections between nodes within the network may be very long lived, as payment channels have an indefinite lifetime. However, it's likely that for a significant portion of the life-time of a connection, no new data will be exchanged. Additionally, on several platforms it's possible that Lightning -clients will be put to sleep without prior warning. As a result, we use a +clients will be put to sleep without prior warning. As a result, we use a distinct ping message in order to probe for the liveness of the connection on -the other side, and also to keep the established connection active. +the other side as well as to keep the established connection active. Additionally, the ability for a sender to request that the receiver send a response with a particular number of bytes enables nodes on the network to create _synthetic_ traffic. Such traffic can be used to partially defend -against packet and timing analysis as nodes can fake the traffic patterns of -typical exchanges, without applying any true updates to their respective -channels. +against packet and timing analysis, as nodes can fake the traffic patterns of +typical exchanges without applying any true updates to their respective +channels. When combined with the onion routing protocol defined in [BOLT #4](https://github.com/lightningnetwork/lightning-rfc/blob/master/04-onion-routing.md), @@ -231,7 +230,7 @@ careful statistically driven synthetic traffic can serve to further bolster the privacy of participants within the network. Limited precautions are recommended against `ping` flooding, however some -latitude is given because of network delays. Note that there are other methods +latitude is given because of network delays. Note that there are other methods of incoming traffic flooding (eg. sending odd unknown message types, or padding every message maximally). From 5450ec193af336ab40c3f78708c0448cbf343a26 Mon Sep 17 00:00:00 2001 From: Landon Mutch Date: Sat, 4 Nov 2017 14:43:56 -0700 Subject: [PATCH 03/23] 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. --- 01-messaging.md | 88 ++++++++++++++++++++++++++++--------------------- 1 file changed, 50 insertions(+), 38 deletions(-) diff --git a/01-messaging.md b/01-messaging.md index 21dfdbbb3..ce8bbba6c 100644 --- a/01-messaging.md +++ b/01-messaging.md @@ -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 From 531317b3b413e16d13a04c7a8e324392b83d9cda Mon Sep 17 00:00:00 2001 From: Landon Mutch Date: Sat, 4 Nov 2017 18:53:46 -0700 Subject: [PATCH 04/23] Further clarify 01-messaging requirement structures by deepening branches. --- 01-messaging.md | 73 +++++++++++++++++++++++++++++-------------------- 1 file changed, 43 insertions(+), 30 deletions(-) diff --git a/01-messaging.md b/01-messaging.md index ce8bbba6c..263587036 100644 --- a/01-messaging.md +++ b/01-messaging.md @@ -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 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. - - 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. +- when receives message of unknown type + - if that type is odd + - MUST ignore the received message. + - otherwise type is even + - MUST fail the channels. 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. -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. +A node: + - MUST ignore any additional data within a message, beyond the length it expects for that type. + - if it receives a known message with insufficient length for the contents + - MUST fail the channels. ### Rationale @@ -96,20 +98,22 @@ 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. - - wait to receive `init` before sending any other messages. +Each node: + - MUST send `init` as the first lightning message for any connection. + - MUST wait to receive `init` before sending any other messages. 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 receiving node MUST: - - respond to known feature bits as specified in [BOLT #9](09-features.md). +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. + - if the bit number is odd + - MUST ignore the bit. + - otherwise the bit number is even + - MUST fail the connection. #### 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 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: + - 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: - 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 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`. + - when sending or receiving `error` + - MUST fail the channel referred to by the error message + - when `channel_id` is zero + - MUST fail all channels + - and MUST close the connection. + - MUST set `len` equal to the length of `data`. The receiving node: - if no existing channel is referred to by the message @@ -197,19 +207,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 -memory. - 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 - 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: - 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: - MAY fail the channels, if `byteslen` does not From 2f6a629a03cc60fee82eb8a7e20cf60ee13b66fb Mon Sep 17 00:00:00 2001 From: Landon Mutch Date: Thu, 9 Nov 2017 13:30:31 -0800 Subject: [PATCH 05/23] minor grammar, punctuation, and capitalization fixes; --- 00-introduction.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/00-introduction.md b/00-introduction.md index e0403a040..bf0dab1e6 100644 --- a/00-introduction.md +++ b/00-introduction.md @@ -1,7 +1,7 @@ # BOLT #0: Introduction and Index Welcome, friend! These Basis of Lightning Technology (BOLT) documents -describe a layer-2 protocol for off-chain bitcoin transfer by mutual +describe a layer-2 protocol for off-chain Bitcoin transfer by mutual cooperation, relying on on-chain transactions for enforcement if necessary. @@ -79,15 +79,15 @@ This is version 0. * *Unilateral close*: - * An uncooperative close of a channel, by broadcasting a - *commitment transaction*. This transaction is larger (ie. less + * An uncooperative close of a channel, through broadcasting of a + *commitment transaction*. This transaction is larger (i.e. less efficient) than a mutual close transaction, and the peer whose commitment is broadcast cannot access its own outputs for some previously-negotiated duration. * *Revoked transaction close*: - * An invalid close of the channel, by broadcasting a revoked + * An invalid close of the channel, through broadcasting of a revoked *commitment transaction*. Since the other peer knows the *commitment revocation secret key*, it can create a *penalty transaction*. @@ -100,7 +100,7 @@ This is version 0. * *Commitment number*: - * A 48-bit incrementing counter for each *commitment transaction*; they + * A 48-bit incrementing counter for each *commitment transaction*; counters are independent for each peer in the channel and start at 0. @@ -115,7 +115,7 @@ This is version 0. * Used in several of the BOLT documents to denote the genesis hash of a target blockchain. This allows nodes to create and reference channels on several blockchains. Nodes are to ignore any messages which reference a - `chain_hash` that are unknown to them. Unlike `bitcoin-cli` the hash is + `chain_hash` that are unknown to them. Unlike `bitcoin-cli`, the hash is not reversed but is used directly. For the main chain Bitcoin blockchain, the `chain_hash` value MUST be From cc86516411f9d1e28b6ccc8210b8f2b36c91a22f Mon Sep 17 00:00:00 2001 From: Landon Mutch Date: Thu, 9 Nov 2017 13:30:53 -0800 Subject: [PATCH 06/23] Make pull request changes; re-structure requirements; correct grammar Implement changes requested by @rustyrussell: wording change, structure requirements according to whether nodes are sending or receiving; Correct grammar, punctuation, capitalization, and style for correctness, concision, clarity, comprehension, and consistency; --- 01-messaging.md | 161 +++++++++++++++++++++++++----------------------- 1 file changed, 83 insertions(+), 78 deletions(-) diff --git a/01-messaging.md b/01-messaging.md index 263587036..b90535cc0 100644 --- a/01-messaging.md +++ b/01-messaging.md @@ -4,7 +4,7 @@ This protocol assumes an underlying authenticated and ordered transport mechanism that takes care of framing individual messages. [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.[1](#reference-1) +The default TCP port is 9735. This corresponds to hexadecimal `0x2607`: the Unicode code point for LIGHTNING.[1](#reference-1) All data fields are big-endian unless otherwise specified. @@ -22,12 +22,12 @@ All data fields are big-endian unless otherwise specified. ## Connection Handling and Multiplexing -Implementations MUST use one connection per peer, channel messages (which include a channel id) are multiplexed over this single connection. +Implementations MUST use a single connection per peer — channel messages (which include a channel id) are multiplexed over this single connection. ## Lightning Message Format -After decryption, all lightning messages are of the form: +After decryption, all Lightning messages are of the form: 1. `type`: 2 byte big-endian field indicating the type of message. 2. `payload`: variable length payload which comprises the remainder of @@ -35,15 +35,16 @@ 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. +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. -- when receives message of unknown type - - if that type is odd - - MUST ignore the received message. - - otherwise type is even - - MUST fail the channels. +A sending node: +- MUST NOT send an evenly-typed message not listed here, without prior negotiation. + +A receiving node: +- upon receiving a message of odd, unknown type: + - MUST ignore the received message. +- upon receiving a message of even, unknown type: + - MUST fail the channels. The messages are grouped logically into 4 groups, ordered by their most significant set bit: @@ -52,11 +53,11 @@ The messages are grouped logically into 4 groups, ordered by their most signific - Commitment (types `128`-`255`): messages related to updating the current commitment transaction, which includes adding, revoking, and settling HTLCs, as well as updating fees and exchanging signatures. 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. +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: +A receiving node: - MUST ignore any additional data within a message, beyond the length it expects for that type. - - if it receives a known message with insufficient length for the contents + - upon receiving a known message with insufficient length for the contents: - MUST fail the channels. ### Rationale @@ -69,12 +70,12 @@ Length is limited to 65535 bytes by the cryptographic wrapping, and messages in the protocol are never more than that length anyway. The "it's OK to be odd" rule allows for future optional extensions -without negotiation or special coding in clients. The "ignore +without negotiation or special coding in clients. The "ignore additional data" rule similarly allows for future expansion. Implementations may prefer to have message data aligned on an 8 byte -boundary (the largest natural alignment requirement of any type here), -but adding a 6 byte padding after the type field was considered +boundary (the largest natural alignment requirement of any type here); +however, 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. @@ -83,7 +84,7 @@ a buffer with 6 bytes of pre-padding. ### The `init` Message Once authentication is complete, the first message reveals the features supported or required by this node, even if this is a reconnection. -[BOLT #9](09-features.md) specifies lists of global and local features. Each feature is generally represented in `globalfeatures` or `localfeatures` by 2 bits. The least-significant bit is numbered 0, which is even, and the next most significant bit is numbered 1, which is odd. +[BOLT #9](09-features.md) specifies lists of global and local features. Each feature is generally represented in `globalfeatures` or `localfeatures` by 2 bits. The least-significant bit is numbered 0, which is even, and the next most significant bit is numbered 1, which is odd. Both fields `globalfeatures` and `localfeatures` MUST be padded to bytes with zeros. @@ -98,40 +99,35 @@ 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. - - MUST wait to receive `init` before sending any other messages. - 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 send `init` as the first Lightning message for any connection. + - 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 receiving node: + - MUST wait to receive `init` before sending any other messages. - MUST respond to known feature bits as specified in [BOLT #9](09-features.md). - - for unknown feature bits which are non-zero: - - if the bit number is odd - - MUST ignore the bit. - - otherwise the bit number is even - - MUST fail the connection. + - upon receiving odd feature bits which are non-zero: + - MUST ignore the bit. + - upon receiving even feature bits which are non-zero: + - MUST fail the connection. #### Rationale -This semantic allows future incompatible changes and/or backward -compatible changes. Bits should generally be assigned in pairs, so -that optional features can later become compulsory. +This semantic allows both future incompatible changes and future backward compatible changes. Bits should generally be assigned in pairs, in order that optional features may later become compulsory. Nodes wait for receipt of the other's features to simplify error diagnosis, where features are incompatible. -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. +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 are thus also advertised to other nodes. ### The `error` Message -For simplicity of diagnosis, it is often useful to tell the peer that something is incorrect. +For simplicity of diagnosis, it's often useful to tell a peer that something is incorrect. 1. type: 17 (`error`) 2. data: @@ -143,42 +139,47 @@ The 2-byte `len` field indicates the number of bytes in the immediately followin #### Requirements -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 (i.e. all bytes are zero), in which case it refers to all channels. The funding node: - - for all error messages sent before (and including) the `funding_created` 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 + - 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 sending node: + - when sending `error`: + - MUST fail the channel referred to by the error message. - 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. - - when sending or receiving `error` - - MUST fail the channel referred to by the error message - - when `channel_id` is zero - - MUST fail all channels + - 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 `channel_id` is zero: + - MUST fail all channels, - and MUST close the connection. - - MUST set `len` equal to the length of `data`. + - MUST set `len` equal to the length of `data`. The receiving node: - - if no existing channel is referred to by the message + - upon receiving `error`: + - MUST fail the channel referred to by the error message. + - 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). + - if it's larger: + - MUST truncate `len` to the remainder of the packet. + - if the string is composed solely of printable ASCII characters (For reference: the printable character set includes byte values 32 through 127, inclusive): + - SHOULD only print out `data` verbatim. #### Rationale There are unrecoverable errors which require an abort of conversations; -if the connection is simply dropped then the peer may retry the +if the connection is simply dropped, then the peer may retry the connection. It's also useful to describe protocol violations for -diagnosis, as it indicates that one peer has a bug. +diagnosis, as this indicates that one peer has a bug. It may be wise not to distinguish errors in production settings, lest -it leak information, thus the optional `data` field. +it leak information — hence, the optional `data` field. ## Control Messages @@ -195,7 +196,7 @@ application level. Such messages also allow obfuscation of traffic patterns. * [`byteslen`:`ignored`] The `pong` message is to be sent whenever a `ping` message is received. It -serves as a reply and also serves to keep the connection alive while +serves as a reply and also serves to keep the connection alive, while explicitly notifying the other end that the receiver is still active. Within the received `ping` message, the sender will specify the number of bytes to be included within the data payload of the `pong` message. @@ -207,46 +208,50 @@ included within the data payload of the `pong` message. #### Requirements -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 +A node sending a `ping` message: + - 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 - - MAY terminate the network connection if it does not receive a corresponding -`pong` + - if it doesn't receive a corresponding `pong`: + - MAY terminate the network connection, - and MUST NOT fail the channels in this case. + - SHOULD NOT send `ping` messages more often than once every 30 seconds. + +A node sending a `pong` message: + - SHOULD set `ignored` to zeroes, + - but MUST NOT set `ignored` to sensitive data such as secrets or portions of initialized + memory. 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 - - MUST respond by sending a `pong` message, with `byteslen` equal to `num_pong_bytes` - - otherwise + - 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: + - MUST respond by sending a `pong` message, with `byteslen` equal to `num_pong_bytes`. + - otherwise (`num_pong_bytes` is not less than 65532): - it MUST ignore the `ping`. 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. + - if `byteslen` does not correspond to any `ping`'s `num_pong_bytes` value it has sent: + - MAY fail the channels. ### Rationale -The largest possible message is 65535 bytes, thus the maximum sensible `byteslen` -is 65531 in order to account for the type field (`pong`) and the `byteslen` itself. This allows +The largest possible message is 65535 bytes; thus, the maximum sensible `byteslen` +is 65531 — in order to account for the type field (`pong`) and the `byteslen` itself. This allows a convenient cutoff for `num_pong_bytes` to indicate that no reply should be sent. Connections between nodes within the network may be very long lived, as payment channels have an indefinite lifetime. However, it's likely that for a -significant portion of the life-time of a connection, no new data will be -exchanged. Additionally, on several platforms it's possible that Lightning -clients will be put to sleep without prior warning. As a result, we use a -distinct ping message in order to probe for the liveness of the connection on -the other side as well as to keep the established connection active. +significant portion of the lifetime of a connection, no new data will be +exchanged. Also, on several platforms it's possible that Lightning +clients will be put to sleep without prior warning. Hence, we use a +distinct `ping` message, in order to probe for the liveness of the connection on +the other side, as well as to keep the established connection active. Additionally, the ability for a sender to request that the receiver send a response with a particular number of bytes enables nodes on the network to create _synthetic_ traffic. Such traffic can be used to partially defend -against packet and timing analysis, as nodes can fake the traffic patterns of -typical exchanges without applying any true updates to their respective +against packet and timing analysis — as nodes can fake the traffic patterns of +typical exchanges, without applying any true updates to their respective channels. When combined with the onion routing protocol defined in @@ -256,7 +261,7 @@ privacy of participants within the network. Limited precautions are recommended against `ping` flooding, however some latitude is given because of network delays. Note that there are other methods -of incoming traffic flooding (eg. sending odd unknown message types, or padding +of incoming traffic flooding (e.g. sending odd unknown message types, or padding every message maximally). Finally, the usage of periodic `ping` messages serves to promote frequent key @@ -265,7 +270,7 @@ rotations as specified within [BOLT #8](https://github.com/lightningnetwork/ligh ## Acknowledgments -TODO(roasbeef); fin +[ TODO: (roasbeef); fin ] ## References @@ -273,7 +278,7 @@ TODO(roasbeef); fin ## Authors -FIXME +[ FIXME: Insert Author List ] ![Creative Commons License](https://i.creativecommons.org/l/by/4.0/88x31.png "License CC-BY")
From 2d829756e1bc9cd20e3f9502e28e55a18e4695f7 Mon Sep 17 00:00:00 2001 From: Landon Mutch Date: Thu, 9 Nov 2017 13:30:53 -0800 Subject: [PATCH 07/23] Amend: Make pull request changes; re-structure requirements; correct grammar Implement changes requested by @rustyrussell: wording change, structure requirements according to whether nodes are sending or receiving; Correct grammar, punctuation, capitalization, and style for correctness, concision, clarity, comprehension, and consistency; --- 01-messaging.md | 161 +++++++++++++++++++++++++----------------------- 1 file changed, 83 insertions(+), 78 deletions(-) diff --git a/01-messaging.md b/01-messaging.md index 263587036..e01e31a39 100644 --- a/01-messaging.md +++ b/01-messaging.md @@ -4,7 +4,7 @@ This protocol assumes an underlying authenticated and ordered transport mechanism that takes care of framing individual messages. [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.[1](#reference-1) +The default TCP port is 9735. This corresponds to hexadecimal `0x2607`: the Unicode code point for LIGHTNING.[1](#reference-1) All data fields are big-endian unless otherwise specified. @@ -22,12 +22,12 @@ All data fields are big-endian unless otherwise specified. ## Connection Handling and Multiplexing -Implementations MUST use one connection per peer, channel messages (which include a channel id) are multiplexed over this single connection. +Implementations MUST use a single connection per peer — channel messages (which include a channel id) are multiplexed over this single connection. ## Lightning Message Format -After decryption, all lightning messages are of the form: +After decryption, all Lightning messages are of the form: 1. `type`: 2 byte big-endian field indicating the type of message. 2. `payload`: variable length payload which comprises the remainder of @@ -35,15 +35,16 @@ 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. +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. -- when receives message of unknown type - - if that type is odd - - MUST ignore the received message. - - otherwise type is even - - MUST fail the channels. +A sending node: +- MUST NOT send an evenly-typed message not listed here, without prior negotiation. + +A receiving node: +- upon receiving a message of odd, unknown type: + - MUST ignore the received message. +- upon receiving a message of even, unknown type: + - MUST fail the channels. The messages are grouped logically into 4 groups, ordered by their most significant set bit: @@ -52,11 +53,11 @@ The messages are grouped logically into 4 groups, ordered by their most signific - Commitment (types `128`-`255`): messages related to updating the current commitment transaction, which includes adding, revoking, and settling HTLCs, as well as updating fees and exchanging signatures. 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. +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: +A receiving node: - MUST ignore any additional data within a message, beyond the length it expects for that type. - - if it receives a known message with insufficient length for the contents + - upon receiving a known message with insufficient length for the contents: - MUST fail the channels. ### Rationale @@ -69,12 +70,12 @@ Length is limited to 65535 bytes by the cryptographic wrapping, and messages in the protocol are never more than that length anyway. The "it's OK to be odd" rule allows for future optional extensions -without negotiation or special coding in clients. The "ignore +without negotiation or special coding in clients. The "ignore additional data" rule similarly allows for future expansion. Implementations may prefer to have message data aligned on an 8 byte -boundary (the largest natural alignment requirement of any type here), -but adding a 6 byte padding after the type field was considered +boundary (the largest natural alignment requirement of any type here); +however, 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. @@ -83,7 +84,7 @@ a buffer with 6 bytes of pre-padding. ### The `init` Message Once authentication is complete, the first message reveals the features supported or required by this node, even if this is a reconnection. -[BOLT #9](09-features.md) specifies lists of global and local features. Each feature is generally represented in `globalfeatures` or `localfeatures` by 2 bits. The least-significant bit is numbered 0, which is even, and the next most significant bit is numbered 1, which is odd. +[BOLT #9](09-features.md) specifies lists of global and local features. Each feature is generally represented in `globalfeatures` or `localfeatures` by 2 bits. The least-significant bit is numbered 0, which is even, and the next most significant bit is numbered 1, which is odd. Both fields `globalfeatures` and `localfeatures` MUST be padded to bytes with zeros. @@ -98,40 +99,35 @@ 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. - - MUST wait to receive `init` before sending any other messages. - 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 send `init` as the first Lightning message for any connection. + - 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 receiving node: + - MUST wait to receive `init` before sending any other messages. - MUST respond to known feature bits as specified in [BOLT #9](09-features.md). - - for unknown feature bits which are non-zero: - - if the bit number is odd - - MUST ignore the bit. - - otherwise the bit number is even - - MUST fail the connection. + - upon receiving odd feature bits which are non-zero: + - MUST ignore the bit. + - upon receiving even feature bits which are non-zero: + - MUST fail the connection. #### Rationale -This semantic allows future incompatible changes and/or backward -compatible changes. Bits should generally be assigned in pairs, so -that optional features can later become compulsory. +This semantic allows both future incompatible changes and future backward compatible changes. Bits should generally be assigned in pairs, in order that optional features may later become compulsory. Nodes wait for receipt of the other's features to simplify error diagnosis, where features are incompatible. -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. +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 are thus also advertised to other nodes. ### The `error` Message -For simplicity of diagnosis, it is often useful to tell the peer that something is incorrect. +For simplicity of diagnosis, it's often useful to tell a peer that something is incorrect. 1. type: 17 (`error`) 2. data: @@ -143,42 +139,47 @@ The 2-byte `len` field indicates the number of bytes in the immediately followin #### Requirements -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 (i.e. all bytes are zero), in which case it refers to all channels. The funding node: - - for all error messages sent before (and including) the `funding_created` 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 + - 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 sending node: + - when sending `error`: + - MUST fail the channel referred to by the error message. - 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. - - when sending or receiving `error` - - MUST fail the channel referred to by the error message - - when `channel_id` is zero - - MUST fail all channels + - 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 `channel_id` is zero: + - MUST fail all channels, - and MUST close the connection. - - MUST set `len` equal to the length of `data`. + - MUST set `len` equal to the length of `data`. The receiving node: - - if no existing channel is referred to by the message + - upon receiving `error`: + - MUST fail the channel referred to by the error message. + - 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). + - if it's larger: + - MUST truncate `len` to the remainder of the packet. + - if the string is composed solely of printable ASCII characters (For reference: the printable character set includes byte values 32 through 127, inclusive): + - SHOULD only print out `data` verbatim. #### Rationale There are unrecoverable errors which require an abort of conversations; -if the connection is simply dropped then the peer may retry the +if the connection is simply dropped, then the peer may retry the connection. It's also useful to describe protocol violations for -diagnosis, as it indicates that one peer has a bug. +diagnosis, as this indicates that one peer has a bug. It may be wise not to distinguish errors in production settings, lest -it leak information, thus the optional `data` field. +it leak information — hence, the optional `data` field. ## Control Messages @@ -195,7 +196,7 @@ application level. Such messages also allow obfuscation of traffic patterns. * [`byteslen`:`ignored`] The `pong` message is to be sent whenever a `ping` message is received. It -serves as a reply and also serves to keep the connection alive while +serves as a reply and also serves to keep the connection alive, while explicitly notifying the other end that the receiver is still active. Within the received `ping` message, the sender will specify the number of bytes to be included within the data payload of the `pong` message. @@ -207,46 +208,50 @@ included within the data payload of the `pong` message. #### Requirements -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 +A node sending a `ping` message: + - SHOULD set `ignored` to zeros, + - 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 - - MAY terminate the network connection if it does not receive a corresponding -`pong` + - if it doesn't receive a corresponding `pong`: + - MAY terminate the network connection, - and MUST NOT fail the channels in this case. + - SHOULD NOT send `ping` messages more often than once every 30 seconds. + +A node sending a `pong` message: + - SHOULD set `ignored` to zeros, + - but MUST NOT set `ignored` to sensitive data such as secrets or portions of initialized + memory. 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 - - MUST respond by sending a `pong` message, with `byteslen` equal to `num_pong_bytes` - - otherwise + - 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: + - MUST respond by sending a `pong` message, with `byteslen` equal to `num_pong_bytes`. + - otherwise (`num_pong_bytes` is not less than 65532): - it MUST ignore the `ping`. 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. + - if `byteslen` does not correspond to any `ping`'s `num_pong_bytes` value it has sent: + - MAY fail the channels. ### Rationale -The largest possible message is 65535 bytes, thus the maximum sensible `byteslen` -is 65531 in order to account for the type field (`pong`) and the `byteslen` itself. This allows +The largest possible message is 65535 bytes; thus, the maximum sensible `byteslen` +is 65531 — in order to account for the type field (`pong`) and the `byteslen` itself. This allows a convenient cutoff for `num_pong_bytes` to indicate that no reply should be sent. Connections between nodes within the network may be very long lived, as payment channels have an indefinite lifetime. However, it's likely that for a -significant portion of the life-time of a connection, no new data will be -exchanged. Additionally, on several platforms it's possible that Lightning -clients will be put to sleep without prior warning. As a result, we use a -distinct ping message in order to probe for the liveness of the connection on -the other side as well as to keep the established connection active. +significant portion of the lifetime of a connection, no new data will be +exchanged. Also, on several platforms it's possible that Lightning +clients will be put to sleep without prior warning. Hence, we use a +distinct `ping` message, in order to probe for the liveness of the connection on +the other side, as well as to keep the established connection active. Additionally, the ability for a sender to request that the receiver send a response with a particular number of bytes enables nodes on the network to create _synthetic_ traffic. Such traffic can be used to partially defend -against packet and timing analysis, as nodes can fake the traffic patterns of -typical exchanges without applying any true updates to their respective +against packet and timing analysis — as nodes can fake the traffic patterns of +typical exchanges, without applying any true updates to their respective channels. When combined with the onion routing protocol defined in @@ -256,7 +261,7 @@ privacy of participants within the network. Limited precautions are recommended against `ping` flooding, however some latitude is given because of network delays. Note that there are other methods -of incoming traffic flooding (eg. sending odd unknown message types, or padding +of incoming traffic flooding (e.g. sending odd unknown message types, or padding every message maximally). Finally, the usage of periodic `ping` messages serves to promote frequent key @@ -265,7 +270,7 @@ rotations as specified within [BOLT #8](https://github.com/lightningnetwork/ligh ## Acknowledgments -TODO(roasbeef); fin +[ TODO: (roasbeef); fin ] ## References @@ -273,7 +278,7 @@ TODO(roasbeef); fin ## Authors -FIXME +[ FIXME: Insert Author List ] ![Creative Commons License](https://i.creativecommons.org/l/by/4.0/88x31.png "License CC-BY")
From c3ef4cabe5bf1893787a88a6dee3b8e20ab0d301 Mon Sep 17 00:00:00 2001 From: Landon Mutch Date: Thu, 9 Nov 2017 18:32:52 -0800 Subject: [PATCH 08/23] fix 00-introduction, 01-messaging section spacings for format consistency --- 00-introduction.md | 65 +++++++++++++++++++++------------------------- 01-messaging.md | 4 --- 2 files changed, 30 insertions(+), 39 deletions(-) diff --git a/00-introduction.md b/00-introduction.md index bf0dab1e6..e403ce81e 100644 --- a/00-introduction.md +++ b/00-introduction.md @@ -26,44 +26,43 @@ This is version 0. ## Glossary and Terminology Guide * *Funding transaction*: - * The on-chain, irreversible transaction that pays to both peers - on a channel. It can only be spent by mutual consent. + * The on-chain, irreversible transaction that pays to both peers on a channel. + It can only be spent by mutual consent. * *Channel*: * A fast, off-chain method of mutual exchange between two *peers*. - To move funds, peers exchange signatures for an updated *commitment - transaction*. + To move funds, peers exchange signatures for an updated *commitment transaction*. * *Commitment transaction*: - * A transaction which spends the funding transaction. Each peer - holds the other peer's signature for this transaction, so that it - always has a commitment transaction it can spend. After a new - commitment transaction is negotiated, the old one is *revoked*. + * A transaction which spends the funding transaction. + Each peer holds the other peer's signature for this transaction, so that it + always has a commitment transaction it can spend. After a new + commitment transaction is negotiated, the old one is *revoked*. * *HTLC*: Hashed Time Locked Contract. * A conditional payment between two peers: the recipient can spend - the payment by presenting its signature and a *payment preimage*, - otherwise the payer can cancel the contract by spending it after - a given time. These are implemented as outputs from the - *commitment transaction*. + the payment by presenting its signature and a *payment preimage*, + otherwise the payer can cancel the contract by spending it after + a given time. These are implemented as outputs from the + *commitment transaction*. * *Payment hash, payment preimage*: * The HTLC contains the payment hash, which is the hash of the - payment preimage. Only the final recipient knows the payment - preimage. In order to release funds, the final recipient releases - the preimage as proof it has received payment. + payment preimage. Only the final recipient knows the payment + preimage. In order to release funds, the final recipient releases + the preimage as proof it has received payment. * *Commitment revocation key*: * Every *commitment transaction* has a unique *commitment revocation key* - value which allows the other peer to spend all outputs - immediately: revealing this key is how old commitment - transactions are revoked. To do this, each output refers to the - commitment revocation pubkey. + value which allows the other peer to spend all outputs + immediately: revealing this key is how old commitment + transactions are revoked. To do this, each output refers to the + commitment revocation pubkey. * *Per-commitment secret*: @@ -74,34 +73,34 @@ This is version 0. * *Mutual close*: * A cooperative close of a channel, by broadcasting an unconditional - spend of the *funding transaction* with an output to each peer - (unless one output is too small, and thus is not included). + spend of the *funding transaction* with an output to each peer + (unless one output is too small, and thus is not included). * *Unilateral close*: * An uncooperative close of a channel, through broadcasting of a - *commitment transaction*. This transaction is larger (i.e. less - efficient) than a mutual close transaction, and the peer whose - commitment is broadcast cannot access its own outputs for some - previously-negotiated duration. + *commitment transaction*. This transaction is larger (i.e. less + efficient) than a mutual close transaction, and the peer whose + commitment is broadcast cannot access its own outputs for some + previously-negotiated duration. * *Revoked transaction close*: * An invalid close of the channel, through broadcasting of a revoked - *commitment transaction*. Since the other peer knows the - *commitment revocation secret key*, it can create a *penalty transaction*. + *commitment transaction*. Since the other peer knows the + *commitment revocation secret key*, it can create a *penalty transaction*. * *Penalty transaction*: * A transaction which spends all outputs of a revoked commitment - transaction, using the *commitment revocation secret key*. A peer uses this - if the other peer tries to "cheat" by broadcasting a revoked - *commitment transaction*. + transaction, using the *commitment revocation secret key*. A peer uses this + if the other peer tries to "cheat" by broadcasting a revoked + *commitment transaction*. * *Commitment number*: * A 48-bit incrementing counter for each *commitment transaction*; counters - are independent for each peer in the channel and start at 0. + are independent for each peer in the channel and start at 0. * *It's ok to be odd*: @@ -124,7 +123,6 @@ This is version 0. ## Theme Song - Why this network could be democratic... Numismatic... Cryptographic! @@ -172,13 +170,10 @@ This is version 0. -- Anthony Towns - ## Authors - [ FIXME: Insert Author List ] - ![Creative Commons License](https://i.creativecommons.org/l/by/4.0/88x31.png "License CC-BY")
This work is licensed under a [Creative Commons Attribution 4.0 International License](http://creativecommons.org/licenses/by/4.0/). diff --git a/01-messaging.md b/01-messaging.md index e01e31a39..4e19749e1 100644 --- a/01-messaging.md +++ b/01-messaging.md @@ -24,7 +24,6 @@ All data fields are big-endian unless otherwise specified. Implementations MUST use a single connection per peer — channel messages (which include a channel id) are multiplexed over this single connection. - ## Lightning Message Format After decryption, all Lightning messages are of the form: @@ -113,7 +112,6 @@ The receiving node: - upon receiving even feature bits which are non-zero: - MUST fail the connection. - #### Rationale This semantic allows both future incompatible changes and future backward compatible changes. Bits should generally be assigned in pairs, in order that optional features may later become compulsory. @@ -267,12 +265,10 @@ every message maximally). Finally, the usage of periodic `ping` messages serves to promote frequent key rotations as specified within [BOLT #8](https://github.com/lightningnetwork/lightning-rfc/blob/master/08-transport.md). - ## Acknowledgments [ TODO: (roasbeef); fin ] - ## References 1. http://www.unicode.org/charts/PDF/U2600.pdf From 919df997a37cda0bd6688c624b1fe3d940686937 Mon Sep 17 00:00:00 2001 From: Landon Mutch Date: Thu, 9 Nov 2017 18:55:40 -0800 Subject: [PATCH 09/23] fix 01-messaging unordered list spacing so formats correctly in githubs markdown --- 01-messaging.md | 111 ++++++++++++++++++++++++------------------------ 1 file changed, 55 insertions(+), 56 deletions(-) diff --git a/01-messaging.md b/01-messaging.md index 4e19749e1..72c033258 100644 --- a/01-messaging.md +++ b/01-messaging.md @@ -37,26 +37,26 @@ The format for each individual type is specified in a specification in this repo 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 sending node: -- MUST NOT send an evenly-typed message not listed here, without prior negotiation. + - MUST NOT send an evenly-typed message not listed here, without prior negotiation. A receiving node: -- upon receiving a message of odd, unknown type: - - MUST ignore the received message. -- upon receiving a message of even, unknown type: - - MUST fail the channels. + - upon receiving a message of odd, unknown type: + - MUST ignore the received message. + - upon receiving a message of even, unknown type: + - MUST fail the channels. The messages are grouped logically into 4 groups, ordered by their most significant set bit: - - Setup & Control (types `0`-`31`): messages related to connection setup, control, supported features, and error reporting. These are described below. - - Channel (types `32`-`127`): messages used to setup and tear down micropayment channels. These are described in [BOLT #2](02-peer-protocol.md). - - Commitment (types `128`-`255`): messages related to updating the current commitment transaction, which includes adding, revoking, and settling HTLCs, as well as updating fees and exchanging signatures. 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). + - Setup & Control (types `0`-`31`): messages related to connection setup, control, supported features, and error reporting. These are described below. + - Channel (types `32`-`127`): messages used to setup and tear down micropayment channels. These are described in [BOLT #2](02-peer-protocol.md). + - Commitment (types `128`-`255`): messages related to updating the current commitment transaction, which includes adding, revoking, and settling HTLCs, as well as updating fees and exchanging signatures. 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 receiving node: - - MUST ignore any additional data within a message, beyond the length it expects for that type. - - upon receiving a known message with insufficient length for the contents: + - MUST ignore any additional data within a message, beyond the length it expects for that type. + - upon receiving a known message with insufficient length for the contents: - MUST fail the channels. ### Rationale @@ -99,18 +99,18 @@ The 2 byte `gflen` and `lflen` fields indicate the number of bytes in the immedi #### Requirements The sending node: - - MUST send `init` as the first Lightning message for any connection. - - 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. + - MUST send `init` as the first Lightning message for any connection. + - MUST set feature bits as defined in [BOLT #9](09-features.md). + - MUST set to zero any feature bits that are not defined. + - SHOULD use the minimum lengths required to represent the feature fields. The receiving node: - - MUST wait to receive `init` before sending any other messages. - - MUST respond to known feature bits as specified in [BOLT #9](09-features.md). - - upon receiving odd feature bits which are non-zero: - - MUST ignore the bit. - - upon receiving even feature bits which are non-zero: - - MUST fail the connection. + - MUST wait to receive `init` before sending any other messages. + - MUST respond to known feature bits as specified in [BOLT #9](09-features.md). + - upon receiving odd feature bits which are non-zero: + - MUST ignore the bit. + - upon receiving even feature bits which are non-zero: + - MUST fail the connection. #### Rationale @@ -140,34 +140,33 @@ 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 (i.e. all bytes are zero), in which case it refers to all channels. The funding node: - - for all error messages sent before (and including) the `funding_created` message: - - MUST use `temporary_channel_id` in lieu of `channel_id`. + - 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`. + - for all error messages sent before (and not including) the `funding_signed` message: + - MUST use `temporary_channel_id` in lieu of `channel_id`. A sending node: - - when sending `error`: - - MUST fail the channel referred to by the error message. - - SHOULD send `error` for protocol violations or internal errors which make channels unusable or further communication unusable. - - MAY send an empty `data` field. - - 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 `channel_id` is zero: - - MUST fail all channels, - - and MUST close the connection. - - MUST set `len` equal to the length of `data`. + - when sending `error`: + - MUST fail the channel referred to by the error message. + - SHOULD send `error` for protocol violations or internal errors which make channels unusable or further communication unusable. + - MAY send an empty `data` field. + - 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 `channel_id` is zero: + - MUST fail all channels, + - and MUST close the connection. + - MUST set `len` equal to the length of `data`. The receiving node: - - upon receiving `error`: - - MUST fail the channel referred to by the error message. - - if no existing channel is referred to by the message: - - MUST ignore the message. - - if it's larger: - - MUST truncate `len` to the remainder of the packet. - - if the string is composed solely of printable ASCII characters (For reference: the printable character set includes byte values 32 through 127, inclusive): - - SHOULD only print out `data` verbatim. + - upon receiving `error`: + - MUST fail the channel referred to by the error message. + - 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's larger). + - if the string is composed solely of printable ASCII characters (For reference: the printable character set includes byte values 32 through 127, inclusive): + - SHOULD only print out `data` verbatim. #### Rationale @@ -207,13 +206,13 @@ included within the data payload of the `pong` message. #### Requirements A node sending a `ping` message: - - SHOULD set `ignored` to zeros, - - but MUST NOT set `ignored` to sensitive data such as secrets or portions of initialized + - SHOULD set `ignored` to zeros, + - but MUST NOT set `ignored` to sensitive data such as secrets or portions of initialized memory. - - if it doesn't receive a corresponding `pong`: - - MAY terminate the network connection, - - and MUST NOT fail the channels in this case. - - SHOULD NOT send `ping` messages more often than once every 30 seconds. + - if it doesn't receive a corresponding `pong`: + - MAY terminate the network connection, + - and MUST NOT fail the channels in this case. + - SHOULD NOT send `ping` messages more often than once every 30 seconds. A node sending a `pong` message: - SHOULD set `ignored` to zeros, @@ -221,15 +220,15 @@ A node sending a `pong` message: memory. 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: - - MUST respond by sending a `pong` message, with `byteslen` equal to `num_pong_bytes`. - - otherwise (`num_pong_bytes` is not less than 65532): - - it MUST ignore the `ping`. + - 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: + - MUST respond by sending a `pong` message, with `byteslen` equal to `num_pong_bytes`. + - otherwise (`num_pong_bytes` is not less than 65532): + - it MUST ignore the `ping`. A node receiving a `pong` message: - - if `byteslen` does not correspond to any `ping`'s `num_pong_bytes` value it has sent: - - MAY fail the channels. + - if `byteslen` does not correspond to any `ping`'s `num_pong_bytes` value it has sent: + - MAY fail the channels. ### Rationale From 20fca8b90cd2f489700f81b5acde706d7b785a8c Mon Sep 17 00:00:00 2001 From: Landon Mutch Date: Thu, 9 Nov 2017 19:03:08 -0800 Subject: [PATCH 10/23] fix 01-messaging missed unordered list spacing --- 01-messaging.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/01-messaging.md b/01-messaging.md index 72c033258..1f16c8a3b 100644 --- a/01-messaging.md +++ b/01-messaging.md @@ -57,7 +57,7 @@ The size of the message is required to fit into a 2 byte unsigned int by the tra A receiving node: - MUST ignore any additional data within a message, beyond the length it expects for that type. - upon receiving a known message with insufficient length for the contents: - - MUST fail the channels. + - MUST fail the channels. ### Rationale From e885a631e8433dfb518a5e7a3bfe3f3a641070ef Mon Sep 17 00:00:00 2001 From: Landon Mutch Date: Thu, 9 Nov 2017 23:23:53 -0800 Subject: [PATCH 11/23] BOLT 1: change HTML tags to markdown --- 01-messaging.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/01-messaging.md b/01-messaging.md index 1f16c8a3b..bd2024492 100644 --- a/01-messaging.md +++ b/01-messaging.md @@ -22,7 +22,7 @@ All data fields are big-endian unless otherwise specified. ## Connection Handling and Multiplexing -Implementations MUST use a single connection per peer — channel messages (which include a channel id) are multiplexed over this single connection. +Implementations MUST use a single connection per peer — channel messages (which include a channel ID) are multiplexed over this single connection. ## Lightning Message Format @@ -34,15 +34,15 @@ 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. +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 sending node: - MUST NOT send an evenly-typed message not listed here, without prior negotiation. A receiving node: - - upon receiving a message of odd, unknown type: + - upon receiving a message of _odd_, unknown type: - MUST ignore the received message. - - upon receiving a message of even, unknown type: + - upon receiving a message of _even_, unknown type: - MUST fail the channels. The messages are grouped logically into 4 groups, ordered by their most significant set bit: @@ -68,7 +68,7 @@ other fields. Length is limited to 65535 bytes by the cryptographic wrapping, and messages in the protocol are never more than that length anyway. -The "it's OK to be odd" rule allows for future optional extensions +The _it's ok to be odd_ rule allows for future optional extensions without negotiation or special coding in clients. The "ignore additional data" rule similarly allows for future expansion. @@ -83,7 +83,7 @@ a buffer with 6 bytes of pre-padding. ### The `init` Message Once authentication is complete, the first message reveals the features supported or required by this node, even if this is a reconnection. -[BOLT #9](09-features.md) specifies lists of global and local features. Each feature is generally represented in `globalfeatures` or `localfeatures` by 2 bits. The least-significant bit is numbered 0, which is even, and the next most significant bit is numbered 1, which is odd. +[BOLT #9](09-features.md) specifies lists of global and local features. Each feature is generally represented in `globalfeatures` or `localfeatures` by 2 bits. The least-significant bit is numbered 0, which is _even_, and the next most significant bit is numbered 1, which is _odd_. Both fields `globalfeatures` and `localfeatures` MUST be padded to bytes with zeros. @@ -107,9 +107,9 @@ The sending node: The receiving node: - MUST wait to receive `init` before sending any other messages. - MUST respond to known feature bits as specified in [BOLT #9](09-features.md). - - upon receiving odd feature bits which are non-zero: + - upon receiving _odd_ feature bits which are non-zero: - MUST ignore the bit. - - upon receiving even feature bits which are non-zero: + - upon receiving _even_ feature bits which are non-zero: - MUST fail the connection. #### Rationale @@ -223,7 +223,7 @@ 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: - MUST respond by sending a `pong` message, with `byteslen` equal to `num_pong_bytes`. - - otherwise (`num_pong_bytes` is not less than 65532): + - otherwise (`num_pong_bytes` is **not** less than 65532): - it MUST ignore the `ping`. A node receiving a `pong` message: @@ -258,7 +258,7 @@ privacy of participants within the network. Limited precautions are recommended against `ping` flooding, however some latitude is given because of network delays. Note that there are other methods -of incoming traffic flooding (e.g. sending odd unknown message types, or padding +of incoming traffic flooding (e.g. sending _odd_ unknown message types, or padding every message maximally). Finally, the usage of periodic `ping` messages serves to promote frequent key From b5d2d8b7a8be7cc1229ea8f9443c927334694d73 Mon Sep 17 00:00:00 2001 From: Landon Mutch Date: Thu, 9 Nov 2017 23:26:09 -0800 Subject: [PATCH 12/23] add copy editing stylesheet temporarily while drafting, for reference; --- .copy-edit-stylesheet-checklist.md | 44 ++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) create mode 100644 .copy-edit-stylesheet-checklist.md diff --git a/.copy-edit-stylesheet-checklist.md b/.copy-edit-stylesheet-checklist.md new file mode 100644 index 000000000..71cd38444 --- /dev/null +++ b/.copy-edit-stylesheet-checklist.md @@ -0,0 +1,44 @@ +Basic checklist/stylesheet used for copy editing BOLTs. +Temporarily included here for reference purposes. + + - spelling + - typos + - sentence structure + - sentence fragments + - run-on sentences + - dangling, misplaced modifiers + - capitalization + - table of contents + - headers + - commonly forgotten: 'Bitcoin', 'Lightning', 'ID' + - punctuation + - correct comma, colon, semi-colon, em-dash placement + - appropriate use of parenthesis + - formatting + - single spaces between sentences + - consistent use of _emphasis_, **strong**, `code`, CAPS, 'quotes' + - single line separators between paragraphs and page elements + - list structure + - 2 spaces before item + - indent 2 spaces + - Requirements sections + - colon after condition + - comma before 'and' item + - period at branch ends + - example: + >A sending node: + - MAY do this. + - if this: + - SHOULD do this. + - else: + - MUST do this, + - and MUST NOT do this. + + - links + - broken links + - link text + - correct anchors/urls + - references + - e.g. [1](#reference-1) + - tags + - consistent usage, e.g. [TODO:], [FIXME:] \ No newline at end of file From 93afa0db9a7782bd496e9d77d8e41d3791885068 Mon Sep 17 00:00:00 2001 From: Landon Mutch Date: Fri, 10 Nov 2017 00:56:38 -0800 Subject: [PATCH 13/23] BOLT 2: first pass copy edit; Done first pass copy edit, up to line 279 of BOLT 2, according to .copy-edit-stylesheet-checklist.md guidelines; --- 02-peer-protocol.md | 503 +++++++++++++++++++++----------------------- 1 file changed, 242 insertions(+), 261 deletions(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index c39796bd4..235300362 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -6,48 +6,45 @@ operation, and closing. # Table of Contents * [Channel](#channel) * [Channel Establishment](#channel-establishment) - * [The `open_channel` message](#the-open_channel-message) - * [The `accept_channel` message](#the-accept_channel-message) - * [The `funding_created` message](#the-funding_created-message) - * [The `funding_signed` message](#the-funding_signed-message) - * [The `funding_locked` message](#the-funding_locked-message) + * [The `open_channel` Message](#the-open_channel-message) + * [The `accept_channel` Message](#the-accept_channel-message) + * [The `funding_created` Message](#the-funding_created-message) + * [The `funding_signed` Message](#the-funding_signed-message) + * [The `funding_locked` Message](#the-funding_locked-message) * [Channel Close](#channel-close) - * [Closing initiation: `shutdown`](#closing-initiation-shutdown) - * [Closing negotiation: `closing_signed`](#closing-negotiation-closing_signed) + * [Closing Initiation: `shutdown`](#closing-initiation-shutdown) + * [Closing Negotiation: `closing_signed`](#closing-negotiation-closing_signed) * [Normal Operation](#normal-operation) * [Forwarding HTLCs](#forwarding-htlcs) * [`cltv_expiry_delta` Selection](#cltv_expiry_delta-selection) * [Adding an HTLC: `update_add_htlc`](#adding-an-htlc-update_add_htlc) - * [Removing an HTLC: `update_fulfill_htlc`, `update_fail_htlc` and `update_fail_malformed_htlc`](#removing-an-htlc-update_fulfill_htlc-update_fail_htlc-and-update_fail_malformed_htlc) + * [Removing an HTLC: `update_fulfill_htlc`, `update_fail_htlc`, and `update_fail_malformed_htlc`](#removing-an-htlc-update_fulfill_htlc-update_fail_htlc-and-update_fail_malformed_htlc) * [Committing Updates So Far: `commitment_signed`](#committing-updates-so-far-commitment_signed) - * [Completing the transition to the updated state: `revoke_and_ack`](#completing-the-transition-to-the-updated-state-revoke_and_ack) + * [Completing the Transition to the Updated State: `revoke_and_ack`](#completing-the-transition-to-the-updated-state-revoke_and_ack) * [Updating Fees: `update_fee`](#updating-fees-update_fee) * [Message Retransmission](#message-retransmission) * [Authors](#authors) - + # Channel ## Channel Establishment - -Channel establishment begins immediately after authentication, and -consists of the funding node sending an `open_channel` message, -followed by the responding node sending `accept_channel`. With the +Channel establishment begins immediately after authentication and +consists of the funding node (funder) sending an `open_channel` message, +followed by the responding node (fundee) sending `accept_channel`. With the channel parameters locked in, the funder is able to create the funding -transaction and both versions of the commitment transaction as described in -[BOLT -03](https://github.com/lightningnetwork/lightning-rfc/blob/master/03-transactions.md#bolt-3-bitcoin-transaction-and-script-formats). -The funder then sends the outpoint of the funding output along with a -signature for the responder's version of the commitment transaction -with the `funding_created` message. Once the responder learns the -funding outpoint, she is able to generate the initiator's commitment -for the commitment transaction, and send it over using the -`funding_signed` message. - -Once the channel funder receives the `funding_signed` message, they +transaction and both versions of the commitment transaction, as described in +[BOLT #3](https://github.com/lightningnetwork/lightning-rfc/blob/master/03-transactions.md#bolt-3-bitcoin-transaction-and-script-formats). +The funder then sends the outpoint of the funding output with the `funding_created` +message, along with the signature for the fundee's version of the commitment +transaction. Once the fundee learns the funding outpoint, it's able to +generate the funder's commitment for the commitment transaction and send it +over using the `funding_signed` message. + +Once the channel funder receives the `funding_signed` message, it must broadcast the funding transaction to the Bitcoin network. After the `funding_signed` message is sent/received, both sides should wait -for the funding transaction to enter the blockchain and reach their +for the funding transaction to enter the blockchain and reach the specified depth (number of confirmations). After both sides have sent the `funding_locked` message, the channel is established and can begin normal operation. The `funding_locked` message includes information @@ -65,20 +62,20 @@ which will be used to construct channel authentication proofs. | |<-(6)--- funding_locked -----| | +-------+ +-------+ + - where node A is 'funder' and node B is 'fundee' -If this fails at any stage, or a node decides that the channel terms +If this fails at any stage, or if one node decides the channel terms offered by the other node are not suitable, the channel establishment fails. Note that multiple channels can operate in parallel, as all channel messages are identified by either a `temporary_channel_id` (before the -funding transaction is created) or `channel_id` derived from the -funding transaction. +funding transaction is created) or `channel_id` (derived from the +funding transaction). -### The `open_channel` message +### The `open_channel` Message - -This message contains information about a node, and indicates its +This message contains information about a node and indicates its desire to set up a new channel. 1. type: 32 (`open_channel`) @@ -104,100 +101,87 @@ desire to set up a new channel. The `chain_hash` value denotes the exact blockchain the opened channel will reside within. This is usually the genesis hash of the respective blockchain. -The existence of the `chain_hash` allows nodes to open channel +The existence of the `chain_hash` allows nodes to open channels across many distinct blockchains as well as have channels within multiple -blockchains opened to the same peer (if they support the target chains). +blockchains opened to the same peer (if it supports the target chains). -The `temporary_channel_id` is used to identify this channel until the funding transaction is established. `funding_satoshis` is the amount the sender is putting into the channel. `dust_limit_satoshis` is the threshold below which outputs should not be generated for this node's commitment or HTLC transaction; ie. HTLCs below this amount plus HTLC transaction fees are not enforceable on-chain. This reflects the reality that tiny outputs are not considered standard transactions and will not propagate through the Bitcoin network. +The `temporary_channel_id` is used to identify this channel until the funding transaction is established. `funding_satoshis` is the amount the sender is putting into the channel. `dust_limit_satoshis` is the threshold below which outputs should not be generated for this node's commitment or HTLC transaction; i.e. HTLCs below this amount plus HTLC transaction fees are not enforceable on-chain. This reflects the reality that tiny outputs are not considered standard transactions and will not propagate through the Bitcoin network. -`max_htlc_value_in_flight_msat` is a cap on total value of outstanding HTLCs, which allows a node to limit its exposure to HTLCs; similarly `max_accepted_htlcs` limits the number of outstanding HTLCs the other node can offer. `channel_reserve_satoshis` is the minimum amount that the other node is to keep as a direct payment. `htlc_minimum_msat` indicates the smallest value HTLC this node will accept. +`max_htlc_value_in_flight_msat` is a cap on total value of outstanding HTLCs, which allows a node to limit its exposure to HTLCs; similarly, `max_accepted_htlcs` limits the number of outstanding HTLCs the other node can offer. `channel_reserve_satoshis` is the minimum amount that the other node is to keep as a direct payment. `htlc_minimum_msat` indicates the smallest value HTLC this node will accept. -`feerate_per_kw` indicates the initial fee rate by 1000-weight (ie. 1/4 the more normally-used 'feerate per kilobyte') which this side will pay for commitment and HTLC transactions as described in [BOLT #3](03-transactions.md#fee-calculation) (this can be adjusted later with an `update_fee` message). `to_self_delay` is the number of blocks that the other nodes to-self outputs must be delayed, using `OP_CHECKSEQUENCEVERIFY` delays; this is how long it will have to wait in case of breakdown before redeeming its own funds. +`feerate_per_kw` indicates the initial fee rate by 1000-weight (i.e. 1/4 the more normally-used 'feerate per kilobyte') which this side will pay for commitment and HTLC transactions, as described in [BOLT #3](03-transactions.md#fee-calculation) (this can be adjusted later with an `update_fee` message). `to_self_delay` is the number of blocks that the other nodes to-self outputs must be delayed, using `OP_CHECKSEQUENCEVERIFY` delays; this is how long it will have to wait in case of breakdown before redeeming its own funds. Only the least-significant bit of `channel_flags` is currently -defined: `announce_channel`. This indicates whether the initiator of the +defined: `announce_channel`. This indicates whether the initiator of the funding flow wishes to advertise this channel publicly to the network as detailed within [BOLT #7](https://github.com/lightningnetwork/lightning-rfc/blob/master/07-routing-gossip.md#bolt-7-p2p-node-and-channel-discovery). -The `funding_pubkey` is the public key in the 2-of-2 multisig script of the funding transaction output. The `revocation_basepoint` is combined with the revocation preimage for this commitment transaction to generate a unique revocation key for this commitment transaction. The `payment_basepoint` and `delayed_payment_basepoint` are similarly used to generate a series of keys for any payments to this node: `delayed_payment_basepoint` is used to for payments encumbered by a delay. Varying these keys ensures that the transaction ID of each commitment transaction is unpredictable by an external observer, even if one commitment transaction is seen: this property is very useful for preserving privacy when outsourcing penalty transactions to third parties. - -FIXME: Describe Dangerous feature bit for larger channel amounts. +The `funding_pubkey` is the public key in the 2-of-2 multisig script of the funding transaction output. The `revocation_basepoint` is combined with the revocation preimage for this commitment transaction to generate a unique revocation key for this commitment transaction. The `payment_basepoint` and `delayed_payment_basepoint` are similarly used to generate a series of keys for any payments to this node: `delayed_payment_basepoint` is used for payments encumbered by a delay. Varying these keys ensures that the transaction ID of each commitment transaction is unpredictable by an external observer, even if one commitment transaction is seen — this property is very useful for preserving privacy when outsourcing penalty transactions to third parties. +[ FIXME: Describe dangerous feature bit for larger channel amounts. ] #### Requirements -A sending node MUST ensure that the `chain_hash` value identifies the chain they -they wish to open the channel within. - -A sending node MUST ensure `temporary_channel_id` is unique from any other -channel id with the same peer. The sender MUST set `funding_satoshis` -to less than 2^24 satoshi. The sender MUST set `push_msat` to -equal or less than to 1000 * `funding_satoshis`. The sender SHOULD set `to_self_delay` sufficient to ensure the sender -can irreversibly spend a commitment transaction output in case of -misbehavior by the receiver. -`funding_pubkey`, `revocation_basepoint`, `payment_basepoint` and `delayed_payment_basepoint` MUST be valid DER-encoded -compressed secp256k1 pubkeys. The sender SHOULD set `feerate_per_kw` -to at least the rate it estimates would cause the transaction to be -immediately included in a block. - - -The sender SHOULD set `dust_limit_satoshis` to a sufficient value to -allow commitment transactions to propagate through the Bitcoin -network. It SHOULD set `htlc_minimum_msat` to the minimum -amount HTLC it is willing to accept from this peer. - -The receiving node MAY fail the channel if `announce_channel` is -`false` (`0`), yet they wish to publicly announce the channel. The -receiving node MUST ignore undefined bits in `channel_flags`. - -The receiving node MUST accept a new `open_channel` message if the -connection has been re-established after receiving a previous -`open_channel` and before receiving a `funding_created` message. In -this case, the receiving node MUST discard the previous `open_channel` -message. - -The receiving node MUST fail the channel if `to_self_delay` is -unreasonably large. The receiver MAY fail the channel if -`funding_satoshis` is too small, and MUST fail the channel if -`push_msat` is greater than `funding_satoshis` * 1000. -The receiving node MAY fail the channel if it considers -`htlc_minimum_msat` too large, `max_htlc_value_in_flight_msat` too small, `channel_reserve_satoshis` too large, or `max_accepted_htlcs` too small. It MUST fail the channel if `max_accepted_htlcs` is greater than 483. - -The receiver MUST fail the channel if it -considers `feerate_per_kw` too small for timely processing, or unreasonably large. The -receiver MUST fail the channel if `funding_pubkey`, `revocation_basepoint`, `payment_basepoint` or `delayed_payment_basepoint` +The sending node MUST: + - ensure that the `chain_hash` value identifies the chain it wishes to open the channel within. + - ensure `temporary_channel_id` is unique from any other. +channel ID with the same peer. + - set `funding_satoshis` to less than 2^24 satoshi. + - set `push_msat` to equal or less than 1000 * `funding_satoshis`. + - set `funding_pubkey`, `revocation_basepoint`, `payment_basepoint`, and `delayed_payment_basepoint` to valid DER-encoded, compressed, secp256k1 pubkeys. + +The sending node SHOULD: + - set `to_self_delay` sufficient to ensure the sender can irreversibly spend a commitment transaction output, in case of misbehavior by the receiver. + - set `feerate_per_kw` to at least the rate it estimates would cause the transaction to be immediately included in a block. + - set `dust_limit_satoshis` to a sufficient value to allow commitment transactions to propagate through the Bitcoin network. + - set `htlc_minimum_msat` to the minimum value HTLC it is willing to accept from this peer. + +The receiving node MUST: + - ignore undefined bits in `channel_flags`. + - if the connection has been re-established after receiving a previous + `open_channel` but before receiving a `funding_created` message: + - accept a new `open_channel` message, + - and MUST discard the previous `open_channel` message. + +The receiving node MAY fail the channel if: + - `announce_channel` is `false` (`0`), yet it wishes to publicly announce the channel. + - `funding_satoshis` is too small. + - it considers `htlc_minimum_msat` too large. + - it considers `max_htlc_value_in_flight_msat` too small. + - it considers `channel_reserve_satoshis` too large. + - it considers `max_accepted_htlcs` too small. + +The receiving node MUST fail the channel if: + - `push_msat` is greater than `funding_satoshis` * 1000. + - `to_self_delay` is unreasonably large. + - `max_accepted_htlcs` is greater than 483. + - it considers `feerate_per_kw` too small for timely processing, or unreasonably large. + - `funding_pubkey`, `revocation_basepoint`, `payment_basepoint`, or `delayed_payment_basepoint` are not valid DER-encoded compressed secp256k1 pubkeys. - -The receiver MUST NOT consider funds received using `push_msat` to be received until the funding transaction has reached sufficient depth. - +The receiving node MUST NOT: + - consider funds received using `push_msat` to be received until the funding transaction has reached sufficient depth. #### Rationale +The *channel reserve* is specified by the peer's `channel_reserve_satoshis`: 1% of the channel total is suggested. Each side of a channel maintains this reserve so it always has something to lose, if it were to try to broadcast an old, revoked commitment transaction. Initially, this reserve may not be met, as only one side has funds; but the protocol ensures that progress is always toward it being met, and once met, it is maintained. -The *channel reserve* is specified by the peer's `channel_reserve_satoshis`; 1% of the channel total is suggested. Each side of a channel maintains this reserve so it always has something to lose if it were to try to broadcast an old, revoked commitment transaction. Initially this reserve may not be met, as only one side has funds, but the protocol ensures that progress is always toward it being met, and once met it is maintained. - +The sender can unconditionally give initial funds to the receiver using a non-zero `push_msat` — this is one case where the normal reserve mechanism doesn't apply. However, like any other on-chain transaction, this payment is not certain until the funding transaction has been confirmed sufficiently (may be double-spent) and may require a separate method to prove payment via on-chain confirmation. -The sender can unconditionally give initial funds to the receiver using a non-zero `push_msat`, and this is one case where the normal reserve mechanism doesn't apply. However, like any other on-chain transaction, this payment is not certain until the funding transaction has been confirmed sufficiently (may be double-spent) and may require a separate method to prove payment via on-chain confirmation. - -The `feerate_per_kw` is generally only a concern to the sender (who pays the fees), but that is also the feerate paid by HTLC transactions; thus unreasonably large fee rates can also penalize the recipient. +The `feerate_per_kw` is generally only a concern to the sender (who pays the fees), but there is also the feerate paid by HTLC transactions; thus, unreasonably large fee rates can also penalize the recipient. #### Future - It would be easy to have a local feature bit which indicated that a receiving node was prepared to fund a channel, which would reverse this protocol. +### The `accept_channel` Message -### The `accept_channel` message - - -This message contains information about a node, and indicates its +This message contains information about a node and indicates its acceptance of the new channel. - 1. type: 33 (`accept_channel`) 2. data: * [`32`:`temporary_channel_id`] @@ -216,20 +200,25 @@ acceptance of the new channel. #### Requirements +The `temporary_channel_id` MUST be the same as the `temporary_channel_id` in +the `open_channel` message. -The receiving node MUST reject the channel if the `chain_hash` value within the -`open_channel` message is set to a hash of a chain unknown to the receiver. +The sender: + - SHOULD set `minimum_depth` to a number of blocks it considers reasonable to +avoid double-spending of the funding transaction. -The `temporary_channel_id` MUST be the same as the `temporary_channel_id` in the `open_channel` message. The sender SHOULD set `minimum_depth` to a number of blocks it considers reasonable to avoid double-spending of the funding transaction. +The receiver: + - if the `chain_hash` value within the `open_channel` message is set to a hash + of a chain unknown to the receiver: + - MUST reject the channel. + - MAY reject the `minimum_depth`, if it considers it unreasonably large. -The receiver MAY reject the `minimum_depth` if it considers it unreasonably large. Other fields have the same requirements as their counterparts in `open_channel`. - -### The `funding_created` message +### The `funding_created` Message This message describes the outpoint which the funder has created for -the initial commitment transactions. After receiving the peer's +the initial commitment transactions. After receiving the peer's signature, it will broadcast the funding transaction. 1. type: 34 (`funding_created`) @@ -241,23 +230,33 @@ signature, it will broadcast the funding transaction. #### Requirements -The sender MUST set `temporary_channel_id` the same as the `temporary_channel_id` in the `open_channel` message. The sender MUST set `funding_txid` to the transaction ID of a non-malleable transaction, which it MUST NOT broadcast, and MUST set `funding_output_index` to the output number of that transaction which corresponds the funding transaction output as defined in [BOLT #3](03-transactions.md#funding-transaction-output), and MUST set `signature` to the valid signature using its `funding_pubkey` for the initial commitment transaction as defined in [BOLT #3](03-transactions.md#commitment-transaction). The sender SHOULD use only BIP141 (Segregated Witness) inputs when creating the funding transaction. +The sender MUST set: + - `temporary_channel_id` the same as the `temporary_channel_id` in the `open_channel` message. + - `funding_txid` to the transaction ID of a non-malleable transaction, which it MUST NOT broadcast. + - `funding_output_index` to the output number of that transaction which corresponds the funding transaction output as defined in [BOLT #3](03-transactions.md#funding-transaction-output). + - `signature` to the valid signature using its `funding_pubkey` for the initial commitment transaction, as defined in [BOLT #3](03-transactions.md#commitment-transaction). + +The sender: + - when creating the funding transaction: + - SHOULD use only BIP141 (Segregated Witness) inputs. -The recipient MUST fail the channel if `signature` is incorrect. +The recipient: + - if `signature` is incorrect: + - MUST fail the channel. #### Rationale -The `funding_output_index` can only be 2 bytes, since that's how we'll pack it into the `channel_id` used throughout the gossip protocol. The limit of 65535 outputs should not be overly burdensome. +The `funding_output_index` can only be 2 bytes, since that's how it's packed into the `channel_id` and used throughout the gossip protocol. The limit of 65535 outputs should not be overly burdensome. -A transaction with all Segregated Witness inputs is not malleable, hence the recommendation for the funding transaction. +A transaction with all Segregated Witness inputs is not malleable, hence the funding transaction recommendation. -### The `funding_signed` message +### The `funding_signed` Message -This message gives the funder the signature they need for the first -commitment transaction, so they can broadcast it knowing they can -redeem their funds if they need to. +This message gives the funder the signature it needs for the first +commitment transaction, so it can broadcast signature knowing funds +can be redeemed, if need be. -This message introduces the `channel_id` to identify the channel, which is derived from the funding transaction by combining the `funding_txid` and the `funding_output_index` using big-endian exclusive-OR (ie. `funding_output_index` alters the last two bytes). +This message introduces the `channel_id` to identify the channel. It's derived from the funding transaction by combining the `funding_txid` and the `funding_output_index`, using big-endian exclusive-OR (i.e. `funding_output_index` alters the last two bytes). 1. type: 35 (`funding_signed`) 2. data: @@ -266,15 +265,20 @@ This message introduces the `channel_id` to identify the channel, which is deriv #### Requirements -The sender MUST set `channel_id` by exclusive-OR of the `funding_txid` and the `funding_output_index` from the `funding_created` message, and MUST set `signature` to the valid signature using its `funding_pubkey` for the initial commitment transaction as defined in [BOLT #3](03-transactions.md#commitment-transaction). +The sender MUST set: + - `channel_id` by exclusive-OR of the `funding_txid` and the `funding_output_index` from the `funding_created` message. + - `signature` to the valid signature, using its `funding_pubkey` for the initial commitment transaction, as defined in [BOLT #3](03-transactions.md#commitment-transaction). -The recipient MUST fail the channel if `signature` is incorrect. +The recipient: + - if `signature` is incorrect: + - MUST fail the channel. + - on receipt of a valid `funding_signed`: + - SHOULD broadcast the funding transaction, + - and MUST NOT broadcast the funding transaction earlier. -The recipient SHOULD broadcast the funding transaction on receipt of a valid `funding_signed` and MUST NOT broadcast the funding transaction earlier. +### The `funding_locked` Message -### The `funding_locked` message - -This message indicates that the funding transaction has reached the `minimum_depth` asked for in `accept_channel`. Once both nodes have sent this, the channel enters normal operating mode. +This message indicates that the funding transaction has reached the `minimum_depth` asked for in `accept_channel`. Once both nodes have sent this, the channel enters normal operating mode. 1. type: 36 (`funding_locked`) 2. data: @@ -283,15 +287,16 @@ This message indicates that the funding transaction has reached the `minimum_dep #### Requirements -The sender MUST wait until the funding transaction has reached +The sender MUST: + - wait until the funding transaction has reached `minimum_depth` before sending this message. - -The sender MUST set `next_per_commitment_point` to the + - set `next_per_commitment_point` to the per-commitment point to be used for the following commitment transaction, derived as specified in [BOLT #3](03-transactions.md#per-commitment-secret-requirements). -A non-funding node SHOULD forget the channel if it does not see the +A non-funding node SHOULD: + - forget the channel if it does not see the funding transaction after a reasonable timeout. From the point of waiting for `funding_locked` onward, a node MAY @@ -301,13 +306,13 @@ other node after a reasonable timeout. #### Rationale The non-funder can simply forget the channel ever existed, since no -funds are at risk; even if `push_msat` is significant, if it remembers -the channel forever on the promise of the funding transaction finally -appearing, there is a denial of service risk. +funds are at risk. There is a denial of service risk: if it remembers +the channel forever (on the promise of the funding transaction finally +appearing), even if `push_msat` is significant. #### Future -We could add an SPV proof, and route block hashes in separate +We could add an SPV proof and route block hashes in separate messages. ## Channel Close @@ -316,9 +321,8 @@ Nodes can negotiate a mutual close for the connection, which unlike a unilateral close, allows them to access their funds immediately and can be negotiated with lower fees. -Closing happens in two stages: the first is by one side indicating -that it wants to clear the channel (and thus will accept no new -HTLCs), and once all HTLCs are resolved, the final channel close +Closing happens in two stages: 1) one side indicates it wants to clear the channel +(and thus will accept no new HTLCs) 2) once all HTLCs are resolved, the final channel close negotiation begins. +-------+ +-------+ @@ -336,10 +340,10 @@ negotiation begins. +-------+ +-------+ -### Closing initiation: `shutdown` +### Closing Initiation: `shutdown` Either node (or both) can send a `shutdown` message to initiate closing, -and indicating the scriptpubkey it wants to be paid to. +along with the scriptpubkey it wants to be paid to. 1. type: 38 (`shutdown`) @@ -350,30 +354,31 @@ and indicating the scriptpubkey it wants to be paid to. #### Requirements -A node MUST NOT send a `shutdown` if there are updates pending -on the receiving node's commitment transaction. - -A node MUST NOT send an `update_add_htlc` after a `shutdown`. A sending node -SHOULD fail to route any HTLC added after it sent `shutdown`. +A node MUST NOT: + - send a `shutdown` if there are updates pending + on the receiving node's commitment transaction. + - send an `update_add_htlc` after a `shutdown`. -A sending node MUST set `scriptpubkey` to one of the following forms: +A sending node: + - SHOULD fail to route any HTLC added after it sent `shutdown`. + - MUST set `scriptpubkey` in one of the following forms: -1. `OP_DUP` `OP_HASH160` `20` 20-bytes `OP_EQUALVERIFY` `OP_CHECKSIG` + 1. `OP_DUP` `OP_HASH160` `20` 20-bytes `OP_EQUALVERIFY` `OP_CHECKSIG` (pay to pubkey hash), OR -2. `OP_HASH160` `20` 20-bytes `OP_EQUAL` (pay to script hash), OR -3. `OP_0` `20` 20-bytes (version 0 pay to witness pubkey), OR -4. `OP_0` `32` 32-bytes (version 0 pay to witness script hash) + 2. `OP_HASH160` `20` 20-bytes `OP_EQUAL` (pay to script hash), OR + 3. `OP_0` `20` 20-bytes (version 0 pay to witness pubkey), OR + 4. `OP_0` `32` 32-bytes (version 0 pay to witness script hash) -A receiving node SHOULD fail the connection if the `scriptpubkey` is not one -of those forms. - -A receiving node MUST reply to a `shutdown` message with a `shutdown` once there are no outstanding updates on the peer, unless it has already sent a `shutdown`. +A receiving node: + - SHOULD fail the connection if the `scriptpubkey` is not one of those forms. + - MUST reply to a `shutdown` message with a `shutdown` once there are no + outstanding updates on the peer, unless it has already sent a `shutdown`. #### Rationale If channel state is always "clean" (no pending changes) when a shutdown starts, we avoid the question of how to behave if it wasn't; -the sender always send an `commitment_signed` first. +the sender always sends a `commitment_signed` first. As shutdown implies a desire to terminate, it implies that no new HTLCs will be added or accepted. @@ -382,15 +387,15 @@ The `scriptpubkey` forms include only standard forms accepted by the Bitcoin network, ensuring that the resulting transaction will propagate to miners. -The `shutdown` response requirement implies that the node sends `commitment_signed` to commit any outstanding changes before replying, but it could theoretically reconnect instead, which simply erases all outstanding uncommitted changes. +The `shutdown` response requirement implies that the node sends `commitment_signed` to commit any outstanding changes before replying; however, it could theoretically reconnect instead, which would simply erase all outstanding uncommitted changes. -### Closing negotiation: `closing_signed` +### Closing Negotiation: `closing_signed` Once shutdown is complete and the channel is empty of HTLCs, the final current commitment transactions will have no HTLCs, and closing fee -negotiation begins. Each node chooses a fee it thinks is fair, and +negotiation begins. Each node chooses a fee it thinks is fair, and signs the close transaction with the `scriptpubkey` fields from the -`shutdown` messages and that fee, and sends the signature. The +`shutdown` messages and that fee, and sends the signature. The process terminates when both agree on the same fee, or one side fails the channel. @@ -402,43 +407,44 @@ the channel. #### Requirements -Nodes SHOULD send a `closing_signed` message after `shutdown` has +Nodes SHOULD: + - send a `closing_signed` message after `shutdown` has been received and no HTLCs remain in either commitment transaction. -A sending node MUST set `fee_satoshis` lower than or equal to the -base fee of the final commitment transaction as calculated in [BOLT #3](03-transactions.md#fee-calculation). - -The sender SHOULD set the initial `fee_satoshis` according to its -estimate of cost of inclusion in a block. - -The sender MUST set `signature` to the Bitcoin signature of the close -transaction as specified in [BOLT #3](03-transactions.md#closing-transaction). +A sending node: + - MUST set `fee_satoshis` lower than or equal to the + base fee of the final commitment transaction as calculated in [BOLT #3](03-transactions.md#fee-calculation). + - SHOULD set the initial `fee_satoshis` according to its + estimate of cost of inclusion in a block. + - MUST set `signature` to the Bitcoin signature of the close + transaction, as specified in [BOLT #3](03-transactions.md#closing-transaction). -The receiver MUST check `signature` is valid for either variant of close +The receiver: + - MUST check `signature` is valid for either variant of close transaction specified in [BOLT #3](03-transactions.md#closing-transaction), -and MUST fail the connection if it is not. - -If `fee_satoshis` is equal to its previously sent `fee_satoshis`, the receiver -SHOULD sign and broadcast the final closing transaction and MAY close the connection. - -Otherwise, the -recipient MUST fail the connection if `fee_satoshis` is greater than + - and MUST fail the connection if it is not. + - if `fee_satoshis` is equal to its previously sent `fee_satoshis`: + - SHOULD sign and broadcast the final closing transaction + - MAY close the connection. + - otherwise: + - MUST fail the connection if `fee_satoshis` is greater than the base fee of the final commitment transaction as calculated in -[BOLT #3](03-transactions.md#fee-calculation), and the -recipient SHOULD fail the connection if `fee_satoshis` is not strictly +[BOLT #3](03-transactions.md#fee-calculation) + - SHOULD fail the connection if `fee_satoshis` is not strictly between its last-sent `fee_satoshis` and its previously-received `fee_satoshis`, unless it has reconnected since then. - -If the receiver agrees with the fee, it SHOULD reply with a -`closing_signed` with the same `fee_satoshis` value, otherwise it -MUST propose a value strictly between the received `fee_satoshis` -and its previously-sent `fee_satoshis`. + - if the receiver agrees with the fee + - it SHOULD reply with a . + 33`closing_signed` with the same `fee_satoshis` value + - otherwise: + - it MUST propose a value strictly between the received `fee_satoshis` + and its previously-sent `fee_satoshis`. #### Rationale The "strictly between" requirements ensure that we make forward -progress, even if only by a single satoshi at a time. To avoid -keeping state and handle the corner case where fees have shifted +progress, even if only by a single satoshi at a time. To avoid +keeping state and to handle the corner case, where fees have shifted between disconnection and reconnection, negotiation restarts on reconnection. Note that there is limited risk if the closing transaction is @@ -481,35 +487,35 @@ Thus each update traverses through the following states: 5. ... and the sender's previous commitment transaction has been revoked -As the two nodes updates are independent, the two commitment -transactions may be out of sync indefinitely. This is not concerning: +As the two node's updates are independent, the two commitment +transactions may be out of sync indefinitely. This is not concerning: what matters is whether both sides have irrevocably committed to a particular HTLC or not (the final state, above). ### Forwarding HTLCs -In general, a node offers HTLCs for two reasons: to initiate a payment of its own, -or to forward a payment coming from another node. In the forwarding case, care must -be taken to ensure that the *outgoing* HTLC cannot be redeemed unless the *incoming* +In general, a node offers HTLCs for two reasons: to initiate a payment of its own, +or to forward a payment coming from another node. In the forwarding case, care must +be taken to ensure that the *outgoing* HTLC cannot be redeemed unless the *incoming* HTLC can be redeemed; these requirements ensure that is always true. The addition/removal of an HTLC is considered *irrevocably committed* when: -1. the commitment transaction with/without it it is committed by both nodes, and any +1. the commitment transaction with/without it it is committed by both nodes, and any previous commitment transaction which without/with it has been revoked, OR -2. the commitment transaction with/without it has been irreversibly committed to +2. the commitment transaction with/without it has been irreversibly committed to the blockchain. #### Requirements -A node MUST NOT offer an HTLC (`update_add_htlc`) in response to an incoming HTLC until +A node MUST NOT offer an HTLC (`update_add_htlc`) in response to an incoming HTLC until the incoming HTLC has been irrevocably committed. -A node MUST NOT fail an incoming HTLC (`update_fail_htlc`) for which it has committed +A node MUST NOT fail an incoming HTLC (`update_fail_htlc`) for which it has committed to an outgoing HTLC, until the removal of the outgoing HTLC is irrevocably committed, or the outgoing on-chain HTLC output has been spent via the HTLC-timeout transaction with sufficient depth. A node MUST fail an incoming HTLC (`update_fail_htlc`) once its `cltv_expiry` has been reached, or if `cltv_expiry` - `current_height` < `cltv_expiry_delta` for the outgoing channel. - + A node SHOULD fail an incoming HTLC (`update_fail_htlc`) if its `cltv_expiry` is unreasonably far in the future. A node MUST fulfill an incoming HTLC for which it has committed to an outgoing HTLC, @@ -518,7 +524,7 @@ as soon as it receives `update_fulfill_htlc` for the outgoing HTLC, or has disco #### Rationale In general, we need to complete one side of the exchange before dealing with the other. -Fulfilling an HTLC is different: knowledge of the preimage is by definition irrevocable, +Fulfilling an HTLC is different: knowledge of the preimage is by definition irrevocable, so we should fulfill the incoming HTLC as soon as we can to reduce latency. An HTLC with an extremely long expiry is a denial-of-service vector, @@ -527,7 +533,6 @@ and may depend on network topology. ### `cltv_expiry_delta` Selection - Once an HTLC has timed out it could either be fulfilled or timed-out; care must be taken around this transition both for offered and received HTLCs. @@ -540,7 +545,7 @@ received. time it out on-chain. 2. B needs to be sure that if C fulfills the HTLC from B, it can fulfill the - incoming HTLC from A. i.e. B can get the preimage from C and fulfill incoming the + incoming HTLC from A. i.e. B can get the preimage from C and fulfill incoming the HTLC on-chain before A can time it out on-chain. The critical settings here are the `cltv_expiry_delta` in @@ -553,7 +558,7 @@ between HTLC CLTV timeout and the current block height for the terminal case (C). Note that if this value is too low for a channel, the risk is only to -the node *accepting* the HTLC, not the node offering it. For this +the node *accepting* the HTLC, not the node offering it. For this reason, the `cltv_expiry_delta` for the *outgoing* channel is used as the delta across a node. @@ -561,8 +566,8 @@ We can derive the worst-case number of blocks between outgoing and incoming HTLC resolution, given a few assumptions: * A worst-case reorganization depth `R` blocks -* A grace-period `G` blocks after HTLC timeout before we give up on - an unresponsive peer and drop to chain. +* A grace-period `G` blocks after HTLC timeout before giving up on + an unresponsive peer and dropping to chain. * A number of blocks `S` between transaction broadcast and the transaction being included in a block. @@ -571,14 +576,14 @@ possible time to spot the outgoing HTLC fulfillment, and then takes the longest possible time to redeem it on-chain: 1. The B->C HTLC times out at block `N`, and B waits `G` blocks until - it gives up waiting for C. B or C commits to the blockchain, + it gives up waiting for C. B or C commits to the blockchain, and B spends HTLC, which takes `S` blocks to be included. 2. Bad case: C wins the race (just) and fulfills the HTLC, B only sees that transaction when it sees block `N+G+S+1`. 3. Worst case: There's reorganization `R` deep in which C wins and fulfills. B only sees transaction at `N+G+S+R`. 4. B now needs to fulfill the incoming A->B HTLC, but A is unresponsive: B waits `G` more - blocks before giving up waiting for A. A or B commits to the blockchain. + blocks before giving up waiting for A. A or B commits to the blockchain. 5. Bad case: B sees A's commitment transaction in block `N+G+S+R+G+1`, and has to spend the HTLC output, which takes `S` blocks to be mined. 6. Worst case: There's another reorganization `R` deep which A uses to @@ -589,64 +594,59 @@ the longest possible time to redeem it on-chain: otherwise another reorganization could allow A to timeout the transaction. -Thus the worst case is `3R+2G+2S` assuming `R` is at least 1. Note that the +Thus the worst case is `3R+2G+2S` assuming `R` is at least 1. Note that the chances of three reorganizations in which the other node wins all of them is -low for `R` of 2 or more. Since we use high fees (and HTLC spends can use -almost arbitrary fees) `S` should be small, though given that block times are +low for `R` of 2 or more. Since high fees are used (and HTLC spends can use +almost arbitrary fees), `S` should be small, though given that block times are irregular and empty blocks still occur, `S = 2` should be considered a -minimum. Similarly, the grace period `G` can be low (1 or 2), as nodes are +minimum. Similarly, the grace period `G` can be low (1 or 2), as nodes are required to timeout or fulfill as soon as possible; but too low increases the risk of unnecessary channel closure due to networking delays. There are four values we need to derive: -1. The `cltv_expiry_delta` for channels. `3R+2G+2S`; if in doubt, a +1. The `cltv_expiry_delta` for channels. `3R+2G+2S`; if in doubt, a `cltv_expiry_delta` of 12 is reasonable (R=2, G=1, S=2). 2. For HTLCs we offer: the timeout deadline when we have to fail the channel - and time it out on-chain. This is `G` blocks after the HTLC + and time it out on-chain. This is `G` blocks after the HTLC `cltv_expiry`; 1 block is reasonable. 3. For HTLCs we accept and have a preimage: the fulfillment deadline when we have to fail the channel and fulfill the HTLC onchain before its - `cltv_expiry`. This is steps 4-7 above, which means a deadline of `2R+G+S` + `cltv_expiry`. This is steps 4-7 above, which means a deadline of `2R+G+S` blocks before `cltv_expiry`; 7 blocks is reasonable. 4. The minimum `cltv_expiry` we will accept for terminal payments: the worst case for the terminal node C lower at `2R+G+S` blocks (steps - 1-3 above don't apply). The default in - [BOLT 11](11-payment-encoding.md) is 9, which is slightly more + 1-3 above don't apply). The default in + [BOLT #11](11-payment-encoding.md) is 9, which is slightly more conservative than the 6 this calculation suggests. - #### Requirements -A node MUST estimate a timeout deadline for each HTLC it offers. A node MUST +A node MUST estimate a timeout deadline for each HTLC it offers. A node MUST NOT offer an HTLC with a timeout deadline before its `cltv_expiry`, and MUST fail the channel if an HTLC which it offered is in either node's current commitment transaction past this timeout deadline. A node MUST estimate a fulfillment deadline for each HTLC it is attempting to -fulfill. A node MUST fail (and not forward) an HTLC whose fulfillment +fulfill. A node MUST fail (and not forward) an HTLC whose fulfillment deadline is already past, and MUST fail the connection if a HTLC it has fulfilled is in either node's current commitment transaction past this fulfillment deadline. - ### Adding an HTLC: `update_add_htlc` - Either node can send `update_add_htlc` to offer a HTLC to the other, -which is redeemable in return for a payment preimage. Amounts are in +which is redeemable in return for a payment preimage. Amounts are in millisatoshi, though on-chain enforcement is only possible for whole satoshi amounts greater than the dust limit: in commitment transactions these are rounded down as specified in [BOLT #3](03-transactions.md). - The format of the `onion_routing_packet` portion, which indicates where the payment is destined, is described in [BOLT #4](04-onion-routing.md). - 1. type: 128 (`update_add_htlc`) 2. data: * [`32`:`channel_id`] @@ -656,7 +656,6 @@ is destined, is described in [BOLT #4](04-onion-routing.md). * [`4`:`cltv_expiry`] * [`1366`:`onion_routing_packet`] - #### Requirements A sending node MUST NOT offer `amount_msat` it cannot pay for in the @@ -672,7 +671,7 @@ zero. A sending node MUST NOT add an HTLC if it would result in it offering more than the remote's `max_accepted_htlcs` HTLCs in the remote commitment -transaction, or if the sum of total offered HTLCs would exceed the remote's +transaction, or if the sum of total offered HTLCs would exceed the remote's `max_htlc_value_in_flight_msat`. A sending node MUST set `id` to 0 for the first HTLC it offers, and @@ -681,7 +680,7 @@ increase the value by 1 for each successive offer. A receiving node SHOULD fail the channel if it receives an `amount_msat` equal to zero, below its own `htlc_minimum_msat`, or which the sending node cannot afford at the current `feerate_per_kw` while -maintaining its channel reserve. A receiving node SHOULD fail the +maintaining its channel reserve. A receiving node SHOULD fail the channel if a sending node adds more than its `max_accepted_htlcs` HTLCs to its local commitment transaction, or adds more than its `max_htlc_value_in_flight_msat` worth of offered HTLCs to its local commitment transaction, or sets `cltv_expiry` to greater or equal to 500000000. @@ -694,7 +693,7 @@ A receiving node MUST allow multiple HTLCs with the same payment hash. A receiving node MUST ignore a repeated `id` value after a reconnection if the sender did not previously acknowledge the -commitment of that HTLC. A receiving node MAY fail the channel if +commitment of that HTLC. A receiving node MAY fail the channel if other `id` violations occur. The `onion_routing_packet` contains an obfuscated list of hops and instructions for each hop along the path. @@ -703,24 +702,21 @@ This prevents replay attacks that'd reuse a previous `onion_routing_packet` with #### Rationale - Invalid amounts are a clear protocol violation and indicate a breakdown. - If a node did not accept multiple HTLCs with the same payment hash, an -attacker could probe to see if a node had an existing HTLC. This +attacker could probe to see if a node had an existing HTLC. This requirement to deal with duplicates leads us to use a separate identifier; we assume a 64 bit counter never wraps. - Retransmissions of unacknowledged updates are explicitly allowed for reconnection purposes; allowing them at other times simplifies the recipient code, though strict checking may help debugging. `max_accepted_htlcs` is limited to 483, to ensure that even if both sides send the maximum number of HTLCs, the `commitment_signed` message will -still be under the maximum message size. It also ensures that +still be under the maximum message size. It also ensures that a single penalty transaction can spend the entire commitment transaction, as calculated in [BOLT #5](05-onchain.md#penalty-transaction-weight-calculation). @@ -731,7 +727,7 @@ seconds, and the protocol only supports an expiry in blocks. specification; larger amounts are not necessary nor wise during the bootstrap phase of the network. -### Removing an HTLC: `update_fulfill_htlc`, `update_fail_htlc` and `update_fail_malformed_htlc` +### Removing an HTLC: `update_fulfill_htlc`, `update_fail_htlc`, and `update_fail_malformed_htlc` For simplicity, a node can only remove HTLCs added by the other node. There are three reasons for removing an HTLC: it has timed out, it has @@ -772,8 +768,8 @@ For a unparsable HTLC: A node SHOULD remove an HTLC as soon as it can; in particular, a node SHOULD fail an HTLC which has timed out. -A node MUST NOT send an `update_fulfill_htlc`, `update_fail_htlc` or -`update_fail_malformed_htlc` until the corresponding HTLC is irrevocably +A node MUST NOT send an `update_fulfill_htlc`, `update_fail_htlc` or +`update_fail_malformed_htlc` until the corresponding HTLC is irrevocably committed in both sides' commitment transactions. A receiving node MUST check that `id` corresponds to an HTLC in its @@ -811,18 +807,16 @@ makes this node do it. The node can check that the SHA256 the upstream is complaining about does match the onion it sent, which may allow it to detect random bit -errors. Without re-checking the actual encrypted packet sent, however, +errors. Without re-checking the actual encrypted packet sent, however, it won't know whether the error was its own or on the remote side, so such detection is left as an option. ### Committing Updates So Far: `commitment_signed` - When a node has changes for the remote commitment, it can apply them, sign the resulting transaction as defined in [BOLT #3](03-transactions.md) and send a `commitment_signed` message. - 1. type: 132 (`commitment_signed`) 2. data: * [`32`:`channel_id`] @@ -832,55 +826,44 @@ sign the resulting transaction as defined in [BOLT #3](03-transactions.md) and s #### Requirements - A node MUST NOT send a `commitment_signed` message which does not include any -updates. Note that a node MAY send a `commitment_signed` message which only +updates. Note that a node MAY send a `commitment_signed` message which only alters the fee, and MAY send a `commitment_signed` message which doesn't change the commitment transaction other than the new revocation hash (due to dust, identical HTLC replacement, or insignificant or multiple -fee changes). A node MUST include one `htlc_signature` for every HTLC +fee changes). A node MUST include one `htlc_signature` for every HTLC transaction corresponding to BIP69 lexicographic ordering of the commitment transaction. - A receiving node MUST fail the channel if `signature` is not valid for its local commitment transaction once all pending updates are applied. A receiving node MUST fail the channel if `num_htlcs` is not equal to the number of HTLC outputs in the local commitment transaction once all -pending updates are applied. A receiving node MUST fail the channel if +pending updates are applied. A receiving node MUST fail the channel if any `htlc_signature` is not valid for the corresponding HTLC transaction. - A receiving node MUST respond with a `revoke_and_ack` message. - #### Rationale - There's little point offering spam updates; it implies a bug. - The `num_htlcs` field is redundant, but makes the packet length check fully self-contained. - -### Completing the transition to the updated state: `revoke_and_ack` - +### Completing the Transition to the Updated State: `revoke_and_ack` Once the recipient of `commitment_signed` checks the signature, it knows that it has a valid new commitment transaction, replies with the commitment preimage for the previous commitment transaction in a `revoke_and_ack` message. - This message also implicitly serves as an acknowledgment of receipt of the `commitment_signed`, so it's a logical time for the `commitment_signed` sender to apply to its own commitment, any pending updates it sent before that `commitment_signed`. - The description of key derivation is in [BOLT #3](03-transactions.md#key-derivation). - 1. type: 133 (`revoke_and_ack`) 2. data: * [`32`:`channel_id`] @@ -889,35 +872,33 @@ The description of key derivation is in [BOLT #3](03-transactions.md#key-derivat #### Requirements - A sending node MUST set `per_commitment_secret` to the secret used to generate keys for the previous commitment transaction, MUST set `next_per_commitment_point` to the values for its next commitment transaction. A receiving node MUST check that `per_commitment_secret` generates the previous `per_commitment_point`, and MUST fail if it does not. A receiving node MAY fail if the `per_commitment_secret` was not generated by the protocol in [BOLT #3](03-transactions.md#per-commitment-secret-requirements). Nodes MUST NOT broadcast old (revoked) commitment transactions; doing -so will allow the other node to seize all the funds. Nodes SHOULD NOT +so will allow the other node to seize all the funds. Nodes SHOULD NOT sign commitment transactions unless it is about to broadcast them (due to a failed connection), to reduce this risk. ### Updating Fees: `update_fee` An `update_fee` message is sent by the node which is paying the -bitcoin fee. Like any update, it is first committed to the receiver's +Bitcoin fee. Like any update, it is first committed to the receiver's commitment transaction, then (once acknowledged) committed to the -sender's. Unlike an HTLC, `update_fee` is never closed, simply +sender's. Unlike an HTLC, `update_fee` is never closed, simply replaced. There is a possibility of a race: the recipient can add new HTLCs before it receives the `update_fee`, and the sender may not be able to afford the fee on its own commitment transaction once the `update_fee` -is acknowledged by the recipient. In this case, the fee will be less +is acknowledged by the recipient. In this case, the fee will be less than the fee rate, as described in [BOLT #3](03-transactions.md#fee-payment). The exact calculation used for deriving the fee from the fee rate is given in [BOLT #3](03-transactions.md#fee-calculation). - 1. type: 134 (`update_fee`) 2. data: * [`32`:`channel_id`] @@ -925,19 +906,19 @@ given in [BOLT #3](03-transactions.md#fee-calculation). #### Requirements -The node which is responsible for paying the bitcoin fee SHOULD send +The node which is responsible for paying the Bitcoin fee SHOULD send `update_fee` to ensure the current fee rate is sufficient for timely processing of the commitment transaction by a significant margin. -The node which is not responsible for paying the bitcoin fee MUST NOT +The node which is not responsible for paying the Bitcoin fee MUST NOT send `update_fee`. A receiving node SHOULD fail the channel if the `update_fee` is too low for timely processing, or unreasonably large. A receiving node MUST fail the channel if the sender is not -responsible for paying the bitcoin fee. +responsible for paying the Bitcoin fee. A receiving node SHOULD fail the channel if the sender cannot afford the new fee rate on the receiving node's current commitment @@ -958,7 +939,7 @@ fee estimation mean we don't specify an exact value. Since the fees are currently one-sided (the party which requested the channel creation always pays the fees for the commitment transaction), -it is simplest to only allow them to set fee levels, but as the same +it is simplest to only allow it to set fee levels; however, as the same fee rate applies to HTLC transactions, the receiving node must also care about the reasonableness of the fee. @@ -976,7 +957,7 @@ This is fairly straightforward in the case of channel establishment and close where messages have an explicit order, but in normal operation acknowledgments of updates are delayed until the `commitment_signed` / `revoke_and_ack` exchange, so we cannot assume -the updates have been received. This also means that the receiving +the updates have been received. This also means that the receiving node only needs to store updates upon receipt of `commitment_signed`. Note that messages described in [BOLT #7](07-routing-gossip.md) are @@ -1004,8 +985,8 @@ reconnection if it has sent the `funding_signed` message, otherwise it SHOULD NOT. On disconnection, a node MUST reverse any uncommitted updates sent by -the other side (ie. all messages beginning with `update_` for which no -`commitment_signed` has been received). Note that a node MAY have +the other side (i.e. all messages beginning with `update_` for which no +`commitment_signed` has been received). Note that a node MAY have already use the `payment_preimage` value from the `update_fulfill_htlc`, so the effects of `update_fulfill_htlc` is not completely reversed. @@ -1016,7 +997,7 @@ channel, and the following requirements do not apply. On reconnection, a node MUST transmit `channel_reestablish` for each channel, and MUST wait for to receive the other node's `channel_reestablish` message before sending any other messages for -that channel. The sending node MUST set `next_local_commitment_number` to the +that channel. The sending node MUST set `next_local_commitment_number` to the commitment number of the next `commitment_signed` it expects to receive, and MUST set `next_remote_revocation_number` to the commitment number of the next `revoke_and_ack` message it expects to receive. @@ -1042,7 +1023,7 @@ receiving node has sent (or equal to zero if none have been sent), it SHOULD fai A node MUST not assume that previously-transmitted messages were lost: in particular, if it has sent a previous `commitment_signed` message, a node MUST handle the case where the corresponding commitment -transaction is broadcast by the other side at any time. This is +transaction is broadcast by the other side at any time. This is particularly important if a node does not simply retransmit the exact same `update_` messages as previously sent. @@ -1053,7 +1034,7 @@ has sent a previous `shutdown` it MUST retransmit it. ### Rationale The effect of requirements above are that the opening phase is almost -atomic: if it doesn't complete, it starts again. The only exception +atomic: if it doesn't complete, it starts again. The only exception is where the `funding_signed` message is sent and not received: in this case, the funder will forget the channel and presumably open a new one on reconnect; the other node will eventually forget the @@ -1067,15 +1048,15 @@ channel altogether. `closing_signed` has no acknowledgment, so must be transmitted again on reconnect (though negotiation restarts on reconnection, so it need -not be an exact retransmission). The only acknowledgment for +not be an exact retransmission). The only acknowledgment for `shutdown` is `closing_signed`, so that needs to always be retransmitted unless `closing_signed` is. The handling of updates is similarly atomic: if the commit is not -acknowledged (or wasn't sent) the updates are re-sent. However, we +acknowledged (or wasn't sent) the updates are re-sent. However, we don't insist they be identical: they could be in a different order, or involve different fees, or even be missing HTLCs which are now too old -to be added. Requiring they be identical would effectively mean a +to be added. Requiring they be identical would effectively mean a write to disk by the sender upon each transmission, whereas the scheme here encourages a single persistent write to disk for each `commitment_signed` sent or received. @@ -1099,7 +1080,7 @@ than 1. A previous draft insisted that the funder "MUST remember ...if it has broadcast the funding transaction, otherwise it MUST NOT": this was in fact an impossible requirement, as a node must either first commit to -disk then broadcast the transaction, or the other way around. The new +disk then broadcast the transaction, or the other way around. The new language reflects this reality: it's surely better to remember a channel which hasn't been broadcast than forget one which has! Similarly, for the fundee's `funding_signed` message; better to @@ -1108,7 +1089,7 @@ funder open it with the funder having forgotten it. # Authors -FIXME +[ FIXME: Insert Author List ] ![Creative Commons License](https://i.creativecommons.org/l/by/4.0/88x31.png "License CC-BY")
From 1afc143cd1f7edc07034243f675a55cfb82bc1d8 Mon Sep 17 00:00:00 2001 From: Landon Mutch Date: Fri, 10 Nov 2017 11:45:51 -0800 Subject: [PATCH 14/23] BOLT 2: first pass copy edit continued; Done first pass copy edit, up to line 576 of BOLT 2, according to .copy-edit-stylesheet-checklist.md guidelines; --- 02-peer-protocol.md | 187 ++++++++++++++++++++++---------------------- 1 file changed, 93 insertions(+), 94 deletions(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 235300362..04e3d198b 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -295,29 +295,29 @@ per-commitment point to be used for the following commitment transaction, derived as specified in [BOLT #3](03-transactions.md#per-commitment-secret-requirements). -A non-funding node SHOULD: +A non-funding node (fundee) SHOULD: - forget the channel if it does not see the funding transaction after a reasonable timeout. -From the point of waiting for `funding_locked` onward, a node MAY +From the point of waiting for `funding_locked` onward, either node MAY fail the channel if it does not receive a required response from the other node after a reasonable timeout. #### Rationale The non-funder can simply forget the channel ever existed, since no -funds are at risk. There is a denial of service risk: if it remembers +funds are at risk. There is a denial of service risk: if the fundee remembers the channel forever (on the promise of the funding transaction finally appearing), even if `push_msat` is significant. #### Future -We could add an SPV proof and route block hashes in separate +An SPV proof could be added and block hashes could be routed in separate messages. ## Channel Close -Nodes can negotiate a mutual close for the connection, which unlike a +Nodes can negotiate a mutual close of the connection, which unlike a unilateral close, allows them to access their funds immediately and can be negotiated with lower fees. @@ -354,37 +354,36 @@ along with the scriptpubkey it wants to be paid to. #### Requirements -A node MUST NOT: - - send a `shutdown` if there are updates pending - on the receiving node's commitment transaction. - - send an `update_add_htlc` after a `shutdown`. - A sending node: + - if there are updates pending on the receiving node's commitment transaction: + - MUST NOT send a `shutdown`. + - MUST NOT send an `update_add_htlc` after a `shutdown`. - SHOULD fail to route any HTLC added after it sent `shutdown`. - MUST set `scriptpubkey` in one of the following forms: - 1. `OP_DUP` `OP_HASH160` `20` 20-bytes `OP_EQUALVERIFY` `OP_CHECKSIG` + 1. `OP_DUP` `OP_HASH160` `20` 20-bytes `OP_EQUALVERIFY` `OP_CHECKSIG` (pay to pubkey hash), OR - 2. `OP_HASH160` `20` 20-bytes `OP_EQUAL` (pay to script hash), OR - 3. `OP_0` `20` 20-bytes (version 0 pay to witness pubkey), OR - 4. `OP_0` `32` 32-bytes (version 0 pay to witness script hash) + 2. `OP_HASH160` `20` 20-bytes `OP_EQUAL` (pay to script hash), OR + 3. `OP_0` `20` 20-bytes (version 0 pay to witness pubkey), OR + 4. `OP_0` `32` 32-bytes (version 0 pay to witness script hash) A receiving node: - - SHOULD fail the connection if the `scriptpubkey` is not one of those forms. - - MUST reply to a `shutdown` message with a `shutdown` once there are no - outstanding updates on the peer, unless it has already sent a `shutdown`. + - if the `scriptpubkey` is not in one of the above forms: + - SHOULD fail the connection. + - once there are no outstanding updates on the peer: + - MUST reply to a `shutdown` message with a `shutdown`, unless it has already sent a `shutdown`. #### Rationale If channel state is always "clean" (no pending changes) when a -shutdown starts, we avoid the question of how to behave if it wasn't; +shutdown starts, the question of how to behave if it wasn't is avoided: the sender always sends a `commitment_signed` first. As shutdown implies a desire to terminate, it implies that no new HTLCs will be added or accepted. The `scriptpubkey` forms include only standard forms accepted by the -Bitcoin network, ensuring that the resulting transaction will +Bitcoin network, which ensures the resulting transaction will propagate to miners. The `shutdown` response requirement implies that the node sends `commitment_signed` to commit any outstanding changes before replying; however, it could theoretically reconnect instead, which would simply erase all outstanding uncommitted changes. @@ -395,7 +394,7 @@ Once shutdown is complete and the channel is empty of HTLCs, the final current commitment transactions will have no HTLCs, and closing fee negotiation begins. Each node chooses a fee it thinks is fair, and signs the close transaction with the `scriptpubkey` fields from the -`shutdown` messages and that fee, and sends the signature. The +`shutdown` messages (along with its chosen fee) and sends the signature. The process terminates when both agree on the same fee, or one side fails the channel. @@ -407,22 +406,22 @@ the channel. #### Requirements -Nodes SHOULD: - - send a `closing_signed` message after `shutdown` has -been received and no HTLCs remain in either commitment transaction. - A sending node: + - after `shutdown` has been received and no HTLCs remain in either commitment transaction: + - SHOULD send a `closing_signed` message. - MUST set `fee_satoshis` lower than or equal to the - base fee of the final commitment transaction as calculated in [BOLT #3](03-transactions.md#fee-calculation). + base fee of the final commitment transaction, as calculated in [BOLT #3](03-transactions.md#fee-calculation). - SHOULD set the initial `fee_satoshis` according to its estimate of cost of inclusion in a block. - MUST set `signature` to the Bitcoin signature of the close transaction, as specified in [BOLT #3](03-transactions.md#closing-transaction). -The receiver: +The receiving node: + - after `shutdown` has been received and no HTLCs remain in either commitment transaction: + - SHOULD send a `closing_signed` message. - MUST check `signature` is valid for either variant of close transaction specified in [BOLT #3](03-transactions.md#closing-transaction), - - and MUST fail the connection if it is not. + - and MUST fail the connection if it is not. - if `fee_satoshis` is equal to its previously sent `fee_satoshis`: - SHOULD sign and broadcast the final closing transaction - MAY close the connection. @@ -433,22 +432,21 @@ the base fee of the final commitment transaction as calculated in - SHOULD fail the connection if `fee_satoshis` is not strictly between its last-sent `fee_satoshis` and its previously-received `fee_satoshis`, unless it has reconnected since then. - - if the receiver agrees with the fee - - it SHOULD reply with a . - 33`closing_signed` with the same `fee_satoshis` value + - if the receiver agrees with the fee: + - SHOULD reply with a `closing_signed` with the same `fee_satoshis` value. - otherwise: - - it MUST propose a value strictly between the received `fee_satoshis` + - MUST propose a value "strictly between" the received `fee_satoshis` and its previously-sent `fee_satoshis`. #### Rationale -The "strictly between" requirements ensure that we make forward -progress, even if only by a single satoshi at a time. To avoid +The "strictly between" requirement ensures that forward +progress is made, even if only by a single satoshi at a time. To avoid keeping state and to handle the corner case, where fees have shifted between disconnection and reconnection, negotiation restarts on reconnection. -Note that there is limited risk if the closing transaction is -delayed, and it will be broadcast very soon, so there is usually no +Note there is limited risk if the closing transaction is +delayed, but it will be broadcast very soon; so there is usually no reason to pay a premium for rapid processing. ## Normal Operation @@ -472,7 +470,7 @@ Changes are sent in batches: one or more `update_` messages are sent before a +-------+ +-------+ -Counterintuitively, these updates apply to the *other node's* +Counter-intuitively, these updates apply to the *other node's* commitment transaction; the node only adds those updates to its own commitment transaction when the remote node acknowledges it has applied them via `revoke_and_ack`. @@ -487,7 +485,7 @@ Thus each update traverses through the following states: 5. ... and the sender's previous commitment transaction has been revoked -As the two node's updates are independent, the two commitment +As the two nodes' updates are independent, the two commitment transactions may be out of sync indefinitely. This is not concerning: what matters is whether both sides have irrevocably committed to a particular HTLC or not (the final state, above). @@ -495,45 +493,46 @@ particular HTLC or not (the final state, above). ### Forwarding HTLCs In general, a node offers HTLCs for two reasons: to initiate a payment of its own, -or to forward a payment coming from another node. In the forwarding case, care must -be taken to ensure that the *outgoing* HTLC cannot be redeemed unless the *incoming* -HTLC can be redeemed; these requirements ensure that is always true. +or to forward another node's payment. In the forwarding case, care must +be taken to ensure the *outgoing* HTLC cannot be redeemed unless the *incoming* +HTLC can be redeemed. The following requirements ensure this is always true: -The addition/removal of an HTLC is considered *irrevocably committed* when: +The respective **addition/removal** of an HTLC is considered *irrevocably committed* when: -1. the commitment transaction with/without it it is committed by both nodes, and any -previous commitment transaction which without/with it has been revoked, OR -2. the commitment transaction with/without it has been irreversibly committed to +1. the commitment transaction **with/without** it is committed by both nodes, and any +previous commitment transaction which **without/with** it has been revoked, OR +2. the commitment transaction **with/without** it has been irreversibly committed to the blockchain. #### Requirements -A node MUST NOT offer an HTLC (`update_add_htlc`) in response to an incoming HTLC until -the incoming HTLC has been irrevocably committed. - -A node MUST NOT fail an incoming HTLC (`update_fail_htlc`) for which it has committed -to an outgoing HTLC, until the removal of the outgoing HTLC is irrevocably committed, or the outgoing on-chain HTLC output has been spent via the HTLC-timeout transaction with sufficient depth. - -A node MUST fail an incoming HTLC (`update_fail_htlc`) once its `cltv_expiry` has been reached, or if `cltv_expiry` - `current_height` < `cltv_expiry_delta` for the outgoing channel. - -A node SHOULD fail an incoming HTLC (`update_fail_htlc`) if its `cltv_expiry` is unreasonably far in the future. - -A node MUST fulfill an incoming HTLC for which it has committed to an outgoing HTLC, -as soon as it receives `update_fulfill_htlc` for the outgoing HTLC, or has discovered the `payment_preimage` from an on-chain HTLC spend. +A node: + - until the incoming HTLC has been irrevocably committed: + - MUST NOT offer an HTLC (`update_add_htlc`) in response to an incoming HTLC. + - until the removal of the outgoing HTLC is irrevocably committed, OR until the outgoing on-chain HTLC output has been spent via the HTLC-timeout transaction (with sufficient depth): + - MUST NOT fail an incoming HTLC (`update_fail_htlc`) for which it has committed +to an outgoing HTLC. + - once its `cltv_expiry` has been reached, OR if `cltv_expiry` - `current_height` < `cltv_expiry_delta` for the outgoing channel: + - MUST fail an incoming HTLC (`update_fail_htlc`). + - if an incoming HTLC's `cltv_expiry` is unreasonably far in the future: + - SHOULD fail that incoming HTLC (`update_fail_htlc`). + - upon receiving an `update_fulfill_htlc` for the outgoing HTLC, OR upon discovering the `payment_preimage` from an on-chain HTLC spend: + - MUST fulfill an incoming HTLC for which it has committed to an outgoing HTLC. #### Rationale -In general, we need to complete one side of the exchange before dealing with the other. -Fulfilling an HTLC is different: knowledge of the preimage is by definition irrevocable, -so we should fulfill the incoming HTLC as soon as we can to reduce latency. +In general, one side of the exchange needs to be dealt with before the other. +Fulfilling an HTLC is different: knowledge of the preimage is, by definition, +irrevocable and the incoming HTLC should be fulfilled as soon as possible to +reduce latency. -An HTLC with an extremely long expiry is a denial-of-service vector, -so it is not allowed: the exact value of "unreasonable" is currently unclear +An HTLC with an unreasonably long expiry is a denial-of-service vector and +therefor is not allowed. Note that the exact value of "unreasonable" is currently unclear and may depend on network topology. ### `cltv_expiry_delta` Selection -Once an HTLC has timed out it could either be fulfilled or timed-out; +Once an HTLC has timed out, it can either be fulfilled or timed-out; care must be taken around this transition both for offered and received HTLCs. Consider the following scenario, where A sends an HTLC to B, who @@ -545,16 +544,16 @@ received. time it out on-chain. 2. B needs to be sure that if C fulfills the HTLC from B, it can fulfill the - incoming HTLC from A. i.e. B can get the preimage from C and fulfill incoming the + incoming HTLC from A; i.e. B can get the preimage from C and fulfill the incoming HTLC on-chain before A can time it out on-chain. The critical settings here are the `cltv_expiry_delta` in -[BOLT #7](07-routing-gossip.md#the-channel_update-message), and the +[BOLT #7](07-routing-gossip.md#the-channel_update-message) and the related [`min_final_cltv_expiry` in BOLT #11](11-payment-encoding.md#tagged-fields). -`cltv_expiry_delta` is the minimum difference in HTLC CLTV timeouts in -the forwarding case (B) and `min_final_ctlv_expiry` is the minimum difference -between HTLC CLTV timeout and the current block height for the +`cltv_expiry_delta` is the minimum difference in HTLC CLTV timeouts, in +the forwarding case (B). `min_final_ctlv_expiry` is the minimum difference +between HTLC CLTV timeout and the current block height, for the terminal case (C). Note that if this value is too low for a channel, the risk is only to @@ -562,17 +561,17 @@ the node *accepting* the HTLC, not the node offering it. For this reason, the `cltv_expiry_delta` for the *outgoing* channel is used as the delta across a node. -We can derive the worst-case number of blocks between outgoing and -incoming HTLC resolution, given a few assumptions: +The worst-case number of blocks between outgoing and +incoming HTLC resolution can be derived, given a few assumptions: -* A worst-case reorganization depth `R` blocks +* A worst-case reorganization depth `R` blocks. * A grace-period `G` blocks after HTLC timeout before giving up on an unresponsive peer and dropping to chain. * A number of blocks `S` between transaction broadcast and the transaction being included in a block. -The worst case is for a forwarding node (B) which takes the longest -possible time to spot the outgoing HTLC fulfillment, and then takes +The worst case is for a forwarding node (B) that takes the longest +possible time to spot the outgoing HTLC fulfillment and also takes the longest possible time to redeem it on-chain: 1. The B->C HTLC times out at block `N`, and B waits `G` blocks until @@ -603,21 +602,21 @@ minimum. Similarly, the grace period `G` can be low (1 or 2), as nodes are required to timeout or fulfill as soon as possible; but too low increases the risk of unnecessary channel closure due to networking delays. -There are four values we need to derive: +There are four values that need be derived: 1. The `cltv_expiry_delta` for channels. `3R+2G+2S`; if in doubt, a `cltv_expiry_delta` of 12 is reasonable (R=2, G=1, S=2). -2. For HTLCs we offer: the timeout deadline when we have to fail the channel - and time it out on-chain. This is `G` blocks after the HTLC - `cltv_expiry`; 1 block is reasonable. +2. For sent HTLCs: the timeout deadline after which the channel has to be failed + and timed out on-chain. This is `G` blocks after the HTLC's + `cltv_expiry`: 1 block is reasonable. -3. For HTLCs we accept and have a preimage: the fulfillment deadline when we - have to fail the channel and fulfill the HTLC onchain before its - `cltv_expiry`. This is steps 4-7 above, which means a deadline of `2R+G+S` - blocks before `cltv_expiry`; 7 blocks is reasonable. +3. For received HTLCs (with a preimage): the fulfillment deadline after which +the channel has to be failed and the HTLC fulfilled on-chain before its + `cltv_expiry`. See steps 4-7 above, which imply a deadline of `2R+G+S` + blocks before `cltv_expiry`: 7 blocks is reasonable. -4. The minimum `cltv_expiry` we will accept for terminal payments: the +4. The minimum `cltv_expiry` accepted for terminal payments: the worst case for the terminal node C lower at `2R+G+S` blocks (steps 1-3 above don't apply). The default in [BOLT #11](11-payment-encoding.md) is 9, which is slightly more @@ -708,7 +707,7 @@ breakdown. If a node did not accept multiple HTLCs with the same payment hash, an attacker could probe to see if a node had an existing HTLC. This requirement to deal with duplicates leads us to use a separate -identifier; we assume a 64 bit counter never wraps. +identifier; its assumed a 64 bit counter never wraps. Retransmissions of unacknowledged updates are explicitly allowed for reconnection purposes; allowing them at other times simplifies the @@ -935,7 +934,7 @@ fee. Given the variance in fees, and the fact that the transaction may be spent in the future, it's a good idea for the fee payer to keep a good margin, say 5x the expected fee requirement, but differing methods of -fee estimation mean we don't specify an exact value. +fee estimation means an exact value is not specified. Since the fees are currently one-sided (the party which requested the channel creation always pays the fees for the commitment transaction), @@ -949,14 +948,14 @@ Because communication transports are unreliable and may need to be re-established from time to time, the design of the transport has been explicitly separated from the protocol. -Nonetheless, we assume that our transport is ordered and reliable; -reconnection introduces doubt as to what has been received, so we -have explicit acknowledgments at that point. +Nonetheless, its assumed our transport is ordered and reliable; +reconnection introduces doubt as to what has been received, so there are +explicit acknowledgments at that point. This is fairly straightforward in the case of channel establishment and close where messages have an explicit order, but in normal operation acknowledgments of updates are delayed until the -`commitment_signed` / `revoke_and_ack` exchange, so we cannot assume +`commitment_signed` / `revoke_and_ack` exchange, so it cannot be assumed the updates have been received. This also means that the receiving node only needs to store updates upon receipt of `commitment_signed`. @@ -1053,18 +1052,18 @@ not be an exact retransmission). The only acknowledgment for unless `closing_signed` is. The handling of updates is similarly atomic: if the commit is not -acknowledged (or wasn't sent) the updates are re-sent. However, we -don't insist they be identical: they could be in a different order, or +acknowledged (or wasn't sent) the updates are re-sent. However, its not +insisted they be identical: they could be in a different order, or involve different fees, or even be missing HTLCs which are now too old to be added. Requiring they be identical would effectively mean a write to disk by the sender upon each transmission, whereas the scheme here encourages a single persistent write to disk for each `commitment_signed` sent or received. -We should never be asked to retransmit `revoke_and_ack` if we've -received a `closing_signed`, since that implies we've completed -shutdown which can only happen once the `revoke_and_ack` was received -by the remote node. +A retransmital of `revoke_and_ack` should never be asked for once a +`closing_signed` has been received, since that implies a shutdown has been +completed — which can only happen once the `revoke_and_ack` was received by the +remote node. Note that the `next_local_commitment_number` starts at 1 since commitment number 0 is created during opening. @@ -1073,7 +1072,7 @@ commitment number 0 is created during opening. point the revocation for commitment number 0 is sent. `funding_locked` is implicitly acknowledged by the start of normal -operation, which we know has begun once a `commitment_signed` has been +operation, which its known has begun once a `commitment_signed` has been received, thus the test for a `next_local_commitment_number` greater than 1. From 4e70a8b607668219e201eae3e38608a87ebfb554 Mon Sep 17 00:00:00 2001 From: Landon Mutch Date: Fri, 10 Nov 2017 11:49:19 -0800 Subject: [PATCH 15/23] update stylesheet checklist fix stylesheet formatting; add passive voice item to stylesheet checklist; apply passive voice change to BOLT 1; --- .copy-edit-stylesheet-checklist.md | 25 ++++++++++++++----------- 01-messaging.md | 4 ++-- 2 files changed, 16 insertions(+), 13 deletions(-) diff --git a/.copy-edit-stylesheet-checklist.md b/.copy-edit-stylesheet-checklist.md index 71cd38444..101affa7c 100644 --- a/.copy-edit-stylesheet-checklist.md +++ b/.copy-edit-stylesheet-checklist.md @@ -1,5 +1,5 @@ -Basic checklist/stylesheet used for copy editing BOLTs. -Temporarily included here for reference purposes. +Basic checklist/stylesheet used for copy editing BOLTs, +temporarily included here for reference purposes. - spelling - typos @@ -7,6 +7,8 @@ Temporarily included here for reference purposes. - sentence fragments - run-on sentences - dangling, misplaced modifiers + - consistent paragraph tense (e.g. past, present, future) + - passive voice (e.g. avoid 'we') - capitalization - table of contents - headers @@ -26,19 +28,20 @@ Temporarily included here for reference purposes. - comma before 'and' item - period at branch ends - example: - >A sending node: - - MAY do this. - - if this: - - SHOULD do this. - - else: - - MUST do this, - - and MUST NOT do this. - + ``` + A sending node: + - MAY do this. + - if this: + - SHOULD do this. + - else: + - MUST do this, + - and MUST NOT do this. + ``` - links - broken links - link text - correct anchors/urls - references - - e.g. [1](#reference-1) + - format e.g. [1](#reference-1) - tags - consistent usage, e.g. [TODO:], [FIXME:] \ No newline at end of file diff --git a/01-messaging.md b/01-messaging.md index bd2024492..16d311a10 100644 --- a/01-messaging.md +++ b/01-messaging.md @@ -240,8 +240,8 @@ Connections between nodes within the network may be very long lived, as payment channels have an indefinite lifetime. However, it's likely that for a significant portion of the lifetime of a connection, no new data will be exchanged. Also, on several platforms it's possible that Lightning -clients will be put to sleep without prior warning. Hence, we use a -distinct `ping` message, in order to probe for the liveness of the connection on +clients will be put to sleep without prior warning. Hence, a +distinct `ping` message is used, in order to probe for the liveness of the connection on the other side, as well as to keep the established connection active. Additionally, the ability for a sender to request that the receiver send a From b475639f48123acec1b212801d8b6c28f05ad6f2 Mon Sep 17 00:00:00 2001 From: Landon Mutch Date: Fri, 10 Nov 2017 14:05:21 -0800 Subject: [PATCH 16/23] BOLT 0, 1, 2: copy edit add stylesheet item: prefer typed, not written numbers; updated BOLT 0, 1 to reflect change; copy edit BOLT 2 up to line 674; --- .copy-edit-stylesheet-checklist.md | 1 + 00-introduction.md | 4 +- 01-messaging.md | 16 +++--- 02-peer-protocol.md | 90 ++++++++++++++++-------------- 4 files changed, 58 insertions(+), 53 deletions(-) diff --git a/.copy-edit-stylesheet-checklist.md b/.copy-edit-stylesheet-checklist.md index 71cd38444..62693775b 100644 --- a/.copy-edit-stylesheet-checklist.md +++ b/.copy-edit-stylesheet-checklist.md @@ -18,6 +18,7 @@ Temporarily included here for reference purposes. - single spaces between sentences - consistent use of _emphasis_, **strong**, `code`, CAPS, 'quotes' - single line separators between paragraphs and page elements + - type numbers (e.g. '1', '1s') rather than write numbers (e.g. 'one', 'ones') - list structure - 2 spaces before item - indent 2 spaces diff --git a/00-introduction.md b/00-introduction.md index e403ce81e..7879ad5cd 100644 --- a/00-introduction.md +++ b/00-introduction.md @@ -31,7 +31,7 @@ This is version 0. * *Channel*: - * A fast, off-chain method of mutual exchange between two *peers*. + * A fast, off-chain method of mutual exchange between 2 *peers*. To move funds, peers exchange signatures for an updated *commitment transaction*. @@ -43,7 +43,7 @@ This is version 0. * *HTLC*: Hashed Time Locked Contract. - * A conditional payment between two peers: the recipient can spend + * A conditional payment between 2 peers: the recipient can spend the payment by presenting its signature and a *payment preimage*, otherwise the payer can cancel the contract by spending it after a given time. These are implemented as outputs from the diff --git a/01-messaging.md b/01-messaging.md index bd2024492..179f7de1c 100644 --- a/01-messaging.md +++ b/01-messaging.md @@ -85,7 +85,7 @@ Once authentication is complete, the first message reveals the features supporte [BOLT #9](09-features.md) specifies lists of global and local features. Each feature is generally represented in `globalfeatures` or `localfeatures` by 2 bits. The least-significant bit is numbered 0, which is _even_, and the next most significant bit is numbered 1, which is _odd_. -Both fields `globalfeatures` and `localfeatures` MUST be padded to bytes with zeros. +Both fields `globalfeatures` and `localfeatures` MUST be padded to bytes with 0s. 1. type: 16 (`init`) 2. data: @@ -101,7 +101,7 @@ The 2 byte `gflen` and `lflen` fields indicate the number of bytes in the immedi The sending node: - MUST send `init` as the first Lightning message for any connection. - 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 any undefined feature bits to 0. - SHOULD use the minimum lengths required to represent the feature fields. The receiving node: @@ -120,7 +120,7 @@ Nodes wait for receipt of the other's features to simplify error diagnosis, where features are incompatible. The feature masks are split into local features (which only affect the -protocol between these two nodes) and global features (which can affect +protocol between these 2 nodes) and global features (which can affect HTLCs) and are thus also advertised to other nodes. ### The `error` Message @@ -137,7 +137,7 @@ The 2-byte `len` field indicates the number of bytes in the immediately followin #### Requirements -The channel is referred to by `channel_id`, unless `channel_id` is zero (i.e. all bytes are zero), in which case it refers to all channels. +The channel is referred to by `channel_id`, unless `channel_id` is 0 (i.e. all bytes are 0), in which case it refers to all channels. The funding node: - for all error messages sent before (and including) the `funding_created` message: @@ -154,7 +154,7 @@ A sending node: - MAY send an empty `data` field. - 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 `channel_id` is zero: + - when `channel_id` is 0: - MUST fail all channels, - and MUST close the connection. - MUST set `len` equal to the length of `data`. @@ -206,7 +206,7 @@ included within the data payload of the `pong` message. #### Requirements A node sending a `ping` message: - - SHOULD set `ignored` to zeros, + - SHOULD set `ignored` to 0s, - but MUST NOT set `ignored` to sensitive data such as secrets or portions of initialized memory. - if it doesn't receive a corresponding `pong`: @@ -215,12 +215,12 @@ memory. - SHOULD NOT send `ping` messages more often than once every 30 seconds. A node sending a `pong` message: - - SHOULD set `ignored` to zeros, + - SHOULD set `ignored` to 0s, - but MUST NOT set `ignored` to sensitive data such as secrets or portions of initialized memory. 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 1 `ping` per 30 seconds. - if `num_pong_bytes` is less than 65532: - MUST respond by sending a `pong` message, with `byteslen` equal to `num_pong_bytes`. - otherwise (`num_pong_bytes` is **not** less than 65532): diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 04e3d198b..dce5eb388 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -1,6 +1,6 @@ # BOLT #2: Peer Protocol for Channel Management -The peer channel protocol has three phases: establishment, normal +The peer channel protocol has 3 phases: establishment, normal operation, and closing. # Table of Contents @@ -256,7 +256,7 @@ This message gives the funder the signature it needs for the first commitment transaction, so it can broadcast signature knowing funds can be redeemed, if need be. -This message introduces the `channel_id` to identify the channel. It's derived from the funding transaction by combining the `funding_txid` and the `funding_output_index`, using big-endian exclusive-OR (i.e. `funding_output_index` alters the last two bytes). +This message introduces the `channel_id` to identify the channel. It's derived from the funding transaction by combining the `funding_txid` and the `funding_output_index`, using big-endian exclusive-OR (i.e. `funding_output_index` alters the last 2 bytes). 1. type: 35 (`funding_signed`) 2. data: @@ -321,7 +321,7 @@ Nodes can negotiate a mutual close of the connection, which unlike a unilateral close, allows them to access their funds immediately and can be negotiated with lower fees. -Closing happens in two stages: 1) one side indicates it wants to clear the channel +Closing happens in 2 stages: 1) one side indicates it wants to clear the channel (and thus will accept no new HTLCs) 2) once all HTLCs are resolved, the final channel close negotiation begins. @@ -453,7 +453,7 @@ reason to pay a premium for rapid processing. Once both nodes have exchanged `funding_locked` (and optionally [`announcement_signatures`](https://github.com/lightningnetwork/lightning-rfc/blob/master/07-routing-gossip.md#the-announcement_signatures-message)), the channel can be used to make payments via Hash TimeLocked Contracts. -Changes are sent in batches: one or more `update_` messages are sent before a +Changes are sent in batches: 1 or more `update_` messages are sent before a `commitment_signed` message, as in the following diagram: +-------+ +-------+ @@ -485,14 +485,14 @@ Thus each update traverses through the following states: 5. ... and the sender's previous commitment transaction has been revoked -As the two nodes' updates are independent, the two commitment +As the 2 nodes' updates are independent, the 2 commitment transactions may be out of sync indefinitely. This is not concerning: what matters is whether both sides have irrevocably committed to a particular HTLC or not (the final state, above). ### Forwarding HTLCs -In general, a node offers HTLCs for two reasons: to initiate a payment of its own, +In general, a node offers HTLCs for 2 reasons: to initiate a payment of its own, or to forward another node's payment. In the forwarding case, care must be taken to ensure the *outgoing* HTLC cannot be redeemed unless the *incoming* HTLC can be redeemed. The following requirements ensure this is always true: @@ -583,28 +583,28 @@ the longest possible time to redeem it on-chain: fulfills. B only sees transaction at `N+G+S+R`. 4. B now needs to fulfill the incoming A->B HTLC, but A is unresponsive: B waits `G` more blocks before giving up waiting for A. A or B commits to the blockchain. -5. Bad case: B sees A's commitment transaction in block `N+G+S+R+G+1`, and has +5. Bad case: B sees A's commitment transaction in block `N+G+S+R+G+1` and has to spend the HTLC output, which takes `S` blocks to be mined. -6. Worst case: There's another reorganization `R` deep which A uses to +6. Worst case: there's another reorganization `R` deep which A uses to spend the commitment transaction, so B sees A's commitment - transaction in block `N+G+S+R+G+R`, and has to spend the HTLC output, which + transaction in block `N+G+S+R+G+R` and has to spend the HTLC output, which takes `S` blocks to be mined. 7. B's HTLC spend needs to be at least `R` deep before it times out, otherwise another reorganization could allow A to timeout the transaction. -Thus the worst case is `3R+2G+2S` assuming `R` is at least 1. Note that the -chances of three reorganizations in which the other node wins all of them is +Thus, the worst case is `3R+2G+2S` assuming `R` is at least 1. Note that the +chances of 3 reorganizations in which the other node wins all of them is low for `R` of 2 or more. Since high fees are used (and HTLC spends can use -almost arbitrary fees), `S` should be small, though given that block times are +almost arbitrary fees), `S` should be small; although, given that block times are irregular and empty blocks still occur, `S = 2` should be considered a minimum. Similarly, the grace period `G` can be low (1 or 2), as nodes are -required to timeout or fulfill as soon as possible; but too low increases the +required to timeout or fulfill as soon as possible; but if `G` is too low it increases the risk of unnecessary channel closure due to networking delays. -There are four values that need be derived: +There are 4 values that need be derived: -1. The `cltv_expiry_delta` for channels. `3R+2G+2S`; if in doubt, a +1. The `cltv_expiry_delta` for channels, `3R+2G+2S`: if in doubt, a `cltv_expiry_delta` of 12 is reasonable (R=2, G=1, S=2). 2. For sent HTLCs: the timeout deadline after which the channel has to be failed @@ -624,24 +624,29 @@ the channel has to be failed and the HTLC fulfilled on-chain before its #### Requirements -A node MUST estimate a timeout deadline for each HTLC it offers. A node MUST -NOT offer an HTLC with a timeout deadline before its `cltv_expiry`, and MUST -fail the channel if an HTLC which it offered is in either node's current -commitment transaction past this timeout deadline. +An offering node: + - MUST estimate a timeout deadline for each HTLC it offers. + - MUST NOT offer an HTLC with a timeout deadline before its `cltv_expiry`. + - if an HTLC which it offered is in either node's current + commitment transaction is past this timeout deadline: + - MUST fail the channel. -A node MUST estimate a fulfillment deadline for each HTLC it is attempting to -fulfill. A node MUST fail (and not forward) an HTLC whose fulfillment -deadline is already past, and MUST fail the connection if a HTLC it has -fulfilled is in either node's current commitment transaction past this -fulfillment deadline. +A fulfilling node: + - for each HTLC it is attempting to fulfill: + - MUST estimate a fulfillment deadline. + - MUST fail (and not forward) an HTLC whose fulfillment +deadline is already past. + - if a HTLC it has fulfilled is in either node's current commitment transaction and is past this +fulfillment deadline: + - MUST fail the connection. ### Adding an HTLC: `update_add_htlc` Either node can send `update_add_htlc` to offer a HTLC to the other, which is redeemable in return for a payment preimage. Amounts are in millisatoshi, though on-chain enforcement is only possible for whole -satoshi amounts greater than the dust limit: in commitment transactions these are rounded down as -specified in [BOLT #3](03-transactions.md). +satoshi amounts greater than the dust limit (in commitment transactions these are rounded down as +specified in [BOLT #3](03-transactions.md)). The format of the `onion_routing_packet` portion, which indicates where the payment is destined, is described in [BOLT #4](04-onion-routing.md). @@ -657,16 +662,15 @@ is destined, is described in [BOLT #4](04-onion-routing.md). #### Requirements -A sending node MUST NOT offer `amount_msat` it cannot pay for in the +A sending node: + - MUST NOT offer `amount_msat` it cannot pay for in the remote commitment transaction at the current `feerate_per_kw` (see "Updating -Fees") while maintaining its channel reserve, MUST offer -`amount_msat` greater than 0, MUST NOT offer `amount_msat` below -the receiving node's `htlc_minimum_msat`, and MUST set `cltv_expiry` less -than 500000000. - -For channels with `chain_hash` identifying the Bitcoin blockchain, the -sending node MUST set the 4 most significant bytes of `amount_msat` to -zero. +Fees") while maintaining its channel reserve. + - MUST offer `amount_msat` greater than 0. + - MUST NOT offer `amount_msat` below the receiving node's `htlc_minimum_msat` + - MUST set `cltv_expiry` less than 500000000. + - for channels with `chain_hash` identifying the Bitcoin blockchain: + - MUST set the 4 most significant bytes of `amount_msat` to 0. A sending node MUST NOT add an HTLC if it would result in it offering more than the remote's `max_accepted_htlcs` HTLCs in the remote commitment @@ -677,7 +681,7 @@ A sending node MUST set `id` to 0 for the first HTLC it offers, and increase the value by 1 for each successive offer. A receiving node SHOULD fail the channel if it receives an -`amount_msat` equal to zero, below its own `htlc_minimum_msat`, or +`amount_msat` equal to 0, below its own `htlc_minimum_msat`, or which the sending node cannot afford at the current `feerate_per_kw` while maintaining its channel reserve. A receiving node SHOULD fail the channel if a sending node adds more than its `max_accepted_htlcs` HTLCs to @@ -686,7 +690,7 @@ sets `cltv_expiry` to greater or equal to 500000000. For channels with `chain_hash` identifying the Bitcoin blockchain, the receiving node MUST fail the channel if the 4 most significant bytes -of `amount_msat` are not zero. +of `amount_msat` are not 0. A receiving node MUST allow multiple HTLCs with the same payment hash. @@ -729,7 +733,7 @@ bootstrap phase of the network. ### Removing an HTLC: `update_fulfill_htlc`, `update_fail_htlc`, and `update_fail_malformed_htlc` For simplicity, a node can only remove HTLCs added by the other node. -There are three reasons for removing an HTLC: it has timed out, it has +There are 3 reasons for removing an HTLC: it has timed out, it has failed to route, or the payment preimage is supplied. The `reason` field is an opaque encrypted blob for the benefit of the @@ -830,7 +834,7 @@ updates. Note that a node MAY send a `commitment_signed` message which only alters the fee, and MAY send a `commitment_signed` message which doesn't change the commitment transaction other than the new revocation hash (due to dust, identical HTLC replacement, or insignificant or multiple -fee changes). A node MUST include one `htlc_signature` for every HTLC +fee changes). A node MUST include 1 `htlc_signature` for every HTLC transaction corresponding to BIP69 lexicographic ordering of the commitment transaction. @@ -1004,20 +1008,20 @@ next `revoke_and_ack` message it expects to receive. If `next_local_commitment_number` is 1 in both the `channel_reestablish` it sent and received, then the node MUST retransmit `funding_locked`, otherwise it MUST NOT. On reconnection, a node MUST ignore a redundant `funding_locked` -if it receives one. +if it receives 1. If `next_local_commitment_number` is equal to the commitment number of the last `commitment_signed` message the receiving node has sent, it MUST reuse the same commitment number for its next `commitment_signed`, -otherwise if `next_local_commitment_number` is not one greater than the commitment number of the +otherwise if `next_local_commitment_number` is not 1 greater than the commitment number of the last `commitment_signed` message the receiving node has sent, it SHOULD fail the channel. If `next_remote_revocation_number` is equal to the commitment number of the last `revoke_and_ack` the receiving node has sent and the receiving node has not already received a `closing_signed`, it MUST re-send the `revoke_and_ack`, otherwise if `next_remote_revocation_number` is not -equal to one greater than the commitment number of the last `revoke_and_ack` the -receiving node has sent (or equal to zero if none have been sent), it SHOULD fail the channel. +equal to 1 greater than the commitment number of the last `revoke_and_ack` the +receiving node has sent (or equal to 0 if none have been sent), it SHOULD fail the channel. A node MUST not assume that previously-transmitted messages were lost: in particular, if it has sent a previous `commitment_signed` message, From 03197f29597f2d633d193847e6bd9a6a84db6ef9 Mon Sep 17 00:00:00 2001 From: Landon Mutch Date: Fri, 10 Nov 2017 18:14:27 -0800 Subject: [PATCH 17/23] BOLT 1, 2: copy edit BOLT 1: minor list formatting fix; BOLT 2: copy edit up to line 955; --- 01-messaging.md | 8 +- 02-peer-protocol.md | 283 ++++++++++++++++++++++---------------------- 2 files changed, 148 insertions(+), 143 deletions(-) diff --git a/01-messaging.md b/01-messaging.md index 74d0d5862..3bd51cf6c 100644 --- a/01-messaging.md +++ b/01-messaging.md @@ -156,7 +156,7 @@ A sending node: - SHOULD include the raw, hex-encoded transaction in reply to a `funding_created`, `funding_signed`, `closing_signed`, or `commitment_signed` message. - when `channel_id` is 0: - MUST fail all channels, - - and MUST close the connection. + - and MUST close the connection. - MUST set `len` equal to the length of `data`. The receiving node: @@ -207,16 +207,16 @@ included within the data payload of the `pong` message. A node sending a `ping` message: - SHOULD set `ignored` to 0s, - - but MUST NOT set `ignored` to sensitive data such as secrets or portions of initialized + - but MUST NOT set `ignored` to sensitive data such as secrets or portions of initialized memory. - if it doesn't receive a corresponding `pong`: - MAY terminate the network connection, - - and MUST NOT fail the channels in this case. + - and MUST NOT fail the channels in this case. - SHOULD NOT send `ping` messages more often than once every 30 seconds. A node sending a `pong` message: - SHOULD set `ignored` to 0s, - - but MUST NOT set `ignored` to sensitive data such as secrets or portions of initialized + - but MUST NOT set `ignored` to sensitive data such as secrets or portions of initialized memory. A node receiving a `ping` message: diff --git a/02-peer-protocol.md b/02-peer-protocol.md index dce5eb388..86037ced8 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -142,7 +142,7 @@ The receiving node MUST: - if the connection has been re-established after receiving a previous `open_channel` but before receiving a `funding_created` message: - accept a new `open_channel` message, - - and MUST discard the previous `open_channel` message. + - and MUST discard the previous `open_channel` message. The receiving node MAY fail the channel if: - `announce_channel` is `false` (`0`), yet it wishes to publicly announce the channel. @@ -210,8 +210,8 @@ avoid double-spending of the funding transaction. The receiver: - if the `chain_hash` value within the `open_channel` message is set to a hash of a chain unknown to the receiver: - - MUST reject the channel. - - MAY reject the `minimum_depth`, if it considers it unreasonably large. + - MUST reject the channel, + - and MAY reject the `minimum_depth`, if it considers it unreasonably large. Other fields have the same requirements as their counterparts in `open_channel`. @@ -274,7 +274,7 @@ The recipient: - MUST fail the channel. - on receipt of a valid `funding_signed`: - SHOULD broadcast the funding transaction, - - and MUST NOT broadcast the funding transaction earlier. + - and MUST NOT broadcast the funding transaction earlier. ### The `funding_locked` Message @@ -421,7 +421,7 @@ The receiving node: - SHOULD send a `closing_signed` message. - MUST check `signature` is valid for either variant of close transaction specified in [BOLT #3](03-transactions.md#closing-transaction), - - and MUST fail the connection if it is not. + - and MUST fail the connection if it is not. - if `fee_satoshis` is equal to its previously sent `fee_satoshis`: - SHOULD sign and broadcast the final closing transaction - MAY close the connection. @@ -634,10 +634,9 @@ An offering node: A fulfilling node: - for each HTLC it is attempting to fulfill: - MUST estimate a fulfillment deadline. - - MUST fail (and not forward) an HTLC whose fulfillment -deadline is already past. - - if a HTLC it has fulfilled is in either node's current commitment transaction and is past this -fulfillment deadline: + - MUST fail (and not forward) an HTLC whose fulfillment deadline is already past. + - if a HTLC it has fulfilled is in either node's current commitment + transaction and is past this fulfillment deadline: - MUST fail the connection. ### Adding an HTLC: `update_add_htlc` @@ -671,63 +670,62 @@ Fees") while maintaining its channel reserve. - MUST set `cltv_expiry` less than 500000000. - for channels with `chain_hash` identifying the Bitcoin blockchain: - MUST set the 4 most significant bytes of `amount_msat` to 0. + - if result would be offering more than the remote's + `max_accepted_htlcs` HTLCs, in the remote commitment transaction: + - MUST NOT add an HTLC. + - if the sum of total offered HTLCs would exceed the remote's +`max_htlc_value_in_flight_msat`: + - MUST NOT add an HTLC. + - for the first HTLC it offers: + - MUST set `id` to 0, + - and MUST increase the value by 1 for each successive offer. -A sending node MUST NOT add an HTLC if it would result in it offering -more than the remote's `max_accepted_htlcs` HTLCs in the remote commitment -transaction, or if the sum of total offered HTLCs would exceed the remote's -`max_htlc_value_in_flight_msat`. - -A sending node MUST set `id` to 0 for the first HTLC it offers, and -increase the value by 1 for each successive offer. - -A receiving node SHOULD fail the channel if it receives an -`amount_msat` equal to 0, below its own `htlc_minimum_msat`, or -which the sending node cannot afford at the current `feerate_per_kw` while -maintaining its channel reserve. A receiving node SHOULD fail the -channel if a sending node adds more than its `max_accepted_htlcs` HTLCs to -its local commitment transaction, or adds more than its `max_htlc_value_in_flight_msat` worth of offered HTLCs to its local commitment transaction, or -sets `cltv_expiry` to greater or equal to 500000000. - -For channels with `chain_hash` identifying the Bitcoin blockchain, the -receiving node MUST fail the channel if the 4 most significant bytes -of `amount_msat` are not 0. - -A receiving node MUST allow multiple HTLCs with the same payment hash. - -A receiving node MUST ignore a repeated `id` value after a -reconnection if the sender did not previously acknowledge the -commitment of that HTLC. A receiving node MAY fail the channel if -other `id` violations occur. +A receiving node: + - receiving an `amount_msat` equal to 0, OR less than its own `htlc_minimum_msat`: + - SHOULD fail the channel. + - receiving an `amount_msat` that the sending node cannot afford at the current `feerate_per_kw` (while maintaining its channel reserve): + - SHOULD fail the channel. + - if a sending node adds more than its `max_accepted_htlcs` HTLCs to + its local commitment transaction, OR adds more than its `max_htlc_value_in_flight_msat` worth of offered HTLCs to its local commitment transaction: + - SHOULD fail the channel. + - if sending node sets `cltv_expiry` to greater or equal to 500000000: + - SHOULD fail the channel. + - for channels with `chain_hash` identifying the Bitcoin blockchain, if the 4 most significant bytes of `amount_msat` are not 0: + - MUST fail the channel. + - MUST allow multiple HTLCs with the same `payment_hash`. + - if the sender did not previously acknowledge the commitment of that HTLC: + - MUST ignore a repeated `id` value after a reconnection. + - if other `id` violations occur: + - MAY fail the channel. The `onion_routing_packet` contains an obfuscated list of hops and instructions for each hop along the path. -It commits to the HTLC by setting the `payment_hash` as associated data, i.e., including the `payment_hash` in the computation of HMACs. -This prevents replay attacks that'd reuse a previous `onion_routing_packet` with a different `payment_hash`. +It commits to the HTLC by setting the `payment_hash` as associated data, i.e. includes the `payment_hash` in the computation of HMACs. +This prevents replay attacks that would reuse a previous `onion_routing_packet` with a different `payment_hash`. #### Rationale -Invalid amounts are a clear protocol violation and indicate a -breakdown. +Invalid amounts are a clear protocol violation and indicate a breakdown. If a node did not accept multiple HTLCs with the same payment hash, an attacker could probe to see if a node had an existing HTLC. This -requirement to deal with duplicates leads us to use a separate -identifier; its assumed a 64 bit counter never wraps. +requirement, to deal with duplicates, leads us to use a separate +identifier; its assumed a 64-bit counter never wraps. Retransmissions of unacknowledged updates are explicitly allowed for reconnection purposes; allowing them at other times simplifies the -recipient code, though strict checking may help debugging. +recipient code (though strict checking may help debugging). -`max_accepted_htlcs` is limited to 483, to ensure that even if both +`max_accepted_htlcs` is limited to 483 to ensure that, even if both sides send the maximum number of HTLCs, the `commitment_signed` message will still be under the maximum message size. It also ensures that a single penalty transaction can spend the entire commitment transaction, as calculated in [BOLT #5](05-onchain.md#penalty-transaction-weight-calculation). -`cltv_expiry` values equal or above 500000000 would indicate a time in +`cltv_expiry` values equal to or greater than 500000000 would indicate a time in seconds, and the protocol only supports an expiry in blocks. `amount_msat` is deliberately limited for this version of the -specification; larger amounts are not necessary nor wise during the +specification; larger amounts are not necessary, nor wise, during the bootstrap phase of the network. ### Removing an HTLC: `update_fulfill_htlc`, `update_fail_htlc`, and `update_fail_malformed_htlc` @@ -737,9 +735,9 @@ There are 3 reasons for removing an HTLC: it has timed out, it has failed to route, or the payment preimage is supplied. The `reason` field is an opaque encrypted blob for the benefit of the -original HTLC initiator as defined in [BOLT #4](04-onion-routing.md), -but there's a special malformed failure variant for the case where -our peer couldn't parse it; in this case the current node encrypts +original HTLC initiator as defined in [BOLT #4](04-onion-routing.md); +however, there's a special malformed failure variant for the case where +our peer couldn't parse it: in this case the current node encrypts it into a `update_fail_htlc` for relaying. 1. type: 130 (`update_fulfill_htlc`) @@ -757,7 +755,7 @@ For a timed out or route-failed HTLC: * [`2`:`len`] * [`len`:`reason`] -For a unparsable HTLC: +For an unparsable HTLC: 1. type: 135 (`update_fail_malformed_htlc`) 2. data: @@ -768,56 +766,53 @@ For a unparsable HTLC: #### Requirements -A node SHOULD remove an HTLC as soon as it can; in particular, a node -SHOULD fail an HTLC which has timed out. - -A node MUST NOT send an `update_fulfill_htlc`, `update_fail_htlc` or -`update_fail_malformed_htlc` until the corresponding HTLC is irrevocably -committed in both sides' commitment transactions. - -A receiving node MUST check that `id` corresponds to an HTLC in its -current commitment transaction, and MUST fail the channel if it does -not. - -A receiving node MUST check that the `payment_preimage` value in -`update_fulfill_htlc` SHA256 hashes to the corresponding HTLC -`payment_hash`, and MUST fail the channel if it does not. - -A receiving node MUST fail the channel if the `BADONION` bit in -`failure_code` is not set for `update_fail_malformed_htlc`. - -A receiving node MAY check the `sha256_of_onion` in -`update_fail_malformed_htlc` and MAY retry or choose an alternate -error response if it does not match the onion it sent. +A node: + - SHOULD remove an HTLC as soon as it can. + - SHOULD fail an HTLC which has timed out. + - until the corresponding HTLC is irrevocably + committed in both sides' commitment transactions: + - MUST NOT send an `update_fulfill_htlc`, `update_fail_htlc` or +`update_fail_malformed_htlc`. -Otherwise, a receiving node which has an outgoing HTLC canceled by -`update_fail_malformed_htlc` MUST return an error in the -`update_fail_htlc` sent to the link which originally sent the HTLC -using the `failure_code` given and setting the data to -`sha256_of_onion`. +A receiving node: + - MUST check that `id` corresponds to an HTLC in its current commitment transaction, + - and MUST fail the channel if it does not. + - MUST check that the `payment_preimage` value in `update_fulfill_htlc` + SHA256 hashes to the corresponding HTLC `payment_hash`, + - and MUST fail the channel if it does not. + - if the `BADONION` bit in `failure_code` is not set for + `update_fail_malformed_htlc`: + - MUST fail the channel. + - MAY check the `sha256_of_onion` in `update_fail_malformed_htlc`, + - and if it does not match the onion it sent: + - MAY retry or choose an alternate error response. + - otherwise, a receiving node which has an outgoing HTLC canceled by `update_fail_malformed_htlc`: + - MUST return an error in the `update_fail_htlc` sent to the link which + originally sent the HTLC, using the `failure_code` given and setting the + data to `sha256_of_onion`. #### Rationale -A node which doesn't time out HTLCs risks channel failure (see -[`cltv_expiry_delta` Selection](#cltv_expiry_delta-selection). +A node that doesn't time out HTLCs risks channel failure (see +[`cltv_expiry_delta` Selection](#cltv_expiry_delta-selection)). -A node which sends `update_fulfill_htlc` before the sender is also -committed to the HTLC risks losing funds. +A node which sends `update_fulfill_htlc`, before the sender, is also +committed to the HTLC and risks losing funds. If the onion is malformed, the upstream node won't be able to extract -a key to generate a response, hence the special failure message which +a key to generate a response — hence the special failure message which makes this node do it. The node can check that the SHA256 the upstream is complaining about does match the onion it sent, which may allow it to detect random bit -errors. Without re-checking the actual encrypted packet sent, however, -it won't know whether the error was its own or on the remote side, so +errors. However, without re-checking the actual encrypted packet sent, +it won't know whether the error was its own or the remote's; so such detection is left as an option. ### Committing Updates So Far: `commitment_signed` When a node has changes for the remote commitment, it can apply them, -sign the resulting transaction as defined in [BOLT #3](03-transactions.md) and send a +sign the resulting transaction (as defined in [BOLT #3](03-transactions.md)), and send a `commitment_signed` message. 1. type: 132 (`commitment_signed`) @@ -829,40 +824,45 @@ sign the resulting transaction as defined in [BOLT #3](03-transactions.md) and s #### Requirements -A node MUST NOT send a `commitment_signed` message which does not include any -updates. Note that a node MAY send a `commitment_signed` message which only -alters the fee, and MAY send a `commitment_signed` message which doesn't -change the commitment transaction other than the new revocation hash +A sending node: + - MUST NOT send a `commitment_signed` message which does not include any +updates. + - but MAY send a `commitment_signed` message which only +alters the fee, + - and MAY send a `commitment_signed` message which doesn't +change the commitment transaction aside from the new revocation hash (due to dust, identical HTLC replacement, or insignificant or multiple -fee changes). A node MUST include 1 `htlc_signature` for every HTLC -transaction corresponding to BIP69 lexicographic ordering of the commitment -transaction. +fee changes). + - MUST include 1 `htlc_signature` for every HTLC transaction corresponding + to BIP69 lexicographic ordering of the commitment transaction. -A receiving node MUST fail the channel if `signature` is not valid for -its local commitment transaction once all pending updates are applied. -A receiving node MUST fail the channel if `num_htlcs` is not equal to -the number of HTLC outputs in the local commitment transaction once all -pending updates are applied. A receiving node MUST fail the channel if -any `htlc_signature` is not valid for the corresponding HTLC transaction. - -A receiving node MUST respond with a `revoke_and_ack` message. +A receiving node: + - if `signature` is not valid for its local commitment transaction once all + pending updates are applied: + - MUST fail the channel. + - if `num_htlcs` is not equal to the number of HTLC outputs in the local + commitment transaction once all pending updates are applied: + - MUST fail the channel. + - if any `htlc_signature` is not valid for the corresponding HTLC transaction: + - MUST fail the channel. + - MUST respond with a `revoke_and_ack` message. #### Rationale -There's little point offering spam updates; it implies a bug. +There's little point offering spam updates: it implies a bug. The `num_htlcs` field is redundant, but makes the packet length check fully self-contained. ### Completing the Transition to the Updated State: `revoke_and_ack` -Once the recipient of `commitment_signed` checks the signature, it knows that -it has a valid new commitment transaction, replies with the commitment +Once the recipient of `commitment_signed` checks the signature and knows +it has a valid new commitment transaction, it replies with the commitment preimage for the previous commitment transaction in a `revoke_and_ack` message. This message also implicitly serves as an acknowledgment of receipt -of the `commitment_signed`, so it's a logical time for the `commitment_signed` sender -to apply to its own commitment, any pending updates it sent before +of the `commitment_signed`, so this is a logical time for the `commitment_signed` sender +to apply (to its own commitment) any pending updates it sent before that `commitment_signed`. The description of key derivation is in [BOLT #3](03-transactions.md#key-derivation). @@ -875,28 +875,36 @@ The description of key derivation is in [BOLT #3](03-transactions.md#key-derivat #### Requirements -A sending node MUST set `per_commitment_secret` to the secret used to generate keys for the -previous commitment transaction, MUST set `next_per_commitment_point` to the values for its next commitment transaction. +A sending node: + - MUST set `per_commitment_secret` to the secret used to generate keys for + the previous commitment transaction. + - MUST set `next_per_commitment_point` to the values for its next commitment + transaction. -A receiving node MUST check that `per_commitment_secret` generates the previous `per_commitment_point`, and MUST fail if it does not. A receiving node MAY fail if the `per_commitment_secret` was not generated by the protocol in [BOLT #3](03-transactions.md#per-commitment-secret-requirements). +A receiving node: + - MUST check that `per_commitment_secret` generates the previous `per_commitment_point`, + - and MUST fail the channel if it does not. + - if the `per_commitment_secret` was not generated by the protocol in [BOLT #3](03-transactions.md#per-commitment-secret-requirements): + - MAY fail the channel. -Nodes MUST NOT broadcast old (revoked) commitment transactions; doing -so will allow the other node to seize all the funds. Nodes SHOULD NOT -sign commitment transactions unless it is about to broadcast them (due -to a failed connection), to reduce this risk. +A node: + - MUST NOT broadcast old (revoked) commitment transactions: doing +so will allow the other node to seize all channel funds. + - SHOULD NOT sign commitment transactions, unless it's about to broadcast + them (due to a failed connection), to reduce the above risk. ### Updating Fees: `update_fee` An `update_fee` message is sent by the node which is paying the Bitcoin fee. Like any update, it is first committed to the receiver's -commitment transaction, then (once acknowledged) committed to the -sender's. Unlike an HTLC, `update_fee` is never closed, simply +commitment transaction and then (once acknowledged) committed to the +sender's. Unlike an HTLC, `update_fee` is never closed but simply replaced. -There is a possibility of a race: the recipient can add new HTLCs -before it receives the `update_fee`, and the sender may not be able to -afford the fee on its own commitment transaction once the `update_fee` -is acknowledged by the recipient. In this case, the fee will be less +There is a possibility of a race, as the recipient can add new HTLCs +before it receives the `update_fee`. Under this circumstance, the sender may +not be able to afford the fee on its own commitment transaction, once the `update_fee` +is finally acknowledged by the recipient. In this case, the fee will be less than the fee rate, as described in [BOLT #3](03-transactions.md#fee-payment). The exact calculation used for deriving the fee from the fee rate is @@ -909,40 +917,37 @@ given in [BOLT #3](03-transactions.md#fee-calculation). #### Requirements -The node which is responsible for paying the Bitcoin fee SHOULD send -`update_fee` to ensure the current fee rate is sufficient for -timely processing of the commitment transaction by a significant -margin. - -The node which is not responsible for paying the Bitcoin fee MUST NOT -send `update_fee`. +The node _responsible_ for paying the Bitcoin fee: + - SHOULD send `update_fee` to ensure the current fee rate is sufficient (by a + significant margin) for timely processing of the commitment transaction. -A receiving node SHOULD fail the channel if the `update_fee` is too -low for timely processing, or unreasonably large. +The node _not responsible_ for paying the Bitcoin fee: + - MUST NOT send `update_fee`. -A receiving node MUST fail the channel if the sender is not -responsible for paying the Bitcoin fee. - -A receiving node SHOULD fail the channel if the sender cannot afford -the new fee rate on the receiving node's current commitment -transaction, but it MAY delay this check until the `update_fee` is -committed. +A receiving node: + - if the `update_fee` is too low for timely processing, OR is unreasonably large: + - SHOULD fail the channel. + - if the sender is not responsible for paying the Bitcoin fee: + - MUST fail the channel. + - if the sender cannot afford the new fee rate on the receiving node's + current commitment transaction: + - SHOULD fail the channel, + - but MAY delay this check until the `update_fee` is committed. #### Rationale -Bitcoin fees are required for unilateral closes to be effective, -particularly since there is no general method for the node which -broadcasts it to use child-pays-for-parent to increase its effective -fee. +Bitcoin fees are required for unilateral closes to be effective — +particularly since there is no general method for the broadcasting node to use +child-pays-for-parent to increase its effective fee. Given the variance in fees, and the fact that the transaction may be spent in the future, it's a good idea for the fee payer to keep a good -margin, say 5x the expected fee requirement, but differing methods of -fee estimation means an exact value is not specified. +margin (say 5x the expected fee requirement); but, due to differing methods of +fee estimation, an exact value is not specified. Since the fees are currently one-sided (the party which requested the channel creation always pays the fees for the commitment transaction), -it is simplest to only allow it to set fee levels; however, as the same +it's simplest to only allow it to set fee levels; however, as the same fee rate applies to HTLC transactions, the receiving node must also care about the reasonableness of the fee. From adb13bf6895f390585ea8ada5562a71bd1ff72ea Mon Sep 17 00:00:00 2001 From: Landon Mutch Date: Fri, 10 Nov 2017 22:18:53 -0800 Subject: [PATCH 18/23] BOLT 2: first pass copy edit done; complete first pass copy edit, following .copy-edit-stylesheed-checklist guidelines; --- 02-peer-protocol.md | 198 ++++++++++++++++++++++++-------------------- 1 file changed, 108 insertions(+), 90 deletions(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 86037ced8..3522263ce 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -953,25 +953,25 @@ care about the reasonableness of the fee. ## Message Retransmission -Because communication transports are unreliable and may need to be +Because communication transports are unreliable, and may need to be re-established from time to time, the design of the transport has been explicitly separated from the protocol. -Nonetheless, its assumed our transport is ordered and reliable; -reconnection introduces doubt as to what has been received, so there are +Nonetheless, it's assumed our transport is ordered and reliable. +Reconnection introduces doubt as to what has been received, so there are explicit acknowledgments at that point. This is fairly straightforward in the case of channel establishment -and close where messages have an explicit order, but in normal +and close where messages have an explicit order, but during normal operation acknowledgments of updates are delayed until the -`commitment_signed` / `revoke_and_ack` exchange, so it cannot be assumed +`commitment_signed` / `revoke_and_ack` exchange; so it cannot be assumed the updates have been received. This also means that the receiving node only needs to store updates upon receipt of `commitment_signed`. Note that messages described in [BOLT #7](07-routing-gossip.md) are independent of particular channels; their transmission requirements -are covered there, and other than being transmitted after `init` (like -any message), they are independent of requirements here. +are covered there, and besides being transmitted after `init` (as all +messages are), they are independent of requirements here. 1. type: 136 (`channel_reestablish`) 2. data: @@ -981,119 +981,137 @@ any message), they are independent of requirements here. ### Requirements -A node MUST handle continuing a previous channel on a new encrypted -transport. - -On disconnection, the funder MUST remember the channel for -reconnection if it has broadcast the funding transaction, otherwise it -SHOULD NOT. - -On disconnection, the non-funding node MUST remember the channel for -reconnection if it has sent the `funding_signed` message, otherwise -it SHOULD NOT. - -On disconnection, a node MUST reverse any uncommitted updates sent by -the other side (i.e. all messages beginning with `update_` for which no -`commitment_signed` has been received). Note that a node MAY have -already use the `payment_preimage` value from the `update_fulfill_htlc`, -so the effects of `update_fulfill_htlc` is not completely reversed. - -On reconnection, if a channel is in an error state, the node SHOULD -retransmit the error packet and ignore any other packets for that -channel, and the following requirements do not apply. - -On reconnection, a node MUST transmit `channel_reestablish` -for each channel, and MUST wait for to receive the other node's -`channel_reestablish` message before sending any other messages for -that channel. The sending node MUST set `next_local_commitment_number` to the -commitment number of the next `commitment_signed` it expects to receive, and -MUST set `next_remote_revocation_number` to the commitment number of the -next `revoke_and_ack` message it expects to receive. - -If `next_local_commitment_number` is 1 in both the `channel_reestablish` it -sent and received, then the node MUST retransmit `funding_locked`, otherwise -it MUST NOT. On reconnection, a node MUST ignore a redundant `funding_locked` -if it receives 1. - -If `next_local_commitment_number` is equal to the commitment number of -the last `commitment_signed` message the receiving node has sent, it -MUST reuse the same commitment number for its next `commitment_signed`, -otherwise if `next_local_commitment_number` is not 1 greater than the commitment number of the -last `commitment_signed` message the receiving node has sent, it -SHOULD fail the channel. - -If `next_remote_revocation_number` is equal to the commitment number of -the last `revoke_and_ack` the receiving node has sent and the receiving node has not already received a `closing_signed`, it MUST re-send -the `revoke_and_ack`, otherwise if `next_remote_revocation_number` is not -equal to 1 greater than the commitment number of the last `revoke_and_ack` the -receiving node has sent (or equal to 0 if none have been sent), it SHOULD fail the channel. - -A node MUST not assume that previously-transmitted messages were lost: -in particular, if it has sent a previous `commitment_signed` message, -a node MUST handle the case where the corresponding commitment -transaction is broadcast by the other side at any time. This is -particularly important if a node does not simply retransmit the exact -same `update_` messages as previously sent. - -On reconnection if the node has sent a previous `closing_signed` it -MUST send another `closing_signed`, otherwise if the node -has sent a previous `shutdown` it MUST retransmit it. +A funding node: + - upon disconnection: + - if it has broadcast the funding transaction: + - MUST remember the channel for reconnection. + - otherwise: + - SHOULD NOT remember the channel for reconnection. + +A non-funding node: + - upon disconnection: + - if it has sent the `funding_signed` message: + - MUST remember the channel for reconnection. + - otherwise: + - SHOULD NOT remember the channel for reconnection. + +A node: + - MUST handle continuation of a previous channel on a new encrypted transport. + - upon disconnection: + - MUST reverse any uncommitted updates sent by the other side (i.e. all + messages beginning with `update_` for which no `commitment_signed` has + been received). + - Note: a node MAY have already use the `payment_preimage` value from + the `update_fulfill_htlc`, so the effects of `update_fulfill_htlc` are not + completely reversed. + - upon reconnection: + - if a channel is in an error state, + - SHOULD retransmit the error packet and ignore any other packets for + that channel. + - otherwise: + - MUST transmit `channel_reestablish` for each channel, + - and MUST wait for to receive the other node's `channel_reestablish` + message before sending any other messages for that channel. + +The sending node: + - MUST set `next_local_commitment_number` to the commitment number of the + next `commitment_signed` it expects to receive. + - MUST set `next_remote_revocation_number` to the commitment number of the + next `revoke_and_ack` message it expects to receive. + +A node: + - if `next_local_commitment_number` is 1 in both the `channel_reestablish` it + sent and received: + - MUST retransmit `funding_locked`. + - otherwise: + - MUST NOT retransmit `funding_locked`. + - upon reconnection: + - MUST ignore any redundant `funding_locked` it receives. + - if `next_local_commitment_number` is equal to the commitment number of + the last `commitment_signed` message the receiving node has sent: + - MUST reuse the same commitment number for its next `commitment_signed`. + - otherwise, if `next_local_commitment_number` is not 1 greater than the + commitment number of the last `commitment_signed` message the receiving + node has sent: + - SHOULD fail the channel. + - if `next_remote_revocation_number` is equal to the commitment number of + the last `revoke_and_ack` the receiving node sent, AND the receiving node + hasn't already received a `closing_signed`: + - MUST re-send the `revoke_and_ack`. + - otherwise: + - if `next_remote_revocation_number` is not equal to 1 greater than the + commitment number of the last `revoke_and_ack` the receiving node has sent: + - SHOULD fail the channel. + - if it has sent no `revoke_and_ack`, AND `next_remote_revocation_number` + is equal to 0: + - SHOULD fail the channel. + - MUST not assume that previously-transmitted messages were lost, + - if it has sent a previous `commitment_signed` message: + - MUST handle the case where the corresponding commitment transaction is + broadcast by the other side at any time. This is particularly important + if the node does not simply retransmit the exact `update_` messages + as previously sent. + - upon reconnection: + - if it has sent a previous `closing_signed`: + - MUST send another `closing_signed`. + - otherwise, if it has sent a previous `shutdown`: + - MUST retransmit `shutdown`. ### Rationale -The effect of requirements above are that the opening phase is almost +The requirements above ensure that the opening phase is nearly atomic: if it doesn't complete, it starts again. The only exception -is where the `funding_signed` message is sent and not received: in -this case, the funder will forget the channel and presumably open -a new one on reconnect; the other node will eventually forget the -original channel due to never receiving `funding_locked` or seeing +is if the `funding_signed` message is sent but not received. In +this case, the funder will forget the channel, and presumably open +a new one upon reconnection; meanwhile, the other node will eventually forget +the original channel, due to never receiving `funding_locked` or seeing the funding transaction on-chain. There's no acknowledgment for `error`, so if a reconnect occurs it's -polite to retransmit before disconnecting again, but it's not a MUST +polite to retransmit before disconnecting again; however, it's not a MUST, because there are also occasions where a node can simply forget the channel altogether. -`closing_signed` has no acknowledgment, so must be transmitted again -on reconnect (though negotiation restarts on reconnection, so it need -not be an exact retransmission). The only acknowledgment for -`shutdown` is `closing_signed`, so that needs to always be retransmitted -unless `closing_signed` is. +`closing_signed` also has no acknowledgment so must be retransmitted +upon reconnection (though negotiation restarts on reconnection, so it need +not be an exact retransmission). +The only acknowledgment for `shutdown` is `closing_signed`, so one or the other +needs to be retransmitted. The handling of updates is similarly atomic: if the commit is not -acknowledged (or wasn't sent) the updates are re-sent. However, its not -insisted they be identical: they could be in a different order, or +acknowledged (or wasn't sent) the updates are re-sent. However, it's not +insisted they be identical: they could be in a different order, involve different fees, or even be missing HTLCs which are now too old to be added. Requiring they be identical would effectively mean a write to disk by the sender upon each transmission, whereas the scheme here encourages a single persistent write to disk for each `commitment_signed` sent or received. -A retransmital of `revoke_and_ack` should never be asked for once a -`closing_signed` has been received, since that implies a shutdown has been -completed — which can only happen once the `revoke_and_ack` was received by the -remote node. +A retransmital of `revoke_and_ack` should never be asked for, after a +`closing_signed` has been received, since that would imply a shutdown has been +completed — which can only occur after the `revoke_and_ack` has been received +by the remote node. -Note that the `next_local_commitment_number` starts at 1 since +Note that the `next_local_commitment_number` starts at 1, since commitment number 0 is created during opening. `next_remote_revocation_number` will be 0 until the `commitment_signed` for commitment number 1 is received, at which point the revocation for commitment number 0 is sent. `funding_locked` is implicitly acknowledged by the start of normal -operation, which its known has begun once a `commitment_signed` has been -received, thus the test for a `next_local_commitment_number` greater +operation, which is known to have begun after a `commitment_signed` has been +received — hence, the test for a `next_local_commitment_number` greater than 1. A previous draft insisted that the funder "MUST remember ...if it has broadcast the funding transaction, otherwise it MUST NOT": this was in -fact an impossible requirement, as a node must either first commit to -disk then broadcast the transaction, or the other way around. The new +fact an impossible requirement; because, a node must either firstly commit to +disk and secondly broadcast the transaction or vice versa. The new language reflects this reality: it's surely better to remember a -channel which hasn't been broadcast than forget one which has! -Similarly, for the fundee's `funding_signed` message; better to -remember a channel which never opens (and time out) than let the -funder open it with the funder having forgotten it. +channel which hasn't been broadcast than to forget one which has! +Similarly, for the fundee's `funding_signed` message: it's better to +remember a channel that never opens (and times out) than to let the +funder open it while the fundee has forgotten it. # Authors From 074b62b6667e8bce882e0bf1f2bc82277bacc588 Mon Sep 17 00:00:00 2001 From: Landon Mutch Date: Fri, 10 Nov 2017 22:35:33 -0800 Subject: [PATCH 19/23] update stylesheet checklist --- .copy-edit-stylesheet-checklist.md | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/.copy-edit-stylesheet-checklist.md b/.copy-edit-stylesheet-checklist.md index 541a20751..44421c46d 100644 --- a/.copy-edit-stylesheet-checklist.md +++ b/.copy-edit-stylesheet-checklist.md @@ -1,4 +1,4 @@ -Basic checklist/stylesheet used for copy editing BOLTs, +Basic checklist/stylesheet used for copy editing BOLTs — temporarily included here for reference purposes. - spelling @@ -20,22 +20,23 @@ temporarily included here for reference purposes. - single spaces between sentences - consistent use of _emphasis_, **strong**, `code`, CAPS, 'quotes' - single line separators between paragraphs and page elements - - type numbers (e.g. '1', '1s') rather than write numbers (e.g. 'one', 'ones') + - type numbers (e.g. '1', '1s') rather than write them (e.g. 'one', 'ones') + - exception: 'non-zero' - list structure - 2 spaces before item - indent 2 spaces - - Requirements sections - - colon after condition - - comma before 'and' item + - `Requirements` sections + - colon after conditions + - comma before 'and' sub-items - period at branch ends - example: ``` A sending node: - MAY do this. - - if this: - - SHOULD do this. - - else: - - MUST do this, + - if this, AND this: + - SHOULD do this. + - otherwise: + - MUST do this, - and MUST NOT do this. ``` - links From 43f4a7e406d67d95b7fe0a4f4f0535ebb01f71bb Mon Sep 17 00:00:00 2001 From: Landon Mutch Date: Fri, 10 Nov 2017 22:41:57 -0800 Subject: [PATCH 20/23] amend: update stylesheet checklist --- .copy-edit-stylesheet-checklist.md | 1 + 1 file changed, 1 insertion(+) diff --git a/.copy-edit-stylesheet-checklist.md b/.copy-edit-stylesheet-checklist.md index 44421c46d..2499f627b 100644 --- a/.copy-edit-stylesheet-checklist.md +++ b/.copy-edit-stylesheet-checklist.md @@ -9,6 +9,7 @@ temporarily included here for reference purposes. - dangling, misplaced modifiers - consistent paragraph tense (e.g. past, present, future) - passive voice (e.g. avoid 'we') + - exception: `Introduction` section - capitalization - table of contents - headers From d99a410d5c066725bbc9778826831baad3e4b002 Mon Sep 17 00:00:00 2001 From: Landon Mutch Date: Mon, 13 Nov 2017 18:32:13 -0800 Subject: [PATCH 21/23] BOLT 2: copy edit merged changes --- 02-peer-protocol.md | 31 +++++++++++++++---------------- 1 file changed, 15 insertions(+), 16 deletions(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index bd9891416..f44060e96 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -1047,15 +1047,15 @@ A node: - if it has sent no `revoke_and_ack`, AND `next_remote_revocation_number` is equal to 0: - SHOULD fail the channel. - + A receiving node: - if it supports `option-data-loss-protect`, AND the `option-data-loss-protect` - fields are present: - - if `next_remote_revocation_number` is greater than expected above, AND - `your_last_per_commitment_secret` is correct for that + fields are present: + - if `next_remote_revocation_number` is greater than expected above, AND + `your_last_per_commitment_secret` is correct for that `next_remote_revocation_number` minus one: - - MUST NOT broadcast its commitment transaction, - - and SHOULD fail the channel, + - MUST NOT broadcast its commitment transaction, + - and SHOULD fail the channel, - and SHOULD store `my_current_per_commitment_point` to retrieve funds should the sending node broadcast its commitment transaction onchain. - otherwise (`your_last_per_commitment_secret` or `my_current_per_commitment_point` @@ -1131,18 +1131,17 @@ Similarly, for the fundee's `funding_signed` message: it's better to remember a channel that never opens (and times out) than to let the funder open it while the fundee has forgotten it. -`option-data-loss-protect` was added to allow a node which has somehow fallen behind -(eg. restored from old backup) to detect it, and know that it cannot -broadcast its current commitment transaction (which would lead to -total loss of funds, as the remote node has proven it knows the -revocation preimage). The error returned by the fallen-behind node +`option-data-loss-protect` was added to allow a node, which has somehow fallen behind +(e.g. restored from old backup), to detect that it's fallen-behind. A fallen-behind +node must know it cannot broadcast its current commitment transaction — which would lead to +total loss of funds — as the remote node can prove it knows the +revocation preimage. The error returned by the fallen-behind node (or simply the invalid numbers in the `channel_reestablish` it has sent) should make the other node drop its current commitment -transaction to the chain, which will at least allow the recovery on -non-HTLC funds for the fallen-behind node if the `my_current_per_commitment_point` -is valid. On the other hand, it also -means the fallen-behind node has revealed this fact (though not -provably: it could be lying), and the other node could use this to +transaction to the chain. This will, at least, allow the fallen-behind node to recovery +non-HTLC funds, if the `my_current_per_commitment_point` +is valid. However, this also means the fallen-behind node has revealed this +fact (though not provably: it could be lying), and the other node could use this to broadcast a previous state. # Authors From 24896d847d622f9c85e3f921dc6d5933af6f546e Mon Sep 17 00:00:00 2001 From: Landon Mutch Date: Mon, 13 Nov 2017 19:18:09 -0800 Subject: [PATCH 22/23] make spellcheck.sh happy --- .aspell.en.pws | 3 ++- 02-peer-protocol.md | 2 +- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/.aspell.en.pws b/.aspell.en.pws index 337fb0f13..dd0ff924f 100644 --- a/.aspell.en.pws +++ b/.aspell.en.pws @@ -1,4 +1,4 @@ -personal_ws-1.1 en 264 +personal_ws-1.1 en 264 secp sig unguessable @@ -214,6 +214,7 @@ num numStreamBytes txout HTLCs +HTLC's retransmission decrypted sessionKey diff --git a/02-peer-protocol.md b/02-peer-protocol.md index f44060e96..3c0ad1448 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -1105,7 +1105,7 @@ write to disk by the sender upon each transmission, whereas the scheme here encourages a single persistent write to disk for each `commitment_signed` sent or received. -A retransmital of `revoke_and_ack` should never be asked for, after a +A re-transmittal of `revoke_and_ack` should never be asked for, after a `closing_signed` has been received, since that would imply a shutdown has been completed — which can only occur after the `revoke_and_ack` has been received by the remote node. From c89a54a7da25fba5ab7414871ad69032bbc4dfe8 Mon Sep 17 00:00:00 2001 From: Landon Mutch Date: Wed, 15 Nov 2017 02:55:16 -0800 Subject: [PATCH 23/23] BOLT 0,1,2: fix requested changes; update stylesheet to reflect appropriate structure of Requirement sub-items and format of digits, numerations, and quantities; copy edit BOLTs 0,1,2 to adhere to these changes; --- .copy-edit-stylesheet-checklist.md | 10 +-- 00-introduction.md | 4 +- 01-messaging.md | 38 +++++----- 02-peer-protocol.md | 110 ++++++++++++++--------------- 4 files changed, 81 insertions(+), 81 deletions(-) diff --git a/.copy-edit-stylesheet-checklist.md b/.copy-edit-stylesheet-checklist.md index 2499f627b..a7302ad2b 100644 --- a/.copy-edit-stylesheet-checklist.md +++ b/.copy-edit-stylesheet-checklist.md @@ -21,14 +21,16 @@ temporarily included here for reference purposes. - single spaces between sentences - consistent use of _emphasis_, **strong**, `code`, CAPS, 'quotes' - single line separators between paragraphs and page elements - - type numbers (e.g. '1', '1s') rather than write them (e.g. 'one', 'ones') - - exception: 'non-zero' + - number values and quantities + - type digits and enumerations, spell out small (<10) amounts + - e.g. 'two 2-byte instances set to 0s', 'one 4-byte instance set to 1s', 'the old one is equal to 1 greater than value' + - exceptions e.g. 'non-zero (digits)' - list structure - 2 spaces before item - indent 2 spaces - `Requirements` sections - colon after conditions - - comma before 'and' sub-items + - comma before sub-items - period at branch ends - example: ``` @@ -38,7 +40,7 @@ temporarily included here for reference purposes. - SHOULD do this. - otherwise: - MUST do this, - - and MUST NOT do this. + - but MUST NOT...in this case. ``` - links - broken links diff --git a/00-introduction.md b/00-introduction.md index 7879ad5cd..e403ce81e 100644 --- a/00-introduction.md +++ b/00-introduction.md @@ -31,7 +31,7 @@ This is version 0. * *Channel*: - * A fast, off-chain method of mutual exchange between 2 *peers*. + * A fast, off-chain method of mutual exchange between two *peers*. To move funds, peers exchange signatures for an updated *commitment transaction*. @@ -43,7 +43,7 @@ This is version 0. * *HTLC*: Hashed Time Locked Contract. - * A conditional payment between 2 peers: the recipient can spend + * A conditional payment between two peers: the recipient can spend the payment by presenting its signature and a *payment preimage*, otherwise the payer can cancel the contract by spending it after a given time. These are implemented as outputs from the diff --git a/01-messaging.md b/01-messaging.md index 8cce19d02..f3bf54b13 100644 --- a/01-messaging.md +++ b/01-messaging.md @@ -28,7 +28,7 @@ Implementations MUST use a single connection per peer — channel messages (whic After decryption, all Lightning messages are of the form: -1. `type`: 2 byte big-endian field indicating the type of message. +1. `type`: 2-byte big-endian field indicating the type of message. 2. `payload`: variable length payload which comprises the remainder of the message and conforms to the format matching the `type`. @@ -45,14 +45,14 @@ A receiving node: - upon receiving a message of _even_, unknown type: - 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 four groups, ordered by their most significant set bit: - Setup & Control (types `0`-`31`): messages related to connection setup, control, supported features, and error reporting. These are described below. - Channel (types `32`-`127`): messages used to setup and tear down micropayment channels. These are described in [BOLT #2](02-peer-protocol.md). - Commitment (types `128`-`255`): messages related to updating the current commitment transaction, which includes adding, revoking, and settling HTLCs, as well as updating fees and exchanging signatures. 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. +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. @@ -74,18 +74,18 @@ The _it's ok to be odd_ rule allows for future optional extensions without negotiation or special coding in clients. The "ignore additional data" rule similarly allows for future expansion. -Implementations may prefer to have message data aligned on an 8 byte +Implementations may prefer to have message data aligned on an 8-byte boundary (the largest natural alignment requirement of any type here); -however, adding a 6 byte padding after the type field was considered +however, 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. +a buffer with 6-bytes of pre-padding. ## Setup Messages ### The `init` Message Once authentication is complete, the first message reveals the features supported or required by this node, even if this is a reconnection. -[BOLT #9](09-features.md) specifies lists of global and local features. Each feature is generally represented in `globalfeatures` or `localfeatures` by 2 bits. The least-significant bit is numbered 0, which is _even_, and the next most significant bit is numbered 1, which is _odd_. +[BOLT #9](09-features.md) specifies lists of global and local features. Each feature is generally represented in `globalfeatures` or `localfeatures` by 2-bits. The least-significant bit is numbered 0, which is _even_, and the next most significant bit is numbered 1, which is _odd_. Both fields `globalfeatures` and `localfeatures` MUST be padded to bytes with 0s. @@ -96,7 +96,7 @@ Both fields `globalfeatures` and `localfeatures` MUST be padded to bytes with 0s * [`2`:`lflen`] * [`lflen`:`localfeatures`] -The 2 byte `gflen` and `lflen` fields indicate the number of bytes in the immediately following field. +The 2-byte `gflen` and `lflen` fields indicate the number of bytes in the immediately following field. #### Requirements @@ -122,7 +122,7 @@ Nodes wait for receipt of the other's features to simplify error diagnosis, where features are incompatible. The feature masks are split into local features (which only affect the -protocol between these 2 nodes) and global features (which can affect +protocol between these two nodes) and global features (which can affect HTLCs) and are thus also advertised to other nodes. ### The `error` Message @@ -157,8 +157,8 @@ A sending node: - 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 `channel_id` is 0: - - MUST fail all channels, - - and MUST close the connection. + - MUST fail all channels. + - MUST close the connection. - MUST set `len` equal to the length of `data`. The receiving node: @@ -167,8 +167,8 @@ 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's larger). - - if the string is composed solely of printable ASCII characters (For reference: the printable character set includes byte values 32 through 127, inclusive): - - SHOULD only print out `data` verbatim. + - if `data` is not composed solely of printable ASCII characters (For reference: the printable character set includes byte values 32 through 127, inclusive): + - SHOULD NOT print out `data` verbatim. #### Rationale @@ -208,8 +208,8 @@ included within the data payload of the `pong` message. #### Requirements A node sending a `ping` message: - - SHOULD set `ignored` to 0s, - - but MUST NOT set `ignored` to sensitive data such as secrets or portions of initialized + - SHOULD set `ignored` to 0s. + - MUST NOT set `ignored` to sensitive data such as secrets or portions of initialized memory. - if it doesn't receive a corresponding `pong`: - MAY terminate the network connection, @@ -217,16 +217,16 @@ memory. - SHOULD NOT send `ping` messages more often than once every 30 seconds. A node sending a `pong` message: - - SHOULD set `ignored` to 0s, - - but MUST NOT set `ignored` to sensitive data such as secrets or portions of initialized + - SHOULD set `ignored` to 0s. + - MUST NOT set `ignored` to sensitive data such as secrets or portions of initialized memory. A node receiving a `ping` message: - - SHOULD fail the channels if it has received significantly in excess of 1 `ping` per 30 seconds. + - 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: - MUST respond by sending a `pong` message, with `byteslen` equal to `num_pong_bytes`. - otherwise (`num_pong_bytes` is **not** less than 65532): - - it MUST ignore the `ping`. + - MUST ignore the `ping`. A node receiving a `pong` message: - if `byteslen` does not correspond to any `ping`'s `num_pong_bytes` value it has sent: diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 3c0ad1448..e0d20c25f 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -1,6 +1,6 @@ # BOLT #2: Peer Protocol for Channel Management -The peer channel protocol has 3 phases: establishment, normal +The peer channel protocol has three phases: establishment, normal operation, and closing. # Table of Contents @@ -125,8 +125,7 @@ The `funding_pubkey` is the public key in the 2-of-2 multisig script of the fund The sending node MUST: - ensure that the `chain_hash` value identifies the chain it wishes to open the channel within. - - ensure `temporary_channel_id` is unique from any other. -channel ID with the same peer. + - ensure `temporary_channel_id` is unique from any other channel ID with the same peer. - set `funding_satoshis` to less than 2^24 satoshi. - set `push_msat` to equal or less than 1000 * `funding_satoshis`. - set `funding_pubkey`, `revocation_basepoint`, `payment_basepoint`, and `delayed_payment_basepoint` to valid DER-encoded, compressed, secp256k1 pubkeys. @@ -141,8 +140,8 @@ The receiving node MUST: - ignore undefined bits in `channel_flags`. - if the connection has been re-established after receiving a previous `open_channel` but before receiving a `funding_created` message: - - accept a new `open_channel` message, - - and MUST discard the previous `open_channel` message. + - accept a new `open_channel` message. + - discard the previous `open_channel` message. The receiving node MAY fail the channel if: - `announce_channel` is `false` (`0`), yet it wishes to publicly announce the channel. @@ -210,8 +209,9 @@ avoid double-spending of the funding transaction. The receiver: - if the `chain_hash` value within the `open_channel` message is set to a hash of a chain unknown to the receiver: - - MUST reject the channel, - - and MAY reject the `minimum_depth`, if it considers it unreasonably large. + - MUST reject the channel. + - if `minimum_depth` is unreasonably large: + - MAY reject the channel. Other fields have the same requirements as their counterparts in `open_channel`. @@ -272,9 +272,9 @@ The sender MUST set: The recipient: - if `signature` is incorrect: - MUST fail the channel. + - MUST NOT broadcast the funding transaction before receipt of a valid `funding_signed`. - on receipt of a valid `funding_signed`: - - SHOULD broadcast the funding transaction, - - and MUST NOT broadcast the funding transaction earlier. + - SHOULD broadcast the funding transaction. ### The `funding_locked` Message @@ -306,9 +306,7 @@ other node after a reasonable timeout. #### Rationale The non-funder can simply forget the channel ever existed, since no -funds are at risk. There is a denial of service risk: if the fundee remembers -the channel forever (on the promise of the funding transaction finally -appearing), even if `push_msat` is significant. +funds are at risk. If the fundee were to remember the channel forever, that would create a Denial of Service risk; therefore, forgetting it is recommended (even if the promise of `push_msat` is significant). #### Future @@ -321,7 +319,7 @@ Nodes can negotiate a mutual close of the connection, which unlike a unilateral close, allows them to access their funds immediately and can be negotiated with lower fees. -Closing happens in 2 stages: 1) one side indicates it wants to clear the channel +Closing happens in two stages: 1) one side indicates it wants to clear the channel (and thus will accept no new HTLCs) 2) once all HTLCs are resolved, the final channel close negotiation begins. @@ -419,9 +417,9 @@ A sending node: The receiving node: - after `shutdown` has been received and no HTLCs remain in either commitment transaction: - SHOULD send a `closing_signed` message. - - MUST check `signature` is valid for either variant of close -transaction specified in [BOLT #3](03-transactions.md#closing-transaction), - - and MUST fail the connection if it is not. + - if the `signature` is not valid for either variant of close transaction + specified in [BOLT #3](03-transactions.md#closing-transaction): + - MUST fail the connection. - if `fee_satoshis` is equal to its previously sent `fee_satoshis`: - SHOULD sign and broadcast the final closing transaction - MAY close the connection. @@ -453,7 +451,7 @@ reason to pay a premium for rapid processing. Once both nodes have exchanged `funding_locked` (and optionally [`announcement_signatures`](https://github.com/lightningnetwork/lightning-rfc/blob/master/07-routing-gossip.md#the-announcement_signatures-message)), the channel can be used to make payments via Hash TimeLocked Contracts. -Changes are sent in batches: 1 or more `update_` messages are sent before a +Changes are sent in batches: one or more `update_` messages are sent before a `commitment_signed` message, as in the following diagram: +-------+ +-------+ @@ -485,14 +483,14 @@ Thus each update traverses through the following states: 5. ... and the sender's previous commitment transaction has been revoked -As the 2 nodes' updates are independent, the 2 commitment +As the two nodes' updates are independent, the two commitment transactions may be out of sync indefinitely. This is not concerning: what matters is whether both sides have irrevocably committed to a particular HTLC or not (the final state, above). ### Forwarding HTLCs -In general, a node offers HTLCs for 2 reasons: to initiate a payment of its own, +In general, a node offers HTLCs for two reasons: to initiate a payment of its own, or to forward another node's payment. In the forwarding case, care must be taken to ensure the *outgoing* HTLC cannot be redeemed unless the *incoming* HTLC can be redeemed. The following requirements ensure this is always true: @@ -500,7 +498,7 @@ HTLC can be redeemed. The following requirements ensure this is always true: The respective **addition/removal** of an HTLC is considered *irrevocably committed* when: 1. the commitment transaction **with/without** it is committed by both nodes, and any -previous commitment transaction which **without/with** it has been revoked, OR +previous commitment transaction **without/with** it has been revoked, OR 2. the commitment transaction **with/without** it has been irreversibly committed to the blockchain. @@ -527,7 +525,7 @@ irrevocable and the incoming HTLC should be fulfilled as soon as possible to reduce latency. An HTLC with an unreasonably long expiry is a denial-of-service vector and -therefor is not allowed. Note that the exact value of "unreasonable" is currently unclear +therefore is not allowed. Note that the exact value of "unreasonable" is currently unclear and may depend on network topology. ### `cltv_expiry_delta` Selection @@ -594,7 +592,7 @@ the longest possible time to redeem it on-chain: transaction. Thus, the worst case is `3R+2G+2S` assuming `R` is at least 1. Note that the -chances of 3 reorganizations in which the other node wins all of them is +chances of three reorganizations in which the other node wins all of them is low for `R` of 2 or more. Since high fees are used (and HTLC spends can use almost arbitrary fees), `S` should be small; although, given that block times are irregular and empty blocks still occur, `S = 2` should be considered a @@ -602,7 +600,7 @@ minimum. Similarly, the grace period `G` can be low (1 or 2), as nodes are required to timeout or fulfill as soon as possible; but if `G` is too low it increases the risk of unnecessary channel closure due to networking delays. -There are 4 values that need be derived: +There are four values that need be derived: 1. The `cltv_expiry_delta` for channels, `3R+2G+2S`: if in doubt, a `cltv_expiry_delta` of 12 is reasonable (R=2, G=1, S=2). @@ -669,7 +667,7 @@ Fees") while maintaining its channel reserve. - MUST NOT offer `amount_msat` below the receiving node's `htlc_minimum_msat` - MUST set `cltv_expiry` less than 500000000. - for channels with `chain_hash` identifying the Bitcoin blockchain: - - MUST set the 4 most significant bytes of `amount_msat` to 0. + - MUST set the four most significant bytes of `amount_msat` to 0. - if result would be offering more than the remote's `max_accepted_htlcs` HTLCs, in the remote commitment transaction: - MUST NOT add an HTLC. @@ -677,8 +675,8 @@ Fees") while maintaining its channel reserve. `max_htlc_value_in_flight_msat`: - MUST NOT add an HTLC. - for the first HTLC it offers: - - MUST set `id` to 0, - - and MUST increase the value by 1 for each successive offer. + - MUST set `id` to 0. + - MUST increase the value of `id` by 1 for each successive offer. A receiving node: - receiving an `amount_msat` equal to 0, OR less than its own `htlc_minimum_msat`: @@ -690,7 +688,7 @@ A receiving node: - SHOULD fail the channel. - if sending node sets `cltv_expiry` to greater or equal to 500000000: - SHOULD fail the channel. - - for channels with `chain_hash` identifying the Bitcoin blockchain, if the 4 most significant bytes of `amount_msat` are not 0: + - for channels with `chain_hash` identifying the Bitcoin blockchain, if the four most significant bytes of `amount_msat` are not 0: - MUST fail the channel. - MUST allow multiple HTLCs with the same `payment_hash`. - if the sender did not previously acknowledge the commitment of that HTLC: @@ -731,7 +729,7 @@ bootstrap phase of the network. ### Removing an HTLC: `update_fulfill_htlc`, `update_fail_htlc`, and `update_fail_malformed_htlc` For simplicity, a node can only remove HTLCs added by the other node. -There are 3 reasons for removing an HTLC: it has timed out, it has +There are three reasons for removing an HTLC: it has timed out, it has failed to route, or the payment preimage is supplied. The `reason` field is an opaque encrypted blob for the benefit of the @@ -767,27 +765,27 @@ For an unparsable HTLC: #### Requirements A node: - - SHOULD remove an HTLC as soon as it can. - - SHOULD fail an HTLC which has timed out. - - until the corresponding HTLC is irrevocably - committed in both sides' commitment transactions: - - MUST NOT send an `update_fulfill_htlc`, `update_fail_htlc` or + - SHOULD remove an HTLC as soon as it can. + - SHOULD fail an HTLC which has timed out. + - until the corresponding HTLC is irrevocably committed in both sides' + commitment transactions: + - MUST NOT send an `update_fulfill_htlc`, `update_fail_htlc`, or `update_fail_malformed_htlc`. A receiving node: - - MUST check that `id` corresponds to an HTLC in its current commitment transaction, - - and MUST fail the channel if it does not. - - MUST check that the `payment_preimage` value in `update_fulfill_htlc` - SHA256 hashes to the corresponding HTLC `payment_hash`, - - and MUST fail the channel if it does not. + - if the `id` does not correspond to an HTLC in its current commitment transaction: + - MUST fail the channel. + - if the `payment_preimage` value in `update_fulfill_htlc` + doesn't SHA256 hash to the corresponding HTLC `payment_hash`: + - MUST fail the channel. - if the `BADONION` bit in `failure_code` is not set for `update_fail_malformed_htlc`: - MUST fail the channel. - - MAY check the `sha256_of_onion` in `update_fail_malformed_htlc`, - - and if it does not match the onion it sent: - - MAY retry or choose an alternate error response. - - otherwise, a receiving node which has an outgoing HTLC canceled by `update_fail_malformed_htlc`: - - MUST return an error in the `update_fail_htlc` sent to the link which + - if the `sha256_of_onion` in `update_fail_malformed_htlc` doesn't match the + onion it sent: + - MAY retry or choose an alternate error response. + - otherwise, a receiving node which has an outgoing HTLC canceled by `update_fail_malformed_htlc`: + - MUST return an error in the `update_fail_htlc` sent to the link which originally sent the HTLC, using the `failure_code` given and setting the data to `sha256_of_onion`. @@ -796,7 +794,7 @@ A receiving node: A node that doesn't time out HTLCs risks channel failure (see [`cltv_expiry_delta` Selection](#cltv_expiry_delta-selection)). -A node which sends `update_fulfill_htlc`, before the sender, is also +A node that sends `update_fulfill_htlc`, before the sender, is also committed to the HTLC and risks losing funds. If the onion is malformed, the upstream node won't be able to extract @@ -827,13 +825,13 @@ sign the resulting transaction (as defined in [BOLT #3](03-transactions.md)), an A sending node: - MUST NOT send a `commitment_signed` message which does not include any updates. - - but MAY send a `commitment_signed` message which only -alters the fee, - - and MAY send a `commitment_signed` message which doesn't + - MAY send a `commitment_signed` message which only +alters the fee. + - MAY send a `commitment_signed` message which doesn't change the commitment transaction aside from the new revocation hash (due to dust, identical HTLC replacement, or insignificant or multiple fee changes). - - MUST include 1 `htlc_signature` for every HTLC transaction corresponding + - MUST include one `htlc_signature` for every HTLC transaction corresponding to BIP69 lexicographic ordering of the commitment transaction. A receiving node: @@ -882,8 +880,8 @@ A sending node: transaction. A receiving node: - - MUST check that `per_commitment_secret` generates the previous `per_commitment_point`, - - and MUST fail the channel if it does not. + - if `per_commitment_secret` does not generate the previous `per_commitment_point`: + - MUST fail the channel. - if the `per_commitment_secret` was not generated by the protocol in [BOLT #3](03-transactions.md#per-commitment-secret-requirements): - MAY fail the channel. @@ -1011,8 +1009,8 @@ A node: - SHOULD retransmit the error packet and ignore any other packets for that channel. - otherwise: - - MUST transmit `channel_reestablish` for each channel, - - and MUST wait for to receive the other node's `channel_reestablish` + - MUST transmit `channel_reestablish` for each channel. + - MUST wait for to receive the other node's `channel_reestablish` message before sending any other messages for that channel. The sending node: @@ -1053,10 +1051,10 @@ A node: fields are present: - if `next_remote_revocation_number` is greater than expected above, AND `your_last_per_commitment_secret` is correct for that - `next_remote_revocation_number` minus one: - - MUST NOT broadcast its commitment transaction, - - and SHOULD fail the channel, - - and SHOULD store `my_current_per_commitment_point` to retrieve funds + `next_remote_revocation_number` minus 1: + - MUST NOT broadcast its commitment transaction. + - SHOULD fail the channel. + - SHOULD store `my_current_per_commitment_point` to retrieve funds should the sending node broadcast its commitment transaction onchain. - otherwise (`your_last_per_commitment_secret` or `my_current_per_commitment_point` do not match the expected values):