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
-describe a layer-2 protocol for off-chain bitcoin transfer by mutual
+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,45 +25,44 @@ 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
-         transaction*.
+   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 is negotiated, the old one is *revoked*.
+* *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*.
 
 
 * *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; 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
-         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*:
@@ -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
-         (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, by broadcasting a
-         *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.
+* *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.
 
 
-* *Revoked Transaction Close*:
-   * An invalid close of the channel, by broadcasting a revoked
-         *commitment transaction*.  Since the other peer knows the
-         *commitment revocation secret key*, it can create a *penalty transaction*.
+* *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*.
 
 
-* *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*; they
-         are independent for each peer in the channel, and start at 0.
+* *Commitment number*:
+   * A 48-bit incrementing counter for each *commitment transaction*; counters
+    are independent for each peer in the channel and start at 0.
 
 
 * *It's ok to be odd*:
@@ -112,19 +111,18 @@ 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.
+     `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
      (encoded in hex):
      `6fe28c0ab6f1b372c1a6a246ae63f74f931e8365e15a089c68d6190000000000`.
 
 ## 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/).