BOLT-2 Edit

Some slightly larger scale revisions for BOLT-2, notably including a reorganization of the "open_channel" function with the introduction of two missing arguments.

Also, the addition of MSAT to the glossary in BOLT-0.

00-introduction.md

@@ -32,6 +32,8 @@ This is version 0.
 * *Peers*:
    * *Nodes* wanting to transact Bitcoins with each other through a *channel*.
 
+* *MSAT*:
+   * A millisatoshi, often used as a field name.
 
 * *Funding transaction*:
    * An irreversible on-chain transaction that pays to both *peers* on a *channel*.

02-peer-protocol.md

@@ -49,7 +49,7 @@ 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
-which will be used to construct channel authentication proofs.
+that will be used to construct channel authentication proofs.
 
 
         +-------+                              +-------+
@@ -71,13 +71,14 @@ 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 is created) or a `channel_id` (derived from the
 funding transaction).
 
 ### The `open_channel` Message
 
 This message contains information about a node and indicates its
-desire to set up a new channel.
+desire to set up a new channel. This is the first step toward creating
+the funding transaction and both versions of the commitment transaction.
 
 1. type: 32 (`open_channel`)
 2. data:
@@ -102,25 +103,63 @@ desire to set up a new channel.
    * [`2`:`shutdown_len`] (`option_upfront_shutdown_script`)
    * [`shutdown_len`: `shutdown_scriptpubkey`] (`option_upfront_shutdown_script`)
 
-The `chain_hash` value denotes the exact blockchain the opened channel will
+
+The `chain_hash` value denotes the exact blockchain that 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 channels
 across many distinct blockchains as well as have channels within multiple
 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; 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.
+The `temporary_channel_id` is used to identify this channel until the
+funding transaction is established. 
 
-`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.
+`funding_satoshis` is the amount the sender is putting into the
+channel. `push_msat` is an amount of initial funds that the sender is
+unconditionally giving to the receiver. `dust_limit_satoshis` is the
+threshold below which outputs should not be generated for this node's
+commitment or HTLC transactions (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. `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 (i.e. 1/4 the more normally-used 'fee rate 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 node's 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.
+`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. 
+
+`feerate_per_kw` indicates the initial fee rate by 1000-weight
+(i.e. 1/4 the more normally-used 'fee rate per kilobyte') that 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 node's 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.
+
+`funding_pubkey` is the public key in the 2-of-2 multisig script of
+the funding transaction output.
+
+The various `_basepoint` fields are used to [derive unique
+keys](03-transactions.md#key-derivation) for each commitment
+transaction. Varying these keys ensures that the transaction ID of
+each commitment transaction is unpredictable to 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.
+
+`first_per_commitment_point` is the per-commitment point to be used
+for the first commitment transaction,
 
 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
-funding flow wishes to advertise this channel publicly to the network,
+the funding flow wishes to advertise this channel publicly to the
-as detailed within
+network, as detailed within [BOLT
-[BOLT #7](https://github.com/lightningnetwork/lightning-rfc/blob/master/07-routing-gossip.md#bolt-7-p2p-node-and-channel-discovery).
+#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`, `htlc_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.
 
 The `shutdown_scriptpubkey` allows the sending node to commit to where
 funds will go on mutual close, which the remote node should enforce
@@ -139,9 +178,9 @@ The sending node:
   - MUST set `first_per_commitment_point` to the per-commitment point to be used for the initial commitment transaction, derived as specified in [BOLT #3](03-transactions.md#per-commitment-secret-requirements).
   - MUST set undefined bits in `channel_flags` to 0.
   - if both nodes advertised the `option_upfront_shutdown_script` feature:
-	- MUST include either a valid `shutdown_scriptpubkey` as required by `shutdown` `scriptpubkey`, or a zero-length `shutdown_scriptpubkey`.
+  - MUST include either a valid `shutdown_scriptpubkey` as required by `shutdown` `scriptpubkey`, or a zero-length `shutdown_scriptpubkey`.
   - otherwise:
-	- MAY include a`shutdown_scriptpubkey`.
+  - MAY include a`shutdown_scriptpubkey`.
 
 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.
@@ -177,9 +216,9 @@ The receiving node MUST NOT:
 
 #### 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 there is always progress toward meeting this reserve, 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 not 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` — 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 (with a danger of double-spend until that occurs) and may require a separate method to prove payment via on-chain confirmation.
 
 The `feerate_per_kw` is generally only of concern to the sender (who pays the fees), but there is also the fee rate paid by HTLC transactions; thus, unreasonably large fee rates can also penalize the recipient.
 
@@ -194,7 +233,8 @@ protocol.
 ### The `accept_channel` Message
 
 This message contains information about a node and indicates its
-acceptance of the new channel.
+acceptance of the new channel. This is the second step toward creating the
+funding transaction and both versions of the commitment transaction.
 
 1. type: 33 (`accept_channel`)
 2. data:
@@ -237,7 +277,7 @@ Other fields have the same requirements as their counterparts in `open_channel`.
 
 This message describes the outpoint which the funder has created for
 the initial commitment transactions. After receiving the peer's
-signature, it will broadcast the funding transaction.
+signature via `funding_signed`, it will broadcast the funding transaction.
 
 1. type: 34 (`funding_created`)
 2. data:
@@ -252,7 +292,7 @@ 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,
     - and MUST NOT broadcast this transaction.
-  - `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).
+  - `funding_output_index` to the output number of that transaction that 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:
@@ -272,7 +312,7 @@ A transaction with all Segregated Witness inputs is not malleable, hence the fun
 ### The `funding_signed` Message
 
 This message gives the funder the signature it needs for the first
-commitment transaction, so it can broadcast the signature knowing funds
+commitment transaction, so it can broadcast the signature knowing that 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 2 bytes).
@@ -410,8 +450,8 @@ propagate to miners.
 The `option_upfront_shutdown_script` feature means that the node
 wanted to pre-commit to `shutdown_scriptpubkey` in case it was
 compromised somehow.  This is a weak commitment (a malevolent
-implementation tends to ignore specifications like this one!) but
+implementation tends to ignore specifications like this one!), but it
-provides an incremental improvement in security by requiring cooperation
+provides an incremental improvement in security by requiring the cooperation
 of the receiving node to change the `scriptpubkey`.
 
 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.
@@ -509,9 +549,10 @@ Thus each update traverses through the following states:
 2. In the receiver's latest commitment transaction,
 3. ... and the receiver's previous commitment transaction has been revoked,
    and the HTLC is pending on the sender.
-4. ... and in the sender's latest commitment transaction.
+4. ... and in the sender's latest commitment transaction,
 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:
 what matters is whether both sides have irrevocably committed to a
@@ -633,19 +674,20 @@ 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 sent HTLCs: the timeout deadline after which the channel has to be failed
+2. The `cltv_expiry_delta` 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 received HTLCs (with a preimage): the fulfillment deadline after which
+3. The `cltv_expiry_delta` 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` accepted for terminal payments: this
+4. The minimum `cltv_expiry` accepted for terminal payments: the
-   is the same calculation as above.  The default in
+   worst case for the terminal node C is `2R+G+S` blocks (as, again, steps
+   1-3 above don't apply). The default in
    [BOLT #11](11-payment-encoding.md) is 9, which is slightly more
-   conservative than the 7 this calculation suggests.
+   conservative than the 7 that this calculation suggests.
 
 #### Requirements
 
@@ -756,14 +798,10 @@ 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 four reasons for removing an HTLC: the payment preimage is supplied,
-failed to route, or the payment preimage is supplied.
+it has timed out, it has failed to route, or it is malformed.
 
-The `reason` field is an opaque encrypted blob for the benefit of the
+To supply the preimage:
-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`)
 2. data:
@@ -780,6 +818,12 @@ For a timed out or route-failed HTLC:
    * [`2`:`len`]
    * [`len`:`reason`]
 
+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);
+however, there's a special malformed failure variant for the case where
+our peer couldn't parse it: in this case the current node instead take action, encrypting
+it into a `update_fail_htlc` for relaying.
+
 For an unparsable HTLC:
 
 1. type: 135 (`update_fail_malformed_htlc`)
@@ -825,10 +869,10 @@ 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
-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
+The node can check that the SHA256 that the upstream is complaining about
 does match the onion it sent, which may allow it to detect random bit
 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
@@ -850,11 +894,11 @@ sign the resulting transaction (as defined in [BOLT #3](03-transactions.md)), an
 #### Requirements
 
 A sending node:
-  - MUST NOT send a `commitment_signed` message which does not include any
+  - MUST NOT send a `commitment_signed` message that does not include any
 updates.
-  - MAY send a `commitment_signed` message which only
+  - MAY send a `commitment_signed` message that only
 alters the fee.
-  - MAY send a `commitment_signed` message which doesn't
+  - MAY send a `commitment_signed` message that doesn't
 change the commitment transaction aside from the new revocation hash
 (due to dust, identical HTLC replacement, or insignificant or multiple
 fee changes).
@@ -988,10 +1032,10 @@ 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 during normal
+and close, where messages have an explicit order, but during normal
-operation acknowledgments of updates are delayed until the
+operation, acknowledgments of updates are delayed until the
 `commitment_signed` / `revoke_and_ack` exchange; so it cannot be assumed
-the updates have been received. This also means that the receiving
+that 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
@@ -1133,7 +1177,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 retransmittal 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.
@@ -1166,7 +1210,7 @@ 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. This will, at least, allow the fallen-behind node to recovery
+transaction to the chain. This will, at least, allow the fallen-behind node to recover
 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