Merge pull request #267 from toadlyBroodle/master

Copy Edit and Requirements Restructuring

.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

.copy-edit-stylesheet-checklist.md

@@ -0,0 +1,52 @@
+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
+    - consistent paragraph tense (e.g. past, present, future)
+    - passive voice (e.g. avoid 'we')
+      - exception: `Introduction` section
+  - 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
+    - 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 sub-items
+      - period at branch ends
+      - example:
+      ```
+      A sending node:
+          - MAY do this.
+          - if this, AND this:
+            - SHOULD do this.
+          - otherwise:
+            - MUST do this,
+              - but MUST NOT...in this case.
+      ```
+  - links
+    - broken links
+    - link text
+    - correct anchors/urls
+  - references
+    - format e.g. <sup>[1](#reference-1)</sup>
+  - tags
+    - consistent usage, e.g. [TODO:], [FIXME:]

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
+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,45 +25,44 @@ This is version 0.
 
 ## Glossary and Terminology Guide
 
-* *Funding Transaction*:
+* *Funding transaction*:
-   * The on-chain, irreversible transaction which pays to both peers
+   * The on-chain, irreversible transaction that pays to both peers on a channel.
-         on a channel.  Thus it can only be spent by mutual consent.
+   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*.
-         transaction*.
 
 
-* *Commitment Transaction*:
+* *Commitment transaction*:
-   * A transaction which spends the funding transaction; each peer
+   * A transaction which spends the funding transaction.
-         holds a signature from the other peer for this transaction, so it
+   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
+   always has a commitment transaction it can spend. After a new
-         commitment transaction is negotiated, the old one is *revoked*.
+   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*,
+    the payment by presenting its signature and a *payment preimage*,
-         otherwise the payer can cancel the contract by spending it after
+    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*.
+    *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
+    payment preimage. Only the final recipient knows the payment
-         preimage; thus when it reveals the preimage to collect funds is
+    preimage. In order to release funds, the final recipient releases
-         considered proof that it received the payment.
+    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
+    value which allows the other peer to spend all outputs
-         immediately: revealing this key is how old commitment
+    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.
+    commitment revocation pubkey.
 
 
 * *Per-commitment secret*:
@@ -72,36 +71,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
+    spend of the *funding transaction* with an output to each peer
-         (unless one output is too small, and thus is not included).
+    (unless one output is too small, and thus is not included).
 
 
-* *Unilateral Close*:
+* *Unilateral close*:
-   * An uncooperative close of a channel, by broadcasting a
+   * An uncooperative close of a channel, through broadcasting of a
-         *commitment transaction*.  This transaction is larger (ie. less
+    *commitment transaction*. This transaction is larger (i.e. less
-         efficient) than a mutual close transaction, and the peer whose
+    efficient) than a mutual close transaction, and the peer whose
-         commitment is broadcast cannot access its own outputs for some
+    commitment is broadcast cannot access its own outputs for some
-         previously-negotiated duration.
+    previously-negotiated duration.
 
 
-* *Revoked Transaction Close*:
+* *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 transaction*. Since the other peer knows the
-         *commitment revocation secret key*, it can create a *penalty transaction*.
+    *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
+    if the other peer tries to "cheat" by broadcasting a revoked
-         *commitment transaction*.
+    *commitment transaction*.
 
 
-* *Commitment Number*:
+* *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.
+    are independent for each peer in the channel and start at 0.
 
 
 * *It's ok to be odd*:
@@ -112,11 +111,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
+     `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):
@@ -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 <aj@erisian.com.au>
 
-
 ## Authors
 
-
 [ FIXME: Insert Author List ]
 
-
 ![Creative Commons License](https://i.creativecommons.org/l/by/4.0/88x31.png "License CC-BY")
 <br>
 This work is licensed under a [Creative Commons Attribution 4.0 International License](http://creativecommons.org/licenses/by/4.0/).

01-messaging.md

@@ -4,53 +4,62 @@
 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.<sup>[1](#reference-1)</sup>
+The default TCP port is 9735. This corresponds to hexadecimal `0x2607`: the Unicode code point for LIGHTNING.<sup>[1](#reference-1)</sup>
 
 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 `init` Message](#the-init-message)
-    * [The `error` message](#the-error-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 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 the message.
+1. `type`: 2-byte big-endian field indicating the type of message.
-2. `payload`: variable length payload. It comprises the remainder of
+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:
+A sending node:
+  - MUST NOT send an evenly-typed message not listed here, without prior negotiation.
 
- - Setup & Control (types `0`-`31`): messages related to connection setup, control, supported features, and error reporting. These are described below.
+A receiving node:
- - Channel (types `32`-`127`): comprises messages used to setup and tear down micropayment channels. These are described in [BOLT #2](02-peer-protocol.md).
+  - upon receiving a message of _odd_, unknown type:
- - 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).
+    - MUST ignore the received message.
- - 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).
+  - upon receiving a message of _even_, unknown type:
+    - MUST fail the channels.
 
-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 messages are grouped logically into four groups, ordered by their most significant set bit:
-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.
+  - Setup & Control (types `0`-`31`): messages related to connection setup, control, supported features, and error reporting. These are described below.
-A node which understands an option (each is numbered) MUST include all the fields annotated with that option.
+  - 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 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.
+  - that understands an option (each is numbered):
+    - MUST include all the fields annotated with that option.
 
 ### Rationale
 
@@ -61,24 +70,24 @@ 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
+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),
+boundary (the largest natural alignment requirement of any type here);
-but 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
+### 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.
+Both fields `globalfeatures` and `localfeatures` MUST be padded to bytes with 0s.
 
 1. type: 16 (`init`)
 2. data:
@@ -87,41 +96,38 @@ Both fields `globalfeatures` and `localfeatures` MUST be padded to bytes with ze
    * [`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
 
-Each node MUST send `init` as the first lightning message for any
+The sending node:
-connection.
+  - MUST send `init` as the first Lightning message for any connection.
-The sending node SHOULD use the minimum lengths required to represent
+  - MUST set feature bits as defined in [BOLT #9](09-features.md).
-the feature fields.  
+  - MUST set any undefined feature bits to 0.
+  - 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 receiving node:
-and MUST set to zero any feature bits that are not defined.
+  - MUST wait to receive `init` before sending any other messages.
-
+  - MUST respond to known feature bits as specified in [BOLT #9](09-features.md).
-The receiver MUST respond to known feature bits as specified in
+  - upon receiving _odd_ feature bits which are non-zero:
-[BOLT #9](09-features.md).  For unknown feature bits which are
+    - MUST ignore the bit.
-non-zero, the receiver MUST ignore the bit if the bit number is odd,
+  - upon receiving _even_ feature bits which are non-zero:
-and MUST fail the connection if the bit number is even.
+    - MUST fail the connection.
-
-Each node MUST wait to receive `init` before sending any other messages.
 
 #### Rationale
 
-This semantic allows future incompatible changes, or backward
+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.
-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
+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 two nodes) and global features (which can affect
-HTLCs and thus are also advertised to other nodes.
+HTLCs) and are thus 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.
+For simplicity of diagnosis, it's often useful to tell a peer that something is incorrect.
 
 1. type: 17 (`error`)
 2. data:
@@ -133,53 +139,66 @@ 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 0 (i.e. all bytes are 0), 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`.
 
-A node SHOULD send `error` for protocol violations or internal
+The fundee node:
-errors which make channels unusable or further communication unusable.
+  - for all error messages sent before (and not including) the `funding_signed` message:
-A node MAY send an empty `data` field.  A node sending `error` MUST
+    - MUST use `temporary_channel_id` in lieu of `channel_id`.
-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 receiving `error` MUST fail the channel referred to by the message,
+A sending node:
-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
+  - when sending `error`:
-`len` to the remainder of the packet if it is larger.
+    - 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 0:
+    - MUST fail all channels.
+    - MUST close the connection.
+  - MUST 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.
+The receiving node:
-For reference, the printable character set includes byte values 32 through 127 inclusive.
+  - 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 `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
 
 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
+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
 
-### 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,43 +207,51 @@ included within the data payload of the `pong` message
 
 #### Requirements
 
-A node sending `pong` or `ping` SHOULD set `ignored` to zeroes, but MUST NOT
+A node sending a `ping` message:
-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,
+      - and MUST NOT fail the channels in this case.
+  - 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,
+A node sending a `pong` message:
-and MAY terminate the network connection if it does not receive a corresponding
+  - SHOULD set `ignored` to 0s.
-`pong`: it MUST NOT fail the channels in this case.
+  - 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
+A node receiving a `ping` message:
-significantly in excess of one `ping` per 30 seconds, otherwise if
+  - SHOULD fail the channels if it has received significantly in excess of one `ping` per 30 seconds.
-`num_pong_bytes` is less than 65532 it 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`.
+    - MUST respond by sending a `pong` message, with `byteslen` equal to `num_pong_bytes`.
+  - otherwise (`num_pong_bytes` is **not** less than 65532):
+    - MUST ignore the `ping`.
 
-A node receiving a `pong` message MAY fail the channels if `byteslen` does not
+A node receiving a `pong` message:
-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 maximum sensible `byteslen`
+The largest possible message is 65535 bytes; thus, the maximum sensible `byteslen`
-is 65531 to account for the type field (`pong`) and `byteslen` itself.  This
+is 65531 — in order to account for the type field (`pong`) and the `byteslen` itself. This allows
-gives us a convenient cutoff for `num_pong_bytes` to indicate that no reply
+a convenient cutoff for `num_pong_bytes` to indicate that no reply should be sent.
-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
+significant portion of the lifetime of a connection, no new data will be
-exchanged. Additionally, on several platforms it's possible that Lightning
+exchanged. Also, 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. Hence, a
-distinct ping message in order to probe for the liveness of the connection on
+distinct `ping` message is used, 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
+against packet and timing analysis — as nodes can fake the traffic patterns of
 typical exchanges, without applying any true updates to their respective
-channels. 
+channels.
 
 When combined with the onion routing protocol defined in
 [BOLT #4](https://github.com/lightningnetwork/lightning-rfc/blob/master/04-onion-routing.md),
@@ -232,25 +259,23 @@ 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
+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
 rotations as specified within [BOLT #8](https://github.com/lightningnetwork/lightning-rfc/blob/master/08-transport.md).
 
-
 ## Acknowledgments
 
-TODO(roasbeef); fin
+[ TODO: (roasbeef); fin ]
-
 
 ## References
 1. <a id="reference-2">http://www.unicode.org/charts/PDF/U2600.pdf</a>
 
 ## Authors
 
-FIXME
+[ FIXME: Insert Author List ]
 
 ![Creative Commons License](https://i.creativecommons.org/l/by/4.0/88x31.png "License CC-BY")
 <br>