BOLT 7: first pass copy edit to line 120

07-routing-gossip.md

@@ -4,19 +4,19 @@ This specification describes simple node discovery, channel discovery, and chann
 
 Node and channel discovery serve two different purposes:
 
- - Channel discovery allows the creation and maintenance of a local view of the network's topology, so that the node can discover routes to the desired destination.
+ - Channel discovery allows the creation and maintenance of a local view of the network's topology, so that a node can discover routes to desired destinations.
- - Node discovery allows nodes to broadcast their ID, host, and port, so that other nodes can open connections and establish payment channels.
+ - Node discovery allows nodes to broadcast their ID, host, and port, so that other nodes can open connections and establish payment channels with them.
 
 To support channel discovery, peers in the network exchange
-`channel_announcement` messages, which contain information about new
+`channel_announcement` messages containing information regarding new
-channels between two nodes. They can also exchange `channel_update`
+channels between the two nodes. They can also exchange `channel_update`
 messages, which update information about a channel. There can only be
 one valid `channel_announcement` for any channel, but at least two
 `channel_update` messages are expected.
 
 To support node discovery, peers exchange `node_announcement`
-messages, which supply additional information about nodes. There can be
+messages, which supply additional information about the nodes. There may be
-multiple `node_announcement` messages, to update node information.
+multiple `node_announcement` messages, in order to update the node information.
 
 # Table of Contents
 
@@ -33,8 +33,8 @@ multiple `node_announcement` messages, to update node information.
 
 ## The `announcement_signatures` Message
 
-This is a direct message between two endpoints of a channel and serves as an opt-in mechanism to allow the announcement of the channel to the rest of the network.
+This is a direct message between the two endpoints of a channel and serves as an opt-in mechanism to allow the announcement of the channel to the rest of the network.
-It contains the necessary signatures by the sender to construct the `channel_announcement` message.
+It contains the necessary signatures, by the sender, to construct the `channel_announcement` message.
 
 1. type: 259 (`announcement_signatures`)
 2. data:
@@ -47,52 +47,59 @@ The willingness of the initiating node to announce the channel is signaled durin
 
 ### Requirements
 
-The `announcement_signatures` message is created by constructing a `channel_announcement` message, corresponding to the newly established channel, and signing it with the secrets matching an endpoint's `node_id` and `bitcoin_key`. The message is then sent using an `announcement_signatures`.
+The `announcement_signatures` message is created by constructing a `channel_announcement` message, corresponding to the newly established channel, and signing it with the secrets matching an endpoint's `node_id` and `bitcoin_key`. The message is then sent using an `announcement_signatures` message.
 
 The `short_channel_id` is the unique description of the funding transaction.
-It is constructed with the most significant 3 bytes indicating the block
+It is constructed as follows:
-height, the next 3 bytes indicating the transaction index within the
+  1. the most significant 3 bytes: indicating the block height
-block, and the least significant two bytes indicating the output
+  2. the next 3 bytes: indicating the transaction index within the block
-index that pays to the channel.
+  3. the least significant 2 bytes: indicating the output index that pays to the channel.
 
-If the `open_channel` message had the `announce_channel` bit set, then both nodes MUST send the `announcement_signatures` message, otherwise they MUST NOT.
+A node:
+  - if the `open_channel` message has the `announce_channel` bit set:
+    - MUST send the `announcement_signatures` message.
+      - MUST NOT send `announcement_signatures` messages until `funding_locked`
+      has been sent AND the funding transaction has at least six confirmations.
+  - otherwise:
+    - MUST NOT send the `announcement_signatures` message.
+  - upon reconnection:
+    - MUST respond to the first `announcement_signatures` message with its own
+    `announcement_signatures` message.
+    - if it has NOT received an `announcement_signatures` message:
+      - SHOULD retransmit the `announcement_signatures` message.
 
-If sent, `announcement_signatures` messages MUST NOT be sent until `funding_locked` has been sent and the funding transaction has at least six confirmations.
+A recipient node:
-
+  - if the `node_signature` OR the `bitcoin_signature` is NOT correct:
-The recipient MAY fail the channel if the `node_signature` or `bitcoin_signature` is incorrect.
+    - MAY fail the channel.
-The recipient SHOULD queue the `channel_announcement` message for its peers if it has sent and received a valid `announcement_signatures` message.
+  - if it has sent AND received a valid `announcement_signatures` message:
-
+    - SHOULD queue the `channel_announcement` message for its peers.
-On reconnection, a node SHOULD retransmit the `announcement_signatures` message if it has not received an `announcement_signatures` message, and MUST respond to the first `announcement_signatures` message after reconnection with its own `announcement_signatures` message.
 
 ## The `channel_announcement` Message
 
-This message contains ownership information about a channel. It ties
+This message contains ownership information regarding a channel. It ties
-each on-chain Bitcoin key to the Lightning node key, and vice-versa.
+each on-chain Bitcoin key to the associated Lightning node key, and vice-versa.
-The channel is not really usable until at least one side has announced
+The channel is not practically usable until at least one side has announced
-its fee levels and expiry using `channel_update`.
+its fee levels and expiry, using `channel_update`.
 
-Proving the existence of a channel between `node_1` and
+Proving the existence of a channel between `node_1` and `node_2` requires:
-`node_2` requires:
 
 1. proving that the funding transaction pays to `bitcoin_key_1` and
    `bitcoin_key_2`
 2. proving that `node_1` owns `bitcoin_key_1`
 3. proving that `node_2` owns `bitcoin_key_2`
 
-The first proof is accomplished by assuming that all nodes know the unspent
+Assuming that all nodes know the unspent transaction outputs, the first proof is
-transaction outputs, and thus can find the output given by
+accomplished by a node finding the output given by the `short_channel_id` and
-`short_channel_id` and validate that it is indeed a P2WSH funding
+verifying that it is indeed a P2WSH funding transaction output for those keys
-transaction output for those keys specified in
+specified in [BOLT #3](03-transactions.md#funding-transaction-output).
-[BOLT #3](03-transactions.md#funding-transaction-output).
 
-The second two proofs are accomplished through explicit signatures (`bitcoin_signature_1`
+The last two proofs are accomplished through explicit signatures:
-and `bitcoin_signature_2`, generated by each `bitcoin_key` and signing
+`bitcoin_signature_1` and `bitcoin_signature_2` are generated for each
-the corresponding `node_id`).
+`bitcoin_key` and each of the corresponding `node_id`s are signed.
 
-It is also necessary to prove that `node_1` and `node_2` both agree on this
+It's also necessary to prove that `node_1` and `node_2` both agree on the
-announcement message; this is accomplished by having a signature from each
+announcement message: this is accomplished by having a signature from each
-`node_id` signing the message (`node_signature_1` and
+`node_id` (`node_signature_1` and `node_signature_2`) signing the message.
-`node_signature_2`).
 
 1. type: 256 (`channel_announcement`)
 2. data: